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

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

@@ -31,7 +31,7 @@ jobs:
   build:
     name: Build package
     if: startsWith(github.event.release.tag_name, 'v')
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
 
@@ -64,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
@@ -80,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.3 → bigquery_agent_analytics-0.3.4}/CHANGELOG.md

@@ -7,6 +7,49 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigquery-agent-analytics
-Version: 0.3.3
+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.3 → bigquery_agent_analytics-0.3.4}/docs/blog/periodic_materialization.md

@@ -67,7 +67,7 @@ bqaa seed-events \
 
 ### Step 2: Define the context graph
 
-Declare the graph shape once, in standard SQL. This models the decision flow: requests, the options each request weighed, the committed outcome, and the edges that connect them.
+Declare the graph shape once, in standard SQL, and run it in BigQuery. This models the decision flow: requests, the options each request weighed, the committed outcome, and the edges that connect them. The deployed graph becomes the single source of truth — the materializer in the next step reads this definition back from BigQuery's `INFORMATION_SCHEMA.PROPERTY_GRAPHS`.
 
 ```sql
 CREATE OR REPLACE PROPERTY GRAPH agent_analytics.agent_decisions_graph
@@ -98,12 +98,12 @@ CREATE OR REPLACE PROPERTY GRAPH agent_analytics.agent_decisions_graph
 
 ### Step 3: Extract context graph from agent traces
 
-A single command reads the raw `agent_events` and populates the graph tables. It derives what to extract directly from the property graph you defined in Step 2: `bqaa context-graph` reads that `CREATE PROPERTY GRAPH` definition and the schemas of the tables it references, so the property-graph schema is the only thing you author — no separate ontology or binding file. For local development, run the materializer once:
+A single command reads the raw `agent_events` and populates the graph tables. It derives what to extract directly from the graph you deployed in Step 2: `bqaa context-graph` reads the `CREATE PROPERTY GRAPH` definition back from `INFORMATION_SCHEMA.PROPERTY_GRAPHS` along with the schemas of the tables it references, so the property-graph schema is the only thing you author — no SQL file handed to the materializer, no separate ontology or binding file. For local development, run the materializer once:
 
 ```bash
 bqaa context-graph \
     --project-id "$PROJECT_ID" --dataset-id "$DATASET" \
-    --property-graph property_graph.sql \
+    --graph agent_decisions_graph \
     --lookback-hours 24
 ```
 

{bigquery_agent_analytics-0.3.3 → bigquery_agent_analytics-0.3.4}/docs/codelabs/periodic_materialization.md

@@ -188,7 +188,7 @@ Duration: 02:00
 
 The codelab needs just two ready-to-use artifacts: the **table DDL** (the physical graph tables) and the **property-graph schema** (`CREATE PROPERTY GRAPH`). You do not author either yourself; the codelab uses them as-is, and the [README in the artifacts folder](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/codelab/periodic_materialization/README.md) explains how to adapt them for your own decision domain.
 
-The property-graph schema is the single source of truth for *what* the graph contains. `bqaa context-graph` reads it (plus your table schemas) to figure out which entities and relationships to extract and where to write them — so you do **not** need to write a separate ontology or binding file.
+The property-graph schema is the single source of truth for *what* the graph contains. You apply it to BigQuery once; from then on the **deployed graph itself is the contract**: `bqaa context-graph` reads the graph's definition back from BigQuery's `INFORMATION_SCHEMA.PROPERTY_GRAPHS` (plus your table schemas) to figure out which entities and relationships to extract and where to write them — so you do **not** need to write a separate ontology or binding file, and no SQL file is ever passed to the materializer.
 
 This codelab is self-contained: the cell below writes the two artifacts into a working directory, so there is nothing to download. They are the same files shipped in [`examples/codelab/periodic_materialization/`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/codelab/periodic_materialization).
 
@@ -299,7 +299,7 @@ DecisionRequest --[evaluatesOption]--> DecisionOption
 `DecisionRequest` is the question the agent received. `DecisionOption` is one alternative the agent considered. `DecisionOutcome` records the committed choice and the rationale.
 
 > aside positive
-> **Advanced: bring your own ontology + binding.** Schema-derived mode covers the common case. When you need finer control — human-readable descriptions to steer the AI extraction prompt, entity inheritance, derived (computed) properties, or column renames — author an explicit `ontology.yaml` + `binding.yaml` and pass `--ontology`/`--binding` instead of `--property-graph`. The [artifacts folder](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/codelab/periodic_materialization) ships both files as a starting point.
+> **Advanced: bring your own ontology + binding.** Schema-derived mode covers the common case. When you need finer control — human-readable descriptions to steer the AI extraction prompt, entity inheritance, derived (computed) properties, or column renames — author an explicit `ontology.yaml` + `binding.yaml` and pass `--ontology`/`--binding` instead of `--graph`. The [artifacts folder](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/codelab/periodic_materialization) ships both files as a starting point.
 
 ## Apply the property graph schema
 
@@ -316,7 +316,7 @@ envsubst < property_graph.sql | bq query --use_legacy_sql=false
 
 You should see five `CREATE TABLE` results and one `CREATE PROPERTY GRAPH` result. The DDL is idempotent; you can re-run it safely.
 
-That is the only schema work you do. Because `bqaa context-graph` derives what to extract from this property graph, there is no separate binding file to render — the `${PROJECT_ID}` / `${DATASET}` markers in `property_graph.sql` are resolved for you from `--project-id` / `--dataset-id` when you materialize.
+That is the only schema work you do — and the only time the SQL files are used. BigQuery now records your graph's definition, and `bqaa context-graph` reads it back from `INFORMATION_SCHEMA.PROPERTY_GRAPHS` by name, so there is no separate binding file to render and no SQL file to pass to the materializer. What you query with GQL and what gets materialized can never drift apart: they are the same deployed graph.
 
 ## Generate sample agent events
 
@@ -406,7 +406,7 @@ The 10 orphaned sessions never emitted `AGENT_COMPLETED`, so the default `bqaa c
 
 Duration: 05:00
 
