# dr-langfuse

Typed Pydantic models, adapter protocols, and concrete implementations for Langfuse prompt fetching and trace emission.

## Install

```bash
pip install dr-langfuse
```

## Quick start

```python
from dr_langfuse import LangfusePromptProvider, PromptFetchRequest

provider = LangfusePromptProvider()  # reads LANGFUSE_* env vars
payload = provider.fetch_prompt(
    PromptFetchRequest(prompt_name="my-prompt", variables={"topic": "recursion"})
)
print(payload.system_content)
print(payload.task_content)
```

```python
from dr_langfuse import LangfuseTraceEmitter, TraceEventRequest

emitter = LangfuseTraceEmitter()
ack = emitter.emit_trace(
    TraceEventRequest(event_name="eval.step", tags=["experiment"], metadata={"run": 1})
)
print(ack.accepted, ack.trace_id)
```

## What's included

| Module | Contents |
|---|---|
| `dr_langfuse.prompts` | `PromptFetchRequest`, `PromptPayload`, `LangfusePromptProvider` |
| `dr_langfuse.tracing` | `TraceEventRequest`, `TraceAck`, `LangfuseTraceEmitter` |
| `dr_langfuse.errors` | `ErrorCode`, `ErrorEnvelope`, `LangfuseError` |
| `dr_langfuse.client` | `LangfuseConfig` |
| `dr_langfuse.protocols` | `PromptProvider`, `TraceEmitter` (runtime-checkable protocols) |

All symbols are re-exported from the top-level package.

## Configuration

Set standard Langfuse environment variables:

```bash
export LANGFUSE_PUBLIC_KEY="pk-..."
export LANGFUSE_SECRET_KEY="sk-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # optional
# LANGFUSE_HOST is still supported as a deprecated fallback.
```

Or pass config explicitly:

```python
from dr_langfuse import LangfuseConfig, LangfusePromptProvider

config = LangfuseConfig(public_key="pk-...", secret_key="sk-...", host="https://cloud.langfuse.com")
provider = LangfusePromptProvider(config=config)
```

## Requirements

- Python 3.12+
- `pydantic` 2.x
- `langfuse` 3.x

## License

MIT
