bigquery-agent-analytics 0.3.2__tar.gz → 0.3.4__tar.gz

bigquery_agent_analytics-0.3.4/.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.2 → bigquery_agent_analytics-0.3.4}/.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.2 → bigquery_agent_analytics-0.3.4}/.github/workflows/producers-ci.yml

@@ -19,11 +19,13 @@ on:
     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:
@@ -49,10 +51,10 @@ jobs:
         run: pip install "pyink>=24.3.0" "isort>=5.0"
 
       - name: isort --check
-        run: isort --check-only src/ tests/
+        run: isort --check-only src/ tests/ scripts/
 
       - name: pyink --check
-        run: pyink --check src/ tests/
+        run: pyink --check src/ tests/ scripts/
 
   test:
     name: Producers test (Python ${{ matrix.python-version }})
@@ -91,7 +93,19 @@ jobs:
       - name: Build sdist and wheel
         run: python -m build
 
-      - name: List artifacts
+      - 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

bigquery_agent_analytics-0.3.4/.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.2 → bigquery_agent_analytics-0.3.4}/.github/workflows/release.yml

@@ -18,10 +18,20 @@ 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
-    runs-on: ubuntu-latest
+    if: startsWith(github.event.release.tag_name, 'v')
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
 
@@ -54,7 +64,7 @@ jobs:
   publish-pypi:
     name: Publish to PyPI
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     environment: pypi
     permissions:
       id-token: write
@@ -70,7 +80,7 @@ jobs:
   publish-testpypi:
     name: Publish to TestPyPI
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     environment: testpypi
     permissions:
       id-token: write

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.4}/CHANGELOG.md

@@ -7,6 +7,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-06-10
+
+### Release highlights
+
+Consume the graph you already deployed. `bqaa context-graph --graph <name>`
+reads your property graph's definition back from BigQuery's
+`INFORMATION_SCHEMA.PROPERTY_GRAPHS` and derives the ontology + binding from
+it plus the live table schemas — no SQL file is passed to (or staged for) the
+materializer. You deploy the graph with standard `bq` DDL once; from then on
+the deployed graph is the single source of truth, so what you query with GQL
+and what gets materialized can never drift apart. The docs (codelab, blog,
+scheduled-deploy runbook, guides) now teach this flow exclusively.
+
+### Added
+
+- **Deployed-graph (`--graph`) materialization mode** — point the
+  materializer at a property graph that already exists in BigQuery instead of
+  a local DDL file. Available on every surface: `bqaa context-graph --graph`
+  (CLI; accepts a bare name resolved in `--dataset-id`, or qualified
+  `dataset.graph` / `project.dataset.graph`),
+  `run_materialize_window(graph=...)` (Python API), `BQAA_GRAPH` (scheduled
+  `run_job.py`), `deploy_cloud_run_job.sh --graph`, and the Terraform
+  module's `graph` variable. The SDK fetches the normalized `CREATE PROPERTY
+  GRAPH` statement from the dataset-qualified
+  `INFORMATION_SCHEMA.PROPERTY_GRAPHS` view and feeds the existing
+  schema-derive pipeline; a missing graph fails with an error that lists the
+  graphs the dataset does contain. In deployed-graph deploys nothing is
+  staged into the image and the entity-table bootstrap is skipped (the
+  graph's existence proves its node/edge tables exist). Mutually exclusive
+  with `--property-graph` and `--ontology`/`--binding`; incompatible with
+  `--extraction-mode=compiled-only` (no reference extractors are staged in
+  derived mode).
+
+### Changed
+
+- **Docs teach only the deployed-graph flow.** The codelab (+ regenerated
+  Colab notebook), blog post, scheduled Context Graph deploy runbook, the
+  Conversational Analytics-first guide, and the example READMEs now apply the
+  table DDL + `CREATE PROPERTY GRAPH` to BigQuery as the one-time deploy step
+  and materialize with `--graph` / `BQAA_GRAPH` / `graph =`. The file-based
+  `--property-graph` mode from 0.3.3 keeps working for existing scripts and
+  images but is no longer documented; prefer `--graph`.
+
+## [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

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.4}/PKG-INFO

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

{bigquery_agent_analytics-0.3.2 → bigquery_agent_analytics-0.3.4}/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 |