-`bqaa context-graph` reads the raw `agent_events`, then **derives what to extract directly from your property graph**: it reads the `CREATE PROPERTY GRAPH` definition you applied in *Apply the property graph schema* and the schemas of the tables it references, works out the entities, relationships, and column types, and populates the graph tables. Point it at `property_graph.sql` with `--property-graph` — no separate ontology or binding file required.
+`bqaa context-graph` reads the raw `agent_events`, then **derives what to extract directly from your deployed graph**: it reads the `CREATE PROPERTY GRAPH` definition you applied in *Apply the property graph schema* back from BigQuery's `INFORMATION_SCHEMA.PROPERTY_GRAPHS`, joins it with the schemas of the tables it references, works out the entities, relationships, and column types, and populates the graph tables. Point it at the deployed graph by name with `--graph` — no SQL file, no separate ontology or binding file.
 
 **Run the materializer** locally:
 
@@ -415,7 +415,7 @@ Duration: 05:00
 bqaa context-graph \
     --project-id "$PROJECT_ID" \
     --dataset-id "$DATASET" \
-    --property-graph ~/bqaa-codelab/property_graph.sql \
+    --graph agent_decisions_graph \
     --lookback-hours 24 \
     --format json
 ```
@@ -577,7 +577,7 @@ TO=$(date -u -d "8 hours ago" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null \
 bqaa context-graph \
     --project-id "$PROJECT_ID" \
     --dataset-id "$DATASET" \
-    --property-graph ~/bqaa-codelab/property_graph.sql \
+    --graph agent_decisions_graph \
     --lookback-hours 1 \
     --backfill --from "$FROM" --to "$TO" \
     --state-key-suffix codelab_backfill_demo \
@@ -592,10 +592,10 @@ os.environ["TO"]   = (now - datetime.timedelta(hours=8)).strftime("%Y-%m-%dT%H:%
 print(f"Backfill window FROM = {os.environ['FROM']}")
 print(f"Backfill window TO   = {os.environ['TO']}")
 
-!cd ~/bqaa-codelab && bqaa context-graph \
+!bqaa context-graph \
     --project-id "$PROJECT_ID" \
     --dataset-id "$DATASET" \
-    --property-graph property_graph.sql \
+    --graph agent_decisions_graph \
     --lookback-hours 1 \
     --backfill --from "$FROM" --to "$TO" \
     --state-key-suffix codelab_backfill_demo \
@@ -639,7 +639,7 @@ The local run you completed in *Materialize the decision graph* uses default beh
 * **Bound the per-run batch size** (`--max-sessions`). Useful when an upstream event spike threatens to overwhelm a single scan.
 
 > aside positive
-> **From "run this once" to "run this every six hours":** The SDK ships a deploy script and a Terraform module that wrap `bqaa context-graph` as a Cloud Run Job triggered by Cloud Scheduler, with least-privilege service accounts and the IAM grants the job needs. Follow the [scheduled Context Graph deploy runbook](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/guides/scheduled-context-graph-deploy.md) to take *this* `--property-graph` graph to a scheduled deploy with the same one-artifact flow, or the [periodic-materialization deployment guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/context_graph/periodic_materialization) for the full IAM matrix and the explicit-ontology/binding path.
+> **From "run this once" to "run this every six hours":** The SDK ships a deploy script and a Terraform module that wrap `bqaa context-graph` as a Cloud Run Job triggered by Cloud Scheduler, with least-privilege service accounts and the IAM grants the job needs. Follow the [scheduled Context Graph deploy runbook](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/guides/scheduled-context-graph-deploy.md) to take *this* deployed graph to a scheduled deploy with the same `--graph` flow, or the [periodic-materialization deployment guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/context_graph/periodic_materialization) for the full IAM matrix and the explicit-ontology/binding path.
 
 ## Clean up
 
@@ -667,7 +667,7 @@ Duration: 02:00
 
 Congratulations! You've turned raw agent event logs into a queryable Context Graph in BigQuery and traced a single decision end-to-end, with no external graph database or ETL pipeline.
 
-The same pattern applies wherever an agent makes consequential decisions: credit underwriting, prior authorization, marketing budget moves, procurement, customer service, and internal IT. To build your own decision graph, copy the codelab artifacts as a starting point and adapt the two declarative files (table DDL + the `CREATE PROPERTY GRAPH` schema) to your domain — `bqaa context-graph --property-graph` derives the rest. Reach for an explicit `ontology.yaml` + `binding.yaml` only when you need descriptions, inheritance, derived properties, or column renames.
+The same pattern applies wherever an agent makes consequential decisions: credit underwriting, prior authorization, marketing budget moves, procurement, customer service, and internal IT. To build your own decision graph, copy the codelab artifacts as a starting point, adapt the two declarative files (table DDL + the `CREATE PROPERTY GRAPH` schema) to your domain, and apply them to BigQuery — `bqaa context-graph --graph` reads the deployed graph and derives the rest. Reach for an explicit `ontology.yaml` + `binding.yaml` only when you need descriptions, inheritance, derived properties, or column renames.
 
 #### What you've learned
 

{bigquery_agent_analytics-0.3.3 → bigquery_agent_analytics-0.3.4}/docs/guides/conversational-analytics-first.md

@@ -36,8 +36,8 @@ an audit artifact.
 already followed the
 [Periodic Materialization codelab](../codelabs/periodic_materialization.md)
 through materialization, so that your project has: the dataset created, the
-graph-table DDL applied, and the `agent_decisions_graph` property graph defined
-(`property_graph.sql`). That setup is about ten minutes and is not repeated
+graph-table DDL applied, and the `agent_decisions_graph` property graph
+deployed to BigQuery. That setup is about ten minutes and is not repeated
 here.
 
 With the codelab setup in place, the only two commands specific to this guide
@@ -52,11 +52,13 @@ bqaa seed-events \
     --project-id "$PROJECT_ID" --dataset-id "$DATASET" \
     --scenario decision-realistic --seed 42
 
-# 2. Materialize the decision graph from the events. --lookback-hours 80
-#    covers the corpus's 72-hour spread so every completed session is captured.
+# 2. Materialize the decision graph from the events. The materializer reads
+#    the deployed graph's definition back from INFORMATION_SCHEMA.PROPERTY_GRAPHS.
+#    --lookback-hours 80 covers the corpus's 72-hour spread so every completed
+#    session is captured.
 bqaa context-graph \
     --project-id "$PROJECT_ID" --dataset-id "$DATASET" \
-    --property-graph property_graph.sql \
+    --graph agent_decisions_graph \
     --lookback-hours 80
 ```
 

