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

Benchmark task tags

Benchmark tasks can carry explicit, queryable labels. Tags serialize as JSON arrays in the benchmark manifest.

task = tj.TaskSpec(
    name="task-1",
    tags=["recruiting"],
)

`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.4

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.4
File	Size	Uploaded
trajectory_sdk-0.4.4.tar.gz	105.8 kB	Jul 24, 2026	Details

Built distribution (wheel)

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

Total release size: 206.0 kB

Release files / trajectory_sdk-0.4.4.tar.gz

Download URL	trajectory_sdk-0.4.4.tar.gz
Size	105.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`e9a25410d5a28fed87ca91daf57f37f71b3d66b5827e59ea0747c15f63078247`
BLAKE2b-256 checksum How to use checksums	`02f01e2eaaa24df3d921cfc9d3648b74c8056f391666dc0f26908dbae43dbf02`
Upload date	Jul 24, 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/3e4179452f83fc9620256908cc7d99782e1f7498

Workflow

Publishing configuration: github.com/Trajectorylabs/trajectory-platform/blob/3e4179452f83fc9620256908cc7d99782e1f7498/.github/workflows/publish-sdk.yml
Publishing logs: github.com/Trajectorylabs/trajectory-platform/actions/runs/30079850870/attempts/1

Artifact

Subject: trajectory_sdk-0.4.4.tar.gz
SHA-256 checksum: e9a25410d5a28fed87ca91daf57f37f71b3d66b5827e59ea0747c15f63078247 Verifying attestations

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

Download URL	trajectory_sdk-0.4.4-py3-none-any.whl
Size	100.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f639747905ad539b437c554f1a536bfc272ace093fcb1efb46ec4c8d7e3d06c1`
BLAKE2b-256 checksum How to use checksums	`36d936dc0c44be6d7cf3ede88d79494dc57a9b35870c7fb8a6f7b8a5841833a6`
Upload date	Jul 24, 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/3e4179452f83fc9620256908cc7d99782e1f7498

Workflow

Publishing configuration: github.com/Trajectorylabs/trajectory-platform/blob/3e4179452f83fc9620256908cc7d99782e1f7498/.github/workflows/publish-sdk.yml
Publishing logs: github.com/Trajectorylabs/trajectory-platform/actions/runs/30079850870/attempts/1

Artifact

Subject: trajectory_sdk-0.4.4-py3-none-any.whl
SHA-256 checksum: f639747905ad539b437c554f1a536bfc272ace093fcb1efb46ec4c8d7e3d06c1 Verifying attestations