trajectory-sdk 0.1.2

SDK for importing and transforming agent traces into Trajectory format

trajectory-sdk

Import and transform agent traces from LangSmith (and other providers) into a standardized Trajectory format.

Install

pip install trajectory-sdk

Quick Start

import trajectory_sdk as tj

tj.init(provider="langsmith", api_key="lsv2_pt_...", project_id="...")

# List available conversations
conversations = tj.list_conversations()

# Import and save all conversations
trajectories = tj.import_conversations(conversations)
tj.save(trajectories, "./exports")

API

tj.init(*, provider, api_key, project_id, storage_dir, debug)

Configure the SDK. Call once before other functions.

tj.init(
    provider="langsmith",       # trace provider (default: "langsmith")
    api_key="lsv2_pt_...",      # provider API key
    project_id="...",           # provider project ID
    storage_dir="~/.trajectory", # local staging directory (default)
    debug=False,                 # enable debug logging (default: False)
)

tj.list_conversations(*, limit) -> list[ConversationSummary]

List available conversations from the configured provider.

conversations = tj.list_conversations(limit=100)
for c in conversations:
    print(c.conversation_id, c.num_turns)

tj.import_conversations(conversations, *, stage, redactor) -> list[Trajectory]

Import conversations and return one Trajectory per conversation. Accepts a list of conversation ID strings or ConversationSummary objects.

# By ID
trajectories = tj.import_conversations(["cc_abc123", "cc_def456"])

# By ConversationSummary (from list_conversations)
conversations = tj.list_conversations()
trajectories = tj.import_conversations(conversations)

# With optional PII redaction
trajectories = tj.import_conversations(["cc_abc123"], redactor=my_redactor)

# Without local staging
trajectories = tj.import_conversations(["cc_abc123"], stage=False)

tj.save(trajectories, output_dir)

Save trajectories to JSON files. Each trajectory is written to {output_dir}/{conversation_id}.json.

# Save all
tj.save(trajectories, "./exports")

# Save a single trajectory
tj.save(trajectories[0], "./exports")

tj.transform(raw_data, *, provider, api_key, project_id, redactor) -> Trajectory

Transform raw conversation data without fetching from a provider. For custom pipelines.

trajectory = tj.transform(raw_data, provider="langsmith")

Full Example

import trajectory_sdk as tj

tj.init(provider="langsmith", api_key="lsv2_pt_...", project_id="...")

# List, import, and save everything
conversations = tj.list_conversations(limit=200)
trajectories = tj.import_conversations(conversations)
tj.save(trajectories, "./exports")

print(f"Exported {len(trajectories)} trajectories")
for t in trajectories:
    print(f"  {t.task.conversation_id}: {t.task.num_turns} turns, {len(t.steps)} steps")