Python API Reference

Every public symbol in staso with its exact signature. Paste this page to an LLM to get correct setup code on the first try.

import staso as st

All examples in this file assume that alias.

Initialization

Symbol	Signature	Description
`st.init`	`st.init(*, api_key=None, agent_name=None, base_url=None, batch_size=100, flush_interval=5.0, max_queue_size=10_000, enabled=True, debug=None, environment=None, workspace_slug=None, capture_messages=True, capture_git=True) -> Client`	Initialize the global Staso client. Raises `ValueError` if `api_key` or `agent_name` is missing.
`st.shutdown`	`st.shutdown() -> None`	Flush pending spans and stop the background transport. Auto-registered via `atexit`.
`st.get_client`	`st.get_client() -> Client \| None`	Return the globally initialized client, or `None` before `init`.
`st.generate_agent_id`	`st.generate_agent_id(agent_name: str) -> str`	Deterministic UUID5 for an agent name — same shape the backend stores.

See Initialization for setup walkthroughs.

Decorators

All decorators support both @st.x and @st.x(...) call styles. They work on both sync and async def functions.

Symbol	Signature	Description
`st.agent`	`st.agent(_fn=None, name=None, *, tags=None, metadata=None, capture_input=True, capture_output=True)`	Wrap an agent entry-point in a `kind="agent"` span and bind `agent_name` to the context.
`st.tool`	`st.tool(_fn=None, name=None, *, tags=None, metadata=None, capture_input=True, capture_output=True)`	Wrap a tool function in a `kind="tool"` span.
`st.trace`	`st.trace(_fn=None, name=None, *, kind=SpanKind.CHAIN, tags=None, metadata=None, capture_input=True, capture_output=True)`	Generic span decorator for arbitrary functions. Exported as `trace` but defined as `trace_fn`.

See Decorators.

Context managers

Symbol	Signature	Description
`st.span`	`with st.span(name: str, *, kind: str \| SpanKind = SpanKind.CHAIN) as s:`	Create a manual span. Yields a `Span` instance.
`st.conversation`	`with st.conversation(conversation_id: str \| None = None, *, user_id: str \| None = None):`	Group every span in scope under one `conversation_id`. Auto-generates a UUID if `conversation_id` is omitted.

`Span` instance methods

Inside with st.span(...) as s: or any decorated function, these methods are available on the span object:

Method / field	Signature	Description
`s.set_status`	`s.set_status(status: SpanStatus, description: str \| None = None) -> None`	Mark the span as `OK`, `ERROR`, or `TIMEOUT`.
`s.record_exception`	`s.record_exception(exception: BaseException) -> None`	Record an exception and flip status to `ERROR`.
`s.annotate`	`s.annotate(name: str, *, value: float \| str \| bool, data_type: str = "numeric", comment: str \| None = None) -> None`	Attach an annotation scoped to this span's trace.
`s.input`	`dict[str, Any]`	Free-form request payload. Serialized to JSON on flush.
`s.output`	`dict[str, Any]`	Free-form response payload.
`s.metadata`	`dict[str, Any]`	Well-known keys listed in Data Model.
`s.model`, `s.input_tokens`, `s.output_tokens`, `s.total_tokens`	—	LLM-specific top-level columns.

Annotations

Symbol	Signature	Description
`st.annotate`	`st.annotate(*, trace_id: str, name: str, value: float \| str \| bool, data_type: str \| AnnotationDataType = AnnotationDataType.NUMERIC, span_id: str \| None = None, comment: str \| None = None) -> None`	Attach a score or label to a trace. Fire-and-forget — HTTP errors are logged, not raised.
`st.AnnotationDataType`	`StrEnum("numeric", "categorical", "boolean")`	Allowed annotation value types.

See Annotations.

Guard

