Python SDK — `frootai-sdk-orchard`

Programmatic access to the FAI Orchard catalog from Python ≥ 3.10. Same 27-contract conformance guarantees as the TypeScript SDK.

ℹ️ Async-first (`anyio`-compatible). PEP 561 type-hinted. PEP 740 attestations on every wheel + sdist. TypeScript SDK at /docs/sdk/orchard-typescript.

§1 — Install

```bash pip install frootai-sdk-orchard

or

uv add frootai-sdk-orchard

or

uvx frootai-sdk-orchard # one-shot use ```

Python ≥ 3.10 required (uses PEP 604 union syntax + PEP 612 `ParamSpec`).

§2 — Quick example (async)

```python import os from frootai_sdk_orchard import OrchardClient

async def main(): orchard = OrchardClient( base_url="https://api.frootai.dev", token=os.environ.get("FROOTAI_TOKEN"), region="us-east", )

# Search the 413-entry catalog
results = await orchard.search(
    query="rag",
    where="variety:azure AND trust_badge:eval_proven",
    limit=20,
)

for r in results.items:
    print(r.id, r.title, r.stars)

# Show full detail of one accelerator
detail = await orchard.show(id="azure-search-openai-demo")
print(detail.manifest)

await orchard.aclose()

import anyio anyio.run(main) ```

§3 — Sync wrapper (for scripts + notebooks)

```python from frootai_sdk_orchard import sync as orchard

results = orchard.search(query="rag", limit=10) for r in results.items: print(r.id) ```

The sync wrapper runs each call in a managed anyio event loop. Use the async API directly in async frameworks (FastAPI, etc.).

§4 — Type-safe error handling

```python from frootai_sdk_orchard import OrchardError

try: await orchard.bushel.push(local) except OrchardError as err: if err.code == "rate_limited": print(f"Rate limited; retry in {err.retry_after_seconds}s") elif err.code == "forbidden": print("Need Pro+ entitlement for bushel sync") else: raise ```

Error codes: `invalid_input`, `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `internal`, `payload_too_large`.

§5 — Configuration via env vars

Var	Purpose
`FROOTAI_TOKEN`	Bearer token (Pro+)
`FROOTAI_BASE_URL`	Override API base URL (default `https://api.frootai.dev\`)
`FROOTAI_REGION`	Pin region (default `us-east`)
`FROOTAI_TIMEOUT_MS`	Per-request timeout (default 30000)
`DO_NOT_TRACK`	Set to `1` to disable any optional telemetry

§6 — Pydantic v2 models

All response shapes are Pydantic v2 `BaseModel`s. They support `.model_dump()`, `.model_dump_json()`, and standard validation:

```python detail = await orchard.show(id="azure-search-openai-demo") print(detail.model_dump_json(indent=2)) ```

This makes the SDK natively interoperable with FastAPI, Django Ninja, and other Pydantic-first frameworks.

§7 — Cross-runtime byte-equal

The same 27 contract assertions run against this Python SDK + the TypeScript SDK. JSON shapes, error envelopes, pagination cursors are byte-equal across both — verified on every release via the conformance certificate (schema).

§8 — Supply-chain

PyPI: PEP 740 attestations on every file (wheel AND sdist)
Verify: https://pypi.org/project/frootai-sdk-orchard/1.0.0/
SLSA v1.0 Build L3 provenance: `pip download frootai-sdk-orchard==1.0.0` then `gh attestation verify`
Reproducible builds: deterministic `pyproject.toml` build via `hatchling` pinned to specific version

§9 — CLI

The SDK ships with a CLI entrypoint:

```bash uvx frootai-sdk-orchard search --query rag --where 'variety:azure' uvx frootai-sdk-orchard show --id azure-search-openai-demo uvx frootai-sdk-orchard whoami ```

Python SDK — frootai-sdk-orchard