Polson

Polson is a framework for agentic co-creative visual art and graphic design, built on the principles of Enactive AI.

Polson runs in three modes:

The screenshot below show Polson running in Claude Desktop:

Managed mode allows you to use your existing agent subscription while terminal and graphics studio mode require API usage and access key.

Setup is the same whichever you use, bar which Python environment you install.

|

Once per checkout. All three modes share §1 and §2; §3 depends on which you want.

git clone https://github.com/allisterb/Polson
cd Polson

[./]build

That produces bin/cli, which is the MCP server every project's wiring points at.

Copy the example config into the built output and edit it:

cp ./appsettings.json.example ./bin/cli/appsettings.json

This is the only place a key lives — every mode reads this one file, so no two of them can disagree about which key. It is gitignored, and a rebuild does not overwrite it.

Run from the repository root. Nothing installs itself — package installation is always a deliberate act by a person.

There are two virtual environments and three locks, and which you need follows from the mode:

On Linux and macOS each is install.sh, taking the same optional driver argument. Create the environment first — python/ for the first two modes, python-adk/ for the third:

python3.13 -m venv python

Name the version, not python3. Where python3 is older — Ubuntu 22.04's is 3.10 — python3 -m venv builds the environment with that one silently, and the failure surfaces later and further away, as pip refusing a pinned package. On Debian and Ubuntu install python3.13-venv too, or venv fails on a missing ensurepip.

requirements.txt pins every package — transitive ones included — to an exact version and hash, and the install refuses anything that does not match.

The two environments are separate on purpose, and the names matter. ADK caps websockets<16 where the Antigravity SDK has no upper bound, so in one shared environment the second install silently wins and neither lock then describes what is actually there. See src/adk_agent/README.md.

Three modes, and nothing to choose between them permanently — they read and write the same projects, so the same directory can be driven by your own host today and by Polson tomorrow.

Polson generates the project; your host drives the agent — and pays for the model, which is why this is the cheapest way in.

[./]polson create-project projects roaster agy --workflow logo --type modern

[./]polson is ./polson on Linux and macOS and .\polson.ps1 on Windows. Both dispatch the verb — .NET for create-project, reset, eval, report, server and version; Python for studio and orchestrator — and both pass the exit code through. polson.cmd is gone: cmd cannot do the branching, and it reported success whatever the CLI actually returned.

The sdk argument decides what the config files are called — agy for Google Antigravity, claude for Claude Code:

Add --prompt "..." to write the brief in a line, or --brief <file> to supply it from a file. Either is treated as untrusted data and normalised before it is written.

Then fill in brief.md, open the directory with your agent host, and tell it to begin. Everything between the BRIEF-BEGIN and BRIEF-END markers is read as a client's statement, never as instructions to the agent.

The host owns tool policy while the host is running it. Polson writes the permissions file your host expects but cannot enforce it or check that it was honoured — which is why image generation is denied there and stated again as a rule in the instructions.

[./]polson reset projects/roaster

Clears the previous run and leaves everything else exactly as it is — the brief, the instructions including your own edits to them, the MCP wiring, the manifest. It takes the project's own path, so there is nothing to restate. --delete removes the run instead of archiving it, and is the only irreversible thing here.

Use create-project --reset instead when you want the project rebuilt as well, which is the case after the templates have changed:

[./]polson create-project projects roaster claude --reset

That regenerates every generated file — so a hand-edited CLAUDE.md goes back to the template — and needs the parent directory, the id and the sdk again. Both routes clear the run identically.

Either way it archives rather than deletes: events/, scripts/, artifacts/ and the files the agent wrote about itself (findings.md, critique_log.md, artwork.js, output.*) move to previous/<timestamp>/ with a README saying what they are. That default was paid for — an earlier version deleted, and took with it the only measurements saying whether a change had been worth making.

Two things stay put: brief.md, the one file a person authors, and .polson/, so a reset of the work is not a reset of the spend — the research and asset caches survive.

