GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 consumer: scope_cardinality view (source_event_id gate, three value columns, fan-out test)

Open
#217 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
47
Forks
21
Avg merge
2d 13h
Merged PRs (30d)
33

Description

Parent tracker: #190 (v15 contract).
Wave: 5 — Consumer views.
Blocked by: #195 (identity stamping), #198 (producer scope), #210 (cross-event deployment plumbing).

## Contract

### Grain
One row per `(JSON_VALUE(attributes, '$.adk.app_name'), user_id, session_id, invocation_id, scope_kind)` where `scope_kind = COALESCE(JSON_VALUE(attributes, '$.adk.scope.kind'), 'unscoped')`.

### Three value columns (correct units)
One ADK `Event` already fans out into multiple BQAA rows on `on_event_callback` (`STATE_DELTA`, HITL, A2A, `AGENT_RESPONSE` co-emit from one source Event). Naive `COUNT(*)` lies about volume:

- `distinct_scope_count = COUNT(DISTINCT JSON_VALUE(attributes, '$.adk.scope.id'))` — cardinality (null/0 for `unscoped`).
- `source_event_count = COUNT(DISTINCT JSON_VALUE(attributes, '$.adk.source_event_id'))` — distinct ADK Events (primary volume metric).
- `row_count = COUNT(*)` — diagnostic only; do not use as primary volume.

### Gate
`WHERE JSON_VALUE(attributes, '$.adk.source_event_id') IS NOT NULL` — **not** `schema_version IS NOT NULL`. The latter lets non-Event-originating callback rows (`USER_MESSAGE_RECEIVED`, before-model, before-tool) through, and they have no meaningful scope. Pre-2.0 rows fall out of the same gate.

## Acceptance

- [ ] Three value columns named and typed as above.
- [ ] Gate uses `source_event_id IS NOT NULL`.
- [ ] **Fan-out test**: one source Event emitting two BQAA rows (e.g. `STATE_DELTA + AGENT_RESPONSE`) produces `source_event_count = 1, row_count = 2`.
- [ ] Null-safe test: pre-2.0 rows and non-Event-originating v2 rows are both excluded.
- [ ] `'unscoped'` bucket contains only v2 Event-originating rows where ADK emitted `scope = null`.

## References

- #190 (v15 consumer view 6; v13 source_event_id gate; v14 three-column split).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.