{bigquery_agent_analytics-0.3.3 → bigquery_agent_analytics-0.3.4}/docs/guides/scheduled-context-graph-deploy.md

@@ -1,10 +1,13 @@
-# Deploy a Context Graph on a schedule — one artifact
+# Deploy a Context Graph on a schedule — consume the deployed graph
 
 This runbook takes the [Periodic Materialization codelab](../codelabs/periodic_materialization.md)
 graph from a local run to a **hands-off scheduled production deploy**, using the
-schema-derived (`--property-graph`) flow: you ship one `property_graph.sql` (plus
-its companion `table_ddl.sql`) and the Cloud Run Job derives the ontology +
-binding from it — no hand-written `ontology.yaml` / `binding.yaml`.
+deployed-graph (`--graph`) flow: you create the property graph in BigQuery once
+(standard `bq` DDL), and the Cloud Run Job reads the graph's definition back
+from `INFORMATION_SCHEMA.PROPERTY_GRAPHS` on every run and derives the
+ontology + binding from it — no hand-written `ontology.yaml` / `binding.yaml`,
+and no SQL file shipped in the image. The deployed graph is the single source
+of truth: what you query with GQL is exactly what the job materializes.
 
 It's the rename-free / common path. For richer graphs (descriptions to steer the
 AI prompt, entity inheritance, derived properties, column renames, or a
@@ -12,14 +15,15 @@ compiled extractor) keep the explicit `--ontology` / `--binding` path in the
 [context-graph deploy README](../../examples/context_graph/periodic_materialization/README.md),
 which is also the deep reference for IAM, scheduling, monitoring, and teardown.
 
-> Requires `bigquery-agent-analytics >= 0.3.3`.
+> Requires `bigquery-agent-analytics >= 0.3.4`.
 
 ## The shape
 
 ```
 agent_events                run_job.py (Cloud Run Job, every N hrs):
-(your EVENTS dataset)  ───►   1. apply table_ddl.sql  → graph tables exist
-   read-only                  2. derive ontology+binding from property_graph.sql
+(your EVENTS dataset)  ───►   1. read graph DDL from INFORMATION_SCHEMA
+   read-only                     .PROPERTY_GRAPHS (your GRAPH dataset)
+                              2. derive ontology+binding from it
                               3. materialize sessions  → node/edge tables
                                                           (your GRAPH dataset)
                                           │
@@ -29,17 +33,16 @@ agent_events                run_job.py (Cloud Run Job, every N hrs):
 ```
 
 Two datasets, two lifecycles: **events** is read-only (your agents write it);
