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
Install the optional agent integration used by the full CLI with:
pip install "trajectory-sdk[cli]"
Quick start
Set TRAJECTORY_API_KEY, then create a client:
from trajectory import Client
client = Client()
benchmarks = client.benchmarks.list(limit=10)
Managed benchmark runtimes inject TRAJECTORY_TOKEN, TRAJECTORY_BASE_URL,
MODEL_ENDPOINT_ID, and TRAJECTORY_TID. The same client uses them for inference, rewards, and
completion:
from trajectory import Client
client = Client()
response = client.chat.completions.create(model="policy", messages=messages)
client.trajectories.log_reward(reward_id="primary", name="correct", value=reward)
client.trajectories.complete(termination_reason="ENV_DONE")
Explicit authentication, URLs, model endpoint headers, and trajectory IDs continue to override the runtime environment.
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. Higher-level operations that
coordinate multiple API calls are available from trajectory.lib:
from trajectory import Client
from trajectory.lib import ingest_events
client = Client()
result = ingest_events(
client,
[
{
"event_type": "agent.completed",
"session_id": "session-123",
"timestamp": "2026-08-28T00:00:00+00:00",
"properties": {"model": "example-model"},
}
],
)
print(result.ingested, result.skipped)
LiteLLM harnesses
Starting with SDK 0.6.6, an existing LiteLLM harness can use this import for policy calls:
from trajectory.lib.litellm import completion
response = completion(model=model, messages=messages, temperature=1.0)
This always uses the injected Trajectory endpoint and credentials. Messages and tools are unchanged.
Keep user/judge calls on native LiteLLM and retain the original loop and grader, then report their
result with the existing
client.trajectories.log_reward(...) and client.trajectories.complete(...) methods.
Command line
The package installs a handwritten trajectory command that delegates API operations to the same
generated client and high-level workflows:
export TRAJECTORY_API_KEY="tj_key_..."
trajectory trajectories upload trajectories.json --dataset my-dataset
trajectory telemetry ingest events.json
trajectory traces upload trajectories.json --events events.json --dataset my-dataset
trajectory secrets set OPENAI_API_KEY
trajectory secrets list
API-backed commands use a 30-minute timeout by default. Override it with --timeout SECONDS.
The existing repository and benchmark tools remain available from the new CLI package:
trajectory bench validate ./benchmark
trajectory bench push ./benchmark --build-images
trajectory extract harness
Benchmark pushes use your organization's only Agent, or create Default Agent if none exists.
With multiple Agents, add --agent-id agt_example to select the owner.
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/, the handwritten CLI lives in cmd/trajectory/cli/trajectory_cli/, and tests live in
tests/.
License
1 maintainer
Release files for trajectory-sdk 0.6.16
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.6.16.tar.gz | 119.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| trajectory_sdk-0.6.16-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 316.6 kB
Release files / trajectory_sdk-0.6.16.tar.gz
| Download URL | trajectory_sdk-0.6.16.tar.gz |
|---|---|
| Size | 119.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a94b5c686be88b8a59376389c0546436e3a09d0a7afad99cfca94b01174a9c08
|
|
BLAKE2b-256 checksum How to use checksums |
f40e80ce4f2e1d93ad9fbbc8e4ac6ae8a4c28370cf02d7b84751185dbc07f8e4
|
| 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 Sep 22, 2026.
Transparency logRelease files / trajectory_sdk-0.6.16-py3-none-any.whl
| Download URL | trajectory_sdk-0.6.16-py3-none-any.whl |
|---|---|
| Size | 196.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f9756c40bd0144e748df949138b11fa84140eb9f6d760d91a70b284823a230d9
|
|
BLAKE2b-256 checksum How to use checksums |
a767a3eab6f00c0da1be96fdf18b74b27b8da9276c16ed8fb340c4a7295e3dbb
|
| 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 Sep 22, 2026.
Transparency log
