Langfuse — CLAUDE.md

# Langfuse — CLAUDE.md

## Overview

Langfuse is an open-source LLM engineering platform. Features:
- **Tracing**: Full observability of LLM calls, chains, agents.
- **Prompt Management**: Version-controlled prompts with A/B testing.
- **Evaluations**: Human annotation + LLM-as-judge + automated evals.
- **Datasets**: Curate and run experiments on test sets.

## Repository Structure

```
web/              # Next.js frontend + API
  src/
    pages/        # Next.js pages
    server/       # tRPC routers
    features/     # Feature modules
worker/           # Background job processor
packages/         # Shared utilities
```

## Development

```bash
# Start with Docker Compose
docker compose up -d postgres redis

npm install
npm run db:migrate
npm run dev
```

## SDK Usage (Python)

```python
from langfuse import Langfuse

langfuse = Langfuse()

# Trace an LLM call
with langfuse.trace(name="chat-completion") as trace:
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    trace.generation(
        name="openai-call",
        model="gpt-4o",
        input=prompt,
        output=response.choices[0].message.content,
        usage=response.usage,
    )
```

## SDK Usage (TypeScript)

```typescript
import { Langfuse } from 'langfuse';

const langfuse = new Langfuse();

const trace = langfuse.trace({ name: 'my-feature' });
const span = trace.span({ name: 'retrieval' });
// ... do work
span.end();
await langfuse.flushAsync();
```

## Prompt Management

```python
# Get versioned prompt
prompt = langfuse.get_prompt("my-prompt", version=3)
formatted = prompt.compile(variable="value")

# Prompt links traces to versions automatically
```

## Database

- PostgreSQL with Prisma ORM.
- ClickHouse for analytics queries (optional).
- Migrations in `packages/db/prisma/migrations/`.