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`. 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.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)

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)

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.

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=...)`

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=.

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 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. The cache commands take --cache-dir, or read THUNC_CACHE_DIR.

Limitations

There's no record/replay for tests yet. cache=True is per function; there's no switch that serves every call from disk and fails on a miss.
Literal results from thunc.call are typed as Any. @thunc.function has no such gap.
Docstrings disappear under python -OO. Use instructions= there.

Edit this page on GitHub