labelbox-recursion-sdk 0.0.1__tar.gz

labelbox_recursion_sdk-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+# Generated by `yarn dx python-sdk:generate` from packages/sdk-ts/openapi.json.
+# Not committed, exactly like `packages/sdk-ts/src/generated`: the reviewable
+# input is the OpenAPI snapshot, and the wheel carries these sources (see the
+# `artifacts` entry in pyproject.toml).
+src/recursion_sdk/
+openapi.generated.json
+
+# Local test/build scratch.
+.venv/
+.generator-venv/
+.release-venv/
+dist/
+.pytest_cache/
+__pycache__/

labelbox_recursion_sdk-0.0.1/AGENTS.md

@@ -0,0 +1,5 @@
+# SDK (Python)
+
+Read `README.md` for what this package is, its request-builder surface, and how to regenerate it (`yarn dx python-sdk:generate`).
+
+`src/recursion_sdk/` is generated and gitignored — including `facade.py`, which reproduces the TypeScript SDK's `rl.<namespace>.<method>()` surface from `x-sdk-path`. Fix the OpenAPI snapshot or the projection in `tools/dx/src/commands/python-sdk.ts`, never the output. The generator's warning allowlist is a contract decision, not noise suppression: each entry is keyed by operation *and* signature and needs a justification a test can pin.

