Metadata-Version: 2.4
Name: llm-path
Version: 0.1.0
Summary: A tool for tracing LLM requests
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: starlette>=0.36.0
Requires-Dist: uvicorn>=0.27.0
Provides-Extra: dev
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# LLM Trace

A lightweight tool for tracing LLM API requests — intercept, record, and visualize your LLM application's behavior.

## Features

- **Transparent Proxy** — Drop-in HTTP proxy that captures all LLM API traffic. Works with any OpenAI-compatible API and Anthropic API.
- **Request Visualization** — Interactive web viewer to visualize the requests topology graph and show the context diff between requests.

## Installation

```bash
# Clone the repository
git clone https://github.com/wang0618/llm-trace.git
cd llm-trace

# Install Python dependencies
uv sync

# Install viewer dependencies
cd viewer && npm install
```

## Quick Start

### 1. Start the Proxy

```bash
uv run llm-trace proxy --port 8080 --target https://api.openai.com --output ./traces/trace.jsonl
```

### 2. Point Your Client to the Proxy

```python
from openai import OpenAI

# Before
client = OpenAI()

# After — just change the base_url
client = OpenAI(base_url="http://localhost:8080/v1")
```

All requests will be transparently forwarded to the original API and recorded to the trace file.

### 3. Visualize the Traces

```bash
# Preprocess traces for the viewer
uv run llm-trace cook ./traces/trace.jsonl -o ./viewer/public/data.json

# Start the viewer
cd viewer && npm run dev
```

Open http://localhost:5173 to explore your traces.

## How It Works

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Client    │ ──── │  LLM Trace  │ ──── │   LLM API   │
│  (your app) │      │   (proxy)   │      │  (OpenAI)   │
└─────────────┘      └──────┬──────┘      └─────────────┘
                            │
                            ▼
                     ┌─────────────┐
                     │ trace.jsonl │
                     └─────────────┘
```

1. Your application sends requests to the local proxy
2. The proxy forwards requests to the target LLM API
3. Responses (including streaming) are passed back to your app
4. Request/response pairs are saved to a JSONL file

### Visualization Model

The viewer displays requests as a **dependency forest**:

- Each node represents one LLM request
- Edges show dependencies — a child request builds upon its parent's messages
- Linear conversations appear as a single chain
- Conversation rewinds or branches create forks
- Unrelated conversations appear as separate trees

## Tech Stack

**Proxy Server**
- Python 3.10+
- Starlette (ASGI framework)
- httpx (async HTTP client)
- uvicorn (ASGI server)

**Viewer**
- React 19
- Vite
- Tailwind CSS v4

## CLI Reference

```bash
# Start proxy server
uv run llm-trace proxy [OPTIONS]
  --port      Port to listen on (default: 8080)
  --output    Output file path (default: ./traces/trace.jsonl)
  --target    Target API URL (default: https://api.openai.com)

# Preprocess traces for visualization
uv run llm-trace cook <input> [OPTIONS]
  -o, --output    Output JSON file (default: ./viewer/public/data.json)
```

## License

MIT
