Trajectory SDK
Generated Python client for the Trajectory API, with high-level workflows for uploading trajectories, telemetry, and runtime-backed benchmarks.
Install
pip install trajectory-sdk
For a coding agent, copy
the Trajectory skill
into your benchmark repo at .agents/skills/trajectory/SKILL.md for Codex or
.claude/skills/trajectory/SKILL.md for Claude Code.
Start here
Start with the SDK quickstart, then bring a benchmark, evaluate, train, and deploy. The installed SDK also includes these guides. The cookbook has worked integrations for different harnesses and graders.
Quick start
Set TRAJECTORY_API_KEY, then create a client:
from trajectory import Client
client = Client()
benchmarks = client.benchmarks.list(limit=10)
For task execution, follow the native benchmark harness and registration and image builds examples below.
SDK-owned API clients use a 600-second read/write/pool timeout and a 5-second connection timeout.
Supplying http_client= inherits that client's timeouts, including a bare HTTPX client's 5-second
default. An explicit Client(timeout=...) overrides the supplied client; a resource method's
timeout= overrides that request. timeout=None disables timeouts. Retry counts are unchanged.
Blob store uploads through signed URLs default to a one-hour timeout (3,600 seconds), configured
separately from API requests. Set upload_timeout=... on push(), start_push(), or
start_task_diagnostic(), or timeout=... on put_files(). Pass None to disable blob store
timeouts. These apply to individual HTTP operations against the blob store, not the total upload
duration or signed-URL expiry.
push() and start_push() retry each upload request up to upload_max_retries times (default
32, within 4.5 minutes of waiting), separately from the client's max_retries.
The generated resource methods map directly to the public HTTP API. Benchmark submission
and file-upload workflows are available from trajectory.lib.
Native benchmark harness
A task's run_command starts your program inside its runtime. This self-contained example uses
an inline question and expected answer for clarity. Inputs and references may come from files or
other sources; ensure the agent and its tools cannot access private reference data. input_messages
is stored task metadata; the native runtime does not send it to the model or to your program's
stdin. Your harness reads the input, calls the model, grades its answer, records the reward, and
completes the trajectory before exiting. The SDK has no trajectory CLI executable.
Managed runs supply TRAJECTORY_API_KEY and TRAJECTORY_BASE_URL.
Use Client() without embedding credentials in the image. trajectories.create() returns the
precreated trajectory ID; pass that ID explicitly to model, reward, and completion calls. Model
requests use the same client and API key, while the Backend resolves the model endpoint.
from trajectory import Client
client = Client()
question = "What is 2 + 2?"
expected_answer = "4"
tid = client.trajectories.create().tid
response = client.chat.completions.create(
model="policy",
messages=[{"role": "user", "content": question}],
x_trajectory_id=tid,
)
model_answer = response.choices[0].message.content or ""
reward = float(model_answer.strip() == expected_answer)
client.trajectories.log_reward(
tid,
name="accuracy",
value=reward,
)
client.trajectories.complete(tid, termination_reason="ENV_DONE")
Package this file and its dependencies in your Dockerfile. For example, copying it to
/app/harness.py makes python /app/harness.py the task's run_command. A wrong answer gets
reward zero and ENV_DONE. Process exit alone does not complete a trajectory.
Registration and image builds
Define a BenchmarkSpec named benchmark with your tasks, distinct train/test splits,
and a runtime such as DockerfileBuild("Dockerfile"). With the Dockerfile and harness under
the local benchmark/ directory,
choose or create an agent, then register the
benchmark and build its runtime. Replace YOUR_AGENT_NAME with that agent's name:
from pathlib import Path
from trajectory import Client
from trajectory.lib import push
client = Client()
result = push(
client, benchmark, agent_name="YOUR_AGENT_NAME", root=Path("benchmark"), build_images=True
)
The benchmark name comes from manifest.name: reusing a name under the same agent pushes
a new version.
Every new submission returns a new benchmark ID. Uploads do not accept a benchmark ID.
push() calls start_push() and waits for registration, returning a benchmark result
with bench_id. Both upload files with progress and accept the same arguments. Image builds
are off by default; pass build_images=True to include them and receive build failures
through the ingestion operation.
Use start_push() when you want control over waiting: it uploads files before returning
a BenchmarkOperation, while server processing continues. Call operation.result() to wait,
or save operation.id and reconnect later with get_operation(client, operation.id).
It is a regular Python function; it does not require await.
push() raises BenchmarkOperationError on a failed build; inspect its failures
for the affected runtime and build error. Once the runtime is ready, follow the
SDK benchmark guide's validation and evaluation steps; uploading does not execute
the tasks. Start evaluation or training with agent_name and benchmark_name
to select the latest version, or bench_id to select a specific version.
Run this registration code with your organization's API key.
Development
uv run pytest
uv run ruff check .
uv run ruff format --check .
The generated client lives in src/trajectory/. Handwritten workflows live in
src/trajectory/lib/, and tests live in tests/.
License
1 maintainer
Metadata
1 maintainer
Release files for trajectory-sdk 0.9.27
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| trajectory_sdk-0.9.27.tar.gz | 181.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| trajectory_sdk-0.9.27-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 466.9 kB
Release files / trajectory_sdk-0.9.27.tar.gz
| Download URL | trajectory_sdk-0.9.27.tar.gz |
|---|---|
| Size | 181.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1cb3606610040c8e19861153495f0d001b216a3131dc353f83f945a9da083493
|
|
BLAKE2b-256 checksum How to use checksums |
108a790929fc3f22cff77444df0d42c2676b9bbcd251bbbf96c94880d4f9ccef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / trajectory_sdk-0.9.27-py3-none-any.whl
| Download URL | trajectory_sdk-0.9.27-py3-none-any.whl |
|---|---|
| Size | 285.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a77cd1fc005028260e2b3c3c1d07b4c6e47fee40bf75d522afb2c2d63d433a7e
|
|
BLAKE2b-256 checksum How to use checksums |
658c6d5bb52ef2b9608b29dae8d3277ad4df532f67d51b6d40072ab816f8d392
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for trajectory-sdk 0.9.27
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for trajectory_sdk-0.9.27.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