Symbol	Signature	Description
`st.guard`	`st.guard(tool_name: str, tool_input: dict[str, Any], *, context: dict \| None = None, wait_for_escalation: bool = False, escalation_poll_interval: float = 3.0, escalation_timeout: float = 300.0, timeout: float = 10.0, fail_closed: bool \| None = None) -> GuardResult`	Evaluate a tool action before executing it. Fail-open by default — set `fail_closed=True` or `STASO_GUARD_FAIL_CLOSED=true` for strict mode.
`st.GuardResult`	`dataclass(frozen=True)` with fields: `action: str`, `reason: str = ""`, `rule_name: str \| None = None`, `severity: str = "low"`, `results: list[GuardRuleResult]`, `modified_input: dict \| None`, `modifications: list[dict]`, `escalation_id: str \| None`, `latency_ms: float`, `rules_triggered: list[str]`	Result of a guard check. `action` is one of `"allow" \| "block" \| "modify" \| "escalate"`.
`st.GuardBlocked`	`Exception` with attributes: `tool_name: str`, `result: GuardResult`, `reason: str`, `rules_triggered: list[str]`, `blocked_tools: list[BlockedTool]`	Raised by `patch_openai` / `patch_anthropic` when an enforce-mode rule fires. Catches at the LLM-call site.
`st.BlockedTool`	`dataclass(frozen=True)` with fields: `tool_name: str`, `result: GuardResult`	One entry in `GuardBlocked.blocked_tools`.

See Manual guard checks and Enforcement.

Integrations

Auto-instrument LLM client libraries. Call once after st.init().

Symbol	Signature	Description
`staso.integrations.patch_anthropic`	`patch_anthropic() -> None`	Auto-instrument the Anthropic SDK (`anthropic.Anthropic`, `AsyncAnthropic`, streaming, tool use).
`staso.integrations.patch_openai`	`patch_openai() -> None`	Auto-instrument the OpenAI SDK (`openai.OpenAI`, `AsyncOpenAI`, chat completions, streaming, tool calls).

See Integrations.

Dataset module

Import as import staso as st — every function is a top-level attribute on st.dataset. import staso.dataset also returns the real module.

CRUD

Symbol	Signature
`st.dataset.create`	`create(name: str, *, description: str = "", columns: list[dict[str, str]] \| None = None, folder_id: str \| None = None) -> Dataset`
`st.dataset.get`	`get(dataset_id: str) -> Dataset`
`st.dataset.list`	`list(*, folder_id: str \| None = None, limit: int = 100, offset: int = 0) -> list[Dataset]`
`st.dataset.update`	`update(dataset_id: str, *, name: str \| None = None, description: str \| None = None) -> Dataset`
`st.dataset.delete`	`delete(dataset_id: str) -> None`

Entries

Symbol	Signature
`st.dataset.add_entry`	`add_entry(dataset_id: str, data: dict[str, Any], *, split: str \| SplitType \| None = None, source_trace_id: str \| None = None, source_span_id: str \| None = None) -> DatasetEntry`
`st.dataset.add_entries`	`add_entries(dataset_id: str, entries: list[dict[str, Any]], *, split: str \| SplitType \| None = None) -> list[DatasetEntry]`
`st.dataset.list_entries`	`list_entries(dataset_id: str, *, split: str \| SplitType \| None = None, limit: int = 100, offset: int = 0) -> list[DatasetEntry]`
`st.dataset.update_entry`	`update_entry(dataset_id: str, entry_id: str, *, data: dict[str, Any] \| None = None) -> DatasetEntry`
`st.dataset.delete_entry`	`delete_entry(dataset_id: str, entry_id: str) -> None`

CSV

Symbol	Signature
`st.dataset.upload_csv`	`upload_csv(dataset_id: str, file_path: str \| Path, *, split: str \| SplitType \| None = None) -> int`
`st.dataset.download_csv`	`download_csv(dataset_id: str, file_path: str \| Path, *, split: str \| SplitType \| None = None) -> Path`

From traces

Symbol	Signature
`st.dataset.from_traces`	`from_traces(name: str, trace_ids: list[str], *, mapping: list[TraceColumnMapping] \| dict[str, str] \| None = None, description: str = "") -> Dataset`
`st.dataset.TraceColumnMapping`	`dataclass(frozen=True)` with fields: `source: str`, `target: str`

