langfuse-lens-agent 0.2.5

Langfuse trace analysis agent with CLI and built-in web console

Langfuse Lens Agent

Korean version: 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)
• Agent orchestration powered by create_deep_agent (Deep Agents)
• Built-in FastAPI web console (chat + ops query UI)
• Deep Agents patterns applied:
  • skills=["/skills/"]
  • memory=["/AGENTS.md", "/memories/AGENTS.md"]
  • mode-specialized subagent delegation (overview / observability / prompt / evaluation / model-compare)
  • composite backend routing (/memories/ long-term path)
• Filesystem interaction enabled via Deep Agent backend (ls/read_file/write_file/edit_file/glob/grep, optional execute)
• Prompt sync with Langfuse Prompt Management:
  • if missing in Langfuse → auto-create from default
  • if exists → fetch latest label/version prompt and run
  • applies to orchestrator + subagent prompts

---

📦 Installation

From PyPI

pip install langfuse-lens-agent

From source

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

---

⚙️ Required environment variables

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

Optional model provider keys:

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

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

or

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

2) Web mode

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

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

---

🛠️ Development

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