Guide

Backends

thunc runs on the Claude API, the OpenAI API, a local model, your Claude Code or Codex login, or TypeSafe's Jev. Pick one for the whole program, per function or per call.

Choosing a backend

For each call, thunc uses the first of these that is set:

backend= on the call or the function;
thunc.configure(backend=...);
the THUNC_BACKEND environment variable;
an API key: ANTHROPIC_API_KEY (or a configure(api_key=...) alone) selects anthropic, and otherwise OPENAI_API_KEY selects openai.

With none of these, the call raises ThuncError: No backend configured.

thunc.configure(backend="anthropic")        # the default for this program


@thunc.function(backend="jev")              # this function only
def needs_reply(message: str) -> bool:
    """Does this message ask a question or report a problem we should answer?"""
    ...


thunc.call("Summarise this.", {"text": doc}, backend="openai", model="gpt-5.5")  # this call only

Pick the model the same way, with model= or configure(model=...).

The backends

Backend	Uses	Needs
`anthropic`	The Claude API. Default model `claude-opus-5-5`	`pip install "thunc[anthropic]"` and `ANTHROPIC_API_KEY` or `configure(api_key=...)`
`openai`	The OpenAI Responses API. Default model `gpt-5.5`	`pip install "thunc[openai]"` and `OPENAI_API_KEY` or `configure(backend="openai", api_key=...)`
`claude-code`	Your local Claude Code login	The `claude` CLI, logged in
`codex`	Your local Codex login	The `codex` CLI, logged in
`jev`	TypeSafe's Jev judgment model, for `bool` and `Literal` answers	The `jev` CLI and `jev login` or `JEV_API_KEY`

Claude API and OpenAI API

The production backends. Set the key in the environment, or pass it with configure(api_key=...). OPENAI_BASE_URL points the openai backend at any server that speaks the OpenAI Responses API, which is how local models work.

Claude Code and Codex

claude-code and codex call your local CLI login, and are meant for cheap testing: no API key, no SDK. Both run with their own tools turned off, so the model can only answer; an agent on either gets only its own thunc tools, as native calls through an MCP server. Your system= replaces the CLI's built-in system prompt.

codex also ignores ~/.codex/config.toml (your MCP servers, plugins, notify command and model settings); your login still works.

Jev

Jev doesn't write text. It answers bool, Literal of strings (up to 255) and Literal of integers (as ordered levels) in about 0.3 seconds, and any other return type raises ThuncError before a request is sent. It's only used when you choose it: backend="jev" or THUNC_BACKEND=jev. The key comes from jev login or JEV_API_KEY, never configure(api_key=...), so Jev can be used for some functions alongside another backend's key.

Setup, options and troubleshooting are in the Jev guide.

Local models

The openai backend works with a local server through OPENAI_BASE_URL. This has been tested with LM Studio running openai/gpt-oss-20b:

export OPENAI_BASE_URL=http://localhost:1234/v1
export OPENAI_API_KEY=lm-studio  # any non-empty key works

thunc.configure(backend="openai", model="openai/gpt-oss-20b")

Small models need the retry more often, for example when they explain the answer instead of giving it alone. For agents on a server without function calling, use protocol="text".

Other settings

thunc.configure(timeout=...) sets the request timeout in seconds. Every configure argument left out keeps its current value, so you can call it more than once. The full list is in the API reference.

Edit this page on GitHub