v0.6.0_graph_native_evidence.md

v0.6.0 graph-native evidence and GraphRAG research preview

Purpose

This development specification introduces an optional graph-native evidence plane alongside the authoritative deterministic TargetIntel-IO decision plane. The graph layer is research-only and read-only with respect to productive feature construction, stable roles, therapeutic-intent scores, ranks, target selection, and candidate activation.

Source-of-truth boundary

Finalized EvidenceItem records and validated ReviewedEvidenceSnapshot objects remain the scientific source of truth. The graph layer converts those records into immutable entities and assertions while retaining exact evidence identifiers, payload provenance, contradictions, limitations, context, release metadata, and review status.

Single-cell and clinical-response adapters accept only precomputed summary rows with explicit dataset, cohort, cell, treatment, timepoint, sample or patient counts, expression metrics, validation state, and source release. They do not load raw matrices, perform differential expression, treat cells as independent patients, generate clinical predictions, or alter rankings.

Architecture

ReviewedEvidenceSnapshot --exact EvidenceItem IDs--> GraphSnapshot
single-cell summaries -----development-only-------> GraphSnapshot
clinical summaries --------development-only-------> GraphSnapshot
                                                     |
                                                     +--> deterministic retrieval
                                                     +--> auditable paths
                                                     +--> communities
                                                     +--> provider-neutral BYOG tables
                                                     +--> restricted reviewed snapshot
                                                          |
                                                          +--> existing grounded_writer

Every graph snapshot and context pack is content-addressed. Unknown entities, dangling relationships, missing EvidenceItem references, modified bundle files, and GraphRAG table inconsistencies fail closed.

Grounded synthesis boundary

Graph retrieval may select evidence, but it may not synthesize scientific claims directly. A selected context pack must resolve every evidence reference to the validated reviewed snapshot. The bridge creates a deterministic read-only evidence subset bound to the context-pack identity and delegates to the existing provider-neutral grounded_writer contracts. Graph-only summary identifiers cannot be silently omitted or presented as reviewed EvidenceItems.

CLI

targetintel graph demo --output results/graph-demo
targetintel graph validate-bundle results/graph-demo
targetintel graph inspect results/graph-demo
targetintel graph paths results/graph-demo --from-entity ID --to-entity ID
targetintel graph export-graphrag results/graph-demo --output results/byog

The standalone equivalent remains python -m targetintel.graph.

Dependency policy

The deterministic baseline keeps its existing dependencies. Graph analytics is installed explicitly with targetintel-io[graph]. Microsoft GraphRAG is an optional, pinned adapter dependency under targetintel-io[graphrag] and is not imported by the productive workflow. The TargetIntel graph snapshot remains the canonical source even when BYOG tables are consumed by another engine.

Acceptance gates

• complete historical test suite remains green;
• graph tests are offline and deterministic;
• targetintel run --validate remains unchanged;
• baseline scores and ranks remain byte-identical;
• exact evidence identity and contradiction preservation are tested;
• GraphRAG exports contain no dangling references;
• no graph path emits candidate activation or clinical guidance.