-**graph** is writable (the job creates the tables, the materialized graph, and
-the state table). `bqaa context-graph --property-graph` resolves the
-`${PROJECT_ID}` / `${DATASET}` placeholders so everything lands in the graph
-dataset while events stay read-only.
+**graph** is writable (you create the tables + the property graph once; the job
+writes the materialized rows and the state table). You deploy the graph schema
+yourself in step 1; from then on the job only ever *reads* the definition.
 
 ## 0. Prerequisites
 
 ```bash
 export PROJECT_ID="your-project"
-export EVENTS_DS="agent_analytics"     # read-only: holds agent_events
-export GRAPH_DS="agent_decisions_graph"  # writable: holds the materialized graph
+export EVENTS_DS="agent_analytics"   # read-only: holds agent_events
+export GRAPH_DS="decision_graph"     # writable: holds the materialized graph
 
 gcloud services enable \
   bigquery.googleapis.com run.googleapis.com cloudscheduler.googleapis.com \
@@ -47,7 +50,7 @@ gcloud services enable \
   aiplatform.googleapis.com --project="$PROJECT_ID"
 ```
 
-`aiplatform.googleapis.com` is needed because schema-derived mode uses
+`aiplatform.googleapis.com` is needed because deployed-graph mode uses
 `AI.GENERATE` extraction (`ai-fallback`). The deploy script grants the runtime
 service account `roles/aiplatform.user` automatically in that mode.
 
@@ -60,46 +63,54 @@ bqaa seed-events --project-id "$PROJECT_ID" --dataset-id "$EVENTS_DS" \
     --scenario decision --sessions 5
 ```
 
-## 1. Your two artifacts
+## 1. Deploy your graph to BigQuery
 
-Schema-derived mode needs exactly two **placeholdered** files. The codelab ships
-both, ready to adapt:
+This is the only schema work you do, and you do it once. The codelab ships
+both DDL files, ready to adapt to your own decision domain:
 
 ```bash
 cp examples/codelab/periodic_materialization/property_graph.sql .
 cp examples/codelab/periodic_materialization/table_ddl.sql .
+
+bq --location=US mk --dataset "$PROJECT_ID:$GRAPH_DS" 2>/dev/null || true
+
+# The files are placeholdered for envsubst; the graph lives in the GRAPH
+# dataset, so render ${DATASET} as $GRAPH_DS. Tables first — CREATE PROPERTY
+# GRAPH rejects references to tables that do not exist yet.
+DATASET="$GRAPH_DS" envsubst < table_ddl.sql      | bq query --use_legacy_sql=false
+DATASET="$GRAPH_DS" envsubst < property_graph.sql | bq query --use_legacy_sql=false
 ```
 
-Both must use `${PROJECT_ID}` / `${DATASET}` (not hardcoded references) — the
-deploy refuses hardcoded artifacts so the scheduled job can never derive against
-the wrong dataset, and `table_ddl.sql` must sit next to `property_graph.sql`.
+BigQuery now records the graph's definition; everything downstream consumes it
+by name (`agent_decisions_graph`) via `INFORMATION_SCHEMA.PROPERTY_GRAPHS`.
+Confirm it's there:
+
+```bash
+bq query --use_legacy_sql=false \
+ "SELECT property_graph_name FROM \`$PROJECT_ID.$GRAPH_DS\`.INFORMATION_SCHEMA.PROPERTY_GRAPHS"
+# → agent_decisions_graph
+```
 
 ## 2. Validate locally before you pay for Cloud Run
 
 Run the job's runtime entrypoint on your laptop against the real datasets — same
-code path the Cloud Run Job runs, no container:
+code path the Cloud Run Job runs, no container, nothing staged:
 
 ```bash
-pip install -e .   # or: pip install 'bigquery-agent-analytics>=0.3.3'
-
-# Stage the runtime + your two artifacts together (mirrors what the deploy
-# script bundles into the image).
-mkdir -p /tmp/cg-deploy && cp \
-  examples/context_graph/periodic_materialization/run_job.py \
-  property_graph.sql table_ddl.sql /tmp/cg-deploy/
+pip install -e .   # or: pip install 'bigquery-agent-analytics>=0.3.4'
 
 BQAA_PROJECT_ID="$PROJECT_ID" \
 BQAA_EVENTS_DATASET_ID="$EVENTS_DS" \
 BQAA_GRAPH_DATASET_ID="$GRAPH_DS" \
-BQAA_PROPERTY_GRAPH="property_graph.sql" \
+BQAA_GRAPH="agent_decisions_graph" \
 BQAA_LOOKBACK_HOURS="72" \
 BQAA_LOCATION="US" \
