Skip to content

xnano.ai.models.state

xnano.ai.models.state

xnano.ai.models.state

A model that keeps a small state up to date as things happen: a character's mood, a door's lock, the phase of a game.

Classes:

Invariant module-attribute

Invariant = Callable[[Any], bool]

A rule every state must keep: a function of the state that returns whether it holds.

StateTransition dataclass

StateTransition(before: StateT, after: StateT, changes: dict[str, tuple[object, object]], confidence: dict[str, float] | None = None, reason: str | None = None)

Bases: Generic[StateT]

How a StateModel changed a state.

Attributes:

  • before (StateT) –

    The state as it was.

  • after (StateT) –

    The state as it is now; before itself when nothing changed.

  • changes (dict[str, tuple[object, object]]) –

    Each field that changed, with its old and its new value.

  • confidence (dict[str, float] | None) –

    How likely the new value of each field is, on a decision model, or None on a language model.

  • reason (str | None) –

    Why the state changed, as a language model wrote it, or None.

is_changed property

is_changed: bool

Whether any field changed.

StateModel

StateModel(state_type: type[StateT], model: Model | KnownModelName | str | None = None, *, invariants: Sequence[Invariant] = (), instructions: str | None = None, model_settings: ModelSettings | None = None, capabilities: Sequence[AbstractCapability[Any]] = (), retries: int = 3, usage_limits: UsageLimits | None = None, thinking: ThinkingLevel | None = None, cache: bool = True)

Bases: TaskModel, Generic[StateT]

Keep a small state up to date as things happen.

The state is a dataclass or a Pydantic model. On a decision model, the fields with a few values (bool and Literal) are decided: when the combinations of them are 255 or fewer, the model picks the whole next state among the ones that keep every invariant, so fields that depend on each other change together; with more, each field is asked on its own among the values that keep the invariants. Other fields keep their values. On a language model, the model writes the fields that change and why, and an answer that breaks an invariant is sent back to be fixed.

Parameters:

  • state_type (type[StateT]) –

    The dataclass or Pydantic model of the state.

  • model (Model | KnownModelName | str | None, default: None ) –

    The model to ask.

  • invariants (Sequence[Invariant], default: () ) –

    Rules every state must keep, as functions of the state that return whether they hold.

  • instructions (str | None, default: None ) –

    What the model is told before every request.

  • model_settings (ModelSettings | None, default: None ) –

    pydantic-ai settings for every request.

  • capabilities (Sequence[AbstractCapability[Any]], default: () ) –

    pydantic-ai capabilities for the agent.

  • retries (int, default: 3 ) –

    How many times an answer that breaks an invariant is sent back.

  • usage_limits (UsageLimits | None, default: None ) –

    Limits on the requests and tokens of one call.

  • thinking (ThinkingLevel | None, default: None ) –

    Whether the model reasons before answering. None, the default, leaves that to the model; False turns it off where the model allows it, and some models cannot turn it off.

  • cache (bool, default: True ) –

    Whether the unchanging start of every prompt is cached by the provider.

Examples:

from dataclasses import dataclass
from typing import Literal

from xnano.ai.models.state import StateModel
from xnano.ai.testing import ScriptedDecisionModel


@dataclass
class Goblin:
    mood: Literal['calm', 'wary', 'angry'] = 'calm'
    is_hostile: bool = False


moods = StateModel(
    Goblin,
    ScriptedDecisionModel({'response': 'mood=angry, is_hostile=true'}),
    invariants=[lambda goblin: goblin.mood == 'angry' or not goblin.is_hostile],
)
transition = moods.update(Goblin(), 'The hero stole its lunch.')
assert transition.after == Goblin(mood='angry', is_hostile=True)
assert transition.changes['mood'] == ('calm', 'angry')

Create the state model; nothing is sent until the first update.

Raises:

  • TypeError –

    state_type is not a dataclass or a Pydantic model, or an invariant is not a function.

Methods:

  • update_async –

    Work out the state after what the evidence says happened, with await.

  • update –

    Work out the state after what the evidence says happened, waiting for the answer.

  • override –

    Ask another model inside a with block: a test double, or a cheaper draft model.

  • details –

    What the backend reported about its last answer, as pydantic-ai's provider_details.

  • probabilities –

    The distribution a decision model gave a pick-one or rubric field in its last answer.

  • confidence –

    The confidence a decision model reported for a field of its last answer, or None.

Attributes:

Source code in xnano/ai/models/state.py
def __init__(
    self,
    state_type: type[StateT],
    model: Model | KnownModelName | str | None = None,
    *,
    invariants: Sequence[Invariant] = (),
    instructions: str | None = None,
    model_settings: ModelSettings | None = None,
    capabilities: Sequence[AbstractCapability[Any]] = (),
    retries: int = 3,
    usage_limits: UsageLimits | None = None,
    thinking: ThinkingLevel | None = None,
    cache: bool = True,
) -> None:
    """
    Create the state model; nothing is sent until the first update.

    Raises:
        TypeError: ``state_type`` is not a dataclass or a Pydantic model, or an invariant
            is not a function.
    """
    self._fields = _field_types(state_type)
    for rule in invariants:
        if not callable(rule):
            raise TypeError(
                f'An invariant is a function of the state that returns whether it holds, '
                f'such as lambda state: state.health >= 0, but got {rule!r}.'
            )
    super().__init__(
        model,
        instructions=instructions,
        model_settings=model_settings,
        capabilities=capabilities,
        retries=retries,
        usage_limits=usage_limits,
        thinking=thinking,
        cache=cache,
    )
    self.state_type = state_type
    self.invariants = tuple(invariants)
    self._retries = retries

is_decision_model property

is_decision_model: bool

Whether model is a decision model, which answers with probabilities.

update_async

update_async(current: StateT, evidence: object) -> Coroutine[Any, Any, StateTransition[StateT]]

Work out the state after what the evidence says happened, with await.

The evidence is read, and the current state checked, when this is called; await the result for the transition.

Parameters:

  • current (StateT) –

    The state now.

  • evidence (object) –

    What happened, such as 'The hero stole its lunch.' or the hook's context; see Evidence.

Returns:

Raises:

  • ValueError –

    current breaks an invariant, or on a decision model the state has no bool or Literal field to decide.

  • TerminalError –

    The model could not be reached (ai.model), or a language model kept breaking an invariant (ai.generation), when awaited.

Source code in xnano/ai/models/state.py
def update_async(
    self, current: StateT, evidence: object
) -> Coroutine[Any, Any, StateTransition[StateT]]:
    """
    Work out the state after what the evidence says happened, with ``await``.

    The evidence is read, and the current state checked, when this is called; await the
    result for the transition.

    Args:
        current: The state now.
        evidence: What happened, such as ``'The hero stole its lunch.'`` or the hook's
            context; see [`Evidence`][xnano.ai.Evidence].

    Returns:
        A coroutine that gives the [`StateTransition`][xnano.ai.models.state.StateTransition].

    Raises:
        ValueError: ``current`` breaks an invariant, or on a decision model the state has
            no ``bool`` or ``Literal`` field to decide.
        TerminalError: The model could not be reached (``ai.model``), or a language model
            kept breaking an invariant (``ai.generation``), when awaited.
    """
    if not self._keeps_invariants(current):
        raise ValueError(
            f'The current state {current!r} breaks the invariants '
            f'{", ".join(self._broken_invariants(current))}, so no update can start from '
            f'it. Fix the state, or the invariants.'
        )
    if self.is_decision_model:
        return self._decide(current, snapshot(evidence))
    return self._patch(current, snapshot(evidence))

update

update(current: StateT, evidence: object) -> StateTransition[StateT]

Work out the state after what the evidence says happened, waiting for the answer.

The same as update_async, for code that does not await.

Source code in xnano/ai/models/state.py
def update(self, current: StateT, evidence: object) -> StateTransition[StateT]:
    """
    Work out the state after what the evidence says happened, waiting for the answer.

    The same as [`update_async`][xnano.ai.models.state.StateModel.update_async], for code that does not
    await.
    """
    return _run_blocking(self.update_async(current, evidence), 'update')

override

override(*, model: Model | KnownModelName | str) -> Generator[None, None, None]

Ask another model inside a with block: a test double, or a cheaper draft model.

Parameters:

  • model (Model | KnownModelName | str) –

    The model to ask instead.

Examples:

from xnano.ai.models.decisions import ChoiceModel
from xnano.ai.testing import ScriptedDecisionModel

pick = ChoiceModel('typesafe:jev-1.14.0')
with pick.override(model=ScriptedDecisionModel({'response': 'left'})):
    assert pick.choose('the hero', ['left', 'right']).choice == 'left'
Source code in xnano/ai/models/__init__.py
@contextlib.contextmanager
def override(
    self, *, model: Model | KnownModelName | str
) -> Generator[None, None, None]:
    """
    Ask another model inside a ``with`` block: a test double, or a cheaper draft model.

    Args:
        model: The model to ask instead.

    Examples:
        ```python
        from xnano.ai.models.decisions import ChoiceModel
        from xnano.ai.testing import ScriptedDecisionModel

        pick = ChoiceModel('typesafe:jev-1.14.0')
        with pick.override(model=ScriptedDecisionModel({'response': 'left'})):
            assert pick.choose('the hero', ['left', 'right']).choice == 'left'
        ```
    """
    previous = self.model
    self.model = model
    try:
        with self.agent.override(model=model):
            yield
    finally:
        self.model = previous

details

details() -> dict[str, Any]

What the backend reported about its last answer, as pydantic-ai's provider_details.

Empty before the first call, and for a backend that reports nothing.

Source code in xnano/ai/models/__init__.py
def details(self) -> dict[str, Any]:
    """
    What the backend reported about its last answer, as pydantic-ai's ``provider_details``.

    Empty before the first call, and for a backend that reports nothing.
    """
    response = self._last_response()
    if response is None or response.provider_details is None:
        return {}
    return dict(response.provider_details)

probabilities

probabilities(field: str) -> dict[str, float] | None

The distribution a decision model gave a pick-one or rubric field in its last answer.

Parameters:

  • field (str) –

    The name of the field, such as 'response' for a single pick-one.

Returns:

  • dict[str, float] | None –

    The probability of each option, or None on a language model or for a field it

  • dict[str, float] | None –

    did not report.

Source code in xnano/ai/models/__init__.py
def probabilities(self, field: str) -> dict[str, float] | None:
    """
    The distribution a decision model gave a pick-one or rubric field in its last answer.

    Args:
        field: The name of the field, such as ``'response'`` for a single pick-one.

    Returns:
        The probability of each option, or ``None`` on a language model or for a field it
        did not report.
    """
    distribution = self.details().get('probabilities', {}).get(field)
    if distribution is None:
        return None
    return {str(option): float(value) for option, value in distribution.items()}

confidence

confidence(field: str) -> float | None

The confidence a decision model reported for a field of its last answer, or None.

The confidence is the backend's own figure; it is not how often the answer is right.

Source code in xnano/ai/models/__init__.py
def confidence(self, field: str) -> float | None:
    """
    The confidence a decision model reported for a field of its last answer, or ``None``.

    The confidence is the backend's own figure; it is not how often the answer is right.
    """
    value = self.details().get('confidence', {}).get(field)
    return None if value is None else float(value)