Recurse SDK

Author, package, and deploy Recurse applications.

Installation

Python 3.14 or newer is required. Install Recurse from PyPI:

pip install recurse-sdk

This installs both the recurse command and the Python API. Check the installation:

recurse --help

If you prefer uv, install the CLI as an isolated tool:

uv tool install recurse-sdk

Add the Python API to an application:

uv add recurse-sdk

Running or deploying an application also requires uv on your PATH to build its package.

The distribution ships two things:

• The recurse Python package: manifest validation, standards-based application packaging (recurse.build_bundle), and the runtime context tools use during a run (recurse.context).
• The recurse command: browser login, encrypted runtime-secret management, direct runs, MCP deployment, artifact retrieval, and billing.

Quickstart

An application is a directory with an agent.yaml manifest, a system prompt, a tool module, and a uv lockfile. See the runnable examples and authoring and deployment guide:

• examples/tiny-tuner — tune a classifier against held-out validation F1.
• examples/rna-fold-lab — design RNA sequences against an independent forward-fold oracle.
• examples/backpack-3d — write, render, visually critique, and revise a 3D backpack using Astra and complete Python modeling programs.

recurse login
recurse secret set github-token
recurse secret list
recurse run examples/tiny-tuner --inputs inputs.json --secret GITHUB_TOKEN=github-token
recurse deploy examples/tiny-tuner --as mcp --cpu 1 --memory-mib 1024 \
  --secret GITHUB_TOKEN=github-token
codex mcp add recurse -- recurse mcp serve <deployment-id>
claude mcp add recurse -- recurse mcp serve <deployment-id>

For Codex, apply the startup and tool timeout settings shown in the guide after adding the server.

Documentation

• docs/guide.md — installation, authoring, runtime, login, deployment, local MCP access, and billing.
• docs/reference/api.md — generated API reference.
• docs/reference/manifest.md — generated agent.yaml reference.

Contributing

Run ./check.sh for formatting, lint, types, tests, generated-reference checks, and package builds. The SDK and examples must reach 100% statement and branch coverage. The RNA and backpack examples' tests and dependencies live under their own tests directories and use separate locked environments.

Install the same gate before committing:

uv tool install pre-commit
pre-commit install

Publishing

pyproject.toml sets readme = "README.md", so package builds embed this README as the PyPI description. Editing it on GitHub does not update an existing release: PyPI retains the metadata from that release's first upload. To publish a corrected description with the next SDK release:

1. Choose an unpublished version, update project.version in pyproject.toml, and run uv lock. Update the SDK version reported in src/_recurse_cli.py and its matching CLI tests. Also run uv lock --directory examples/rna-fold-lab/tests and uv lock --directory examples/backpack-3d/tests to refresh their local SDK dependency.
2. Run ./check.sh to validate the release and build its wheel and source distribution in dist/.
3. Inspect the wheel's .dist-info/METADATA and the source distribution's PKG-INFO. Their description must match the current README, with pip install recurse-sdk first and uv tool install recurse-sdk as an optional alternative.
4. With PyPI publishing access, upload only the two files for that version using uv publish dist/recurse_sdk-<version>-py3-none-any.whl dist/recurse_sdk-<version>.tar.gz, replacing <version> with the selected version.
5. Check the new release's description on PyPI and the default project page. In a fresh Python 3.14 environment outside this checkout, run pip install recurse-sdk, pip check, and recurse --help. Confirm pip show recurse-sdk reports the published version.

Version 0.1.0 retains its original description. Publish a new version to refresh the default project page; PyPI does not allow replacing previously uploaded files.

License

Licensed under the Apache License 2.0.