Runtime Models API

Status: Generated from current Python docstrings and type hints.

Runtime objects backing the authoring DSL. These are the in-memory objects that the compiler reads before lowering to Gaia IR.

gaia.engine.lang.runtime

Runtime dataclasses and helpers backing the Gaia Lang DSL.

Associate dataclass

Associate(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), helper: Claim | None = None, a: Claim | None = None, b: Claim | None = None, p_a_given_b: float = 0.5, p_b_given_a: float = 0.5, pattern: str | None = None)

Bases: Relation

Symmetric probabilistic association between two Claims.

CandidateRelation dataclass

CandidateRelation(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), claims: tuple[Claim, ...] = (), pattern: str | None = None, status: str = 'hypothesis')

Bases: Scaffold

Marks a hypothesized relation that has not been formalized yet.

a property

a: Claim | None

Compatibility view for older binary callers.

b property

b: Claim | None

Compatibility view for older binary callers.

proposed property

proposed: str | None

Compatibility view for older proposed-pattern callers.

Compose dataclass

Compose(name: str = '', version: str = '', inputs: tuple[Knowledge | str, ...] = (), actions: tuple[Action | str, ...] = (), conclusion: Claim | None = None)

Bases: Action

Action-level composition of child actions into a reviewable DAG.

structure_hash

structure_hash(input_refs: list[str], action_refs: list[str], conclusion_ref: str, warrant_refs: list[str], background_refs: list[str] | None = None) -> str

Hash the canonical compose payload used for the IR compose ID.

Source code in gaia/engine/lang/runtime/action.py

def structure_hash(
    self,
    input_refs: list[str],
    action_refs: list[str],
    conclusion_ref: str,
    warrant_refs: list[str],
    background_refs: list[str] | None = None,
) -> str:
    """Hash the canonical compose payload used for the IR compose ID."""
    payload = {
        "name": self.name,
        "version": self.version,
        "inputs": sorted(input_refs),
        "background": sorted(background_refs or []),
        "actions": list(action_refs),
        "conclusion": conclusion_ref,
        "warrants": sorted(warrant_refs),
    }
    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(canonical.encode()).hexdigest()[:16]

Compute dataclass

Compute(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), conclusion: Claim | None = None, given: tuple[Claim, ...] = (), fn: Callable[..., Any] | None = None, code_hash: str | None = None)

Bases: Support

Deterministic code execution.

Contradict dataclass

Contradict(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), a: Claim | None = None, b: Claim | None = None, helper: Claim | None = None)

Bases: Structural

Declares two Claims contradictory.

Decompose dataclass

Decompose(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), whole: Claim | None = None, parts: tuple[Claim, ...] = (), formula: Any = None)

Bases: Reasoning

Declares a whole Claim equivalent to a formula over atomic Claims.

DependsOn dataclass

DependsOn(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), conclusion: Claim | None = None, given: tuple[Claim, ...] = ())

Bases: Scaffold

Marks unformalized dependencies for a conclusion.

Derive dataclass

Derive(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), conclusion: Claim | None = None, given: tuple[Claim, ...] = ())

Bases: Support

Logical derivation.

Directed dataclass

Directed(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list())

Bases: Reasoning

Directed reasoning shape: sources or premises point toward a target.

Equal dataclass

Equal(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), a: Claim | None = None, b: Claim | None = None, helper: Claim | None = None)

Bases: Structural

Declares two Claims equivalent.

Exclusive dataclass

Exclusive(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), a: Claim | None = None, b: Claim | None = None, helper: Claim | None = None)

Bases: Structural

Declares two Claims form a closed binary partition.

GaiaGraph dataclass

GaiaGraph(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict())

Base Gaia authoring graph record. Parallel to Knowledge, not a Knowledge subclass.

Infer dataclass

Infer(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), helper: Claim | None = None, hypothesis: Claim | None = None, evidence: Claim | None = None, given: tuple[Claim, ...] = (), p_e_given_h: float | Claim = 0.5, p_e_given_not_h: float | Claim | None = 0.5, p_e_given_not_h_defaulted: bool = False)

Bases: Directed

Bayesian inference: P(E|H) update.

MaterializationLink dataclass

MaterializationLink(scaffold: Scaffold, by: tuple[GaiaGraph, ...], label: str | None = None, rationale: str = '', metadata: dict[str, Any] = dict())

Bookkeeping link from scaffold to the formal graph records that handle it.

Observe dataclass

Observe(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), conclusion: Claim | None = None, given: tuple[Claim, ...] = ())

Bases: Support

Empirical observation or measurement.

Reasoning dataclass

Reasoning(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list())

Bases: GaiaGraph

Reviewable reasoning record that can carry warrant Claims.

Relation dataclass

Relation(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list())

Bases: Reasoning

Symmetric or non-directed relation among Claims.

Scaffold dataclass

Scaffold(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict())

Bases: GaiaGraph

Formalization workflow record. Does not enter IR/BP as a warrant.

Structural dataclass

Structural(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list())

Bases: Relation

Hard structural constraint between claims or claim formulas.

Support dataclass

Support(label: str | None = None, rationale: str = '', background: list[Knowledge] = list(), metadata: dict[str, Any] = dict(), warrants: list[Claim] = list(), conclusion: Claim | None = None, given: tuple[Claim, ...] = ())

Bases: Directed

Directional reasoning: given -> conclusion.

Distribution dataclass

Distribution(content: str, *, impl: _BaseDistribution, format: str = 'markdown', **kwargs: Any)

Bases: Knowledge

Knowledge-wrapped continuous quantity with a probability distribution.

Use the family-specific factories (:func:Normal, :func:LogNormal, :func:Beta, etc.) rather than constructing this directly — they wrap the matching gaia.engine.bayes.distributions._BaseDistribution subclass into a Distribution carrying a content string + identity.

The wrapped computational object is available as .impl and exposes logpdf / logpmf / cdf / support / model_dump via thin delegating properties on this class.

Create a Knowledge-wrapped distribution.

Parameters:

Name	Type	Description	Default
content	str	Human-readable description of what this quantity is.	required
impl	_BaseDistribution	A _BaseDistribution subclass instance (Normal, Beta, …) that provides the computational backend.	required
format	str	Content format (markdown by default).	'markdown'
**kwargs	Any	Standard :class:Knowledge keyword arguments (title, label, metadata, provenance, …).	{}

Source code in gaia/engine/lang/runtime/distribution.py

def __init__(
    self,
    content: str,
    *,
    impl: _BaseDistribution,
    format: str = "markdown",
    **kwargs: Any,
) -> None:
    """Create a Knowledge-wrapped distribution.

    Args:
        content: Human-readable description of what this quantity is.
        impl: A ``_BaseDistribution`` subclass instance (Normal, Beta, …)
            that provides the computational backend.
        format: Content format (markdown by default).
        **kwargs: Standard :class:`Knowledge` keyword arguments
            (``title``, ``label``, ``metadata``, ``provenance``, …).
    """
    from gaia.engine.bayes.distributions.base import _BaseDistribution

    if not isinstance(impl, _BaseDistribution):
        raise TypeError(
            "Distribution(impl=...) must be a _BaseDistribution instance "
            "from gaia.engine.bayes.distributions; got "
            f"{type(impl).__name__}. Use the family factories (Normal, "
            "LogNormal, Beta, ...) instead of constructing Distribution "
            "directly."
        )
    super().__init__(content=content, type="distribution", format=format, **kwargs)
    self._impl = impl

impl property

impl: _BaseDistribution

Return the wrapped computational distribution object.

kind property

kind: str

Distribution family identifier ("normal", "beta", ...).

params property

params: dict[str, Any]

Return the distribution parameter dictionary.

logpdf

logpdf(x: float) -> float

Evaluate the log probability density at x (continuous).

Source code in gaia/engine/lang/runtime/distribution.py

def logpdf(self, x: float) -> float:
    """Evaluate the log probability density at ``x`` (continuous)."""
    return cast("_DistImpl", self._impl).logpdf(x)

logpmf

logpmf(k: int) -> float

Evaluate the log probability mass at k (discrete).

Source code in gaia/engine/lang/runtime/distribution.py

def logpmf(self, k: int) -> float:
    """Evaluate the log probability mass at ``k`` (discrete)."""
    return cast("_DistImpl", self._impl).logpmf(k)

support

support() -> tuple[float, float]

Return the inclusive support bounds of the distribution.

Source code in gaia/engine/lang/runtime/distribution.py

def support(self) -> tuple[float, float]:
    """Return the inclusive support bounds of the distribution."""
    return cast("_DistImpl", self._impl).support()

cdf

cdf(x: float) -> float

Cumulative distribution function P(X <= x).

Used at compile time to compute the prior of a predicate claim (P(k > c) = 1 - dist.cdf(c)). Lazy import of scipy keeps this out of the cold import path.

Source code in gaia/engine/lang/runtime/distribution.py

