feat(dashboards): add Streamlit agent analytics dashboard

.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install package with dev dependencies
-        run: pip install -e ".[dev]"
+        run: pip install -e ".[dev,streamlit]"
 
       - name: Run tests
         run: pytest --tb=short -q

.github/workflows/streamlit-sync-check.yml

@@ -0,0 +1,71 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Streamlit query sync check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "dashboards/grafana/queries/**"
+      - "dashboards/streamlit/**"
+      - "scripts/check_streamlit_queries_sync.py"
+      - "tests/test_dashboards_streamlit_app.py"
+      - "tests/test_check_streamlit_queries_sync.py"
+      - "tests/test_dashboards_streamlit_charts.py"
+      - "tests/test_dashboards_streamlit_apptest.py"
+      - "pyproject.toml"
+      - ".github/workflows/streamlit-sync-check.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "dashboards/grafana/queries/**"
+      - "dashboards/streamlit/**"
+      - "scripts/check_streamlit_queries_sync.py"
+      - "tests/test_dashboards_streamlit_app.py"
+      - "tests/test_check_streamlit_queries_sync.py"
+      - "tests/test_dashboards_streamlit_charts.py"
+      - "tests/test_dashboards_streamlit_apptest.py"
+      - "pyproject.toml"
+      - ".github/workflows/streamlit-sync-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  streamlit-query-sync:
+    name: Dashboard queries and contracts match SQL sources
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package with dev and streamlit dependencies
+        run: pip install -e ".[dev,streamlit]"
+
+      - name: Validate Streamlit queries match canonical Grafana SQL
+        run: python3 scripts/check_streamlit_queries_sync.py
+
+      - name: Run Streamlit dashboard contract tests
+        run: |
+          pytest --tb=short -q \
+            tests/test_dashboards_streamlit_app.py \
+            tests/test_check_streamlit_queries_sync.py \
+            tests/test_dashboards_streamlit_charts.py \
+            tests/test_dashboards_streamlit_apptest.py

.gitignore

@@ -43,3 +43,4 @@ dashboards/grafana/.local/
 # Service-account credentials (never commit downloaded JSON keys).
 grafana/*.json
 dashboards/grafana/*.json
+dashboards/streamlit/*.json

dashboards/README.md

@@ -0,0 +1,12 @@
+# Self-Hosted Dashboards
+
+Self-hosted observability and analytics dashboards for BigQuery Agent Analytics (BQAA).
+
+## Available Dashboards
+
+| Dashboard                   | Primary Use Case                                                                            | Documentation                                               |
+| :-------------------------- | :------------------------------------------------------------------------------------------ | :---------------------------------------------------------- |
+| **Streamlit**               | Interactive Python-native telemetry inspection, latency distributions, token analytics      | [Streamlit Guide](streamlit/README.md)                      |
+| **Grafana**                 | Time-series metrics, customizable SQL panels, public demo sharing, one-command local runner | [Grafana Guide](grafana/README.md)                       |
+| **Looker Studio**           | Published 37-chart template over BQAA views, zero-install, team-wide reporting              | [Looker Studio Guide](../dashboard/looker_studio/README.md) |
+| **Demo Streamlit (Legacy)** | Original standalone demo app and Colab tutorial for raw ADK table logs                      | [Legacy Demo App](../dashboard/README.md)                   |

dashboards/streamlit/.env.sample

@@ -0,0 +1,14 @@
+# Path to Google Cloud service account JSON key file
+GOOGLE_APPLICATION_CREDENTIALS=dashboards/streamlit/sa-key.json # Remove or comment out to use user credentials (ADC)
+
+# Google Cloud project ID
+BQ_PROJECT_ID=my-gcp-project
+
+# BigQuery dataset ID
+BQ_DATASET_ID=agent_analytics
+
+# BigQuery table ID storing raw agent telemetry events
+BQ_TABLE_ID=agent_events #default
+
+# Prefix applied to typed analytical views
+BQ_VIEW_PREFIX=adk_ #default

dashboards/streamlit/README.md

@@ -0,0 +1,78 @@
+# Streamlit Dashboard for BigQuery Agent Analytics
+
+Interactive dashboard for monitoring, diagnosing, and evaluating AI agent traces in Google BigQuery.
+
+---
+
+## 1. Install
+
+Install dependencies with the `dashboards` extra:
+
+```bash
+pip install '.[streamlit]'
+```
+
+---
+
+## 2. Configure
+
+Copy the sample environment file and configure your parameters:
+
+```bash
+cp dashboards/streamlit/.env.sample dashboards/streamlit/.env
+```
+
+Parameters configured in `dashboards/streamlit/.env`:
+
+| Variable                         | Description                              | Default                            |
+| :------------------------------- | :--------------------------------------- | :--------------------------------- |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON key file    | `dashboards/streamlit/sa-key.json` |
+| `BQ_PROJECT_ID`                  | Google Cloud project ID                  | `my-gcp-project`                   |
+| `BQ_DATASET_ID`                  | BigQuery dataset containing agent events | `agent_analytics`                  |
+| `BQ_TABLE_ID`                    | Raw agent events table                   | `agent_events`                     |
+| `BQ_VIEW_PREFIX`                 | Prefix for typed analytical views        | `adk_`                             |
+
+---
+
+## 3. Prerequisites & Typed Views
+
+The dashboard queries typed analytical views (`adk_llm_responses`, `adk_tool_starts`, etc.) created over the raw events table.
+
+### IAM Roles
+
+Ensure the query identity (service account or `gcloud auth application-default login`) has:
+* **`roles/bigquery.jobUser`** on the Google Cloud project to run query jobs.
+* **`roles/bigquery.dataViewer`** on the dataset to read tables and views.
+
+### Create Views
+
+Generate the typed analytical views matching your project, dataset, and events table:
+
+```bash
+bq-agent-sdk views create-all \
+  --project-id YOUR_PROJECT \
+  --dataset-id YOUR_DATASET \
+  --table-id YOUR_TABLE
+```
+
+> **Note:** Views default to the `adk_` prefix. If you specify a custom prefix with `--prefix`, set `BQ_VIEW_PREFIX` in `.env` (or in the dashboard sidebar) to match.
+
+---
+
+## 4. Run
+
+Launch the Streamlit dashboard:
+
+```bash
+streamlit run dashboards/streamlit/app.py
+```
+
+---
+
+## 5. Sidebar Controls
+
+The sidebar provides runtime controls and guardrails for query execution:
+
+* **Time range selector**: Snaps query execution to discrete sliding windows (e.g., Last 15 minutes, Last 24 hours, Last 7 days, Last 30 days) with bucketed intervals.
+* **Per-query scan cap guardrail (`maximum_bytes_billed`)**: Sets a strict byte limit on every BigQuery job. A free dry-run preflight validates query scan size before execution, preventing queries from running if they exceed the selected cap rather than billing for unexpected costs.
+* **Token pricing defaults**: Configures input and output token rates for estimated cost calculations (defaults to \$1.25 / 1M input tokens and \$5.00 / 1M output tokens). Note that costs are derived from token counts rather than recorded billing telemetry.