bigquery-agent-analytics 0.5.2__tar.gz → 0.5.3__tar.gz

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
       - name: Run autoformat and check for changes
         run: |
           bash autoformat.sh
-          if ! git diff --exit-code src/ tests/ examples/ scripts/; then
+          if ! git diff --exit-code src/ tests/ examples/ scripts/ dashboards/; then
             echo ""
             echo "::error::Code is not formatted. Run 'bash autoformat.sh' and commit the changes."
             exit 1
@@ -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

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/.github/workflows/grafana-sync-check.yml

@@ -18,13 +18,13 @@ on:
   push:
     branches: [main]
     paths:
-      - "grafana/**"
+      - "dashboards/grafana/**"
       - "scripts/check_grafana_queries_sync.py"
       - ".github/workflows/grafana-sync-check.yml"
   pull_request:
     branches: [main]
     paths:
-      - "grafana/**"
+      - "dashboards/grafana/**"
       - "scripts/check_grafana_queries_sync.py"
       - ".github/workflows/grafana-sync-check.yml"
 

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

@@ -0,0 +1,76 @@
+# 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
+
+      - name: Verify minimum Streamlit floor dependency
+        run: |
+          pip install "streamlit==1.63.0"
+          pytest --tb=short -q tests/test_dashboards_streamlit_apptest.py

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/.gitignore

@@ -37,6 +37,10 @@ deploy/streaming_evaluation/.streaming_evaluation_state.json
 ._*
 grafana/datasource.yaml
 grafana/.local/