Evaluation

Symbol	Signature
`st.dataset.evaluate`	`evaluate(dataset_id: str, fn: Callable[[dict[str, Any]], Any], *, scorers: list[Callable[[dict, Any], float]] \| None = None, split: str \| SplitType \| None = None, max_concurrency: int = 1, trace: bool = True) -> EvalSummary`
`st.EvalResult`	`dataclass(frozen=True)` — `entry_id`, `input_data`, `expected`, `actual`, `scores: dict[str, float]`, `passed: bool`, `error: str \| None`, `trace_id: str \| None`, `duration_ms: float`
`st.EvalSummary`	`dataclass(frozen=True)` — `dataset_id`, `dataset_name`, `total`, `passed`, `failed`, `error_count`, `avg_duration_ms`, `scores: dict[str, float]`, `results: tuple[EvalResult, ...]`

Synthetic

Symbol	Signature
`st.dataset.generate`	`generate(dataset_id: str, *, count: int = 10, prompt: str \| None = None, seed_entry_ids: list[str] \| None = None) -> list[DatasetEntry]`

Folders

Symbol	Signature
`st.dataset.create_folder`	`create_folder(name: str, *, parent_id: str \| None = None) -> DatasetFolder`
`st.dataset.list_folders`	`list_folders(*, parent_id: str \| None = None) -> list[DatasetFolder]`
`st.dataset.delete_folder`	`delete_folder(folder_id: str) -> None`

Types

Symbol	Fields
`st.Dataset`	`id`, `name`, `description`, `folder_id`, `template`, `columns: tuple[DatasetColumn, ...]`, `entry_count`, `created_at`, `updated_at`
`st.DatasetEntry`	`id`, `dataset_id`, `data: dict[str, Any]`, `split: str \| None`, `source_type: str \| None`, `created_at`
`st.DatasetColumn`	`name`, `column_type: str = "variable"`, `description`, `required: bool = False`
`st.DatasetFolder`	`id`, `name`, `parent_id: str \| None`
`st.ColumnType`	`StrEnum` — `variable`, `input`, `output`, `expected_output`, `expected_tool_calls`, `scenario`, `expected_steps`, `conversation_history`, `files`, `custom`
`st.SplitType`	`StrEnum` — `train`, `test`, `validation`
`st.StasoDatasetError`	`Exception` — `message`, `status_code: int \| None`, `response_body: str`

See Datasets and Evaluation.

Types

Symbol	Values
`st.SpanKind`	`StrEnum` — `LLM`, `TOOL`, `CHAIN`, `RETRIEVER`, `AGENT`, `CUSTOM`
`st.SpanStatus`	`StrEnum` — `OK`, `ERROR`, `TIMEOUT`

See Data Model for field-by-field semantics.

Configuration objects

Symbol	Description
`st.Client`	The object returned by `st.init`. Holds the transport and config. Users rarely construct this directly.
`st.Config`	`dataclass(frozen=True)` — full field list: `api_key`, `agent_name`, `agent_id`, `base_url`, `batch_size=100`, `flush_interval=5.0`, `max_queue_size=10_000`, `enabled=True`, `debug=False`, `environment="default"`, `workspace_slug="default"`, `capture_messages=True`, `git_context`
`st.Span`	The span class yielded by `st.span` and by decorators. Fields listed above under Context managers.

Errors

Exception	Raised by	When
`st.GuardBlocked`	`patch_openai`, `patch_anthropic`	An enforce-mode guard rule blocked one or more tool calls.
`st.StasoDatasetError`	`st.dataset.*`	Backend returned a non-2xx response (`status_code`, `response_body` on the exception).
`ValueError`	`st.init`, `st.annotate`	Missing `api_key`/`agent_name`, or annotation value type mismatch.

Environment variables

See Environment Variables for the complete list of STASO_* variables read by the SDK, CLI, and integrations.

Version

Symbol	Description
`staso.__version__`	Installed SDK version string.

On this page