Documentation Index
Fetch the complete documentation index at: https://docs.getbasalt.ai/llms.txt
Use this file to discover all available pages before exploring further.
Migrating from v0 to v1
Basalt v1 is a major update that introduces a unified observability system based on OpenTelemetry and a more consistent SDK API. This guide covers the main changes you need to make when upgrading.
Key Changes at a Glance
| Feature | v0 (Legacy) | v1 (Current) |
|---|
| Prompts API | basalt.prompt | basalt.prompts |
| Tracing | basalt.monitor / generation.end() | start_observe / observe |
| Identity | Manual in log or trace | Automatic via context propagation |
| Error Handling | Error as value (error, result = ...) | Standard Python Exceptions |
1. Prompts API
The prompts API has been renamed from prompt to prompts (plural) and now distinguishes between synchronous and asynchronous calls.
# Always async, returns a tuple
error, prompt, generation = await basalt.prompt.get('my-slug')
2. Observability & Tracing
The biggest change in v1 is the move to a unified observability model. Instead of manually logging generations or ending traces, you now use decorators or context managers.
Basic Tracing
error, prompt, generation = await basalt.prompt.get('my-slug')
output = call_llm(prompt.text)
generation.end(output)
3. Identity Tracking
In v0, you had to pass user and organization information to every log or trace call. In v1, you set it once at the start of your trace, and it flows automatically to all nested spans.
basalt.monitor.log(
event="llm_call",
user_id="user_123",
org_id="org_456",
...
)
4. Error Handling (Exceptions vs Error as Value)
In v0, the SDK followed an “error as value” pattern (similar to Go), where most methods returned a tuple containing an error object and the result. In v1, the SDK uses standard Python exceptions for a more idiomatic experience.
# Methods return (error, result, ...)
error, prompt, generation = await basalt.prompt.get('my-slug')
if error:
print(f"Error: {error.message}")
else:
print(prompt.text)
