bigquery-agent-analytics 0.3.1__tar.gz → 0.3.3__tar.gz

bigquery_agent_analytics-0.3.3/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "bqaa-tracing",
+  "description": "Claude Code tracing plugins for BigQuery Agent Analytics.",
+  "owner": {
+    "name": "Google LLC",
+    "url": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK"
+  },
+  "plugins": [
+    {
+      "name": "bigquery-agent-analytics-tracing",
+      "description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
+      "version": "0.1.0",
+      "source": "./plugins/claude_code_dist/bigquery-agent-analytics-tracing",
+      "author": {
+        "name": "Google LLC"
+      },
+      "homepage": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/plugins/claude_code",
+      "repository": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK",
+      "license": "Apache-2.0",
+      "keywords": [
+        "bigquery",
+        "agent-analytics",
+        "observability",
+        "tracing",
+        "claude-code"
+      ]
+    }
+  ]
+}

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/.github/workflows/ci.yml

@@ -41,12 +41,18 @@ jobs:
       - name: Run autoformat and check for changes
         run: |
           bash autoformat.sh
-          if ! git diff --exit-code src/ tests/ examples/; then
+          if ! git diff --exit-code src/ tests/ examples/ scripts/; then
             echo ""
             echo "::error::Code is not formatted. Run 'bash autoformat.sh' and commit the changes."
             exit 1
           fi
 
+      - name: Check codelab notebook is in sync with markdown source
+        run: |
+          python scripts/generate_colab_from_codelab.py --check \
+            docs/codelabs/periodic_materialization.md \
+            examples/codelab/periodic_materialization/colab_notebook.ipynb
+
   test:
     name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest

bigquery_agent_analytics-0.3.3/.github/workflows/producers-ci.yml

