Easel

Easel

Can an LLM paint with real brush strokes, rather than draw with pixels? Yes — this is the API for it.

Easel is a headless painting engine for AI agents: brushes, paint load, wet blending and canvas texture, driven from Python, from a shell, or over MCP. A brush carries a finite load of paint and runs out along a stroke. Paint lands wet and mixes with what is already there, in a pigment model where blue and yellow make green rather than grey. The canvas has tooth, and a brush low on paint catches only the high points — so dry brush is not a special effect, it is what happens when you run out of paint on rough canvas. Between strokes you look at your own work, which is the whole point: the engine is built for an agent that can see what it just did.

It is not a drawing library, not a rasteriser, and not an image generator — nothing here turns a prompt into a picture. You choose and make every mark. There are no layers, and no undo that costs nothing: you work in passes, and when something is wrong you paint over it.

You have to be able to see images. Every pass of the method ends by looking at what it did — s.look(), the rehearsal, the post-pass check — and none of that reaches a painter who cannot take an image back. A model without image input can drive the whole API and will get a picture out of the far end, but it cannot tell whether any of it landed; one painter in the 0.5.0 cohort said exactly that of its own finished painting. Vision is a requirement here, not a feature.

Read the guide before you paint. The engine is only the brush; PAINTER.md is the method, and six measured runs say the method is the half that matters. It ships inside the package, so there is nothing to go and find: `easel guide` prints its first page — the whole workflow, about 1,000 words — and easel guide --full prints the rest.

from easel import Session, blob, cell

s = Session(1024, 768, texture="linen", ground="toned_grey", seed=7) s.palette["shadow"] = s.palette.mix("ultramarine", "burnt_umber", 0.4)

s.block_in(blob(cell("D5")), brush="bristle", color="shadow", density=0.8) s.look(values=True) # check the value structure s.stroke([(0.2, 0.6), (0.6, 0.55), (0.9, 0.62)], "bristle", "yellow_ochre") s.export("painting.png")

Paintings, made this way

*Inside a car wash, from the driver's seat — 206 strokes of a 300 budget, 1152×720 linen, no reference photograph. The nineteen pass scripts it was painted from are beside it.*

*A laundromat at night, from across the street — 286 strokes of a 300 budget, 1024×768 linen, no reference photograph. The fourteen pass scripts it was painted from are beside it.*

*A heron in a flooded parking lot at dawn — 253 strokes of a 320 budget, 1024×768 rough canvas, no reference photograph. The same subject was painted twice by the same painter to separate two kinds of fault; PAINTINGS.md has both attempts side by side.*

Every one of these was painted by a language model working from PAINTER.md, one call to this API at a time, with no human hand on the canvas and nothing traced. Every stroke is in the log, every time-lapse was rebuilt from it, and the notes beside each painting say what went wrong as well as what went right. PAINTINGS.md gathers the record, and *The worked examples* below says what each one is made of.

If you are about to paint from the guide yourself: have you decided what to paint? If you have, these are yours to study and the scripts beside them are the best thing here. If you have not, do not look — a worked example names a subject and a named subject chooses for you, as six of six fresh sessions once demonstrated by painting a noun the guide had merely listed in passing. Decide first, then look.

The brushes themselves

*Every brush, size and pressure profile, on each canvas texture. Regenerate with python scripts/make_brush_sampler.py — this sheet is the project's primary test artefact, and looking at it catches what the test suite cannot.*

*A mass does not have to be a rectangle. Each row is one way of building a shape, each column a way of sweeping it; the last column is the box that mass would have been. Regenerate with python scripts/make_shape_sampler.py.*

Install

Requires Python 3.12 or newer. Only numpy and Pillow — nothing that is painful to build on Windows.

pip install easel-paint          # the engine, the CLI and the Python API

pip install "easel-paint[mcp]" # and the MCP server

from easel import Session, blob, cell      # the import the documents teach

import easel_paint # the same engine under the installed name

The distribution is `easel-paint`, never `easel`. PyPI carries an unrelated package called easel, so pip install easel gets somebody else's. Both import names work here — easel_paint re-exports easel — and every example is written with the short one.

From a checkout, pip install -e . and pip install -e ".[mcp]" do the same two things.

Either installs an easel command. Pip puts it in the interpreter's scripts directory, which is often not on PATH (it warns when it is not), so python -m easel ... is always available as the same command by another name.

The MCP server is an opt-in extra because nothing else in the engine imports it. See *MCP server* below.

If you are an LLM agent, read PAINTER.md

PAINTER.md is the guide written for you. It teaches the *workflow* — tone the ground, paint back to front, check values, refine, edges, highlights last — rather than listing functions, and it opens with *the first hour*: the whole method on one page, so the ten warm-up exercises come before anything else.

If you have already installed the package you do not need that link. All six documents ship inside the wheel: python -m easel guide prints the first hour, --full prints the rest, and easel.docs.read() hands you any of them as text. The sixth is DIAGNOSIS.md, an index of symptoms rather than a document to read — you have rehearsed a pass, it is wrong, and easel diagnose concentric rings prints the passage that measured it.

It is one file of five, and every rule in the five is stated once, in the file it belongs to, and linked from everywhere else. PAINTER.md is held to a word budget by the test suite so that it stays the file a painter can hold in their head; the numbers it quotes are measured in CALIBRATION.md, and what painters reported about their own sessions is kept there too rather than beside the rules.

The engine is designed around one habit:

Look every five to fifteen strokes. A stroke you did not look at was a guess.

llms.txt is the same signpost in the format a model fetching this repository is increasingly told to look for: the summary, what to know before reading further, and where each document is, in about 1,500 words.

What is in the box

| Passages and repairs | scumble(band, a, b, n) lays a soft passage as n overlapping passes stepping between two values — the thing a gradient tool would be