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:
-
StateTransition–How a
StateModelchanged a state. -
StateModel–Keep a small state up to date as things happen.
Invariant
module-attribute
¶
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;
beforeitself 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
Noneon a language model. -
reason(str | None) –Why the state changed, as a language model wrote it, or
None.
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;Falseturns 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_typeis 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
withblock: 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:
-
is_decision_model(bool) –Whether
modelis a decision model, which answers with probabilities.
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; seeEvidence.
Returns:
-
Coroutine[Any, Any, StateTransition[StateT]]–A coroutine that gives the
StateTransition.
Raises:
-
ValueError–currentbreaks an invariant, or on a decision model the state has noboolorLiteralfield 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
¶
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
¶
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
¶
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
Noneon 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
¶
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)