Skip to content

xnano.ai.models.art

xnano.ai.models.art

xnano.ai.models.art

Pixel art from a language model: generated, edited, animated and varied, always as xnano.Art, with the rows and palette the model wrote kept beside it.

Classes:

  • PaletteColor –

    One colour of a palette, and what it is for.

  • PixelRun –

    Pixels set in a row, from a column to the right: one letter of the palette per pixel.

  • ArtPatch –

    A change to pixel art: the runs of pixels it sets, and any colours it adds.

  • ArtText –

    Pixel art as a model writes it: rows of one letter per pixel, and a palette with roles.

  • ArtModel –

    Generate and edit pixel art: xnano.Art from a description.

  • Animation –

    Frames of pixel art shown one after another: what ArtModel.animate makes.

Attributes:

  • ColorRole –

    What a colour of a palette is for: 'outline', 'base', 'shadow', 'highlight', 'accent', 'skin' or 'detail'.

  • ArtStrategy –

    How the model writes the art: a small 'program' of drawing calls (rectangles, ellipses,

  • EditMode –

    How an edit is written: a 'patch' of the pixels that change, a 'redraw' of all of them, or 'auto' for the model to choose.

  • ArtSize (TypeAlias) –

    The size of art in pixels: a number such as 16, a share of the active canvas such as

ColorRole module-attribute

ColorRole = Literal['outline', 'base', 'shadow', 'highlight', 'accent', 'skin', 'detail']

What a colour of a palette is for: 'outline', 'base', 'shadow', 'highlight', 'accent', 'skin' or 'detail'.

ArtStrategy module-attribute

ArtStrategy = Literal['program', 'svg']

How the model writes the art: a small 'program' of drawing calls (rectangles, ellipses, lines, polygons, fills, mirrors and an outline), or an 'svg' drawing sampled onto the pixels.

EditMode module-attribute

EditMode = Literal['auto', 'patch', 'redraw']

How an edit is written: a 'patch' of the pixels that change, a 'redraw' of all of them, or 'auto' for the model to choose.

ArtSize module-attribute

ArtSize: TypeAlias = 'int | Percentage | str | tuple[int | None, int | None] | None'

The size of art in pixels: a number such as 16, a share of the active canvas such as '50%' (a cell is one pixel wide and two tall), an expression such as ParentWidth - 4, a (low, high) range the model picks within, or None for any size up to 32.

PaletteColor dataclass

PaletteColor(role: ColorRole, color: str)

One colour of a palette, and what it is for.

Attributes:

  • role (ColorRole) –

    What the colour is for, such as 'outline' or 'shadow'.

  • color (str) –

    The colour as '#rrggbb'.

PixelRun dataclass

PixelRun(row: int, column: int, letters: str)

Pixels set in a row, from a column to the right: one letter of the palette per pixel.

Attributes:

  • row (int) –

    The row, from 0 at the top.

  • column (int) –

    The first column, from 0 at the left.

  • letters (str) –

    The letters to write, one per pixel; '.' makes a pixel transparent.

ArtPatch dataclass

ArtPatch(runs: tuple[PixelRun, ...], new_colors: Mapping[str, PaletteColor] = (lambda: MappingProxyType({}))())

A change to pixel art: the runs of pixels it sets, and any colours it adds.

Attributes:

pixel_count property

pixel_count: int

How many pixels the patch sets.

ArtText dataclass

ArtText(rows: tuple[str, ...], palette: Mapping[str, PaletteColor])

Pixel art as a model writes it: rows of one letter per pixel, and a palette with roles.

It is what ArtModel works with: the model names its colours by role under letters, then draws with those letters, and an edit changes letters. The changes that need no model (flip_horizontal, shift, recolor, scaled, apply) cost nothing. to_art() makes the Art to write on a canvas.

Attributes:

  • rows (tuple[str, ...]) –

    The rows, top to bottom, one letter per pixel; '.' is a transparent pixel.

  • palette (Mapping[str, PaletteColor]) –

    The colour of each letter, and what it is for.

  • width (int) –

    The width in pixels.

  • height (int) –

    The height in pixels.

Examples:

from xnano.ai.models.art import ArtText, PaletteColor

text = ArtText(
    rows=('.oo.', 'obbo', '.oo.'),
    palette={'o': PaletteColor('outline', '#1a1c2c'), 'b': PaletteColor('base', '#b13e53')},
)
assert text.flip_vertical().rows == text.rows
assert text.to_art().width == 4

Methods:

  • __post_init__ –

    Check that the rows are even and use only letters of the palette.

  • to_art –

    Make the Art of these rows and palette.

  • from_art –

    The rows and palette of art: the ones it was made from, or read from its pixels.

  • labelled –

    The rows with a column ruler above them and the row number before each, for a prompt.

  • palette_text –

    The palette as one line per letter, o = outline #1a1c2c, for a prompt.

  • flip_horizontal –

    The art mirrored left to right.

  • flip_vertical –

    The art mirrored top to bottom.

  • shift –

    The art moved by x pixels right and y down, inside the same size.

  • recolor –

    The art with new colours for some letters, keeping their roles.

  • scaled –

    The art with every pixel made factor pixels wide and tall.

  • apply –

    The art with a patch applied: its runs written, its new colours added.

width property

width: int

The width in pixels.

height property

height: int

The height in pixels.

__post_init__

__post_init__() -> None

Check that the rows are even and use only letters of the palette.

Source code in xnano/ai/models/art.py
def __post_init__(self) -> None:
    """Check that the rows are even and use only letters of the palette."""
    rows = tuple(self.rows)
    object.__setattr__(self, 'rows', rows)
    object.__setattr__(self, 'palette', MappingProxyType(dict(self.palette)))
    if not rows or not rows[0]:
        raise ValueError('ArtText needs at least one row of at least one pixel.')
    width = len(rows[0])
    for index, row in enumerate(rows):
        if len(row) != width:
            raise ValueError(
                f'Row {index} of the art has {len(row)} pixels, but row 0 has {width}. '
                f'Give every row the same number of letters.'
            )
        unknown = sorted(set(row) - set(self.palette) - {_TRANSPARENT})
        if unknown:
            raise ValueError(
                f'Row {index} uses {", ".join(map(repr, unknown))}, which the palette '
                f'does not name. Add them to the palette, or use {_TRANSPARENT!r} for a '
                f'transparent pixel.'
            )

to_art

to_art(*, symbol: str | None = None, encoding: PixelEncoding = 'half_blocks', borders: bool = False) -> Art

Make the Art of these rows and palette.

Parameters:

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

    A name to register the art under in symbols.

  • encoding (PixelEncoding, default: 'half_blocks' ) –

    How the pixels are packed into cells, as for pixel_art.

  • borders (bool, default: False ) –

    Whether the art shows its edge in box-drawing characters, as for pixel_art.

Source code in xnano/ai/models/art.py
def to_art(
    self,
    *,
    symbol: str | None = None,
    encoding: PixelEncoding = 'half_blocks',
    borders: bool = False,
) -> Art:
    """
    Make the [`Art`][xnano.art.Art] of these rows and palette.

    Args:
        symbol: A name to register the art under in [`symbols`][xnano.symbols].
        encoding: How the pixels are packed into cells, as for [`pixel_art`][xnano.pixel_art].
        borders: Whether the art shows its edge in box-drawing characters, as for
            [`pixel_art`][xnano.pixel_art].
    """
    art = pixel_art(
        list(self.rows),
        {letter: color.color for letter, color in self.palette.items()},
        symbol=symbol,
        encoding=encoding,
        borders=borders,
    )
    _text_of[art] = self
    return art

from_art classmethod

from_art(art: Art) -> ArtText

The rows and palette of art: the ones it was made from, or read from its pixels.

Art made by ArtModel or to_art gives back the model's own letters and roles. Other art is read pixel by pixel: each colour gets a letter, the darkest the 'outline' role and the others 'detail'.

Raises:

  • ValueError –

    The art is a world, which has no pixels of its own.

Source code in xnano/ai/models/art.py
@classmethod
def from_art(cls, art: Art) -> ArtText:
    """
    The rows and palette of art: the ones it was made from, or read from its pixels.

    Art made by [`ArtModel`][xnano.ai.models.art.ArtModel] or ``to_art`` gives back the model's own
    letters and roles. Other art is read pixel by pixel: each colour gets a letter, the
    darkest the ``'outline'`` role and the others ``'detail'``.

    Raises:
        ValueError: The art is a world, which has no pixels of its own.
    """
    known = _text_of.get(art)
    if known is not None:
        return known
    pixels = art.pixels
    if pixels is None:
        raise ValueError(
            'This art is a world, which has no pixels of its own to read. Give the art '
            'of one of its children, such as world.children[0].'
        )
    colors: dict[tuple[int, int, int], str] = {}
    rows = []
    letters = iter('abcdefghijklmnpqrstuvwxyz')
    for y in range(art.height):
        row = []
        for x in range(art.width):
            start = (y * art.width + x) * 4
            red, green, blue, alpha = pixels[start : start + 4]
            if alpha == 0:
                row.append(_TRANSPARENT)
                continue
            key = (red, green, blue)
            if key not in colors:
                colors[key] = next(letters, '?')
                if colors[key] == '?':
                    raise ValueError(
                        'This art has more than 25 colours, more than a palette of '
                        'letters can name. Reduce its colours before editing it.'
                    )
            row.append(colors[key])
        rows.append(''.join(row))
    darkest = min(colors, key=sum, default=None)
    palette = {
        letter: PaletteColor(
            'outline' if key == darkest else 'detail',
            '#{:02x}{:02x}{:02x}'.format(*key),
        )
        for key, letter in colors.items()
    }
    return cls(rows=tuple(rows), palette=palette)

labelled

labelled() -> str

The rows with a column ruler above them and the row number before each, for a prompt.

Source code in xnano/ai/models/art.py
def labelled(self) -> str:
    """The rows with a column ruler above them and the row number before each, for a prompt."""
    return _ruled('\n'.join(self.rows), self.width, self.height)

palette_text

palette_text() -> str

The palette as one line per letter, o = outline #1a1c2c, for a prompt.

Source code in xnano/ai/models/art.py
def palette_text(self) -> str:
    """The palette as one line per letter, ``o = outline #1a1c2c``, for a prompt."""
    return '\n'.join(
        f'{letter} = {color.role} {color.color}'
        for letter, color in self.palette.items()
    )

flip_horizontal

flip_horizontal() -> ArtText

The art mirrored left to right.

Source code in xnano/ai/models/art.py
def flip_horizontal(self) -> ArtText:
    """The art mirrored left to right."""
    return ArtText(tuple(row[::-1] for row in self.rows), self.palette)

flip_vertical

flip_vertical() -> ArtText

The art mirrored top to bottom.

Source code in xnano/ai/models/art.py
def flip_vertical(self) -> ArtText:
    """The art mirrored top to bottom."""
    return ArtText(self.rows[::-1], self.palette)

shift

shift(x: int = 0, y: int = 0) -> ArtText

The art moved by x pixels right and y down, inside the same size.

Source code in xnano/ai/models/art.py
def shift(self, x: int = 0, y: int = 0) -> ArtText:
    """The art moved by ``x`` pixels right and ``y`` down, inside the same size."""
    width, height = self.width, self.height
    blank = _TRANSPARENT * width
    rows = []
    for row_index in range(height):
        source = row_index - y
        if not 0 <= source < height:
            rows.append(blank)
            continue
        row = self.rows[source]
        moved = (
            (_TRANSPARENT * x + row)[:width]
            if x >= 0
            else (row[-x:] + _TRANSPARENT * -x)
        )
        rows.append(moved)
    return ArtText(tuple(rows), self.palette)

recolor

recolor(colors: Mapping[str, str]) -> ArtText

The art with new colours for some letters, keeping their roles.

Parameters:

  • colors (Mapping[str, str]) –

    The new '#rrggbb' colour of each letter to change.

Raises:

Source code in xnano/ai/models/art.py
def recolor(self, colors: Mapping[str, str]) -> ArtText:
    """
    The art with new colours for some letters, keeping their roles.

    Args:
        colors: The new ``'#rrggbb'`` colour of each letter to change.

    Raises:
        ValueError: A letter is not in the palette.
    """
    palette = dict(self.palette)
    for letter, color in colors.items():
        if letter not in palette:
            raise ValueError(
                f'recolor() was given {letter!r}, which the palette does not have. Its '
                f'letters are {", ".join(map(repr, palette))}.'
            )
        palette[letter] = PaletteColor(
            palette[letter].role, _normalized_color(color)[0]
        )
    return ArtText(self.rows, palette)

scaled

scaled(factor: int) -> ArtText

The art with every pixel made factor pixels wide and tall.

Raises:

  • ValueError –

    factor is not a whole number of 1 or more.

Source code in xnano/ai/models/art.py
def scaled(self, factor: int) -> ArtText:
    """
    The art with every pixel made ``factor`` pixels wide and tall.

    Raises:
        ValueError: ``factor`` is not a whole number of 1 or more.
    """
    if isinstance(factor, bool) or not isinstance(factor, int) or factor < 1:
        raise ValueError(
            f'scaled() needs a whole number of 1 or more, such as 2, but got {factor!r}.'
        )
    rows = tuple(
        ''.join(letter * factor for letter in row)
        for row in self.rows
        for _ in range(factor)
    )
    return ArtText(rows, self.palette)

apply

apply(patch: ArtPatch) -> ArtText

The art with a patch applied: its runs written, its new colours added.

Raises:

  • ValueError –

    A run is outside the art, or uses a letter neither palette names.

Source code in xnano/ai/models/art.py
def apply(self, patch: ArtPatch) -> ArtText:
    """
    The art with a patch applied: its runs written, its new colours added.

    Raises:
        ValueError: A run is outside the art, or uses a letter neither palette names.
    """
    palette = {**self.palette, **patch.new_colors}
    grid = [list(row) for row in self.rows]
    for run in patch.runs:
        if (
            not 0 <= run.row < self.height
            or run.column < 0
            or (run.column + len(run.letters) > self.width)
        ):
            raise ValueError(
                f'The run at row {run.row}, column {run.column} with '
                f'{len(run.letters)} letters is outside the art, which is {self.width} '
                f'by {self.height} pixels.'
            )
        for offset, letter in enumerate(run.letters):
            grid[run.row][run.column + offset] = letter
    return ArtText(tuple(''.join(row) for row in grid), palette)

ArtModel

ArtModel(model: Model | KnownModelName | str | None = None, *, strategy: ArtStrategy = 'program', width: ArtSize = (None, _DEFAULT_MOST), height: ArtSize = (None, _DEFAULT_MOST), max_colors: int | None = None, style: str | None = None, critique: int = 0, critic: Model | KnownModelName | str | None = None, image_model: ImageGenerationModel | str | None = None, 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

Generate and edit pixel art: xnano.Art from a description.

A piece larger than 12 pixels is drawn in two steps. First the model sketches it: the size, a palette of its masses (hair, face, body), and a few big shapes on a grid of blocks of 2 by 2 pixels, which settles the proportions and the placement of each part. Then it draws the piece at full size over that sketch, in the form of its strategy, as flat colours: one base colour per material, and the details; a drawing that leaves the composition of its sketch is sent back. A piece of 12 pixels or less is drawn in one step. The renderer then finishes the piece the way a pixel artist does, with the light from the top left: lone pixels take the colour around them, the silhouette gets an outline inside it in a dark colour of its own, and each material gets a shadow along its lower-right edges and a highlight along its upper-left edges, in colours shifted in hue. The model names its colours by role (base, skin, detail, accent, and outline, shadow or highlight when it draws those itself, which the renderer then leaves alone) under letters. Every answer is checked as it arrives: a size outside the range, an unknown letter, too many colours or a program that fails goes back to the model with the exact fault. A safe repair (a colour written '#f8c', a code fence around the program) is made instead of a retry and reported in last_generation, as is what the renderer added. Built-in references, the two closest to each request, show the craft in the strategy's own form; the 'art-references' library of xnano.ai.assets adds more when it is installed.

An image_model draws the piece as a picture instead: an image model paints the sprite scaled up on a flat background, and the picture's own pixel grid is read back into pixel art, one sample per drawn pixel, the background keyed out, the sprite cropped to its bounds and shrunk by a whole factor when it is larger than asked, and its colours reduced to the palette. The language model then edits and critiques that art as it does any other.

Parameters:

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

    The language model to ask.

  • strategy (ArtStrategy, default: 'program' ) –

    How the model writes the art: 'program' (the default: a short program of rectangles, ellipses, polygons, mirroring and an outline) or 'svg' (an SVG drawing, for round and diagonal forms).

  • width (ArtSize, default: (None, _DEFAULT_MOST) ) –

    The width of what generate makes, in the forms of ArtSize; each call can give its own.

  • height (ArtSize, default: (None, _DEFAULT_MOST) ) –

    The height, in the same forms.

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

    The most colours a piece may have; None scales with the size, from about 5 at 8 by 8 to 16 at 32 by 32.

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

    How the art should look, such as 'chunky outlines, warm palette'.

  • critique (int, default: 0 ) –

    How many rounds of critique generate runs, unless a call gives its own: in each, a vision model sees the piece as an image and lists what to fix, the model draws it again, and the piece with the best score is kept. 0 by default.

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

    The vision model that critiques; None asks model, which must then see images.

  • image_model (ImageGenerationModel | str | None, default: None ) –

    An image generation model that draws the piece as a picture, by name ('openrouter:google/gemini-2.5-flash-image', or one pydantic-ai knows such as 'openai:gpt-image-1') or as a pydantic-ai ImageGenerationModel; None draws with model in the form of strategy.

  • 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 fails its checks 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:

  • strategy (ArtStrategy) –

    How the model writes the art.

  • critique –

    How many rounds of critique generate runs.

  • critic –

    The vision model that critiques, or None for the model itself.

  • image_model –

    The image generation model that draws, or None.

  • last_generation (GenerationReport | None) –

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

Examples:

from xnano.ai.models.art import ArtModel, ArtText
from xnano.ai.testing import scripted_model

answer = {
    'layout': 'A coin filling the canvas.',
    'palette': [
        {'letter': 'o', 'role': 'outline', 'color': '#1a1c2c'},
        {'letter': 'y', 'role': 'base', 'color': '#ffcd75'},
    ],
    'width': 4,
    'height': 4,
    'program': "ellipse(0, 0, W, H, 'o'); rect(1, 1, 2, 2, 'y')",
}
artist = ArtModel(scripted_model(answer).model, width=4, height=4)
coin = artist.generate('a gold coin')
assert ArtText.from_art(coin).rows == ('.oo.', 'oyyo', 'oyyo', '.oo.')
assert artist.last_generation.attempts == 1

Create the art model; nothing is sent until the first call.

Raises:

  • ValueError –

    strategy is not one of the strategies, max_colors is not a whole number from 2 to 25, or critique is not a whole number from 0 to 3.

Methods:

  • generate_async –

    Draw pixel art from a description, with await.

  • generate –

    Draw pixel art from a description, waiting for it.

  • edit_async –

    Change pixel art as asked, with await: a patch of the pixels that change.

  • edit –

    Change pixel art as asked, waiting for it.

  • variants_async –

    Make one edit of the art for each request, all at once, with await.

  • variants –

    Make one edit of the art for each request, all at once, waiting for them.

  • animate_async –

    Animate pixel art, with await: one patch of the art for each frame.

  • animate –

    Animate pixel art, 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/art.py
def __init__(
    self,
    model: Model | KnownModelName | str | None = None,
    *,
    strategy: ArtStrategy = 'program',
    width: ArtSize = (None, _DEFAULT_MOST),
    height: ArtSize = (None, _DEFAULT_MOST),
    max_colors: int | None = None,
    style: str | None = None,
    critique: int = 0,
    critic: Model | KnownModelName | str | None = None,
    image_model: ImageGenerationModel | str | None = None,
    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 art model; nothing is sent until the first call.

    Raises:
        ValueError: ``strategy`` is not one of the strategies, ``max_colors`` is not a
            whole number from 2 to 25, or ``critique`` is not a whole number from 0 to 3.
    """
    _check_critique(critique)
    if strategy not in _STRATEGY_INSTRUCTIONS:
        raise ValueError(
            f"strategy must be 'program' or 'svg', but was {strategy!r}."
        )
    if max_colors is not None and (
        isinstance(max_colors, bool)
        or not isinstance(max_colors, int)
        or not 2 <= max_colors <= 25
    ):
        raise ValueError(
            f'max_colors must be a whole number from 2 to 25, or None, but was '
            f'{max_colors!r}.'
        )
    parts = [
        _STRATEGY_INSTRUCTIONS[strategy],
        _SKETCH_INSTRUCTIONS,
        instructions or '',
    ]
    if style:
        parts.append(f'Draw in this style: {style}.')
    super().__init__(
        model,
        instructions='\n\n'.join(part for part in parts if part),
        model_settings=model_settings,
        capabilities=capabilities,
        retries=retries,
        usage_limits=usage_limits,
        thinking=thinking,
        cache=cache,
    )
    self.strategy: ArtStrategy = strategy
    self.style = style
    self._width = width
    self._height = height
    self._max_colors = max_colors
    self.critique = critique
    self.critic = critic
    self.image_model = image_model
    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: ArtSize = None, height: ArtSize = None, symmetrical: bool = False, braille: bool = False, borders: bool = False, candidates: int = 1, critique: int | None = None, symbol: str | None = None) -> Coroutine[Any, Any, Art]

Draw pixel art from a description, with await.

The sizes are read when this is called; await the result for the art.

Parameters:

  • request (str) –

    What to draw, such as 'a knight with a red plume'.

  • evidence (object, default: None ) –

    What the art is for, such as the hook's context; see Evidence.

  • width (ArtSize, default: None ) –

    The width; None uses the model's.

  • height (ArtSize, default: None ) –

    The height; None uses the model's.

  • symmetrical (bool, default: False ) –

    Whether the piece is symmetric about its vertical middle, like a face or a creature seen from the front. The model then draws only the left half, which is mirrored to make the right half (an odd width shares its middle column), so the two sides match exactly. False by default.

  • braille (bool, default: False ) –

    Whether the art shows as braille dots, two by four per terminal cell in one colour per cell: a finer, drawing-like look that pixel art cannot have. The model is told, and draws for it. False by default.

  • borders (bool, default: False ) –

    Whether the art shows one pixel per cell, its edge traced in box-drawing characters and its inside filled with colour: the look of a terminal, which pixel art cannot have. The model is told that a cell is twice as tall as it is wide, and draws for it. False by default.

  • candidates (int, default: 1 ) –

    How many pieces to draw at once; the one that is valid, within its colours and the most connected is kept.

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

    How many rounds of critique to run; None uses the model's. See Critique.

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

    A name to register the art under in symbols.

Returns:

Raises:

  • ValueError –

    A size is not one of the forms of ArtSize, candidates is not 1 or more, or critique is not a whole number from 0 to 3.

  • GenerationError –

    No answer could be made into the art, even after the retries; its generation lists every problem, when awaited.

  • TerminalError –

    The model could not be reached (ai.model), when awaited.

Source code in xnano/ai/models/art.py
def generate_async(
    self,
    request: str,
    evidence: object = None,
    *,
    width: ArtSize = None,
    height: ArtSize = None,
    symmetrical: bool = False,
    braille: bool = False,
    borders: bool = False,
    candidates: int = 1,
    critique: int | None = None,
    symbol: str | None = None,
) -> Coroutine[Any, Any, Art]:
    """
    Draw pixel art from a description, with ``await``.

    The sizes are read when this is called; await the result for the art.

    Args:
        request: What to draw, such as ``'a knight with a red plume'``.
        evidence: What the art is for, such as the hook's context; see
            [`Evidence`][xnano.ai.Evidence].
        width: The width; ``None`` uses the model's.
        height: The height; ``None`` uses the model's.
        symmetrical: Whether the piece is symmetric about its vertical middle, like a
            face or a creature seen from the front. The model then draws only the left
            half, which is mirrored to make the right half (an odd width shares its
            middle column), so the two sides match exactly. ``False`` by default.
        braille: Whether the art shows as braille dots, two by four per terminal cell in
            one colour per cell: a finer, drawing-like look that pixel art cannot have.
            The model is told, and draws for it. ``False`` by default.
        borders: Whether the art shows one pixel per cell, its edge traced in box-drawing
            characters and its inside filled with colour: the look of a terminal, which
            pixel art cannot have. The model is told that a cell is twice as tall as it
            is wide, and draws for it. ``False`` by default.
        candidates: How many pieces to draw at once; the one that is valid, within its
            colours and the most connected is kept.
        critique: How many rounds of critique to run; ``None`` uses the model's. See
            [`Critique`][xnano.ai.Critique].
        symbol: A name to register the art under in [`symbols`][xnano.symbols].

    Returns:
        A coroutine that gives the [`Art`][xnano.art.Art].

    Raises:
        ValueError: A size is not one of the forms of ``ArtSize``, ``candidates`` is not
            1 or more, or ``critique`` is not a whole number from 0 to 3.
        GenerationError: No answer could be made into the art, even after the retries;
            its ``generation`` lists every problem, when awaited.
        TerminalError: The model could not be reached (``ai.model``), when awaited.
    """
    widths = _pixel_range(self._width if width is None else width, 'width')
    heights = _pixel_range(self._height if height is None else height, 'height')
    if (
        isinstance(candidates, bool)
        or not isinstance(candidates, int)
        or candidates < 1
    ):
        raise ValueError(
            f'candidates must be a whole number of 1 or more, but was {candidates!r}.'
        )
    for name, flag in (
        ('symmetrical', symmetrical),
        ('braille', braille),
        ('borders', borders),
    ):
        if not isinstance(flag, bool):
            raise ValueError(f'{name} must be True or False, but was {flag!r}.')
    rounds = self.critique if critique is None else _check_critique(critique)
    return self._generate(
        request,
        snapshot(evidence),
        widths,
        heights,
        _Look(symmetrical, braille, borders),
        candidates,
        rounds,
        symbol,
    )

generate

generate(request: str, evidence: object = None, *, width: ArtSize = None, height: ArtSize = None, symmetrical: bool = False, braille: bool = False, borders: bool = False, candidates: int = 1, critique: int | None = None, symbol: str | None = None) -> Art

Draw pixel art from a description, waiting for it.

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

Source code in xnano/ai/models/art.py
def generate(
    self,
    request: str,
    evidence: object = None,
    *,
    width: ArtSize = None,
    height: ArtSize = None,
    symmetrical: bool = False,
    braille: bool = False,
    borders: bool = False,
    candidates: int = 1,
    critique: int | None = None,
    symbol: str | None = None,
) -> Art:
    """
    Draw pixel art from a description, waiting for it.

    The same as [`generate_async`][xnano.ai.models.art.ArtModel.generate_async], for code that does
    not await.
    """
    return _run_blocking(
        self.generate_async(
            request,
            evidence,
            width=width,
            height=height,
            symmetrical=symmetrical,
            braille=braille,
            borders=borders,
            candidates=candidates,
            critique=critique,
            symbol=symbol,
        ),
        'generate',
    )

edit_async

edit_async(art: Art, request: str, *, protect: Sequence[str] = (), allow_new_colors: bool = False, max_changes: float = 0.5, mode: EditMode = 'auto', symbol: str | None = None) -> Coroutine[Any, Any, Art]

Change pixel art as asked, with await: a patch of the pixels that change.

The art itself is not changed: a new Art is returned, so when the edit fails the art you had is still there.

Parameters:

  • art (Art) –

    The art to change.

  • request (str) –

    The change, such as 'give the knight a blue cape'.

  • protect (Sequence[str], default: () ) –

    Roles or letters whose pixels must not change, such as ['outline', 'skin'].

  • allow_new_colors (bool, default: False ) –

    Whether the edit may add colours to the palette.

  • max_changes (float, default: 0.5 ) –

    The largest share of the drawn pixels a patch may change; a larger change is drawn again whole (mode='auto') or refused.

  • mode (EditMode, default: 'auto' ) –

    'patch', 'redraw', or 'auto' for the model to choose.

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

    A name to register the new art under in symbols.

Returns:

Raises:

  • ValueError –

    mode or max_changes is out of range, or protect names a role or letter the art does not have.

  • GenerationError –

    No answer made a valid edit, when awaited.

Source code in xnano/ai/models/art.py
def edit_async(
    self,
    art: Art,
    request: str,
    *,
    protect: Sequence[str] = (),
    allow_new_colors: bool = False,
    max_changes: float = 0.5,
    mode: EditMode = 'auto',
    symbol: str | None = None,
) -> Coroutine[Any, Any, Art]:
    """
    Change pixel art as asked, with ``await``: a patch of the pixels that change.

    The art itself is not changed: a new [`Art`][xnano.art.Art] is returned, so when the
    edit fails the art you had is still there.

    Args:
        art: The art to change.
        request: The change, such as ``'give the knight a blue cape'``.
        protect: Roles or letters whose pixels must not change, such as
            ``['outline', 'skin']``.
        allow_new_colors: Whether the edit may add colours to the palette.
        max_changes: The largest share of the drawn pixels a patch may change; a
            larger change is drawn again whole (``mode='auto'``) or refused.
        mode: ``'patch'``, ``'redraw'``, or ``'auto'`` for the model to choose.
        symbol: A name to register the new art under in [`symbols`][xnano.symbols].

    Returns:
        A coroutine that gives the new art.

    Raises:
        ValueError: ``mode`` or ``max_changes`` is out of range, or ``protect`` names a
            role or letter the art does not have.
        GenerationError: No answer made a valid edit, when awaited.
    """
    if mode not in ('auto', 'patch', 'redraw'):
        raise ValueError(
            f"mode must be 'auto', 'patch' or 'redraw', but was {mode!r}."
        )
    if isinstance(max_changes, bool) or not 0 < max_changes <= 1:
        raise ValueError(
            f'max_changes must be a share above 0 and at most 1, such as 0.5, but was '
            f'{max_changes!r}.'
        )
    text = ArtText.from_art(art)
    protected = _protected_letters(text, protect)
    return self._edit(
        text, request, protected, allow_new_colors, max_changes, mode, symbol
    )

edit

edit(art: Art, request: str, *, protect: Sequence[str] = (), allow_new_colors: bool = False, max_changes: float = 0.5, mode: EditMode = 'auto', symbol: str | None = None) -> Art

Change pixel art as asked, waiting for it.

The same as edit_async.

Examples:

from xnano.ai.models.art import ArtModel, ArtText, PaletteColor
from xnano.ai.testing import scripted_model

coin = ArtText(
    rows=('.oo.', 'oyyo', '.oo.'),
    palette={
        'o': PaletteColor('outline', '#1a1c2c'),
        'y': PaletteColor('base', '#ffcd75'),
    },
).to_art()
patch = {'runs': [{'row': 1, 'column': 1, 'letters': 'oo'}], 'new_colors': []}
artist = ArtModel(scripted_model(('patch', patch)).model)
dented = artist.edit(coin, 'put a dent in the middle')
assert dented.pixel(1, 1) == coin.pixel(0, 1)
Source code in xnano/ai/models/art.py
def edit(
    self,
    art: Art,
    request: str,
    *,
    protect: Sequence[str] = (),
    allow_new_colors: bool = False,
    max_changes: float = 0.5,
    mode: EditMode = 'auto',
    symbol: str | None = None,
) -> Art:
    """
    Change pixel art as asked, waiting for it.

    The same as [`edit_async`][xnano.ai.models.art.ArtModel.edit_async].

    Examples:
        ```python
        from xnano.ai.models.art import ArtModel, ArtText, PaletteColor
        from xnano.ai.testing import scripted_model

        coin = ArtText(
            rows=('.oo.', 'oyyo', '.oo.'),
            palette={
                'o': PaletteColor('outline', '#1a1c2c'),
                'y': PaletteColor('base', '#ffcd75'),
            },
        ).to_art()
        patch = {'runs': [{'row': 1, 'column': 1, 'letters': 'oo'}], 'new_colors': []}
        artist = ArtModel(scripted_model(('patch', patch)).model)
        dented = artist.edit(coin, 'put a dent in the middle')
        assert dented.pixel(1, 1) == coin.pixel(0, 1)
        ```
    """
    return _run_blocking(
        self.edit_async(
            art,
            request,
            protect=protect,
            allow_new_colors=allow_new_colors,
            max_changes=max_changes,
            mode=mode,
            symbol=symbol,
        ),
        'edit',
    )

variants_async

variants_async(art: Art, requests: Sequence[str], **edit_options: Any) -> Coroutine[Any, Any, list[Art]]

Make one edit of the art for each request, all at once, with await.

Parameters:

  • art (Art) –

    The art to change.

  • requests (Sequence[str]) –

    One change for each variant, such as ['winter coat', 'chain mail'].

  • edit_options (Any, default: {} ) –

    The keywords of edit, for every variant.

Returns:

Source code in xnano/ai/models/art.py
def variants_async(
    self, art: Art, requests: Sequence[str], **edit_options: Any
) -> Coroutine[Any, Any, list[Art]]:
    """
    Make one edit of the art for each request, all at once, with ``await``.

    Args:
        art: The art to change.
        requests: One change for each variant, such as ``['winter coat', 'chain mail']``.
        edit_options: The keywords of [`edit`][xnano.ai.models.art.ArtModel.edit], for every
            variant.

    Returns:
        A coroutine that gives the variants, in the order of the requests.
    """
    edits = [self.edit_async(art, request, **edit_options) for request in requests]

    async def gather() -> list[Art]:
        return list(await asyncio.gather(*edits))

    return gather()

variants

variants(art: Art, requests: Sequence[str], **edit_options: Any) -> list[Art]

Make one edit of the art for each request, all at once, waiting for them.

The same as variants_async.

Source code in xnano/ai/models/art.py
def variants(
    self, art: Art, requests: Sequence[str], **edit_options: Any
) -> list[Art]:
    """
    Make one edit of the art for each request, all at once, waiting for them.

    The same as [`variants_async`][xnano.ai.models.art.ArtModel.variants_async].
    """
    return _run_blocking(
        self.variants_async(art, requests, **edit_options), 'variants'
    )

animate_async

animate_async(art: Art, request: str, *, frames: int = 2, fps: float = 4.0) -> Coroutine[Any, Any, Animation]

Animate pixel art, with await: one patch of the art for each frame.

Every frame is a patch of the same base art, so the frames never drift away from it.

Parameters:

  • art (Art) –

    The art to animate.

  • request (str) –

    The motion, such as 'a two-frame idle bob'.

  • frames (int, default: 2 ) –

    How many frames.

  • fps (float, default: 4.0 ) –

    How many frames are shown each second.

Returns:

Raises:

  • ValueError –

    frames is not a whole number from 2 to 16, or fps is not above 0.

  • GenerationError –

    No answer made valid frames, when awaited.

Source code in xnano/ai/models/art.py
def animate_async(
    self, art: Art, request: str, *, frames: int = 2, fps: float = 4.0
) -> Coroutine[Any, Any, Animation]:
    """
    Animate pixel art, with ``await``: one patch of the art for each frame.

    Every frame is a patch of the same base art, so the frames never drift away from it.

    Args:
        art: The art to animate.
        request: The motion, such as ``'a two-frame idle bob'``.
        frames: How many frames.
        fps: How many frames are shown each second.

    Returns:
        A coroutine that gives the [`Animation`][xnano.ai.models.art.Animation].

    Raises:
        ValueError: ``frames`` is not a whole number from 2 to 16, or ``fps`` is not
            above 0.
        GenerationError: No answer made valid frames, when awaited.
    """
    if (
        isinstance(frames, bool)
        or not isinstance(frames, int)
        or not 2 <= frames <= 16
    ):
        raise ValueError(
            f'frames must be a whole number from 2 to 16, but was {frames!r}.'
        )
    if isinstance(fps, bool) or not fps > 0:
        raise ValueError(f'fps must be above 0, such as 4, but was {fps!r}.')
    return self._animate(ArtText.from_art(art), request, frames, float(fps))

animate

animate(art: Art, request: str, *, frames: int = 2, fps: float = 4.0) -> Animation

Animate pixel art, waiting for it.

The same as animate_async.

Source code in xnano/ai/models/art.py
def animate(
    self, art: Art, request: str, *, frames: int = 2, fps: float = 4.0
) -> Animation:
    """
    Animate pixel art, waiting for it.

    The same as [`animate_async`][xnano.ai.models.art.ArtModel.animate_async].
    """
    return _run_blocking(
        self.animate_async(art, request, frames=frames, fps=fps), 'animate'
    )

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)

Animation dataclass

Animation(frames: tuple[Art, ...], fps: float)

Frames of pixel art shown one after another: what ArtModel.animate makes.

Write it like art, with canvas.screen.write(animation): it shows the frame the canvas's clock is on, and moves to the next one fps times a second.

Attributes:

  • frames (tuple[Art, ...]) –

    The frames, in order.

  • fps (float) –

    How many frames are shown each second.

Examples:

import xnano
from xnano.ai.models.art import Animation

blink = Animation(
    frames=(xnano.pixel_art(['#'], {'#': 'white'}), xnano.pixel_art(['.'], {})),
    fps=2,
)
with xnano.new(width=2, height=1) as canvas:
    canvas.screen.write(blink)
    assert blink.frame_at(0.0) is blink.frames[0]
    assert blink.frame_at(0.5) is blink.frames[1]

Methods:

__post_init__

__post_init__() -> None

Check the frames and the rate.

Source code in xnano/ai/models/art.py
def __post_init__(self) -> None:
    """Check the frames and the rate."""
    if not self.frames:
        raise ValueError('An Animation needs at least one frame.')
    if isinstance(self.fps, bool) or not self.fps > 0:
        raise ValueError(f'fps must be above 0, such as 4, but was {self.fps!r}.')

frame_at

frame_at(seconds: float) -> Art

The frame shown seconds after the animation started.

Source code in xnano/ai/models/art.py
def frame_at(self, seconds: float) -> Art:
    """The frame shown ``seconds`` after the animation started."""
    return self.frames[int(seconds * self.fps) % len(self.frames)]

__xnano_write__

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

The frame the canvas's clock is on.

Source code in xnano/ai/models/art.py
def __xnano_write__(self, context: Context[object, object]) -> Art:
    """The frame the canvas's clock is on."""
    return self.frame_at(context.clock.elapsed_seconds)