-python /tmp/cg-deploy/run_job.py
+python examples/context_graph/periodic_materialization/run_job.py
 ```
 
-Expect a JSON report with `"mode": "property-graph"` and
+Expect a JSON report with `"mode": "deployed-graph"` and
 `"sessions_materialized" > 0`. This is the cheapest way to confirm the
-placeholder + split-dataset wiring before deploying.
+graph lookup + split-dataset wiring before deploying.
 
 To validate a specific `AI.GENERATE` model here too, add
 `BQAA_ENDPOINT="gemini-3.5-flash"` to the env block above — the same knob the
@@ -119,15 +130,15 @@ first.
   --project "$PROJECT_ID" --region us-central1 \
   --events-dataset "$EVENTS_DS" --graph-dataset "$GRAPH_DS" \
   --schedule "0 */6 * * *" \
-  --property-graph property_graph.sql \
+  --graph agent_decisions_graph \
   --smoke
 ```
 
 `--smoke` runs the job once after deploy and tails the logs, so you find out
 *now* whether it works. The script builds + publishes the image from local
 source, pre-creates the graph dataset, sets up least-privilege service accounts
-+ IAM, deploys the Cloud Run Job with `BQAA_PROPERTY_GRAPH=property_graph.sql`,
-and wires the Cloud Scheduler trigger. (`--property-graph` is incompatible with
++ IAM, deploys the Cloud Run Job with `BQAA_GRAPH=agent_decisions_graph`,
+and wires the Cloud Scheduler trigger. (`--graph` is incompatible with
 `--extraction-mode=compiled-only`, which the script rejects at the boundary.)
 
 To pick the `AI.GENERATE` extraction model — e.g. a Gemini 3.x model — add
@@ -139,21 +150,20 @@ runtime keeps its `gemini-2.5-flash` default:
   --project "$PROJECT_ID" --region us-central1 \
   --events-dataset "$EVENTS_DS" --graph-dataset "$GRAPH_DS" \
   --schedule "0 */6 * * *" \
-  --property-graph property_graph.sql \
+  --graph agent_decisions_graph \
   --endpoint gemini-3.5-flash \
   --smoke
 ```
 
 ### Option B — Terraform
 
-Terraform takes a published image as input, so build one first with
-`build_image.sh --property-graph` (it stages `property_graph.sql` + the sibling
-`table_ddl.sql` instead of `ontology.yaml`/`binding.yaml`/`reference_extractor.py`):
+Terraform takes a published image as input, so build one first. Deployed-graph
+mode needs nothing staged beyond the runtime, so the default build works as-is:
 
 ```bash
 IMAGE_URI="$(./examples/context_graph/periodic_materialization/build_image.sh \
-  --project "$PROJECT_ID" --repo bqaa --create-repo \
-  --property-graph property_graph.sql)"     # → REGION-docker.pkg.dev/.../...:<tag>
+  --project "$PROJECT_ID" --repo bqaa --create-repo)"
+  # → REGION-docker.pkg.dev/.../...:<tag>
 ```
 
 Then point Terraform at it:
@@ -163,9 +173,9 @@ Then point Terraform at it:
 project_id        = "your-project"
 region            = "us-central1"
 events_dataset_id = "agent_analytics"
-graph_dataset_id  = "agent_decisions_graph"
+graph_dataset_id  = "decision_graph"
 schedule          = "0 */6 * * *"
-property_graph    = true
+graph             = "agent_decisions_graph"
 # endpoint        = "gemini-3.5-flash"   # optional: AI.GENERATE model (BQAA_ENDPOINT)
 ```
 
@@ -179,7 +189,7 @@ terraform init
 terraform apply -var "image_uri=$IMAGE_URI"
 ```
 
-`property_graph = true` sets `BQAA_PROPERTY_GRAPH` on the Job; a plan-time
+`graph = "agent_decisions_graph"` sets `BQAA_GRAPH` on the Job; a plan-time
 precondition rejects it together with `extraction_mode = "compiled-only"`.
 
 ## 4. Verify
@@ -200,7 +210,7 @@ bq query --use_legacy_sql=false \
 ```
 
 The Cloud Logging entry per run is structured JSON; the key fields are
