Adding a model
Affordance turns an app into the exact tokens a model reads. To do that for a model it needs that model's chat format: how the model's publisher writes a conversation, its tools and its replies as tokens. This page says how to check whether a model is supported, how to add one that is not, and how to send the addition to the project.
#Check whether your model is supported
Models are listed in views/index.json under their Hugging Face name with / written as __:
grep '"Qwen__Qwen3.5-2B"' views/index.jsonIf the name is there, name the model as the template of your model binding and run:
{"model": {"kind": "completions", "url": "http://127.0.0.1:8000", "template": "Qwen/Qwen3.5-2B"}}A fine-tune usually keeps its base model's chat template. If your fine-tune is not listed but
its base model is, the base model's name works as the template, as long as the two repositories
have the same chat_template.jinja and tokenizer.
#Add a model with one command
You need a checkout of this repository, Python through uv, and a release build:
uv sync
cargo build --release --features reference-tests --examples
uv run python tools/add_model.py ORG/NAME
cargo build --releaseThe command does five things and says which one it is on:
- It fetches the model's tokenizer and chat template files from Hugging Face into
ref/models/. It does not fetch weights. - It renders the official output: the model's own template and tokenizer, run by Hugging
Face's
apply_chat_template, on six sets of test conversations (about 960 conversations). - It converts the template to a view (
tools/jinja2tsx.py) underviews/third_party/, and checks the view against the official output on every conversation, token for token. - It measures what an agent needs to read the model's replies: the tokens that end a reply, whether the prompt ends inside open thinking, and how the model writes a tool call.
- It registers the model in
views/index.json. For a model that takes pictures it also records how the model's processor turns a picture into tokens, where the processor is a design it knows, so a style sheet can size the model's pictures (img { max-tokens: .. }).
If a step fails, the command names the step and the reason, and registers nothing. The second
cargo build puts the new index into the binary.
#Try it
Render a conversation in the model's format without a server:
./target/release/affordance render tests/fixtures/any_model_agent.tsx \
--template ORG/NAME --tokenizer ref/tokenizers/ORG__NAME.json \
--state <(echo '{"log": [{"kind": "input", "content": "Hello."}]}')Then step an agent on it, as the test suite does for every registered model:
AFFORDANCE_ALL_MODELS=1 cargo test --release --features reference-tests --test suite any_model::#When the command fails
"its tokenizer is a Python class in the repository." Some publishers ship the tokenizer as
Python code and not as tokenizer.json (Kimi, InternLM, Phi-3-small). Affordance does not run a
model repository's code on your machine. ref/sandbox/run.sh ORG__NAME runs that code in a
Docker container with no network and a read-only file system, and
ref/sandbox/build_tokenizer.py ORG__NAME builds a standard tokenizer from the model's data
file and keeps it only if it gives the same ids as the publisher's code on every text. After
both pass, run tools/add_model.py again.
"converter does not handle ..." The template uses a Jinja feature the converter has not met.
Open an issue with the model's name and the message. The fix belongs in tools/jinja2tsx.py
or views/common/jinja.tsx, and it usually unlocks other models too.
"the converted template does not match the official output." The view renders, but some
conversation gives different tokens. ./target/release/affordance check --only ORG__NAME
prints the first difference for each failing conversation. This is a bug in the converter or
its runtime; open an issue with that output.
"its tool calls are not read yet." The model is registered and an agent can talk to it, but the model writes tool calls in a shape the reader does not handle. Open an issue with the model's name.
#Send it to the project
A model addition is a pull request with these files, all written by the command:
views/third_party/<org>/<model>.tsx, the converted template.views/third_party/<org>/NOTICE.md, which names the model, the revision the template was read at and its license. The template's text belongs to the model's publisher under that license.views/index.json, with the model's entry.ref/models.txt, with the model's line.views/templates.lock.json, with the hash of the model's template as it is today. A weekly job compares every registered template with its repository and names the ones a publisher has changed (tools/check_templates.pydoes the same by hand).
Steps:
git checkout -b add-ORG-NAME
git add views ref/models.txt
git commit -m "ORG/NAME's prompt format, matching its official template token for token"
git push -u origin add-ORG-NAME
gh pr create --fillIn the pull request, paste the command's output. A reviewer runs the same command and the
checks in tools/check-models.sh. The files under ref/models, ref/tokenizers and ref/out
stay on your machine: they are downloads and references, and the repository does not carry
them.
Source: docs/ADDING_A_MODEL.md, about 4 minutes to read.