Installation
Install the Tracia SDK using pip:
Requirements
- Python 3.10+
- Dependencies:
httpx, pydantic, litellm
Configuration
Initialize the Tracia client with your API key:
from tracia import Tracia
client = Tracia(api_key="tr_your_api_key_here")
Configuration Options
| Option | Type | Required | Description |
|---|
api_key | str | Yes | Your Tracia API key (starts with tr_) |
base_url | str | No | Override the API base URL (default: https://app.tracia.io) |
on_span_error | Callable[[Exception, str], None] | No | Callback for background span submission failures |
Environment Variables
We recommend storing your API key in environment variables:
TRACIA_API_KEY=tr_your_api_key_here
import os
from tracia import Tracia
client = Tracia(api_key=os.environ["TRACIA_API_KEY"])
Never commit API keys to version control. Use environment variables or a secrets manager.
Context Manager
The SDK supports context managers for automatic resource cleanup:
with Tracia(api_key="tr_your_api_key") as client:
result = client.run_local(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
print(result.text)
# Resources cleaned up automatically
Async Context Manager
async with Tracia(api_key="tr_your_api_key") as client:
result = await client.arun_local(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
print(result.text)
Async Support
Every method has both sync and async variants. Async methods use the a prefix:
from tracia import Tracia
client = Tracia(api_key="tr_your_api_key")
# Sync
result = client.run_local(model="gpt-4o", messages=[...])
prompts = client.prompts.list()
# Async
result = await client.arun_local(model="gpt-4o", messages=[...])
prompts = await client.prompts.alist()
Type Exports
The SDK exports all types for type checking:
from tracia import (
Tracia,
TraciaSession,
TraciaError,
TraciaErrorCode,
Eval,
# Streaming
LocalStream,
AsyncLocalStream,
# Core types
LLMProvider,
TokenUsage,
FinishReason,
# Message types
LocalPromptMessage,
ContentPart,
TextPart,
ToolCallPart,
# Tool types
ToolDefinition,
ToolCall,
ToolChoice,
# Run local types
RunLocalInput,
RunLocalResult,
StreamResult,
# Span types
Span,
ListSpansOptions,
ListSpansResult,
EvaluateOptions,
EvaluateResult,
# Prompt types
Prompt,
PromptListItem,
PromptMessage,
CreatePromptOptions,
UpdatePromptOptions,
RunOptions,
RunResult,
)
Next Steps