labelbox_recursion_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: labelbox-recursion-sdk
+Version: 0.0.1
+Summary: Python SDK for the Recursion RL Platform API
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2
+Requires-Dist: httpx<0.29,>=0.23
+Requires-Dist: python-dateutil>=2.8
+Description-Content-Type: text/markdown
+
+# recursion-sdk (Python)
+
+The rl-gym Python SDK, **generated from the same backend OpenAPI snapshot, and
+the same `@SdkRoute` opt-in set, as [`@labelbox/rl-sdk`](../sdk-ts/README.md)**
+with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+— free, open source, and pinned by version. The only hand-written code is a thin
+auth constructor (`src/recursion/__init__.py`); everything under
+`src/recursion_sdk/` is generated and gitignored.
+
+**The two SDKs share a surface, not just a set of operations.** `@SdkRoute('synthesizers', 'create')`
+on a backend handler produces `rl.synthesizers.create(...)` in *both* clients,
+from that one declaration.
+
+```python
+import asyncio
+import os
+
+from recursion import create_recursion_client
+
+
+async def main() -> None:
+    rl = create_recursion_client(api_key=os.environ["LABELBOX_API_KEY"])
+    environment = await rl.environments.get(environment_id)
+    print(environment.name)
+
+
+asyncio.run(main())
+```
+
+## Surface
+
+Namespaced exactly like the TypeScript SDK, because both are driven by the same
+`x-sdk-path`:
+
+```ts
+// @labelbox/rl-sdk
+const job = await rl.synthesizers.create({
+  environmentId,
+  body: { name: 'Variant generator', systemPrompt: '…', runConfigVersionId },
+});
+```
+
+```python
+# recursion-sdk
+body = CreateSynthesizerJobBodyDto(name="Variant generator", system_prompt="…", ...)
+job = await rl.synthesizers.create(environment_id, body=body)
+```
+
+Path parameters are positional, the body and query parameters are keywords. Every
+call is `async`. Non-2xx responses raise `RecursionApiError`, carrying
+`.status_code`, `.parsed` (the typed error body, when the operation documents
+one) and `.content` — matching the TypeScript client's `throwOnError: true`.
+
+The namespace facade (`recursion_sdk/facade.py`) is **generated** from
+`x-sdk-path`, exactly as hey-api's `nesting()` callback drives the TypeScript
+side, so the two clients cannot drift into different namespacing. The generated
+per-endpoint modules underneath it (`recursion_sdk.api.<namespace>.<method>`)
+remain available directly, and expose `sync`/`asyncio` variants plus
+`*_detailed` forms that return the full response instead of raising.
+
+**Opt-in, declared at the source.** An operation is in this SDK iff its backend
+handler carries `@SdkRoute(...)`
+(`apps/recursion/api/src/common/sdk-route.decorator.ts`), read through the same
+`packages/sdk-ts/src/nesting.ts` the TypeScript SDK uses, so the two clients
+cannot cover different operations.
+
+### Notes from real use
+
+- ID fields deserialize to `uuid.UUID`, not `str`.
+- Required fields are enforced at model construction, so a partial body fails
+  fast rather than at the server.
+- Some operations document an error status with a description and no schema; for
+  those `RecursionApiError.parsed` is `None` and `.content` carries the bytes.
+
+## Install
+
+Not published to a package registry yet — no free Python index has been chosen,
+and the TypeScript SDK's private Artifact Registry release is npm-specific.
+Build and install the wheel locally:
+
+```sh
+yarn dx python-sdk:generate                    # pip venv, no Docker
+cd packages/sdk-python
+python3 -m build                               # or `uv build`, if you have it
+pip install dist/recursion_sdk-*.whl
+```
+
+Requires Python 3.11+ (the generated client imports `typing.Self`).
+
+**Tooling: pip + hatchling, no lockfile — matching `mcp_server`, the repo's only
+other Python package.** `uv` is not a repo dependency, and `yarn dx ci:python-sdk`
+deliberately uses stdlib `venv` + `pip` so the gate needs nothing beyond the
+interpreter. Both work locally; `uv` is just faster. There is no `uv.lock` or
+`requirements.txt` on purpose: this is a *library*, so it declares dependency
+ranges and lets the consuming application own the resolution.
+
+## Regenerating
+
+```sh
+# Regenerate the client from the committed spec snapshot (packages/sdk-ts/openapi.json).
+yarn dx python-sdk:generate
+
+# Everything CI runs: regenerate, build the wheel, install it into a clean
+# virtualenv, and run the test suite against that installed distribution.
+yarn dx ci:python-sdk
+```
+
+Refreshing the snapshot itself is the TypeScript SDK's job
+(`yarn dx sdk:generate --refresh-spec`); this package only ever reads it.
+
+## The generator-private projection
+
+The committed snapshot is a **mixed OAS 3.0/3.1 document**: Nest + `nestjs-zod`
+emit 3.0 (`nullable: true`, boolean `exclusiveMinimum`) while the merged Managed
+Agents Go schemas are already JSON Schema 2020-12 (`type: "null"`,
+`prefixItems`). Relabelling one as 3.1 would silently discard the 3.0 halves'
+meaning, since `nullable` is not a 3.1 keyword.
+
+So `yarn dx python-sdk:generate` writes a **generator-private projection**
+(`openapi.generated.json`, gitignored) that *converts* rather than relabels, and
+feeds the generator that. It never touches the snapshot, the TypeScript SDK, or
+the backend. Each transform, and why it preserves semantics, is documented in
+`tools/dx/src/commands/python-sdk.ts` and pinned by
+`tools/dx/src/commands/python-sdk.test.ts`.
+
+The projection is not cosmetic — it is measurably what makes generation
+complete. From the unprojected spec the generator emits **342/343** operations
+with parse failures on the recursive-union endpoints; from the projection,
+**343/343** with one allowlisted warning.
+
+Generation then **fails on any generator diagnostic that is not explicitly
+allowlisted**, and on any opted-in operation missing from either the generated
+tree or the facade. The generator exits 0 while printing "Client was generated,
+but some pieces may be missing", so neither is implied by a successful run. The
+one allowlisted warning is an `application/x-yaml` *alternative* request encoding
+on a single Managed Agents operation; the `application/json` variant every other
+operation uses is generated normally. The allowlist is keyed by operation *and*
+signature, so the same warning elsewhere still fails.
+
+## Not a Yarn workspace
+
+`packages/AGENTS.md` requires every new package under `packages/` to be
+registered in the root `workspaces` array, `tools/dx/src/context.ts`,
+`tools/dx/src/commands/workspace.ts`, and the backend `Dockerfile`. None of that
+applies here: those steps exist so Node consumers can `require.resolve()` the
+package's `dist/` and so `yarn install --immutable` sees every manifest. This
+package has no `package.json`, is not in the Node dependency graph, and is never
+installed into the backend image. Registration is keyed on `package.json`
+discovery (`tools/dx/src/workspace-registration.test.ts`), so there is nothing to
+register.

labelbox_recursion_sdk-0.0.1/README.md

