SDK

Python SDK

Use the Stimulir Python SDK when an application, backend, or agent needs to manage prompts, data assets, Lab evals, or capability execution without shelling out to the CLI.

Install

The SDK ships with the stimulir Python package. Add it to the application or backend environment that will call Stimulir:

bash
uv add stimulir

If you already manage a virtual environment directly, install or upgrade into that environment:

bash
uv pip install -U stimulir

uv tool install stimulir installs the terminal CLI as an isolated command-line tool. Use it for shell workflows, not as the dependency path for application code that imports the SDK. See CLI Installation.

Configure

The normal customer auth path is a Stimulir-issued hyb_* API key from the Console. The key carries its workspace and platform scope, so application code does not need to pass a workspace id for normal prompt, data, eval, or inference calls.

bash
export STIMULIR_API_BASE=https://api.stimulir.com
export STIMULIR_API_KEY=hyb_...
python
import os

from stimulir import StimulirClient

client = StimulirClient(
    api_base=os.getenv("STIMULIR_API_BASE", "https://api.stimulir.com"),
    api_key=os.environ["STIMULIR_API_KEY"],
)

The same hyb_* key works with the OpenAI-compatible inference endpoint. See Inference API for direct chat-completions usage.

Prompts

Fetch prompt versions by key, label, or exact version; create new versions; update metadata; archive old versions; and persist prompt lineage alongside application sessions.

python
from stimulir import StimulirClient

client = StimulirClient()

prompt = client.prompts.get("aca.assessment.agent", label="prod")

session_metadata = {
    **prompt.lineage,
    "model": "Qwen/Qwen2.5-VL-72B-Instruct",
}

# Use prompt.content in your runtime, then store session_metadata with the result.
python
client.prompts.create_version(
    "aca.assessment.agent",
    content=open("prompts/aca_assessment_agent.md").read(),
    label="prod",
    prompt_type="system",
    change_notes="Seed current ACA assessment prompt",
)

client.prompts.patch_metadata(
    "aca.assessment.agent",
    3,
    change_notes="Tightened interview scoring rubric",
)

client.prompts.label("aca.assessment.agent", 3, "prod")
client.prompts.archive("aca.assessment.agent", 2)

Data assets

Use data assets as the hub between traces, uploads, cleaning jobs, snapshots, SFT datasets, preference data, and eval sets.

python
asset = client.data_assets.upload(
    "datasets/aca_eval.jsonl",
    name="ACA eval seed",
    target="eval",
)

client.data_assets.patch(asset["id"], description="Held-out interview eval cases")
client.data_assets.stage(asset["id"], "lab", status="ready")

trace_asset = client.data_assets.from_trace(
    "<trace-id>",
    source="agent",
    target="sft",
    name="Cleaned assessment trace",
)

snapshot = client.data_assets.snapshot(trace_asset["id"])
python
client.data_assets.bulk_stage(
    ["<asset-id-1>", "<asset-id-2>"],
    stage="lab",
    target="eval",
    lineage_event={"job": "redact-normalize-label"},
)

client.data_assets.unstage("<asset-id>")

Lab evals

Lab eval runs compare prompt versions, staged data assets, inference endpoints, adapters, and policies before promotion.

python
run = client.lab_evals.create_run(
    name="ACA prompt regression",
    data_asset_id=snapshot["id"],
    prompt_ref="aca.assessment.agent:prod",
    model="hybrie-runtime-default",
    execute=True,
)

report = client.lab_evals.get_run(run["id"])

See Evaluation for the durable eval model and CLI equivalents.

Capabilities

Agents can call registered Stimulir capabilities through the SDK when they need the same typed backend path that the console uses.

python
result = client.capabilities.execute(
    "engineering_usage_summary",
    scope={
        "mode": "chat",
        "modeContext": "workspace",
        "opsWorkspace": "engineering_ops",
    },
    args={"window": "month"},
    confirmed=True,
)

SDK surface

Client

  • StimulirClient(api_base=None, api_key=None, timeout=...)
  • client.request(method, path, params=None, json_body=None) for low-level platform API calls.

Subclients

  • client.prompts — list, get, versions, create_version, patch_metadata, label, archive.
  • client.data_assets — list, create, upload, from_trace, patch, stage, unstage, bulk_stage, snapshot.
  • client.lab_evals — list_runs, get_run, create_run, execute_run.
  • client.capabilities — execute.