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.5.1

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.5.1
File	Size	Uploaded
trajectory_sdk-0.5.1.tar.gz	109.6 kB	Aug 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for trajectory-sdk 0.5.1
File	Interpreter	ABI	Platform	Reset
trajectory_sdk-0.5.1-py3-none-any.whl 104.0 kB Aug 11, 2026	Python 3	none	any	Details

Total release size: 213.6 kB

Release files / trajectory_sdk-0.5.1.tar.gz

Download URL	trajectory_sdk-0.5.1.tar.gz
Size	109.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`dd367818369c39b3737c3f030e385b022e472f4b40d7a377424aafdf0f477313`
BLAKE2b-256 checksum How to use checksums	`2234336dca9d012e382c8a42ecd2ff62077b5809daa933e27ea0d13fb2b0c5d3`
Upload date	Aug 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/ae40cf71853a4a9c24bbe1f64f5c3ab39b320345

Workflow

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

Artifact

Subject: trajectory_sdk-0.5.1.tar.gz
SHA-256 checksum: dd367818369c39b3737c3f030e385b022e472f4b40d7a377424aafdf0f477313 Verifying attestations

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

Download URL	trajectory_sdk-0.5.1-py3-none-any.whl
Size	104.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`bf1e5be9eab5914e8670e4e81e73534aedce3ec123e8cab85038e870755e887f`
BLAKE2b-256 checksum How to use checksums	`b8a1cf6ef402861631575fd5ffc776d8c885cb189597726a0ecb1a4160bc5035`
Upload date	Aug 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/ae40cf71853a4a9c24bbe1f64f5c3ab39b320345

Workflow

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

Artifact

Subject: trajectory_sdk-0.5.1-py3-none-any.whl
SHA-256 checksum: bf1e5be9eab5914e8670e4e81e73534aedce3ec123e8cab85038e870755e887f Verifying attestations