Skip to content

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

Component(request: str, code: str, width: int, height: int, text: str, _cells: Region[int])

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__

__xnano_write__(context: Context[object, object]) -> Region[int]

The cells the program drew.

Source code in xnano/ai/models/components.py
def __xnano_write__(self, context: Context[object, object]) -> Region[int]:
    """The cells the program drew."""
    return self._cells

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; 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.

Attributes:

  • last_generation (GenerationReport | None) –

    How the last call went, or None before the first.

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.

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 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.

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; None is max_width.

  • height (int | None, default: None ) –

    The height in rows; None is max_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

edit_async(component: Component, request: str) -> Coroutine[Any, Any, Component]

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:

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

edit(component: Component, request: str) -> Component

Change a widget as asked, waiting for it.

The same as edit_async.

Source code in xnano/ai/models/components.py
def edit(self, component: Component, request: str) -> Component:
    """
    Change a widget as asked, waiting for it.

    The same as [`edit_async`][xnano.ai.models.components.ComponentModel.edit_async].
    """
    return _run_blocking(self.edit_async(component, request), 'edit')

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)