# Langfuse Lens Agent

[![PyPI](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: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

English: [README.md](./README.md)

**Langfuse Lens Agent**는 Langfuse 트레이스 데이터를 기반으로 **관찰 → 분석 → 실험 → 개선** 사이클을 실행하는 LLM 운영 에이전트입니다.

웹 콘솔에서 자연어로 질문하면 AI 에이전트가 트레이스를 조회·분석하고, 프롬프트 개선안을 제시하며, 다른 모델로 재실행하여 결과를 비교합니다.

---

## 핵심 기능

### AI 에이전트 (LangGraph 기반)

- **트레이스 분석** — 날짜, 사용자, 세션, 태그, 메타데이터 기준 필터링 및 요약
- **옵저버빌리티 진단** — 에러 분류, 레이턴시·비용 추이, 병목 탐지
- **프롬프트 개선** — 기존 프롬프트 A/B/C 리라이트 + 자동 점수화 + 추천안
- **모델 비교 평가** — 동일 입력에 여러 LLM 응답을 나란히 비교
- **트레이스 재실행** — 과거 트레이스를 다른 모델/프롬프트로 재실행
- **A/B 실험** — 데이터셋 기반 변형별 자동 실행 + LLM-as-Judge 채점
- **응답 랭킹** — 여러 모델 응답을 자동 비교하고 순위 매김

### 웹 콘솔 (FastAPI + Jinja2)

| 페이지 | 기능 |
|--------|------|
| **대시보드** | 서버 상태, 채팅 현황, 감사 이벤트, LLM 키 상태 |
| **에이전트 채팅** | 자연어 대화로 트레이스 분석·프롬프트 개선·평가 실행 |
| **프롬프트** | Langfuse 프롬프트 CRUD + 버전 관리 + 라벨 프로모션 |
| **데이터셋** | Langfuse 데이터셋 관리 + 트레이스에서 항목 가져오기 |
| **API 콘솔** | Langfuse OpenAPI 동적 탐색 및 직접 실행 |
| **보고서** | 일간/주간/월간 활동 리포트 자동 생성 + 스케줄링 |
| **실험** | 트레이스 재실행, A/B 테스트, 평가, 응답 비교 관리 |
| **설정** | LLM 키, Langfuse 연결, 다중 프로젝트, 로컬 추론 서버 |
| **관리** | 사용자·API 토큰·감사 로그·시스템 상태·에이전트 도구 |

### 그 외

- **다국어** — 한국어/영어 실시간 전환
- **다크/라이트 테마**
- **RBAC** — `viewer`, `analyst`, `editor`, `owner`, `ops`, `super_admin` 6단계 역할
- **멀티 프로젝트** — 사용자별 여러 Langfuse 프로젝트 연결 (Fernet 암호화 저장)
- **보고서 스케줄러** — asyncio 기반 자동 생성 (일/주/월, KST 기준)
- **JSON/CSV 내보내기** — 실험 결과 다운로드
- **Langfuse OpenAPI 동적 도구** — 에이전트가 Langfuse API를 직접 호출
- **Python 3.11–3.14** — 3.14에서는 자동으로 Langfuse REST 폴백 사용

---

## 지원 LLM

| 프로바이더 | 예시 모델 |
|-----------|----------|
| OpenAI | gpt-4o, gpt-4o-mini, gpt-4.1, o1, o3-mini |
| Anthropic | claude-sonnet-4-20250514, claude-haiku |
| Google | gemini-2.0-flash, gemini-2.5-pro |
| OpenRouter | deepseek/deepseek-chat-v3, meta-llama 등 |
| Ollama (로컬) | llama3, phi3, mistral 등 |
| vLLM / LM Studio | 로컬 추론 서버 |

---

## 빠른 시작

### 1. 설치

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

또는 소스에서:

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

### 2. 설정

```bash
cp .env.example .env
```

최소 설정 (`.env`):

```bash
# LLM 키 (최소 1개)
OPENAI_API_KEY=sk-...

# 부트스트랩 관리자 (첫 실행용)
AGENT_BOOTSTRAP_ADMIN_TOKEN=your-secret-token
```

Langfuse 연결은 **웹 UI > 설정 > Langfuse Projects**에서 사용자별로 설정하는 것을 권장합니다.

### 3. 실행

```bash
langfuse-lens-web
```

브라우저에서 `http://localhost:8010` 접속 후 부트스트랩 토큰으로 로그인합니다.

---

## 설정 상세

### .env 주요 항목

```bash
# Langfuse (전역 폴백, 선택)
LANGFUSE_BASE_URL=https://cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGFUSE_ENVIRONMENT=production

# LLM 프로바이더 키
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# 로컬 추론 (선택)
OLLAMA_BASE_URL=
VLLM_BASE_URL=
LMSTUDIO_BASE_URL=

# 에이전트 설정
AGENT_LLM_TEMPERATURE=0.2
AGENT_LLM_MAX_WORKERS=3
AGENT_LLM_COMPARISON_MODELS=openai:gpt-4o,anthropic:claude-sonnet-4-20250514

# 보안
AGENT_BOOTSTRAP_ADMIN_TOKEN=
AGENT_DATA_ENCRYPTION_KEY=          # Fernet 키 (자격증명 암호화)
AGENT_AUTH_ALLOW_SIGNUP=true
AGENT_LANGFUSE_CONTROL_ALLOW_MUTATION=false

# 보고서 스케줄러 (KST)
REPORT_SCHEDULER_ENABLED=true
REPORT_SCHEDULER_DAILY_HOUR=0
REPORT_SCHEDULER_DAILY_MINUTE=0

# 관리자 토큰 정책
AGENT_TOKEN_DEFAULT_EXPIRES_DAYS=30
AGENT_TOKEN_DEFAULT_ROTATE_BEFORE_DAYS=3
```

### Config.yaml (선택)

`.env`에 없는 키를 `Config.yaml`로 보충할 수 있습니다.

검색 순서: `./Config.yaml` → `./config/Config.yaml` → `AGENT_CONFIG_YAML_PATH`

---

## Docker

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

컨테이너는 비-root 사용자(`appuser`)로 실행되며 내장 헬스체크가 포함되어 있습니다.

---

## 프로젝트 구조

```
langfuse-lens-agent/
├── api/                        # FastAPI 라우터 및 미들웨어
│   ├── routers/                # auth, admin, langfuse, experiments, reports, settings, pages
│   ├── deps.py                 # 인증·인가 의존성 헬퍼
│   ├── models.py               # Pydantic 요청/응답 모델
│   └── state.py                # RBAC 역할·권한 정의
├── src/                        # 핵심 에이전트 로직
│   ├── agent_core.py           # LangGraph 에이전트 빌더
│   ├── report_generator.py     # 일간/주간/월간 보고서 생성
│   ├── report_scheduler.py     # 비동기 보고서 자동 스케줄러
│   ├── user_store.py           # SQLite 저장소 (사용자, 채팅, 보고서, 실험)
│   ├── tools/                  # 에이전트 도구
│   │   ├── analysis.py         # 트레이스 분석·모델 비교
│   │   ├── experiment_tools.py # 재실행·A/B·평가·랭킹
│   │   ├── langfuse_fetch.py   # Langfuse 데이터 조회
│   │   └── openapi_registry.py # OpenAPI 동적 도구 생성
│   └── web_entry.py            # CLI 엔트리포인트
├── templates/                  # Jinja2 HTML 템플릿 (11개 페이지)
├── static/                     # CSS, JS, 다국어 리소스 (en/ko)
├── config/                     # Config.yaml, 도구 프리셋, 런타임 프로필
├── skills/                     # 에이전트 스킬 참조
├── tests/                      # 88개 단위 테스트 (9개 파일)
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml
```

---

## 보안

| 기능 | 설명 |
|------|------|
| **인증** | Bearer 토큰 (세션 기반) + 부트스트랩 관리자 토큰 |
| **RBAC** | 6단계 계층 역할 + 스코프 기반 권한 |
| **암호화** | Fernet 암호화로 사용자 Langfuse 자격증명 안전 저장 |
| **토큰 관리** | 만료, 자동 로테이션, 폐기 정책 (관리자 API) |
| **감사 로깅** | 모든 관리자 및 쓰기 작업 SQLite 기록 |
| **타이밍 안전 비교** | `secrets.compare_digest`로 토큰 검증 |
| **입력 검증** | Pydantic max_length, 날짜 파싱, 필드 밸리데이터 |
| **Docker** | 비-root 사용자, 헬스체크, .dockerignore로 시크릿 보호 |

---

## API 개요

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/auth/login` | 로그인 |
| POST | `/api/auth/register` | 회원가입 |
| GET | `/api/auth/me` | 현재 사용자 정보 |
| POST | `/api/chat` | 에이전트 채팅 메시지 |
| GET | `/api/chat/threads` | 채팅 스레드 목록 |
| GET | `/api/reports` | 보고서 목록 |
| POST | `/api/reports/generate` | 보고서 생성 (일간/주간/월간) |
| GET | `/api/experiments` | 실험 목록 |
| POST | `/api/experiments` | 실험 생성 |
| GET | `/api/experiments/{id}/export` | JSON/CSV 내보내기 |
| GET | `/api/langfuse/prompts` | 프롬프트 목록 |
| GET | `/api/langfuse/datasets` | 데이터셋 목록 |
| POST | `/api/langfuse/openapi/execute` | Langfuse API 작업 실행 |
| GET | `/api/langfuse/tools/catalog` | 에이전트 도구 카탈로그 |
| GET | `/api/admin/users` | 사용자 관리 |
| GET | `/api/admin/tokens` | API 토큰 관리 |
| GET | `/api/admin/audit-logs` | 감사 로그 |
| GET | `/api/admin/system/health` | 시스템 상태 |

전체 API는 웹 콘솔의 **API 콘솔** 페이지에서 탐색·실행할 수 있습니다.

---

## 개발

```bash
# 의존성 설치
pip install -e ".[dev]"

# 테스트 실행
python -m pytest tests/ -v

# 개발 서버 (핫 리로드)
langfuse-lens-web --reload
```

---

## 라이선스

MIT — [LICENSE](./LICENSE)

---

## 기여

이슈와 PR을 환영합니다: [GitHub Issues](https://github.com/BAEM1N/langfuse-lens-agent/issues)
