Metadata-Version: 2.4
Name: langfuse-lens-agent
Version: 0.2.0
Summary: Langfuse trace analysis agent with CLI and built-in web console
Author: BAEM1N
License-Expression: MIT
Project-URL: Homepage, https://github.com/BAEM1N/langfuse-lens-agent
Project-URL: Repository, https://github.com/BAEM1N/langfuse-lens-agent
Project-URL: Issues, https://github.com/BAEM1N/langfuse-lens-agent/issues
Keywords: langfuse,llm,observability,agent,fastapi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langchain>=1.0.0
Requires-Dist: langchain-openai>=0.3.0
Requires-Dist: langchain-anthropic>=0.3.0
Requires-Dist: langchain-google-genai>=2.1.0
Requires-Dist: deepagents>=0.3.5
Requires-Dist: langfuse>=2.0.0
Requires-Dist: tavily-python>=0.5.0
Dynamic: license-file

# 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
```

---

## 🚀 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`

---

## 🧪 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)