@@ -0,0 +1,150 @@
+# recursion-sdk (Python)
+
+The rl-gym Python SDK, **generated from the same backend OpenAPI snapshot, and
+the same `@SdkRoute` opt-in set, as [`@labelbox/rl-sdk`](../sdk-ts/README.md)**
+with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+— free, open source, and pinned by version. The only hand-written code is a thin
+auth constructor (`src/recursion/__init__.py`); everything under
+`src/recursion_sdk/` is generated and gitignored.
+
+**The two SDKs share a surface, not just a set of operations.** `@SdkRoute('synthesizers', 'create')`
+on a backend handler produces `rl.synthesizers.create(...)` in *both* clients,
+from that one declaration.
+
+```python
+import asyncio
+import os
+
+from recursion import create_recursion_client
+
+
+async def main() -> None:
+    rl = create_recursion_client(api_key=os.environ["LABELBOX_API_KEY"])
+    environment = await rl.environments.get(environment_id)
+    print(environment.name)
+
+
+asyncio.run(main())
+```
+
+## Surface
+
+Namespaced exactly like the TypeScript SDK, because both are driven by the same
+`x-sdk-path`:
+
+```ts
+// @labelbox/rl-sdk
+const job = await rl.synthesizers.create({
+  environmentId,
+  body: { name: 'Variant generator', systemPrompt: '…', runConfigVersionId },
+});
+```
+
+```python
+# recursion-sdk
+body = CreateSynthesizerJobBodyDto(name="Variant generator", system_prompt="…", ...)
+job = await rl.synthesizers.create(environment_id, body=body)
+```
+
+Path parameters are positional, the body and query parameters are keywords. Every
+call is `async`. Non-2xx responses raise `RecursionApiError`, carrying
+`.status_code`, `.parsed` (the typed error body, when the operation documents
+one) and `.content` — matching the TypeScript client's `throwOnError: true`.
+
+The namespace facade (`recursion_sdk/facade.py`) is **generated** from
+`x-sdk-path`, exactly as hey-api's `nesting()` callback drives the TypeScript
+side, so the two clients cannot drift into different namespacing. The generated
+per-endpoint modules underneath it (`recursion_sdk.api.<namespace>.<method>`)
+remain available directly, and expose `sync`/`asyncio` variants plus
+`*_detailed` forms that return the full response instead of raising.
+
+**Opt-in, declared at the source.** An operation is in this SDK iff its backend
+handler carries `@SdkRoute(...)`
+(`apps/recursion/api/src/common/sdk-route.decorator.ts`), read through the same
+`packages/sdk-ts/src/nesting.ts` the TypeScript SDK uses, so the two clients
+cannot cover different operations.
+
+### Notes from real use
+
+- ID fields deserialize to `uuid.UUID`, not `str`.
+- Required fields are enforced at model construction, so a partial body fails
+  fast rather than at the server.
+- Some operations document an error status with a description and no schema; for
+  those `RecursionApiError.parsed` is `None` and `.content` carries the bytes.
+
+## Install
+
+Not published to a package registry yet — no free Python index has been chosen,
+and the TypeScript SDK's private Artifact Registry release is npm-specific.
+Build and install the wheel locally:
+
+```sh
+yarn dx python-sdk:generate                    # pip venv, no Docker
+cd packages/sdk-python
+python3 -m build                               # or `uv build`, if you have it
+pip install dist/recursion_sdk-*.whl
+```
+
+Requires Python 3.11+ (the generated client imports `typing.Self`).
+
+**Tooling: pip + hatchling, no lockfile — matching `mcp_server`, the repo's only
+other Python package.** `uv` is not a repo dependency, and `yarn dx ci:python-sdk`
+deliberately uses stdlib `venv` + `pip` so the gate needs nothing beyond the
+interpreter. Both work locally; `uv` is just faster. There is no `uv.lock` or
+`requirements.txt` on purpose: this is a *library*, so it declares dependency
+ranges and lets the consuming application own the resolution.
+
+## Regenerating
+
+```sh
+# Regenerate the client from the committed spec snapshot (packages/sdk-ts/openapi.json).
+yarn dx python-sdk:generate
+
+# Everything CI runs: regenerate, build the wheel, install it into a clean
+# virtualenv, and run the test suite against that installed distribution.
+yarn dx ci:python-sdk
+```
+
+Refreshing the snapshot itself is the TypeScript SDK's job
+(`yarn dx sdk:generate --refresh-spec`); this package only ever reads it.
+
+## The generator-private projection
+
+The committed snapshot is a **mixed OAS 3.0/3.1 document**: Nest + `nestjs-zod`
+emit 3.0 (`nullable: true`, boolean `exclusiveMinimum`) while the merged Managed
+Agents Go schemas are already JSON Schema 2020-12 (`type: "null"`,
+`prefixItems`). Relabelling one as 3.1 would silently discard the 3.0 halves'
+meaning, since `nullable` is not a 3.1 keyword.
+
+So `yarn dx python-sdk:generate` writes a **generator-private projection**
+(`openapi.generated.json`, gitignored) that *converts* rather than relabels, and
+feeds the generator that. It never touches the snapshot, the TypeScript SDK, or
+the backend. Each transform, and why it preserves semantics, is documented in
+`tools/dx/src/commands/python-sdk.ts` and pinned by
+`tools/dx/src/commands/python-sdk.test.ts`.
+
+The projection is not cosmetic — it is measurably what makes generation
+complete. From the unprojected spec the generator emits **342/343** operations
+with parse failures on the recursive-union endpoints; from the projection,
+**343/343** with one allowlisted warning.
+
+Generation then **fails on any generator diagnostic that is not explicitly
+allowlisted**, and on any opted-in operation missing from either the generated
+tree or the facade. The generator exits 0 while printing "Client was generated,
+but some pieces may be missing", so neither is implied by a successful run. The
+one allowlisted warning is an `application/x-yaml` *alternative* request encoding
+on a single Managed Agents operation; the `application/json` variant every other
+operation uses is generated normally. The allowlist is keyed by operation *and*
+signature, so the same warning elsewhere still fails.
+
+## Not a Yarn workspace
+
+`packages/AGENTS.md` requires every new package under `packages/` to be
+registered in the root `workspaces` array, `tools/dx/src/context.ts`,
+`tools/dx/src/commands/workspace.ts`, and the backend `Dockerfile`. None of that
+applies here: those steps exist so Node consumers can `require.resolve()` the
+package's `dist/` and so `yarn install --immutable` sees every manifest. This
+package has no `package.json`, is not in the Node dependency graph, and is never
+installed into the backend image. Registration is keyed on `package.json`
+discovery (`tools/dx/src/workspace-registration.test.ts`), so there is nothing to
+register.

