trajectory-sdk

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

Install

pip install trajectory-sdk

Quick Start

Individual conversation import

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")

Bulk export (E2E)

Export all conversations from a LangSmith project, parse into Trajectories, and upload to GCS + BigQuery in three lines:

import trajectory_sdk as tj

tj.init(
    provider="langsmith",
    api_key="lsv2_pt_...",
    project_id="...",
    workspace_id="...",
    destination_id="...",
)
trajectories = tj.import_conversations(bulk=True)
tj.upload(trajectories, dataset="my_dataset")

This automatically discovers all trace IDs, triggers a LangSmith bulk export, downloads the parquet from GCS, and parses it into Trajectory objects.

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 (or set LANGSMITH_API_KEY env var)
    project_id="...",            # provider project/session ID
    workspace_id="...",          # LangSmith workspace/tenant ID (required for bulk export)
    destination_id="...",        # bulk export destination ID (required for bulk export)
    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)

# Bulk export from a local parquet file
trajectories = tj.import_conversations(bulk=True, source="export.parquet")

# Live bulk export (triggers export, downloads, parses)
trajectories = tj.import_conversations(bulk=True)

# 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.upload(trajectories, dataset)`

Upload trajectories to GCS and BigQuery.

tj.upload(trajectories, dataset="my_dataset")

`tj.save(trajectories, output_dir)`

Save trajectories to local 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")


## Full Example

```python
import trajectory_sdk as tj

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

# Bulk export everything and upload
trajectories = tj.import_conversations(bulk=True)
tj.upload(trajectories, dataset="production_traces")

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")

CLI: harness extraction

trajectory extract harness extracts an AI agent's harness — the scaffolding around the model (system prompts, tool definitions, the agentic loop, retry/compaction logic) — into a structured, reviewable spec. Run it from inside the agent's repo:

cd ~/code/my-agent
trajectory extract harness "the support-bot harness (prompts in app/prompts, loop in app/agent.py)"

This runs a read-only agent session that traces the codebase outward from the model call and writes .trajectory/harness.md. The flow:

Discover — walk cwd to the .git root.
Extract — a pluggable BaseAgent (Claude Code first) runs the bundled extract-harness skill with a read-only tool profile.
Persist — write the harness spec to .trajectory/harness.md.

The Claude Code backend requires ANTHROPIC_API_KEY (or a logged-in Claude Code install).

Release files for trajectory-sdk 0.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trajectory-sdk 0.4.2
File	Size	Uploaded
trajectory_sdk-0.4.2.tar.gz	105.5 kB	Jul 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for trajectory-sdk 0.4.2
File	Interpreter	ABI	Platform	Reset
trajectory_sdk-0.4.2-py3-none-any.whl 99.8 kB Jul 20, 2026	Python 3	none	any	Details

Total release size: 205.3 kB

Release files / trajectory_sdk-0.4.2.tar.gz

Download URL	trajectory_sdk-0.4.2.tar.gz
Size	105.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`293c107e50e0d8ffbfebe7290322be1b056010d13937c26371a8631b0d34e575`
BLAKE2b-256 checksum How to use checksums	`e8ea3f0ce710a71b134a35d22166e243245cb6855bc39a4c3b31ef9336e9c418`
Upload date	Jul 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Trajectorylabs/trajectory-platform
Publishing commit: github.com/Trajectorylabs/trajectory-platform/tree/24eee215c49a8e12fbd7595851d4ef6103ade927

Workflow

Publishing configuration: github.com/Trajectorylabs/trajectory-platform/blob/24eee215c49a8e12fbd7595851d4ef6103ade927/.github/workflows/publish-sdk.yml
Publishing logs: github.com/Trajectorylabs/trajectory-platform/actions/runs/29712891171/attempts/1

Artifact

Subject: trajectory_sdk-0.4.2.tar.gz
SHA-256 checksum: 293c107e50e0d8ffbfebe7290322be1b056010d13937c26371a8631b0d34e575 Verifying attestations

Release files / trajectory_sdk-0.4.2-py3-none-any.whl

Download URL	trajectory_sdk-0.4.2-py3-none-any.whl
Size	99.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f90e8e351fb8d0de93c196d3623486cd91dc71230b0de0f9c2560d43564072ad`
BLAKE2b-256 checksum How to use checksums	`92988cd5eb245da168a24540b4cec9e17d28b233c0c43a433374f7b69088dc0f`
Upload date	Jul 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Trajectorylabs/trajectory-platform
Publishing commit: github.com/Trajectorylabs/trajectory-platform/tree/24eee215c49a8e12fbd7595851d4ef6103ade927

Workflow

Publishing configuration: github.com/Trajectorylabs/trajectory-platform/blob/24eee215c49a8e12fbd7595851d4ef6103ade927/.github/workflows/publish-sdk.yml
Publishing logs: github.com/Trajectorylabs/trajectory-platform/actions/runs/29712891171/attempts/1

Artifact

Subject: trajectory_sdk-0.4.2-py3-none-any.whl
SHA-256 checksum: f90e8e351fb8d0de93c196d3623486cd91dc71230b0de0f9c2560d43564072ad Verifying attestations