# Python SDK

> Install sference-sdk, Responses API patterns, framework examples (Prefect), and agent prompts for Cursor and Claude Code.

Source: https://sference.com/docs/sdk

The **`sference-sdk`** package on PyPI is the supported way to call sference from Python. Source and API contract live in the **[sference OSS repository](https://github.com/s-ference/sference)**.

## Install

```bash
pip install sference-sdk
```

```bash
uv add sference-sdk
```

Import name: **`sference_sdk`**.

## Credentials

```bash
export SFERENCE_API_KEY='sk_...'
```

Pass the key in code when you prefer not to use the environment: `SferenceClient(api_key="sk_...")`.

> **Picking a pattern**
>
> For interactive code, anything where a user is waiting, call the blocking response/chat methods; that is the common case and the one the platform is tuned for. For unattended jobs, use **`create_response(..., background=True)`** then **`wait_for_response`**, which runs async with no blocking HTTP connection. The SDK mirrors the API's [three processing modes](https://sference.com/docs/guides/responses#processing-modes).

## Example (Responses API)

```python
import os
from sference_sdk import SferenceClient

client = SferenceClient(api_key=os.environ["SFERENCE_API_KEY"])

resp = client.create_response(
    model="Qwen/Qwen3.6-35B-A3B",
    input=[{"role": "user", "content": "Say hello in one sentence."}],
    background=True,
    metadata={"completion_window": "24h"},  # "24h" is the only supported value
)

done = client.wait_for_response(resp.id, poll_interval=2.0, timeout=3600.0)
print(done.status)
```

## Processing modes and completion windows

| Mode | Where | Window |
|------|-------|--------|
| **Realtime** | Sync chat, [Anthropic messages](https://sference.com/docs/anthropic), blocking `/v1/responses` | No window; returns when inference finishes |
| **Flex** | `/v1/chat/completions` or `/v1/responses` with `service_tier: "flex"` (flex-enabled accounts; not `/v1/messages`) | No window; discounted, lower scheduling priority, raise client timeouts |
| **Async** | Background responses, streams, batches | `"24h"` (the only supported value) |

Set the async window via `metadata={"completion_window": "24h"}` on background responses, `window=` on `create_stream` / `submit_batch`.

For **grouped work** (e.g. one preset for log analysis), create a **stream** first, then pass `metadata={"stream_id": stream.id, "completion_window": "24h"}` on each response.

For a fixed JSONL file run once, use **`submit_batch`**. Each row shares one **catalog-available model** (same id on every line, or pass `model=` for content-only JSONL). Row `body` may use chat `messages` or Responses `input` (normalized at create). See **[Batch inference](https://sference.com/docs/guides/batches)**.

```python
batch = client.submit_batch(
    input_file="./workload.jsonl",
    model="Qwen/Qwen3.6-35B-A3B",
    window="24h",
)
done = client.wait_for_completion(batch.id, poll_interval=5.0, timeout=86_400.0)
client.download_results_jsonl(done.id, out="./results.jsonl")
```

See [Responses & streams](https://sference.com/docs/guides/responses) for HTTP-oriented async guides.

## Framework examples

Runnable workflows in the **[sference OSS repo](https://github.com/s-ference/sference/tree/main/examples)** show how to combine **`sference-sdk`** with orchestration tools. Clone that repo (or copy the example into your project), install example deps, and set `SFERENCE_API_KEY`.

```bash
git clone https://github.com/s-ference/sference.git
cd sference
uv sync --group dev --group examples
export SFERENCE_API_KEY='sk_...'
export SFERENCE_MODEL='Qwen/Qwen3.6-35B-A3B'   # model id from your deployment
```

More frameworks will be added here as examples land in `examples/`.

### Prefect

**[examples/prefect/](https://github.com/s-ference/sference/tree/main/examples/prefect)**: two-stage flow for batch-style analysis: enqueue background responses, then poll to completion. Adapted from Prefect’s [AI data analyst example](https://github.com/PrefectHQ/prefect/blob/main/examples/ai_data_analyst_with_pydantic_ai.py), using sference instead of an in-process LLM.

| Stage | Prefect | SDK |
|-------|---------|-----|
| Prepare | `@task`: build prompts from local data (pandas, files) | No API calls |
| Submit | `@task` + `.map(prompts)` | `create_response(..., background=True, metadata={"completion_window": "24h"})` → `response.id` |
| Wait | `@task` + `.map(response_ids)` | `wait_for_response(id)` |
| Report | `@task` | Parse `done.output` (`message` → `output_text` parts) |

**Why split submit and wait?** Prefect retries and observability stay in the orchestrator; inference runs on sference. If a **wait** task fails, you can retry polling without re-submitting jobs that already have an ID.

Run locally:

```bash
uv run python examples/prefect/ai_data_analyst_batch_responses.py
```

Deploy with Prefect (worker + UI):

```bash
uv run python examples/prefect/ai_data_analyst_batch_responses.py --serve
```

Then trigger **ai-data-analyst-batch-responses** from the Prefect UI or CLI. Source and setup notes: **[examples/prefect/README.md](https://github.com/s-ference/sference/blob/main/examples/prefect/README.md)** · **[ai_data_analyst_batch_responses.py](https://github.com/s-ference/sference/blob/main/examples/prefect/ai_data_analyst_batch_responses.py)**.

## Coding agents (Cursor, Claude Code, …)

Two layers in the OSS repo: use the **prompt** for vibe coding; add the **skill file** when you want depth or a Cursor skill install.

> **Teaching an agent the SDK vs. running the agent on sference**
>
> This section teaches your coding agent to **write code against the sference SDK**. If you instead want Claude Code itself to **run on sference models**, that is the [Anthropic Messages endpoint](https://sference.com/docs/anthropic); see [Claude Code on sference](https://sference.com/docs/anthropic/claude-code).

### 1. Agent prompt (copy this first)

Canonical file (always current on `main`):

**[github.com/s-ference/sference/blob/main/PROMPT.txt](https://github.com/s-ference/sference/blob/main/PROMPT.txt)**

Raw URL to open and copy:

```text
https://raw.githubusercontent.com/s-ference/sference/main/PROMPT.txt
```

Paste into **Cursor** project rules, **Claude Code** `CLAUDE.md`, or your agent’s custom instructions. It points to the full skill file for examples and edge cases.

### 2. Full skill (optional)

For Cursor’s skill format, copy **[SKILL.md](https://github.com/s-ference/sference/blob/main/SKILL.md)** (keep the YAML frontmatter) into your app repo:

```text
.cursor/skills/sference-sdk/SKILL.md
```

Raw: `https://raw.githubusercontent.com/s-ference/sference/main/SKILL.md`

Install steps for every tool: **[AGENTS.md](https://github.com/s-ference/sference/blob/main/AGENTS.md)** in the OSS repo.

## Go deeper

- [Framework examples](https://github.com/s-ference/sference/tree/main/examples): Prefect today; more orchestration samples in examples/.
- [SDK README](https://github.com/s-ference/sference/blob/main/sdk-python/README.md): Batch vs stream, async client, and method reference in the OSS repo.
- [Batch inference](https://sference.com/docs/guides/batches): JSONL jobs, body shapes, and create-time validation.
- [Responses & streams](https://sference.com/docs/guides/responses): HTTP guide for async responses and stream presets.
- [CLI](https://sference.com/docs/cli): One-line install for the sference command.