create-project --reset keeps what the project is, too. The workflow, type and profile recorded in project.json are inherited when you do not restate them, so it cannot quietly turn a drawing project into a logo one; naming --workflow still changes it, because that is someone asking. --force is the blunter neighbour: it regenerates every generated file including brief.md, which has cost a hand-written brief before.

The studio's pages work over a project whoever is driving it — the MCP server writes the record regardless of which host called it, so this only puts a reader on it. Nothing is started and nothing is spent.

With the base lock installed (§3), from the repo root:

[./]polson studio projects --observe-only

studio is the one verb the launcher sends to Python rather than to the .NET CLI; everything after it is forwarded verbatim, so --host, --port and --observe-only are the module's own options and [./]polson help studio prints them. Running it directly still works and is exactly equivalent, from src/: python -m studio ../projects --observe-only.

It serves http://127.0.0.1:8000 over a directory of projects, and gives you the live trace, the renders beside the scripts that made them, and the creative sense-making curve — the things polson report can only summarise afterwards.

The base lock deliberately carries no agent SDK. studio/ has no reference to one and the driver is imported lazily, so serving the pages and reading a record need none of it — 17 packages rather than 52. Install the driver lock instead if you also want the page's Start button, which turns this from observing into mode 2 with a page attached.

Think before binding beyond 127.0.0.1. A reachable studio is an open cost surface, and visitor-typed text reaches an agent holding tools.

With the driver lock installed, Polson hosts the agent itself through the Google Antigravity SDK and you direct it from the terminal:

[./]polson orchestrator projects/acme

No page, no port, nothing to watch — the agent asks its questions in the terminal and you answer. The record is written exactly as in every other mode, so polson report and the studio read it afterwards without knowing which mode produced it.

orchestrator is the launcher's other Python verb, and the only one that needs the driver lock. Run it on the base install and it says so before doing anything — naming the interpreter it found, what is in it, and the one command that fixes it — rather than failing on a ModuleNotFoundError from inside the SDK import. (Equivalent directly, from src/: python -m orchestrator ../projects/acme.)

Polson runs the agent on Google ADK and serves the whole studio — the commission form, the run pages and ADK's own console. This is the mode a visitor can be handed, and the one DEPLOY.md deploys.

python-adk/Scripts/python.exe -m uvicorn main:app --host 127.0.0.1 --port 8000 --app-dir src/adk_agent

On Linux or macOS the interpreter is at python-adk/bin/python.

Then open:

Projects are written to projects/ beside the checkout. Set POLSON_PROJECTS_DIR to put them elsewhere — they hold everything a run produces and are independent of the repo.

Useful environment variables, all optional:

Think before binding to 0.0.0.0. A public URL is an open cost surface, and visitor-typed text reaches an agent holding tools.

A workflow decides the stages the agent works through and the instructions it is given. A type narrows the visual direction.

Attach a document and the agent will read it. Anything you upload lands in the project's documents/ folder; Documents.list() is free and Documents.ask(path, question) puts the question to Gemini. It reads scanned PDFs with no text layer, so a screenplay or a scanned report works as a brief.

Everything a run produces stays in the project directory: renders in artifacts/, every executed script in scripts/, the record in events/, and the basis for any sourced figure in .polson/research/. docs/project-layout.md is the contract for all of it.

[./]polson report projects/acme

    events recorded        344
    scripts executed       33
    scripts failed         0
    renders recorded       33
    stage notes            160
    looked before drawing  175 probes across 13 of 33 scripts
    stages declared        32 across 6 sessions

    Nothing unaccounted for: every artifact traces to a render, every script to an execution.

The report is the machine-checkable half — script paths, durations, artifact paths, byte counts. The stages and notes beside it are the agent's own account of what it was doing, which is what makes a run legible rather than merely logged.

Mode 3 is the one that deploys, because it is the only one that hosts the agent and serves a page — the other two need either your own agent host or your own terminal. It runs as one container: the ADK runtime, the .NET engine, the SDK docs and the web interface. See DEPLOY.md for the Cloud Run path, and src/adk_agent/README.md for what the image contains and why.

AGPL-3.0.