def cdf(self, x: float) -> float:
    """Cumulative distribution function P(X <= x).

    Used at compile time to compute the prior of a predicate claim
    (``P(k > c) = 1 - dist.cdf(c)``). Lazy import of scipy keeps this
    out of the cold import path.
    """
    from gaia.engine.bayes.adapters.scipy_backend import _to_scipy_dist

    impl = cast("_BaseDistribution", self._impl)
    resolved = impl._resolved_params()
    return float(_to_scipy_dist(impl.kind, resolved).cdf(x))

model_dump

model_dump() -> dict[str, Any]

Return the JSON-serialisable distribution literal payload.

Source code in gaia/engine/lang/runtime/distribution.py

def model_dump(self) -> dict[str, Any]:
    """Return the JSON-serialisable distribution literal payload."""
    return cast("_DistImpl", self._impl).model_dump()

Domain dataclass

Domain(content: str, *, members: list[Any], format: str = 'markdown', **kwargs: Any)

Bases: Knowledge

A user-declared, finite, enumerable typed sort.

Subclasses Knowledge so it carries identity, provenance, and metadata. Lang-only: does NOT enter the package's IR-bound knowledge map.

Create a finite enumerable authoring domain.

Source code in gaia/engine/lang/runtime/domain.py

def __init__(
    self,
    content: str,
    *,
    members: list[Any],
    format: str = "markdown",
    **kwargs: Any,
) -> None:
    """Create a finite enumerable authoring domain."""
    if not isinstance(members, list):
        raise TypeError("members must be a list")
    if len(members) == 0:
        raise ValueError("members must be a non-empty list")
    super().__init__(content=content, type="domain", format=format, **kwargs)
    self.members = list(members)

Claim dataclass

Claim(content: str | None = None, *, prior: float | None = None, from_actions: list[Any] | None = None, formula: Any = None, kind: ClaimKind = ClaimKind.GENERAL, **kwargs: Any)

Bases: Knowledge

Proposition with prior. Participates in BP.

Create a probabilistic claim node.

Source code in gaia/engine/lang/runtime/knowledge.py

def __init__(
    self,
    content: str | None = None,
    *,
    prior: float | None = None,
    from_actions: list[Any] | None = None,
    formula: Any = None,
    kind: ClaimKind = ClaimKind.GENERAL,
    **kwargs: Any,
) -> None:
    """Create a probabilistic claim node."""
    _validate_formula_and_kind(formula, kind)
    param_fields = getattr(self.__class__, "_param_fields", {})
    param_values, knowledge_kwargs = _split_param_kwargs(kwargs, param_fields)
    params = _parameter_entries(param_fields, param_values)

    template = self.__class__.__doc__ or ""
    content = _render_templated_content(
        content,
        template=template,
        param_fields=param_fields,
        param_values=param_values,
        knowledge_kwargs=knowledge_kwargs,
    )

    for name, val in param_values.items():
        object.__setattr__(self, name, val)

    super().__init__(
        content=content or "",
        type="claim",
        parameters=params or knowledge_kwargs.pop("parameters", []),
        **knowledge_kwargs,
    )
    self.prior = prior
    self.from_actions = list(from_actions or [])
    self.formula = formula
    self.kind = kind

ClaimKind

Bases: Enum

Shape discriminator for the structured-content of a Claim (spec §4.2).

GENERAL — default; formula optional, no structural commitments PARAMETER — asserts a Variable takes a specific value (Equals(var, const)) QUANTIFIED — top-level quantifier (Forall/Exists) in formula

NOT a "role" (hypothesis/prediction/observation-as-evidence) — those live on action graph nodes. Observation is an Observe action, not a Claim kind. NOT helper-claim metadata.

Context dataclass

Context(content: str, *, format: str = 'markdown', **kwargs: Any)

Bases: Note

Deprecated compatibility alias for Note.

Create a deprecated context note alias.

Source code in gaia/engine/lang/runtime/knowledge.py

def __init__(self, content: str, *, format: str = "markdown", **kwargs: Any) -> None:
    """Create a deprecated context note alias."""
    if "prior" in kwargs:
        raise TypeError("Context cannot have a prior.")
    metadata = dict(kwargs.pop("metadata", {}) or {})
    metadata.setdefault("legacy_kind", "context")
    super().__init__(content=content, format=format, metadata=metadata, **kwargs)

Knowledge dataclass

Knowledge(content: str, format: str = 'markdown', type: str = 'knowledge', title: str | None = None, background: list[Knowledge] = list(), parameters: list[dict[str, Any]] = list(), provenance: list[dict[str, str]] = list(), metadata: dict[str, Any] = dict(), label: str | None = None, strategy: Any | None = None)

Base knowledge node. Plain text plus metadata.

Note dataclass

Note(content: str, *, format: str = 'markdown', **kwargs: Any)

