API reference

The package exports SovaraClient and trace. Trace-scoped helpers are methods on SovaraClient; module-level recording scopes and logging helpers are not supported. For existing integrations, client.run(run_id=...), client.subrun() and client.get_run_id() remain deprecated aliases for the trace methods below. client.log() also accepts run_id, run_input and run_output; supplying both an old and new name for the same field raises an error. These aliases use the current server contract and trace ID derivation.

`SovaraClient(*, project_name, base_url=None, agent_token=None, http_client=None)`

Creates a client bound to one project name. Project admins can rename a project from the Sovara app; update this value when they do.

from sovara import SovaraClient

client = SovaraClient(project_name="finance-agent")

Parameter	Required	Purpose
`project_name`	Yes	Stable project name for every top-level trace created by this client.
`base_url`	No	Execution server URL. Defaults to `SOVARA_EXEC_SERVER_URL`, otherwise `http://127.0.0.1:5960` (port configurable with `SOVARA_EXEC_SERVER_PORT`). Set environment variables before importing Sovara.
`agent_token`	No	Project-scoped token for an agent host without a signed-in Sovara user. Pass it explicitly; the Python client does not read `SOVARA_AGENT_TOKEN` automatically.
`http_client`	No	Caller-owned synchronous `httpx.Client`. Sovara uses it for lifecycle and runtime requests and does not close it.

For a remote server, pass base_url and agent_token explicitly:

import os
from sovara import SovaraClient

client = SovaraClient(
    project_name="finance-agent",
    base_url="https://exec.example.com",
    agent_token=os.environ["SOVARA_AGENT_TOKEN"],
)

`client.trace(name=None, *, trace_id=None, eval_run_id=None, capture_logs=True, lesson_scope=<inherit>)`

Opens a recording session on a durable trace, usable with with or async with. No turn is created implicitly; work outside turn() remains recorded without a turn.

with client.trace("sync-agent"):
    ...

async with client.trace("async-agent", trace_id=chat_id):
    ...

Argument	Purpose
`name`	Optional display name. Sovara generates one when omitted.
`trace_id`	Optional. Pass your own stable identifier or the ID yielded by a previous SDK trace. Reuse it to add steps to the same trace in this project.
`eval_run_id`	Optional eval run that owns this trace. Set it when the trace starts; subtraces inherit it and it cannot change later.
`capture_logs`	Captures `stdout` and `stderr` by default. Disable for concurrent top-level traces.
`lesson_scope`	Folder path or list for this trace. Omit to inherit; `None` selects root/all; `[]` disables retrieval.

Entering the context yields the trace ID, or None if recording is unavailable. Use a stable trace_id to append to the same trace. A sovara- ID must already exist in the project.

`client.subtrace(name, *, lesson_scope=<inherit>)`

Creates a child trace under the active trace.

with client.trace("batch"):
    with client.subtrace("sample-1"):
        trace_one_sample()

name is required. Returns SovaraTraceContext, supporting with and async with; entering it yields the subtrace’s trace ID, or None in no-capture mode. Requires an enclosing trace opened by the same client.

`client.turn(*, turn_input=None)`

Groups one interaction in the active trace or subtrace. Supports with and async with, yielding the turn ID or None if recording is unavailable. turn_input accepts a string or None. Use the same client and do not nest turns within a trace.

with client.trace("conversation", trace_id="chat-123"):
    with client.turn(turn_input="Hi.") as turn_id:
        reply = respond()

Finish tasks and streams before leaving the trace. See the usage guide for turn examples.

`trace(fn=None, *, name=None, meta=None)`

Wraps a sync or async function as a tool-like step. It is the only top-level instrumentation helper. It records a step inside the current trace and does not open a trace; use client.trace() for that.

from sovara import trace

@trace(name="lookup_customer", meta={"system": "crm"})
def lookup_customer(customer_id: str):
    return crm.get(customer_id)

Argument	Purpose
`fn`	Function to wrap. Omit when using decorator options.
`name`	Optional step name; defaults to the function name.
`meta`	Optional step metadata.

The wrapper preserves the call signature, records arguments and return values, records raised exceptions, and re-raises them.

Lesson methods

`client.lesson_scope(scope)`

Temporarily replaces the active lesson scope. Paths include descendants; None means root/all and [] disables retrieval.

with client.lesson_scope(["conventions/", "markets/"]):
    call_model()

`client.disable_lesson_injection()`

Temporarily prevents automatic lesson retrieval while leaving tracing active.

