Skip to content

Causal Attribution Graph

director_ai.core.attribution.causal_graph.CausalAttributionGraph dataclass 

CausalAttributionGraph(nodes: Iterable[AttributionNode], edges: Iterable[AttributionEdge], root_id: str, schema_version: str = SCHEMA_VERSION)

Validated explanatory DAG for score and halt decisions.

__post_init__ 

__post_init__() -> None

Freeze graph collections and validate DAG integrity.

node 

node(node_id: str) -> AttributionNode

Return one graph node by id.

top_contributors 

top_contributors(*, limit: int = 5) -> tuple[AttributionEdge, ...]

Return strongest direct contributors to the graph root.

to_dict 

to_dict(*, include_text: bool = False) -> dict[str, Any]

Serialise the graph with raw text redacted by default.

director_ai.core.attribution.causal_graph.AttributionNode dataclass 

AttributionNode(node_id: str, kind: AttributionNodeKind, label: str, score: float | None = None, text: str | None = None, metadata: Mapping[str, Any] = dict())

Single vertex in an attribution DAG.

label is safe for operator-facing summaries. Raw claim, source, or fact text belongs in text and is redacted by default during serialisation.

__post_init__ 

__post_init__() -> None

Validate required node fields and optional score.

to_dict 

to_dict(*, include_text: bool = False) -> dict[str, Any]

Serialise the node with raw text redacted by default.

director_ai.core.attribution.causal_graph.AttributionEdge dataclass 

AttributionEdge(source: str, target: str, relation: AttributionRelation, weight: float, metadata: Mapping[str, Any] = dict())

Directed causal influence edge between attribution nodes.

__post_init__ 

__post_init__() -> None

Validate edge endpoints and normalise edge weight.

to_dict 

to_dict() -> dict[str, Any]

Serialise the attribution edge.

director_ai.core.attribution.causal_graph.build_causal_attribution_graph 

build_causal_attribution_graph(evidence: CoherenceScore | ScoringEvidence | HaltEvidence) -> CausalAttributionGraph

Build a causal attribution graph from Director-AI evidence objects.

Operational Model

build_causal_attribution_graph() converts existing Director-AI evidence into a validated directed acyclic graph:

  • CoherenceScore and ScoringEvidence graphs connect retrieved evidence, claim support or contradiction, and final score contribution.
  • HaltEvidence graphs connect retrieved evidence, halt trace coordinates, and counterfactual score deltas to the halt decision.
  • to_dict() redacts raw claim, source, and fact text by default. Pass include_text=True only inside trusted operator or audit boundaries.
from director_ai.core import build_causal_attribution_graph

graph = build_causal_attribution_graph(score)
for edge in graph.top_contributors(limit=3):
    print(edge.source, edge.relation, edge.weight)

The graph is not a speculative causal discovery algorithm. It is an auditable representation of the causal path Director-AI used during scoring or stream halt enforcement.