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

{bigquery_agent_analytics-0.5.4 → 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.5.4 → 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.5.4 → 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.5.4 → bigquery_agent_analytics-0.6.1}/CHANGELOG.md

@@ -7,6 +7,431 @@ 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
+
+A minor release: it adds public API, and the per-event views change what
+they select and which tables they deploy over (see Changed). In the wheel:
+span-level OpenTelemetry correlation (#312 / #510). `Span` gains
+`otel_span_id`, `otel_trace_id` and `source_event_id`; every per-event
+view selects `otel_span_id` and `otel_trace_id`; and
+`ViewManager(denied_columns=...)`, with a matching `--denied-column` flag
+on the `views` CLI, deploys views over an events table written with the
+plugin's `payload_column_denylist` (#321). Two view changes matter when
+you upgrade: the event-specific columns now come two positions later, and
+over an events table with no `attributes` column the per-event views
+deploy only with `denied_columns=["attributes"]`. Unused imports are
+dropped from 11 modules (#504). No public API is removed or renamed, and
+the wheel's dependencies are unchanged. Around the wheel: an agent memory
+demo built from `agent_events` (#512) and a BigQuery Conversational
+Analytics (BQCA) Prompt & Response Logging starter notebook and manual
+(#507) land under `examples/` and `docs/`; SDK.md gains a trace and span
+correlation guide (#510) and a `compaction_windows` limitation note
+(#502), and the EvalBench guide documents its `import_version` pin (#508);
+two deploy scripts keep IAM-retry stderr in a private temp file (#506);
+and tests, a hash lock and the tracing producer get small cleanups (#505,
+#509, #513).
+
+### Added
+
+- **Span-level OpenTelemetry correlation (#312 / #510)** — `Span` gains
+  `otel_span_id`, `otel_trace_id` and `source_event_id` after its
+  existing fields, so positional construction is unchanged.
+  `Span.from_bigquery_row()` reads them from same-named columns, or else
+  from `attributes.otel` and `attributes.adk` (or the legacy
+  `attributes.source_event_id`), ignoring non-string values in
+  `attributes`; they stay `None` on rows without those columns or keys,
+  and the span tree is still built from `span_id` / `parent_span_id`.
+  Every per-event view also projects
+  `otel_span_id` and `otel_trace_id`, which are `NULL` unless the ADK
+  plugin runs with `BigQueryLoggerConfig(enable_otel_correlation=True)`
+  (`google-adk>=2.4.0`).
+- **`ViewManager(denied_columns=...)` (#321 / #510)** — a keyword-only
+  argument for an events table written with the plugin's
+  `payload_column_denylist`. Denying `attributes` drops the two
+  OpenTelemetry columns, and a view whose own SQL reads a denied column
+  is skipped by `create_all_views()` (with a warning) and rejected by
+  `create_view()` with `ValueError` before any query runs. With
+  `denied_columns=["attributes"]` the six per-event views that read
+  `attributes` (`LLM_REQUEST`, `LLM_RESPONSE`, `TOOL_COMPLETED`,
+  `STATE_DELTA`, `A2A_INTERACTION`, `TOOL_PAUSED`) and
+  `compaction_windows` are skipped; the other 19 per-event views deploy.
+  Only `content`, `content_parts`, `attributes` and `latency_ms` (exact
+  case) are accepted: any other name raises `ValueError`, and a single
+  string instead of a collection raises `TypeError`.
+  `bq-agent-sdk views create-all` and `views create` take the same names
+  as a repeatable `--denied-column` flag and exit 2 on an invalid name.
+
+### Changed
+
+- **Per-event views select two more columns (#312 / #510)** — every
+  per-event `CREATE OR REPLACE VIEW` statement now selects the nullable
+  `otel_span_id` and `otel_trace_id` between the standard headers and the
+  event-specific columns. Existing columns keep their names and types,
+  but the event-specific columns now come two positions later: update
+  anything that reads view columns by position, such as
+  `INSERT INTO ... SELECT *` from a view. Re-run `create_all_views()` to
+  pick up the new columns. Over an events table without an `attributes`
+  column, every per-event view now fails to deploy unless you pass
+  `ViewManager(denied_columns=["attributes"])` or
+  `bq-agent-sdk views create-all --denied-column=attributes`; with it,
+  the same 19 per-event views deploy as before and the other six are
+  skipped.
+
+### Removed
+
+- **Unused imports (#504)** — import lines only, in 11 modules; no logic,
+  signature or exported name changes. Module attributes that existed only
+  as these imports are gone: `ai_ml_integration.timedelta`,
+  `eval_validator.field`, `extractor_compilation.diagnostics.Any`,
+  `extractor_compilation.measurement.CompileResult` (import it from
+  `extractor_compilation` or the package root), `feedback.dataclass`,
+  `feedback.field`, `feedback.json`, `insights.asyncio`,
+  `insights.dataclass`, `insights.json`,
+  `ontology_materializer.ResolvedProperty` (defined in `resolved_spec`),
+  `ontology_models.Any`, `ttl_importer.XSD` (present only with `rdflib`
+  installed; use `rdflib.XSD`) and
+  `bigquery_ontology.graph_ddl_compiler.PropertyBinding` (exported from
+  `bigquery_ontology`). None of these names was exported from the
+  package or documented.
+
+### Examples and guides (repo side, not in the wheel)
+
+- **Agent memory demo (#511 / #512)** — `examples/agent_memory/` reads
+  three memory layers back from the `agent_events` rows that the ADK
+  `BigQueryAgentAnalyticsPlugin` writes, with `Client.list_traces`:
+  short-term (per-session conversations), long-term (the version history
+  of ADK `user:` state, plus entities) and reasoning (one trace per
+  invocation with its model turns, tool calls and outcome). It combines
+  them in a `get_context()` prompt block whose lines name their source
+  rows. The demo runs offline on a committed synthetic fixture, through
+  the real `Client` and a fail-closed stand-in for `bigquery.Client`, or
+  live with `--project-id` / `--dataset-id`. `analyst_agent.py` runs a
+  live ADK data-analyst agent (`gemini-3.8-flash`) over
+  `bigquery-public-data.thelook_ecommerce`; `memory_consolidation.py`
+  extracts facts and entities from each logged user message with
+  `AI.GENERATE` and embeds it with `AI.EMBED`, and recall ranks similar
+  past tasks with `ML.DISTANCE`. The recorded run of 2026-10-07 (36
+  sessions with memory and 6 without, 1,606 logged rows), a static web
+  view and a narrated video are committed. Its tests in
+  `tests/examples/test_agent_memory_*.py` (182 cases) run without network
+  or credentials.
+- **BQCA Prompt & Response Logging starter notebook and manual (#507)** —
+  `examples/bqca_prompt_response_logging_customer_notebook.ipynb` and
+  `docs/guides/bqca-prompt-response-logging-manual.md` evaluate BigQuery
+  Conversational Analytics Prompt & Response Logging tables with this SDK,
+  in eight sections: schema and Vertex AI health (`doctor()` plus an
+  `AI.GENERATE` ping), a conversation explorer, sentiment and UX triage,
+  question topics, semantic drift and golden-question coverage, golden Q&A
+  grading, FinOps, and operational health. Two non-destructive compatibility
+  views, one for the SDK and one for SQL and BI, flatten BQCA's nested
+  `AGENT_RESPONSE` JSON. The notebook's SDK adapters are notebook code, not
+  wheel changes, and its install cell installs
+  `bigquery-agent-analytics[llm]==0.5.4` when the SDK is missing or older
+  than 0.5.4. `README.md` and `examples/README.md` link both.
+
+### Documentation
+
+- **Trace and span correlation guide (#209, #220, #320 / #510)** — SDK.md
+  documents the three correlation layers, the plugin's
+  `enable_otel_correlation`, `custom_metadata_allowlist` and
+  `payload_column_denylist` options, the OpenTelemetry span each plugin
+  callback records, and two partition-pruned SQL recipes that join the
+  events table to an `otel_spans` table.
+- **`compaction_windows` partition limitation in SDK.md (#502)** — the
+  view's reference section now states the known limitation recorded in
+  0.5.4 (no event `timestamp` column, so no partition pruning, and a
+  failure on tables that set `require_partition_filter`) and points
+  time-bounded queries at the `adk_event_compactions` per-event view,
+  which is not a drop-in replacement. A test ties the note to the view.
+- **EvalBench drill-down `import_version` pin (#508)** —
+  `docs/evalbench.md` now says that `EvalBenchSession.trace_selector()`
+  also returns `import_version` and that
+  `EvalBenchImportSessions.trace_filter()` sets
+  `TraceFilter(import_version=...)`. The pin is redundant for imports
+  converted from EvalBench source tables, but it is what isolates one
+  version of a native `agent_events` import (#463).
+
+### Security (repo side, not in the wheel)
+
+- **IAM-retry stderr goes to a private temp file (#506)** — `_retry_iam` in
+  `deploy/skill_evolution_job/deploy.sh` and
+  `examples/context_graph/periodic_materialization/deploy_cloud_run_job.sh`
+  wrote each IAM grant's stderr to `/tmp/_iam_err.$$`, a name another local
+  user can predict: the redirect truncated the target of a symlink planted
+  there, and the file was world-readable under a 022 umask. Both scripts now
+  capture it in a `mktemp` file (mode 0600, random name) that is removed on
+  every return path; retries are unchanged.
+
+### CI, tests and build locks (repo side, not in the wheel)
+
+- **Compiled-only deploy-script test stays offline (#505)** —
+  `test_compiled_only_now_accepted_by_validator` shadows `python3`, `bq`
+  and `gcloud` on the subprocess `PATH`, so `deploy_cloud_run_job.sh` no
+  longer pip-installs from PyPI or calls BigQuery during the unit test,
+  and the test now asserts that the script reached its first deploy
+  step. The deploy script is unchanged.
+- **Browser smoke readiness budget (#513)** — `browser_smoke.sh` reads
+  its readiness budget from `SMOKE_READY_POLLS` (default 20 polls, 0.5 s
+  apart, so the real check is unchanged) and rejects an invalid value
+  before it starts a server or browser. The self-test's
+  alive-but-unready fixture uses 4 polls, about 8 s less per self-test
+  run.
+- **Dead private helpers and a drifted hash lock (#509)** — removes the
+  tracing producer's unused OTLP writer helper `_str` (under
+  `producers/`, which ships on `tracing-v*` tags; no tracing release
+  includes it yet) and an unused test helper, with no behavior change,
+  and regenerates `deploy/otlp_receiver/requirements.lock` for upstream
+  PyPI drift (newer pins such as `google-cloud-bigquery` 3.46.1,
+  `google-auth` 2.60.0, `cryptography` 50.0.2 and OpenTelemetry 1.45.1).
+
 ## [0.5.4] - 2026-09-29
 
 ### Release highlights

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bigquery-agent-analytics
-Version: 0.5.4
+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)
@@ -350,8 +350,11 @@ with a runnable ADK agent.
 | Resource | Description |
 |----------|-------------|
 | [SDK Feature Reference](SDK.md) | Complete API walkthrough with working code examples |
+| [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.5.4 → 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)
@@ -277,8 +277,11 @@ with a runnable ADK agent.
 | Resource | Description |
 |----------|-------------|
 | [SDK Feature Reference](SDK.md) | Complete API walkthrough with working code examples |
+| [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 |