GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
Epic: Address Remaining Ontology Platform Gaps (Live Agent Resolution, Advanced Resolvers, SHACL, Spanner/MAKO)
- Dominant language
- Python
- Stars
- 47
- Forks
- 21
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 33
Description
### Description
With the successful implementation of SKOS import support (#57) and runtime entity resolution primitives (#58), the bulk analytics and trace-consumption layers of the SDK are firmly established. However, to fully satisfy the `Ontology_Platform_Requirements_Spec_GCP`.
This epic tracks the implementation of the four remaining architectural gaps to transition from trace consumption to a fully governed, production-scale reasoning engine.
---
### Gap 1: Turn-Time Live Agent Resolution (The Integration Gap)
Feature #58 explicitly scoped out a live-agent integration surface, focusing instead on consumption/analytics over trace data already in BigQuery.
* **Requirement:** We need a separate, agent-facing package (ideally an extension of the ADK) that allows a live agent to invoke the `EntityResolver` protocol at turn-time.
* **Goal:** Enable agents to perform low-latency grounding of brief arguments against the ontology *before* calling a tool, reusing the existing resolution contract but engineered for live inference.
### Gap 2: Advanced LLM & Embedding-Based Resolvers
Currently, the entity resolution primitives only ship with deterministic, SQL-based resolvers (`ExactMatchResolver` and `SynonymResolver`). To handle typos, phrasing drift, and complex cross-language semantics, we need to implement the deferred LLM composition patterns.
* **Requirement:** Promote the **Embedding fuzzy matching (P1)** pattern into core, leveraging compile-time `AI.EMBED` and runtime `ML.DISTANCE`.
* **Requirement:** Implement **LLM disambiguation passes (P2)** using `AI.GENERATE` on ambiguous, multi-match hard cases.
### Gap 3: SHACL Constraints & Validation Service (REQ-ONT-030 to 033)
The current pipeline lacks a managed SHACL validator service to automatically enforce cardinality, datatypes, and closed shapes on every materialization batch.
* **Requirement:** Implement a validator endpoint/Cloud Function that evaluates RDF/Property Graph instances against SHACL shapes.
* **Requirement:** Ensure that validation failures do not result in silent data drops; instead, the system must generate structured violation nodes inside the BigQuery context graph, making them queryable by shape and parent `DecisionPoint`.
### Gap 4: Spanner Graph Backend & MAKO Governance Bridge
To realize the targeted Two-Layer Reference Architecture (Hot Spanner Runtime for <100ms targeting vs. Warm BigQuery Analytics for deep lineage), the infrastructure must bridge both environments.
* **Requirement (Epic B3):** Implement the Spanner Graph backend, including Spanner target configurations in bindings and Spanner DDL emission in the compiler.
* **Requirement (Epic B5):** Build the MAKO Governance Bridge to synchronize the two layers. This must include temporal `EVOLVED_FROM` replication from Spanner's active negotiations into BigQuery's immutable decision lineage tables to support regulatory auditing (DSA/GDPR).
---
### Proposed Acceptance Criteria
- [ ] ADK extension published allowing live agents to execute sub-50ms resolution queries against the concept index.
- [ ] `EmbeddingResolver` added to core, alongside compilation flags to generate embedding labels.
- [ ] Managed SHACL validator service deployed, emitting `Violation` nodes directly into the Context Graph upon constraint failure.
- [ ] Epic B3 and B5 completed: Spanner DDL generation is supported, and the MAKO bridge successfully replicates `EVOLVED_FROM` temporal edges from Spanner to BigQuery.
Contributor guide
Assessment
This issue has not been assessed yet.