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.Artfrom a description. -
Animation–Frames of pixel art shown one after another: what
ArtModel.animatemakes.
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
¶
PixelRun
dataclass
¶
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:
-
runs(tuple[PixelRun, ...]) –The pixels to set, in order.
-
new_colors(Mapping[str, PaletteColor]) –The colours the runs use that the palette does not have yet.
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
Artof 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
xpixels right andydown, inside the same size. -
recolor–The art with new colours for some letters, keeping their roles.
-
scaled–The art with every pixel made
factorpixels wide and tall. -
apply–The art with a patch applied: its runs written, its new colours added.
__post_init__
¶
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
¶
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.
palette_text
¶
palette_text() -> str
The palette as one line per letter, o = outline #1a1c2c, for a prompt.
shift
¶
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
¶
The art with new colours for some letters, keeping their roles.
Parameters:
Raises:
-
ValueError–A letter is not in the palette.
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
¶
The art with every pixel made factor pixels wide and tall.
Raises:
-
ValueError–factoris 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
¶
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
generatemakes, in the forms ofArtSize; 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;
Nonescales 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
generateruns, 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.0by default. -
critic(Model | KnownModelName | str | None, default:None) –The vision model that critiques;
Noneasksmodel, 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-aiImageGenerationModel;Nonedraws withmodelin the form ofstrategy. -
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;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:
-
strategy(ArtStrategy) –How the model writes the art.
-
critique–How many rounds of critique
generateruns. -
critic–The vision model that critiques, or
Nonefor the model itself. -
image_model–The image generation model that draws, or
None. -
last_generation(GenerationReport | None) –How the last call went, or
Nonebefore 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–strategyis not one of the strategies,max_colorsis not a whole number from 2 to 25, orcritiqueis 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
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/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;
Noneuses the model's. -
height(ArtSize, default:None) –The height;
Noneuses 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.
Falseby 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.
Falseby 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.
Falseby 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;
Noneuses the model's. SeeCritique. -
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,candidatesis not 1 or more, orcritiqueis not a whole number from 0 to 3. -
GenerationError–No answer could be made into the art, even after the retries; its
generationlists 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–modeormax_changesis out of range, orprotectnames 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
¶
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–framesis not a whole number from 2 to 16, orfpsis 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 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
¶
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)
Animation
dataclass
¶
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__–Check the frames and the rate.
-
frame_at–The frame shown
secondsafter the animation started. -
__xnano_write__–The frame the canvas's clock is on.