Metadata-Version: 2.4
Name: tracelab-sdk
Version: 0.1.0
Summary: Python trace instrumentation for LLM applications and agents
License-Expression: MIT
Keywords: llm,agents,observability,tracing,evaluation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28
Dynamic: license-file

# TraceLab Python SDK

Record traces from your LLM application or agent and send them to a TraceLab backend. Inspect inputs, outputs, nested operations, errors, latency, and usage in the TraceLab workspace.

Requires Python 3.11+ and a running TraceLab backend with a project API key. This package contains the instrumentation client; run the backend and workspace separately.

## Install

Install the released SDK from PyPI:

```bash
python -m pip install tracelab-sdk
```

For a local or unpublished build, install its wheel directly:

```bash
python -m pip install ./tracelab_sdk-0.1.0-py3-none-any.whl
```

## Connect your application

Set the address of your TraceLab backend and a key issued by that deployment:

```bash
export TRACELAB_URL="http://127.0.0.1:8000"
export TRACELAB_API_KEY="YOUR_PROJECT_KEY"
```

For a shared deployment, use its HTTPS address instead of localhost. Keep the project key in your server environment.

Wrap your existing model function with a trace and an LLM span:

```python
import os

from tracelab import TraceLabClient

client = TraceLabClient(
    base_url=os.environ["TRACELAB_URL"],
    api_key=os.environ["TRACELAB_API_KEY"],
    service_name="my-agent",
    spool_dir=".tracelab-spool",
)


def traced_answer(question, call_model):
    with client.trace(
        "answer-question",
        workflow_version="v1",
        input={"question": question},
    ) as trace:
        with trace.span("generate-answer", "llm", input=question) as span:
            answer = call_model(question)
            span.set_output(answer)
        trace.set_output(answer)
    return answer
```

Call `traced_answer(question, your_existing_model_function)` with a function that returns a JSON-serializable result. Reuse the client across requests and call `client.close()` at application shutdown. Each trace exports when its context closes.

Open the workspace connected to the same project key to inspect the run. Exceptions are recorded and re-raised to your application.

## Record tools, usage, and evaluations

- Nest `trace.span("lookup-order", "tool")` inside a trace to record a tool call. Set its input and output explicitly; nested spans retain their parent relationships.
- Call `span.set_usage(input_tokens=12, output_tokens=7)` with the actual provider-reported counts. An optional `cost_usd` records a cost you supply; the SDK does not calculate prices.
- Use an `evaluator` span to record a check you implement. Set its output to a JSON object such as `{"passed": False, "score": 0}`, and call `span.set_error("explanation")` to mark a failed check without raising.
- Set `workflow_version` to identify prompt or application versions for comparisons. The package does not include the sample support agent, its dataset, or its experiment runner.

Instrumentation and evaluation are explicit. The SDK does not automatically capture model calls, score answers, or send regression alerts.

## Export behavior

Exports are synchronous, with bounded retries for transient failures. Retry time adds to the duration of closing a trace. An export failure emits a warning and preserves your application's result or original exception.

With `spool_dir` set, failed HTTP exports are saved to private JSON files. Retry them after restoring connectivity:

```python
client.retry_exports()
```

Acknowledged files are removed; unsuccessful ones are retained. Common credential fields and email addresses are redacted before export and spooling. This is conservative filtering, not a comprehensive PII detector.

## License

The Python SDK is licensed under [MIT](LICENSE).
