Python SDK

Updated 12 October 2026

Reviewed against Console v0.2.2. Available actions depend on project access and runtime configuration; check your installed CLI version for command differences.

Install in your application#

uv add stimulir
# For websocket voice support:
uv add 'stimulir[realtime]'

An isolated uv tool install provides a command, not an import in your application environment. Use the installed package’s signatures when working across versions.

Construct the client#

import os
from stimulir import StimulirClient

client = StimulirClient(
    api_key=os.environ["STIMULIR_API_KEY"],
    project_id=os.environ["STIMULIR_PROJECT_ID"],
    tags=["support-summary"],
)

The default API origin is https://api.stimulir.com. The application key supplies workspace scope. Load your environment through your application’s configuration; constructing a client does not mean a local dotenv file has been read.

Send tagged inference#

reply = client.agent(
    prompt="Summarise this example request.",
    model=os.environ["STIMULIR_MODEL"],
    tag="summary-example",
)
if reply.status == "error":
    raise RuntimeError(reply.error)
print(reply.content)

Use tags=[…] on the client or a single tag="…" on agent(). An untagged SDK LLM action is rejected before sending. agent() returns an error status for request failures; inspect it instead of treating empty content as success.

Render a versioned prompt#

prompt = client.prompts.get("support.summary", label="prod")
text = prompt.render({"request": "Example request"})
reply = client.agent(
    prompt=text,
    model=os.environ["STIMULIR_MODEL"],
    metadata=prompt.lineage,
)

Create the prompt and label before fetching it. Keep its returned lineage with the request so an evaluation can identify the production prompt. Changing a label affects callers that resolve that label.

Send conversation history#

agent() is a single-prompt convenience method. For a conversation, use an OpenAI-compatible client or client.request() with a complete messages array at /api/v1/inference/chat/completions. Preserve the project header and workflow tags. See Inference API.

Use a panel and judge#

client.fusion.complete() requests a fused answer. Provide a tag through the call or client. Panel and judge calls can increase usage, so evaluate their quality and cost on your own cases. See Fusion.

Use realtime voice#

The optional realtime package exposes a connection lifecycle and typed audio events. Set up each connection once, send supported audio frames, and handle completion and disconnection. See Realtime voice.

Prepare reproducible evidence#

Use client.data_assets to register or upload data, curate a trace, update metadata, stage assets and create a snapshot. Registration alone does not upload bytes. Keep the snapshot ID used by an evaluation. See Data assets.

Compare and improve#

client.lab_evals manages evaluation runs, results, derivations and promotion proposals. client.improve inspects project evidence, previews a bounded run and starts only from a reviewed runnable preview. client.rsi remains an alias. Never infer completion from the returned creation response.

Evaluation covers comparable experiments. Improve covers preview tokens, cohort fingerprints, cost boundaries and the separate promotion decision.

Manage training and adapters#

Use lab_train, lab_jobs, lab_adapters and lab_projectors for their distinct tasks. A training request needs eligible data, a compatible model and configured compute. Creating or loading an adapter does not establish an improvement in production.

Execute a supported capability#

client.capabilities.execute() invokes a capability available to the workspace. Supply its typed payload and examine its outcome. Capability execution can incur cost or change state; inspect the specific capability contract first.

Run a stored-input workflow#

Upload input through client.storage, import a reviewed skill through client.skills, and pass its storage key to client.sandbox.run(). A sandbox output key is not an object ID; use storage.get_by_key() or read_by_key() to retrieve it. Pipeline execution stops at the first unsuccessful step.

Configure an app integration#

Use the CLI Codex integration to preview and apply local configuration. Do not print command-backed bearer tokens into logs or commit generated credentials.

Method catalogue#

The catalogue below lists public SDK operations and parameter names. Optional fields and accepted payloads depend on the selected operation. Start with the task-specific reference and inspect a returned typed error before retrying.

SDK method catalogue#

Expand a client to inspect public methods and parameter names. Read each operation’s task guide before supplying a payload or starting work. The SDK returns platform responses; handle errors and inspect completion state before using a result.