Skip to main content

​
Prerequisites

  • Python 3.11 or higher
  • A LangSmith API key (starts with lsv2_pt_...)
  • A LangSmith project with existing traces

​
Installation

pip install trajectory-sdk
For bulk imports from Parquet files, install with the parquet extra: 
pip install "trajectory-sdk[parquet]"

​
Your First Import

import trajectory_sdk as tj

# 1. Configure the SDK
tj.init(
    provider="langsmith",
    api_key="lsv2_pt_...",
    project_id="your-project-id",
)

# 2. List available conversations
conversations = tj.list_conversations(limit=10)

for c in conversations:
    print(f"{c.conversation_id} — {c.num_turns} turns")

# 3. Import conversations as Trajectories
trajectories = tj.import_conversations(conversations)

# 4. Save to disk
tj.save(trajectories, "./exports")

print(f"Exported {len(trajectories)} trajectories")
This will:
  1. Connect to LangSmith using your API key
  2. List the 10 most recent conversations in your project
  3. Fetch the full run tree for each conversation, extract messages, and build Trajectories
  4. Write each Trajectory as a JSON file to ./exports/

​
Inspect a Trajectory

Each exported Trajectory is a structured object you can inspect programmatically: 
t = trajectories[0]

print(f"Conversation: {t.task.conversation_id}")
print(f"Turns: {t.task.num_turns}")
print(f"Steps: {len(t.steps)}")

for i, step in enumerate(t.steps):
    print(f"\n--- Step {i} ---")
    for msg in step.messages:
        role = msg.role
        content = msg.content[:80] if msg.content else "(tool call)"
        print(f"  [{role}] {content}")

​
Import by Conversation ID

If you already know which conversations you want, pass their IDs directly: 
trajectories = tj.import_conversations([
    "cc_abc123",
    "cc_def456",
])

​
Next Steps

Core Concepts

Learn what Trajectories, Steps, and Messages represent.

Bulk Import

Import thousands of conversations from provider exports.

Local Import

Import from local Parquet files.

API Reference

Full function signatures and parameters.