labelbox_recursion_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+# PyPI has no scopes, so the npm `@labelbox/rl-sdk` convention flattens to a
+# `labelbox-` prefix here. On a public index the provenance is worth more than
+# the brevity: an unprefixed `recursion-sdk` says nothing about who ships it.
+name = "labelbox-recursion-sdk"
+# Placeholder, like the TypeScript packages: the released version comes from the
+# highest `python-sdk-v*` git tag at publish time, stamped in the runner only.
+# The Python SDK releases on its own tag line, independent of `sdk-v*` (TypeScript)
+# and `cli-v*`.
+version = "0.0.1"
+description = "Python SDK for the Recursion RL Platform API"
+readme = "README.md"
+# 3.11, not 3.10: the generated `client.py` imports `typing.Self`, which does not
+# exist before 3.11. Claiming 3.10 let pip install the wheel and then fail at
+# import. `openapi-python-client` itself also requires >=3.11.
+requires-python = ">=3.11"
+# Runtime deps of the generated client only. `openapi-python-client` itself is a
+# build-time tool, pinned and installed into a throwaway venv by
+# `yarn dx python-sdk:generate` — it is deliberately not a dependency of the wheel.
+dependencies = [
+  "httpx>=0.23,<0.29",
+  "attrs>=22.2",
+  "python-dateutil>=2.8",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+# `src/recursion_sdk/` is gitignored — it is regenerated from `openapi.json` by
+# `yarn dx python-sdk:generate` and never committed — but it is the whole point
+# of the distribution. `artifacts` is hatchling's override for exactly that:
+# without it both the sdist and the wheel ship the hand-written entry point and
+# nothing for it to import. The pattern is `.py` only, so the projection JSON and
+# the generator's own metadata stay out of the package.
+artifacts = ["src/recursion_sdk/**/*.py"]
+
+[tool.hatch.build.targets.wheel]
+# Two packages: `recursion` is the hand-written entry point (auth + base URL),
+# `recursion_sdk` is the generator output (including the generated namespace
+# facade). Both ship; only the first is edited.
+packages = ["src/recursion", "src/recursion_sdk"]
+
+[tool.pytest.ini_options]
+# No `pythonpath`: `yarn dx ci:python-sdk` installs the built distribution into a
+# clean virtualenv and runs the suite against *that*, so packaging problems (a
+# generated module missing from the wheel) fail the tests rather than hiding
+# behind a source-tree import path.
+testpaths = ["tests"]
+asyncio_mode = "auto"

labelbox_recursion_sdk-0.0.1/src/recursion/__init__.py

@@ -0,0 +1,88 @@
+"""Public entry point for the rl-gym Python SDK.
+
+Everything under `recursion_sdk/` is generated from the backend OpenAPI spec by
+`yarn dx python-sdk:generate`, including the `Recursion` namespace facade — which
+is derived from the same `@SdkRoute(...)` declarations that shape the TypeScript
+SDK, so `rl.synthesizers.create(...)` means the same call in both clients.
+
+This module is the only hand-written surface: it wires auth and the base URL, the
+same job `packages/sdk-ts/src/index.ts` does for TypeScript. It does not grow as
+operations are added.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from urllib.parse import urlparse
+
+from recursion_sdk.client import AuthenticatedClient
+from recursion_sdk.facade import Recursion, RecursionApiError
+
+__all__ = ["DEFAULT_BASE_URL", "Recursion", "RecursionApiError", "create_recursion_client"]
+
+#: Default base URL — the public API gateway, the host external clients are meant
+#: to reach (the direct rl-gym host serves the static frontend, not the API). A
+#: bare origin with no path suffix: the API version lives in each operation's
+#: path (`/v1/environments`), not here.
+#:
+#: Keep in sync with `DEFAULT_BASE_URL` in `packages/sdk-ts/src/index.ts`, whose
+#: comment carries the full note on where the API key is actually validated.
+DEFAULT_BASE_URL = "https://api.recursion.labelbox.com"
+
+
+def create_recursion_client(
+    api_key: str,
+    base_url: str = DEFAULT_BASE_URL,
+    headers: Mapping[str, str] | None = None,
+    timeout_seconds: float | None = None,
+) -> Recursion:
+    """Construct an authenticated, namespaced client.
+
+    :param api_key: Labelbox API key. Sent as ``Authorization: Bearer <key>``.
+    :param base_url: rl-gym API base URL. Defaults to the production gateway;
+        override it to target staging or a local backend.
+    :param headers: Extra headers sent on every request, for callers that need a
+        per-request routing header (e.g. ``X-Proxy-Target-Url`` to pin the
+        Labelbox rl-gym proxy at an ephemeral preview backend). ``Authorization``
+        is applied by the client itself and cannot be displaced from here.
+    :param timeout_seconds: Per-request timeout. The generator's default is no
+        timeout at all, which turns a hung backend into a hung caller.
+
+    Example::
+
+        rl = create_recursion_client(api_key=os.environ["LABELBOX_API_KEY"])
+        environment = await rl.environments.get(environment_id)
+        job = await rl.synthesizers.create(environment_id, body=body)
+
+    Every non-2xx response raises :class:`recursion_sdk.facade.RecursionApiError`
+    — documented in the spec or not — matching the TypeScript client's
+    ``throwOnError: true``. Left to itself the generator returns ``None`` for an
+    undocumented status and the parsed *error body* for a documented one, either
+    of which is easy to mistake for success.
+    """
+    if not api_key or not api_key.strip():
+        raise ValueError("api_key must be a non-empty Labelbox API key.")
+    if not urlparse(base_url).hostname:
+        raise ValueError(
+            f"base_url must include a scheme and host (e.g. https://host); got {base_url!r}."
+        )
+
+    client = AuthenticatedClient(
+        base_url=base_url,
+        token=api_key,
+        # Redirects are not followed: a cross-origin hop would otherwise carry the
+        # Authorization header to another host. This is the generator's default;
+        # it is named here because it is a security property, not an accident.
+        follow_redirects=False,
+        headers=dict(headers) if headers else {},
+        # Deliberately False, which reads backwards. With it True the generated
+        # code raises its own `UnexpectedStatus` for any status the spec does not
+        # document, *before* the facade sees the response — so a caller following
+        # the documented contract and catching `RecursionApiError` would miss
+        # exactly the unexpected failures. Left False, every non-2xx reaches
+        # `_unwrap`, which raises `RecursionApiError` uniformly whether the status
+        # is documented or not. Pinned by a test.
+        raise_on_unexpected_status=False,
+        timeout=timeout_seconds,
+    )
+    return Recursion(client)

labelbox_recursion_sdk-0.0.1/src/recursion_sdk/__init__.py

@@ -0,0 +1,8 @@
+
+""" A client library for accessing Recursion RL Platform API """
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

labelbox_recursion_sdk-0.0.1/src/recursion_sdk/api/__init__.py

@@ -0,0 +1 @@
+""" Contains methods for accessing the API """

labelbox_recursion_sdk-0.0.1/src/recursion_sdk/api/agent_skills/__init__.py

@@ -0,0 +1 @@
+""" Contains endpoint functions for accessing the API """