bigquery-agent-analytics 0.6.0__tar.gz → 0.6.1__tar.gz

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/.github/workflows/external-access-staleness.yml

@@ -73,10 +73,10 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           MESSAGE: ${{ needs.check.outputs.message }}
         run: |
-          title="External access attestation overdue (report_template.yaml)"
+          title="External access attestation overdue"
           body="$MESSAGE
 
-          Protocol: dashboard/looker_studio/bindings/report_template.yaml -> external_access_verification. Context: #445."
+          Protocol: dashboard/looker_studio/bindings/report_template.yaml (#445) and dashboard/looker_studio/bindings/bqca_report_template.yaml (#515) -> external_access_verification."
           existing=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open \
             --search "\"$title\" in:title" --json number --jq '.[0].number // empty')
           if [ -n "$existing" ]; then

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/.github/workflows/looker-studio-pages.yml

@@ -33,6 +33,7 @@ concurrency:
 
 jobs:
   deploy:
+    if: github.ref == 'refs/heads/main'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

bigquery_agent_analytics-0.6.1/.github/workflows/mutation-testing.yml

@@ -0,0 +1,73 @@
+# 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.
+
+# Report-only mutation testing (scripts/mutation_testing.py, see
+# docs/mutation_testing.md). Weekly and on demand only: it never runs on pull
+# requests and is not a required check. Surviving mutants are published to the
+# job summary and the mutation-report artifact; they never fail the run, and
+# neither does a mutmut failure (continue-on-error). No cloud credentials: the
+# selected tests mock BigQuery.
+
+name: Mutation testing (report-only)
+
+on:
+  schedule:
+    - cron: "30 7 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mutation-testing-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  mutation:
+    name: Mutation report (non-gating)
+    runs-on: ubuntu-22.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package, test and mutation dependencies
+        run: pip install -e ".[dev]" -r scripts/requirements-mutation.txt
+
+      - name: Run mutation testing (report-only)
+        continue-on-error: true
+        run: python scripts/mutation_testing.py --time-budget-minutes 20
+
+      - name: Publish the report to the job summary
+        if: always()
+        run: |
+          report=build/mutation/report/mutation_report.md
+          if [ -f "$report" ]; then
+            cat "$report" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No mutation report was written; see the step log." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        if: always()
+        with:
+          name: mutation-report
+          path: build/mutation/report/
+          if-no-files-found: warn
+          retention-days: 30

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/.github/workflows/streamlit-sync-check.yml

@@ -21,10 +21,8 @@ on:
       - "dashboards/grafana/queries/**"
       - "dashboards/streamlit/**"
       - "scripts/check_streamlit_queries_sync.py"
-      - "tests/test_dashboards_streamlit_app.py"
+      - "tests/test_dashboards_streamlit.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:
@@ -33,10 +31,8 @@ on:
       - "dashboards/grafana/queries/**"
       - "dashboards/streamlit/**"
       - "scripts/check_streamlit_queries_sync.py"
-      - "tests/test_dashboards_streamlit_app.py"
+      - "tests/test_dashboards_streamlit.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"
 
@@ -65,12 +61,10 @@ jobs:
       - 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
+            tests/test_dashboards_streamlit.py \
+            tests/test_check_streamlit_queries_sync.py
 
       - name: Verify minimum Streamlit floor dependency
         run: |
           pip install "streamlit==1.63.0"
-          pytest --tb=short -q tests/test_dashboards_streamlit_apptest.py
+          pytest --tb=short -q tests/test_dashboards_streamlit.py

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/CHANGELOG.md

