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

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

@@ -37,6 +37,15 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Reject SDLC working notes (intent.md / plan.md / spec.md)
+        run: |
+          found="$(find . -path ./.git -prune -o -type f \( -name intent.md -o -name plan.md -o -name spec.md \) -print)"
+          if [ -n "$found" ]; then
+            echo "$found"
+            echo "::error::intent.md / plan.md / spec.md must not be checked in. Keep SDLC working notes outside this repo."
+            exit 1
+          fi
+
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: "3.12"
@@ -47,7 +56,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 +85,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.4}/.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.4/.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.4}/.gitignore

@@ -37,6 +37,16 @@ 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
+
+# SDLC working notes (intent / spec / plan) live outside this repo.
+# Basename patterns match at any depth; CI "Format check" also enforces this.
+intent.md
+plan.md
+spec.md

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

@@ -7,6 +7,293 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-09-29
+
+### Release highlights
+
+A small patch release. In the wheel: a `compaction_windows` cross-event
+view deploys beside the per-event views (#216 / #494); the
+extractor-compilation smoke test decodes its child process's pickled
+output through an allowlist, so compiled-extractor code can no longer
+run code in the parent (#492); and unreferenced private helpers and
+imports are removed (#490, #496). No public API is removed or renamed,
+and the wheel's dependencies are unchanged. Around the wheel: the
+separately released tracing producer keeps its spool, state and log
+private to the user, with compatibility notes below (#499); SDK docs
+and examples are corrected against the code (#493, #495); and CI,
+tests and hash locks are tidied (#490, #491, #497, #500).
+
+### Added
+
+- **Compaction windows view (#216 / #494)** — `ViewManager` and the
+  `views` CLI deploy `compaction_windows` (`adk_compaction_windows` by
+  default, `<view_prefix>compaction_windows` otherwise) from the
+  cross-event registry: `create_all_views()` and
+  `bq-agent-sdk views create-all` now create it after the per-event
+  views, and `bq-agent-sdk views create compaction_windows` creates it
+  alone. It returns one row per distinct compaction range for each full
+  telemetry identity (`app_name`, `user_id`, `session_id`,
+  `invocation_id`), keeps fractional epoch seconds at microsecond
+  precision, and excludes incomplete identities and invalid boundaries.
+  Per-event view SQL is unchanged. Known limitation: the view exposes no
+  event `timestamp` column, so a query through it scans the whole events
+  table (no partition pruning) and fails on a table that sets
+  `require_partition_filter`.
+
+### Security
+
+- **Smoke-test harness unpickles child output against an allowlist
+  (#492)** — `run_smoke_test_in_subprocess` decodes the child process's
+  pickled result with a restricted unpickler that admits only the SDK's
+  extraction result and model classes (`StructuredExtractionResult`,
+  `ExtractorException`, `ExtractedNode`, `ExtractedEdge`,
+  `ExtractedProperty`) plus a few inert standard-library value types
+  (`datetime`, `date`, `time`, `timedelta`, `timezone`, `Decimal`,
+  `bytearray`). A `__reduce__` gadget in untrusted compiled-extractor
+  code can no longer run in the parent process: any other global fails
+  closed and is reported as a smoke-test harness failure. An extractor
+  whose `ExtractedProperty.value` holds another type that pickle looks
+  up by name, such as a custom class instance or a `uuid.UUID`, now
+  fails the gate the same way; `str`, `int`, `float`, `bool`, `None`,
+  lists, dicts and sets are unaffected.
+
+### Removed
+
+- **Unreferenced private helpers and incidental imports (#490, #496)** —
+  #490 deletes unreferenced private helpers and unused imports from seven
+  `src/` modules (59 lines), and #496 drops two unused imports from
+  `system_evaluator.py`. Supported behavior is unchanged, but module
+  attributes that existed only as incidental imports are gone:
+  `client.CATEGORICAL_AI_GENERATE_QUERY` (import it from
+  `categorical_evaluator`), `system_evaluator.strip_markdown_fences`
+  (still exported from `utils` and `evaluators`),
+  `system_evaluator._parse_json_from_text` (a private helper that stays
+  in `utils`), `system_evaluator.udf_kernels` and
+  `_streaming_evaluation.udf_kernels` (import
+  `bigquery_agent_analytics.udf_kernels`),
+  `ontology_schema_compiler.ResolvedEntity` / `ResolvedRelationship`
+  (defined in `resolved_spec`), `insights.dc_field` (use
+  `dataclasses.field`) and `trace.functools`. The deleted private
+  helpers are `ontology_schema_compiler._compile_entity_schema`,
+  `_compile_relationship_schema` and `ontology_runtime._first_string_value`.
+  None of these names was exported from the package or documented.
+
+### Tracing producer (released separately, not in this wheel)
+
+- **Spool, state and log are private to the user (#499)** — this changes
+  `bigquery-agent-analytics-tracing` under `producers/`, which ships on
+  `tracing-vX.Y.Z` tags; no tracing release includes it yet. The spool,
+  state and log now default to a per-user
+  `<tempdir>/bqaa-agent-tracing-<user>/` directory created with mode
+  0700 (`<user>` is the numeric uid; without `os.getuid`, a sanitized
+  login name, else a per-process tag) instead of the shared
+  `/tmp/bqaa-agent-tracing/` and `/tmp/bqaa-agent-tracing.log`. Spool
+  and state files are created with mode 0600 and, where the platform
+  supports it, opened relative to the checked directory with
+  `O_NOFOLLOW`. Compatibility:
+  - Spool, state and dead-letter directories, default or set through
+    `BQAA_SPOOL_DIR` / `BQAA_STATE_DIR`, are refused if they are a
+    symlink, are owned by another user, are group- or world-writable
+    (for a directory you own, remove both write bits with
+    `chmod go-w`), or sit under a parent owned by another non-root
+    user. A shared directory such as `/tmp` itself is refused.
+  - An explicit `BQAA_LOG_FILE` must be a regular file you own or a
+    character device; `/dev/stdout`, `/dev/stderr`, `/dev/null` and
+    terminals keep working. Its directory and every physical parent
+    must be owned by root or by you, and a directory of yours must not
+    be group- or world-writable; a missing directory is created with
+    mode 0700. Symlinks leading to an existing log directory outside
+    the state directory are still followed (a log inside the state
+    directory gets the spool and state rules above), but a symlink at
+    the log file name is refused, and in a root-owned shared directory
+    such as `/tmp` a log with other hard links is refused. An existing
+    log with group or other permission bits is changed to mode 0600.
+  - Refusals fail closed. The drainer exits 1 without draining when its
+    spool directory is refused. Hooks swallow the error and return 0;
+    they try to log it, but a refused log path drops log lines silently,
+    so nothing is recorded when the refused directory also holds the log
+    (the default layout).
+  - The drainer uploads only spool entries that are regular files you
+    own; anything else is left in place and logged once per drainer run.
+  - The old `/tmp` paths are no longer the defaults and queued rows are
+    not migrated: drain or copy any rows you need from the old spool
+    before deleting it. Explicit `BQAA_*` paths keep working when they
+    pass the checks above.
+  - Where a platform lacks descriptor-relative calls or `O_NOFOLLOW`,
+    the checks run by path as a best effort; without `os.geteuid`, the
+    ownership and permission-mode checks are skipped, and tightening an
+    existing log's mode needs `os.fchmod`. None of this adds Windows
+    support: the producer still imports `fcntl`.
+  - The Claude Code plugin's vendored copy (`plugins/claude_code_dist`)
+    is unchanged; it picks this up at the next tracing release sync.
+
+### Documentation
+
+- **SDK docs and examples match the code (#493, #495)** — `SDK.md` and
+  the example snippets call `get_section()` with section titles, stop
+  reading `.key` / `.value` from `search_memory()` entries, and pass
+  `extract_response_text()` its single argument. The README counts six
+  deployment surfaces, the periodic-materialization README documents the
+  shipped `--backfill` mode, and the `sdk_feature` label lists name all
+  19 values, including `eval-performance` and the four EvalBench labels.
+  The conversational-analytics guide points at its codelab's
+  `agent_analytics_demo` dataset with its own checkpoint key, and the
+  docs index links the `gm scaffold` design page.
+
+### CI and tests (repo side, not in the wheel)
+
+- **Checked-in SDLC working notes are rejected (#490)** — six committed
+  `intent.md` / `plan.md` / `spec.md` files are deleted, `.gitignore`
+  lists those names, and the CI Format check fails if one is committed
+  again.
+- **Categorical retry tests stop sleeping (#491)** — two tests record the
+  backoff instead of waiting it out, saving about four seconds per
+  Python version in the CI matrix. Production retry code is unchanged.
+- **Browser smoke test retries its server port (#497)** — the Looker
+  Studio configurator's `browser_smoke.sh` tries up to five random
+  ports, each verified with a nonce, instead of failing on the first
+  collision. Runs pinned with `SMOKE_PORT` still make one attempt.
+
+### Build locks (repo side, not in the wheel)
+
+- **Hash locks regenerated (#500)** —
+  `deploy/otlp_receiver/pip-tools.lock`,
+  `deploy/otlp_receiver/requirements.lock` and
+  `producers/build-requirements.lock` are replaced with CI's
+  `regen-locks.sh` output to clear upstream PyPI drift. No `.in`,
+  `pyproject.toml`, Dockerfile or script changes.
+
+## [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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bigquery-agent-analytics
-Version: 0.5.2
+Version: 0.5.4
 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
@@ -317,7 +356,7 @@ with a runnable ADK agent.
 | [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 |
 | [Examples](examples/README.md) | Notebooks, SQL scripts, and demos |
-| [Deployment Guides](deploy/README.md) | Four deployment surfaces for Google Cloud |
+| [Deployment Guides](deploy/README.md) | Six deployment surfaces for Google Cloud |
 
 ## Architecture
 

{bigquery_agent_analytics-0.5.2 → bigquery_agent_analytics-0.5.4}/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
@@ -259,7 +283,7 @@ with a runnable ADK agent.
 | [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 |
 | [Examples](examples/README.md) | Notebooks, SQL scripts, and demos |
-| [Deployment Guides](deploy/README.md) | Four deployment surfaces for Google Cloud |
+| [Deployment Guides](deploy/README.md) | Six deployment surfaces for Google Cloud |
 
 ## Architecture