Functions
tj.init()
Configure the SDK. Call once before list_conversations() or import_conversations().
| Parameter | Type | Default | Description |
|---|---|---|---|
provider | str | "langsmith" | Trace provider to connect to |
api_key | str | required | Provider API key |
project_id | str | required | Provider project ID |
storage_dir | str | "~/.trajectory" | Directory for local staging data |
debug | bool | False | Enable debug logging |
tj.list_conversations()
List available conversations from the configured provider.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | int | 50 | Max conversations to return |
ConversationSummary:
| Field | Type | Description |
|---|---|---|
conversation_id | str | Unique conversation identifier |
num_turns | int | Number of turns |
first_seen | str | None | ISO timestamp of earliest trace |
last_seen | str | None | ISO timestamp of most recent trace |
root_run_names | list[str] | Names of top-level runs |
tj.import_conversations()
Import conversations and return one Trajectory per conversation.
| Parameter | Type | Default | Description |
|---|---|---|---|
conversations | list | None | Conversation IDs or ConversationSummary objects |
bulk | bool | False | Use bulk export path instead of API calls |
source | str | None | Path to local export file (required when bulk=True) |
stage | bool | True | Stage in local SQLite for deduplication |
redactor | BasePiiRedactor | None | PII redactor to apply after building |
tj.save()
Save Trajectories to JSON files on disk.
{output_dir}/{conversation_id}.json.
Data Models
All models are frozen dataclasses (immutable after construction).Trajectory
| Field | Type | Description |
|---|---|---|
task | Task | Conversation metadata |
steps | list[Step] | Ordered decision points with cumulative messages |
reward | Reward | None | Aggregate reward signal |
metrics | TrajectoryMetrics | None | Computed content metrics |
execution_metrics | ExecutionMetrics | None | Timing data |
error | str | None | Error if conversation failed |
Task
| Field | Type | Description |
|---|---|---|
conversation_id | str | None | Unique conversation identifier |
data_source | str | None | Provider name (e.g. "langsmith") |
num_turns | int | None | Number of user-agent turns |
num_steps | int | None | Number of steps |
total_tokens | int | None | Total tokens consumed |
total_cost | float | None | Estimated cost in USD |
Step
| Field | Type | Description |
|---|---|---|
messages | list[Message] | Cumulative messages up to this point |
reward | Reward | None | Per-step reward signal |
info | dict | None | Provider-specific metadata |
trainable_status | TrainableStatus | Training suitability flag |
Message
| Field | Type | Description |
|---|---|---|
role | Role | "system", "user", "assistant", or "tool" |
content | str | None | Text content (None for tool-call-only messages) |
tool_calls | list[ToolCall] | None | Tool invocations by the assistant |
tool_response | ToolResponse | None | Tool execution result |
usage | dict | None | Token usage stats |
finish_reason | str | None | Why the model stopped ("stop", "tool_calls") |
reasoning | str | None | Chain-of-thought content |
trainable_status | TrainableStatus | Training suitability flag |
ToolCall
| Field | Type | Description |
|---|---|---|
name | str | Tool name |
arguments | dict | Arguments passed to the tool |
id | str | None | Identifier matching the ToolResponse |
ToolResponse
| Field | Type | Description |
|---|---|---|
id | str | Matches the ToolCall id |
name | str | Tool name |
arguments | dict | Arguments that were passed |
response | Any | None | Return value |
error | str | None | Error if the call failed |
TrajectoryMetrics & ExecutionMetrics
| Field | Type | Description |
|---|---|---|
steps | int | None | Total steps |
tokens_generated | int | None | Total completion tokens |
num_tool_calls | int | None | Total tool invocations |
num_tool_failures | int | None | Failed tool calls |
tool_error_rate | float | None | Failure ratio |
env_time | float | None | Time in tool execution (seconds) |
llm_time | float | None | Time waiting for LLM (seconds) |
total_time | float | None | Wall-clock time (seconds) |
termination_reason | TerminationReason | None | Why the conversation ended |