@@ -7,6 +7,252 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-10-20
+
+### Release highlights
+
+A patch release. In the wheel: `Client.drift_detection()` and
+`bq-agent-sdk drift` refuse a golden table that is not one table name,
+which closes an identifier injection through the BigQuery remote
+function's `drift` operation (#516); the `evaluate` and `evalbench-score`
+`--exit-code` gates escape the outside text they print, so session IDs,
+judge replies and stored values cannot run CI workflow commands (#527);
+contextual categorical rows no longer persist an unrecognized category,
+which can echo the trusted judge context (#529); and unreferenced
+helpers, dead stores and unused private parameters are removed (#523,
+#533). Behavior changes only for the values these fixes refuse, escape or
+drop (see Security and Fixed). No exported or documented name is added,
+removed or renamed, and the wheel's dependencies are unchanged. Around
+the wheel: BigQuery Conversational Analytics (BQCA) Prompt & Response
+Logging dashboards land for Looker Studio and the self-hosted Streamlit
+dashboard (#515), with the Looker Studio template moved to a copy that
+has public link sharing turned on (#520) and a BQCA troubleshooting row
+in its manual (#521); the `agent_improvement_cycle` example grades with
+the SDK's canonical rubrics (#534), and the self-evolving demo reads its
+project from the environment before asking for credentials (#525);
+SDK.md and the ontology and evaluation docs are corrected against the
+code (#518, #526, #528); and CI gains a weekly, report-only
+mutation-testing workflow, alongside new and consolidated tests and a
+`dashboard_v2` lock bump (#517, #519, #522, #524, #532, #536).
+
+### Security
+
+- **Drift golden tables must be one table name (#516)** —
+  `compute_drift()` formats the golden table into the query's quoted
+  `project.dataset.table` path, so a backtick in it ended the path. The
+  BigQuery remote function's `drift` operation passes its `golden_dataset`
+  param straight through, so a caller could append a `UNION` over any
+  table the function's service account can read (the rows came back in
+  `uncovered_questions`) or a second statement. `compute_drift()`, and
+  with it `Client.drift_detection()` and `drift_detection_async()`, now
+  raises `ValueError` before any query runs unless the value is one
+  BigQuery table name: Unicode letters, marks and numbers, connectors
+  such as `_`, dashes and spaces. A backtick, dot, backslash, line break,
+  empty value or non-string is refused; `bq-agent-sdk drift` prints the
+  error and exits 2, and the remote function returns a per-row `_error`
+  with code `ValueError` once it is redeployed from this release. Pass a
+  bare table name in the client's dataset: the client's project and
+  dataset are always prefixed, and the SDK.md example now does this
+  (`golden_dataset="qa_pairs_v3"`).
+- **The `--exit-code` gates escape outside text in CI logs (#527)** —
+  `bq-agent-sdk evaluate` and `evalbench-score` print session IDs (which
+  an ADK API client can choose), LLM-judge feedback, judge-chosen metric
+  names and errors that quote stored values. The GitHub Actions runner
+  runs a log line as a workflow command when it starts with `::name::`
+  after leading spaces or contains `##[name]` anywhere, and `\n`, `\r`
+  and `\r\n` all end a line, so a session ID with a line break, or judge
+  text with a `##[` marker, could run commands such as `add-mask` or
+  `stop-commands`. The new private module
+  `bigquery_agent_analytics._ci_log` escapes that text: a backslash (and,
+  in the quoted `feedback="..."` field, a double quote) gets a backslash,
+  a non-printable character becomes its Python escape (`\n`, `\x1b`), the
+  `[` after `##` becomes `\x5b`, and the first `:` of a leading `::`
+  becomes `\x3a`. This covers the FAIL lines' session ID, `metric=` and
+  feedback snippet; the gates' `Error:` line, which now stays on one
+  line; `EvaluationReport.summary()` metric names; and the `LLMAsJudge`
+  "LLM judge failed" and `Client` "Evaluation failed for session"
+  warnings. The report, in every `--format`, writes `##[` as `##\u005b`,
+  which JSON and Python string literals decode back to `[`, so JSON
+  output still decodes to the same values. Ordinary IDs, feedback and
+  metric names print as before, and scores keep the raw text.
+
+### Fixed
+
+- **Contextual categorical rows persist only validated categories
+  (#529)** — with `Client.evaluate_categorical(per_session_context=...)`
+  and `CategoricalEvaluationConfig(persist_results=True)`,
+  `flatten_results_to_rows()` already wrote `justification` and
+  `raw_response` as `NULL` on contextual rows but passed `category`
+  through. `parse_classifications()` keeps an unrecognized category
+  verbatim (`passed_validation=False`, `parse_error=True`), so when the
+  `AI.GENERATE` retries could not repair a row, or on the API fallback, a
+  model that answered with the judge context as its category had that
+  text written to the results table, although the docs say the context is
+  never persisted. A contextual row now keeps `category` only when it
+  matched one of the metric's categories; otherwise it is written as
+  `NULL`, and `parse_error` stays set. Those rows now count under a `NULL`
+  category in `categorical_daily_counts` and `categorical_hourly_counts`;
+  `categorical_operational_metrics`, the returned
+  `CategoricalEvaluationReport` and rows without context are unchanged.
+  SDK.md lists what a contextual row stores.
+
+### Removed
+
+- **Unreferenced helpers, dead stores and unused private parameters
+  (#523, #533)** — no behavior change. Removed module attributes:
+  `_streaming_evaluation.is_launch_trigger_row` and
+  `_streaming_evaluation.DEFAULT_POLL_INTERVAL_MINUTES` (the scheduler
+  cadence is `POLL_SCHEDULE` in `deploy/streaming_evaluation/setup.sh`),
+  `context_graph._INSERT_BIZ_NODES_QUERY`,
+  `context_graph._CANDIDATES_FOR_SESSION_QUERY` and
+  `materialize_window._DEFAULT_GRAPH_NAME_SENTINEL`. Dead locals go from
+  `resolved_spec.resolve_from_graph_spec`,
+  `bigquery_ontology.graph_ddl_compiler._resolve` and
+  `bigquery_ontology.owl_importer._yaml_scalar`, and never-read
+  parameters from the private `OntologyGraphManager._extract_graph_impl`
+  (`use_ai_generate`), `owl_importer._extract_relationships` (`entities`)
+  and `owl_importer._extract_skos_relationships` (`namespaces`), with
+  every call site updated. None of these names was exported from the
+  package or documented. Unused imports also go from
+  `scripts/quality_report.py`, `examples/e2e_demo.py` and
+  `examples/context_graph/run_agent.py`, and an unused `_HERE` from
+  `examples/a2a_joint_lineage_demo/run_analyst_agent.py` (repo side).
+
+### Dashboards (repo side, not in the wheel)
+
+- **BQCA Prompt & Response Logging dashboards (#515)** — the Looker
+  Studio template tools and the self-hosted Streamlit dashboard gain a
+  surface for BigQuery Conversational Analytics Prompt & Response Logging
+  tables:
+  - Looker Studio (`dashboard/looker_studio/`): a `bqca` profile
+    (`--profile bqca` on `hydrate_dashboard.py`, `render_template.py` and
+    `render_web_config.py`) for a dedicated template without tool pages,
+    with 7 pages and 34 components per `spec/bqca_chart_manifest.yaml`; a
+    custom-SQL generator (`tools/gen_bqca_events_tmpl.py`) and a preflight
+    query; an ADK Agents / BQCA surface toggle and a `bqca/` entry page in
+    the web configurator; and `tools/validate_contracts.py`, which checks
+    the template contracts. `scripts/check_external_access_staleness.py`
+    and its workflow now cover both templates' external-access
+    attestations, and the Pages deploy job runs only from `main`.
+  - Streamlit (`dashboards/streamlit/`): a BQCA surface
+    (`bqca_models.py`, `bqca_queries.py`, `bqca_charts.py`) with five
+    tabs (Overview & Latency; Data Agents & Personas; Prompt, Response &
+    SQL Explorer; Tokens & Embedding Suggestions; Error Attribution) over
+    nine allowlisted BQCA event types. Open it from the sidebar, with
+    `?profile=bqca` or with `BQAA_PROFILE`. Each BQCA query is dry-run
+    first and refused above the scan cap, and its job sets
+    `maximum_bytes_billed`.
+  - `README.md`, the Looker Studio README and USER_MANUAL,
+    `dashboards/streamlit/README.md` and the BQCA guide
+    (`docs/guides/bqca-prompt-response-logging-manual.md`) document both.
+- **BQCA Looker Studio template moves to a shareable copy (#520, #521)** —
+  the original template's organization allows sharing only inside it, so
+  every BQCA surface now points at report
+  `42e79a1f-a979-4de8-911f-80d5a99543d5`, a copy whose owner turned on
+  link sharing on 2026-10-09. External access is not verified yet:
+  `bindings/bqca_report_template.yaml` records `link_access: PUBLIC` as
+  owner-side intent, and its status stays
+  `PENDING_EXTERNAL_IDENTITY_CHECK` (next check due 2026-11-08) until an
+  outside account completes the copy flow. The Looker Studio
+  USER_MANUAL's "This report isn't shared with you" row now gives the
+  BQCA fallbacks: the self-hosted Streamlit BQCA dashboard, or the
+  `--custom-sql-out` query in your own Looker Studio report (#521).
+
+### Examples (repo side, not in the wheel)
+
+- **`agent_improvement_cycle` uses the canonical rubrics (#482 / #534)** —
+  the example's judge prompt is built from the `response_usefulness` and
+  `tool_usage` metrics of
+  `bigquery_agent_analytics.evaluation_rubrics.build_metrics()` instead
+  of a hand-written pass/fail rubric. Judge results record both
+  categories beside `pass`, and a `pass: true` verdict with any
+  recognized usefulness label other than `meaningful` now counts as a
+  failure. The improver agent selects failed sessions and formats their
+  trajectories with `partition_trajectories()` and `format_trajectory()`
+  from `scripts/skill_evolution.py`, and `examples/README.md` says how
+  `agent_improvement_cycle`, `self_evolving_agent_demo` and
+  `skill_evolution_lab` differ.
+- **The self-evolving demo reads its project from the environment first
+  (#525)** — `load_config()` in
+  `examples/self_evolving_agent_demo/analytics/session_metrics.py` called
+  `google.auth.default()` before reading `PROJECT_ID` /
+  `GOOGLE_CLOUD_PROJECT`, then discarded its project whenever either was
+  set. It now asks for Application Default Credentials only when both
+  are unset, and the returned config is unchanged. Two tests pin the
+  order.
+
+### Documentation
+
+- **`otel_spans` join recipes dedupe (#518)** — both join recipes in
+  SDK.md's trace and span correlation guide read the OTLP receiver's raw
+  `otel_spans` table, which the receiver writes at least once, so each
+  events row that matched a replayed span came back once per copy. Each
+  `spans` CTE now keeps only the newest row per `idempotency_key` (by
+  `ingest_time`), the rule of the receiver's `otel_spans_dedup` view,
+  after its constant timestamp filter, so partitions are still pruned.
+- **SDK.md producer details (#312 / #526)** — follow-ups from the #510
+  review: the legacy `attributes.source_event_id` key is only on
+  `AGENT_RESPONSE` rows written from the event stream; the per-event
+  views project neither `source_event_id` nor `attributes`, so
+  `Span.source_event_id` is `None` on a view row (read it from the events
+  table, as `get_trace()` does); `on_event_callback` also writes
+  `HITL_*_REQUEST_COMPLETED` rows; the google-adk 2.8.0 note now says
+  that 2.8.0 changed the span recorded by the `on_event_callback` rows of
+  a root agent that is not an `LlmAgent`; and the plugin leaves
+  `payload_column_denylist` columns out only of an events table it
+  creates, so an existing table keeps them.
+- **CLI and `gm` docs match the code (#528)** — `gm scaffold` requires
+  `--project` and `--out` (the docs called `--project` optional), so the
+  documented commands and the sample DDL and binding now carry the
+  project; the greenfield flow passes `--ontology` to `gm compile`;
+  `docs/ontology/cli.md` gives `--output` as `gm compile`'s long output
+  flag (`--out` is `gm import-owl`'s); SDK.md and
+  `docs/hatteras_evaluation.md` say that context calls accept
+  `persist_results=True` since U5 (#380); and SDK.md's global options
+  note that `categorical-views` takes `--results-table` instead of
+  `--table-id` and that `views create` and `views create-all` take no
+  `--location`. The ontology user manual it fixes
+  (`src/bigquery_ontology/docs/user_manual.md`) is excluded from the
+  wheel.
+
+### CI, tests and build locks (repo side, not in the wheel)
+
+- **Report-only mutation testing (#522)** — `scripts/mutation_testing.py`
+  mutates `udf_kernels.py`, `system_evaluator.py` and
+  `aggregate_grader.py` in a scratch copy (`pyproject.toml` is unchanged)
+  and writes a Markdown and a JSON report: the mutation score per module
+  and each surviving mutant. `mutation-testing.yml` runs it weekly
+  (Mondays 07:30 UTC) and on demand, never on pull requests; surviving
+  mutants never fail the run, and the report goes to the job summary and
+  a `mutation-report` artifact. The tool is pinned in
+  `scripts/requirements-mutation.txt`, not in a package extra, and
+  `docs/mutation_testing.md` covers running it and triaging survivors.
+- **`WeightedStrategy` rules pinned (#524)** — three tests in
+  `tests/test_aggregate_grader.py`: a weighted score exactly at the
+  threshold passes, all-zero weights give a failing 0.0 instead of a
+  `ZeroDivisionError`, and a grader's metric scores are averaged before
+  weighting.
+- **Streamlit dashboard tests consolidated (#519), and six lost checks
+  restored (#531 / #532)** — #519 merges the app, AppTest and chart
+  suites into `tests/test_dashboards_streamlit.py`, condenses
+  `tests/test_check_streamlit_queries_sync.py`, drops two unused locals
+  from `scripts/check_streamlit_queries_sync.py` and points
+  `streamlit-sync-check.yml` at the new files. #532 restores six checks
+  that the consolidation lost: effective filters across Apply, reconnect
+  and pending edits; two-value selections that survive a surface switch;
+  lazy tabs; the five-series line chart; color-map wrap-around; and
+  integer run IDs. Dashboard code is unchanged.
+- **`dashboard_v2` lock bump (#517)** — `source-map-js` 1.2.1 → 1.2.2, an
+  indirect dependency, in `dashboard_v2/package-lock.json`.
+- **Browser smoke polls Chrome every 0.1 s (#536)** — `dump_dom()` in
+  `browser_smoke.sh` checks the background browser every 0.1 s instead
+  of every second, so a pass ends within 0.1 s of the browser exiting,
+  not on the next whole second; the output deadline (450 polls) and the
+  grace window (100 polls) keep their 45 s and 10 s of sleep. In CI,
+  self-test fixtures 2–14 together went from a median 21.6 s to 16.0 s.
+  A browser that never writes output now takes about 7 s longer to time
+  out on macOS, because every poll starts a `sleep` process.
+
 ## [0.6.0] - 2026-10-08
 
 ### Release highlights

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bigquery-agent-analytics
-Version: 0.6.0
+Version: 0.6.1
 Summary: SDK for analyzing and evaluating agent traces stored in BigQuery.
 Author: Google LLC
 License-Expression: Apache-2.0
@@ -95,7 +95,7 @@ regressions — all through BigQuery SQL or Python.
 **Observability**
 - Trace reconstruction and DAG visualization
 - Per-event-type BigQuery views
-- Observability dashboards (Looker Studio, SQL, and BigFrames)
+- Observability dashboards (Looker Studio, Streamlit, SQL, and BigFrames), including BQCA Prompt & Response Logging dashboards for Conversational Analytics data agents
 
 **Evaluation**
 - System metrics (latency, turn count, tool call error rate, token efficiency, time to first token, cost)
@@ -353,6 +353,8 @@ with a runnable ADK agent.
 | [BQCA Prompt & Response Logging Manual](docs/guides/bqca-prompt-response-logging-manual.md) | Self-hosting setup, capability matrix, customization, and self-debugging guide for the [BQCA Customer Starter Notebook](examples/bqca_prompt_response_logging_customer_notebook.ipynb) ([Open in Colab](https://colab.research.google.com/github/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/bqca_prompt_response_logging_customer_notebook.ipynb)) |
 | [Looker Studio Dashboard](dashboard/looker_studio/README.md) | Published 37-chart BQAA observability template with project/dataset/table configurator |
 | [Dashboard User Manual](dashboard/looker_studio/USER_MANUAL.md) | End-user guide to the Looker Studio dashboard: setup in three steps, page guide, sharing, troubleshooting |
+| [Streamlit Dashboard](dashboards/streamlit/README.md) | Self-hosted dashboard with two surfaces: ADK Agents, and BQCA Prompt & Response Logging (turn latency, data agents and personas, prompt/response/SQL explorer, tokens, embedding suggestions, error attribution) |
+| [BQCA Analytics Dashboards](docs/guides/bqca-prompt-response-logging-manual.md#74-visualizing-logs-with-the-bqca-analytics-dashboards-looker-studio--streamlit) | Visualize BQCA Prompt & Response Logging with Looker Studio (`hydrate_dashboard.py --profile bqca`, `/bqca/` configurator) or Streamlit (`?profile=bqca`) |
 | [Agent Context Graph Codelab](docs/codelabs/periodic_materialization.md) | Extract decision traces from your agent's context graph, end to end (~35 min) |
 | [Scheduled Deploy Runbook](docs/guides/scheduled-context-graph-deploy.md) | Keep the context graph fresh on a Cloud Run + Cloud Scheduler cron |
 | [Design Documents](docs/README.md) | Architecture decisions and design rationale |

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/README.md

@@ -22,7 +22,7 @@ regressions — all through BigQuery SQL or Python.
 **Observability**
 - Trace reconstruction and DAG visualization
 - Per-event-type BigQuery views
-- Observability dashboards (Looker Studio, SQL, and BigFrames)
+- Observability dashboards (Looker Studio, Streamlit, SQL, and BigFrames), including BQCA Prompt & Response Logging dashboards for Conversational Analytics data agents
 
 **Evaluation**
 - System metrics (latency, turn count, tool call error rate, token efficiency, time to first token, cost)
@@ -280,6 +280,8 @@ with a runnable ADK agent.
 | [BQCA Prompt & Response Logging Manual](docs/guides/bqca-prompt-response-logging-manual.md) | Self-hosting setup, capability matrix, customization, and self-debugging guide for the [BQCA Customer Starter Notebook](examples/bqca_prompt_response_logging_customer_notebook.ipynb) ([Open in Colab](https://colab.research.google.com/github/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/bqca_prompt_response_logging_customer_notebook.ipynb)) |
 | [Looker Studio Dashboard](dashboard/looker_studio/README.md) | Published 37-chart BQAA observability template with project/dataset/table configurator |
 | [Dashboard User Manual](dashboard/looker_studio/USER_MANUAL.md) | End-user guide to the Looker Studio dashboard: setup in three steps, page guide, sharing, troubleshooting |
+| [Streamlit Dashboard](dashboards/streamlit/README.md) | Self-hosted dashboard with two surfaces: ADK Agents, and BQCA Prompt & Response Logging (turn latency, data agents and personas, prompt/response/SQL explorer, tokens, embedding suggestions, error attribution) |
+| [BQCA Analytics Dashboards](docs/guides/bqca-prompt-response-logging-manual.md#74-visualizing-logs-with-the-bqca-analytics-dashboards-looker-studio--streamlit) | Visualize BQCA Prompt & Response Logging with Looker Studio (`hydrate_dashboard.py --profile bqca`, `/bqca/` configurator) or Streamlit (`?profile=bqca`) |
 | [Agent Context Graph Codelab](docs/codelabs/periodic_materialization.md) | Extract decision traces from your agent's context graph, end to end (~35 min) |
 | [Scheduled Deploy Runbook](docs/guides/scheduled-context-graph-deploy.md) | Keep the context graph fresh on a Cloud Run + Cloud Scheduler cron |
 | [Design Documents](docs/README.md) | Architecture decisions and design rationale |

{bigquery_agent_analytics-0.6.0 → bigquery_agent_analytics-0.6.1}/SDK.md

@@ -167,7 +167,7 @@ correlation identifiers:
 |---|---|---|
 | 1. Trace and execution tree | `trace_id`, `span_id`, `parent_span_id` (columns and `Span` fields) | `trace_id` is the OpenTelemetry trace ID whenever the run has an active span, so it matches Cloud Trace. `span_id` / `parent_span_id` are the plugin's own execution tree: they link rows of the events table to each other and drive `Trace` (for example `trace.render()`). They are **not** OpenTelemetry span IDs; only the root invocation row may reuse the active span ID. |
 | 2. OpenTelemetry span | `attributes.otel.span_id` / `attributes.otel.trace_id`; the `otel_span_id` / `otel_trace_id` [view columns](#otel-correlation-columns-and-denied_columns) and `Span` fields | The OpenTelemetry span that was active when the row was written. Recorded only when the plugin runs with `enable_otel_correlation=True`. A best-effort join key into Cloud Trace or an `otel_spans` table, not a foreign key: spans dropped by head sampling are never exported. |
-| 3. Source event | `attributes.adk.source_event_id` (and the legacy `attributes.source_event_id` on `AGENT_RESPONSE` rows); the `Span.source_event_id` field | The ADK `Event.id` behind a row written from the event stream. ADK 2.0 `invoke_node` spans list the IDs of the events their node yielded in the span attribute `gcp.vertex.agent.associated_event_ids`. |
+| 3. Source event | `attributes.adk.source_event_id` (and the legacy `attributes.source_event_id` on `AGENT_RESPONSE` rows written from the event stream); the `Span.source_event_id` field | The ADK `Event.id` behind a row written from the event stream. `AGENT_RESPONSE` rows from `after_tool_callback` (`final_response_tool_names`) carry no source event ID. ADK 2.0 `invoke_node` spans list the IDs of the events their node yielded in the span attribute `gcp.vertex.agent.associated_event_ids`. |
 
 #### Producer configuration
 
@@ -179,7 +179,7 @@ behavior.
 |---|---|---|
 | `enable_otel_correlation` | `False` | When `True`, each row records the active OpenTelemetry span context in `attributes.otel.span_id` (16 hex digits) and `attributes.otel.trace_id` (32 hex digits). A row written while no valid span is active gets no `attributes.otel`. The plugin does not create spans of its own. |
 | `custom_metadata_allowlist` | `None` | Keys of `Event.custom_metadata` to copy into `attributes.custom_metadata`: exact keys, or prefixes ending in `*` (for example `"a2a:*"`). `None` or empty keeps only the built-in `a2a:*` capture. |
-| `payload_column_denylist` | `None` | Payload columns to leave out of the events table. Only `content`, `content_parts`, `attributes` and `latency_ms` are accepted; any other name raises `ValueError`. Denying `attributes` removes layers 2 and 3 (`attributes.otel`, `attributes.adk`) as well as `attributes.custom_metadata`, and combining it with a non-empty `custom_metadata_allowlist` raises `ValueError`. |
+| `payload_column_denylist` | `None` | Payload columns the plugin does not write; it leaves them out of the events table only when it creates the table. Only `content`, `content_parts`, `attributes` and `latency_ms` are accepted; any other name raises `ValueError`. Denying `attributes` removes layers 2 and 3 (`attributes.otel`, `attributes.adk`) as well as `attributes.custom_metadata`, and combining it with a non-empty `custom_metadata_allowlist` raises `ValueError`. |
 
 ```python
 from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin
@@ -203,7 +203,10 @@ an `otel_spans` table (for example by the
 columns when the row has them (for example a row read from a per-event view)
 and otherwise from `attributes`. They are `None` on rows that do not record
 them, such as rows written with `enable_otel_correlation=False` or by an older
-plugin. The span tree is still built from `span_id` / `parent_span_id` alone.
+plugin. The SDK's per-event views project neither `source_event_id` nor
+`attributes`, so `source_event_id` is always `None` on a view row; read it
+from rows of the events table itself, as `get_trace()` does. The span tree is
+still built from `span_id` / `parent_span_id` alone.
 
 ```python
 trace = client.get_trace("trace-abc-123")
@@ -228,7 +231,7 @@ into six groups. Older releases write fewer event types:
 | `before_agent_callback`, `after_agent_callback`, `on_agent_error_callback` | `AGENT_STARTING`, `AGENT_COMPLETED`, `AGENT_ERROR` | `invoke_agent {agent_name}` | Exact; the row's `span_id` is a plugin-only ID |
 | `before_model_callback`, `after_model_callback`, `on_model_error_callback` | `LLM_REQUEST`, `LLM_RESPONSE` (streaming partials and final), `LLM_ERROR` | `call_llm` (parent of `generate_content {model}`) as of google-adk 2.11. ADK's telemetry schema migration plans to remove `call_llm`; re-check this row after that change. | Exact; one ID for the request, every partial and the final response or error |
 | `before_tool_callback`, `after_tool_callback`, `on_tool_error_callback` | `TOOL_STARTING`, `TOOL_COMPLETED`, `TOOL_ERROR`, `AGENT_RESPONSE` (tools in `final_response_tool_names`) | `execute_tool {tool_name}`; for a tool used as a node in a `Workflow` (google-adk 2.11 runs these callbacks there too), the node's `invoke_node {node_name}` span | Exact; distinct for each parallel tool call |
-| `on_event_callback` | `STATE_DELTA`, `NODE_OUTPUT`, `NODE_ERROR`, `AGENT_TRANSFER`, `EVENT_COMPACTION`, `AGENT_STATE_CHECKPOINT`, `TOOL_PAUSED`, `HITL_*_REQUEST`, `A2A_INTERACTION`, `AGENT_RESPONSE` | The runner's root span, as in the rows above: the runner writes these rows outside the span of the node that produced the event | Coarse; for events yielded by function nodes or other nodes that are neither agents nor workflows, join on `source_event_id` instead (second recipe below) |
+| `on_event_callback` | `STATE_DELTA`, `NODE_OUTPUT`, `NODE_ERROR`, `AGENT_TRANSFER`, `EVENT_COMPACTION`, `AGENT_STATE_CHECKPOINT`, `TOOL_PAUSED`, `HITL_*_REQUEST`, `HITL_*_REQUEST_COMPLETED`, `A2A_INTERACTION`, `AGENT_RESPONSE` | The runner's root span, as in the rows above: the runner writes these rows outside the span of the node that produced the event | Coarse; for events yielded by function nodes or other nodes that are neither agents nor workflows, join on `source_event_id` instead (second recipe below) |
 
 #### Join recipes for an `otel_spans` table
 
@@ -240,6 +243,14 @@ the constant `@start_ts` / `@end_ts` bounds, which prune partitions and satisfy
 `require_partition_filter`. The ±1 hour window in the join condition refers to
 the other table, so it narrows the matches but prunes nothing.
 
+The receiver writes `otel_spans` at least once: a retried or replayed export
+adds another row for the same span, with the same `idempotency_key` (the span's
+`trace_id` followed by its `span_id`) and a later `ingest_time`. Each `spans`
+CTE therefore keeps only the newest row per `idempotency_key`, the same rule as
+the receiver's `otel_spans_dedup` view. Without it, each `events` row that
+matches a duplicated span comes back once per copy. `QUALIFY` is evaluated
+after `WHERE`, so the constant bounds still prune partitions.
+
 Rows from the synchronous callbacks join directly on
 `attributes.otel.span_id`. Use a `LEFT JOIN`, since unsampled spans are missing
 from `otel_spans`:
@@ -266,6 +277,10 @@ spans AS (
   FROM `my-project.my_dataset.otel_spans`
   WHERE timestamp BETWEEN @start_ts AND @end_ts
     AND trace_id = @trace_id
+  -- At-least-once writes: keep the newest row of each span.
+  QUALIFY ROW_NUMBER() OVER (
+    PARTITION BY idempotency_key ORDER BY ingest_time DESC
+  ) = 1
 )
 SELECT
   e.timestamp,
@@ -315,6 +330,10 @@ spans AS (
   FROM `my-project.my_dataset.otel_spans`
   WHERE timestamp BETWEEN @start_ts AND @end_ts
     AND trace_id = @trace_id
+  -- At-least-once writes: keep the newest row of each span.
+  QUALIFY ROW_NUMBER() OVER (
+    PARTITION BY idempotency_key ORDER BY ingest_time DESC
+  ) = 1
 )
 SELECT
   e.timestamp,
@@ -347,11 +366,12 @@ These joins are best-effort:
   `LlmAgent` root, list their events on no span (`invoke_agent` spans carry no
   `gcp.vertex.agent.associated_event_ids`), so their rows have no match;
   narrow those by `trace_id` and time instead.
-- Before google-adk 2.8.0, a root agent that is not an `LlmAgent` (for
-  example a `SequentialAgent`) runs on the runner's classic path, where
+- A root agent that is not an `LlmAgent` (for example a `SequentialAgent`)
+  runs on the runner's classic path. There, before google-adk 2.8.0,
   `on_event_callback` rows record the span that was active where the agent
   yielded the event, such as an `invoke_agent` span, instead of the runner's
-  root span.
+  root span. Since 2.8.0, `BaseAgent.run_async` yields each event in its
+  caller's context.
 - A span that starts before `@start_ts`, such as a long root span, is
   filtered out of `spans`. Subtract a margin from `@start_ts` in that CTE; a
   constant expression still prunes partitions. The join condition compares
@@ -1132,7 +1152,7 @@ Compare your golden dataset against production traffic to understand coverage ga
 
 ```python
 drift_report = client.drift_detection(
-    golden_dataset="my_project.golden.qa_pairs_v3",
+    golden_dataset="qa_pairs_v3",  # a table in the client's dataset
     filters=TraceFilter(
         agent_id="support_bot",
         start_time=datetime.now() - timedelta(days=30),
@@ -1626,10 +1646,14 @@ Every per-event view also projects `otel_span_id` and `otel_trace_id`, right
 after the standard headers, from `attributes.otel` (see
 [Trace & Span Correlation](#trace--span-correlation-trace_id-span_id-attributesotelspan_id-attributesadksource_event_id)).
 Both are `NULL` on rows written without `enable_otel_correlation=True`.
+Because both read `attributes`, `SELECT *` on any per-event view reads that
+column as well, unless `denied_columns` (below) includes `attributes`.
 
-If the plugin writes the events table with `payload_column_denylist`, pass the
-same column names as `denied_columns` so the views read only columns that
-exist:
+The plugin omits the columns in `payload_column_denylist` only from an events
+table it creates; its schema upgrade only adds columns, so an existing table
+keeps them. If payload columns are missing from the events table because the
+plugin projects them out, pass the same names as `denied_columns` so the views
+read only columns that exist:
 
 ```python
 vm = ViewManager(
@@ -1663,8 +1687,8 @@ created = vm.create_all_views()
 
 - `Client` read methods such as `get_trace()` select `content`,
   `content_parts`, `attributes` and `latency_ms` by name, so they fail on an
-  events table written with `payload_column_denylist`; `denied_columns` applies
-  only to the views.
+  events table that lacks any of them; `denied_columns` applies only to the
+  views.
 
 The plugin's own views (`BigQueryLoggerConfig(create_views=True)`) handle a
 denylist differently: they drop only the derived columns that read a denied
@@ -1900,10 +1924,14 @@ filtered population are ignored.
 Treat context as trusted evaluator material subject to the same governance as
 your evaluation prompts. It is carried as query-parameter/model input and is
 redacted from context-aware error logs; it is never SQL text or a job label.
-The U4 API deliberately rejects `persist_results=True` with context until the
-U5 identity columns, writer, views, and cardinality migration land, preventing
-two identities that reuse a session ID from being persisted as indistinguishable
-rows.
+`persist_results=True` works with context: each row carries the trace identity
+(`user_id`, `root_agent_name`, `experiment_id`, `scope_key`, `identity_key`)
+and SDK-owned provenance (`context_applied`, `context_source`), so two
+identities that reuse a session ID stay distinct rows. The context itself is
+never persisted, and neither is model text that could echo it: contextual rows
+write `justification` and `raw_response` as NULL and keep `category` only when
+it matched one of the metric's categories. An unrecognized category is written
+as NULL with `parse_error` set.
 
 ### Step 3: Create Dashboard Views
 
@@ -2267,7 +2295,11 @@ pip install bigquery-agent-analytics
 
 ### Global Options
 
-Every command accepts:
+The commands below accept these options, except that `categorical-views`
+takes `--results-table` instead of `--table-id`, and `views create` and
+`views create-all` take no `--location`. Commands documented elsewhere, such
+as `export langsmith` and `evalbench-import`, have their own options;
+`bq-agent-sdk <command> --help` lists each command's set.
 
 | Option | Env Var | Default | Description |
 |--------|---------|---------|-------------|
@@ -2410,7 +2442,7 @@ bq-agent-sdk categorical-views --project-id=P --dataset-id=D --prefix=adk_
 ```bash
 bq-agent-sdk views create-all --project-id=P --dataset-id=D --prefix=adk_
 
-# Events table written with payload_column_denylist=["attributes"]
+# Events table the plugin created with payload_column_denylist=["attributes"]
 # (repeat --denied-column for more columns; views create takes it too)
 bq-agent-sdk views create-all --project-id=P --dataset-id=D --denied-column=attributes
 ```