mixle.experimental.typed_runtime.context_ir module

Revisitable effective-context graph, provenance, and context action IR.

class ContextAction(action_id, kind, expected_graph_version=None, input_nodes=(), query=None, source_scope=(), expected_information_gain=0.0, gain_standard_error=0.0, gain_sample_count=0, expected_latency_seconds=0.0, expected_tokens=0, expected_monetary_cost=0.0, expected_tool_calls=0, maximum_outputs=1, generated_output=False, resource_limits=None)[source]

Bases: object

Inspectable proposal for one context-construction operation.

Parameters:

  • action_id (str)

  • kind (ContextActionKind)

  • expected_graph_version (int | None)

  • input_nodes (tuple[str, ...])

  • query (str | None)

  • source_scope (tuple[str, ...])

  • expected_information_gain (float)

  • gain_standard_error (float)

  • gain_sample_count (int)

  • expected_latency_seconds (float)

  • expected_tokens (int)

  • expected_monetary_cost (float)

  • expected_tool_calls (int)

  • maximum_outputs (int)

  • generated_output (bool)

  • resource_limits (ContextActionLimits | None)

as_dict()[source]

Return a JSON-compatible context action.

Return type:

dict[str, Any]

class ContextActionKind(*values)[source]

Bases: StrEnum

Operation that may create, expand, verify, or materialize context.

class ContextActionLimits(latency_seconds, materialized_tokens, monetary_cost, tool_calls)[source]

Bases: object

Finite worst-case resources an adapter is permitted to consume.

Parameters:

  • latency_seconds (float)

  • materialized_tokens (int)

  • monetary_cost (float)

  • tool_calls (int)

as_dict()[source]

Return JSON-compatible action resource limits.

Return type:

dict[str, Any]

class ContextActionReceipt(action, graph_version_before, graph_version_after, output_nodes, output_edges, latency_seconds, materialized_tokens, tool_calls, monetary_cost, measured_information_gain, outcome, rolled_back=False)[source]

Bases: object

Actual graph transition and cost for one context action.

Parameters:

  • action (ContextAction)

  • graph_version_before (int)

  • graph_version_after (int)

  • output_nodes (tuple[str, ...])

  • output_edges (tuple[str, ...])

  • latency_seconds (float)

  • materialized_tokens (int)

  • tool_calls (int)

  • monetary_cost (float)

  • measured_information_gain (float | None)

  • outcome (str)

  • rolled_back (bool)

as_dict()[source]

Return a JSON-compatible context action receipt.

Return type:

dict[str, Any]

class ContextEdge(edge_id, source_node, target_node, kind, confidence=None, provenance=())[source]

Bases: object

One versionable typed relation in the context graph.

Parameters:

  • edge_id (str)

  • source_node (str)

  • target_node (str)

  • kind (ContextEdgeKind)

  • confidence (float | None)

  • provenance (tuple[Provenance, ...])

as_dict()[source]

Return a JSON-compatible context edge.

Return type:

dict[str, Any]

class ContextEdgeKind(*values)[source]

Bases: StrEnum

Typed relation between context artifacts.

class ContextGraph[source]

Bases: object

Mutable, versioned evidence graph with deterministic snapshot/restore.

add_node(node)[source]

Add an immutable node or accept an idempotent duplicate.

Parameters:

node (ContextNode)

Return type:

None

add_edge(edge)[source]

Add an immutable edge after endpoint validation.

Parameters:

edge (ContextEdge)

Return type:

None

verify(node_id, status, *, provenance=(), confidence=None)[source]

Replace verification fields without erasing generated provenance.

Parameters:

  • node_id (str)

  • status (EvidenceStatus)

  • provenance (tuple[Provenance, ...])

  • confidence (float | None)

Return type:

ContextNode

remove_node(node_id)[source]

Remove one node and all incident edges as one versioned mutation.

Parameters:

node_id (str)

Return type:

None

neighbors(node_id, *, kinds=None)[source]

Return both incoming and outgoing neighbors for revisitation.

Parameters:

  • node_id (str)

  • kinds (tuple[ContextEdgeKind, ...] | None)

Return type:

tuple[str, …]

unresolved_nodes()[source]

Generated hypotheses/claims that still need verification.

Return type:

tuple[ContextNode, …]

snapshot()[source]

Capture graph state for transactional context actions.

Return type:

tuple[int, dict[str, ContextNode], dict[str, ContextEdge]]

restore(snapshot)[source]

Restore an action snapshot after failure, or leave the graph untouched.

Validation happens on the candidate before anything is installed, so a rejected snapshot is a no-op rather than a half-applied state: this is the recovery path, and a restore that corrupts the graph it is restoring is worse than one that fails (MXR-080-1859).

Parameters:

snapshot (tuple[int, dict[str, ContextNode], dict[str, ContextEdge]])

Return type:

None

transaction()[source]

Exclude concurrent graph mutations while a staged transaction is prepared.

Return type:

Iterator[None]

replace_if_unchanged(expected, replacement)[source]

Install a staged state only when the complete base snapshot still matches.

Like restore(), the replacement is validated before it is installed, so a rejected staging attempt leaves the live graph exactly as it was (MXR-080-1859).

Parameters:
Return type:

None

as_dict()[source]

Return a JSON-compatible graph sorted by stable ids.

Return type:

dict[str, Any]

class ContextNode(node_id, kind, text, token_count, provenance=(), evidence_status=EvidenceStatus.UNVERIFIED, confidence=None, generated=False, source_horizon_position=None, metadata=<factory>, evidence_history=())[source]

Bases: object

One source, claim, generated artifact, summary, result, or memory unit.

Parameters:

  • node_id (str)

  • kind (ContextNodeKind)

  • text (str)

  • token_count (int)

  • provenance (tuple[Provenance, ...])

  • evidence_status (EvidenceStatus)

  • confidence (float | None)

  • generated (bool)

  • source_horizon_position (int | None)

  • metadata (Mapping[str, Any])

  • evidence_history (tuple[EvidenceTransition, ...])

property content_hash: str

Deterministic node-content fingerprint.

as_dict()[source]

Return a JSON-compatible context node.

Return type:

dict[str, Any]

class ContextNodeKind(*values)[source]

Bases: StrEnum

Semantic role of one bounded context artifact.

class EvidenceTransition(graph_version, status, provenance=(), confidence=None)[source]

Bases: object

One immutable, graph-versioned evidentiary state.

Parameters:

  • graph_version (int)

  • status (EvidenceStatus)

  • provenance (tuple[Provenance, ...])

  • confidence (float | None)

as_dict()[source]

Return a JSON-compatible evidence transition.

Return type:

dict[str, Any]

class EvidenceStatus(*values)[source]

Bases: StrEnum

Verification status kept separate from model confidence.

class FrozenMetadata(values=None)[source]

Bases: Mapping[str, Any]

Deterministic, recursively immutable context metadata.

Parameters:

values (Mapping[str, Any] | None)

class Provenance(source_id, source_version, locator, content_hash, provider=None, uri=None)[source]

Bases: object

Stable source identity and exact locator for one context artifact.

Parameters:

  • source_id (str)

  • source_version (str)

  • locator (str)

  • content_hash (str)

  • provider (str | None)

  • uri (str | None)

as_dict()[source]

Return a JSON-compatible provenance record.

Return type:

dict[str, Any]