Skip to main content

Python SDK

The Python SDK is the recommended way to integrate SimplAI into a Python application. It abstracts orchestration concerns (polling, retries, streaming, scheduling) behind clean, idiomatic functions with typed exceptions.

Workflow / Tool execution​

A single unified function executes workflows in both synchronous and asynchronous modes.

execute_workflow(
  workflow_id,
  inputs,
  mode="sync" | "async",
  timeout=None,
  poll_interval=None
)
  • Async mode — returns immediately with an execution ID. You poll status separately when you need it.
  • Sync mode — the SDK internally polls workflow status, handles retries and backoff, honours the configured timeout, and returns the final output (or raises on terminal failure).
  • Polling interval and timeout are configurable; sensible defaults apply if you omit them.

Fetch workflow status​

get_workflow_status(execution_id)

Returns the current execution state (running, waiting, completed, failed, cancelled) plus any available partial metadata.

Schedule a workflow run​

schedule_workflow(
  workflow_id,
  inputs,
  schedule_config
)
  • One-time scheduled execution at a future time.
  • Recurring execution via cron expression.
  • Idempotent scheduling — submitting the same schedule twice doesn't create duplicates.

Bulk runs​

trigger_bulk_run(
  workflow_id,
  records,
  concurrency_limit=None
)
  • Accepts a list, file, or iterable of input records.
  • Triggers workflows in parallel with the configured concurrency limit.
  • Returns a bulk run identifier.
  • Per-record execution status can be tracked individually via the bulk run ID.

Agent chat​

Two flavours of agent interaction — non-streaming and streaming.

Non-streaming​

agent_chat(
  agent_id,
  message,
  chat_history=None
)
  • Single request → single response.
  • Optional chat_history argument to provide multi-turn context. If omitted, the SDK relies on the server-side conversation tracking.

Streaming​

agent_chat_stream(
  agent_id,
  message,
  chat_history=None,
  on_chunk_callback=<your handler>
)
  • Token / chunk streaming via Server-Sent Events.
  • Partial response handling — your callback fires for each chunk as it arrives.
  • Supports tool-call events and other intermediate events alongside content chunks.
  • Optional chat history injection.
  • The SDK handles backpressure so your handler doesn't get overwhelmed.

Use streaming when you need to display tokens to a user as they're generated (chat UIs, voice transcript surfaces).

Observability​

Fetch execution traces​

get_execution_traces(execution_id)

Returns the step-level timeline for a workflow or agent execution:

  • LLM calls (with model, latency, token counts).
  • Tool calls.
  • Retries.
  • Waits / polling intervals.
  • Correlation IDs for cross-service traces.

This is the same data you'd see in Observability → Run history — the SDK gives you programmatic access for piping into your own monitoring or analytics pipeline.

Billing & usage​

Fetch billing details​

get_billing_details(
  entity_type="workflow" | "agent",
  entity_id,
  time_range
)

Returns:

  • Token usage — prompt + completion tokens.
  • Workflow execution cost.
  • Agent execution cost.
  • Time-range scoped — query a day, a month, a custom range.

Useful for chargeback, internal usage tracking, or cost-control automations (alert when a workflow exceeds X tokens/day).

Non-functional behaviour​

  • Idiomatic Python — type hints, async support where applicable, raises on error.
  • Backward compatible — pinned SDK versions remain compatible across platform updates within the same major release.
  • Strong error handling — typed exceptions per failure mode; retry semantics where they make sense (transient errors get retried, hard failures don't).
  • Authentication abstraction — supply an API key; OAuth support is planned.

What's not in the SDK​

  • Workflow / Agent authoring — applications are built in Studio. The SDK invokes published applications; it does not create or modify their configuration.
  • Billing computation — the SDK retrieves billing data already computed by the platform.

Future languages​

JS / TypeScript SDK is on the roadmap. Architecture and API surface are designed to translate cleanly across languages, so the conceptual model documented here will hold for future SDK releases.