+dashboards/grafana/datasource.yaml
+dashboards/grafana/.local/
 
 # Service-account credentials (never commit downloaded JSON keys).
 grafana/*.json
+dashboards/grafana/*.json
+dashboards/streamlit/*.json

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/CHANGELOG.md

@@ -7,6 +7,137 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-09-20
+
+### Release highlights
+
+A small patch release. In the wheel: reads against a missing events table
+now fail with `EventsTableNotFoundError`, a `NotFound` subclass that names
+the table, the location and the `Client()` arguments to check (#485); the
+extractor-compilation smoke gate measures its memory budget above the SDK's
+own import footprint instead of failing before the candidate loads (#480);
+new `streamlit` / `dashboards` extras install what the Streamlit dashboard
+needs (#480); and `ViewManager` gains an empty-but-tested cross-event view
+registry so ADK 2.0 analytical views can deploy beside per-event views
+(#210). Around the wheel: a Streamlit agent-analytics dashboard joins
+Grafana under a consolidated `dashboards/` directory (#480, #481), the
+scheduled skill-evolution job gains a per-analyst timeout (#483), the
+README onboarding path is corrected (#484, #485), an OKF Attested
+Computation receipt spike lands under `examples/` (#479), and three demos
+decouple the agent `MODEL_NAME` from a separate `JUDGE_MODEL` for SDK-side
+grading (#471). No public API is removed or renamed.
+
+### Added
+
+- **Cross-event view deployment path on `ViewManager` (#210 / #489)** — a
+  second registry, `_CROSS_EVENT_VIEW_DEFS`, sits next to `_EVENT_VIEW_DEFS`
+  for analytical views that span several event types. `create_all_views()`
+  and `bq-agent-sdk views create-all` deploy per-event views and then
+  cross-event views in one invocation; `create_view()` / `get_view_sql()`
+  / `views create` accept a key from either registry. The registry ships
+  empty (the ADK 2.0 consumer views register into it as they land), so
+  the deployed set and per-event SQL are unchanged.
+
+- **`streamlit` and `dashboards` extras (#480)** —
+  `pip install 'bigquery-agent-analytics[streamlit]'` pulls the Streamlit
+  dashboard's dependencies (`streamlit>=1.63.0`, `plotly>=6.0.0`,
+  `db-dtypes`, `pandas`, `python-dotenv`); `dashboards` is an alias for it,
+  and the `all` extra now includes `dashboards`. The dashboard code itself
+  lives in the repo, not the wheel (see *Dashboards* below).
+
+### Changed
+
+- **Package quick-start docstring (#484)** — the `bigquery_agent_analytics`
+  module docstring now lists a trace with
+  `client.list_traces(TraceFilter(limit=1))` instead of assuming a known
+  trace id, and calls `client.insights()` with its default of 50 sessions
+  (pass `config=InsightsConfig(max_sessions=...)` to change it). README
+  Quick Start updated to match.
+
+### Fixed
+
+- **README onboarding and `EventsTableNotFoundError` (#485)** — the
+  Prerequisites link to the retired `contributing/extensions` exporter
+  (404) is replaced by a "How this fits together" block naming both
+  producers (the ADK plugin and the LangChain/LangGraph callback) and this
+  SDK as the consumer; the Quick Start passes `table_id="agent_events"`
+  and `location="US"` explicitly instead of assuming the defaults. Reads
+  in `get_trace()` and `list_traces()` that hit a missing table now raise
+  `EventsTableNotFoundError` (a `NotFound` subclass, exported at the
+  package top level) naming the fully qualified table and the location and
+  saying which constructor arguments to check, and the schema-verification
+  warning names the table, the exception type and the same fix, so the
+  swallowed warning is no longer the only signal.
+- **Extractor smoke-gate memory cap counts the candidate, not the SDK
+  (#480)** — `run_smoke_test_in_subprocess(memory_limit_mb=...)` applied
+  `RLIMIT_AS` as an absolute ceiling before the child imported the trusted
+  SDK harness, so in environments where `google-cloud-bigquery` pulls in
+  pandas / pyarrow / numpy the import baseline alone could exhaust the
+  budget and fail the gate with `MemoryError` before the candidate
+  extractor loaded. The child now imports the harness first and applies
+  `memory_limit_mb` as headroom above its current address space (read from
+  `/proc/self/statm` on Linux, where `RLIMIT_AS` is enforced); when the
+  baseline cannot be read it falls back to the previous absolute cap.
+
+### Dashboards (repo side, not in the wheel)
+
+- **Streamlit agent analytics dashboard (#480)** — `dashboards/streamlit/`
+  is a Python-native alternative to the Grafana dashboard, backed by the
+  same typed views and filter semantics, with scan-cap guardrails and query
+  caching. Install with the `streamlit` extra and configure through
+  `dashboards/streamlit/.env`. `scripts/check_streamlit_queries_sync.py`
+  guards its queries against drift.
+- **Grafana moves under `dashboards/` (#481)** — `grafana/` is now
+  `dashboards/grafana/` (dashboard JSON, queries and `run_local.py`), and
+  `scripts/check_grafana_queries_sync.py` follows it. Update any local
+  scripts or bookmarks that pointed at the old top-level path.
+
+### Deploy (repo side, not in the wheel)
+
+- **`ANALYST_TIMEOUT_S` for the scheduled skill-evolution job** — the job
+  now binds the engine's per-analyst timeout (default `600` seconds, `0`
+  disables it) and passes it to `evolve_skill`, so one hung analyst —
+  typically a host `error_analyst` hook stuck on its own tool calls —
+  hands its slot to the next queued analyst instead of stalling the
+  fleet into the Cloud Run task timeout. A malformed or negative value
+  fails the run rather than silently reverting to the default.
+- **The skill-evolution job stops feature-detecting its engine** — the
+  image bakes `scripts/` from the checkout `deploy.sh` runs in, so the
+  engine always carries the #395 host hooks. `engine.supported_kwargs` /
+  `engine.evolve_skill_compat` and the secondary `error_analyst` gate in
+  `evolve.py` are gone (callers use the engine's `evolve_skill`
+  directly), and `deploy.sh --scripts-dir`, which existed to bake a
+  different branch's engine, is removed. Host hooks still degrade
+  gracefully: no `error_analyst` hook means single-pass analysts, no
+  `score` hook means size-based candidate selection.
+
+### Examples
+
+- **Judge model decoupled from agent `MODEL_NAME` (#471 / #488)** —
+  `examples/e2e_demo.py`, `examples/context_graph_adcp_demo.ipynb`, and
+  `examples/nba_agent_trace_analysis_notebook.ipynb` now take a separate
+  env-overridable `JUDGE_MODEL` for all SDK-side LLM usage (`Client`
+  endpoint, `ContextGraphConfig` endpoint, `LLMAsJudge` model,
+  `PerformanceEvaluator` `llm_judge_model`) while `LlmAgent(model=MODEL_NAME)`
+  is unchanged. Startup output prints both roles. `examples/README.md`
+  documents that the judge is independent of the agent by default and names
+  the silent SDK fallback (`gemini-2.5-flash`).
+
+- **OKF result-bound receipt spike (#479)** —
+  `examples/okf_attested_computation/`: one OKF v0.2 §10 Attested
+  Computation is approved by a trusted broker, executed under the caller's
+  own BigQuery delegation, and independently verified by a separate code
+  path before a deterministic consumer releases the number. Spike,
+  example-only, synthetic fixture; not a production receipt service. The
+  #474 observer (`examples/okf_bqaa_adapter`) is untouched.
+
+### Documentation
+
+- **README onboarding (#484, #485)** — the Prerequisites section gains a
+  "How this fits together" block naming both producers and this SDK as the
+  consumer, and the Quick Start passes `table_id` and `location`
+  explicitly; see the *Fixed* entry above for the matching error.
+
 ## [0.5.2] - 2026-09-05
 
 ### Release highlights

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bigquery-agent-analytics
-Version: 0.5.2
+Version: 0.5.3
 Summary: SDK for analyzing and evaluating agent traces stored in BigQuery.
 Author: Google LLC
 License-Expression: Apache-2.0
@@ -23,20 +23,29 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: all
 Requires-Dist: bigframes>=1.0.0; extra == 'all'
+Requires-Dist: db-dtypes>=1.3.0; extra == 'all'
 Requires-Dist: google-cloud-aiplatform>=1.148.0; extra == 'all'
 Requires-Dist: google-genai>=1.0.0; extra == 'all'
 Requires-Dist: isort>=5.0; extra == 'all'
 Requires-Dist: jsonschema>=4.0; extra == 'all'
 Requires-Dist: langsmith>=0.10.0; extra == 'all'
 Requires-Dist: pandas>=2.0.0; extra == 'all'
+Requires-Dist: plotly>=6.0.0; extra == 'all'
 Requires-Dist: pyink>=24.3.0; extra == 'all'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'all'
 Requires-Dist: pytest>=7.0; extra == 'all'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
 Requires-Dist: rdflib>=7.0; extra == 'all'
+Requires-Dist: streamlit>=1.63.0; extra == 'all'
 Provides-Extra: bigframes
 Requires-Dist: bigframes>=1.0.0; extra == 'bigframes'
 Provides-Extra: cli
+Provides-Extra: dashboards
+Requires-Dist: db-dtypes>=1.3.0; extra == 'dashboards'
+Requires-Dist: pandas>=2.0.0; extra == 'dashboards'
+Requires-Dist: plotly>=6.0.0; extra == 'dashboards'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dashboards'
+Requires-Dist: streamlit>=1.63.0; extra == 'dashboards'
 Provides-Extra: dev
 Requires-Dist: isort>=5.0; extra == 'dev'
 Requires-Dist: jsonschema>=4.0; extra == 'dev'
@@ -54,6 +63,12 @@ Provides-Extra: llm
 Requires-Dist: google-genai>=1.0.0; extra == 'llm'
 Provides-Extra: owl
 Requires-Dist: rdflib>=7.0; extra == 'owl'
+Provides-Extra: streamlit
+Requires-Dist: db-dtypes>=1.3.0; extra == 'streamlit'
+Requires-Dist: pandas>=2.0.0; extra == 'streamlit'
+Requires-Dist: plotly>=6.0.0; extra == 'streamlit'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'streamlit'
+Requires-Dist: streamlit>=1.63.0; extra == 'streamlit'
 Description-Content-Type: text/markdown
 
 # BigQuery Agent Analytics SDK
@@ -118,12 +133,23 @@ regressions — all through BigQuery SQL or Python.
   pipeline is required. See [docs/sdk_usage_tracking.md](docs/sdk_usage_tracking.md)
   for the label schema and ready-to-run tracking queries.
 
+## How this fits together
+
+Two kinds of components share one `agent_events` table:
+
+- **Producers write it.** The ADK
+  [`BigQueryAgentAnalyticsPlugin`](https://adk.dev/observability/bigquery-agent-analytics/)
+  and the LangChain / LangGraph
+  [`BigQueryCallbackHandler`](https://docs.langchain.com/oss/python/integrations/callbacks/google_bigquery)
+  emit the same schema and can write to the same table side by side.
+- **This SDK consumes it.** Everything here is read-only over that table:
+  trace reconstruction, evaluation, insights, the context graph.
+
 ## Prerequisites
 
 - Python 3.10+
 - A Google Cloud project with BigQuery enabled
-- Agent traces stored in BigQuery via the
-  [ADK BigQuery Trace Exporter](https://github.com/google/adk-python/tree/main/contributing/extensions/bigquery_trace_exporter)
+- Agent traces already written to BigQuery by one of the producers above
 
 ## Installation
 
@@ -152,13 +178,26 @@ pip install bigquery-agent-analytics[langsmith]
 ## Quick Start
 
 ```python
-from bigquery_agent_analytics import Client
+from bigquery_agent_analytics import Client, TraceFilter
 
-client = Client(project_id="my-project", dataset_id="analytics")
-trace = client.get_trace("trace-abc-123")
-trace.render()
+client = Client(
+  project_id="my-project",
+  dataset_id="analytics",
+  table_id="agent_events",  # the table your producer writes (this is the default)
+  location="US",  # your dataset's location; omit to use the BigQuery client default
+)
+
+traces = client.list_traces(TraceFilter(limit=1))
+if traces:
+  traces[0].render()
+else:
+  print("No traces found. Check that agent events have been ingested.")
 ```
 
+If the table or location does not match what your producer wrote, reads raise
+`EventsTableNotFoundError`, whose message names both and says what to pass. It
+is a `google.api_core.exceptions.NotFound`, so existing handlers still catch it.
+
 ### Export traces to LangSmith
 
 Export the standard ADK `agent_events` schema with Application Default

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/README.md

@@ -60,12 +60,23 @@ regressions — all through BigQuery SQL or Python.
   pipeline is required. See [docs/sdk_usage_tracking.md](docs/sdk_usage_tracking.md)
   for the label schema and ready-to-run tracking queries.
 
+## How this fits together
+
+Two kinds of components share one `agent_events` table:
+
+- **Producers write it.** The ADK
+  [`BigQueryAgentAnalyticsPlugin`](https://adk.dev/observability/bigquery-agent-analytics/)
+  and the LangChain / LangGraph
+  [`BigQueryCallbackHandler`](https://docs.langchain.com/oss/python/integrations/callbacks/google_bigquery)
+  emit the same schema and can write to the same table side by side.
+- **This SDK consumes it.** Everything here is read-only over that table:
+  trace reconstruction, evaluation, insights, the context graph.
+
 ## Prerequisites
 
 - Python 3.10+
 - A Google Cloud project with BigQuery enabled
-- Agent traces stored in BigQuery via the
-  [ADK BigQuery Trace Exporter](https://github.com/google/adk-python/tree/main/contributing/extensions/bigquery_trace_exporter)
+- Agent traces already written to BigQuery by one of the producers above
 
 ## Installation
 
@@ -94,13 +105,26 @@ pip install bigquery-agent-analytics[langsmith]
 ## Quick Start
 
 ```python
-from bigquery_agent_analytics import Client
+from bigquery_agent_analytics import Client, TraceFilter
 
-client = Client(project_id="my-project", dataset_id="analytics")
-trace = client.get_trace("trace-abc-123")
-trace.render()
+client = Client(
+  project_id="my-project",
+  dataset_id="analytics",
+  table_id="agent_events",  # the table your producer writes (this is the default)
+  location="US",  # your dataset's location; omit to use the BigQuery client default
+)
+
+traces = client.list_traces(TraceFilter(limit=1))
+if traces:
+  traces[0].render()
+else:
+  print("No traces found. Check that agent events have been ingested.")
 ```
 
+If the table or location does not match what your producer wrote, reads raise
+`EventsTableNotFoundError`, whose message names both and says what to pass. It
+is a `google.api_core.exceptions.NotFound`, so existing handlers still catch it.
+
 ### Export traces to LangSmith
 
 Export the standard ADK `agent_events` schema with Application Default

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/SDK.md

@@ -1374,7 +1374,7 @@ print(ALL_KNOWN_EVENT_TYPES)
 
 ## 15. BigQuery View Management
 
-`ViewManager` creates per-event-type BigQuery views that unnest the generic `agent_events` table into typed columns. Each view retains standard identity headers (`timestamp`, `agent`, `session_id`, etc.).
+`ViewManager` creates per-event-type BigQuery views that unnest the generic `agent_events` table into typed columns. Each view retains standard identity headers (`timestamp`, `agent`, `session_id`, etc.). It also deploys [cross-event views](#cross-event-views) that span several event types.
 
 ```python
 from bigquery_agent_analytics import ViewManager
@@ -1385,7 +1385,7 @@ vm = ViewManager(
     table_id="agent_events",
 )
 
-# Create all per-event-type views at once
+# Create all per-event-type and cross-event views at once
 vm.create_all_views()
 
 # Or create a single view
@@ -1414,6 +1414,68 @@ tool completions they are **null**. `pause_orphan` is reserved for the pause
 registry and stays null until that ships — treat a null `pause_orphan` as
 "not yet determined", not as "not an orphan".
 
+#### Cross-event views
+
+Some analytical views span several event types — pairing a `TOOL_PAUSED` with
+its resuming `TOOL_COMPLETED`, or chaining `AGENT_TRANSFER` rows — so they do
+not fit the per-event shape of "standard headers plus typed columns, filtered
+to one `event_type`". `ViewManager` deploys them from a second registry,
+`_CROSS_EVENT_VIEW_DEFS`, next to the per-event `_EVENT_VIEW_DEFS`. There is
+still one manager and one deployment path:
+
+```python
+# Per-event-type views first, then cross-event views, in one call.
+created = vm.create_all_views()
+# {"LLM_REQUEST": "adk_llm_requests", ..., "<cross_event_key>": "adk_<suffix>"}
+
+vm.available_cross_event_views          # keys in the cross-event registry
+vm.create_view("<cross_event_key>")     # single view, same method
+print(vm.get_view_sql("<cross_event_key>"))
+```
+
+```bash
+# Same combined set, one invocation.
+bq-agent-sdk views create-all --project-id=my-project --dataset-id=analytics
+
+# A single view — event type or cross-event key.
+bq-agent-sdk views create <cross_event_key> \
+  --project-id=my-project --dataset-id=analytics
+```
+
+The cross-event registry ships **empty**: this is the deployment plumbing, and
+the ADK 2.0 consumer views (`workflow_invocations`, `agent_transfer_chains`,
+`branch_fanout`, `long_running_tool_durations`, `compaction_windows`,
+`scope_cardinality`) register into it as they land. Until then
+`create_all_views()` and `views create-all` deploy exactly the per-event set,
+with unchanged SQL.
+
+A registry entry maps a view key to `(view_suffix, query_sql)`. `query_sql` is
+the full `SELECT` body, rendered with `str.format` (double any literal braces)
+with `{project}`, `{dataset}`, `{table}` (the events table) and
+`{view_prefix}`, so a cross-event view can read either the events table or a
+per-event view such as `` `{project}.{dataset}.{view_prefix}tool_starts` ``.
+Deployment rules:
+
+- Per-event views are created first, then cross-event views in registry order.
+  A cross-event view that reads another must be registered after it.
+- Keys must not collide with event types and suffixes must be unique across
+  both registries; `create_all_views()` raises `ValueError` before issuing any
+  query otherwise.
+- A view that fails to create is logged and left out of the returned dict; the
+  remaining views still deploy (same as per-event views).
+
+**Design decision — extend `ViewManager` rather than add an
+`AnalyticsViewManager`.** The tradeoff was consistency versus separation. A
+sibling manager would keep the per-event class narrowly scoped, but every
+caller that wants "all the views" — `create_all_views()`, `views create-all`,
+setup scripts — would then have to know about and invoke two managers, and the
+two could drift in prefixing, client/telemetry labelling and error handling.
+Cross-event views also depend on the per-event views' names and prefix, which a
+single manager already owns, so deployment order is enforced in one place.
+Extending `ViewManager` keeps one constructor, one `create_all_views()` and one
+CLI path; the separation that matters — the two view *shapes* — is preserved by
+keeping two registries with two SQL builders.
+
 ---
 
 ## 16. Categorical Evaluation & Real-Time Dashboards

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/autoformat.sh

@@ -21,9 +21,9 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")" && pwd)"
 
 echo "==> Running isort (import sorting)..."
-isort "${REPO_ROOT}/src/" "${REPO_ROOT}/tests/" "${REPO_ROOT}/examples/" "${REPO_ROOT}/scripts/"
+isort "${REPO_ROOT}/src/" "${REPO_ROOT}/tests/" "${REPO_ROOT}/examples/" "${REPO_ROOT}/scripts/" "${REPO_ROOT}/dashboards/"
 
 echo "==> Running pyink (code formatting)..."
-pyink --config "${REPO_ROOT}/pyproject.toml" "${REPO_ROOT}/src/" "${REPO_ROOT}/tests/" "${REPO_ROOT}/examples/" "${REPO_ROOT}/scripts/"
+pyink --config "${REPO_ROOT}/pyproject.toml" "${REPO_ROOT}/src/" "${REPO_ROOT}/tests/" "${REPO_ROOT}/examples/" "${REPO_ROOT}/scripts/" "${REPO_ROOT}/dashboards/"
 
 echo "==> Done. All Python files formatted."

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/dashboard/looker_studio/README.md

@@ -171,7 +171,7 @@ from a signed-in, non-owner, out-of-domain account (anonymous HTTP cannot
 observe either). While the template is unavailable, the
 `tools/hydrate_dashboard.py` preflight below still validates the table — but
 its creation URL copies the same template, so it is not an outage workaround;
-the [Grafana dashboard](../../grafana/) and the Looker Agent Analytics block
+the [Grafana dashboard](../../dashboards/grafana/) and the Looker Agent Analytics block
 (below) remain available.
 
 Looker Studio report parameters are intentionally not used for these values:

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/dashboard/looker_studio/USER_MANUAL.md

@@ -232,7 +232,7 @@ configurator produces.
 | What you see | What's happening and what to do |
 |---|---|
 | The new tab shows loading, not-found, or an error page right after clicking **Create my dashboard** | Google is still provisioning your report copy — this resolves within about 10 seconds. Don't close the tab. If it's still broken after a minute, close it and click the button again. (Exception: the "This report isn't shared with you" dialog below never resolves by waiting or retrying.) |
-| The new tab shows **"This report isn't shared with you"** with *Reload* / *Return to report list* / *Go to report template* buttons | The shared dashboard *template* is unavailable to the Google account signed in to that tab — nothing is wrong with your project, dataset, table, access, or the identifiers you entered; they haven't been consulted yet. First check the tab is using the account you intend (Looker Studio uses the browser's default Google account — switch accounts or use a profile signed in to only the right one, then click **Create my dashboard** again). If you're on a work or school account, your own organization's sharing policy can also block receiving Looker Studio assets from outside domains — try a personal account if you can. If the dialog still persists, the template's copy path is blocked: report it on [issue #445](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/445) — say only whether your signed-in account is personal or part of an organization; do not post the account's email address. While it's blocked, the [compatibility check](#check-compatibility-before-creating-optional-needs-a-terminal) still validates your table (it is not a workaround — its URL copies the same template), and the repository's [Grafana dashboard](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/grafana) works independently of Looker Studio. |
+| The new tab shows **"This report isn't shared with you"** with *Reload* / *Return to report list* / *Go to report template* buttons | The shared dashboard *template* is unavailable to the Google account signed in to that tab — nothing is wrong with your project, dataset, table, access, or the identifiers you entered; they haven't been consulted yet. First check the tab is using the account you intend (Looker Studio uses the browser's default Google account — switch accounts or use a profile signed in to only the right one, then click **Create my dashboard** again). If you're on a work or school account, your own organization's sharing policy can also block receiving Looker Studio assets from outside domains — try a personal account if you can. If the dialog still persists, the template's copy path is blocked: report it on [issue #445](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/445) — say only whether your signed-in account is personal or part of an organization; do not post the account's email address. While it's blocked, the [compatibility check](#check-compatibility-before-creating-optional-needs-a-terminal) still validates your table (it is not a workaround — its URL copies the same template), and the repository's [Grafana dashboard](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/dashboards/grafana) works independently of Looker Studio. |
 | Charts blank or trickling in after opening a page | Normal on a cold load — allow up to 90 seconds. If a chart is still empty after that, widen the date range: your table may have no events in the selected window. |
 | Layout looks cut off on the left | Collapse the Looker Studio navigation drawer, and make the window at least 1280 px wide. Phones and narrow tablets aren't supported. |
 | Bottom charts clipped on Token Consumption or Latency | You're on a copy created before 2026-07-29, which keeps the old page geometry. Create a fresh copy from the configurator. |

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3}/dashboard/looker_studio/docs/index.html

@@ -189,7 +189,7 @@
         validate your table, but it copies the same template, so it is not
         a workaround;
         while the template is blocked, use the
-        <a href="https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/grafana">
+        <a href="https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/dashboards/grafana">
           Grafana dashboard</a>.
       </aside>
 

bigquery_agent_analytics-0.5.3/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)                   |

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3/dashboards}/grafana/README.md

@@ -2,7 +2,7 @@
 
 Visualize BQAA telemetry straight from BigQuery in Grafana.
 Works on the free tier of Grafana Cloud. It runs alongside the
-[`dashboard_v2/`](../dashboard_v2) React app rather than replacing it — both
+[`dashboard_v2/`](../../dashboard_v2) React app rather than replacing it — both
 read the same data.
 
 ```
@@ -26,7 +26,7 @@ AI Agent app ──SDK──▶ BigQuery agent_events ──ViewManager──▶
 On macOS or Linux with `gcloud auth application-default login` already run:
 
 ```bash
-python3 grafana/run_local.py --project YOUR_PROJECT --dataset YOUR_DATASET
+python3 dashboards/grafana/run_local.py --project YOUR_PROJECT --dataset YOUR_DATASET
 ```
 
 That downloads a pinned Grafana (cached and checksum-verified after the
@@ -41,7 +41,7 @@ work by default — the job location is selected automatically; pass
 `--processing-location EU` (or a region) to pin it. `--sa-key key.json`
 switches to the JWT auth documented below and writes the credential file
 with `0600` permissions; `--stop` tears it down; everything generated lives
-in the disposable, gitignored `grafana/.local/`. Production setups should
+in the disposable, gitignored `dashboards/grafana/.local/`. Production setups should
 still follow the full steps below with a scoped service account.
 
 > **Known pitfalls if you run Grafana your own way instead:**
@@ -77,7 +77,7 @@ still follow the full steps below with a scoped service account.
 3. **Keys → Add Key → Create new key → JSON**, and download it.
 
 > **Keep the key out of the repo.** `.gitignore` only covers new `*.json`
-> files inside `grafana/`. A key saved anywhere else can be committed by
+> files inside `dashboards/grafana/`. A key saved anywhere else can be committed by
 > accident.
 
 ### 3. Prepare the data
@@ -138,7 +138,7 @@ form with literal `\n` escapes.
 
 ```bash
 # Docker
-cp grafana/datasource.example.yaml grafana/datasource.yaml
+cp dashboards/grafana/datasource.example.yaml dashboards/grafana/datasource.yaml
 docker run -d -p 3000:3000 \
   -e "GF_INSTALL_PLUGINS=grafana-bigquery-datasource" \
   -v /path/to/your/datasource.yaml:/etc/grafana/provisioning/datasources/datasource.yaml \
@@ -267,7 +267,7 @@ every panel's SQL:
 sed -e 's/YOUR_PROJECT_ID/my-gcp-project/g' \
     -e 's/YOUR_DATASET_ID/my_demo_dataset/g' \
     -e 's/agent_events/my_demo_table/g' \
-    grafana/bqaa-public-demo.json > grafana/bqaa-public-demo.ready.json
+    dashboards/grafana/bqaa-public-demo.json > dashboards/grafana/bqaa-public-demo.ready.json
 ```
 
 The third substitution only matters if your events table is not named

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3/dashboards}/grafana/datasource.example.yaml

@@ -3,7 +3,7 @@
 # OPTIONAL — only for self-managed Grafana (Docker, k8s, bare metal).
 # On Grafana Cloud, add the data source through the UI instead
 # (Connections -> Data sources -> Add data source -> "Google BigQuery");
-# see grafana/README.md.
+# see dashboards/grafana/README.md.
 #
 # Usage (self-managed):
 #   1. Install the plugin:  grafana-cli plugins install grafana-bigquery-datasource

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.3/dashboards}/grafana/queries/README.md

@@ -1,7 +1,7 @@
 # Grafana Panel Queries: Source of Truth
 
 The `.sql` files in this directory are the **canonical source of truth** for
-every panel and query template variable in `grafana/bqaa-dashboard.json`.
+every panel and query template variable in `dashboards/grafana/bqaa-dashboard.json`.
 The dashboard JSON embeds a copy of each query (Grafana has no "include SQL
 from file" mechanism), so: