.
This commit is contained in:
1 parent
1453433b62
commit
da76af3826
65 files changed
+11089
-143
No files matched your search
@@ -0,0 +1,855 @@
|
||||
# lolympus-agent Evaluation Stage 2 — Implementation Plan
|
||||
|
||||
> **Audience**: Codex(또는 다른 AI 에이전트)가 self-contained하게 작업할 수 있도록 작성됨. 기존 `/Users/dahyeon/source/lolympus-agent/plan.md`의 Phase 0–5(Phase 5에서 shadow eval / judge / alert 인프라가 이미 완성됨)를 전제로 하며, 그 위에 **evaluation 깊이와 활용 폭**을 강화한다.
|
||||
>
|
||||
> **충돌 시 우선순위**: 본 문서 > `plan.md`. 단 Phase 0–5의 인터페이스/스키마/env 컨벤션은 그대로 따른다.
|
||||
>
|
||||
> **운영 runbook**: 구현 후 서비스 운영 흐름과 evaluation CLI/Redis/Mongo/장애 대응은 `docs/service-evaluation-operations.md`를 기준으로 확인한다.
|
||||
|
||||
---
|
||||
|
||||
## 1. Context (왜 이 작업)
|
||||
|
||||
### 문제
|
||||
Phase 5 직후 evaluation 인프라는 굴러가지만 **데이터가 한쪽으로만 흐르고, 깊이가 얕고, 사람 검증이 없다**:
|
||||
|
||||
1. **얕은 평가 (outcome-only)** — 현재 judge는 최종 응답 텍스트 한 점만 평가. classifier 오분류, derive 잘못된 tier 결정, planner의 approach 선택 오류, tool args 오류 등 **회귀 원인이 어느 단계인지 핀포인트 불가**.
|
||||
2. **데이터 활용 부재** — `lolympus-agent:eval:results` Stream이 MAXLEN=10000으로 쌓이고 잘려 나갈 뿐, alert trigger 외에 **분석/리포팅/재학습 루프 0건**. 어느 intent/tier가 약한지 가시화 안 됨. Drift detection 없음.
|
||||
3. **휘발성** — Redis Stream MAXLEN 정책으로 7일 이전 데이터는 사실상 사라짐. 장기 추세 분석 불가.
|
||||
4. **사람 검증 부재** — LLM judge가 곧 진실. judge 자체가 잘못 평가해도 잡을 길 없음. golden set이 정적이라 온라인 분포 변화에 따라가지 못함.
|
||||
5. **개선 루프 부재** — eval이 약점을 보여줘도 prompt/tool/process 개선까지 사람이 매번 손으로 잇는다.
|
||||
|
||||
### 의도한 결과
|
||||
- 회귀 발생 시 "어느 단계가 깨졌는지" 5분 내 식별
|
||||
- shadow eval 30일치 영속 보관 + 슬라이스별 점수 가시화
|
||||
- 약한 슬라이스의 케이스가 자동으로 사람 검토 큐에 들어가고, 라벨된 케이스가 golden set 후보로 자동 적립
|
||||
- 약점 슬라이스에 대해 prompt/tool 개선 후보가 LLM에 의해 제안되고, A/B 토너먼트로 검증된 뒤 PR로 머지
|
||||
|
||||
### 비목표
|
||||
- Front-end 대시보드 구축 — 분석은 CLI 명령으로 충분 (필요 시 별도 후속 plan)
|
||||
- 실시간(stream) ML 학습 — judge/golden은 batch 갱신
|
||||
- 다중 skill 일반화 — onboarding 단일 skill 전제 (`plan.md` §13의 결정 유지)
|
||||
|
||||
---
|
||||
|
||||
## 2. Relationship to `plan.md` (기존 인프라)
|
||||
|
||||
### 그대로 사용 (변경 없음)
|
||||
- `src/eval/{capture,anonymize,runner,cli,types,shadow-bus,shadow-worker}.ts`
|
||||
- `src/eval/judges/{rule-judge,llm-judge}.ts`
|
||||
- `src/eval/golden/onboarding.jsonl`
|
||||
- Redis: `lolympus-agent:eval:results`, `lolympus-agent:eval:baseline`, `lolympus-agent:background[:dlq]`
|
||||
- NATS: `lolympus-agent.alert`, `lolympus-agent.eval.report`
|
||||
- env: `SHADOW_EVAL_SAMPLING_RATE_TIER{0,1,2}`, `ALERT_THRESHOLD_*`, `LLM_JUDGE_*`, `EVAL_STREAM_MAXLEN`, `EVAL_RESULTS_TTL_SEC`
|
||||
- 익명화 salt 하드코딩 (`EVAL_ANON_SALT="lolympus-agent-v1"`)
|
||||
|
||||
### 확장 / 변경
|
||||
- `shadow-bus.ts`: `ShadowEvalEnvelope`에 `process` 필드 추가 (Phase 7)
|
||||
- `shadow-worker.ts`: aggregator tick / persistence / drift / review-routing tick 추가 (Phase 6, 8)
|
||||
- `runner.ts`: per-case 결과에 `processJudge` 필드 추가 (Phase 7)
|
||||
- `judges/llm-judge.ts`: 변경 없음. 신규 `judges/process-judge.ts` 추가 (Phase 7)
|
||||
- `cli.ts`: `eval:review`, `eval:promote`, `eval:report`, `eval:tournament` 명령 추가
|
||||
|
||||
### 신규 의존
|
||||
- 없음. 모든 신규 기능은 이미 의존 중인 라이브러리(Redis/Garnet, MongoDB driver, Zod, `LlmClient`)로 구현 가능.
|
||||
|
||||
---
|
||||
|
||||
## 3. Target Architecture (강화 후)
|
||||
|
||||
```
|
||||
[agent runtime]
|
||||
│
|
||||
┌────────────┴───────────┐
|
||||
▼ ▼
|
||||
ShadowEvalEnvelope OTel span tree
|
||||
(+ process snapshot) (per-step trace)
|
||||
│
|
||||
▼
|
||||
lolympus-agent:background ── stream ──┐
|
||||
│
|
||||
┌───────────────┘
|
||||
▼
|
||||
ShadowWorker
|
||||
┌──────────────────────┼──────────────────────┐
|
||||
│ │ │
|
||||
[LLM judge] [Process judge] [Aggregator tick / 5m]
|
||||
(outcome 4축) (per-step rubric) slice = tier × intent × phase
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
eval:results Stream ──┬─→ MongoDB eval_archive (24h tick: 영속)
|
||||
│
|
||||
├─→ Drift detector (24h vs 7d 평균)
|
||||
│ └→ NATS lolympus-agent.alert
|
||||
│
|
||||
└─→ Review router
|
||||
└→ eval:review:queue Stream
|
||||
│
|
||||
[npm run eval:review CLI]
|
||||
│
|
||||
┌───────┴────────┐
|
||||
▼ ▼
|
||||
eval:review:labeled Calibration metric
|
||||
Stream (사람 vs LLM 상관)
|
||||
│
|
||||
▼
|
||||
Auto-promotion (nightly)
|
||||
└→ src/eval/golden/onboarding.candidate.jsonl
|
||||
│
|
||||
(사람이 batch curation → golden.jsonl PR)
|
||||
|
||||
|
||||
[Closed loop: 별도 CLI orchestration]
|
||||
eval:report → 약점 슬라이스 식별 (top-k)
|
||||
│
|
||||
▼
|
||||
eval:propose → LLM이 prompt diff / tool 후보 생성
|
||||
│
|
||||
▼
|
||||
eval:tournament → shadow에서 두 prompt 버전 동시 실행, side-by-side LLM judge
|
||||
ELO 랭킹 → 승자가 PR draft 생성
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Phase Plan
|
||||
|
||||
각 Phase는 **독립 PR**. 의존: 6 → 7, 6 → 8 (병렬 가능), 7+8 → 9. 개발 순서 권장: **Phase 6 → 7 → 8 → 9**.
|
||||
|
||||
| Phase | 제목 | 추정 |
|
||||
|---|---|---|
|
||||
| 6 | Shadow data 활용 (Aggregator / Persistence / Drift / Auto-promotion) | 5–7일 |
|
||||
| 7 | Process-based evaluation (단계별 trace judge) | 4–5일 |
|
||||
| 8 | Hybrid HITL (Review CLI + Calibration) | 3–4일 |
|
||||
| 9 | Closed loop (prompt/tool propose + A/B tournament) | 5–7일 |
|
||||
|
||||
총 17–23일 (단일 개발자).
|
||||
|
||||
---
|
||||
|
||||
## 5. Phase 6 — Shadow Data 활용
|
||||
|
||||
### 5.1 Critical Files
|
||||
- **신규**:
|
||||
- `src/eval/aggregator.ts` — slice별 5분 tick aggregator
|
||||
- `src/eval/archive.ts` — Redis Stream → MongoDB 영속화
|
||||
- `src/eval/drift.ts` — 24h vs 7d 평균 회귀 감지
|
||||
- `src/eval/promote.ts` — 약점 케이스를 candidate jsonl에 적재
|
||||
- `src/eval/golden/onboarding.candidate.jsonl` — 자동 후보 (gitignore 안 함, 사람이 검토 후 golden으로 promote)
|
||||
- `src/eval/aggregator.test.ts`, `src/eval/archive.test.ts`, `src/eval/drift.test.ts`, `src/eval/promote.test.ts`
|
||||
- **변경**:
|
||||
- `src/eval/shadow-worker.ts` — `runLoop()`에 5분 tick(aggregator), 1시간 tick(archive), 24시간 tick(promote+drift) 추가
|
||||
- `src/eval/cli.ts` — `eval:report`, `eval:promote` 명령 추가
|
||||
- `src/common/env-loader.ts` — 신규 env 등록 (§5.6)
|
||||
- `src/common/known-secret-keys.ts` — `MONGODB_CONNECTION_STRING`은 이미 등록됨, 변경 없음
|
||||
|
||||
### 5.2 Aggregator (`src/eval/aggregator.ts`)
|
||||
|
||||
```typescript
|
||||
export interface SliceKey {
|
||||
tier: 0 | 1 | 2;
|
||||
intent: string;
|
||||
phase: string;
|
||||
}
|
||||
|
||||
export interface SliceMetrics {
|
||||
count: number;
|
||||
llmOverallSum: number;
|
||||
llmOverallCount: number;
|
||||
validatorRejectCount: number;
|
||||
validatorSoftWarnCount: number;
|
||||
latencySumMs: number;
|
||||
latencySamples: number[]; // 윈도우 내 최대 200개 샘플로 cap (P95 계산용)
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
export function sliceKeyToString(key: SliceKey): string {
|
||||
return `${key.tier}:${key.intent}:${key.phase}`;
|
||||
}
|
||||
|
||||
export async function aggregateRecentEvalResults(
|
||||
garnetClient: GarnetClient,
|
||||
options: { sinceId: string; nowMs: number }
|
||||
): Promise<{ lastSeenId: string; updatedSlices: number }>;
|
||||
```
|
||||
|
||||
- shadow-worker가 5분마다 호출. `XRANGE lolympus-agent:eval:results sinceId +` 로 미aggregated entry 조회
|
||||
- 각 entry를 SliceKey로 분류 → `lolympus-agent:eval:agg:{sliceKeyString}` Hash에 누적 (HINCRBY/HSET)
|
||||
- TTL: `EVAL_AGG_TTL_SEC` (기본 7일). 7일 지난 슬라이스는 expire 후 archive(§5.3)에서 복원 가능
|
||||
- "최근 sinceId"는 `lolympus-agent:eval:agg:cursor` String에 보관 (worker 재기동 시 복원)
|
||||
- `eval:report` CLI가 `SCAN 0 MATCH lolympus-agent:eval:agg:* COUNT 200`으로 전 슬라이스 읽어 표 출력
|
||||
|
||||
### 5.3 Persistence (`src/eval/archive.ts`)
|
||||
|
||||
```typescript
|
||||
export interface EvalArchiveEntry {
|
||||
streamId: string;
|
||||
evaluatedAt: string; // UTC ISO
|
||||
// 이하 stream entry 그대로
|
||||
request: AgentRequest;
|
||||
response: AgentResponse;
|
||||
derived: DerivedState;
|
||||
classified: ClassifiedIntent;
|
||||
validation: ValidationResult;
|
||||
llmJudge: LlmJudgeResult;
|
||||
processJudge?: ProcessJudgeResult; // Phase 7에서 추가
|
||||
latencyMs: number | null;
|
||||
tier: 0 | 1 | 2;
|
||||
}
|
||||
|
||||
export async function archiveEvalResults(
|
||||
garnetClient: GarnetClient,
|
||||
mongoClient: MongoClient,
|
||||
options: { sinceId: string; nowMs: number; batchSize?: number }
|
||||
): Promise<{ lastArchivedId: string; archivedCount: number }>;
|
||||
```
|
||||
|
||||
- 1시간마다 호출. `XRANGE lolympus-agent:eval:results sinceId +` → MongoDB `eval_archive` 컬렉션 bulk insert (`{ ordered: false }`)
|
||||
- `streamId` unique index. 중복 insert는 silently skip
|
||||
- TTL index: `evaluatedAt` 기준 `EVAL_ARCHIVE_TTL_DAYS` (기본 30일) 후 자동 삭제
|
||||
- "마지막 archive id"는 `lolympus-agent:eval:archive:cursor` String에 보관
|
||||
- Mongo write 실패 시: warn 로그 + cursor 미업데이트 → 다음 tick 재시도. 3회 연속 실패 시 alert(`kind="archive-stalled"`)
|
||||
|
||||
### 5.4 Drift detection (`src/eval/drift.ts`)
|
||||
|
||||
```typescript
|
||||
export interface DriftReport {
|
||||
slice: SliceKey;
|
||||
recent24hAverage: number;
|
||||
recent7dAverage: number;
|
||||
dropPct: number;
|
||||
significant: boolean; // 통계적 유의성 (count ≥ 30 && drop ≥ ALERT_THRESHOLD_DRIFT_PCT)
|
||||
}
|
||||
|
||||
export async function computeDriftReports(
|
||||
mongoClient: MongoClient,
|
||||
options?: { metricKey?: "llmOverall" | "validatorPassRate" }
|
||||
): Promise<DriftReport[]>;
|
||||
```
|
||||
|
||||
- 24시간마다 호출. MongoDB `eval_archive`에서 24h 평균 vs 7d 평균을 slice별 aggregation
|
||||
- `dropPct ≥ ALERT_THRESHOLD_DRIFT_PCT` (기본 15%) && 24h 표본 수 ≥ 30 → `lolympus-agent.alert` publish (`kind="eval-drift"`, severity는 dropPct에 따라 warn/critical)
|
||||
- baseline alert와 별개 — baseline은 골든셋 회귀, drift는 운영 분포 회귀
|
||||
|
||||
### 5.5 Auto-promotion (`src/eval/promote.ts`)
|
||||
|
||||
```typescript
|
||||
export interface PromotionCandidate {
|
||||
caseId: string; // anonymize된 streamId
|
||||
request: AgentRequest;
|
||||
response: AgentResponse;
|
||||
derived: DerivedState;
|
||||
llmJudge: LlmJudgeResult;
|
||||
reason: "low-score" | "rule-llm-disagree" | "rare-slice";
|
||||
}
|
||||
|
||||
export async function selectPromotionCandidates(
|
||||
mongoClient: MongoClient,
|
||||
options?: { limit?: number; minLowScore?: number }
|
||||
): Promise<PromotionCandidate[]>;
|
||||
|
||||
export async function appendCandidatesToJsonl(
|
||||
candidates: PromotionCandidate[],
|
||||
outputPath?: string
|
||||
): Promise<{ appendedCount: number; outputPath: string }>;
|
||||
```
|
||||
|
||||
- 24시간마다 호출. MongoDB에서 지난 24h 결과를 다음 기준으로 선정 (각 카테고리당 최대 10건):
|
||||
1. **low-score**: `llmJudge.scores.overall ≤ EVAL_PROMOTE_LOW_SCORE` (기본 2)
|
||||
2. **rule-llm-disagree**: `validation.status === "pass"` && `llmJudge.scores.overall ≤ 3` (또는 반대)
|
||||
3. **rare-slice**: SliceKey 카운트가 `EVAL_PROMOTE_RARE_THRESHOLD` (기본 5)건 이하인 슬라이스에서 1건
|
||||
- 모든 후보는 `anonymize.ts`의 함수로 다시 익명화 (이미 익명화돼 있어도 재적용 — defense in depth)
|
||||
- 결과를 `src/eval/golden/onboarding.candidate.jsonl`에 append (line-by-line, `EvalCaseDefinition` 포맷, `expected` 필드는 비워두고 `notes`에 promotion reason 기재)
|
||||
- 사람이 batch로 curation해 `onboarding.jsonl`로 옮기고 candidate에서 삭제 (수동)
|
||||
|
||||
### 5.6 신규 env
|
||||
|
||||
| Key | 기본값 | 설명 |
|
||||
|---|---|---|
|
||||
| `EVAL_AGG_TICK_MS` | 300000 | aggregator tick 주기 (5분) |
|
||||
| `EVAL_AGG_TTL_SEC` | 604800 | slice Hash TTL (7일) |
|
||||
| `EVAL_AGG_LATENCY_SAMPLE_CAP` | 200 | slice당 P95 계산용 샘플 cap |
|
||||
| `EVAL_ARCHIVE_TICK_MS` | 3600000 | archive tick 주기 (1시간) |
|
||||
| `EVAL_ARCHIVE_TTL_DAYS` | 30 | MongoDB TTL index |
|
||||
| `EVAL_ARCHIVE_BATCH_SIZE` | 500 | 한 tick당 archive batch size |
|
||||
| `EVAL_DRIFT_TICK_MS` | 86400000 | drift detection tick (24시간) |
|
||||
| `ALERT_THRESHOLD_DRIFT_PCT` | 15 | 24h vs 7d 평균 drop 임계 (%) |
|
||||
| `EVAL_PROMOTE_TICK_MS` | 86400000 | promotion tick (24시간) |
|
||||
| `EVAL_PROMOTE_LOW_SCORE` | 2 | low-score 카테고리 임계 |
|
||||
| `EVAL_PROMOTE_RARE_THRESHOLD` | 5 | rare-slice 임계 카운트 |
|
||||
| `EVAL_PROMOTE_PER_CATEGORY_LIMIT` | 10 | 카테고리당 최대 선정 수 |
|
||||
|
||||
### 5.7 신규 Redis key
|
||||
|
||||
| Key Pattern | Type | TTL | 설명 |
|
||||
|---|---|---|---|
|
||||
| `lolympus-agent:eval:agg:{tier}:{intent}:{phase}` | Hash | `EVAL_AGG_TTL_SEC` | slice별 누적 메트릭 |
|
||||
| `lolympus-agent:eval:agg:cursor` | String | no TTL | 마지막 aggregated stream id |
|
||||
| `lolympus-agent:eval:archive:cursor` | String | no TTL | 마지막 archive stream id |
|
||||
| `lolympus-agent:alert:dedupe:eval-drift:{sliceKey}` | String | `ALERT_RATE_LIMIT_SEC` | drift alert dedupe |
|
||||
|
||||
### 5.8 신규 NATS subject
|
||||
- 없음. drift alert는 기존 `lolympus-agent.alert` 재사용 (`kind="eval-drift"`, `kind="archive-stalled"` 추가)
|
||||
|
||||
### 5.9 CLI 추가 (`src/eval/cli.ts`)
|
||||
- `eval:report` — slice 표 출력
|
||||
- `--top=20` (기본): 카운트 상위 20 slice를 점수 desc/asc로 정렬해 표시
|
||||
- `--worst=10`: 점수 하위 10 slice
|
||||
- `--since=24h|7d|30d`: 시간 범위 (Mongo aggregate)
|
||||
- 출력: tier · intent · phase · count · llmOverallAvg · validatorRejectRate · p50LatencyMs · p95LatencyMs
|
||||
- `eval:promote` — promotion candidate를 즉시 생성 (CI/cron 외 수동 실행용)
|
||||
- `--dry-run`: 후보 표시만, 파일 변경 없음
|
||||
- 두 명령 모두 `MongoClient` connection 필요 (env: `MONGODB_CONNECTION_STRING`)
|
||||
|
||||
### 5.10 검증
|
||||
|
||||
1. **단위 테스트**:
|
||||
- `aggregator.test.ts`: 가짜 stream entry 10건 → slice Hash 누적 정확성
|
||||
- `archive.test.ts`: cursor 진행, 중복 streamId skip
|
||||
- `drift.test.ts`: 24h vs 7d 평균 계산, dropPct 임계
|
||||
- `promote.test.ts`: 3개 카테고리 선정 로직, anonymize 재적용 확인
|
||||
2. **통합**:
|
||||
- shadow-worker 부팅 후 5분 + 가짜 stream entry 50건 → `lolympus-agent:eval:agg:*` Hash ≥ 1
|
||||
- 1시간 후 MongoDB `eval_archive` 컬렉션에 documents ≥ 1
|
||||
- 24시간 후 `onboarding.candidate.jsonl`에 line ≥ 1 (테스트 시 tick interval env override)
|
||||
3. **eval:report**:
|
||||
- dev 환경에서 실행 시 표 출력 + `MONGODB_CONNECTION_STRING` 미설정이면 명확한 에러 메시지
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase 7 — Process-based Evaluation
|
||||
|
||||
### 6.1 Critical Files
|
||||
- **신규**:
|
||||
- `src/eval/judges/process-judge.ts` — 단계별 rubric (rule + 선택적 LLM judge)
|
||||
- `src/skills/onboarding/runtime/trace.ts` — `ProcessTrace` 수집/직렬화
|
||||
- `src/eval/judges/process-judge.test.ts`
|
||||
- **변경**:
|
||||
- `src/eval/types.ts` — `ProcessJudgeResult`, `ProcessTraceSnapshot` 추가, `EvalCaseResult.processJudge` 필드, `EvalCaseExpected.processExpected` 필드
|
||||
- `src/eval/shadow-bus.ts` — `ShadowEvalEnvelope.process: ProcessTraceSnapshot` 필드 추가
|
||||
- `src/eval/shadow-worker.ts` — `processShadowEval`이 `process-judge` 호출, 결과를 `eval:results` Stream에 저장
|
||||
- `src/eval/runner.ts` — `evaluateCase`가 ProcessTrace 수집, `processJudge` 결과를 EvalCaseResult에 포함
|
||||
- `src/skills/onboarding/skill.ts` — `handle()`이 ProcessTrace를 수집해 ShadowEvalBus에 전달
|
||||
- `src/skills/onboarding/runtime/orchestrator.ts` — planner output / tool calls / critic decisions를 trace에 기록
|
||||
- `src/skills/onboarding/runtime/validator.ts` — validation result를 trace에 기록 (이미 반환되고 있음, trace에 push만)
|
||||
|
||||
### 6.2 ProcessTrace schema (`src/skills/onboarding/runtime/trace.ts`)
|
||||
|
||||
```typescript
|
||||
export interface ProcessTraceStep<T> {
|
||||
name: string; // "classify" | "derive" | "plan" | "tool-call" | "respond" | "critic" | "validate"
|
||||
startedAtMs: number;
|
||||
durationMs: number;
|
||||
output: T; // 단계별 output 직렬화
|
||||
}
|
||||
|
||||
export interface ProcessTraceSnapshot {
|
||||
steps: {
|
||||
classify: ProcessTraceStep<{
|
||||
intent: string;
|
||||
confidence: number;
|
||||
source: "trigger" | "regex" | "llm";
|
||||
}>;
|
||||
derive: ProcessTraceStep<{
|
||||
phase: string;
|
||||
responseMode: string;
|
||||
tier: 0 | 1 | 2;
|
||||
shouldRespond: boolean;
|
||||
}>;
|
||||
plan?: ProcessTraceStep<{
|
||||
approach: string;
|
||||
suggestedTools: string[];
|
||||
mustInclude: string[];
|
||||
mustAvoid: string[];
|
||||
targetLengthChars: number;
|
||||
}>;
|
||||
toolCalls?: ProcessTraceStep<{
|
||||
name: string;
|
||||
args: unknown;
|
||||
resultSummary: string; // 첫 200자
|
||||
ok: boolean;
|
||||
}>[];
|
||||
respond: ProcessTraceStep<{
|
||||
draftText: string;
|
||||
tokensIn: number;
|
||||
tokensOut: number;
|
||||
}>;
|
||||
critic?: ProcessTraceStep<{
|
||||
decision: "keep" | "rewrite";
|
||||
rationale: string;
|
||||
}>;
|
||||
validate: ProcessTraceStep<{
|
||||
status: "pass" | "soft-warn" | "reject";
|
||||
reasons: string[];
|
||||
}>;
|
||||
};
|
||||
}
|
||||
|
||||
export class ProcessTraceCollector {
|
||||
startStep<T>(name: string): { finish: (output: T) => void };
|
||||
snapshot(): ProcessTraceSnapshot;
|
||||
}
|
||||
```
|
||||
|
||||
- `OnboardingSkill.handle()`이 collector 생성 → 각 단계 호출부에 `startStep` 주입
|
||||
- ALS(`RequestContext`)에 collector 보관 — orchestrator/tool loop가 직접 import 없이 접근
|
||||
- 직렬화 시 PII 우려: `args`/`draftText`는 이미 anonymize 단계 통과한 상태(`agent.ts`가 사전 anonymize 안 하므로 — 주의: `shadow-bus.publish` 직전에 `anonymizeProcessTrace(snapshot)` 강제 호출. `src/eval/anonymize.ts`에 함수 추가)
|
||||
|
||||
### 6.3 Process Judge (`src/eval/judges/process-judge.ts`)
|
||||
|
||||
```typescript
|
||||
export interface ProcessJudgeCheck {
|
||||
step: string;
|
||||
rule: string; // "intent-match" | "tier-appropriate" | "tools-selected-correctly" | "tool-args-valid" | "critic-decision-justified" | "validate-no-reject"
|
||||
passed: boolean;
|
||||
detail?: string;
|
||||
}
|
||||
|
||||
export interface ProcessJudgeResult {
|
||||
checks: ProcessJudgeCheck[];
|
||||
passedCount: number;
|
||||
totalCount: number;
|
||||
score: number; // passedCount / totalCount, 0..1
|
||||
rationale?: string; // LLM judge 사용 시
|
||||
}
|
||||
|
||||
export function judgeProcessRule(
|
||||
expected: EvalCaseExpected,
|
||||
trace: ProcessTraceSnapshot
|
||||
): ProcessJudgeResult;
|
||||
|
||||
export async function judgeProcessWithLlm(
|
||||
llmClient: LlmClient,
|
||||
trace: ProcessTraceSnapshot,
|
||||
options: { request: AgentRequest; finalText: string }
|
||||
): Promise<ProcessJudgeResult>;
|
||||
```
|
||||
|
||||
- **Rule mode** (offline runner 기본):
|
||||
- `intent-match`: `expected.intent` vs `trace.steps.classify.output.intent`
|
||||
- `tier-appropriate`: `responseMode === "llm-with-tools"` 케이스에서 tier ≥ 1 인지
|
||||
- `tools-selected-correctly`: `expected.processExpected?.expectedTools`와 `trace.steps.toolCalls`의 names 비교 (set equality, 단 `subset` 모드도 지원)
|
||||
- `tool-args-valid`: 각 tool의 args가 해당 tool의 zod schema validation 통과 (이미 `src/tools/builtins/*`에 schema 존재)
|
||||
- `critic-decision-justified`: tier 2이고 critic이 `keep` 결정했을 때 validate가 reject가 아닌지
|
||||
- `validate-no-reject`: 마지막 validate step이 reject가 아닌지
|
||||
- **LLM mode** (shadow-worker에서 `EVAL_PROCESS_LLM_JUDGE_ENABLED=true`일 때만):
|
||||
- tool args가 `validate-nickname` 같은 도구에 적절했는지, planner의 approach 선택이 합리적이었는지 — 텍스트 rationale 위주
|
||||
- 비용 절약을 위해 sampling rate `EVAL_PROCESS_LLM_JUDGE_SAMPLING_RATE` (기본 0.1)
|
||||
|
||||
### 6.4 EvalCaseExpected 확장
|
||||
|
||||
```typescript
|
||||
export interface EvalCaseExpected {
|
||||
intent?: string;
|
||||
mustIncludeAny?: string[];
|
||||
mustNotInclude?: string[];
|
||||
responseMode?: string;
|
||||
// 신규
|
||||
processExpected?: {
|
||||
expectedTools?: string[];
|
||||
toolMode?: "exact" | "subset"; // 기본 "subset"
|
||||
expectedApproach?: string;
|
||||
minSteps?: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- `onboarding.jsonl`의 기존 케이스는 `processExpected` 없으면 process-judge가 해당 check를 skip(skipped flag)
|
||||
- `eval:capture`가 capture할 때 trace 데이터를 함께 직렬화 → curation 시 사람이 `processExpected` 채울 수 있도록 `notes`에 보조 정보 노출
|
||||
|
||||
### 6.5 Shadow integration
|
||||
|
||||
- `OnboardingSkill.handle()`이 trace collector 생성 → `shadowEvalPublisher.publish({...envelope, process: anonymizeProcessTrace(collector.snapshot())})`
|
||||
- `shadow-worker.processShadowEval`이 LLM mode가 활성이면 `judgeProcessWithLlm` 호출, 항상 `judgeProcessRule` 호출
|
||||
- `eval:results` Stream entry에 `processJudge` (JSON), `process` (JSON, 디버깅용 trace) 필드 추가
|
||||
- aggregator가 `processJudge.score`도 slice metric에 누적 (Phase 6 Hash에 `processJudgeSum`/`processJudgeCount` 필드 추가)
|
||||
|
||||
### 6.6 신규 env
|
||||
|
||||
| Key | 기본값 | 설명 |
|
||||
|---|---|---|
|
||||
| `EVAL_PROCESS_LLM_JUDGE_ENABLED` | `false` | shadow-worker에서 LLM mode 활성 |
|
||||
| `EVAL_PROCESS_LLM_JUDGE_SAMPLING_RATE` | 0.1 | LLM mode 샘플링 |
|
||||
| `EVAL_PROCESS_LLM_JUDGE_MAX_TOKENS` | 256 | LLM judge max tokens |
|
||||
|
||||
### 6.7 검증
|
||||
- `process-judge.test.ts`: 6개 rule 각각의 pass/fail 케이스 fixture
|
||||
- `runner.ts`의 `runOnboardingEval` 출력에 `processJudge` 필드 존재 확인
|
||||
- 한 번 `npm run eval`을 돌려 기존 골든셋이 process-judge skipped(processExpected 미정의)로 통과하는지 확인 (회귀 방지)
|
||||
- shadow eval entry에 `processJudge` 필드 채워지는지 5분 내 확인
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase 8 — Hybrid Human-in-the-Loop
|
||||
|
||||
### 7.1 Critical Files
|
||||
- **신규**:
|
||||
- `src/eval/review/queue.ts` — 검토 큐 publisher / consumer
|
||||
- `src/eval/review/cli.ts` — interactive CLI (npm run eval:review)
|
||||
- `src/eval/review/calibration.ts` — 사람 vs LLM 점수 상관 계산
|
||||
- `src/eval/review/queue.test.ts`, `src/eval/review/calibration.test.ts`
|
||||
- **변경**:
|
||||
- `src/eval/shadow-worker.ts` — review-routing tick 추가 (5분), 조건 충족 케이스를 review queue Stream에 publish
|
||||
- `src/eval/cli.ts` — `eval:review`, `eval:calibrate` 명령 추가
|
||||
- `package.json` — script 추가
|
||||
|
||||
### 7.2 Review queue (`src/eval/review/queue.ts`)
|
||||
|
||||
```typescript
|
||||
export interface ReviewQueueEntry {
|
||||
evalStreamId: string; // lolympus-agent:eval:results의 id
|
||||
reason: "low-score" | "rule-llm-disagree" | "validator-soft-warn" | "rare-slice";
|
||||
// shadow eval entry snapshot (review CLI가 별도 lookup 안 하도록)
|
||||
request: AgentRequest;
|
||||
response: AgentResponse;
|
||||
derived: DerivedState;
|
||||
classified: ClassifiedIntent;
|
||||
validation: ValidationResult;
|
||||
llmJudge: LlmJudgeResult;
|
||||
processJudge?: ProcessJudgeResult;
|
||||
process?: ProcessTraceSnapshot;
|
||||
enqueuedAt: string;
|
||||
}
|
||||
|
||||
export async function enqueueReviewCandidate(
|
||||
garnetClient: GarnetClient,
|
||||
entry: ReviewQueueEntry
|
||||
): Promise<string>;
|
||||
|
||||
export async function fetchNextReviewItem(
|
||||
garnetClient: GarnetClient,
|
||||
options: { consumerName: string; blockMs?: number }
|
||||
): Promise<{ streamId: string; entry: ReviewQueueEntry } | null>;
|
||||
|
||||
export async function recordReviewLabel(
|
||||
garnetClient: GarnetClient,
|
||||
options: {
|
||||
streamId: string;
|
||||
consumerName: string;
|
||||
label: ReviewLabel;
|
||||
}
|
||||
): Promise<void>;
|
||||
|
||||
export interface ReviewLabel {
|
||||
evalStreamId: string;
|
||||
verdict: "pass" | "fail";
|
||||
humanScore: 1 | 2 | 3 | 4 | 5;
|
||||
rationale: string;
|
||||
betterResponse?: string; // 선택적, golden 후보용
|
||||
reviewedBy: string; // env REVIEWER_ID 또는 git user.email
|
||||
reviewedAt: string;
|
||||
}
|
||||
```
|
||||
|
||||
- **Routing**: shadow-worker가 5분 tick에서 최근 25분간 eval result 중 다음 조건의 케이스를 enqueue (각 카테고리당 최대 5건):
|
||||
- `low-score`: `llmJudge.scores.overall ≤ 2`
|
||||
- `rule-llm-disagree`: `validation.status === "pass" && llmJudge.scores.overall ≤ 3`, 또는 반대
|
||||
- `validator-soft-warn`: `validation.status === "soft-warn"`
|
||||
- `rare-slice`: 7일 누적 카운트 ≤ 5인 slice의 새 entry 1건
|
||||
- 각 카테고리당 dedupe: `lolympus-agent:eval:review:dedupe:{evalStreamId}` SETNX EXPIRE 7일
|
||||
- Stream: `lolympus-agent:eval:review:queue` (consumer group `reviewers`, MAXLEN `EVAL_REVIEW_QUEUE_MAXLEN` 기본 500)
|
||||
- Label Stream: `lolympus-agent:eval:review:labeled` (MAXLEN `EVAL_REVIEW_LABEL_MAXLEN` 기본 5000, TTL은 archive 통해 영속)
|
||||
- 사람이 라벨링 완료 시 XACK + label Stream에 publish
|
||||
|
||||
### 7.3 Review CLI (`src/eval/review/cli.ts`)
|
||||
|
||||
`npm run eval:review` (cli.ts에서 router):
|
||||
```
|
||||
[1/12] reason: low-score
|
||||
chatroom: room_2a83 / user: user_1f0c / trigger: photo-failed
|
||||
intent: photo-question (confidence 0.92, llm)
|
||||
tier: 1 / phase: discord-step / responseMode: llm
|
||||
|
||||
[user message]
|
||||
사진을 어디로 보내야 하나요?
|
||||
|
||||
[assistant response]
|
||||
디스코드 채널에 올려주시면 됩니다 :)
|
||||
|
||||
[llm judge] overall=2 friendliness=4 accuracy=1 concision=3 scope=2
|
||||
rationale: 사용자가 사진 인증을 물었는데 디스코드를 잘못 안내함
|
||||
|
||||
[validator] status=pass
|
||||
|
||||
[process] classify→derive→respond→validate (no plan/tools)
|
||||
|
||||
verdict (p=pass / f=fail / s=skip / q=quit) >
|
||||
humanScore (1-5) >
|
||||
rationale > 사진은 카톡 봇으로 보내야 함, discord와 혼동 응답
|
||||
better (optional, ENTER to skip) > 사진은 이 채팅방에 직접 올려주시면 봇이 자동 인증해드려요. discord는 텍스트 인증용입니다.
|
||||
```
|
||||
|
||||
- 명령 옵션:
|
||||
- `--limit=N`: 한 세션 최대 N개 (기본 20)
|
||||
- `--reason=low-score`: 특정 reason만
|
||||
- `--export-labeled=path.jsonl`: 세션 종료 시 labeled를 jsonl로 export
|
||||
- `--reset-pending`: 기존 PEL을 모두 XCLAIM 후 stale 정리 (옵션, 1시간 idle 이상)
|
||||
- 반복문 구조:
|
||||
1. `fetchNextReviewItem(blockMs=5000)` — 큐 비면 5초 대기 후 종료
|
||||
2. 항목 표시 → stdin에서 verdict/score/rationale/better 수집
|
||||
3. `recordReviewLabel` → XACK
|
||||
4. `q` 입력 시 즉시 종료
|
||||
|
||||
### 7.4 Calibration (`src/eval/review/calibration.ts`)
|
||||
|
||||
```typescript
|
||||
export interface CalibrationReport {
|
||||
pairs: number;
|
||||
pearsonOverall: number;
|
||||
pearsonByDim: { friendliness: number; accuracy: number; concision: number; scope: number };
|
||||
meanGapOverall: number; // mean(human - llm)
|
||||
worstDisagreements: Array<{ evalStreamId: string; humanScore: number; llmOverall: number }>;
|
||||
generatedAt: string;
|
||||
}
|
||||
|
||||
export async function computeCalibrationReport(
|
||||
mongoClient: MongoClient,
|
||||
garnetClient: GarnetClient,
|
||||
options?: { since?: string }
|
||||
): Promise<CalibrationReport>;
|
||||
```
|
||||
|
||||
- `eval:calibrate` CLI가 호출
|
||||
- MongoDB `eval_archive` + Redis labeled Stream(또는 archive된 label)을 evalStreamId로 join
|
||||
- `pearsonOverall ≤ EVAL_CALIBRATION_MIN_CORR` (기본 0.5)면 `npm run eval:calibrate --check`가 exit code 1 (CI gate에 활용 가능)
|
||||
- worstDisagreements top 10은 LLM judge prompt 개선의 입력으로 사용 (Phase 9의 propose에 연결)
|
||||
|
||||
### 7.5 Auto-promotion 연동
|
||||
Phase 6의 `promote.ts`가 promotion candidate 선정 시 다음 우선순위 추가:
|
||||
- **labeled-fail**: `humanScore ≤ 2`인 케이스 (사람이 명시적으로 "잘못된 응답"이라 한 것 — 가장 가치 높음)
|
||||
- `betterResponse`가 있으면 `EvalCaseExpected.notes`에 함께 기재해 사람이 golden curation 시 참고
|
||||
|
||||
### 7.6 신규 env
|
||||
|
||||
| Key | 기본값 | 설명 |
|
||||
|---|---|---|
|
||||
| `EVAL_REVIEW_TICK_MS` | 300000 | review-routing tick (5분) |
|
||||
| `EVAL_REVIEW_QUEUE_MAXLEN` | 500 | review queue Stream MAXLEN |
|
||||
| `EVAL_REVIEW_LABEL_MAXLEN` | 5000 | labeled Stream MAXLEN |
|
||||
| `EVAL_REVIEW_PER_CATEGORY_LIMIT` | 5 | tick당 카테고리별 enqueue 한도 |
|
||||
| `EVAL_REVIEW_DEDUPE_TTL_SEC` | 604800 | enqueue dedupe TTL (7일) |
|
||||
| `EVAL_CALIBRATION_MIN_CORR` | 0.5 | 캘리브레이션 임계 |
|
||||
| `REVIEWER_ID` | (git user.email) | review CLI에서 reviewedBy 자동 채움 |
|
||||
|
||||
### 7.7 신규 Redis key
|
||||
|
||||
| Key Pattern | Type | TTL | 설명 |
|
||||
|---|---|---|---|
|
||||
| `lolympus-agent:eval:review:queue` | Stream | MAXLEN `EVAL_REVIEW_QUEUE_MAXLEN` | review 대기 큐 (consumer group `reviewers`) |
|
||||
| `lolympus-agent:eval:review:labeled` | Stream | MAXLEN `EVAL_REVIEW_LABEL_MAXLEN` | 사람 라벨 적립 |
|
||||
| `lolympus-agent:eval:review:dedupe:{evalStreamId}` | String | `EVAL_REVIEW_DEDUPE_TTL_SEC` | 동일 케이스 중복 라우팅 방지 |
|
||||
| `lolympus-agent:eval:review:cursor` | String | no TTL | 마지막 검토 라우팅된 stream id |
|
||||
|
||||
### 7.8 검증
|
||||
1. shadow-worker 부팅 + 가짜 low-score eval entry 5건 → 5분 내 `eval:review:queue`에 5개 enqueue
|
||||
2. `npm run eval:review --limit=2` 실행 → 2건 라벨링 → labeled Stream에 2건, queue PEL 0건
|
||||
3. 동일 케이스 5분 후 다시 라우팅돼도 dedupe로 skip되는지
|
||||
4. `npm run eval:calibrate` — 5건 라벨로는 `pairs<10` 경고 + correlation 계산만 출력
|
||||
5. `eval:review:labeled` Stream → archive 컬렉션(`eval_review_labels`)으로 영속
|
||||
|
||||
---
|
||||
|
||||
## 8. Phase 9 — Closed Loop (Prompt/Tool 개선 자동 제안 + A/B 토너먼트)
|
||||
|
||||
### 8.1 Critical Files
|
||||
- **신규**:
|
||||
- `src/eval/loop/propose.ts` — 약점 슬라이스 → prompt diff / tool 후보 LLM 생성
|
||||
- `src/eval/loop/tournament.ts` — shadow에서 두 prompt 버전 동시 실행 + side-by-side judge
|
||||
- `src/eval/loop/elo.ts` — ELO 랭킹 갱신
|
||||
- `src/eval/loop/{propose,tournament,elo}.test.ts`
|
||||
- **변경**:
|
||||
- `src/eval/cli.ts` — `eval:propose`, `eval:tournament`, `eval:tournament-results` 명령
|
||||
- `src/skills/onboarding/prompts/builder.ts` — variant id를 받아 layer 차이를 적용 가능하게 (이미 layer 구조면 변경 최소)
|
||||
- `src/skills/onboarding/skill.ts` — prompt variant 선택을 위한 hook (env / variant manifest 기반)
|
||||
|
||||
### 8.2 Propose (`src/eval/loop/propose.ts`)
|
||||
|
||||
```typescript
|
||||
export interface ProposalInput {
|
||||
slice: SliceKey;
|
||||
recentLabels: ReviewLabel[]; // 사람 라벨 우선
|
||||
worstCases: EvalArchiveEntry[]; // top 5 low-score
|
||||
currentPromptSnapshot: string; // 현재 사용 중인 system prompt 텍스트
|
||||
}
|
||||
|
||||
export interface PromptVariantProposal {
|
||||
variantId: string; // hash 8자리
|
||||
description: string; // LLM이 적은 한 줄 요약
|
||||
diff: PromptLayerDiff[]; // builder.ts의 layer add/replace/remove
|
||||
rationale: string;
|
||||
expectedImprovement: string; // LLM의 가설
|
||||
}
|
||||
|
||||
export interface ToolProposal {
|
||||
variantId: string;
|
||||
description: string;
|
||||
toolName: string;
|
||||
schema: unknown; // zod schema source
|
||||
whyNeeded: string;
|
||||
}
|
||||
|
||||
export async function proposeVariants(
|
||||
llmClient: LlmClient,
|
||||
input: ProposalInput
|
||||
): Promise<{ prompts: PromptVariantProposal[]; tools: ToolProposal[] }>;
|
||||
```
|
||||
|
||||
- `eval:propose --slice=tier=1,intent=photo-question,phase=discord-step` 실행
|
||||
- LLM(`LLM_JUDGE_MODEL` 또는 `LLM_PROPOSE_MODEL` 별도 env)에 system prompt + 약점 케이스 + 현재 prompt를 넣고 prompt diff JSON을 받음
|
||||
- 결과를 `proposals/{variantId}.json`에 저장 (gitignore 안 함, PR review에 활용)
|
||||
- Tool 제안은 별도 — 같은 intent에서 LLM이 hallucinate가 잦으면 tool화 후보로 식별
|
||||
|
||||
### 8.3 Tournament (`src/eval/loop/tournament.ts`)
|
||||
|
||||
```typescript
|
||||
export interface TournamentMatch {
|
||||
matchId: string;
|
||||
variantA: string; // variantId 또는 "control"
|
||||
variantB: string;
|
||||
caseId: string; // archive entry id
|
||||
responseA: string;
|
||||
responseB: string;
|
||||
judgeVerdict: "A" | "B" | "tie";
|
||||
judgeRationale: string;
|
||||
}
|
||||
|
||||
export interface TournamentResult {
|
||||
variants: { id: string; elo: number; matches: number; wins: number }[];
|
||||
matches: TournamentMatch[];
|
||||
generatedAt: string;
|
||||
}
|
||||
|
||||
export async function runTournament(
|
||||
llmClient: LlmClient,
|
||||
options: {
|
||||
variantIds: string[]; // ["control", "abc123"]
|
||||
caseIds: string[]; // archive entry ids
|
||||
maxMatches?: number;
|
||||
}
|
||||
): Promise<TournamentResult>;
|
||||
```
|
||||
|
||||
- shadow eval과 별개로 in-process로 실행 (NATS 거치지 않음, runner.ts 패턴 재사용)
|
||||
- 각 case에 대해 두 변형(prompt diff 적용 vs control)으로 동일 input으로 응답 생성
|
||||
- LLM judge에게 (request, expected, responseA, responseB)를 주고 "A/B/tie + rationale" JSON 받음
|
||||
- ELO 갱신 (`elo.ts`, K=32, initial=1500)
|
||||
- 결과를 MongoDB `eval_tournaments` 컬렉션에 저장. `eval:tournament-results --variant=abc123` 으로 조회
|
||||
|
||||
### 8.4 Variant 적용
|
||||
- `src/skills/onboarding/prompts/builder.ts`에 `applyVariant(variantId: string): PromptBuilder` 추가
|
||||
- variant manifest: `proposals/{variantId}.json`을 빌드 타임에 import — 또는 env `PROMPT_VARIANT_ID`로 런타임 전환
|
||||
- 토너먼트는 in-process이므로 manifest를 직접 인자로 받음 (런타임 변형 불필요)
|
||||
|
||||
### 8.5 신규 env
|
||||
|
||||
| Key | 기본값 | 설명 |
|
||||
|---|---|---|
|
||||
| `LLM_PROPOSE_MODEL` | (`LLM_JUDGE_MODEL`과 동일) | propose 단계용 모델 — 더 큰 모델 권장 |
|
||||
| `LLM_PROPOSE_MAX_TOKENS` | 1024 | proposal output 길이 |
|
||||
| `EVAL_TOURNAMENT_MAX_MATCHES` | 50 | 한 토너먼트당 매치 수 |
|
||||
| `EVAL_TOURNAMENT_MIN_CASES` | 10 | propose 실행 위한 최소 케이스 수 |
|
||||
|
||||
### 8.6 PR 자동화
|
||||
- `eval:propose --apply --variant=<id>`가 통과 시:
|
||||
1. 새 branch `eval/variant-{id}` 체크아웃
|
||||
2. `src/eval/proposals/{id}.json` 커밋
|
||||
3. `src/skills/onboarding/prompts/builder.ts`에 manifest import 라인 추가
|
||||
4. PR draft 생성 (`gh pr create --draft`)
|
||||
- 토너먼트 결과를 PR description에 첨부 (ELO, win rate, sample matches)
|
||||
- **사람이 머지 결정** — 자동 머지 안 함 (`plan.md` §10의 사용자 판단 원칙 유지)
|
||||
|
||||
### 8.7 검증
|
||||
- `propose.test.ts`: 가짜 archive entries → mocked LLM → JSON 스키마 통과
|
||||
- `tournament.test.ts`: 2 variant × 5 cases → ELO 갱신 정확성, judge mock
|
||||
- `elo.test.ts`: 표준 ELO 공식 단위 테스트
|
||||
- E2E: 실제 worst slice로 `eval:propose` → `eval:tournament` → 결과 표 확인
|
||||
|
||||
---
|
||||
|
||||
## 9. Migration Strategy
|
||||
|
||||
각 Phase는 독립 PR. `plan.md` §10의 v2 직진 원칙을 그대로 따른다 (feature flag 없음, 머지 후 즉시 활성).
|
||||
|
||||
| 순서 | PR | 가드 |
|
||||
|---|---|---|
|
||||
| 1 | Phase 6: aggregator + archive + drift + promote | `npm run eval` 회귀 0건. `MONGODB_CONNECTION_STRING` 미설정이면 archive/drift는 skip + warn (개발 환경 fallback) |
|
||||
| 2 | Phase 7: process-judge + trace | 기존 골든셋 통과 (processExpected 미정의는 skip). shadow eval에 `processJudge` 필드 채움 |
|
||||
| 3 | Phase 8: review queue + CLI + calibration | Phase 6 archive가 있어야 calibration 가능 |
|
||||
| 4 | Phase 9: propose + tournament | Phase 7/8 산출물(process trace + 사람 라벨)을 입력으로 사용 |
|
||||
|
||||
배포 후 회귀 발견 시: `plan.md` §10.6과 동일하게 사용자 판단으로 git revert.
|
||||
|
||||
---
|
||||
|
||||
## 10. Risks & Mitigations
|
||||
|
||||
| 리스크 | 영향 | 완화 |
|
||||
|---|---|---|
|
||||
| MongoDB write 실패로 archive 누락 | 장기 분석 데이터 빈 곳 발생 | archive cursor 미업데이트로 다음 tick 재시도. 3회 연속 실패 시 alert (`kind="archive-stalled"`). Redis Stream MAXLEN까지 버퍼링 |
|
||||
| process trace에 PII 누출 | 개인정보 유출 | `shadow-bus.publish` 직전 `anonymizeProcessTrace()` 강제. tool args에 user nickname/userId 포함 시 자동 redaction. PR review 시 grep 기반 평문 PII 검사 |
|
||||
| Aggregator slice 폭발 (intent × phase 수십 종) | Redis 메모리 ↑ | `EVAL_AGG_TTL_SEC=7d`로 자동 expire. SCAN으로 `eval:agg:*` 1k 이하 유지. 1k 넘으면 alert |
|
||||
| LLM process-judge 비용 | CLIPROXY 호출량 ↑ | sampling 0.1 + tier 2만으로 제한 옵션 (`EVAL_PROCESS_LLM_JUDGE_TIER_FILTER`로 후속 추가 가능) |
|
||||
| Review CLI에서 사람이 큐에 부담 느낌 | 라벨링 안 하게 됨 | 한 세션 기본 20건 cap, 카테고리당 5건 라우팅. dedupe 7일로 같은 케이스 반복 노출 방지. 큐가 비어있으면 즉시 종료 |
|
||||
| Calibration 표본 부족 | 신뢰도 낮은 메트릭 | `pairs < 10`이면 경고만, 임계 검사 안 함. 표본 ≥ 30일 때부터 CI gate 가능 |
|
||||
| Auto-promotion이 노이즈 케이스로 candidate jsonl 오염 | curation 부담 ↑ | label-fail 우선, 카테고리당 10건 cap, anonymize 재적용. 사람이 candidate에서 골라 golden으로 옮기는 것은 항상 수동 |
|
||||
| Tournament 결과의 LLM judge 편향 | 잘못된 variant가 승리 | side-by-side에서 A/B 위치 swap (각 매치 50% 확률). control과 variant 둘 다 같은 케이스에서 실행해 case 분산 0 |
|
||||
| Variant manifest가 prompt builder를 깨뜨림 | 런타임 장애 | tournament는 in-process로 격리. 운영 prompt에 적용은 PR draft 단계에서 `npm run eval` 통과를 머지 조건 |
|
||||
| 4개 phase 한 번에 머지 시도 | 디버깅 어려움 | 위 §9의 순서 강제. 각 PR에 §11의 phase별 검증 통과 |
|
||||
|
||||
---
|
||||
|
||||
## 11. Verification Plan
|
||||
|
||||
### Phase별 (각 PR 머지 조건)
|
||||
|
||||
| Phase | 검증 |
|
||||
|---|---|
|
||||
| 6 | `aggregator/archive/drift/promote` 단위 테스트 통과. 5분 후 `eval:agg:*` Hash ≥ 1, 1시간 후 MongoDB `eval_archive` documents ≥ 1, 24시간 후 `onboarding.candidate.jsonl` line ≥ 1. `npm run eval:report --top=20` 정상 출력. 기존 `npm run eval` 골든셋 ≥ 80% pass |
|
||||
| 7 | `process-judge.test.ts` 통과. `runner` 결과에 `processJudge` 필드 존재. shadow eval entry에 `processJudge` 채워짐. 기존 골든셋(processExpected 없음) 회귀 0건. `anonymizeProcessTrace`가 평문 PII 0건 |
|
||||
| 8 | `queue/calibration.test.ts` 통과. 가짜 low-score 5건 → 5분 내 review queue ≥ 5. `eval:review --limit=2`로 라벨링 정상 동작. 동일 케이스 dedupe 검증. `eval:calibrate` 출력 정상 |
|
||||
| 9 | `propose/tournament/elo.test.ts` 통과. `eval:propose --slice=...` JSON 산출. `eval:tournament` ELO 갱신 + MongoDB `eval_tournaments` 컬렉션 documents ≥ 1. PR draft 생성 명령 정상 |
|
||||
|
||||
### 운영 지속 검증 (Phase 6+ 활성 후)
|
||||
- shadow eval 24h 평균 vs 7d 평균 dropPct < 15% (drift alert 0건이 정상 상태)
|
||||
- review queue PEL idle ≥ 1시간 항목 5개 미만 (라벨링 진척 모니터)
|
||||
- calibration `pearsonOverall ≥ 0.5` (LLM judge 신뢰도)
|
||||
- archive 누적 documents ≥ 일평균 (worker 정상 동작)
|
||||
|
||||
---
|
||||
|
||||
## 12. Minor Decisions (확정 기본값)
|
||||
|
||||
| 항목 | 결정 |
|
||||
|---|---|
|
||||
| Slice 정의 | `tier × intent × phase` 3-튜플. responseMode는 derive 결과로 phase에 종속이라 별도 슬라이스 안 함 |
|
||||
| Aggregator 메트릭 | count, llmOverallSum/Count, validatorRejectCount, validatorSoftWarnCount, latencySumMs, latencySamples (P95용 cap 200), processJudgeSum/Count |
|
||||
| Archive index | `{streamId: 1}` unique, `{evaluatedAt: 1}` TTL, `{tier:1, "derived.intent.kind":1, "derived.phase.kind":1, evaluatedAt:-1}` 복합 |
|
||||
| Drift 비교 metric | 우선 `llmOverall`. validatorPassRate는 v2 |
|
||||
| Process trace 직렬화 | JSON.stringify, 단 draftText/args는 600자 cap |
|
||||
| Review CLI 입력 검증 | verdict는 `p`/`f`/`s`/`q`만, humanScore는 1–5 정수. invalid면 재입력 prompt |
|
||||
| Reviewer 식별 | env `REVIEWER_ID` > `git config user.email` > `"unknown"` |
|
||||
| Tournament 매치 분배 | 각 case에서 (A,B), (B,A) 두 번 실행 후 평균 — position bias 완화 |
|
||||
| Variant 보관 위치 | `src/eval/proposals/{variantId}.json` (git-tracked) |
|
||||
| Tournament 동시성 | 직렬 실행 (LLM endpoint rate limit 고려). 병렬은 v2 |
|
||||
| 시간대 | UTC (plan.md §13 그대로) |
|
||||
|
||||
---
|
||||
|
||||
## 13. Codex Hand-off Checklist
|
||||
|
||||
Codex가 이 plan으로 작업할 때 **Phase 6부터 순차 진행**. 각 Phase 완료 기준:
|
||||
|
||||
- [ ] §5–8의 Phase별 신규/변경 파일 모두 구현
|
||||
- [ ] `npm run typecheck && npm run lint && npm run build && npm test` 통과
|
||||
- [ ] §11의 Phase별 검증 항목 통과
|
||||
- [ ] env/Redis key/NATS subject 추가 시 본 문서의 신규 항목 표를 `plan.md` §6/§7/§8에 동기 (별도 PR로 plan.md 갱신 가능)
|
||||
- [ ] 커밋/PR 본문에 "Phase N — \<title\>" 명시 (Phase 번호는 `plan.md` Phase 0–5에 이어 6, 7, 8, 9 순)
|
||||
- [ ] 각 PR에서 `npm run eval` 골든셋 ≥ 80% pass 유지
|
||||
|
||||
**참고 문서**:
|
||||
- `/Users/dahyeon/source/lolympus-agent/plan.md` — Phase 0–5 원본 (충돌 시 본 문서 우선, 단 Phase 0–5 인터페이스/스키마는 그대로 따름)
|
||||
- 본 문서가 Evaluation Stage 2의 정본
|
||||
|
||||
**질문 대응**:
|
||||
- 본 문서에 없는 세부 결정은 `plan.md`의 Resolved Decisions와 "기존 인터페이스 유지, 최소 침습" 원칙에 부합하는 방향으로 진행.
|
||||
- 불가한 모순 발견 시 작업 중단하고 사용자에게 확인.
|
||||
Reference in new issue
Block a user