Bases: Knowledge

Non-probabilistic contextual material. Does not enter BP.

Create a non-probabilistic note.

Source code in gaia/engine/lang/runtime/knowledge.py

def __init__(self, content: str, *, format: str = "markdown", **kwargs: Any) -> None:
    """Create a non-probabilistic note."""
    if "prior" in kwargs:
        raise TypeError("Note cannot have a prior.")
    super().__init__(content=content, type="note", format=format, **kwargs)

Question dataclass

Question(content: str, **kwargs: Any)

Bases: Knowledge

Open inquiry. Does not enter BP.

Create a non-probabilistic question.

Source code in gaia/engine/lang/runtime/knowledge.py

def __init__(self, content: str, **kwargs: Any) -> None:
    """Create a non-probabilistic question."""
    if "prior" in kwargs:
        raise TypeError("Question cannot have a prior.")
    targets = kwargs.pop("targets", [])
    super().__init__(content=content, type="question", **kwargs)
    self.targets = list(targets)

Setting dataclass

Setting(content: str, *, format: str = 'markdown', **kwargs: Any)

Bases: Note

Deprecated compatibility alias for Note.

Create a deprecated setting note alias.

Source code in gaia/engine/lang/runtime/knowledge.py

def __init__(self, content: str, *, format: str = "markdown", **kwargs: Any) -> None:
    """Create a deprecated setting note alias."""
    if "prior" in kwargs:
        raise TypeError("Setting cannot have a prior.")
    metadata = dict(kwargs.pop("metadata", {}) or {})
    metadata.setdefault("legacy_kind", "setting")
    super().__init__(content=content, format=format, metadata=metadata, **kwargs)

Operator dataclass

Operator(operator: str, variables: list[Knowledge] = list(), conclusion: Knowledge | None = None, reason: str = '', metadata: dict[str, Any] = dict())

A deterministic logical constraint.

Step dataclass

Step(reason: str, premises: list[Knowledge] | None = None, metadata: dict[str, Any] | None = None)

A single reasoning step with optional premise references.

Strategy dataclass

Strategy(type: str, premises: list[Knowledge] = list(), conclusion: Knowledge | None = None, background: list[Knowledge] = list(), reason: ReasonInput = '', metadata: dict[str, Any] = dict(), label: str | None = None, formal_expr: list[Any] | None = None, sub_strategies: list[Strategy] = list(), composition_warrant: Knowledge | None = None)

A reasoning declaration.

RoleOccurrence dataclass

RoleOccurrence(claim: Claim, role: str, action: Action, action_type: str, action_label: str | None = None, path: tuple[str, ...] = (), source: str = 'explicit_field')

A claim role at a specific occurrence in an authored action.

Variable dataclass

Variable(*, symbol: str, domain: PrimitiveType | Domain, value: Any | None = None, unit: str | None = None, content: str | None = None, format: str = 'markdown', **kwargs: Any)

Bases: Knowledge

A typed term referenceable by formulas, models, and actions.

Subclasses Knowledge for identity, provenance, metadata. Carries a symbol used in formulas, a domain (PrimitiveType or user-declared Domain), and an optional bound value. Binding semantics (CONSTANT / FREE / BOUND_BY_CLAIM) are inferred by Milestone B's compiler; this class stores only authored data.

Lang-only: does NOT enter the package's IR-bound knowledge map (spec §2.4).

Create a typed authoring variable.

Source code in gaia/engine/lang/runtime/variable.py

def __init__(
    self,
    *,
    symbol: str,
    domain: PrimitiveType | Domain,
    value: Any | None = None,
    unit: str | None = None,
    content: str | None = None,
    format: str = "markdown",
    **kwargs: Any,
) -> None:
    """Create a typed authoring variable."""
    if not isinstance(symbol, str) or not symbol:
        raise TypeError("symbol must be a non-empty string")
    if not isinstance(domain, (PrimitiveType, Domain)):
        raise TypeError("domain must be a PrimitiveType or a Domain")

    if value is not None:
        _validate_value(value, domain)

    canonical_unit_value: str | None = None
    if unit is not None:
        from gaia.unit import canonical_unit

        canonical_unit_value = canonical_unit(unit)

    if content is None:
        content = _default_content(symbol, domain, value, canonical_unit_value)

    super().__init__(content=content, type="variable", format=format, **kwargs)
    self.symbol = symbol
    self.domain = domain
    self.value = value
    self.unit = canonical_unit_value

attach_reasoning

attach_reasoning(claim: Claim, reasoning: Reasoning) -> None

Attach a reasoning record to a claim's reverse index exactly once.

