> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getspine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Official Python client for the Spine API.

The Spine Python SDK (`spine-sdk`) is a typed, documented client for the
[Spine API](/api-reference/overview). It wraps all five public endpoints,
handles polling with exponential backoff, and exposes both a sync and an
async client.

## Install

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
pip install spine-sdk
```

Requires Python 3.9 or newer. The package ships full type hints
(PEP 561 `py.typed`), so mypy and Pyright pick them up out of the box.

## First request

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
from spine import SpineClient, Template

with SpineClient(api_key="sk_spine_...") as client:
    handle = client.runs.create(
        prompt="Summarise the Q4 AI chip market in 3 paragraphs.",
        template=Template.MEMO,
    )
    result = handle.wait(timeout=600)
    print(result.final_output)
    for artifact in result.artifacts:
        print(artifact.name, artifact.download_url)
```

Prefer the `SPINE_API_KEY` environment variable so keys stay out of your
source code:

```bash theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
export SPINE_API_KEY=sk_spine_...
```

```python theme={"theme":{"light":"github-light","dark":"tokyo-night"}}
with SpineClient() as client:   # picks up SPINE_API_KEY automatically
    ...
```

## What's in the box

<CardGroup cols={2}>
  <Card title="SpineClient + AsyncSpineClient" icon="plug">
    Sync and async clients built on `httpx`. Use whichever matches your
    stack.
  </Card>

  <Card title="Typed models" icon="cube">
    Pydantic v2 models for every request and response — IDE
    autocompletion and mypy coverage out of the box.
  </Card>

  <Card title="Polling helper" icon="rotate">
    `handle.wait()` polls with exponential backoff;
    `handle.stream_progress()` yields progress snapshots for UIs.
  </Card>

  <Card title="Typed exceptions" icon="shield-halved">
    `AuthenticationError`, `NotFoundError`, `BadRequestError`,
    `RateLimitError`, `ServerError`, `SpineTimeoutError` — branch on the
    exact failure.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/sdks/python/quickstart">
    Full end-to-end example with uploads, polling, and artifact download.
  </Card>

  <Card title="Runs and polling" icon="arrows-rotate" href="/sdks/python/runs">
    All the options on `runs.create`, `wait`, and `stream_progress`.
  </Card>

  <Card title="Canvas introspection" icon="diagram-project" href="/sdks/python/canvas">
    Walk the block graph and task tree produced by a run.
  </Card>

  <Card title="Errors and retries" icon="triangle-exclamation" href="/sdks/python/errors">
    Exception hierarchy and how to tune the built-in retry policy.
  </Card>
</CardGroup>