xnano.ai.models.components
xnano.ai.models.components
¶
xnano.ai.models.components
Widgets from a language model: a small program that draws on a canvas of its own size, run in
the sandbox of xnano.sandbox and written like any other content.
Classes:
-
Component–A widget a model wrote: a small program that draws on a canvas of its own size.
-
ComponentModel–Generate widgets: a status card, a menu, a table, as a small program that draws them.
Component
dataclass
¶
A widget a model wrote: a small program that draws on a canvas of its own size.
Write it like other content, with canvas.screen.write(component): it takes its
width and height, and a border or a title given to the write goes around it. Its
code runs in the sandbox of xnano.sandbox, so it can only draw.
Attributes:
-
request(str) –What was asked for.
-
code(str) –The program, in Python.
-
width(int) –The width it draws at, in cells.
-
height(int) –The height it draws at, in rows.
-
text(str) –What it draws, as text.
Examples:
import xnano
from xnano.ai.models.components import ComponentModel
from xnano.ai.testing import scripted_model
answer = {'layout': 'One bold line.', 'program': "canvas.screen.write('Ready', bold=True)"}
components = ComponentModel(scripted_model(answer).model)
badge = components.generate('a ready badge', width=8, height=1)
assert badge.text == 'Ready'
with xnano.new(width=12, height=3) as canvas:
canvas.screen.write(badge, border='rounded')
assert canvas.screen.render().splitlines()[1] == '│Ready │'
Methods:
-
__xnano_write__–The cells the program drew.
ComponentModel
¶
ComponentModel(model: Model | KnownModelName | str | None = None, *, max_width: int = 48, max_height: int = 12, instructions: str | None = None, model_settings: ModelSettings | None = None, capabilities: Sequence[AbstractCapability[Any]] = (), retries: int = 2, usage_limits: UsageLimits | None = None, thinking: ThinkingLevel | None = None, cache: bool = True)
Bases: TaskModel
Generate widgets: a status card, a menu, a table, as a small program that draws them.
The model is given the drawing API of the sandbox and worked examples, each with what it
draws, and writes a program at the size asked for. The program is run in the sandbox of
xnano.sandbox as it arrives. What can be fixed safely is fixed and reported
in last_generation.notes: a near-miss border or colour name, a keyword the API does not
take, a cell outside the canvas, a line too long for it. An error, something else drawn
outside the size, or nothing drawn at all goes back to the model with what it drew so far,
under a column ruler. When the 'component-examples' library of xnano.ai.assets
is installed, the examples closest to each request are shown too.
Parameters:
-
model(Model | KnownModelName | str | None, default:None) –The language model to ask.
-
max_width(int, default:48) –The widest component a call may ask for, in cells.
-
max_height(int, default:12) –The tallest component a call may ask for, in rows.
-
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:2) –How many times a program that fails 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.
Attributes:
-
last_generation(GenerationReport | None) –How the last call went, or
Nonebefore the first.
Create the component model; nothing is sent until the first call.
Raises:
-
ValueError–max_widthormax_heightis not a whole number of 1 or more.
Methods:
-
generate_async–Write a widget from a description, with
await. -
generate–Write a widget from a description, waiting for it.
-
edit_async–Change a widget as asked, at the same size, with
await. -
edit–Change a widget as asked, waiting for it.
-
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.
Source code in xnano/ai/models/components.py
def __init__(
self,
model: Model | KnownModelName | str | None = None,
*,
max_width: int = 48,
max_height: int = 12,
instructions: str | None = None,
model_settings: ModelSettings | None = None,
capabilities: Sequence[AbstractCapability[Any]] = (),
retries: int = 2,
usage_limits: UsageLimits | None = None,
thinking: ThinkingLevel | None = None,
cache: bool = True,
) -> None:
"""
Create the component model; nothing is sent until the first call.
Raises:
ValueError: ``max_width`` or ``max_height`` is not a whole number of 1 or more.
"""
for name, value in (('max_width', max_width), ('max_height', max_height)):
if isinstance(value, bool) or not isinstance(value, int) or value < 1:
raise ValueError(
f'{name} must be a whole number of 1 or more, but was {value!r}.'
)
super().__init__(
model,
instructions='\n\n'.join(
part for part in (_instructions(), instructions) if part
),
model_settings=model_settings,
capabilities=capabilities,
retries=retries,
usage_limits=usage_limits,
thinking=thinking,
cache=cache,
)
self.max_width = max_width
self.max_height = max_height
self.last_generation: GenerationReport | None = None
is_decision_model
property
¶
is_decision_model: bool
Whether model is a decision model, which answers with probabilities.
generate_async
¶
generate_async(request: str, evidence: object = None, *, width: int | None = None, height: int | None = None) -> Coroutine[Any, Any, Component]
Write a widget from a description, with await.
Parameters:
-
request(str) –What to draw, such as
'a status card: CPU 73%, memory 41%'. -
evidence(object, default:None) –What the widget shows, such as the hook's context; see
Evidence. -
width(int | None, default:None) –The width in cells;
Noneismax_width. -
height(int | None, default:None) –The height in rows;
Noneismax_height.
Returns:
Raises:
-
ValueError–A size is not a whole number from 1 to the model's most.
-
GenerationError–No program drew the widget, even after the retries, when awaited.
Source code in xnano/ai/models/components.py
def generate_async(
self,
request: str,
evidence: object = None,
*,
width: int | None = None,
height: int | None = None,
) -> Coroutine[Any, Any, Component]:
"""
Write a widget from a description, with ``await``.
Args:
request: What to draw, such as ``'a status card: CPU 73%, memory 41%'``.
evidence: What the widget shows, such as the hook's context; see
[`Evidence`][xnano.ai.Evidence].
width: The width in cells; ``None`` is ``max_width``.
height: The height in rows; ``None`` is ``max_height``.
Returns:
A coroutine that gives the [`Component`][xnano.ai.models.components.Component].
Raises:
ValueError: A size is not a whole number from 1 to the model's most.
GenerationError: No program drew the widget, even after the retries, when
awaited.
"""
size = (self._check_size(width, 'width'), self._check_size(height, 'height'))
return self._write(request, snapshot(evidence), size, None)
generate
¶
generate(request: str, evidence: object = None, *, width: int | None = None, height: int | None = None) -> Component
Write a widget from a description, waiting for it.
The same as generate_async.
Source code in xnano/ai/models/components.py
def generate(
self,
request: str,
evidence: object = None,
*,
width: int | None = None,
height: int | None = None,
) -> Component:
"""
Write a widget from a description, waiting for it.
The same as [`generate_async`][xnano.ai.models.components.ComponentModel.generate_async].
"""
return _run_blocking(
self.generate_async(request, evidence, width=width, height=height), 'generate'
)
edit_async
¶
Change a widget as asked, at the same size, with await.
Parameters:
-
component(Component) –The widget to change.
-
request(str) –The change, such as
'turn the CPU bar red'.
Returns:
-
Coroutine[Any, Any, Component]–A coroutine that gives the new
Component; the one given -
Coroutine[Any, Any, Component]–is not changed.
Source code in xnano/ai/models/components.py
def edit_async(
self, component: Component, request: str
) -> Coroutine[Any, Any, Component]:
"""
Change a widget as asked, at the same size, with ``await``.
Args:
component: The widget to change.
request: The change, such as ``'turn the CPU bar red'``.
Returns:
A coroutine that gives the new [`Component`][xnano.ai.models.components.Component]; the one given
is not changed.
"""
return self._write(request, None, (component.width, component.height), component)
edit
¶
Change a widget as asked, waiting for it.
The same as edit_async.
Source code in xnano/ai/models/components.py
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)