Python 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.

Install

pip install sference-sdk

uv add sference-sdk

Import name: sference_sdk.

Credentials

export SFERENCE_API_KEY='sk_...'

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

Example (Responses API)

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

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.

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 for HTTP-oriented async guides.

Framework examples

Runnable workflows in the sference OSS repo 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.

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/: two-stage flow for batch-style analysis: enqueue background responses, then poll to completion. Adapted from Prefect’s AI data analyst example, using sference instead of an in-process LLM.

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:

uv run python examples/prefect/ai_data_analyst_batch_responses.py

Deploy with Prefect (worker + UI):

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 · 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.

1. Agent prompt (copy this first)

Canonical file (always current on main):

github.com/s-ference/sference/blob/main/PROMPT.txt

Raw URL to open and copy:

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 (keep the YAML frontmatter) into your app repo:

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

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

Install steps for every tool: AGENTS.md in the OSS repo.

Go deeper