Metadata-Version: 2.4
Name: trajectory-sdk
Version: 0.6.17
Summary: Generated Trajectory API client and high-level workflows
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic>=2.0
Provides-Extra: cli
Requires-Dist: claude-agent-sdk>=0.1.0; extra == "cli"
Dynamic: license-file

# Trajectory SDK

Generated Python client for the Trajectory API, with high-level workflows for uploading
trajectories, telemetry, and runtime-backed benchmarks.

## Install

```bash
pip install trajectory-sdk
```

Install the optional agent integration used by the full CLI with:

```bash
pip install "trajectory-sdk[cli]"
```

## Quick start

Set `TRAJECTORY_API_KEY`, then create a client:

```python
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:

```python
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`:

```python
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:

```python
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:

```bash
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:

```bash
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

```bash
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

[Apache 2.0](LICENSE)
