diff --git a/.env.example b/.env.example index f7cc6ad..2c779e4 100644 --- a/.env.example +++ b/.env.example @@ -123,6 +123,8 @@ CORTEX_CMVK_OPENAI_MODEL=gpt-4o-mini CORTEX_CONTRADICTION_ENABLED=true CORTEX_CONTRADICTION_KAFKA=true CORTEX_SEMANTIC_ENABLED=false +# V2 Evidence Graph writers (Claim/Evidence). Schema V010 applies regardless; writes gated here. +CORTEX_EVIDENCE_GRAPH=false # Decay worker interval when Compose profile `api` is up (seconds). Default 24h. CORTEX_DECAY_INTERVAL_SECONDS=86400 diff --git a/DECISIONS.md b/DECISIONS.md index 4fcb47d..30b296f 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -298,6 +298,12 @@ access_policy: { **Alternatives rejected:** Keep calling Phase 8 "next" as V1 incomplete; ship stub `coverage_score` just to match README. **Owner:** Abhinaysai +### D-019 — 2026-09-18 — Claim/Evidence models alongside DecisionEvent (V2 foundations) +**Status:** Active +**Decision:** Add V2 `Claim` / `Evidence` / `ReliabilityDecision` models and Neo4j V010 schema. V1 `DecisionEvent` remains the Kafka write unit. Adapters in `evidence/adapters.py` map Decision → Claim+Evidence. Writers stay behind `CORTEX_EVIDENCE_GRAPH` (default false). +**Rationale:** Enables Evidence Graph without breaking existing pipeline. Schema-first so migrations can apply in demo/prod before feature flag is on. +**Owner:** Abhinaysai + --- ## PENDING DECISIONS (need resolution before build) diff --git a/evidence/__init__.py b/evidence/__init__.py new file mode 100644 index 0000000..235ceef --- /dev/null +++ b/evidence/__init__.py @@ -0,0 +1,15 @@ +"""Evidence graph package — Claim/Evidence adapters and (later) explain APIs.""" + +from evidence.adapters import ( + claim_evidence_bundle, + decision_to_claim, + decision_to_evidence, + evidence_graph_enabled, +) + +__all__ = [ + "claim_evidence_bundle", + "decision_to_claim", + "decision_to_evidence", + "evidence_graph_enabled", +] diff --git a/evidence/adapters.py b/evidence/adapters.py new file mode 100644 index 0000000..9a41389 --- /dev/null +++ b/evidence/adapters.py @@ -0,0 +1,109 @@ +"""Adapters between V1 DecisionEvent and V2 Claim/Evidence.""" + +from __future__ import annotations + +import hashlib +import os +from typing import Any + +from shared.models import DecisionEvent +from shared.v2_models import AssertionType, AuthorityClass, Claim, Evidence + + +def evidence_graph_enabled() -> bool: + """Return True when CORTEX_EVIDENCE_GRAPH is enabled.""" + return os.environ.get("CORTEX_EVIDENCE_GRAPH", "false").lower() in { + "1", + "true", + "yes", + "on", + } + + +def _authority_for_source(source: str) -> tuple[AuthorityClass, float]: + """Map connector source to authority class + default score.""" + mapping: dict[str, tuple[AuthorityClass, float]] = { + "github": ("merged_PR", 0.75), + "jira": ("approved_ticket", 0.70), + "linear": ("approved_ticket", 0.70), + "slack": ("casual_chat", 0.45), + "meeting": ("verified_human_statement", 0.55), + "cicd": ("production_state", 0.80), + "manual": ("verified_human_statement", 0.60), + } + return mapping.get(source, ("external_unverified", 0.30)) + + +def _assertion_for_decision(decision: DecisionEvent) -> AssertionType: + """Label agent/manual inference vs observed organizational decisions.""" + model = (decision.provenance.extractor_model or "").lower() + if decision.provenance.source == "manual" and "agent" in model: + return "INFERRED" + if decision.extraction_confidence < 0.7: + return "DERIVED" + return "ASSERTED" + + +def decision_to_claim( + decision: DecisionEvent, + *, + subject: str | None = None, + predicate: str = "decided", + object_: str | None = None, +) -> Claim: + """Map a V1 DecisionEvent to a V2 Claim without mutating the decision.""" + subj = subject or (decision.affects[0] if decision.affects else "organization") + obj = object_ or decision.content[:200] + status = "ACTIVE" if decision.status == "active" else "SUPERSEDED" + if decision.status == "archived": + status = "ARCHIVED" + elif decision.status == "under_review": + status = "CHALLENGED" + return Claim( + workspace_id=decision.workspace_id, + subject=subj, + predicate=predicate, + object=obj, + claim_type="decision", + assertion_type=_assertion_for_decision(decision), + confidence=max(decision.trust_score, decision.extraction_confidence), + status=status, # type: ignore[arg-type] + valid_from=decision.extracted_at, + observed_at=decision.extracted_at, + decision_id=decision.event_id, + content=decision.content, + superseded_by=None if decision.status != "superseded" else decision.replaces, + ) + + +def decision_to_evidence(decision: DecisionEvent) -> Evidence: + """Create primary Evidence from the decision provenance chain.""" + authority_class, authority_score = _authority_for_source(decision.provenance.source) + raw = f"{decision.provenance.raw_event_id}:{decision.content}".encode() + return Evidence( + workspace_id=decision.workspace_id, + source_type=decision.provenance.source, + source_id=decision.provenance.raw_event_id, + source_uri=None, + author=decision.made_by[0] if decision.made_by else None, + content_hash=hashlib.sha256(raw).hexdigest()[:32], + authority_class=authority_class, + authority_score=authority_score, + captured_at=decision.extracted_at, + observed_at=decision.provenance.original_timestamp, + integrity_state="ok", + snippet=decision.content[:280], + access_policy={}, + ) + + +def claim_evidence_bundle(decision: DecisionEvent) -> dict[str, Any]: + """Return claim + supporting evidence for optional graph write paths.""" + claim = decision_to_claim(decision) + evidence = decision_to_evidence(decision) + return { + "claim": claim, + "evidence": [evidence], + "relation": "SUPPORTS", + "enabled": evidence_graph_enabled(), + } diff --git a/graph/migrations/V010__claim_evidence_schema.cypher b/graph/migrations/V010__claim_evidence_schema.cypher new file mode 100644 index 0000000..66bda0c --- /dev/null +++ b/graph/migrations/V010__claim_evidence_schema.cypher @@ -0,0 +1,41 @@ +// V010 — Claim + Evidence graph schema (Cortex V2 Phase 1 foundations) +// Feature flag CORTEX_EVIDENCE_GRAPH gates application writers; schema is safe to apply always. + +CREATE CONSTRAINT claim_id_unique IF NOT EXISTS + FOR (c:Claim) REQUIRE c.id IS UNIQUE; + +CREATE CONSTRAINT evidence_id_unique IF NOT EXISTS + FOR (e:Evidence) REQUIRE e.id IS UNIQUE; + +CREATE INDEX claim_workspace IF NOT EXISTS + FOR (c:Claim) ON (c.workspace_id); + +CREATE INDEX claim_status IF NOT EXISTS + FOR (c:Claim) ON (c.status); + +CREATE INDEX claim_subject IF NOT EXISTS + FOR (c:Claim) ON (c.subject); + +CREATE INDEX claim_decision_id IF NOT EXISTS + FOR (c:Claim) ON (c.decision_id); + +CREATE INDEX claim_valid_from IF NOT EXISTS + FOR (c:Claim) ON (c.valid_from); + +CREATE INDEX evidence_workspace IF NOT EXISTS + FOR (e:Evidence) ON (e.workspace_id); + +CREATE INDEX evidence_authority IF NOT EXISTS + FOR (e:Evidence) ON (e.authority_class); + +CREATE INDEX evidence_source IF NOT EXISTS + FOR (e:Evidence) ON (e.source_type, e.source_id); + +CREATE INDEX claim_access_policy IF NOT EXISTS + FOR (c:Claim) ON (c.access_policy); + +CREATE INDEX evidence_access_policy IF NOT EXISTS + FOR (e:Evidence) ON (e.access_policy); + +MERGE (v:SchemaVersion {version: 10}) +SET v.applied_at = datetime(), v.description = "Claim + Evidence schema"; diff --git a/shared/v2_models.py b/shared/v2_models.py new file mode 100644 index 0000000..c49eb10 --- /dev/null +++ b/shared/v2_models.py @@ -0,0 +1,145 @@ +"""Cortex V2 shared models — Claim, Evidence, ReliabilityDecision, temporal types. + +Backward compatible with V1 DecisionEvent. Adapters live in evidence/adapters.py. +Feature flag: CORTEX_EVIDENCE_GRAPH (default false until writers are wired). +""" + +from __future__ import annotations + +import uuid +from datetime import UTC, datetime +from typing import Any, Literal + +from pydantic import BaseModel, ConfigDict, Field + + +def _utcnow() -> datetime: + return datetime.now(UTC) + + +def _uuid4() -> str: + return str(uuid.uuid4()) + + +TemporalStatus = Literal[ + "CANDIDATE", + "VERIFIED", + "ACTIVE", + "CHALLENGED", + "SUPERSEDED", + "ARCHIVED", + "QUARANTINED", + "ERASED", +] + +AssertionType = Literal["ASSERTED", "OBSERVED", "INFERRED", "DERIVED"] + +AuthorityClass = Literal[ + "formal_policy", + "approved_ADR", + "production_state", + "merged_PR", + "approved_ticket", + "incident_record", + "verified_human_statement", + "casual_chat", + "agent_inference", + "external_unverified", +] + +ReliabilityVerdict = Literal["ACT", "VERIFY", "ASK", "ESCALATE", "BLOCK"] + +ActionRisk = Literal[ + "READ_ONLY", + "LOW_RISK_WRITE", + "REVERSIBLE_WRITE", + "HIGH_IMPACT_WRITE", + "IRREVERSIBLE", + "PRIVILEGED", +] + + +class Evidence(BaseModel): + """Source-backed support or conflict for a Claim.""" + + id: str = Field(default_factory=_uuid4) + workspace_id: str + source_type: str = Field(description="slack | github | adr | incident | ...") + source_id: str + source_uri: str | None = None + author: str | None = None + content_hash: str | None = None + authority_class: AuthorityClass = "casual_chat" + authority_score: float = Field(default=0.5, ge=0.0, le=1.0) + captured_at: datetime = Field(default_factory=_utcnow) + observed_at: datetime | None = None + integrity_state: Literal["ok", "quarantined", "tampered", "unknown"] = "ok" + access_policy: dict[str, Any] = Field(default_factory=dict) + snippet: str | None = Field(default=None, description="Short evidence excerpt") + + model_config = ConfigDict() + + +class Claim(BaseModel): + """Organizational belief supported by Evidence (V2 atomic memory unit).""" + + id: str = Field(default_factory=_uuid4) + workspace_id: str + subject: str = Field(description="Entity the claim is about, e.g. payments-service") + predicate: str = Field(description="Relation, e.g. uses_database") + object: str = Field(description="Value, e.g. CockroachDB") + claim_type: str = Field(default="fact", description="fact | policy | procedure_assumption") + assertion_type: AssertionType = "ASSERTED" + confidence: float = Field(default=0.0, ge=0.0, le=1.0) + status: TemporalStatus = "CANDIDATE" + valid_from: datetime | None = None + valid_to: datetime | None = None + observed_at: datetime | None = None + invalidated_at: datetime | None = None + superseded_by: str | None = None + decision_id: str | None = Field( + default=None, + description="Optional link to V1 DecisionEvent.event_id", + ) + content: str = Field(default="", description="Human-readable claim summary") + access_policy: dict[str, Any] = Field(default_factory=dict) + created_at: datetime = Field(default_factory=_utcnow) + updated_at: datetime = Field(default_factory=_utcnow) + + model_config = ConfigDict() + + +class ReliabilityDecision(BaseModel): + """Typed gate output: whether memory is safe enough for an action.""" + + id: str = Field(default_factory=_uuid4) + workspace_id: str + query_id: str | None = None + candidate_action: dict[str, Any] = Field(default_factory=dict) + memory_confidence: float = Field(ge=0.0, le=1.0) + action_confidence: float = Field(ge=0.0, le=1.0) + risk: ActionRisk = "READ_ONLY" + decision: ReliabilityVerdict + reason_codes: list[str] = Field(default_factory=list) + required_checks: list[str] = Field(default_factory=list) + created_at: datetime = Field(default_factory=_utcnow) + trace_id: str | None = None + + model_config = ConfigDict() + + +class KnowledgeGap(BaseModel): + """Aggregated missing/stale/contradictory knowledge for a domain.""" + + id: str = Field(default_factory=_uuid4) + workspace_id: str + domain: str + gap_type: str + description: str + frequency: int = 1 + coverage_score: float = Field(default=0.0, ge=0.0, le=1.0) + first_seen: datetime = Field(default_factory=_utcnow) + last_seen: datetime = Field(default_factory=_utcnow) + status: Literal["open", "mitigated", "closed"] = "open" + + model_config = ConfigDict() diff --git a/tests/evidence/test_adapters.py b/tests/evidence/test_adapters.py new file mode 100644 index 0000000..5a11b55 --- /dev/null +++ b/tests/evidence/test_adapters.py @@ -0,0 +1,121 @@ +"""Tests for V2 Claim/Evidence models and DecisionEvent adapters.""" + +from __future__ import annotations + +from datetime import UTC, datetime + +import pytest + +from evidence.adapters import ( + claim_evidence_bundle, + decision_to_claim, + decision_to_evidence, + evidence_graph_enabled, +) +from shared.models import DecisionEvent, Provenance +from shared.v2_models import Claim, Evidence, ReliabilityDecision + + +def _decision(**kwargs: object) -> DecisionEvent: + now = datetime.now(UTC) + base = dict( + source_raw_event_id="raw-1", + workspace_id="ws-1", + event_type="decision", + content="Migrate payments to CockroachDB.", + made_by=["priya@"], + affects=["payments-service"], + rationale=["scale"], + extraction_confidence=0.9, + importance_score=0.8, + trust_score=0.85, + provenance=Provenance( + source="slack", + channel="#eng", + original_timestamp=now, + extractor_version="0.1.0", + extractor_model="gpt-4o", + raw_event_id="raw-1", + ), + extracted_at=now, + ) + base.update(kwargs) + return DecisionEvent(**base) # type: ignore[arg-type] + + +def test_decision_to_claim_links_decision_id() -> None: + d = _decision() + claim = decision_to_claim(d) + assert isinstance(claim, Claim) + assert claim.decision_id == d.event_id + assert claim.workspace_id == "ws-1" + assert claim.subject == "payments-service" + assert claim.status == "ACTIVE" + assert claim.assertion_type == "ASSERTED" + + +def test_low_confidence_marked_derived() -> None: + d = _decision(extraction_confidence=0.5) + assert decision_to_claim(d).assertion_type == "DERIVED" + + +def test_agent_manual_marked_inferred() -> None: + now = datetime.now(UTC) + d = _decision( + provenance=Provenance( + source="manual", + channel="api", + original_timestamp=now, + extractor_version="0.1.0", + extractor_model="agent-inferred", + raw_event_id="raw-2", + ) + ) + assert decision_to_claim(d).assertion_type == "INFERRED" + + +def test_decision_to_evidence_authority_by_source() -> None: + d = _decision() + ev = decision_to_evidence(d) + assert isinstance(ev, Evidence) + assert ev.authority_class == "casual_chat" + assert ev.content_hash + + +def test_github_source_higher_authority() -> None: + now = datetime.now(UTC) + d = _decision( + provenance=Provenance( + source="github", + channel="repo", + original_timestamp=now, + extractor_version="0.1.0", + extractor_model="gpt-4o", + raw_event_id="pr-1", + ) + ) + ev = decision_to_evidence(d) + assert ev.authority_class == "merged_PR" + assert ev.authority_score >= 0.7 + + +def test_bundle_respects_feature_flag(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("CORTEX_EVIDENCE_GRAPH", "false") + assert evidence_graph_enabled() is False + bundle = claim_evidence_bundle(_decision()) + assert bundle["enabled"] is False + assert bundle["relation"] == "SUPPORTS" + monkeypatch.setenv("CORTEX_EVIDENCE_GRAPH", "true") + assert claim_evidence_bundle(_decision())["enabled"] is True + + +def test_reliability_decision_model() -> None: + rd = ReliabilityDecision( + workspace_id="ws-1", + memory_confidence=0.9, + action_confidence=0.2, + risk="HIGH_IMPACT_WRITE", + decision="BLOCK", + reason_codes=["STALE_PROCEDURE"], + ) + assert rd.decision == "BLOCK" diff --git a/tests/graph/test_migrate_strip.py b/tests/graph/test_migrate_strip.py index e5113f9..f86e973 100644 --- a/tests/graph/test_migrate_strip.py +++ b/tests/graph/test_migrate_strip.py @@ -15,6 +15,11 @@ def test_v009_rbac_enforcement_migration_registered() -> None: assert 9 in versions +def test_v010_claim_evidence_migration_registered() -> None: + versions = {version for version, _, _ in get_migration_files()} + assert 10 in versions + + def test_strip_leading_comments_preserves_create_after_header() -> None: chunk = """// V005 — header // second line