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
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 HTTP 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.
The generated resource methods map directly to the public HTTP API. Benchmark submission
and file-upload workflows are available from trajectory.lib. Detailed authored guides are
not currently available without documentation access; the core workflow is included here.
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,
reward_id="answer",
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, register it and build its runtime:
from pathlib import Path
from trajectory import Client
from trajectory.lib import push, wait_for_benchmark_images
client = Client()
result = push(client, benchmark, agent_name="support-agent", root=Path("benchmark"))
images = wait_for_benchmark_images(client, result.bench_id)
Uploads accept agent_id="agt_existing", agent_name="support-agent", or both
(which must match). The agent must already exist. 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.
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.
wait_for_benchmark_images() first calls client.benchmarks.images.build(bench_id) and then
polls for completion. client.benchmarks.images.list(bench_id) only reads status. Once the
runtime is ready, use the benchmark ID to start evaluation or training; uploading does not
execute the tasks. 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.8.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| trajectory_sdk-0.8.10.tar.gz | 86.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| trajectory_sdk-0.8.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 251.4 kB
Release files / trajectory_sdk-0.8.10.tar.gz
| Download URL | trajectory_sdk-0.8.10.tar.gz |
|---|---|
| Size | 86.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f43ff985c5028761da6e1df0262ff2e666da913a549b53c4243aa572bc7917fd
|
|
BLAKE2b-256 checksum How to use checksums |
83130290f5016cfe56aa8508cf5d8c0118bbde26500b1c5052db84e8271dab9e
|
| Upload date | |
|
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.
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 1, 2026.
Transparency logRelease files / trajectory_sdk-0.8.10-py3-none-any.whl
| Download URL | trajectory_sdk-0.8.10-py3-none-any.whl |
|---|---|
| Size | 164.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4e222505ba8cf1dff9882db9827ae6cf313ca58d51d8b5b6cd47d4ce30a46650
|
|
BLAKE2b-256 checksum How to use checksums |
acca64ed659d86d87d409e15f414aa0dd083fd8348f43ce0fbc705fd8f72c75b
|
| Upload date | |
|
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.
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 1, 2026.
Transparency log
