Metadata-Version: 2.4
Name: trajectory-sdk
Version: 0.1.1
Summary: Use the Trajectory SDK to instrument your codebase for continual learning
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: langsmith>=0.1.0

# Trajectory SDK

Use the Trajectory SDK to instrument your codebase for continual learning.

## Installation

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

## Quick Start

```python
import trajectory_sdk as tj

# Initialize with LangSmith credentials
tj.init(provider="langsmith", api_key="lsv2_pt_...", project_id="...")

# List available conversations
conversations = tj.list_conversations()

# Import a single conversation
trajectories = tj.import_conversation("cc_0t9n9qfgH4qayTPXAdg")

# Import multiple conversations
result = tj.import_conversations(["cc_...", "cc_..."])
print(f"Imported: {result.imported}, Failed: {result.failed}")

```

## Features

- **Provider-agnostic** — pluggable provider system (LangSmith supported, extensible to others)
- **Structured output** — converts raw traces into typed `Trajectory` objects with steps, messages, tool calls, and metrics
- **Deduplication** — content hashing and idempotency keys prevent duplicate imports
- **Local staging** — optional SQLite + gzip storage for offline processing
- **PII redaction** — pluggable redactor interface for scrubbing sensitive data

## Usage

### Transform raw data without fetching

```python
trajectories = tj.transform(raw_conversation_dict, provider="langsmith")
```

### Custom PII redaction

```python
from trajectory_sdk import BasePiiRedactor, Trajectory

class MyRedactor(BasePiiRedactor):
    def redact(self, trajectory: Trajectory) -> Trajectory:
        # your redaction logic
        ...

    def preview(self, trajectories):
        # preview what would be redacted
        ...

trajectories = tj.import_conversation("cc_...", redactor=MyRedactor())
```

### Implement a custom provider

```python
from trajectory_sdk import BaseProvider

class MyProvider(BaseProvider):
    def fetch_conversation(self, conversation_id):
        ...

    def parse_conversation(self, raw_data):
        ...

    def list_conversations(self, query=None, limit=50):
        ...
```

## Output Schema

Each `Trajectory` contains:

- **`task`** — the initial user request
- **`steps`** — cumulative message sequences up to each decision point
- **`reward`** — aggregated reward value and components
- **`metrics`** — step count, token usage, tool call/failure counts
- **`execution_metrics`** — timing (LLM time, env time, total) and termination reason

Messages within steps have a `role` (system, user, assistant, tool) and may include `tool_calls` or `tool_response` objects.

## Requirements

- Python 3.11+
- `langsmith>=0.1.0`

## License

MIT