Source code in gaia/engine/lang/runtime/action.py

def attach_reasoning(claim: Claim, reasoning: Reasoning) -> None:
    """Attach a reasoning record to a claim's reverse index exactly once."""
    if all(existing is not reasoning for existing in claim.from_actions):
        claim.from_actions.append(reasoning)

validate_no_self_warrant

validate_no_self_warrant(reasoning: Reasoning, primary: Claim) -> None

Reject reasoning records whose primary claim/helper is also their warrant.

Source code in gaia/engine/lang/runtime/action.py

def validate_no_self_warrant(reasoning: Reasoning, primary: Claim) -> None:
    """Reject reasoning records whose primary claim/helper is also their warrant."""
    if any(warrant is primary for warrant in reasoning.warrants):
        raise ValueError("reasoning primary claim/helper must not also be its warrant")

compose

compose(*, name: str, version: str, background: list[Knowledge] | None = None, warrants: list[Claim] | None = None, rationale: str = '', label: str | None = None) -> Callable[[Callable[..., Claim]], Callable[..., Claim]]

Decorate a function as a Gaia action composition template.

Source code in gaia/engine/lang/runtime/composition.py

def compose(
    *,
    name: str,
    version: str,
    background: list[Knowledge] | None = None,
    warrants: list[Claim] | None = None,
    rationale: str = "",
    label: str | None = None,
) -> Callable[[Callable[..., Claim]], Callable[..., Claim]]:
    """Decorate a function as a Gaia action composition template."""

    def decorator(fn: Callable[..., Claim]) -> Callable[..., Claim]:
        @wraps(fn)
        def wrapper(*args: Any, **kwargs: Any) -> Claim:
            scope = _CompositionScope(name, version)
            token = _current_composition_scope.set(scope)
            try:
                result = fn(*args, **kwargs)
            finally:
                _current_composition_scope.reset(token)
            if not isinstance(result, Claim):
                raise TypeError("@compose functions must return a Claim object")

            compose_background = list(background or [])
            compose_action = Compose(
                label=label,
                rationale=rationale,
                background=compose_background,
                warrants=list(warrants or []),
                name=name,
                version=version,
                inputs=_infer_inputs(
                    args=args,
                    kwargs=kwargs,
                    actions=scope.captured_actions,
                    background=compose_background,
                ),
                actions=tuple(scope.captured_actions),
                conclusion=result,
            )
            validate_no_self_warrant(compose_action, result)
            attach_reasoning(result, compose_action)
            return result

        return wrapper

    return decorator

register_role_handler

register_role_handler(action_type: type[Action], handler: RoleHandler) -> None

Register role projection for an optional action subclass.

Source code in gaia/engine/lang/runtime/roles.py

def register_role_handler(action_type: type[Action], handler: RoleHandler) -> None:
    """Register role projection for an optional action subclass."""
    if not isinstance(action_type, type) or not issubclass(action_type, Action):
        raise TypeError("action_type must be an Action subclass")
    _ROLE_HANDLERS[action_type] = handler

roles_for_claim

roles_for_claim(claim: Claim, graph: ActionGraph, *, include_background: bool = True, include_warrants: bool = True) -> tuple[RoleOccurrence, ...]

Return all authored action roles for claim.

Source code in gaia/engine/lang/runtime/roles.py

def roles_for_claim(
    claim: Claim,
    graph: ActionGraph,
    *,
    include_background: bool = True,
    include_warrants: bool = True,
) -> tuple[RoleOccurrence, ...]:
    """Return all authored action roles for ``claim``."""
    return tuple(
        occurrence
        for occurrence in _iter_role_occurrences(
            graph,
            include_background=include_background,
            include_warrants=include_warrants,
        )
        if occurrence.claim is claim
    )

roles_for_package

roles_for_package(graph: ActionGraph, *, include_background: bool = True, include_warrants: bool = True) -> dict[Claim, tuple[RoleOccurrence, ...]]

Index authored action roles by claim identity.

Source code in gaia/engine/lang/runtime/roles.py

def roles_for_package(
    graph: ActionGraph,
    *,
    include_background: bool = True,
    include_warrants: bool = True,
) -> dict[Claim, tuple[RoleOccurrence, ...]]:
    """Index authored action roles by claim identity."""
    roles: dict[Claim, list[RoleOccurrence]] = defaultdict(list)
    for occurrence in _iter_role_occurrences(
        graph,
        include_background=include_background,
        include_warrants=include_warrants,
    ):
        roles[occurrence.claim].append(occurrence)
    return {claim: tuple(occurrences) for claim, occurrences in roles.items()}