`client.create_eval_run()`

Creates an evaluation in the client’s project and returns its eval_run_id. Record samples with client.trace(eval_run_id=...), then log results with client.log().

`client.log(*, trace_id=..., eval_run_id=..., **fields)`

Logs to an explicit target, including after the recording context closes. No identifier is inherited from a context. Agent traces and eval runs must already exist.

Supplied targets	Meaning
`trace_id`	Update that trace or subtrace using its Sovara ID or your own identifier.
`eval_run_id`	Update custom fields on that eval run.
Both	Check that the eval run owns the trace, then update the trace’s fields.
Neither	Validation error.

Reserved fields trace_input, trace_output, groundtruth, and llm_judge_output accept strings; llm_judge_is_correct accepts a boolean. These require trace_id. Custom fields accept booleans, strings, finite floats, and integers between -253 and 253. Explicit None is invalid. Writes replace supplied fields and leave others unchanged. Logging never changes a trace’s evaluation owner. groundtruth updates the trace annotation; llm_judge_is_correct records a separate evaluation verdict. See Evaluations for aggregate metrics and accuracy.

eval_run_id = client.create_eval_run()
with client.trace(eval_run_id=eval_run_id) as trace_id:
    if trace_id is None:
        raise RuntimeError("This evaluation requires a recorded sample.")
    client.log(trace_id=trace_id, trace_input=question, groundtruth=expected_answer)
    answer = agent(question)

client.log(
    trace_id=trace_id,
    eval_run_id=eval_run_id,
    trace_output=answer,
    llm_judge_output="The answer matches the expected value.",
    llm_judge_is_correct=True,
    latency_ms=842,
)
client.log(eval_run_id=eval_run_id, accuracy=1.0, sample_count=1)

log() and create_eval_run() are synchronous and raise on errors. Skip trace logging when recording yields None. After a timeout, check the saved result before retrying; the write may have succeeded.

`client.get_trace_id()`

Returns the current trace or subtrace ID as a string, or None when called outside an active trace.

trace_id = client.get_trace_id()

Context and tracing controls

`client.with_context(fn)`

Captures the current context and returns a wrapper for another thread.

executor.submit(client.with_context(eval_sample), sample)

`client.disable_tracing()`

Temporarily disables supported provider, MCP, and explicit trace recording.

with client.disable_tracing():
    noisy_or_sensitive_work()

Get started

Use the SDK

Reference

`SovaraClient(*, project_name, base_url=None, agent_token=None, http_client=None)`

`client.trace(name=None, *, trace_id=None, eval_run_id=None, capture_logs=True, lesson_scope=<inherit>)`

`client.subtrace(name, *, lesson_scope=<inherit>)`

`client.turn(*, turn_input=None)`

`trace(fn=None, *, name=None, meta=None)`

Lesson methods

`client.lesson_scope(scope)`

`client.disable_lesson_injection()`

`client.create_eval_run()`

`client.log(*, trace_id=..., eval_run_id=..., **fields)`

`client.get_trace_id()`

Context and tracing controls

`client.with_context(fn)`

`client.disable_tracing()`

​SovaraClient(*, project_name, base_url=None, agent_token=None, http_client=None)

​client.trace(name=None, *, trace_id=None, eval_run_id=None, capture_logs=True, lesson_scope=<inherit>)

​client.subtrace(name, *, lesson_scope=<inherit>)

​client.turn(*, turn_input=None)

​trace(fn=None, *, name=None, meta=None)

​Lesson methods

​client.lesson_scope(scope)

​client.disable_lesson_injection()

​client.create_eval_run()

​client.log(*, trace_id=..., eval_run_id=..., **fields)

​client.get_trace_id()

​Context and tracing controls

​client.with_context(fn)

​client.disable_tracing()

`SovaraClient(*, project_name, base_url=None, agent_token=None, http_client=None)`

`client.trace(name=None, *, trace_id=None, eval_run_id=None, capture_logs=True, lesson_scope=<inherit>)`

`client.subtrace(name, *, lesson_scope=<inherit>)`

`client.turn(*, turn_input=None)`

`trace(fn=None, *, name=None, meta=None)`

Lesson methods

`client.lesson_scope(scope)`

`client.disable_lesson_injection()`

`client.create_eval_run()`

`client.log(*, trace_id=..., eval_run_id=..., **fields)`

`client.get_trace_id()`

Context and tracing controls

`client.with_context(fn)`

`client.disable_tracing()`