GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
A2A joint lineage: cross-ontology concept alignment (was 129d)
- Dominant language
- Python
- Stars
- 47
- Forks
- 21
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 33
Description
## Why
Follow-up from [#129](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/129). The A2A joint lineage demo extracts business entities (`MediaEntity`, `PlanningDecision`, `DecisionOption`, etc.) using one ontology on both the caller side and the receiver side. In the demo, both agents share the same domain vocabulary because they're in the same project and use the same SDK extractor.
In production cross-organization deployments, the caller and receiver are **separate orgs with separate ontologies**. Org A's "audience" may map to Org B's "segment"; Org A's "Consumer Banking" may map to Org B's `skos_RetailBanking`. Without cross-ontology concept alignment, the auditor can stitch the trace at the A2A correlation IDs but cannot answer queries like "show me every audience-related decision across both orgs" — the names don't match.
This issue tracks the cross-ontology mapping layer that closes that gap.
## Scope
### Build on existing primitives
[PR #92](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/92) already shipped the **concept index**: `gm compile --emit-concept-index` writes a SKOS-aware lookup table per ontology with `compile_id` / `compile_fingerprint` provenance. [Issue #58](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/issues/58)'s reader follow-on resolves user-typed inputs to canonical entity names within **one** ontology via `skos:altLabel` matching.
This issue extends the reader to **traverse `skos:closeMatch` / `skos:exactMatch` across schemes** so an auditor's query against Org A's vocabulary returns matching entities from Org B's vocabulary too.
### Concrete deliverables
- [ ] Extend the `OntologyRuntime` reader (the post-#58 surface) to take a list of concept-index tables (one per participating ontology) and resolve user input by walking `skos:closeMatch` / `skos:exactMatch` annotations across them.
- [ ] Define the cross-scheme mapping ontology pattern: a small "bridge" SKOS file that declares `skos:exactMatch` triples between Org A's `skos_*` URIs and Org B's `skos_*` URIs. The bridge is itself an ontology compiled into a third concept-index table.
- [ ] Demo extension (or new sibling demo) showing two orgs with deliberately different vocabularies (`audience` vs `segment`, `Consumer Banking` vs `Retail Banking`) and a bridge ontology that aligns them.
- [ ] BigQuery Studio block: "show me every audience/segment-related decision across both orgs," where the user types one term and the resolver returns matches from both vocabularies via the bridge.
### Acceptance criteria
- [ ] `OntologyRuntime` resolver returns matches across multiple concept indexes when a `skos:exactMatch` / `skos:closeMatch` triple exists in the bridge.
- [ ] Match score reflects the chain length (direct match > one-hop bridge > multi-hop).
- [ ] Demo proves the auditor can ask one question and get answers spanning two orgs' divergent vocabularies.
- [ ] DESIGN.md covers the bridge-ontology pattern and the maintenance contract (who owns the bridge — the auditor? a neutral third party?).
## Out of scope
- Auto-suggestion of `skos:closeMatch` candidates (that's an LLM-as-judge problem, not a resolver problem).
- Probabilistic / fuzzy alignment beyond what SKOS predicates already express.
- IAM enforcement on the bridge ontology (covered in the cross-org IAM follow-up).
## Related
- Issue #129 — implementation contract for the three merged PRs (#132, #133, #135, #136).
- Issue #58 — single-ontology concept resolver; this follow-up extends to multi-ontology.
- PR #92 — concept-index emission (already shipped).
- Companion follow-ups: receiver-side task_id propagation, cross-org IAM/redaction fixture.
Contributor guide
Assessment
This issue has not been assessed yet.