Sentinel

Langfuse 기반 LLMOps 에이전트 — Deep Agents 프레임워크로 구축된 LLM 애플리케이션 운영 자동화 도구입니다.

트레이스 분석, 프롬프트 버전 관리, LLM-as-judge 자동 평가, 운영 보고서 생성, 플랫폼 데이터 관리를 하나의 대화형 에이전트로 수행합니다.

주요 기능

아키텍처

sentinel/
├── main.py                      # CLI 엔트리포인트 (대화형 / 단일 질의 / --json / --output)
├── server.py                    # FastAPI 웹 서버 엔트리포인트
├── pyproject.toml
├── sentinel/
│   ├── agent.py                 # create_sentinel_agent()
│   ├── config.py                # 멀티 프로바이더 모델 팩토리, Langfuse 클라이언트
│   ├── prompts.py               # Sentinel 시스템 프롬프트
│   ├── subagents.py             # 서브에이전트 3개
│   ├── report_template.html     # McKinsey 스타일 A4 HTML 템플릿
│   ├── tools/
│   │   ├── traces.py            # list_traces, get_trace_detail, list_sessions
│   │   ├── prompt_mgmt.py       # get/save_langfuse_prompt, suggest_prompt_improvement
│   │   ├── evaluation.py        # evaluate_with_llm, list_scores, create_score
│   │   ├── metrics.py           # query_metrics, generate_report
│   │   └── platform.py          # manage_datasets, manage_annotations, think_tool
│   ├── web/
│   │   ├── app.py               # FastAPI 앱 팩토리 (스케줄러 on/off 가능)
│   │   ├── routes.py            # 웹 페이지 + API + /health + /ready
│   │   ├── scheduler.py         # APScheduler 크론 잡
│   │   └── notify.py            # Slack / Telegram / Email 알림
│   └── templates/
│       ├── base.html            # Jinja2 + Tailwind 베이스
│       ├── index.html           # 대시보드
│       ├── reports.html         # 보고서 목록 + 생성
│       ├── report_view.html     # 보고서 상세 보기 (DOMPurify sanitize)
│       └── scheduler.html       # 스케줄러 상태
├── skills/
│   └── langfuse-ops/SKILL.md    # Langfuse SDK API 레퍼런스 (에이전트용)
└── reports/                     # 보고서 출력 디렉토리

빠른 시작

1. 환경 설정

cp .env.example .env
# .env 파일을 편집하여 API 키를 설정합니다

2. 의존성 설치

# 기본 (OpenAI만)
pip install -e .

# 특정 프로바이더 추가
pip install -e ".[anthropic]"
pip install -e ".[gemini]"
pip install -e ".[ollama]"

# 전체 프로바이더
pip install -e ".[all-providers]"

3. 실행

# CLI 대화형 모드
python main.py

# CLI 단일 질의
python main.py --query "최근 3일간 트레이스를 분석해주세요"

# 웹 서버 (대시보드 + 스케줄러)
python server.py

웹 서버

python server.py로 FastAPI 서버를 실행하면:

• 대시보드 (/) — 보고서 현황 + 즉시 생성 폼
• 보고서 목록 (/reports) — 전체 보고서 조회, 다운로드
• 보고서 상세 (/reports/{filename}) — MD/HTML 보고서 보기 (XSS sanitize 적용)
• 보고서 생성 (POST /api/generate) — 기간/날짜 지정 보고서 생성 + 알림
• 스케줄러 현황 (/scheduler) — 스케줄러 상태 및 잡 목록
• 스케줄러 API (/api/scheduler/status) — 크론 잡 현황 JSON
• 헬스 체크 (/health) — 프로세스 상태
• 준비 상태 (/ready) — Langfuse/스토리지/스케줄러 의존성 체크

자동 보고서 스케줄러

알림 채널

보고서 생성 시 설정된 채널로 자동 전송합니다.

멀티 프로바이더

.env에서 SENTINEL_PROVIDER를 설정하여 LLM 프로바이더를 변경할 수 있습니다.

보고서

generate_report 도구는 Markdown 보고서를 항상 생성하며, HTML은 옵션입니다.

• MD (기본): McKinsey 컨설팅 스타일 구조화된 보고서
• HTML (output_html=True): A4 인쇄 대응 HTML 보고서
• 스케줄러는 SENTINEL_AUTO_HTML=true (기본) 일 때 HTML도 함께 생성합니다
• 파일명에 run ID가 포함되어 동일 기간 재생성 시 충돌하지 않습니다

환경 변수

기술 스택

• Deep Agents — 에이전트 프레임워크
• LangChain — LLM 추상화, 도구 정의
• LangGraph — 상태 관리, 체크포인팅
• Langfuse — LLM 관측성 플랫폼
• FastAPI — 웹 서버
• APScheduler — 크론 스케줄러

라이선스

MIT