GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
Distribute tracing package and Claude Code plugin
- Dominant language
- Python
- Stars
- 47
- Forks
- 21
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 33
Description
## Context
PR #232 adds the shared `producers/` tracing package scaffold and writer/drainer. The next distribution milestone is to make this usable by Claude Code users: publish the Python tracing package and ship a Claude Code plugin artifact that can run hooks and drain rows without requiring a separate tracing-wheel install in the hook runtime.
This tracks the work after #232 lands. It is a follow-up to #229.
## Goals
- Publish `bigquery-agent-analytics-tracing` from `producers/` as its own package.
- Add the Claude Code hook producer surface to the tracing package.
- Build a Claude Code plugin artifact that vendors the tracing package source at release time.
- Ensure the vendored plugin can execute hook -> spool -> drainer -> BigQuery without `bigquery-agent-analytics-tracing` installed on `BQAA_PYTHON`.
- Prepare the plugin for marketplace submission.
## Proposed work
1. Add `bigquery_agent_analytics_tracing.claude_code`
- Port the existing Claude Code hook event parsing and entrypoint.
- Preserve current default agent/source semantics.
- Keep `attributes.writer` package-owned and preserve caller metadata under non-reserved keys.
- Preserve environment controls including `BQAA_TRACE_ENABLED`, `BQAA_PYTHON`, BigQuery destination vars, dry-run, auto-create flags, and writer label.
2. Add plugin artifact build
- Generate the plugin artifact from source rather than maintaining a second vendored copy.
- Copy `src/bigquery_agent_analytics_tracing/` into the plugin artifact during build.
- Propagate `importlib.metadata.version("bigquery-agent-analytics-tracing")` into plugin metadata where applicable, with `0.0.0+local` fallback for dev/vendored runs.
3. Make vendored drainer invocation explicit
- For wheel installs: use `python -m bigquery_agent_analytics_tracing.drain`.
- For vendored plugin installs: either inject the vendored package root into `PYTHONPATH` on the spawned drainer env, or ship a tiny `bqaa_drain_entry.py` wrapper inside the plugin artifact.
- Test that the drainer succeeds from a hook running under the vendored plugin with no tracing wheel installed.
4. Add distribution workflows
- Add a producer-package publish workflow separate from the root SDK release workflow.
- Use package-specific tags, for example `tracing-v0.1.0`, or another maintainer-approved versioning trigger.
- Publish to TestPyPI first, then PyPI.
- Upload the Claude Code plugin artifact from the same version/build.
5. Marketplace readiness
- Add plugin metadata and install/setup guidance.
- Keep `/bqaa-setup` headless/dry-run behavior separate from interactive Claude Code slash-command behavior.
- Document runtime prerequisites: `BQAA_PYTHON` must have `google-cloud-bigquery`; Storage Write path additionally needs the storage extra dependencies.
## Acceptance criteria
- `pip install bigquery-agent-analytics-tracing` exposes the shared logger/drainer package.
- Claude Code plugin artifact installs without requiring a separate tracing-wheel install.
- Hook -> spool -> drainer works from the vendored plugin path with `BQAA_TRACE_ENABLED=true`.
- `BQAA_TRACE_ENABLED=false` cleanly disables emission.
- Dry-run mode writes the expected rows without BigQuery access.
- CI builds the wheel/sdist and plugin artifact.
- TestPyPI smoke install passes before PyPI publish.
- Plugin artifact is ready for Claude Code marketplace submission.
## Non-goals
- Do not add new top-level BigQuery columns for this distribution step.
- Do not emit ADK-only event types from Claude Code producers.
- Do not require users to manually keep a vendored plugin copy in sync with the PyPI package.
Contributor guide
Assessment
This issue has not been assessed yet.