Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
15 changes: 15 additions & 0 deletions evidence/__init__.py
Original file line number Diff line number Diff line change
@@ -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",
]
109 changes: 109 additions & 0 deletions evidence/adapters.py
Original file line number Diff line number Diff line change
@@ -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(),
}
41 changes: 41 additions & 0 deletions graph/migrations/V010__claim_evidence_schema.cypher
Original file line number Diff line number Diff line change
@@ -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";
145 changes: 145 additions & 0 deletions shared/v2_models.py
Original file line number Diff line number Diff line change
@@ -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()
Loading
Loading