Recursion Python SDK
Typed, synchronous and asynchronous request/response access to the Recursion API. The client and Pydantic models are generated from Recursion's committed public OpenAPI contract snapshots. Session-event and gestalt streaming are excluded.
The distribution is
labelbox-recursion-sdk,
and the Python import is recursion_sdk. This implementation starts at version
0.1.0; earlier releases contain the retired SDK and its different import/API.
Build a wheel from this checkout to try the implementation before its first
release. Versions remain below 1.0 while the public API evolves.
import os
from recursion_sdk import Recursion
with Recursion(api_key=os.environ["RECURSION_API_KEY"]) as recursion:
result = recursion.managed_agents.list_sessions()
print(result.data, result.response.headers.get("etag"))
AsyncRecursion exposes the same methods as coroutines and supports
async with. The production base URL is https://api.recursion.labelbox.com.
Set organization_id or tenant_id on the constructor when the API key
requires those selectors. Operation-level selectors may repeat those values;
they cannot change the constructor's scope.
The agent, agent-version, vault, credential, memory-list, agent-template,
environment, setup-run, environment-template, sandbox-provider, and session
discovery/overview read methods use
/managed-agents/v2 by default. For example,
managed_agents.list_agents(limit=50, cursor=...) returns the v2 page with
items, nextCursor, and total; managed_agents.list_environments(limit=50, cursor=...) returns items and nextCursor; and
managed_agents.list_sessions(limit=50, cursor=...) returns items,
nextCursor, and a nullable total. The explicit *_v2 names remain
available; use *_v1 to call the deprecated legacy endpoints and receive their
legacy shapes. Those calls emit DeprecationWarning and their docstrings point
to the v2 replacement. Skill and skill-group methods also use v2 by default,
including the camelCase request and response models; their explicit *_v1
methods retain the deprecated legacy contracts. Other Managed Agents methods
use the version declared by the public contract.
Methods return ApiResponse with typed data and the original HTTPX
response, including status and headers. A declared bodyless 304 has
data=None. Declared API errors raise RecursionAPIError; malformed or
undeclared responses raise RecursionContractError. HTTPX transport failures
retain their HTTPX exception types. Request and response values are validated
against the canonical schemas, including constraints beyond Pydantic's model
annotations.
JSON methods accept generated models from recursion_sdk.models, with
snake_case attributes and canonical JSON field aliases. Omitted model
fields stay omitted; explicitly supplied None becomes JSON null where the
contract permits it. Multipart methods accept Upload values, and binary
download methods return bytes. The client has no automatic retries or
pagination; callers retain control of mutation replay and iteration.
Refresh active outcomes during an upgrade
The single-session and bulk upgrade methods accept
replaceActiveOutcome: true in their JSON body. It reapplies the target
version's default rubric to an active outcome, including a caller-defined
outcome or a session already running that version:
import os
from uuid import UUID
from recursion_sdk import Recursion, models
with Recursion(api_key=os.environ["RECURSION_API_KEY"]) as recursion:
recursion.managed_agents.replace_session_agent_version(
session_id=UUID("e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53"),
body=models.ReplaceSessionAgentVersionRequest.model_validate({
"agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
"replaceActiveOutcome": True,
}),
)
recursion.managed_agents.start_agent_session_upgrade(
agent_id=UUID("7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14"),
idempotency_key="refresh-active-outcomes-1",
body=models.StartAgentSessionUpgradeRequest.model_validate({
"replaceActiveOutcome": True,
}),
)
While a bulk upgrade is running, a different replaceActiveOutcome policy
returns 409 conflict; the running upgrade keeps the policy it accepted.
AsyncRecursion exposes the same calls with await. The bulk body is optional;
leave it out for the usual version-only request. Without the option, inherited
default outcomes follow the version and caller-defined outcomes stay.
Explicit replacement requires a nonempty default rubric, preserves the
objective and pass limit, and retains the prior outcome and grading history as
interrupted. An evaluation in progress finishes before replacement; terminal
outcomes stay unchanged. A successful upgrade response acknowledges the
request. Verify the active criteria with managed_agents.list_session_outcomes
after the session's next model operation.
Development
All Python tooling uses uv. Run these commands from the repository root through the worktree's devbox:
./devbox exec -- yarn check recursion:python-sdk
The package's uv wrapper reuses uv on PATH or installs a checksum-verified,
pinned copy under the worktree's .local/ directory on a Linux devbox. Other
hosts can use an existing uv installation. Nothing is installed globally.
The check command generates, checks formatting, runs strict typing and behavioral
tests, verifies deterministic generation, builds wheel/sdist artifacts, and
checks an isolated installation of the wheel with hashed runtime dependencies
from uv.lock. Generated files under
src/recursion_sdk/_generated/ are ignored; change the public contract or
generator inputs and rerun the check. It runs tools/check.py through uv with
the materialized preview contract.
Python dependencies and generated outputs belong to this independent package. Root Yarn installation, postinstall, JavaScript code generation, and ordinary application checks do not install or run Python tooling. Dedicated CI runs when this package or the canonical Recursion public contract changes.
Generation and ownership
datamodel-code-generator compiles schemas into Pydantic v2 models. A small
operation emitter produces typed methods and bundles the unmodified canonical
contract. One shared HTTPX transport owns wire behavior and uses JSON Schema
validation at its boundaries. No endpoint or request/response model is
maintained by hand, and generation requires no JVM or hosted service.
Generation binds the exact preview audience served by production: the public
contract source recursion-public-openapi.preview.generated.json without its
x-recursion-stability markers. yarn ci check recursion:python-sdk and release
qualification materialize those bytes and pass their path in
RECURSION_PYTHON_SDK_CONTRACT_PATH; the generator requires it and rejects a
marked source.
Build after generation, then add the wheel to your application's uv project:
uv build --project packages/recursion-python-sdk
uv add --project /absolute/path/to/your-python-project /absolute/path/to/labelbox_recursion_sdk-0.0.0-py3-none-any.whl
Published releases reuse the existing labelbox-recursion-sdk PyPI project.
The source version 0.0.0 identifies local preview builds; the release process
stamps the requested version into release artifacts. The TypeScript SDK release
process is independent.
Release
Releases are proposed on Tuesdays and Thursdays and announced in
#recursion-info while they wait for approval: publishing runs in the recursion-sdk-pypi
environment, which requires an approval from the recursion team, and the run
refuses to publish if it has none. Approving and yanking a bad release:
client package releases.
The Python release workflow builds and qualifies an explicit version. Its default run only uploads artifacts:
gh workflow run release-python-sdk.yml --ref main -f version=0.1.0
The SDK code comes from the workflow's commit. By default, its API contract does
too. When main contains API changes that have not reached production, set
PYTHON_SDK_CONTRACT_SOURCE_SHA to a deployed commit's full SHA and select its
contract explicitly:
gh workflow run release-python-sdk.yml --ref main -f version=0.1.0 -f contract-source-sha="$PYTHON_SDK_CONTRACT_SOURCE_SHA" -f publish=true
The contract source must be a full commit SHA in the workflow commit's ancestry.
The release extracts that commit's production contract without modifying any
tracked snapshot. Generation, behavioral tests, and strict production
verification all consume those exact bytes. Newer API changes on main can
therefore coexist with a release for the deployed API. The artifact manifest
records the SDK source commit, contract source commit, snapshot path, and hash.
For a local build without publishing, use an ignored artifact directory from a clean checkout:
yarn release python-sdk:prepare --version 0.1.0 --artifact-dir "$PWD/.agent/python-sdk-release"
The local command also accepts --contract-source-sha <full-commit-sha> and
--verify-production true for the same source selection and production check
without uploading anything.
The release command rejects published/older versions, temporarily stamps the package and lockfile, runs the full qualification, and restores the source metadata. The immutable candidate contains the wheel, source distribution, checksums, and its source commit.
Passing -f publish=true to the workflow additionally verifies the source
contract in production and publishes those exact archives with uv publish
through PyPI trusted publishing. Its publisher identity is
repository Labelbox/recursion-platform, workflow release-python-sdk.yml,
environment recursion-sdk-pypi, project labelbox-recursion-sdk. The final job verifies
PyPI's archive hashes before recording python-sdk-v<version> at the source
commit. Publication and Git tagging have separate credentials; release runs
never commit version changes to the branch.
Metadata
Release files for labelbox-recursion-sdk 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| labelbox_recursion_sdk-0.1.1.tar.gz | 558.4 kB | Without provenance | Details for labelbox_recursion_sdk-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| labelbox_recursion_sdk-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for labelbox_recursion_sdk-0.1.1-py3-none-any.whl |
Total release size: 1.1 MB
Release files / labelbox_recursion_sdk-0.1.1.tar.gz
| Download URL | labelbox_recursion_sdk-0.1.1.tar.gz |
|---|---|
| Size | 558.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a6667316f908f1b16b7d1bfa6fc22f7f8e41c02c030d9877f75ac190b68fde52
|
|
BLAKE2b-256 checksum How to use checksums |
821190724a6d8bf332ac1fa0d1f13b0f78515850baffe59c5a4851199aa02afa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.14 {"installer":{"name":"uv","version":"0.12.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / labelbox_recursion_sdk-0.1.1-py3-none-any.whl
| Download URL | labelbox_recursion_sdk-0.1.1-py3-none-any.whl |
|---|---|
| Size | 536.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4d8db2066466f21cb6bd177db5df40b886db36aed0d9b766819a503543d89c39
|
|
BLAKE2b-256 checksum How to use checksums |
abb281cd37df68d70616442f4130f47f3f05a1c9481b9452a599c787f6aefa35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.14 {"installer":{"name":"uv","version":"0.12.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for labelbox-recursion-sdk 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.