> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The public Sovara Python SDK surface and exact client methods.

<script src="/assets/sdk-nav.js" />

The package exports `SovaraClient` and `trace`. Run-scoped helpers are methods
on `SovaraClient`; module-level `run`, `subrun`, and logging helpers are not
supported.

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

Creates a client bound to one immutable project name.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from sovara import SovaraClient

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

| Parameter      | Required | Purpose                                                                                                           |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `project_name` | Yes      | Stable project name for every top-level run created by this client.                                               |
| `base_url`     | No       | Exec server URL. Defaults to `SOVARA_EXEC_SERVER_URL` or the local exec server.                                   |
| `agent_token`  | No       | Project-scoped token for an agent host without a signed-in Sovara user.                                           |
| `http_client`  | No       | Caller-owned synchronous `httpx.Client`. Sovara uses it for lifecycle and runtime requests and does not close it. |

`client.project_name` is read-only. For a remote agent host, keep the token in
the host's secret manager or an excluded `.env` file and pass it explicitly:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import httpx
from sovara import SovaraClient

http_client = httpx.Client()  # Optional: proxy, custom CA, or other transport settings.
client = SovaraClient(
    project_name="finance-agent",
    base_url="https://exec.example.com",
    agent_token=os.environ["SOVARA_AGENT_TOKEN"],
    http_client=http_client,
)
```

The custom client is optional. Without it, Sovara creates and manages its
normal internal HTTP client.

## `client.run(name=None, *, client_run_id=None, capture_logs=True, lesson_scope=<inherit>)`

Creates a top-level run context usable with `with` or `async with`.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
with client.run("sync-agent"):
    ...

async with client.run("async-agent", client_run_id=chat_id):
    ...
```

| Argument        | Purpose                                                                                              |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| `name`          | Optional display name. Sovara generates one when omitted.                                            |
| `client_run_id` | Optional project-scoped application ID for appendable workflows.                                     |
| `capture_logs`  | Captures `stdout` and `stderr` by default. Disable for concurrent top-level runs.                    |
| `lesson_scope`  | Folder path or list for this run. Omit to inherit; `None` selects root/all; `[]` disables retrieval. |

Returns `SovaraRunContext`.

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

Creates a child run under the active run.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
with client.run("batch"):
    with client.subrun("sample-1"):
        run_one_sample()
```

`name` is required. Returns `SovaraRunContext`.

## `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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
with client.lesson_scope(["conventions/", "markets/"]):
    call_model()
```

### `client.inject_lessons(context=None)`

Retrieves lessons for the active run and returns a prompt-ready managed block,
or `""` outside a run or when nothing matches.

### `client.disable_lesson_injection()`

Temporarily prevents automatic lesson retrieval while leaving tracing active.

## `client.log_input(input)`

Stores the latest user-visible input string on the active run. This value
appears in the Input column of the Runs table and replaces the previously
logged input.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara_client.log_input(question)
```

Outside an active run, it logs a warning and does nothing.

## `client.log_output(output)`

Stores the latest user-visible output string on the active run. This value
appears in the Output column of the Runs table and replaces the previously
logged output.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara_client.log_output(answer)
```

Outside an active run, it logs a warning and does nothing.

## `client.log_metrics(**metrics)`

Adds filterable custom metrics to the active run. Values must be booleans,
integers, or finite floats; keys must be lower snake case and at most 32
characters.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara_client.log_metrics(answered=True, latency_ms=842)
```

Logging the same key again updates its latest value. Outside an active run, it
logs a warning and does nothing.

## `client.get_run_id()`

Returns the current run or subrun ID as a string, or `None` when called outside
an active run.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
run_id = sovara_client.get_run_id()
```

## Context and tracing controls

### `client.with_context(fn)`

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
executor.submit(client.with_context(eval_sample), sample)
```

### `client.disable_tracing()`

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
with client.disable_tracing():
    noisy_or_sensitive_work()
```