@@ -0,0 +1,114 @@
+# 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: Producers CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'producers/**'
+      - 'plugins/claude_code/**'
+      - '.github/workflows/producers-ci.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'producers/**'
+      - 'plugins/claude_code/**'
+      - '.github/workflows/producers-ci.yml'
+
+concurrency:
+  group: producers-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: producers
+
+jobs:
+  format:
+    name: Producers format check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install formatting tools
+        run: pip install "pyink>=24.3.0" "isort>=5.0"
+
+      - name: isort --check
+        run: isort --check-only src/ tests/ scripts/
+
+      - name: pyink --check
+        run: pyink --check src/ tests/ scripts/
+
+  test:
+    name: Producers test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    name: Producers build
+    runs-on: ubuntu-latest
+    needs: [format, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: List wheel/sdist
+        run: ls -la dist/
+
+      - name: Install built wheel for plugin build
+        # Make `importlib.metadata.version` resolve correctly so the
+        # plugin manifest gets a real version stamped in, not the
+        # pyproject fallback.
+        run: pip install dist/bigquery_agent_analytics_tracing-*.whl
+
+      - name: Build Claude Code plugin artifact
+        run: python scripts/build_claude_plugin.py
+
+      - name: List plugin artifact
+        run: ls -la dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: producers-dist
+          path: producers/dist/

bigquery_agent_analytics-0.3.3/.github/workflows/release-tracing.yml

@@ -0,0 +1,220 @@
+# 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.
+
+# Release the `bigquery-agent-analytics-tracing` package and the
+# Claude Code plugin tarball.
+#
+# Trigger: push a `tracing-vX.Y.Z` tag whose version matches
+# `producers/pyproject.toml`'s `[project].version`. The tag namespace
+# is distinct from the root `vX.Y.Z` tags used by the consumption SDK
+# so the two release pipelines never collide.
+#
+# Pipeline:
+#   verify          - tag matches pyproject; run producer tests on 3.12
+#   build           - wheel + sdist + Claude Code plugin tarball
+#   github-release  - attach all artifacts to the GitHub release for
+#                     this tag, with auto-generated release notes
+#   publish-testpypi - upload wheel + sdist to TestPyPI via Trusted
+#                      Publishing (no secrets)
+#   publish-pypi    - same, to PyPI (gated by the `pypi` environment
+#                     so maintainers can require manual approval)
+#
+# Trusted Publishing setup (one-time, on the PyPI side):
+#   - https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+#   - Project: bigquery-agent-analytics-tracing
+#   - Owner:   GoogleCloudPlatform
+#   - Repo:    BigQuery-Agent-Analytics-SDK
+#   - Workflow: release-tracing.yml
+#   - Environment: testpypi / pypi (match the `environment:` blocks
+#     below). Until the project + trusted publisher are configured on
+#     TestPyPI/PyPI, the publish jobs will fail with a clear error —
+#     `build` and `github-release` still produce + attach artifacts so
+#     the release tag is not blocked.
+
+name: Release tracing
+
+on:
+  push:
+    tags:
+      - 'tracing-v*'
+
+concurrency:
+  group: release-tracing-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify version + tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: producers
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject version
+        id: version
+        run: |
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG="${GITHUB_REF_NAME#tracing-v}"
+          echo "Package version: ${PKG_VERSION}"
+          echo "Release tag:     ${GITHUB_REF_NAME} (extracted: ${TAG})"
+          if [ "${PKG_VERSION}" != "${TAG}" ]; then
+            echo "::error::Version mismatch: producers/pyproject.toml has ${PKG_VERSION} but tag is ${GITHUB_REF_NAME} (expected tracing-v${PKG_VERSION})"
+            exit 1
+          fi
+          echo "version=${PKG_VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Install producers with dev deps
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    name: Build wheel + plugin tarball
+    runs-on: ubuntu-latest
+    needs: verify
+    defaults:
+      run:
+        working-directory: producers
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Install built wheel
+        # importlib.metadata.version() needs to see the dist-info so
+        # build_claude_plugin.py stamps the real version (not the
+        # pyproject fallback). Installing the wheel mirrors the
+        # producers-ci build path exactly.
+        run: pip install dist/bigquery_agent_analytics_tracing-*.whl
+
+      - name: Build Claude Code plugin tarball
+        run: python scripts/build_claude_plugin.py
+
+      - name: Verify all expected artifacts are present
+        run: |
+          ls -la dist/
+          test -f dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}.tar.gz \
+            || (echo "::error::missing sdist" && exit 1)
+          test -f dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}-py3-none-any.whl \
+            || (echo "::error::missing wheel" && exit 1)
+          test -f dist/bigquery-agent-analytics-tracing-claude-code-${{ needs.verify.outputs.version }}.tar.gz \
+            || (echo "::error::missing plugin tarball" && exit 1)
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: producers/dist/
+          if-no-files-found: error
+
+  github-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: [verify, build]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: dist/
+
+      - name: List downloaded artifacts
+        run: ls -la dist/
+
+      - name: Create release with artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "Tracing ${{ github.ref_name }}"
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: |
+            dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}-py3-none-any.whl
+            dist/bigquery_agent_analytics_tracing-${{ needs.verify.outputs.version }}.tar.gz
+            dist/bigquery-agent-analytics-tracing-claude-code-${{ needs.verify.outputs.version }}.tar.gz
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    # Depend on github-release too: the plugin tarball ships ONLY as a
+    # GitHub release asset, so if that step fails we must not let the
+    # wheel/sdist reach PyPI. Otherwise the "wheel and plugin always
+    # go together" invariant from RELEASING.md breaks silently.
+    # publish-pypi inherits the guard transitively via needs: publish-testpypi.
+    needs: [verify, build, github-release]
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/bigquery-agent-analytics-tracing
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: dist/
+
+      - name: Strip non-PyPI artifacts
+        # The plugin tarball is a release artifact, not a PyPI
+        # distribution. Filename uses hyphens in
+        # 'bigquery-agent-analytics-tracing-claude-code-*' so it's
+        # distinguishable from the underscore-named sdist.
+        run: |
+          rm -f dist/bigquery-agent-analytics-tracing-claude-code-*.tar.gz
+          ls -la dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [verify, publish-testpypi]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bigquery-agent-analytics-tracing
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-tracing-dist
+          path: dist/
+
+      - name: Strip non-PyPI artifacts
+        run: |
+          rm -f dist/bigquery-agent-analytics-tracing-claude-code-*.tar.gz
+          ls -la dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/.github/workflows/release.yml

@@ -18,9 +18,19 @@ on:
   release:
     types: [published]
 
+# The release event has no tag-pattern filter, so any published
+# release fires this workflow. The producer pipeline publishes
+# `tracing-vX.Y.Z` releases (release-tracing.yml); without this
+# guard, every producer release would also trigger root SDK
+# publishing and fail version verification.
+#
+# Root SDK tags use the plain `vX.Y.Z` pattern; producer tags use
+# `tracing-vX.Y.Z`. Only the root pattern starts with literal `v`,
+# so this is an unambiguous boundary.
 jobs:
   build:
     name: Build package
+    if: startsWith(github.event.release.tag_name, 'v')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/.gitignore

@@ -11,11 +11,20 @@ build/
 .venv/
 venv/
 env/
+.adk/
 uv.lock
+.env
 
 # Script outputs
 scripts/reports/
 
+# Example run artifacts
+examples/*/reports/
+examples/*/reports_*/
+examples/*/trials_*/
+scripts/**/*.log
+examples/**/*.log
+
 # Local workspace metadata
 .code*/
 deploy/streaming_evaluation/.streaming_evaluation_state.json

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/CHANGELOG.md

