Skip to content

Types

These are the objects that cross every boundary: what you pass into a decision (Event, EvidenceSnapshot) and what you get back (DecisionRecord, with one ChannelReport per check and a Health summary). They are frozen dataclasses, and each has to_dict() and from_dict(), so a record can be stored as JSON and read back. Open this page when you are writing the code that builds evidence, stores records, or reads verdict, proposed_action and reason.

Public here: Event, EvidenceSnapshot, DecisionRecord, Verdict, Envelope (all in grounded_decision.__all__). ChannelReport, Health, CatalogRef, ChannelName and Trust appear inside records and are importable from grounded_decision.types. What each field means in plain words: The decision record and the glossary.

types

Shared, serializable types for the grounded decision runtime.

Every public object that crosses a module boundary is a frozen dataclass with to_dict(). The runtime never mutates a decision record in place.

Verdict

Bases: StrEnum

Terminal output of one decision step.

Envelope

Bases: StrEnum

Hardness tag the solver router is allowed to honor.

Trust

Bases: StrEnum

How much of a catalog claim this check is allowed to lean on.

CatalogRef dataclass 

CatalogRef(
    family: str, title: str, lean: bool, note: str = ""
)

Pointer at a result family in the math catalog.

ChannelReport dataclass 

ChannelReport(
    name: ChannelName,
    passed: bool,
    trust: Trust,
    summary: str,
    metrics: Mapping[str, float | int | bool | str] = dict[
        str, float | int | bool | str
    ](),
    catalog: tuple[CatalogRef, ...] = (),
)

One go/no-go channel in the conjunction.

Health dataclass 

Health(
    d_lambda_sq: float,
    reconstruction_margin: float,
    p_hat: float,
    p_threshold: float,
    threshold_width_theorem: float,
    threshold_width_operational: float,
    in_theorem_window: bool,
    in_operational_window: bool,
    theorem_window_vacuous: bool,
    conformal_p: float,
    star_height: int,
    game_solved: bool,
    mixer_status: str = "idle",
    support: float | None = None,
)

Self-management vector of a module after one step.

Event dataclass 

Event(
    name: str, payload: Mapping[str, Any] = dict[str, Any]()
)

One input the statechart can consume.

EvidenceSnapshot dataclass 

EvidenceSnapshot(
    n: int,
    p_hat: float,
    p_threshold: float,
    degree: float,
    lambda_hat: float,
    n_states: int = 2,
    scores: tuple[float, ...] = (),
    label_score: float = 0.0,
    observations: Mapping[str, Any] = dict[str, Any](),
    support: float | None = None,
)

Graph-shaped evidence read by the reconstruction, threshold and conformal checks.

n is the number of vertices of the corroboration graph. p_hat is its edge density (or the Bernoulli parameter of a monotone property). p_threshold is the operating threshold of that property. degree and lambda_hat describe a broadcast/tree channel. scores are nonconformity scores for the conformal wrap; label_score is the score of the candidate decision. support is the share (0 to 1) of related cases whose label is the one the proposed action implies, for example the share of linked accounts confirmed as fraud when the proposed action is block. None means it was not measured; the support check then passes unless Limits.require_support is set.

DecisionRecord dataclass 

DecisionRecord(
    verdict: Verdict,
    action: str | None,
    reason: str,
    module: str,
    event: Event,
    channels: tuple[ChannelReport, ...],
    health: Health,
    envelope: Envelope,
    proposed_action: str | None = None,
    extras: Mapping[str, Any] = dict[str, Any](),
)

Fully described output of Module.decide.

This is the public interface of the system. Downstream services should persist the dict form, not infer hidden state.