feat(synthetic-llm-dataflow-bigquery): synthetic data generation solution guide (v0.6.1)

[albertols]

What this changes

The synthetic data generation solution guide, generated from release
v0.6.1 (edcfdcd6a621) of its source repository.

Path	Content
pipelines/synthetic-llm-dataflow-bigquery/	Beam pipeline (uv workspace: sdfb-core, sdfb-beam, tests), the standalone evaluator (packages/sdfb-evaluation: its own uv project, lock and tests), Dockerfile, Flex Template metadata, launch scripts 01–06, one design document (docs/DESIGN.md) that maps every decision the code cites
terraform/synthetic-llm-dataflow-bigquery/	Service accounts, Artifact Registry, bucket, thelook_ecommerce snapshots, landing tables with the public schemas, one table per config/bq_schema file, the evaluator's four tables and two views from its own schema files, optional Flex Template job, generated scripts/00_set_variables.sh
use_cases/Synthetic_Data_Generation.md	Solution guide page, plus one row in each repository index

Pipeline

bigquery-public-data.thelook_ecommerce ── terraform snapshot ──▶ synthetic_source
  └─ Flex Template launcher: relationship model → users ▸ orders ▸ order_items
      └─ Dataflow NVIDIA L4 (G2, dtype auto) or T4 (N1, float16, Qwen only) workers: reference sample → vLLM value pools (bounded) → vectorized rows
          ├─ BigQuery synthetic_data            (landing, FKs valid by construction)
          ├─ BigQuery synthetic_data_quality    (dlq, validation_runs, fk_fanout_stats)
          └─ BigQuery synthetic_rag             (rag_chunks, freetext_pools, source_table_stats)
  └─ 06: same template, sdfb_job=evaluation, CPU workers: landed tables vs synthetic_source
      └─ BigQuery synthetic_data_quality        (evaluation_* tables, evaluation_latest views)

Security guardrails

• --disable-public-ips, with --subnetwork only when Terraform was given one (plus roles/compute.networkUser on it)
• Dedicated launcher/worker and Cloud Build service accounts; no default compute account
• Model weights staged once to GCS; no model hub or external LLM API at runtime (HF_HUB_OFFLINE=1)
• Public, ungated model repositories staged by Cloud Build: no credentials in Terraform, scripts or state
• apache-beam[gcp]==2.76.0 matches the apache/beam_python3.14_sdk:2.76.0 base image

Also in this PR

None.

Changes in the source repository for this release

🚀 Added

• The Dataflow Solution Guides copy ships the evaluator, and can run it (ADR 0040, ADR 0041). dsg/manifest.yaml now includes packages/sdfb-evaluation (source with the metric catalogue and schemas, its own pyproject.toml, uv.lock and Python pin, its README and docs, and its tests), so the guide's image carries the evaluator. Not shipped: the one evaluator test that reads the Composer DAGs, and the GUI (gui/, scripts/gui/), which the use-case page links in the source repository. The root side of the evaluator's golden parity test ships with it. New scripts/06_run_evaluation.sh RUN_ID [GENERATION_JOB_ID] launches the same Flex Template with sdfb_job=evaluation on CPU workers, the way the generation DAG's chained evaluation does (seed_table=order_items, the public FK model, scope=manual, reference_rows_limit=10000, validation_runs_table, the generation job's id, disk_size_gb=200, an e2-standard-8 launcher); it finds the job by its name sdfb-RUN_ID and refuses one that is not done. Terraform creates the four evaluation_* tables in synthetic_data_quality from the evaluator's own schema files, partitioned and clustered as sdfb-eval schemas does, and the views evaluation_latest and evaluation_latest_per_job from its views.sql; the Dataflow service account needs no new role (dataflow.developer covers the job-window read; bigquery.tables.deleteSnapshot is not granted, so the source pin degrades to an unpinned read with a warning). The README header, the use-case page, the Terraform README, the index rows and the PR template describe step 6. The sync now also retitles the licence header where a shipped file quotes it (views.sql's -- block, the parity fixture that embeds the models' text), and the shipped evaluator modules carry their docs/DESIGN.md line. The guide's row in the DSG README.md index now matches upstream verbatim (Beta :factory:, the maintainers' status) instead of setting Ready. Not yet run on Google Cloud.

🔧 Changed

• Preflight step 13j looks only for the deployment's one template (sdfb-<version>-template.json, sdfb-latest-template.json, or any sdfb-*-template.json) and, when none is there, names the build that makes it: docker/flex_template_metadata.json on the image of docker/Dockerfile.
• The launch-surface tests split the one parameter file without importing each other's package: the generator's suite holds that every parameter is a generator flag, sdfb_job, disk_size_gb or one whose help text starts "Evaluation only"; the evaluator's suite checks every such parameter and every sdfb-eval run flag a launch can supply against its own parser, and its Beam and Python pins against docker/Dockerfile.
• The evaluator's documentation, rewritten for a first reader. packages/sdfb-evaluation/README.md is now a short page: what the evaluator is, how the one image and template carry and dispatch it (docker/Dockerfile, docker/flex_entry.py, docker/flex_template_metadata.json), and four ways to use it (on your machine, on Dataflow, from Composer, step 6 of the Dataflow Solution Guides copy), each with one diagram or command. The detail moved, re-checked against the code, into packages/sdfb-evaluation/docs/: CLI.md (every command and flag as --help prints it, exit codes, an offline trial), DATAFLOW.md (launch parameters, the read path, the launcher's 12 minutes, the reference panel under the temp location), COMPOSER.md (the chained and the standalone DAG) and RESULTS.md (tables, views, registry, baselines, noise floors, lifts, thresholds). A new packages/sdfb-evaluation/GUI.md describes the self-hosted GUI for evaluations, which stays in the source repository. Statements that were no longer true were dropped: the evaluator-only template and the standalone image, "never parsed by Airflow", and a chain diagram that showed run_evaluation false by default. docs/DESIGN.md §11 says the same.

🗑️ Removed

• packages/sdfb-evaluation/docker/ (the evaluator's standalone CPU image and its entrypoint, which no script built) and packages/sdfb-evaluation/deploy/ (an optional evaluator-only template: its metadata and build script). The evaluator is deployed only through the repository's one image and one template, and docker/flex_template_metadata.json is the one file that declares the template's parameters (ADR 0041, note of 2026-10-15). Nothing deployed changes.

📗 Docs

• ADR 0041, note of 2026-10-15 (one parameter file, and how the two test suites split it); the evaluation design's §8.2; docs/DEPLOYMENT_PREREQUISITES.md (Evaluator, step 13j); the standalone evaluation DAG's header.

Testing

Gates run by scripts/dsg/sync.py against this branch, mirroring .github/workflows/pull_request.yml:

Gate	Result	Seconds
precheck	✅	11
pylintrc-parity	✅	0
python-version	✅	0
headers	✅	0
links	✅	0
bash -n	✅	0
yapf + pylint	✅	232
terraform	✅	77
python build (pipenv + sdist + pytest)	✅	528

Important

Not yet run in Google Cloud for this sync. The gates above are local and CI-equivalent; a live Dataflow run of scripts/04_run_dataflow.sh and scripts/06_run_evaluation.sh is pending.

How this PR is produced

This PR was generated by scripts/dsg/sync.py in the source repository
(https://github.com/albertols/synthetic-llm-dataflow-bigquery); the pipeline README names the release and
commit. Review feedback is applied there and published to this pull request
as a new commit, so the two trees stay identical.