Reference

API reference

Every public function, option, environment variable and error in thunc 0.2, on one page. The guide pages explain each in context.

Functions

Name	What it does
`@thunc.function`	Turns a signature and docstring into an AI-backed function. Options: `instructions=`, `system=`, `ensure=`, `retries=2`, `backend=`, `model=`, `cache=False`, `write=False` (experimental, thunc write: the function writes its own body). The body must be empty (`...`); real code raises `TypeError`. `async def` works.
`thunc.call`	One prompt. Inputs are sent separately from the instructions. `name=` groups its cached answers.
`thunc.acall`	`thunc.call`, to await.
`thunc.amap`	`thunc.map`, to await: up to `workers` calls at once, in input order. Takes `async def` and plain functions.
`thunc.map`	Runs calls in parallel, keeping the input order.
`thunc.configure`	Process-wide settings.
`thunc.clear_cache`	Deletes saved answers: all of them, one function's, or those older than an age. Returns how many.
`thunc.cache_info`	What's in the cache: a list of `thunc.CacheGroup`, one per function, with its entries, size on disk and newest answer.
`thunc.Agent`	An agent: a name, a working directory, permissions and tasks.
`@agent.task`, `@thunc.agent`	Declare a task on an agent, or an agent with a single task.
`agent.call`	A task built in code, like `thunc.call`.
`agent.run`	Runs a task and returns a `thunc.Run` with what happened.
`thunc.prompts`	System prompt presets for agents: `CODING`, `CODE_REVIEW`, `ANALYSIS`.
`thunc.temporal`	Optional durable runtime: `Registry`, `Worker`, `Runtime`. Needs `thunc[temporal]`.

Signatures

@thunc.function(*, instructions=None, retries=2, ensure=None, backend=None, model=None,
                system=None, cache=False, write=False)

thunc.call(instructions, inputs=None, *, returns=str, ensure=None, retries=2, backend=None,
           model=None, system=None, cache=False, name=None)

thunc.map(func, items, *, workers=8)

await thunc.acall(...)  # the arguments of thunc.call

await thunc.amap(func, items, *, workers=8)

thunc.clear_cache(function=None, *, older_than=None)  # function or name; timedelta or seconds

thunc.Agent(name, *, workdir, system=None, permissions=(), env=None, command_timeout=120,
            follow=False, protocol=None, tools=(), timeout=None, max_steps=40,
            retries=2, backend=None, model=None, effort=None)

thunc.configure

Sets defaults for every call. Arguments left out keep their current value.

backend: "anthropic", "openai", "claude-code", "codex" or "jev". See choosing a backend.
api_key: The API key for anthropic or openai. An api_key with no backend means anthropic. Never sent to Jev.
model: The default model. anthropic defaults to claude-opus-5-5, openai to gpt-5.5.
timeout: The time limit for each backend request, in seconds. Default 300.
trace: Path of a JSONL file that records every call.
cache_dir: Where cache=True answers go. Default .thunc_cache.
system: A system prompt for every call in place of thunc's default. A per-call system= wins.
agents_dir: Where agents keep memory and run records. Default .thunc_agents.
recordings: A folder of recorded answers. Every call and agent run is answered from it and no model is asked; one that wasn't recorded raises ThuncError. See record and replay.

Environment variables

Variable	Means
`THUNC_BACKEND`	The backend, when neither the call nor `configure` sets one
`ANTHROPIC_API_KEY`	Claude API key; selects `anthropic` when no backend is set
`OPENAI_API_KEY`	OpenAI API key; selects `openai` when no backend is set and there's no Anthropic key
`OPENAI_BASE_URL`	Points the `openai` backend at another server, such as a local model
`JEV_API_KEY`	Jev key, in place of `jev login`
`THUNC_TRACE`	Trace file, like `configure(trace=...)`
`THUNC_CACHE_DIR`	Cache folder, like `configure(cache_dir=...)`; also read by the `thunc` command
`THUNC_AGENTS_DIR`	Agents folder, like `configure(agents_dir=...)`
`THUNC_RECORDINGS`	Recordings folder, like `configure(recordings=...)`: replay recorded answers
`THUNC_RECORD`	`1` asks the model and saves every answer to the recordings folder; `missing` saves only the answers it lacks
`THUNC_WRITE`	`0` stops thunc write from writing, as in production; so does `CI`

Errors

thunc.ThuncError: No valid answer arrived after the retries, the backend failed, or nothing is configured. Also raised when a function is declared with an unsupported return type.
thunc.AgentError: A ThuncError from an agent run that hit max_steps, never gave a valid value, or lost its backend. .run is the record up to that point.
thunc.errors.TransientError: A ThuncError that asking again may fix: a timeout, a lost connection, a rate limit, a server error, or a CLI call that ended in an error. An agent run retries the step twice before failing; thunc.call and @thunc.function don't retry it.
TypeError: Raised when a function is declared with code in its body, or with no docstring and no instructions=.

Deprecations

Part of the API that's going away keeps working for at least two minor releases, and warns with thunc.ThuncDeprecationWarning where you use it, naming the release that removes it and what to use instead. The warning is shown by default, once per place in your code; turn it off with warnings.filterwarnings("ignore", category=thunc.ThuncDeprecationWarning), or make it an error in your tests with -W error::thunc.ThuncDeprecationWarning. The changelog lists deprecations and removals in each release. Experimental features (thunc write) can change without one.

Command line

thunc run --profile app.py --limit 20             # run a script, then print where the time went
thunc run --profile -m myapp.triage               # a module, as with python -m
thunc write app.py::minutes --dry-run             # experimental: write a write=True function now (--dry-run: show the diff)
thunc cache list                                   # saved answers per function
thunc cache clear                                  # everything
thunc cache clear --function urgency               # one function (repeat for several)
thunc cache clear --older-than 30d --dry-run       # what would go, without deleting

Also python -m thunc, and thunc --version. thunc run runs the program as python would and passes its exit code through; --profile adds the performance report. thunc write (experimental) writes a write=True function ahead of its first call. The cache commands take --cache-dir, or read THUNC_CACHE_DIR; point --cache-dir at a recordings folder to list or clear its recordings.

Limitations

Docstrings disappear under python -OO. Use instructions= there.

Edit this page on GitHub