diff --git a/docs/tech-specs/extraction-time-provenance.md b/docs/tech-specs/extraction-time-provenance.md new file mode 100644 index 00000000..2f5761dd --- /dev/null +++ b/docs/tech-specs/extraction-time-provenance.md @@ -0,0 +1,49 @@ +# Extraction-Time Provenance: Source Layer + +## Status + +Notes - Not yet started + +## Overview + +This document captures notes on extraction-time provenance for future specification work. Extraction-time provenance records the "source layer" - where data came from originally, how it was extracted and transformed. + +This is separate from query-time provenance (see `query-time-provenance.md`) which records agent reasoning. + +## Current State + +Source metadata is already partially stored in the knowledge graph (~40% solved): +- Documents have source URLs, timestamps +- Some extraction metadata exists + +## Scope + +Extraction-time provenance should capture: + +### Source Layer (Origin) +- URL / file path +- Retrieval timestamp +- Funding sources +- Authorship / authority +- Document metadata (title, date, version) + +### Transformation Layer (Extraction) +- Extraction tool used (e.g., PDF parser, table extractor) +- Extraction method / version +- Confidence scores +- Raw-to-structured mapping +- Parent-child relationships (PDF → table → row → fact) + +## Key Questions for Future Spec + +1. What metadata is already captured today? +2. What gaps exist? +3. How to structure the extraction DAG? +4. How does query-time provenance link to extraction-time nodes? +5. Storage format - RDF triples? Separate schema? + +## References + +- Query-time provenance: `docs/tech-specs/query-time-provenance.md` +- PROV-O standard for provenance modeling +- Existing source metadata in knowledge graph (needs audit) diff --git a/docs/tech-specs/query-time-provenance.md b/docs/tech-specs/query-time-provenance.md new file mode 100644 index 00000000..06bfaf70 --- /dev/null +++ b/docs/tech-specs/query-time-provenance.md @@ -0,0 +1,282 @@ +# Query-Time Provenance: Agent Explainability + +## Status + +Draft - Gathering Requirements + +## Overview + +This specification defines how the agent framework records and communicates provenance during query execution. The goal is full explainability: tracing how a result was obtained, from final answer back through reasoning steps to source data. + +Query-time provenance captures the "inference layer" - what the agent did during reasoning. It connects to extraction-time provenance (source layer) which records where facts came from originally. + +## Terminology + +| Term | Definition | +|------|------------| +| **Provenance** | The record of how a result was derived | +| **Provenance Node** | A single step or artifact in the provenance DAG | +| **Provenance DAG** | Directed Acyclic Graph of provenance relationships | +| **Query-time Provenance** | Provenance generated during agent reasoning | +| **Extraction-time Provenance** | Provenance from data ingestion (source metadata) - separate spec | + +## Architecture + +### Two Provenance Contexts + +1. **Extraction-time** (out of scope for this spec): + - Generated when data is ingested (PDF extraction, web scraping, etc.) + - Records: source URL, extraction method, timestamps, funding, authorship + - Already partially implemented via source metadata in knowledge graph + - See: `docs/tech-specs/extraction-time-provenance.md` (notes) + +2. **Query-time** (this spec): + - Generated during agent reasoning + - Records: tool invocations, retrieval results, LLM reasoning, final conclusions + - Links to extraction-time provenance for retrieved facts + +### Provenance Flow + +``` +Agent Session + │ + ├─► Tool: Knowledge Query + │ │ + │ ├─► Retrieved Fact A ──► [link to extraction provenance] + │ └─► Retrieved Fact B ──► [link to extraction provenance] + │ + ├─► LLM Reasoning Step + │ │ + │ └─► "Combined A and B to conclude X" + │ + └─► Final Answer + │ + └─► Derived from reasoning step above +``` + +### Storage + +- Provenance stored in knowledge graph infrastructure +- Segregated in a **separate collection** for distinct retrieval patterns +- Query-time provenance references extraction-time provenance nodes via IRIs +- Persists beyond agent session (reusable, auditable) + +### Real-Time Streaming + +Provenance events stream back to the client as the agent works: + +1. Agent invokes tool +2. Tool generates provenance data +3. Provenance stored in graph +4. Provenance event sent to client +5. UX builds provenance visualization incrementally + +## Provenance Node Structure + +Each provenance node represents a step in the reasoning process. + +### Node Identity + +Provenance nodes are identified by IRIs containing UUIDs, consistent with the RDF-style knowledge graph: + +``` +urn:trustgraph:prov:550e8400-e29b-41d4-a716-446655440000 +``` + +### Core Fields + +| Field | Description | +|-------|-------------| +| `id` | IRI with UUID (e.g., `urn:trustgraph:prov:{uuid}`) | +| `session_id` | Agent session this belongs to | +| `timestamp` | When this step occurred | +| `type` | Node type (see below) | +| `derived_from` | List of parent node IRIs (DAG edges) | + +### Node Types + +| Type | Description | Additional Fields | +|------|-------------|-------------------| +| `retrieval` | Facts retrieved from knowledge graph | `facts`, `source_refs` | +| `tool_invocation` | Tool was called | `tool_name`, `input`, `output` | +| `reasoning` | LLM reasoning step | `prompt_summary`, `conclusion` | +| `answer` | Final answer produced | `content` | + +### Example Provenance Nodes + +```json +{ + "id": "urn:trustgraph:prov:550e8400-e29b-41d4-a716-446655440001", + "session_id": "urn:trustgraph:session:7c9e6679-7425-40de-944b-e07fc1f90ae7", + "timestamp": "2024-01-15T10:30:00Z", + "type": "retrieval", + "derived_from": [], + "facts": [ + { + "id": "urn:trustgraph:fact:9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", + "content": "Swallow airspeed is 8.5 m/s" + } + ], + "source_refs": ["urn:trustgraph:extract:1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"] +} +``` + +```json +{ + "id": "urn:trustgraph:prov:550e8400-e29b-41d4-a716-446655440002", + "session_id": "urn:trustgraph:session:7c9e6679-7425-40de-944b-e07fc1f90ae7", + "timestamp": "2024-01-15T10:30:01Z", + "type": "reasoning", + "derived_from": ["urn:trustgraph:prov:550e8400-e29b-41d4-a716-446655440001"], + "prompt_summary": "Asked to determine average swallow speed", + "conclusion": "Based on retrieved data, average speed is 8.5 m/s" +} +``` + +## Provenance Events + +Events streamed to the client during agent execution. + +### Design: Lightweight Reference Events + +Provenance events are lightweight - they reference provenance nodes by IRI rather than embedding full provenance data. This keeps the stream efficient while allowing the client to fetch full details if needed. + +A single agent step may create or modify multiple provenance objects. The event references all of them. + +### Event Structure + +```json +{ + "provenance_refs": [ + "urn:trustgraph:prov:550e8400-e29b-41d4-a716-446655440001", + "urn:trustgraph:prov:550e8400-e29b-41d4-a716-446655440002" + ] +} +``` + +### Integration with Agent Response + +Provenance events extend `AgentResponse` with a new `chunk_type: "provenance"`: + +```json +{ + "chunk_type": "provenance", + "content": "", + "provenance_refs": ["urn:trustgraph:prov:..."], + "end_of_message": false +} +``` + +This allows provenance updates to flow alongside existing chunk types (`thought`, `observation`, `answer`, `error`). + +## Tool Provenance Reporting + +Tools report provenance as part of their execution. + +### Minimum Reporting (all tools) + +Every tool can report at minimum: +- Tool name +- Input arguments +- Output result + +### Enhanced Reporting (tools that can describe more) + +Tools that understand their internals can report: +- What sources were consulted +- What reasoning/transformation was applied +- Confidence scores +- Links to extraction-time provenance + +### Graceful Degradation + +Tools that can't provide detailed provenance still participate: +```json +{ + "type": "tool_invocation", + "tool_name": "calculator", + "input": {"expression": "8 + 5"}, + "output": "13", + "detail_level": "basic" +} +``` + +## Design Decisions + +### Provenance Node Identity: IRIs with UUIDs + +Provenance nodes use IRIs containing UUIDs, consistent with the RDF-style knowledge graph: +- Format: `urn:trustgraph:prov:{uuid}` +- Globally unique, persistent across sessions +- Can be dereferenced to retrieve full node data + +### Storage Segregation: Separate Collection + +Provenance is stored in a separate collection within the knowledge graph infrastructure. This allows: +- Distinct retrieval patterns for provenance vs. data +- Independent scaling/retention policies +- Clear separation of concerns + +### Client Protocol: Extended AgentResponse + +Provenance events extend `AgentResponse` with `chunk_type: "provenance"`. Events are lightweight, containing only IRI references to provenance nodes created/modified in the step. + +### Retrieval Granularity: Flexible, Multiple Objects Per Step + +A single agent step can create multiple provenance objects. The provenance event references all objects created or modified. This handles cases like: +- Retrieval returning multiple facts (each gets a provenance node) +- Tool invocation creating both an invocation node and result nodes + +### Graph Structure: True DAG + +The provenance structure is a DAG (not a tree): +- A provenance node can have multiple parents (e.g., reasoning combines facts A and B) +- Extraction-time nodes can be referenced by multiple query-time sessions +- Enables proper modeling of how conclusions derive from multiple sources + +### Linking to Extraction Provenance: Direct IRI Reference + +Query-time provenance references extraction-time provenance via direct IRI links in the `source_refs` field. No separate linking mechanism needed. + +## Open Questions + +### Provenance Retrieval API + +Base layer uses the existing knowledge graph API to query the provenance collection. A higher-level service may be added to provide convenience methods. Details TBD during implementation. + +### Provenance Node Granularity + +Placeholder to explore: What level of detail should different node types capture? +- Should `reasoning` nodes include the full LLM prompt, or just a summary? +- How much of tool input/output to store? +- Trade-offs between completeness and storage/performance + +### Provenance Retention + +TBD - retention policy to be determined: +- Indefinitely? +- Tied to session retention? +- Configurable per collection? + +## Implementation Considerations + +### Files Likely Affected + +| Area | Changes | +|------|---------| +| Agent service | Generate provenance events | +| Tool implementations | Report provenance data | +| Agent response schema | Add provenance event type | +| Knowledge graph | Provenance storage/retrieval | + +### Backward Compatibility + +- Existing agent clients continue to work (provenance is additive) +- Tools that don't report provenance still function + +## References + +- PROV-O (PROV-Ontology): W3C standard for provenance modeling +- Current agent implementation: `trustgraph-flow/trustgraph/agent/react/` +- Agent schemas: `trustgraph-base/trustgraph/schema/services/agent.py` +- Extraction-time provenance notes: `docs/tech-specs/extraction-time-provenance.md`