trajectory-sdk 0.1.1

Use the Trajectory SDK to instrument your codebase for continual learning

Trajectory SDK

Use the Trajectory SDK to instrument your codebase for continual learning.

Installation

pip install trajectory-sdk

Quick Start

import trajectory_sdk as tj

# Initialize with LangSmith credentials
tj.init(provider="langsmith", api_key="lsv2_pt_...", project_id="...")

# List available conversations
conversations = tj.list_conversations()

# Import a single conversation
trajectories = tj.import_conversation("cc_0t9n9qfgH4qayTPXAdg")

# Import multiple conversations
result = tj.import_conversations(["cc_...", "cc_..."])
print(f"Imported: {result.imported}, Failed: {result.failed}")

Features

• Provider-agnostic — pluggable provider system (LangSmith supported, extensible to others)
• Structured output — converts raw traces into typed Trajectory objects with steps, messages, tool calls, and metrics
• Deduplication — content hashing and idempotency keys prevent duplicate imports
• Local staging — optional SQLite + gzip storage for offline processing
• PII redaction — pluggable redactor interface for scrubbing sensitive data

Usage

Transform raw data without fetching

trajectories = tj.transform(raw_conversation_dict, provider="langsmith")

Custom PII redaction

from trajectory_sdk import BasePiiRedactor, Trajectory

class MyRedactor(BasePiiRedactor):
    def redact(self, trajectory: Trajectory) -> Trajectory:
        # your redaction logic
        ...

    def preview(self, trajectories):
        # preview what would be redacted
        ...

trajectories = tj.import_conversation("cc_...", redactor=MyRedactor())

Implement a custom provider

from trajectory_sdk import BaseProvider

class MyProvider(BaseProvider):
    def fetch_conversation(self, conversation_id):
        ...

    def parse_conversation(self, raw_data):
        ...

    def list_conversations(self, query=None, limit=50):
        ...

Output Schema

Each Trajectory contains:

• task — the initial user request
• steps — cumulative message sequences up to each decision point
• reward — aggregated reward value and components
• metrics — step count, token usage, tool call/failure counts
• execution_metrics — timing (LLM time, env time, total) and termination reason

Messages within steps have a role (system, user, assistant, tool) and may include tool_calls or tool_response objects.

Requirements

• Python 3.11+
• langsmith>=0.1.0

License

MIT