# Langfuse Lens Agent

[![PyPI version](https://img.shields.io/pypi/v/langfuse-lens-agent.svg)](https://pypi.org/project/langfuse-lens-agent/)
[![Python](https://img.shields.io/pypi/pyversions/langfuse-lens-agent.svg)](https://pypi.org/project/langfuse-lens-agent/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

Korean version: [README_ko.md](./README_ko.md)

Langfuse Lens Agent is an open-source analysis agent for LLM operations teams.  
It turns Langfuse traces into practical outputs for observability, evaluation, and prompt improvement.

---

## ✨ Features

- Trace analytics with filters (`date`, `metadata`, `user_id`, `session_id`, `trace_id`, tags)
- Observability deep-dive (error breakdown, latency/cost trends, root-cause hints)
- Prompt engineering mode (A/B/C rewrites + scoring + recommended variant)
- Evaluation mode (rubric scoring, confidence labels, regression checks)
- Multi-model comparison (`openai`, `anthropic`, `google_genai`, `openrouter`)
- Built-in FastAPI web console (chat + ops query UI)

---

## 📦 Installation

### From PyPI

```bash
pip install langfuse-lens-agent
```

### From source

```bash
git clone https://github.com/BAEM1N/langfuse-lens-agent.git
cd langfuse-lens-agent
pip install -e .
```

---

## ⚙️ Required environment variables

```bash
export LANGFUSE_BASE_URL=https://<your-langfuse-host>
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
```

Optional model provider keys:

```bash
export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GOOGLE_API_KEY=...
export OPENROUTER_API_KEY=...
export OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
```

You can also set keys in:
- project `.env`: `./.env`
- home `.env`: `~/.env`

CLI prints a warning when LLM keys are missing.

---

## 🚀 Usage

### 1) CLI mode

```bash
langfuse-lens --message "mode=overview limit=20"
```

or

```bash
echo "mode=prompt limit=20 user_id=demo-user" | langfuse-lens
```

### 2) Web mode

```bash
langfuse-lens-web --host 0.0.0.0 --port 8010
```

Open: `http://localhost:8010`

In Web UI, use **Settings · LLM API Keys** to save keys into project/home `.env`.

---

## 🧪 Common query modes

- `mode=overview`
- `mode=observability`
- `mode=prompt`
- `mode=evaluation`

---

## 🐳 Docker

```bash
cp .env.example .env
docker compose up -d --build
curl http://localhost:8091/health
```

---

## 🛠️ Development

```bash
python -m unittest discover -s tests -q
```

---

## 📚 Documentation

- Setup: `docs/SETUP.md`
- Feature comparison: `docs/POLLY_COMPARISON.md`

---

## 🤝 Contributing

Issues and pull requests are welcome:
- https://github.com/BAEM1N/langfuse-lens-agent/issues

---

## 📄 License

MIT — see [LICENSE](./LICENSE)