@@ -7,6 +7,193 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-06-08
+
+### Release highlights
+
+Schema-derived Context Graph materialization, end to end. `bqaa context-graph
+--property-graph property_graph.sql` now derives the ontology + binding from the
+property graph plus live table schemas, so rename-free graphs need no
+hand-written `ontology.yaml` / `binding.yaml` — and the same one-artifact flow
+reaches the scheduled production path (Cloud Run deploy script, image builder,
+`run_job.py`, and the Terraform module), with a split read-only-events /
+writable-graph dataset contract. Explicit `--ontology` / `--binding` is retained
+as the advanced override for descriptions, inheritance, derived properties,
+renames, and the migration-v5 compiled-extractor path.
+
+### Added
+
+- **Schema-derived (`--property-graph`) materialization, local → production**
+  (local: [#277](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/277)
+  via [#278](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/278)–[#281](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/281),
+  [#285](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/285),
+  [#287](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/287);
+  deploy: [#286](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/286)
+  via [#288](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/288)–[#292](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/292))
+  — `bqaa context-graph --property-graph property_graph.sql` derives the ontology
+  + binding from the property graph + live table schemas, so no hand-written
+  `ontology.yaml` / `binding.yaml` is needed for rename-free graphs. Scheduled
+  production reaches parity: the Cloud Run deploy script, image builder,
+  `run_job.py` (`BQAA_PROPERTY_GRAPH`), and the Terraform module all accept the
+  one-artifact flow (placeholdered `property_graph.sql` + sibling
+  `table_ddl.sql`), with a split read-only-events / writable-graph contract
+  (events read-only; graph tables + `_bqaa_materialization_state` land in the
+  graph dataset). Explicit `--ontology`/`--binding` is preserved as the advanced
+  override (descriptions, inheritance, derived properties, renames, the
+  migration-v5 compiled extractor).
+- **Selectable `AI.GENERATE` extraction model**
+  ([#298](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/298))
+  — choose the model for the `ai-fallback` extraction across every surface:
+  `run_materialize_window(endpoint=...)` (Python API), `bqaa context-graph
+  --endpoint` (CLI), and `BQAA_ENDPOINT` for the scheduled `run_job.py` deploy.
+  Short names resolve to the Vertex `locations/global` publisher URL, so Gemini
+  3.x models such as `gemini-3.5-flash` work. Defaults to `gemini-2.5-flash`
+  everywhere, so existing callers are unaffected; ignored under
+  `--extraction-mode=compiled-only` (no AI call is made).
+
+### Fixed
+
+- **`run_job.py` table-DDL bootstrap mis-split on statement boundaries**
+  ([#286](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/286))
+  — `_bootstrap_entity_tables` split the DDL on `;` without accounting for
+  comments or quoting, so a `;` inside a `--` comment (e.g. the codelab
+  `table_ddl.sql`'s "materializer fills automatically; they are required")
+  produced a comment-only fragment BigQuery rejected with "Unexpected end of
+  statement" — and a `;` or `--` inside a string literal
+  (`OPTIONS(description="has; semicolon")`, `DEFAULT 'a;b'`) or a backtick
+  identifier could corrupt a customer's DDL. Replaced with a quote- and
+  comment-aware splitter: it strips `--` line comments and `/* */` block
+  comments and splits on `;` only at the top level (never inside `'`, `"`, or
+  `` ` `` quoting). Found by a live `--property-graph` deploy smoke.
+
+### Changed
+
+- **Renamed the context-graph example for product-facing clarity**
+  ([#282](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/282))
+  — `examples/migration_v5/` → `examples/context_graph/` (the `migration_v5`
+  label was internal milestone bookkeeping). The scheduled-deploy entrypoints
+  move with it (`examples/context_graph/periodic_materialization/...`). The
+  demo's default BigQuery dataset is now `context_graph` (was `migration_v5_demo`)
+  and the Terraform example's graph dataset is `context_graph` (was
+  `migration_v5_graph`). The user-facing docs (blog, codelab, runbook, deploy +
+  Terraform READMEs) now lead with the one-artifact `property_graph.sql` path as
+  primary and frame explicit `ontology.yaml` / `binding.yaml` as the advanced
+  override. The previously executed demo notebook is archived as
+  `examples/_archive/context_graph_historical_notebook.ipynb`. **Action for
+  users:** update any deep links to `examples/migration_v5/...` and any reference
+  to the `migration_v5_demo` dataset.
+
+## [0.3.2] - 2026-05-22
+
+### Release highlights
+
+The migration-v5 production track lands the design-partner asks from
+[#187](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/187)
+end-to-end: backfill mode, compiled-only extraction (with zero-LLM
+guarantee), explicit FK→PK mapping that re-enables MAKO self-edges,
+an opt-in orphan-session watchdog, the Beat 5 feedback / reward
+loop in both the demo and the live notebook, hardened deploy
+defaults (split SAs + tunable retries), and a Terraform module
+mirroring the bash deploy. The migration-v5 cron path is now
+complete for audit-critical production deployments.
+
+### Added
+
+- **Backfill mode for `materialize_window`** ([#188](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/188),
+  closes [#177](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/177))
+  — `bqaa-materialize-window --backfill --from / --to --state-key-suffix`
+  runs a one-shot historical window with isolated state-table
+  rows (the suffix folds into the `state_key` hash, so backfill
+  rows can't advance the steady-state cron checkpoint).
+- **Compiled-only extraction mode + deploy path** ([#192](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/192),
+  [#193](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/193),
+  closes [#178](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/178))
+  — `--extraction-mode=compiled-only` routes the orchestrator
+  through structured extractors only, never calls `AI.GENERATE`,
+  surfaces uncovered spans as typed `empty_extraction` failures
+  with sample diagnostics. The deploy script (`#193`) stages
+  `reference_extractor.py` into the container, wires
+  `BQAA_REFERENCE_EXTRACTORS_MODULE`, and makes
+  `roles/aiplatform.user` conditional (idempotently removes the
+  grant when transitioning an existing ai-fallback deploy to
+  compiled-only). `TestCompiledOnlyMakesZeroLLMCalls` proves the
+  zero-LLM contract.
+- **Explicit FK→PK mapping for binding columns** ([#191](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/191),
+  [#222](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/222),
+  closes [#179](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/179))
+  — `from_columns` / `to_columns` accept `list[dict[str, str]]`
+  shape (`[{src_decision_execution_id: id}]`) in addition to the
+  legacy `list[str]`. Materializer, validators, and the PG DDL
+  compiler consume the canonical
+  `ResolvedRelationship.from_column_mapping`. MAKO's
+  `evolvedFrom` / `supersededBy` self-edges are re-added to the
+  migration v5 binding.
+- **Orphan-session watchdog** ([#224](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/224),
+  closes [#180](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/180))
+  — opt-in via `--max-session-age-hours N`. Each cron pass scans
+  for sessions whose first event is older than the cutoff but
+  which never emitted `AGENT_COMPLETED`; flags them as
+  `session_orphaned` failures and records the running set in the
+  state table (`mode='orphan_scan'` + `mode='orphan_ledger'`
+  rows). Strict `>` watermark, explicit timestamp-bound partition
+  pruning on the resolved-orphan probe.
+- **Migration v5 Beat 5 — feedback / reward loop** ([#227](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/227),
+  [#228](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/228),
+  closes [#181](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/181),
+  [#184](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/184),
+  [#185](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/185))
+  — demo scope grows from 6 → 11 entities and 9 → 14
+  relationships. Adds `BusinessConstraint`,
+  `ConstraintApplication`, `RejectionReason`, `OutcomeSignal`,
+  `RewardComputation` + their edges. The demo agent emits four
+  new tools (`apply_constraint`, `record_rejection`,
+  `record_outcome_signal`, `compute_reward`); the reference
+  extractor covers all four; the notebook's new Beat 5 cells run
+  the two payoff GQL traversals end-to-end against a live
+  BigQuery scratch dataset (29 / 29 cells executed, counts 1–29,
+  6 unique reward rows + 8 unique rejection rows verified live).
+- **Split runtime + scheduler-caller SAs by default** ([#230](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/230),
+  closes [#182](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/182))
+  — `deploy_cloud_run_job.sh` creates two SAs by default:
+  `bqaa-periodic-runtime-sa` (BigQuery + Vertex AI roles) and
+  `bqaa-periodic-scheduler-sa` (only `roles/run.invoker` on the
+  job). `--single-sa` is the escape hatch for the pre-#182
+  combined identity. Least-privilege: scheduler-caller never
+  needs BigQuery permissions.
+- **Tunable `--max-retries` on Cloud Run Job** ([#230](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/230),
+  closes [#183](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/183))
+  — default 2 (was hard-coded 1). The orchestrator's session-
+  level idempotency + append-only state table make additional
+  retries safe. The retry count flows into `BQAA_MAX_RETRIES` on
+  the job's env so the runtime's startup log surfaces it in
+  `jsonPayload.max_retries` — operators correlating Cloud
+  Monitoring alert noise with retry behaviour see the policy
+  without `gcloud run jobs describe`.
+- **Terraform module for periodic materialization** ([#231](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/231),
+  closes [#186](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/186))
+  — `examples/migration_v5/periodic_materialization/terraform/`
+  mirrors the bash deploy's resources (graph dataset, both SAs,
+  IAM bindings, Cloud Run v2 Job, Scheduler trigger) with
+  defaults matching `deploy_cloud_run_job.sh`'s post-#230
+  surface. New `build_image.sh` helper produces the staging
+  layout the runtime needs. Image build/publish are intentionally
+  outside the module — `var.image_uri` takes the published
+  container image. `var.manage_apis` enables the required APIs
+  on a clean project; `var.deletion_protection` matches the bash
+  deploy's lifecycle. Live-verified end-to-end against
+  `test-project-0728-467323`.
+
+### Fixed
+
+- **Orphan-watchdog empty-array streaming-insert crash hotfix** ([#225](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/225))
+  — BigQuery's streaming-insert API rejects empty
+  `ARRAY<STRING>` values with `Field value of
+  flagged_session_ids cannot be empty.`. Pre-fix, every cron
+  pass after [#224](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/224)
+  crashed at insert time. Fix: omit nullable columns from the
+  `insert_rows_json` payload when their value is `None` or
+  empty.
+
 ## [0.3.1] - 2026-05-18
 
 ### Release highlights

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigquery-agent-analytics
-Version: 0.3.1
+Version: 0.3.3
 Summary: SDK for analyzing and evaluating agent traces stored in BigQuery.
 Author: Google LLC
 License-Expression: Apache-2.0

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/autoformat.sh

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

{bigquery_agent_analytics-0.3.1 → bigquery_agent_analytics-0.3.3}/docs/README.md

@@ -61,7 +61,7 @@ architecture, rationale, and implementation plans behind key SDK features.
 
 | Document | Description |
 |----------|-------------|
-| [Migration v5 periodic materialization playbook](../examples/migration_v5/periodic_materialization/README.md) | Customer deployment path for keeping the MAKO migration v5 graph fresh on a schedule: local dry-run, Cloud Run Job + Cloud Scheduler deploy with `--smoke`, IAM matrix, schedule guidance, JSON log shape, Cloud Monitoring alert filters, state-table inspection, cleanup, and troubleshooting. |
+| [Context Graph periodic materialization playbook](../examples/context_graph/periodic_materialization/README.md) | Customer deployment path for keeping the MAKO context graph fresh on a schedule: local dry-run, Cloud Run Job + Cloud Scheduler deploy with `--smoke`, IAM matrix, schedule guidance, JSON log shape, Cloud Monitoring alert filters, state-table inspection, cleanup, and troubleshooting. |
 | [proposal_bigquery_agent_cli.md](proposal_bigquery_agent_cli.md) | CLI proposal and command design |
 | [python_udf_support_design.md](python_udf_support_design.md) | BigQuery Python UDF architecture |
 | [remote_function_rationale.md](remote_function_rationale.md) | Cloud Run remote function rationale |