Release 0.5.2: EvalBench snapshots, G1 taxonomy, unified evaluators

[caohy1988]

Summary

Version bump 0.5.1 → 0.5.2 plus the changelog cut for everything merged since v0.5.1 (2026-08-29), 19 commits. Two files: pyproject.toml and CHANGELOG.md.

In the wheel: the versioned EvalBench import pipeline — immutable (job_id, import_version) snapshots with the W0.4 failed-session contract, the version-pinned evalbench_failed_sessions view, and bq-agent-sdk evalbench-score (#451/#452/#453); the native agent_events snapshot writer that needs no EvalBench tables (#464); failure_taxonomy frozen at G1 v0.1.0 and the span-level span_taxonomy localisation layer, persisted on the native snapshot via --span-labels-table (#467/#470); evaluator API unification behind PerformanceEvaluator with compatibility aliases for every existing name (#123); canonical metric factories and the opt-in policy_compliance scorecard (#91).

Repo side (labeled sections, not in the wheel): skill-evolution host hooks and auditable patch provenance (#395/#477); the scheduled skill-evolution Cloud Run Job (#472); the OKF adapter example (#474); the AgentForensics Week 0 freeze and sealed preregistration (#435/#473) — the six-week clock has still not started; EvalBench demo, docs, and CLI-discoverability follow-ups (#454–#457, #468); dashboard_v2 browserslist bump (#476).

Changelog entries added in this cut because the Unreleased section did not have them: #91, #123 (its free-standing bullets move under Changed with the PR number), #395, #472, #474, #476. Every other bullet is carried verbatim under a ## [0.5.2] - 2026-09-05 header with a new Release highlights paragraph, and ## [Unreleased] is left empty as in the 0.5.1 cut.

Release steps after merge

1. Squash-merge; the tag goes on the squash-merge commit, and only on it.
2. Resolve that commit's SHA and target it explicitly — never main, which keeps moving and would let a later merge ride into the tag, the wheel, and the PyPI upload:

   BQAA_RELEASE_SHA=$(gh pr view 478 \
     --repo GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK \
     --json mergeCommit --jq '.mergeCommit.oid')
   gh release create v0.5.2 \
     --repo GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK \
     --target "$BQAA_RELEASE_SHA" \
     --generate-notes

   Publishing fires release.yml (build → version check → PyPI + TestPyPI, in parallel).
3. Approve the pypi environment deployment when the workflow pauses on it.
4. Confirm pip index versions bigquery-agent-analytics (or the PyPI page) shows 0.5.2.

Test plan

• python -m build on this branch produces bigquery_agent_analytics-0.5.2-py3-none-any.whl and the sdist; pyproject version equals the v0.5.2 tag minus the v, which is the check release.yml performs
• git diff --check
• Full test suite on this branch: 4938 passed, 73 skipped

[caohy1988]

Full fresh review at d18f8dc

P1 - Pin the release tag to the squash-merge commit

The two release steps do not currently enforce the same contract:

1. Step 1 says the tag goes on the merge commit.
2. Step 2 runs gh release create v0.5.2 --target main --generate-notes.

Because v0.5.2 does not exist yet, gh release create creates it from the state of the named target when the command runs. main is a moving branch. If another PR merges after #478 and before this command, the 0.5.2 tag, wheel, sdist, and PyPI upload will include that later commit instead of the reviewed release commit. The workflow builds the release tag (actions/checkout in .github/workflows/release.yml:41), so its version check does not catch this drift. PyPI publication then makes the mistake effectively immutable.

Please change step 2 to resolve and use the exact merge SHA after the squash merge. For example:

BQAA_RELEASE_SHA=$(gh pr view 478 \
  --repo GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK \
  --json mergeCommit --jq '.mergeCommit.oid')

gh release create v0.5.2 \
  --repo GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK \
  --target "$BQAA_RELEASE_SHA" \
  --generate-notes

gh release create --help explicitly accepts either a branch or a full commit SHA for --target. The full SHA makes the stated release boundary enforceable.

What I verified

• The release range from v0.5.1 through current main is exactly the 19 merged PR commits listed by the release, and the changelog maps the wheel, repo-only, examples, and infrastructure changes correctly.
• The version is 0.5.2; no stale packaging/runtime 0.5.1 constant exists. Remaining references are compatibility documentation/tests or the deploy job's intentional lower bound.
• An exact-tree clean build produced bigquery_agent_analytics-0.5.2-py3-none-any.whl and the 0.5.2 sdist. Both pass twine check; wheel metadata, console entry points, RECORD, and the advertised modules are present.
• The larger sdist is not a new release regression: 0.5.2 is 28,889,424 bytes versus 28,478,976 bytes when rebuilding v0.5.1 with the same toolchain.
• A generated-notes preview from v0.5.1 to this head includes all 19 merged PRs.
• The PR's Python 3.10-3.14 matrix, format, browser smoke, package build, action scans, and CLA check are now green. The checked test result is 4,938 passed / 73 skipped.
• The force-updated head d18f8dc has the same tree as the initially reviewed cb1316d, so the earlier artifact inspection remains exact.

No code, package-content, versioning, or changelog correctness findings beyond the release-target race above.

Verdict: Ready with this release-procedure fix. I am not marking LGTM until the command targets the exact merge commit.

[caohy1988]

Review: Approve

Verified the cut end to end. This is accurate and complete.

Completeness — 19/19 commits since v0.5.1 represented. git rev-list --count v0.5.1..origin/main is exactly 19 (tag = 3fb6a00, 2026-08-29, as stated). Every commit maps to a changelog bullet; the one exclusion (#456, a docs/changelog chore whose deliverable is already the #451 bullet) is justified. No bullet claims work that didn't merge; the closed-unmerged #462/#465 are cited only as docs-consolidation sources, which is worded accurately.

Accuracy spot-checks all pass. Verified against the merged code: the EvalBench pipeline (lock sentinel, (job_id, import_version) keying, W0.4 contract, evalbench_failed_sessions view, both CLI commands), the native snapshot writer with the reserved-name guard, span_taxonomy accepting only the frozen names + --span-labels-table, PerformanceEvaluator with all four compat aliases still exported, the four #91 metric factories, skill_evolution.py's __all__/error_analyst_fn/incumbent_score/patch provenance, the Cloud Run job, the OKF adapter, the #473 sealed fixture (sealed: true, clock_started: false — matches the bullet exactly), and the browserslist bump. The moved #123 sub-bullets are character-identical to the originals.

Version handling matches the 0.5.1 precedent. pyproject.toml is the only pin for the root SDK (no __version__; producers derive via importlib); the remaining "0.5.1" strings in evalbench.py are historical contract comments, correctly untouched. release.yml's version check compares pyproject vs tag-minus-v, so 0.5.2 == 0.5.2 will pass.

Release steps match the workflow. release.yml triggers on release: [published] with a v-prefix guard; tag on the squash-merge commit is the v0.5.1 pattern; the pypi environment has required reviewers (approval step is real), testpypi has none. Note: PyPI and TestPyPI publish in parallel, not TestPyPI-first — existing design, not a regression.

CI: all green across Python 3.10–3.14; BLOCKED is solely the missing approving review. Head is up to date with main.

One cosmetic nit, optional: the #395/#397 bullets describe scripts/skill_evolution.py (repo-side — the wheel ships only src/bigquery_agent_analytics + src/bigquery_ontology) but sit under plain ### Added, while the same cut created ### Deploy (repo side, not in the wheel) for #472. The highlights paragraph's "Around the wheel" phrasing mostly covers it. Not blocking.

After merge: squash → gh release create v0.5.2 --target main --generate-notes → approve the pypi environment → sanity-check the published PyPI version reads 0.5.2.

Review by @caohy1988's assistant (Kimi Code CLI).

[caohy1988]

Both reviews addressed at 8c78039.

P1 — release target race. Agreed: --target main tags whatever main holds when the command runs, and the workflow builds from the tag, so a merge landing between the squash and the release command would ship in the wheel unreviewed. The PR body's release steps now resolve the squash-merge SHA with gh pr view 478 --json mergeCommit and pass that full SHA to gh release create --target, exactly as proposed, with a final step to confirm the published PyPI version reads 0.5.2. That is also the command I will run.

Nit — skill-evolution bullets under Added. Taken. The #395 and #397 entries now sit in their own ### Skill evolution (repo side, not in the wheel) section, matching the Deploy section this cut already uses for #472. Bullet text is unchanged; only the heading moved. pyproject.toml and everything else in the cut are untouched, so the built artifacts are the same as the ones already inspected.