-`mode = "property-graph"`, `sessions_materialized`, `sessions_failed`, and
+`mode = "deployed-graph"`, `sessions_materialized`, `sessions_failed`, and
 `ok`. Wire a Cloud Monitoring alert on `ok = false` (see the
 [deploy README](../../examples/context_graph/periodic_materialization/README.md#cloud-monitoring-alerts)).
 
@@ -209,6 +219,15 @@ exactly as in [Phase 4 of the codelab](../codelabs/periodic_materialization.md).
 
 ## Troubleshooting
 
+**`Property graph ... not found in ... (INFORMATION_SCHEMA.PROPERTY_GRAPHS)`**
+— the job looked for `BQAA_GRAPH` in the graph dataset and didn't find it. The
+error lists the graphs that *do* exist there. Usual causes: step 1 was applied
+to a different dataset than `BQAA_GRAPH_DATASET_ID`, or the `CREATE PROPERTY
+GRAPH` statement failed (its tables didn't exist yet). Re-run step 1 and
+confirm with the `INFORMATION_SCHEMA.PROPERTY_GRAPHS` query shown there. If
+your graph lives in a *different* dataset on purpose, pass a qualified name:
+`--graph other_dataset.agent_decisions_graph`.
+
 **`404 NOT_FOUND ... Publisher Model ... was not found or your project does not
 have access to it`** when you set `--endpoint` / `BQAA_ENDPOINT` to a Gemini 3.x
 model. This is almost always a *location* mismatch, not an access problem:
@@ -221,8 +240,8 @@ project. The runtime's default `gemini-2.5-flash` works without any of this.
 
 ## When to use explicit `--ontology` / `--binding` instead
 
-Schema-derived mode covers rename-free graphs with AI extraction. Reach for the
-explicit pair (omit `--property-graph`; the deploy bundles `ontology.yaml` +
+Deployed-graph mode covers rename-free graphs with AI extraction. Reach for the
+explicit pair (omit `--graph`; the deploy bundles `ontology.yaml` +
 `binding.yaml`) when you need: human-readable descriptions to steer the
 `AI.GENERATE` prompt, entity inheritance, derived (computed) properties, column
 renames, or a deterministic compiled extractor (`--extraction-mode=compiled-only`).

{bigquery_agent_analytics-0.3.3 → bigquery_agent_analytics-0.3.4}/examples/codelab/periodic_materialization/README.md

@@ -6,9 +6,9 @@ These are the artifacts the *Trace AI Agent Decisions with BigQuery Property Gra
 
 | File | Purpose |
 |---|---|
-| `property_graph.sql` | Property-graph DDL. Stitches the node and edge tables into a queryable BigQuery property graph. **This is the single source of truth `bqaa context-graph --property-graph` derives the materialization spec from.** |
+| `property_graph.sql` | Property-graph DDL. Stitches the node and edge tables into a queryable BigQuery property graph. **You apply this to BigQuery once; the deployed graph is then the single source of truth `bqaa context-graph --graph` derives the materialization spec from** (read back via `INFORMATION_SCHEMA.PROPERTY_GRAPHS`). |
 | `table_ddl.sql` | Node and edge table DDL. The materializer writes into these tables every run. |
-| `ontology.yaml` | **Optional override.** Names the entities and relationships; used by the materializer to construct the `AI.GENERATE` extraction prompt. Only needed when you pass `--ontology`/`--binding` instead of `--property-graph`. |
+| `ontology.yaml` | **Optional override.** Names the entities and relationships; used by the materializer to construct the `AI.GENERATE` extraction prompt. Only needed when you pass `--ontology`/`--binding` instead of `--graph`. |
 | `binding.yaml` | **Optional override.** Maps ontology entities to physical BigQuery tables and columns. Must be rendered with `envsubst` before use. Pairs with `ontology.yaml`. |
 | `seed_events.py` | Thin compatibility shim over the maintained `bqaa seed-events` command (SDK module `bigquery_agent_analytics.seed_events`). Writes a small corpus of completed decision sessions so the materializer has something to process. |
 
@@ -18,11 +18,11 @@ These are the artifacts the *Trace AI Agent Decisions with BigQuery Property Gra
 2. `envsubst < table_ddl.sql | bq query --use_legacy_sql=false` creates the node and edge tables.
 3. `envsubst < property_graph.sql | bq query --use_legacy_sql=false` creates the property graph.
 4. `bqaa seed-events --project-id "$PROJECT_ID" --dataset-id "$DATASET" --sessions 5` populates `agent_events` (the bundled `seed_events.py` remains as a compatibility shim if you are running from the downloaded kit).
-5. `bqaa context-graph --project-id "$PROJECT_ID" --dataset-id "$DATASET" --property-graph property_graph.sql --lookback-hours 24` materializes the graph. It derives the entities, relationships, and column types from `property_graph.sql` plus the table schemas — no ontology or binding file required, and the `${PROJECT_ID}` / `${DATASET}` markers are resolved from `--project-id` / `--dataset-id`.
+5. `bqaa context-graph --project-id "$PROJECT_ID" --dataset-id "$DATASET" --graph agent_decisions_graph --lookback-hours 24` materializes the graph. It reads the deployed graph's definition back from `INFORMATION_SCHEMA.PROPERTY_GRAPHS` and derives the entities, relationships, and column types from it plus the table schemas — no SQL file passed to the materializer, no ontology or binding file required.
 
 ### Advanced: explicit ontology + binding
 
-`ontology.yaml` and `binding.yaml` are kept here for when you outgrow schema-derived mode — when you need human-readable descriptions to steer the AI extraction prompt, entity inheritance, derived (computed) properties, or column renames. Render the binding (`envsubst < binding.yaml > binding.rendered.yaml`) and pass `--ontology ontology.yaml --binding binding.rendered.yaml` in place of `--property-graph`.
+`ontology.yaml` and `binding.yaml` are kept here for when you outgrow schema-derived mode — when you need human-readable descriptions to steer the AI extraction prompt, entity inheritance, derived (computed) properties, or column renames. Render the binding (`envsubst < binding.yaml > binding.rendered.yaml`) and pass `--ontology ontology.yaml --binding binding.rendered.yaml` in place of `--graph`.
 
 ## Domain model
 
@@ -37,7 +37,7 @@ DecisionRequest --[evaluatesOption]--> DecisionOption
 
 ## Adapting these for your domain
 
-For a production deployment you author your own versions of just **two** files describing your decision domain; `bqaa context-graph --property-graph` derives the rest:
+For a production deployment you author your own versions of just **two** files describing your decision domain, apply them to BigQuery, and `bqaa context-graph --graph` derives the rest from the deployed graph:
 
 * `property_graph.sql` — `CREATE OR REPLACE PROPERTY GRAPH ... NODE TABLES (...) EDGE TABLES (... SOURCE KEY (...) REFERENCES ... LABEL ...)`.
 * `table_ddl.sql` — `CREATE TABLE IF NOT EXISTS` for each node and edge table, with the SDK metadata columns `session_id` and `extracted_at` included on every bound table.

{bigquery_agent_analytics-0.3.3 → bigquery_agent_analytics-0.3.4}/examples/codelab/periodic_materialization/colab_notebook.ipynb

@@ -208,7 +208,7 @@
     "\n",
     "The codelab needs just two ready-to-use artifacts: the **table DDL** (the physical graph tables) and the **property-graph schema** (`CREATE PROPERTY GRAPH`). You do not author either yourself; the codelab uses them as-is, and the [README in the artifacts folder](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/codelab/periodic_materialization/README.md) explains how to adapt them for your own decision domain.\n",
     "\n",
-    "The property-graph schema is the single source of truth for *what* the graph contains. `bqaa context-graph` reads it (plus your table schemas) to figure out which entities and relationships to extract and where to write them — so you do **not** need to write a separate ontology or binding file.\n",
+    "The property-graph schema is the single source of truth for *what* the graph contains. You apply it to BigQuery once; from then on the **deployed graph itself is the contract**: `bqaa context-graph` reads the graph's definition back from BigQuery's `INFORMATION_SCHEMA.PROPERTY_GRAPHS` (plus your table schemas) to figure out which entities and relationships to extract and where to write them — so you do **not** need to write a separate ontology or binding file, and no SQL file is ever passed to the materializer.\n",
     "\n",
     "This codelab is self-contained: the cell below writes the two artifacts into a working directory, so there is nothing to download. They are the same files shipped in [`examples/codelab/periodic_materialization/`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/codelab/periodic_materialization)."
    ]
@@ -327,7 +327,7 @@
     "\n",
     "`DecisionRequest` is the question the agent received. `DecisionOption` is one alternative the agent considered. `DecisionOutcome` records the committed choice and the rationale.\n",
     "\n",
-    "> **Advanced: bring your own ontology + binding.** Schema-derived mode covers the common case. When you need finer control — human-readable descriptions to steer the AI extraction prompt, entity inheritance, derived (computed) properties, or column renames — author an explicit `ontology.yaml` + `binding.yaml` and pass `--ontology`/`--binding` instead of `--property-graph`. The [artifacts folder](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/codelab/periodic_materialization) ships both files as a starting point.\n",
+    "> **Advanced: bring your own ontology + binding.** Schema-derived mode covers the common case. When you need finer control — human-readable descriptions to steer the AI extraction prompt, entity inheritance, derived (computed) properties, or column renames — author an explicit `ontology.yaml` + `binding.yaml` and pass `--ontology`/`--binding` instead of `--graph`. The [artifacts folder](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/codelab/periodic_materialization) ships both files as a starting point.\n",
     "\n",
     "## Apply the property graph schema\n",
     "\n",
@@ -352,7 +352,7 @@
    "source": [
     "You should see five `CREATE TABLE` results and one `CREATE PROPERTY GRAPH` result. The DDL is idempotent; you can re-run it safely.\n",
     "\n",
-    "That is the only schema work you do. Because `bqaa context-graph` derives what to extract from this property graph, there is no separate binding file to render — the `${PROJECT_ID}` / `${DATASET}` markers in `property_graph.sql` are resolved for you from `--project-id` / `--dataset-id` when you materialize.\n",
+    "That is the only schema work you do — and the only time the SQL files are used. BigQuery now records your graph's definition, and `bqaa context-graph` reads it back from `INFORMATION_SCHEMA.PROPERTY_GRAPHS` by name, so there is no separate binding file to render and no SQL file to pass to the materializer. What you query with GQL and what gets materialized can never drift apart: they are the same deployed graph.\n",
     "\n",
     "## Generate sample agent events\n",
     "\n",
@@ -472,7 +472,7 @@
     "## Materialize the decision graph\n",
     "\n",
     "\n",
-    "`bqaa context-graph` reads the raw `agent_events`, then **derives what to extract directly from your property graph**: it reads the `CREATE PROPERTY GRAPH` definition you applied in *Apply the property graph schema* and the schemas of the tables it references, works out the entities, relationships, and column types, and populates the graph tables. Point it at `property_graph.sql` with `--property-graph` — no separate ontology or binding file required.\n",
+    "`bqaa context-graph` reads the raw `agent_events`, then **derives what to extract directly from your deployed graph**: it reads the `CREATE PROPERTY GRAPH` definition you applied in *Apply the property graph schema* back from BigQuery's `INFORMATION_SCHEMA.PROPERTY_GRAPHS`, joins it with the schemas of the tables it references, works out the entities, relationships, and column types, and populates the graph tables. Point it at the deployed graph by name with `--graph` — no SQL file, no separate ontology or binding file.\n",
     "\n",
     "**Run the materializer** locally:"
    ]
@@ -483,7 +483,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!bqaa context-graph      --project-id \"$PROJECT_ID\"      --dataset-id \"$DATASET\"      --property-graph ~/bqaa-codelab/property_graph.sql      --lookback-hours 24      --format json"
+    "!bqaa context-graph      --project-id \"$PROJECT_ID\"      --dataset-id \"$DATASET\"      --graph agent_decisions_graph      --lookback-hours 24      --format json"
    ]
   },
   {
@@ -658,10 +658,10 @@
     "print(f\"Backfill window FROM = {os.environ['FROM']}\")\n",
     "print(f\"Backfill window TO   = {os.environ['TO']}\")\n",
     "\n",
-    "!cd ~/bqaa-codelab && bqaa context-graph \\\n",
+    "!bqaa context-graph \\\n",
     "    --project-id \"$PROJECT_ID\" \\\n",
     "    --dataset-id \"$DATASET\" \\\n",
-    "    --property-graph property_graph.sql \\\n",
+    "    --graph agent_decisions_graph \\\n",
     "    --lookback-hours 1 \\\n",
     "    --backfill --from \"$FROM\" --to \"$TO\" \\\n",
     "    --state-key-suffix codelab_backfill_demo \\\n",
@@ -712,7 +712,7 @@
     "* **Replay a past window** (`--backfill --from / --to`). You exercised this in *Replay a past window* above. The replay is tracked separately from the regular schedule so it cannot interfere with the live refresh.\n",
     "* **Bound the per-run batch size** (`--max-sessions`). Useful when an upstream event spike threatens to overwhelm a single scan.\n",
     "\n",
-    "> **From \"run this once\" to \"run this every six hours\":** The SDK ships a deploy script and a Terraform module that wrap `bqaa context-graph` as a Cloud Run Job triggered by Cloud Scheduler, with least-privilege service accounts and the IAM grants the job needs. Follow the [scheduled Context Graph deploy runbook](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/guides/scheduled-context-graph-deploy.md) to take *this* `--property-graph` graph to a scheduled deploy with the same one-artifact flow, or the [periodic-materialization deployment guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/context_graph/periodic_materialization) for the full IAM matrix and the explicit-ontology/binding path.\n",
+    "> **From \"run this once\" to \"run this every six hours\":** The SDK ships a deploy script and a Terraform module that wrap `bqaa context-graph` as a Cloud Run Job triggered by Cloud Scheduler, with least-privilege service accounts and the IAM grants the job needs. Follow the [scheduled Context Graph deploy runbook](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/guides/scheduled-context-graph-deploy.md) to take *this* deployed graph to a scheduled deploy with the same `--graph` flow, or the [periodic-materialization deployment guide](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/examples/context_graph/periodic_materialization) for the full IAM matrix and the explicit-ontology/binding path.\n",
     "\n",
     "## Clean up\n",
     "\n",
@@ -743,7 +743,7 @@
     "\n",
     "Congratulations! You've turned raw agent event logs into a queryable Context Graph in BigQuery and traced a single decision end-to-end, with no external graph database or ETL pipeline.\n",
     "\n",
-    "The same pattern applies wherever an agent makes consequential decisions: credit underwriting, prior authorization, marketing budget moves, procurement, customer service, and internal IT. To build your own decision graph, copy the codelab artifacts as a starting point and adapt the two declarative files (table DDL + the `CREATE PROPERTY GRAPH` schema) to your domain — `bqaa context-graph --property-graph` derives the rest. Reach for an explicit `ontology.yaml` + `binding.yaml` only when you need descriptions, inheritance, derived properties, or column renames.\n",
+    "The same pattern applies wherever an agent makes consequential decisions: credit underwriting, prior authorization, marketing budget moves, procurement, customer service, and internal IT. To build your own decision graph, copy the codelab artifacts as a starting point, adapt the two declarative files (table DDL + the `CREATE PROPERTY GRAPH` schema) to your domain, and apply them to BigQuery — `bqaa context-graph --graph` reads the deployed graph and derives the rest. Reach for an explicit `ontology.yaml` + `binding.yaml` only when you need descriptions, inheritance, derived properties, or column renames.\n",
     "\n",
     "#### What you've learned\n",
     "\n",