---
name: langfuse-python-sdk
description: Use Langfuse Python SDK patterns for trace query, experiments, model comparison, and evaluator setup.
---

# Langfuse Python SDK Skill

## When to use
- 사용자가 Langfuse 실험(Experiments) 구성/실행을 요청할 때
- 동일 프롬프트 + 다른 모델 비교를 요청할 때
- evaluator(LLM judge 포함) 설정을 요청할 때
- Python SDK로 trace/score/dataset run 자동화를 요청할 때

## Core intent
Lens는 “관측(Trace) → 평가(Eval) → 개선(Prompt)” 루프를 Python SDK로 재현 가능해야 한다.

## Execution playbook
1. Trace filter를 먼저 고정한다 (기간, user_id, session_id, metadata).
2. 실험 입력셋(dataset items)을 명확히 분리한다.
3. 동일 프롬프트/다른 모델 조건으로 dataset run을 분기한다.
4. evaluator를 함수 단위로 분리한다 (품질, 안전성, 형식 준수 등).
5. 결과를 비교표(성공률/점수/실패 패턴)로 요약한다.

## Guardrails
- 정답을 프롬프트에 직접 주입하지 않는다.
- 실패 원인은 trace/evaluation evidence로 설명한다.
- 실험 메타데이터에 model/prompt_version/evaluator_version을 남긴다.

## Quick pattern (concept)
- `langfuse.run_experiment(...)`
- `evaluators=[...]`, `run_evaluators=[...]`
- 모델별 `metadata={"model": "..."}`
- 결과 URL(dataset_run_url) 또는 trace_id를 리포트에 포함

