Compare commits
6
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e4f7a5df48 | ||
|
|
da76af3826 | ||
|
|
1453433b62 | ||
|
|
2bb9fcf27e | ||
|
|
ae44aa03db | ||
|
|
7fa293c9e8 |
No files matched your search
@@ -4,4 +4,3 @@ eval-reports/
|
||||
node_modules/
|
||||
*.tsbuildinfo
|
||||
.env*
|
||||
env-vars/*.env
|
||||
@@ -0,0 +1,886 @@
|
||||
# lolympus-agent — Research-Driven Improvements (Codename: goofy-plum)
|
||||
|
||||
> **Audience**: Codex(또는 다른 AI 에이전트)가 self-contained 하게 작업할 수 있도록 작성됨. 기존 `plan.md` (Phase 0–5)와 `evaluation-lively-island.md` (Phase 6–9)가 이미 production 인프라(shadow eval / judge / drift / promote / tournament)를 완성한 상태를 전제로 한다.
|
||||
>
|
||||
> **충돌 시 우선순위**: 본 문서 > `evaluation-lively-island.md` > `plan.md`. 단 Phase 0–9의 인터페이스/스키마/env 컨벤션은 그대로 따른다.
|
||||
>
|
||||
> **참고 논문 (papers/ 내)**
|
||||
> - **Paper A** — arXiv 2602.12430v3 (Xu & Yan, 2026.02) *Agent Skills for LLMs*. SKILL.md 명세, progressive disclosure(L1/L2/L3), Tool Search Tool, Programmatic Tool Calling, Skill Trust & Lifecycle Governance(G1–G4 gates · T1–T4 tiers).
|
||||
> - **Paper B** — arXiv 2502.09054v1 (Zellinger et al., 2025.02) *Cost-Saving LLM Cascades with Early Abstention*. cheap model이 cascade 초반에 abstain → cost −13%, error −5%, abstention +4.1%.
|
||||
> - **Paper C** — arXiv 2605.06350v1 (Bouchard, 2026.05) *Decision-Theoretic Characterization of LLM Cascades*. k>2 cascade는 잘 튜닝된 2-model pairwise envelope 대비 우월하지 않음. **Pre-generation diagnostic router**가 4/5 benchmarks에서 cascade 우위.
|
||||
|
||||
---
|
||||
|
||||
## 1. Context — 왜 이 작업
|
||||
|
||||
### 문제 (현 production agent의 격차)
|
||||
1. **비용 효율의 구조적 한계** — `OnboardingOrchestrator.run()`은 `derived.tier`만 보고 tier0/1/2 LLM 호출. classify confidence가 낮아도 동일 비용. Paper B/C 기준 cheap-model generation 자체를 피할 수 있는 *pre-generation* 결정 지점이 부재.
|
||||
2. **Tool 사용의 견고성/확장성 한계** — `tool-loop.ts`는 `maxHops=2` 고정, retry/error 분류 없음. tool 1개 실패 시 throw로 전체 흐름 정지. 신규 skill 도입 시 도구 prompt bloat 폭증 구조.
|
||||
3. **Skill 추상화 부재** — `PromptBuilder.buildSystemPrompt()`가 persona/policy/state/examples/context를 매 요청 1회 직렬화(~1800 tokens). 신규 skill 추가가 단기 결정됨에 따라 SKILL.md progressive disclosure 도입 필수.
|
||||
4. **자동 propose의 안전망 부재** — `eval/loop/propose.ts`는 LLM이 생성한 prompt variant를 직접 file에 기록. injection / unintended behavior 차단 게이트 없음. Paper A: community skill 26.1%에 취약점.
|
||||
|
||||
### 의도한 결과 (3개월 horizon)
|
||||
- 평균 응답 비용 **−15~20%**, p50 latency **−10~15%**
|
||||
- LLM judge overall **regression 0** (또는 +0.3 이상)
|
||||
- 신규 skill 추가 시간을 monolithic 대비 **5x 단축**할 수 있는 SKILL.md 인프라
|
||||
- 자동 propose 변형이 G1–G4 gate를 거쳐 prod에 **안전 승급**되는 폐쇄 루프
|
||||
|
||||
### 비목표
|
||||
- 코드 실행 sandbox 형태의 Programmatic Tool Calling (DAG 형태로 한정)
|
||||
- 외부 embedding 서비스 의존 (로컬 Qwen-embed 만 사용; 미정인 동안 v3 router 보류)
|
||||
- 단일 회사 외부 trust tier T4(vendor-certified) 자동화 — 인간 검토 유지
|
||||
|
||||
---
|
||||
|
||||
## 2. 사용자 결정 (반영됨)
|
||||
|
||||
| 항목 | 결정 |
|
||||
|---|---|
|
||||
| Phase α 우선 가치 | **균형** — Early Abstention + Tool Error Recovery + Programmatic 시범 |
|
||||
| Abstention 정책 | **Hybrid (대화 위치 기반)** — 초반 turn은 짧은 확인 질문, 반복/혼란 시그널은 `[NO_RESPONSE]` |
|
||||
| Skill 확장 | **단기 내 추가 예정** → SKILL.md(#1) Phase β로, Governance(#7) Phase γ 앞부분으로 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Relationship to Existing Plans (변경 영향)
|
||||
|
||||
### 그대로 사용 (변경 없음)
|
||||
- `src/eval/{capture,anonymize,runner,types,shadow-bus,shadow-worker,aggregator,archive,drift,promote}.ts`
|
||||
- `src/eval/judges/{rule-judge,llm-judge}.ts`
|
||||
- `src/eval/loop/{tournament,elo}.ts`
|
||||
- `src/eval/review/{queue,label-archive,calibration}.ts`
|
||||
- `src/eval/golden/*.jsonl` (스키마 호환 유지)
|
||||
- Redis/Garnet 키, NATS subjects, env 컨벤션
|
||||
- 익명화(`anonymize.ts`) — 신규 user-memory 쓰기에 강제 적용
|
||||
|
||||
### 확장 / 변경
|
||||
- `src/skills/onboarding/runtime/{orchestrator,tool-loop,critic,trace}.ts` — 행동 분기 추가, 시그니처 일부 확장
|
||||
- `src/skills/onboarding/state/{derive,onboarding-state,blackboard}.ts` — `routingDecision`, `abstentionScore`, long-term key 추가
|
||||
- `src/skills/onboarding/prompts/{builder,layers,examples}.ts` — SKILL.md mode 분기, retriever 호출
|
||||
- `src/llm/routing.ts` — `selectModelsForProvider` · `selectProviderOrder` 시그니처에 `routingDecision` 옵션 추가
|
||||
- `src/eval/judges/process-judge.ts` — PRM forward score 통합
|
||||
- `src/eval/loop/propose.ts` — T1 자동 진입 + gate 호출
|
||||
- `src/config.ts` — 신규 env 항목 (Section 4 참조)
|
||||
|
||||
### 신규 파일
|
||||
| 경로 | 역할 | Phase |
|
||||
|---|---|---|
|
||||
| `src/skills/onboarding/runtime/abstention.ts` | Hybrid early abstention 결정 | α |
|
||||
| `src/skills/onboarding/runtime/tool-plan-runner.ts` | DAG 기반 programmatic tool calling | α |
|
||||
| `src/skills/onboarding/runtime/router.ts` | Pre-gen diagnostic router | β |
|
||||
| `src/skills/onboarding/runtime/runtime-flag-manifest.ts` | tournament 가능한 runtime flag variant | α (시작) / β (확장) |
|
||||
| `src/skills/onboarding/SKILL.md` | L1 metadata + L2 body | β |
|
||||
| `src/skills/onboarding/resources/*.md` | L3 resources (nickname-format, heart-rule, discord-format, age-policy) | β |
|
||||
| `src/skills/skill-loader.ts` | SkillRegistry — 모든 SKILL.md 인덱스 | β |
|
||||
| `src/skills/onboarding/state/user-memory.ts` | UserMemoryStore (long-term) | β |
|
||||
| `src/skills/onboarding/prompts/example-store.ts` | ExampleRetriever | β |
|
||||
| `src/eval/judges/prm.ts` | Process Reward Model (v1 Ridge) | β |
|
||||
| `src/eval/judges/attribution.ts` | outcome → trace step root cause | β |
|
||||
| `src/eval/governance/gates.ts` | G1–G4 gates | γ |
|
||||
| `src/eval/governance/trust.ts` | T1–T4 promotion/demotion | γ |
|
||||
| `src/tools/tool-search.ts` | search_tools meta tool | γ |
|
||||
|
||||
### 신규 의존
|
||||
- 없음. 모든 신규 기능은 기존 의존(Garnet, MongoDB driver, Zod, LlmClient, Pino, OpenTelemetry)로 구현 가능.
|
||||
- (v3 router·example-store v2 시점에) 로컬 Qwen-embed가 필요 — 그 시점 별도 결정 (현 단계 보류).
|
||||
|
||||
---
|
||||
|
||||
## 4. 신규 환경 변수 / 설정
|
||||
|
||||
`src/config.ts`에 추가. 모든 신기능은 default OFF로 시작 → shadow eval 후 ON.
|
||||
|
||||
```
|
||||
# Phase α
|
||||
AGENT_ABSTENTION_ENABLED=false
|
||||
AGENT_ABSTENTION_THRESHOLD=0.35 # ξ — [NO_RESPONSE] 임계
|
||||
AGENT_ABSTENTION_CLARIFY_THRESHOLD=0.45 # φ_clarify — clarify 질문 임계
|
||||
AGENT_TOOL_RETRY_MAX=1
|
||||
AGENT_TOOL_LOOP_MAX_HOPS=3 # 기존 2 → 3 (precondition retry 여유)
|
||||
AGENT_PROGRAMMATIC_TOOL_CALLING=false # variant manifest 노출도 가능
|
||||
|
||||
# Phase β
|
||||
AGENT_SKILL_MD_MODE=false # SKILL.md L1/L2/L3 disclosure
|
||||
AGENT_ROUTER_MODE=static # static | learned-v1 | learned-v2
|
||||
AGENT_ROUTER_WEIGHTS_PATH=
|
||||
AGENT_USER_MEMORY_ENABLED=false
|
||||
AGENT_USER_MEMORY_TTL_DAYS=30
|
||||
EVAL_PRM_ENABLED=false
|
||||
EVAL_PRM_WEIGHTS_PATH=
|
||||
|
||||
# Phase γ
|
||||
AGENT_TRUST_MIN_TIER=T2 # 미달 variant는 control fallback
|
||||
AGENT_CRITIC_MAX_ITERATIONS=2
|
||||
AGENT_TOOL_SEARCH_ENABLED=false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Phase α (Week 1-2) — 즉시 효과·낮은 위험
|
||||
|
||||
### TASK-α-2-01 · Hybrid Early Abstention
|
||||
|
||||
**파일**: `src/skills/onboarding/runtime/abstention.ts` (신규), `src/skills/onboarding/runtime/orchestrator.ts`, `src/skills/onboarding/state/onboarding-state.ts`, `src/config.ts`, `src/skills/onboarding/onboarding-templates.ts`
|
||||
|
||||
**시그니처**:
|
||||
```ts
|
||||
// src/skills/onboarding/runtime/abstention.ts
|
||||
export type AbstentionAction =
|
||||
| { kind: "proceed" }
|
||||
| { kind: "clarify"; templateKey: "abstain-clarify-default" | string }
|
||||
| { kind: "no-response" };
|
||||
|
||||
export interface AbstentionDecision {
|
||||
action: AbstentionAction;
|
||||
reason:
|
||||
| "low-confidence-early-turn"
|
||||
| "low-confidence-repeated"
|
||||
| "off-topic-strong"
|
||||
| "flagged-confused"
|
||||
| null;
|
||||
score: number; // 0..1
|
||||
features: {
|
||||
classifyConfidence: number;
|
||||
intentKind: Intent["kind"];
|
||||
turnIndex: number;
|
||||
sameIntentStreak: number;
|
||||
flaggedIssues: number;
|
||||
};
|
||||
}
|
||||
|
||||
export function decideEarlyAbstention(input: {
|
||||
classified: ClassifiedIntent;
|
||||
derived: DerivedState;
|
||||
blackboard: Blackboard | null;
|
||||
request: AgentRequest;
|
||||
thresholds: {
|
||||
abstain: number; // AGENT_ABSTENTION_THRESHOLD
|
||||
clarify: number; // AGENT_ABSTENTION_CLARIFY_THRESHOLD
|
||||
};
|
||||
}): AbstentionDecision;
|
||||
```
|
||||
|
||||
**룰 (Hybrid)**:
|
||||
1. `intent.kind === "off-topic-to-other"` && `confidence > 0.9` → `no-response`, reason=`off-topic-strong`.
|
||||
2. `flaggedIssues.length > 0` || `sameIntentStreak >= 3` (blackboard.lastIntent 비교) → `no-response` if confidence < abstain, reason=`flagged-confused` or `low-confidence-repeated`.
|
||||
3. `turnIndex <= 1` (greetedAt 미존재) && `confidence < clarify` && intent ∈ {unknown, chitchat} → `clarify` (templateKey=`abstain-clarify-default` = "조금 더 구체적으로 알려주시면 도와드릴게요!"), reason=`low-confidence-early-turn`.
|
||||
4. 그 외 → `proceed`.
|
||||
|
||||
**orchestrator 통합** (`runtime/orchestrator.ts:run()` 진입부 직후):
|
||||
```ts
|
||||
if (getAbstentionEnabled()) {
|
||||
const decision = decideEarlyAbstention({
|
||||
classified, derived, blackboard, request,
|
||||
thresholds: { abstain: getAbstentionThreshold(), clarify: getAbstentionClarifyThreshold() },
|
||||
});
|
||||
derived.abstentionScore = decision.score;
|
||||
traceCollector?.startStep("classify").finish({
|
||||
confidence: classified.confidence,
|
||||
intent: classified.intent.kind,
|
||||
source: classified.source,
|
||||
abstention: decision, // process-trace에 기록
|
||||
});
|
||||
if (decision.action.kind === "no-response") {
|
||||
return { text: "[NO_RESPONSE]", validation: { status: "pass", reasons: ["early-abstention"] } };
|
||||
}
|
||||
if (decision.action.kind === "clarify") {
|
||||
return { text: getOnboardingTemplate(decision.action.templateKey), validation: { status: "pass", reasons: ["early-abstention-clarify"] } };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**템플릿 추가** (`onboarding-templates.ts`):
|
||||
```ts
|
||||
"abstain-clarify-default": "조금 더 구체적으로 알려주시면 도와드릴게요!",
|
||||
```
|
||||
|
||||
**Trace 확장** (`runtime/trace.ts`):
|
||||
- `ProcessTraceStep<classify>.output`에 `abstention?: AbstentionDecision` 필드 추가 (옵셔널, 기존 호환).
|
||||
|
||||
**Eval 연동**:
|
||||
- `src/eval/aggregator.ts`: slice에 `abstentionReason`, `abstentionAction` 차원 추가.
|
||||
- `src/eval/drift.ts`: abstention rate (action≠proceed 비율)를 metric으로 등록.
|
||||
- 통과 기준: 7일 shadow에서 cost −10% 이상, false-abstention < 2%, quality regression < 0.05.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `pnpm test src/skills/onboarding/runtime/abstention.test.ts` (신규 unit test 5+ case: off-topic / early-low-conf / repeated / proceed / boundary)
|
||||
- [ ] env OFF에서 기존 behavior 100% 일치 (snapshot 비교)
|
||||
- [ ] env ON 24h shadow에서 abstention rate 0.05~0.25 사이 (밴드 밖이면 임계 재튜닝)
|
||||
|
||||
---
|
||||
|
||||
### TASK-α-8a-01 · Structured Tool Error Recovery
|
||||
|
||||
**파일**: `src/skills/onboarding/runtime/tool-loop.ts`, `src/tools/tool.ts`, `src/skills/onboarding/runtime/trace.ts`, `src/config.ts`
|
||||
|
||||
**타입 확장** (`src/tools/tool.ts`):
|
||||
```ts
|
||||
export type ToolErrorKind = "args-invalid" | "transient" | "precondition-failed" | "permanent";
|
||||
export interface ToolExecutionFailure {
|
||||
kind: ToolErrorKind;
|
||||
toolName: string;
|
||||
message: string;
|
||||
retryable: boolean;
|
||||
details?: unknown;
|
||||
}
|
||||
```
|
||||
|
||||
**tool-loop.ts 변경 요지** (현 `:113-137` 영역):
|
||||
- zod parse 실패 → `args-invalid` → 1 hop 자기교정 (assistant tool_call → user "이전 args가 schema 어긋남" 안내). 이때 hop budget을 consume 하되 별도 카운터 `selfCorrectionHops` 추적해 무한 루프 차단(max 1).
|
||||
- fetch/timeout 등 network error 감지 (`AbortError`/`FetchError`/timeout) → `transient` → 200ms backoff → 1회 retry (`AGENT_TOOL_RETRY_MAX`). hop budget 사용 안 함.
|
||||
- tool 내부 throw → `permanent` → `{ ok: false, errorKind: "permanent", message }` 를 tool 결과로 message에 push, hop 계속.
|
||||
- precondition 검증 실패 (예: session 없음) → tool이 `result.ok=false`로 정상 반환하도록 builtins 수정 → tool-loop에서 `precondition-failed`로 분류, hop budget consume 안 함.
|
||||
|
||||
**maxHops**: 기본 `getAgentToolLoopMaxHops()` (default 3). precondition-failed로 인한 추가 hop은 +1 까지만 허용.
|
||||
|
||||
**Trace 확장**:
|
||||
```ts
|
||||
toolCalls?: Array<ProcessTraceStep<{
|
||||
name: string;
|
||||
args: unknown;
|
||||
ok: boolean;
|
||||
resultSummary: string;
|
||||
errorKind?: ToolErrorKind; // 신규
|
||||
retried?: boolean; // 신규
|
||||
}>>;
|
||||
```
|
||||
|
||||
**재사용**:
|
||||
- `parseToolCalls` (`src/tools/parser.ts`) — 변경 없음
|
||||
- 기존 `traceStep?.finish({ ok: false, ... })` 경로
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `src/skills/onboarding/runtime/tool-loop.test.ts` (신규): mock tool throw / network timeout / zod-invalid / precondition-failed 각 케이스
|
||||
- [ ] tool-heavy slice(nickname-rejected, discord-verify-question) shadow eval에서 success rate +3% 이상
|
||||
- [ ] p95 latency 변화 < +200ms
|
||||
|
||||
---
|
||||
|
||||
### TASK-α-4a-01 · Programmatic Tool Calling 시범 (선언적 DAG)
|
||||
|
||||
**파일**: `src/skills/onboarding/runtime/tool-plan-runner.ts` (신규), `src/skills/onboarding/runtime/planner-schema.ts`, `src/skills/onboarding/runtime/orchestrator.ts`
|
||||
|
||||
**스키마 확장** (`planner-schema.ts`):
|
||||
```ts
|
||||
export const toolPlanStepSchema = z.object({
|
||||
id: z.string().min(1),
|
||||
tool: z.string().min(1),
|
||||
argsFromContext: z.record(z.string(), z.string()).optional(), // "$request.nickname"
|
||||
argsLiteral: z.record(z.string(), z.unknown()).optional(),
|
||||
dependsOn: z.array(z.string()).optional(),
|
||||
on: z.object({ error: z.enum(["abort", "fallback-llm"]).optional() }).optional(),
|
||||
});
|
||||
export const toolPlanSchema = z.object({
|
||||
steps: z.array(toolPlanStepSchema).max(4), // 안전 한계
|
||||
composeWith: z.enum(["all-then-llm", "first-then-llm"]),
|
||||
});
|
||||
export const plannerOutputSchema = z.object({
|
||||
approach: z.string(),
|
||||
mustInclude: z.array(z.string()).optional(),
|
||||
mustAvoid: z.array(z.string()).optional(),
|
||||
suggestedTools: z.array(z.string()).optional(),
|
||||
targetLengthChars: z.number().optional(),
|
||||
toolPlan: toolPlanSchema.optional(), // NEW
|
||||
});
|
||||
```
|
||||
|
||||
**runner** (`tool-plan-runner.ts`):
|
||||
```ts
|
||||
export interface ToolPlanResult {
|
||||
results: Record<string /* step id */, unknown>;
|
||||
failures: ToolExecutionFailure[];
|
||||
durationMs: number;
|
||||
}
|
||||
export async function runToolPlan(
|
||||
plan: ToolPlan,
|
||||
tools: readonly Tool<unknown, unknown>[],
|
||||
ctx: ToolContext,
|
||||
request: AgentRequest,
|
||||
): Promise<ToolPlanResult>;
|
||||
```
|
||||
- DAG 정렬 (`dependsOn`) 후 `Promise.all`로 동일 레벨 동시 실행 (단 동일 NATS RPC 큐 부담 고려해 `Promise.all` 최대 2 병렬).
|
||||
- `$request.nickname`, `$request.userId`, `$session.openQuestions[0]` 등 path 표현식 resolve.
|
||||
- 실패 시 `on.error === "fallback-llm"`이면 tool-loop으로 fallback (free-form), `abort`이면 즉시 종료.
|
||||
|
||||
**orchestrator 통합** (`run()` planner 출력 처리 부분):
|
||||
- planner output에 `toolPlan` 있고 `getProgrammaticToolCalling()` ON이면 `runToolPlan` 먼저 → 결과를 message[]에 tool messages로 push → responder 1회 호출.
|
||||
- 없으면 기존 `runWithTools` 경로.
|
||||
|
||||
**variant 노출**:
|
||||
- `src/eval/proposals/planner-with-toolplan.json` 신규 — planner system layer에 `"가능하면 toolPlan 필드를 채워주세요"` append.
|
||||
- Tournament로 control vs toolplan 비교. 통과 기준 ELO +20, latency p50 −150ms 이상.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `src/skills/onboarding/runtime/tool-plan-runner.test.ts` (신규): 정상 DAG / 의존성 누락 / step 실패 fallback 케이스
|
||||
- [ ] process-judge 확장: `toolPlan.steps.length` vs `actualToolCalls.length` consistency check (`src/eval/judges/process-judge.ts`)
|
||||
|
||||
---
|
||||
|
||||
### TASK-α-FLAG-01 · RuntimeFlagManifest 인프라
|
||||
|
||||
**파일**: `src/skills/onboarding/runtime/runtime-flag-manifest.ts` (신규), `src/skills/onboarding/runtime/orchestrator.ts`, `src/eval/loop/tournament.ts`
|
||||
|
||||
**타입**:
|
||||
```ts
|
||||
export interface RuntimeFlagManifest {
|
||||
variantId: string; // e.g. "abstention-on", "router-v1"
|
||||
description: string;
|
||||
flags: Partial<{
|
||||
abstentionEnabled: boolean;
|
||||
abstentionThreshold: number;
|
||||
abstentionClarifyThreshold: number;
|
||||
programmaticToolCalling: boolean;
|
||||
toolLoopMaxHops: number;
|
||||
routerMode: "static" | "learned-v1" | "learned-v2";
|
||||
userMemoryEnabled: boolean;
|
||||
criticMaxIterations: number;
|
||||
}>;
|
||||
}
|
||||
export function loadRuntimeFlagManifest(variantId: string): RuntimeFlagManifest | null;
|
||||
export function resolveRuntimeFlags(
|
||||
base: ResolvedRuntimeFlags,
|
||||
variant?: RuntimeFlagManifest,
|
||||
): ResolvedRuntimeFlags;
|
||||
```
|
||||
|
||||
**효과**: `PromptVariantManifest`(prompt만)와 별도로 행동 변화 variant를 tournament로 비교 가능. `tournament.ts`에서 `loadVariantBundle(variantId)`가 prompt+runtime 둘 다 로드하도록 확장.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `runtime-flag-manifest.test.ts`: variant 로드 / merge / 잘못된 키 거부
|
||||
- [ ] tournament가 동일 골든셋에 대해 control / abstention-on / toolplan-on 3종 ELO 산출 가능
|
||||
|
||||
---
|
||||
|
||||
### Phase α Exit 게이트
|
||||
|
||||
전부 만족 시 Phase β 진입.
|
||||
|
||||
| 메트릭 | 측정 위치 | 목표 |
|
||||
|---|---|---|
|
||||
| Cost (shadow 7일 평균) | `eval/aggregator.ts` slice별 latencySumMs * tier price | −10% vs control |
|
||||
| LLM judge overall | `aggregator.llmOverallAvg` | ≥ baseline − 0.05 |
|
||||
| Abstention false-positive | `review/queue.ts` 라벨 vs decision | < 2% |
|
||||
| Tool failure → soft-template | `validator.ts` reject 사례 비율 | −30% |
|
||||
| Regression alerts | `drift.ts` significant count | 0 |
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase β (Week 3-5) — Skill 확장 대비 + 평가 정밀화
|
||||
|
||||
### TASK-β-1-01 · SKILL.md L1/L2/L3 Progressive Disclosure
|
||||
|
||||
**핵심 가정**: 단기 내 추가 skill(discord-help / community-rules / identity-room 중 1+) 도입 결정. SKILL.md 인프라가 없으면 prompt 폭증.
|
||||
|
||||
**신규 파일**:
|
||||
- `src/skills/onboarding/SKILL.md` — frontmatter + body
|
||||
- `src/skills/onboarding/resources/{nickname-format,heart-rule,discord-format,age-policy}.md`
|
||||
- `src/skills/skill-loader.ts` — SkillRegistry
|
||||
|
||||
**SKILL.md frontmatter 스키마**:
|
||||
```yaml
|
||||
---
|
||||
name: onboarding
|
||||
description: 카카오톡 오픈채팅 새내기 등록을 도와주는 친절한 선배 역할.
|
||||
version: 1
|
||||
intents: [greeting, acknowledgement, status-question, help-how, help-where, nickname-question, photo-question, discord-question, discord-verify-question, age-question]
|
||||
triggers: [user-message, new-member, nickname-invalid, photo-failed, progress-update, timeout-warning, completed]
|
||||
tools: [validate-nickname, check-onboarding-progress, lookup-community-rule, get-room-context, verify-discord-nickname]
|
||||
resources:
|
||||
nickname-format: ./resources/nickname-format.md
|
||||
heart-rule: ./resources/heart-rule.md
|
||||
discord-format: ./resources/discord-format.md
|
||||
age-policy: ./resources/age-policy.md
|
||||
trustTier: T3
|
||||
---
|
||||
```
|
||||
|
||||
**SkillRegistry**:
|
||||
```ts
|
||||
// src/skills/skill-loader.ts
|
||||
export interface SkillManifest {
|
||||
name: string;
|
||||
description: string;
|
||||
version: number;
|
||||
intents: string[];
|
||||
triggers: string[];
|
||||
tools: string[];
|
||||
resources: Record<string, string>; // key → relative path
|
||||
trustTier: TrustTier;
|
||||
bodyPath: string; // SKILL.md absolute path
|
||||
}
|
||||
export class SkillRegistry {
|
||||
static load(rootDir: string): SkillRegistry; // 모든 SKILL.md frontmatter 메모리 로드
|
||||
list(): SkillManifest[];
|
||||
get(name: string): SkillManifest | null;
|
||||
loadBody(name: string): Promise<string>; // L2 lazy load
|
||||
loadResource(name: string, key: string): Promise<string>; // L3 lazy load
|
||||
}
|
||||
```
|
||||
|
||||
**PromptBuilder 재설계** (`prompts/builder.ts`):
|
||||
- env `AGENT_SKILL_MD_MODE=true`일 때:
|
||||
1. system 1차 메시지: 모든 skill manifest의 `description` 만 ~30 tokens/skill 직렬화 (L1).
|
||||
2. 매칭된 skill의 body(`loadBody`)를 system 2차 메시지로 (L2).
|
||||
3. planner output에 `requestResources: ["nickname-format"]` 있으면 responder 호출 직전에 해당 resource MD를 system 3차 메시지로 inject (L3).
|
||||
- 기존 layer 함수(`personaLayer`, `policyLayer`, ...)는 그대로 두되 `policyLayer`만 intent-conditional layer로 분리되어 L2 단계에서 inject. (점진 마이그레이션)
|
||||
|
||||
**planner-schema 확장**:
|
||||
```ts
|
||||
requestResources: z.array(z.string()).optional(),
|
||||
```
|
||||
|
||||
**마이그레이션**:
|
||||
- Step 1: SKILL.md를 mirror로 생성. 기존 prompt 결과와 token 차이 측정.
|
||||
- Step 2: feature flag ON 후 24h shadow eval. quality regression < 0.05 확인.
|
||||
- Step 3: L3 resource를 nickname-related intent부터 적용 (가장 적은 intent → 점진).
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] SkillRegistry unit test: 잘못된 frontmatter / 빈 resources / 중복 name
|
||||
- [ ] snapshot test: system prompt token count baseline ↔ SKILL.md mode (≤ −40%)
|
||||
- [ ] 30일 long-soak shadow: regression < 0.05
|
||||
- [ ] dry-run: 새 skill 추가가 SKILL.md 1개 + registry 1줄로 동작
|
||||
|
||||
---
|
||||
|
||||
### TASK-β-5-01 · Process Reward Model (PRM) + Bidirectional Attribution
|
||||
|
||||
**신규 파일**:
|
||||
- `src/eval/judges/prm.ts` — feature extractor + Ridge regression (사용 라이브러리: 직접 구현, dependencies 최소)
|
||||
- `src/eval/judges/attribution.ts` — outcome → trace step root cause
|
||||
|
||||
**Feature vector** (Section 5 #5 PRM 참조):
|
||||
```ts
|
||||
export interface PrmFeatureVector {
|
||||
classifyConfidence: number; classifySource: 0|1;
|
||||
planApproach: string; // categorical hash
|
||||
toolCallCount: number; toolErrorCount: number;
|
||||
criticDecision: 0|1; validateStatus: 0|1|2; tier: 0|1|2;
|
||||
abstentionScore: number; // Phase α에서 추가됨
|
||||
}
|
||||
```
|
||||
|
||||
**Forward model (v1)**: Ridge regression on label-archive humanScore vs features. weights는 `EVAL_PRM_WEIGHTS_PATH`(JSON)에 저장.
|
||||
|
||||
**Backward attribution**:
|
||||
- 각 entry에 대해 trace step별 counterfactual delta (step output 평균값으로 swap 시 PRM score 변화) → `attributedScoreLoss`.
|
||||
- 결과 collection: `eval_process_attribution` (MongoDB).
|
||||
|
||||
**process-judge 통합** (`eval/judges/process-judge.ts`):
|
||||
```ts
|
||||
// 기존 ProcessJudgeResult에 추가
|
||||
prmScore?: number; // PRM forward
|
||||
prmFeatures?: PrmFeatureVector;
|
||||
rootCauseStep?: ProcessTraceStepName;
|
||||
rootCauseScoreLoss?: number;
|
||||
```
|
||||
|
||||
**Background job 추가** (`workers/background.ts`):
|
||||
- 새 tick: `EVAL_ATTRIBUTION_TICK_MS` (default 6h). 최근 archive entries에 대해 attribution 계산 후 collection 적재.
|
||||
- 라벨 수가 N(env `EVAL_PRM_MIN_LABELS`, default 500) 미만이면 forward 모델은 "explanation only" 모드(score 출력 X, root cause만).
|
||||
|
||||
**propose 입력 확장** (`eval/loop/propose.ts`):
|
||||
- `buildProposalInputFromArchive`에 `rootCauses: RootCauseReport[]` 필드 추가. LLM이 root cause 분포를 보고 더 타겟팅된 prompt diff 생성.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `prm.test.ts`: feature vector 안정성, weight 로드/저장
|
||||
- [ ] `attribution.test.ts`: synthetic trace에서 root cause step 식별 정확도 ≥ 0.8
|
||||
- [ ] tournament: PRM-augmented variant가 ELO +30 차이를 식별 가능 (synthetic label)
|
||||
|
||||
---
|
||||
|
||||
### TASK-β-3-01 · Pre-Generation Diagnostic Router (v1 룰)
|
||||
|
||||
**신규 파일**: `src/skills/onboarding/runtime/router.ts`
|
||||
|
||||
**Decision space**:
|
||||
```ts
|
||||
export type RoutingDecision =
|
||||
| { kind: "abstain"; reason: string } // = TASK-α-2 abstention
|
||||
| { kind: "template-only"; templateKey: string }
|
||||
| { kind: "tier0-only" }
|
||||
| { kind: "tier1-direct"; skipPlanner: boolean }
|
||||
| { kind: "tier1-with-tools" }
|
||||
| { kind: "tier2-full" };
|
||||
|
||||
export interface DiagnosticRouter {
|
||||
decide(input: RouterInput): RoutingDecision;
|
||||
}
|
||||
```
|
||||
|
||||
**v1 rules** (`router.ts` 초안):
|
||||
- `intent.kind === "off-topic-to-other"` && conf > 0.9 → `abstain`
|
||||
- `intent.kind === "greeting"` && conf > 0.95 && no prior greeting → `template-only`
|
||||
- `intent.kind === "acknowledgement"` && conf > 0.9 → `template-only`
|
||||
- `phase.kind === "nickname-rejected"` → `tier1-with-tools`
|
||||
- `phase.kind === "completed"` && intent ≠ status-question → `template-only`
|
||||
- `phase.kind ∈ {fresh, nickname-pending, photo-pending, both-pending}` && intent ∈ {nickname-question, photo-question, help-how} → `tier1-with-tools`
|
||||
- 그 외 → `tier0-only`
|
||||
|
||||
**derive.ts 통합**: `deriveState()` 끝에서 `router.decide(...)` 호출, 결과를 `DerivedState.routingDecision`에 저장.
|
||||
|
||||
**llm/routing.ts 확장**:
|
||||
- `selectModelsForProvider(provider, options, llamaFallbackModel)` 시그니처에 `routingDecision?: RoutingDecision` 추가.
|
||||
- llama 분기(`routing.ts:24-25`)는 `routingDecision.kind`가 `tier1-with-tools` 이상이면 fallback 모델 대신 explicit fallback 사용; 현 단일 모델 환경에서는 effective change 0 (multi-llama 환경 대비 hook 추가).
|
||||
- `selectProviderOrder(endpoints, options)`도 `routingDecision`을 받아 cliproxy/openrouter/llama 우선순위를 동적 조정 (예: `template-only` decision이면 llama only).
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `router.test.ts`: 30+ 케이스로 v1 룰 커버
|
||||
- [ ] Shadow A/B 24h: cost −8%, quality flat (LLM judge overall delta < 0.05)
|
||||
- [ ] `routingDecision`을 `ShadowEvalEnvelope`에 기록 (`shadow-bus.ts`) — aggregator slice 추가
|
||||
|
||||
---
|
||||
|
||||
### TASK-β-3-02 · Router v2 학습
|
||||
|
||||
**의존**: TASK-β-5-01 (PRM features). 데이터 ≥ 5000 archive entries.
|
||||
|
||||
**파일**: `src/skills/onboarding/runtime/router.ts` 확장, `scripts/train-router.ts` (신규 script)
|
||||
|
||||
**모델**: lightweight logistic regression (multi-class: 6 decision kinds). 입력은 PRM `extractFeatures` + 사용자 메시지 길이/언어 식별.
|
||||
|
||||
**학습 데이터 라벨링**:
|
||||
- archive에서 actual derived.tier · validation status · llmJudge.overall 기반 ground truth tier 추정:
|
||||
- llmJudge.overall ≥ 4 + tier=0 → `tier0-only` 충분
|
||||
- llmJudge.overall < 3 + tier=0 → `tier1-direct` 필요했음 (under-routed)
|
||||
- llmJudge.overall < 3 + tier=1 → `tier2-full` 필요했음
|
||||
- 5% exploration noise (`epsilon=0.05`) 도입 — 무작위로 1 tier ↑
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `train-router.ts` 가 weights JSON 생성 (`AGENT_ROUTER_WEIGHTS_PATH`)
|
||||
- [ ] Tournament: `router-v1` vs `router-v2` 비교 — v2 cost −5% 추가 절감
|
||||
|
||||
---
|
||||
|
||||
### TASK-β-6-01 · Persistent User Memory + Adaptive Few-shot
|
||||
|
||||
**신규 파일**:
|
||||
- `src/skills/onboarding/state/user-memory.ts`
|
||||
- `src/skills/onboarding/prompts/example-store.ts`
|
||||
|
||||
**Garnet 키**: `lolympus-agent:user:profile:{anonHash(userId)}` (TTL `AGENT_USER_MEMORY_TTL_DAYS` × 86400).
|
||||
|
||||
**UserMemoryStore**:
|
||||
```ts
|
||||
export interface UserProfile {
|
||||
userId: string; // anonHash
|
||||
firstSeenAt: string; lastSeenAt: string;
|
||||
totalTurns: number;
|
||||
preferredStyle: "concise" | "warm" | "neutral";
|
||||
pastIntents: { kind: Intent["kind"]; count: number }[];
|
||||
flaggedIssues: string[];
|
||||
completedOnboardingAt?: string;
|
||||
}
|
||||
export class UserMemoryStore {
|
||||
constructor(private garnet: GarnetClient, private salt: string) {}
|
||||
async load(userId: string): Promise<UserProfile | null>;
|
||||
async observeTurn(userId: string, derived: DerivedState, response: AgentResponse): Promise<UserProfile>;
|
||||
}
|
||||
```
|
||||
|
||||
**PII 강제**:
|
||||
- 모든 string write에 `anonymizeText` (`src/eval/anonymize.ts`) 적용. unit test로 nickname/이메일/번호 미저장 검증.
|
||||
- userId 자체는 `anonymizeIdentifier("user", userId)` 해시 사용.
|
||||
|
||||
**ExampleRetriever** (`prompts/example-store.ts`):
|
||||
- v1: intent + phase로 필터링한 golden examples 중 user.preferredStyle과 매칭되는 최대 3개 반환.
|
||||
- v2 (embedding): 보류 — 로컬 Qwen-embed 도입 결정 후.
|
||||
|
||||
**examplesLayer 시그니처 확장** (`prompts/examples.ts`):
|
||||
```ts
|
||||
export function examplesLayer(intent: Intent, retriever: ExampleRetriever, query: ExampleQuery): string;
|
||||
```
|
||||
|
||||
**variant 노출**: `runtime-flag-manifest` `userMemoryEnabled: true`.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `user-memory.test.ts`: PII redaction 강제, observeTurn idempotent
|
||||
- [ ] 같은 user(anon) 재방문 시 LLM judge friendliness 평균 +0.2 (shadow eval)
|
||||
|
||||
---
|
||||
|
||||
### Phase β Exit 게이트
|
||||
| 메트릭 | 목표 |
|
||||
|---|---|
|
||||
| system prompt token | baseline 대비 −40% (SKILL.md mode ON) |
|
||||
| 누적 cost (β 종료) | α 대비 추가 −8% |
|
||||
| PRM attribution AUC | ≥ 0.75 (라벨 1000+) |
|
||||
| 신규 skill dry-run | SKILL.md 1개 + registry 1줄로 동작 확인 |
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase γ (Week 6+) — Governance + Reflection
|
||||
|
||||
### TASK-γ-7-01 · Skill Trust & Lifecycle Governance (G1–G4 · T1–T4)
|
||||
|
||||
**신규 파일**: `src/eval/governance/gates.ts`, `src/eval/governance/trust.ts`
|
||||
|
||||
**Gates 시그니처**:
|
||||
```ts
|
||||
export interface GateResult { passed: boolean; reason?: string; evidence?: unknown; }
|
||||
|
||||
export function runG1Static(manifest: PromptVariantManifest | RuntimeFlagManifest): GateResult;
|
||||
// URL allowlist (validator.ts:8-11 재사용), layer 길이 제한, persona override 차단, 위험 키워드
|
||||
|
||||
export async function runG2Semantic(manifest, control, llmClient: LlmClient): Promise<GateResult>;
|
||||
// LLM이 변형의 핵심 행동 변화 의도 분류 — "변경이 의도된 범위 내인가?"
|
||||
|
||||
export async function runG3Sandbox(manifest, evalRunner, goldenSetPath, n: number = 200): Promise<GateResult>;
|
||||
// shadow run on N=200 cases, validator reject rate / llm overall 변화 측정
|
||||
|
||||
export function runG4Permission(manifest, toolRegistry: ToolRegistry, skillRegistry: SkillRegistry): GateResult;
|
||||
// required tools/resources가 registry에 등록되어 있는지
|
||||
```
|
||||
|
||||
**Trust Tiers** (`trust.ts`):
|
||||
```ts
|
||||
export type TrustTier = "T1-unvetted" | "T2-community" | "T3-org-vetted" | "T4-certified";
|
||||
|
||||
// Promotion 규칙
|
||||
// T1 → T2: G1 + G4 통과 (자동)
|
||||
// T2 → T3: G3 sandbox + tournament 100+ matches + ELO > control + 30 + drift OK 7일 (자동)
|
||||
// T3 → T4: human review label-archive 평균 ≥ 4.0 + reviewer 2명 이상 동의 (semi-auto)
|
||||
//
|
||||
// Demotion: drift significant 또는 G3 sandbox regression → 즉시 T1로 강등 + alert
|
||||
|
||||
export async function evaluatePromotion(variantId: string, services: GovernanceServices): Promise<TrustTier>;
|
||||
export async function applyDemotion(variantId: string, reason: string): Promise<void>;
|
||||
```
|
||||
|
||||
**propose.ts 통합** (`eval/loop/propose.ts`):
|
||||
- 새 proposal은 항상 T1로 저장. `writeVariantManifest` 호출 직후 `runG1Static` + `runG4Permission` 실행 → 통과 시 T2로 자동 승급.
|
||||
|
||||
**런타임 강제** (`src/skills/onboarding/skill.ts`):
|
||||
- `getPromptVariantId()` 로드 시 `trust.getActiveTier(variantId)` 확인. `AGENT_TRUST_MIN_TIER` (default T2) 미달이면 control fallback.
|
||||
|
||||
**Background job**:
|
||||
- `workers/background.ts`에 `EVAL_PROMOTION_TICK_MS` (default 30m). 모든 T1/T2 variant 대상 promotion 평가 실행.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] `gates.test.ts`: 의도적 prompt injection variant가 G1에서 차단
|
||||
- [ ] T1→T2 자동 승급, T2→T3 tournament 게이트 통과 시 자동 승급 시뮬레이션
|
||||
- [ ] Drift significant 발생 시 즉시 강등 통합 테스트
|
||||
|
||||
---
|
||||
|
||||
### TASK-γ-4b-01 · Tool Search Tool
|
||||
|
||||
**신규 파일**: `src/tools/tool-search.ts`. `src/tools/registry.ts`에 `searchByDescription(query, k)` 추가.
|
||||
|
||||
```ts
|
||||
export const toolSearchTool: Tool<{ query: string; topK?: number }, { tools: Array<{ name: string; description: string }> }> = {
|
||||
name: "search_tools",
|
||||
description: "도구 카탈로그에서 가장 적합한 도구 후보를 검색합니다.",
|
||||
argsSchema: z.object({ query: z.string().min(2), topK: z.number().int().min(1).max(5).default(3) }),
|
||||
resultSchema: z.object({ tools: z.array(z.object({ name: z.string(), description: z.string() })) }),
|
||||
async execute(args, ctx) { /* registry.searchByDescription */ },
|
||||
};
|
||||
```
|
||||
|
||||
**registry 변경** (`tools/registry.ts`):
|
||||
- `searchByDescription(query, k)`: 단순 keyword overlap → BM25 (lite, 의존 추가 없이 inline 구현).
|
||||
- 도구 등록 시 description 인덱싱.
|
||||
|
||||
**orchestrator 통합** (`runtime/orchestrator.ts`):
|
||||
- skill manifest의 `tools` 배열이 N 초과(env `AGENT_TOOL_SEARCH_THRESHOLD`, default 10)일 때만 `search_tools`만 노출 + planner가 `requestTools: [...]` 통해 expand.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] 20 tool mock registry에서 nickname 관련 query → validate-nickname top-1 회수
|
||||
- [ ] 도구 5개 미만 환경에서는 effective change 0 (기존 path)
|
||||
|
||||
---
|
||||
|
||||
### TASK-γ-8b-01 · Multi-step Self-Critic (Reflection)
|
||||
|
||||
**파일**: `src/skills/onboarding/runtime/critic.ts`, `src/skills/onboarding/runtime/trace.ts`
|
||||
|
||||
**시그니처 확장**:
|
||||
```ts
|
||||
export interface CritiqueResultV2 {
|
||||
changed: boolean;
|
||||
text: string;
|
||||
iterations: number;
|
||||
abstained: boolean;
|
||||
rubricScores: { accuracy: number; scope: number; tone: number };
|
||||
prmScoreBefore?: number;
|
||||
prmScoreAfter?: number;
|
||||
}
|
||||
|
||||
class OnboardingCritic {
|
||||
async critiqueIterative(
|
||||
draft: string, derived: DerivedState, messages: ChatMessage[],
|
||||
options: { maxIters: number; deadlineMs: number; prm?: PrmModel },
|
||||
): Promise<CritiqueResultV2>;
|
||||
}
|
||||
```
|
||||
|
||||
**알고리즘**:
|
||||
1. PRM forward score → `prmScoreBefore`. score < `criticRubricFloor` && tier == 2 → 반복.
|
||||
2. rubric 기반 prompt로 LLM 호출 → 점수 + 개선안.
|
||||
3. `revise()` 1회. 다시 PRM. `prmScoreAfter - prmScoreBefore < δ`면 abort.
|
||||
4. `iterations <= maxIters` (default 2). 결과 trace에 기록.
|
||||
5. PRM이 `abstainFloor` 미만이면 `[NO_RESPONSE]` 반환 (Paper B 통합).
|
||||
|
||||
**Tier 적용**: tier 2만. tier 0/1은 기존 1-shot critic 유지.
|
||||
|
||||
**deadline 강제**: 매 iteration 시작 시 `Date.now() < deadlineMs` 체크. 초과면 즉시 반환.
|
||||
|
||||
**Acceptance**:
|
||||
- [ ] tier 2 slice에서 LLM judge accuracy +0.3
|
||||
- [ ] critic 평균 iterations 2 이하, p99 latency +400ms 이하
|
||||
|
||||
---
|
||||
|
||||
### Phase γ Exit 게이트
|
||||
| 메트릭 | 목표 |
|
||||
|---|---|
|
||||
| 자동 propose-deploy 주기 | weekly 1+ variant T2 자동 승급 |
|
||||
| Tier2 PRM rubric score | +0.3 이상 |
|
||||
| 누적 cost (γ 종료) | baseline 대비 −15~20% |
|
||||
|
||||
---
|
||||
|
||||
## 8. 평가 시스템 통합 (변경별)
|
||||
|
||||
| 변경 | shadow-bus | aggregator slice | tournament | drift | promote |
|
||||
|---|---|---|---|---|---|
|
||||
| #2 Abstention | `decision.reason`/`action` | abstention rate | — | abstention drift | abstention-mismatch |
|
||||
| #8a Tool Recovery | `errorKind` in trace | tool failure rate | — | tool error drift | tool-failure |
|
||||
| #4a Programmatic | `toolPlan` | tool success rate | plan-mode vs free | tool round-trip | tool-failure |
|
||||
| #1 SKILL.md | `disclosureMode` | system token usage | L1L2L3 vs flat | — | regression |
|
||||
| #5 PRM | trace 그대로 | PRM score column | PRM-aug vs raw | PRM score drift | rule-prm-disagree |
|
||||
| #3 Router | `routingDecision` | tier mix | router-on vs off | tier-mix drift | wrong-router |
|
||||
| #6 Memory | `userProfileLoadedAt` | 재방문 user slice | with-mem vs without | memory hit | low-retention |
|
||||
| #7 Governance | `variantTrustTier` | tier별 quality | 승급 게이트 | demotion alert | T1 강등 |
|
||||
| #8b Self-Critic | `iterations`, `rubricScores` | tier2 cost | iter-1 vs iter-2 | critic loop drift | critic-loop-failure |
|
||||
|
||||
---
|
||||
|
||||
## 9. 검증 — End-to-End
|
||||
|
||||
### 개발 중
|
||||
```bash
|
||||
# 1. unit + integration test
|
||||
pnpm test
|
||||
|
||||
# 2. golden set 회귀
|
||||
pnpm run eval:run --input src/eval/golden/onboarding.jsonl
|
||||
# ruleJudge.score, llmJudge.overall regression < 0.05 확인
|
||||
|
||||
# 3. tournament (variant 등록 후)
|
||||
pnpm run eval:tournament --variants control,<new-variant>
|
||||
# ELO 차이 측정
|
||||
|
||||
# 4. drift (5분 tick)
|
||||
pnpm run eval:report --slice tier=0
|
||||
```
|
||||
|
||||
### 운영 검증 (각 Phase 종료 후 1주)
|
||||
- Aggregator dashboard: slice별 quality/cost/latency 추세
|
||||
- Drift 알람 false-positive 0 (변경 의도와 일치)
|
||||
- Promote candidates에 의미 있는 root cause 포함
|
||||
|
||||
### Rollback
|
||||
- 모든 신규 행동은 env flag 또는 `RuntimeFlagManifest` 뒤에 배치 → 즉시 OFF
|
||||
- shadow eval 단계에서 production 영향 0 (counterfactual 기록만)
|
||||
|
||||
---
|
||||
|
||||
## 10. 핵심 수정 파일 — 진입점 (Codex가 첫 PR에서 손댈 파일)
|
||||
|
||||
**Phase α 첫 PR (TASK-α-2-01 + TASK-α-FLAG-01)**:
|
||||
1. `src/skills/onboarding/runtime/abstention.ts` (신규)
|
||||
2. `src/skills/onboarding/runtime/orchestrator.ts` — abstention gate 진입
|
||||
3. `src/skills/onboarding/state/onboarding-state.ts` — `DerivedState.abstentionScore?` 추가
|
||||
4. `src/skills/onboarding/onboarding-templates.ts` — clarify 템플릿
|
||||
5. `src/skills/onboarding/runtime/trace.ts` — classify step에 `abstention?` 필드
|
||||
6. `src/skills/onboarding/runtime/runtime-flag-manifest.ts` (신규)
|
||||
7. `src/config.ts` — `AGENT_ABSTENTION_*` env 추가
|
||||
8. `src/skills/onboarding/runtime/abstention.test.ts` (신규)
|
||||
|
||||
**Phase α 두 번째 PR (TASK-α-8a-01)**:
|
||||
1. `src/tools/tool.ts` — `ToolErrorKind`, `ToolExecutionFailure`
|
||||
2. `src/skills/onboarding/runtime/tool-loop.ts` — retry/error 분류
|
||||
3. `src/skills/onboarding/runtime/trace.ts` — toolCalls output에 `errorKind?` 추가
|
||||
4. `src/skills/onboarding/runtime/tool-loop.test.ts` (신규)
|
||||
|
||||
**Phase α 세 번째 PR (TASK-α-4a-01)**:
|
||||
1. `src/skills/onboarding/runtime/planner-schema.ts` — `toolPlan?` 필드
|
||||
2. `src/skills/onboarding/runtime/tool-plan-runner.ts` (신규)
|
||||
3. `src/skills/onboarding/runtime/orchestrator.ts` — toolPlan 우선 분기
|
||||
4. `src/eval/proposals/planner-with-toolplan.json` (신규 variant)
|
||||
5. `src/eval/judges/process-judge.ts` — toolPlan consistency check
|
||||
6. `src/skills/onboarding/runtime/tool-plan-runner.test.ts` (신규)
|
||||
|
||||
**Phase β 핵심**:
|
||||
- `src/skills/skill-loader.ts`, `src/skills/onboarding/SKILL.md`, `src/skills/onboarding/resources/*.md`
|
||||
- `src/skills/onboarding/prompts/builder.ts` — SKILL.md mode
|
||||
- `src/eval/judges/prm.ts`, `src/eval/judges/attribution.ts`, `src/eval/judges/process-judge.ts`
|
||||
- `src/skills/onboarding/runtime/router.ts`, `src/skills/onboarding/state/derive.ts`, `src/llm/routing.ts`
|
||||
- `src/skills/onboarding/state/user-memory.ts`, `src/skills/onboarding/prompts/example-store.ts`
|
||||
|
||||
**Phase γ**:
|
||||
- `src/eval/governance/{gates,trust}.ts`
|
||||
- `src/eval/loop/propose.ts` (T1 entry)
|
||||
- `src/tools/{tool-search.ts,registry.ts}`
|
||||
- `src/skills/onboarding/runtime/critic.ts`
|
||||
|
||||
---
|
||||
|
||||
## 11. 위험 & 미해결 질문
|
||||
|
||||
### 위험 (mitigation 동반)
|
||||
1. **#2 abstention false-negative** → ξ=0.35 보수, in-conversation abstain 차단(turnIndex ≥ 2일 때 clarify 안 함), 24h shadow 우선.
|
||||
2. **#3 router 학습 데이터 편향** (현 정책 재현) → epsilon=0.05 exploration noise, 라벨 보강.
|
||||
3. **#5 PRM 초기 라벨 부족** → `EVAL_PRM_MIN_LABELS=500` 미만 시 explanation-only 모드(forward score 미노출).
|
||||
4. **#6 PII 누출** → `UserMemoryStore.update`에 anonymize wrapper 강제, audit job 매일 1회.
|
||||
5. **#1 SKILL.md 행동 변화** → 30일 long-soak, regression 시 `AGENT_SKILL_MD_MODE=false` 즉시 rollback.
|
||||
6. **#7 propose 속도 저하** → T1→T2 자동(G1+G4만 요구)으로 가속 trade-off.
|
||||
7. **#8b critic loop 폭주** → `AGENT_CRITIC_MAX_ITERATIONS=2` 강제, deadlineMs 체크.
|
||||
|
||||
### 미해결 질문 (구현 시작 전 사용자 확인 필요)
|
||||
- [ ] **현재 label-archive 누적 라벨 수**? PRM v1 위해 ≥ 500. 부족하면 review queue 가속을 Phase α에 추가.
|
||||
- [ ] **재방문 user rate** (chatroom 별 30일 동일 user turn 분포)? 메모리 ROI 산정.
|
||||
- [ ] **로컬 embedding infra** 추가 가능? (router v3, example-store v2 위해 Qwen-embed 64d). 외부 사용 가능?
|
||||
- [ ] **다음 skill 후보 명세** — discord-help · community-rules · identity-room 중 어떤 것이 먼저? SKILL.md L3 resources 설계 영향.
|
||||
|
||||
---
|
||||
|
||||
## 12. 작업 체크리스트 (codex가 PR 단위로 진행)
|
||||
|
||||
### Phase α (Week 1-2)
|
||||
- [x] PR-A1: TASK-α-2-01 (Hybrid Early Abstention) + TASK-α-FLAG-01 (RuntimeFlagManifest)
|
||||
- [x] PR-A2: TASK-α-8a-01 (Structured Tool Error Recovery)
|
||||
- [x] PR-A3: TASK-α-4a-01 (Programmatic Tool Calling 시범)
|
||||
- [ ] Phase α Exit 게이트 검증 (Section 5)
|
||||
|
||||
### Phase β (Week 3-5)
|
||||
- [x] PR-B1: TASK-β-1-01 (SKILL.md L1/L2/L3) — *skill 추가 결정에 따라 최우선*
|
||||
- [x] PR-B2: TASK-β-5-01 (PRM + Attribution)
|
||||
- [x] PR-B3: TASK-β-3-01 (Router v1 룰)
|
||||
- [x] PR-B4: TASK-β-6-01 (User Memory + Adaptive Few-shot)
|
||||
- [x] PR-B5: TASK-β-3-02 (Router v2 학습) — *PRM 라벨 충분 시*
|
||||
- [ ] Phase β Exit 게이트 검증
|
||||
|
||||
### Phase γ (Week 6+)
|
||||
- [x] PR-C1: TASK-γ-7-01 (Trust & Governance)
|
||||
- [x] PR-C2: TASK-γ-4b-01 (Tool Search Tool) — *skill/tool 증가 시점*
|
||||
- [x] PR-C3: TASK-γ-8b-01 (Multi-step Self-Critic)
|
||||
- [ ] Phase γ Exit 게이트 검증
|
||||
|
||||
### Verification Run Log
|
||||
- [x] 2026-05-13T06:35Z local static gates: `npm run typecheck`, `npm run lint`, `npm test` 통과 (43 files / 168 tests).
|
||||
- [x] 2026-05-13T06:02Z golden eval without LLM judge: passRate=1, ruleAverageScore=1, averageLatencyMs=1.4ms. Report: `eval-reports/2026-05-13T06-02-46-431Z.json`.
|
||||
- [x] 2026-05-13T06:04Z all-new-flags smoke eval without LLM judge: passRate=1, ruleAverageScore=1, averageLatencyMs=1.8ms. Flags: abstention, programmatic tool calling, SKILL.md mode, user memory, tool search, critic iterations=2, static router. Report: `eval-reports/2026-05-13T06-04-40-217Z.json`.
|
||||
- [x] 2026-05-13T06:33Z fixed OpenRouter `/api/v1` endpoint normalization to `/api/v1/chat/completions`; added `llm-client.test.ts`. `npm run typecheck`, `npm run lint`, targeted LLM client tests 통과.
|
||||
- [ ] 2026-05-13T06:03Z full golden eval with LLM judge: blocked/degraded by LLM endpoint health. cliproxy timed out, OpenRouter returned HTML instead of JSON, llama timed out intermittently. Report: `eval-reports/2026-05-13T06-03-54-205Z.json` (not accepted as a quality gate).
|
||||
- [ ] 2026-05-13T06:32Z full golden eval retry after URL fix: OpenRouter URL path is now correct, but gate is still blocked/degraded by provider health/model availability. cliproxy returned unknown-provider for the judge model, OpenRouter free models returned upstream 429 rate-limit, and many generation calls produced empty fallback responses. Report: `eval-reports/2026-05-13T06-32-45-317Z.json` (not accepted as a quality gate).
|
||||
- [ ] Aggregator/report/drift/tournament operational gates: blocked locally because `MONGODB_CONNECTION_STRING` is not available in current eval environment.
|
||||
|
||||
---
|
||||
|
||||
## 13. 비고
|
||||
|
||||
- 사용자가 highlight한 `src/llm/routing.ts:24-25` (`return [llamaFallbackModel]`) — 현 코드는 `provider === "llama"`일 때 단일 fallback. TASK-β-3-01에서 `selectModelsForProvider` 시그니처에 `routingDecision`을 inject하면 llama provider도 router의 `requiredTier`에 따라 모델 선택 가능 (현재는 단일 모델이라 effective change 0, multi-llama 환경 대비 hook).
|
||||
- Phase α만으로 measurable 효과: cost −10%·quality flat·latency p50 −10%.
|
||||
- 모든 PR은 `evaluation-lively-island.md`의 평가 인프라(shadow eval, tournament, drift)를 활용해 검증 가능.
|
||||
- Plan 원본(우선순위 분석·상세 트레이드오프)은 `~/.claude/plans/papers-goofy-plum.md`에 보관. 본 문서는 codex actionable view.
|
||||
@@ -0,0 +1,621 @@
|
||||
# Refactor: agent / skills / tools DX 개선 plan
|
||||
|
||||
> 한 번의 작업 세션으로 codex가 처음부터 끝까지 수행할 수 있도록 작성된 단일 PR plan.
|
||||
|
||||
---
|
||||
|
||||
## 목표
|
||||
|
||||
지금 구조는 컨셉상 "agent ⊃ skills ⊃ tools"인데 실제 코드가 다음과 같이 어긋나 있다.
|
||||
|
||||
1. `src/tools/builtins/`의 5개 tool은 전부 onboarding 전용인데도 글로벌 폴더에 위치
|
||||
2. tool 파일이 `@skills/onboarding/*`을 import (의존 방향이 거꾸로)
|
||||
3. `OnboardingSkill`이 모든 tool을 `createBuiltInToolRegistry().list()`로 받아 `selectToolsForDerived()`에서 **이름 문자열로** 필터 → 오타에 무방비
|
||||
4. `runtime/tool-loop.ts`는 generic LLM↔tool loop인데 onboarding 폴더 안에 갇혀 있음
|
||||
5. `Skill` 인터페이스가 `name/canHandle/handle` 3줄뿐 — 새 skill이 어떻게 자기 tool을 선언할지 가이드 없음
|
||||
6. skill의 의존성 조립이 `main.ts`에 노출 — skill 폴더에 entry factory가 없음
|
||||
|
||||
이 plan을 끝내면:
|
||||
|
||||
- onboarding-tool은 onboarding 폴더 안에서 self-contained
|
||||
- tool→skill의 역방향 import 0건
|
||||
- `selectToolsForDerived`가 tool 객체 직접 참조 (컴파일 타임 안전)
|
||||
- generic runtime은 `src/agent/runtime/`로 hoist
|
||||
- `Skill` 인터페이스에 `tools` 필드 추가
|
||||
- `createOnboardingSkill(deps)` factory 도입
|
||||
- `docs/skill-authoring.md`로 신규 skill/tool 추가 절차 문서화
|
||||
|
||||
---
|
||||
|
||||
## 최종 구조
|
||||
|
||||
```
|
||||
src/
|
||||
agent/
|
||||
agent.ts
|
||||
types.ts
|
||||
index.ts
|
||||
runtime/
|
||||
tool-loop.ts ← hoisted from skills/onboarding/runtime
|
||||
tool-loop.test.ts ← hoisted
|
||||
tools/
|
||||
tool.ts ← ToolContext에서 OnboardingSession 제거, generic param 추가
|
||||
registry.ts
|
||||
parser.ts
|
||||
parser.test.ts
|
||||
serializer.ts
|
||||
index.ts
|
||||
(builtins/ 폴더 삭제)
|
||||
skills/
|
||||
skill.ts ← tools: readonly Tool[] 추가
|
||||
onboarding/
|
||||
index.ts ← createOnboardingSkill(deps) factory export
|
||||
skill.ts ← tool을 직접 import, selectToolsForDerived 객체 참조
|
||||
session.ts
|
||||
types.ts
|
||||
constants.ts
|
||||
message-filter.ts
|
||||
onboarding-templates.ts
|
||||
tools/ ← NEW: onboarding 전용 tool 모음
|
||||
index.ts ← createOnboardingToolRegistry, ALL_TOOLS export
|
||||
context.ts ← OnboardingToolContext
|
||||
validate-nickname.ts
|
||||
check-onboarding-progress.ts
|
||||
check-onboarding-progress.test.ts
|
||||
lookup-community-rule.ts
|
||||
get-room-context.ts
|
||||
verify-discord-nickname.ts
|
||||
verify-discord-nickname.test.ts
|
||||
prompts/ ← 변경 없음
|
||||
runtime/ ← tool-loop만 빠짐
|
||||
orchestrator.ts ← import 경로 갱신
|
||||
orchestrator.test.ts
|
||||
critic.ts
|
||||
validator.ts
|
||||
validator.test.ts
|
||||
planner-schema.ts
|
||||
trace.ts
|
||||
state/ ← 변경 없음
|
||||
docs/
|
||||
skill-authoring.md ← NEW
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 변경 사항 상세
|
||||
|
||||
### 1. `src/tools/tool.ts` — ToolContext에서 onboarding 의존성 제거 + Tool generic화
|
||||
|
||||
**before**
|
||||
|
||||
```ts
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import type { NatsClient } from "@common/nats";
|
||||
import type { RoomContextService } from "@room/room-context-service";
|
||||
import type { ZodType } from "zod";
|
||||
import type { OnboardingSession } from "@skills/onboarding/types";
|
||||
|
||||
export interface ToolContext {
|
||||
chatroomId?: string | undefined;
|
||||
natsClient?: Pick<NatsClient, "request"> | undefined;
|
||||
userId?: string | undefined;
|
||||
session?: OnboardingSession | null | undefined;
|
||||
garnetClient?: GarnetClient | undefined;
|
||||
roomContextService?: RoomContextService | undefined;
|
||||
}
|
||||
|
||||
export interface Tool<A, R> {
|
||||
name: string;
|
||||
description: string;
|
||||
argsSchema: ZodType<A>;
|
||||
resultSchema: ZodType<R>;
|
||||
execute(args: A, ctx: ToolContext): Promise<R>;
|
||||
}
|
||||
```
|
||||
|
||||
**after**
|
||||
|
||||
```ts
|
||||
import type { GarnetClient } from "@common/garnet";
|
||||
import type { NatsClient } from "@common/nats";
|
||||
import type { RoomContextService } from "@room/room-context-service";
|
||||
import type { ZodType } from "zod";
|
||||
|
||||
export interface ToolContext {
|
||||
chatroomId?: string | undefined;
|
||||
natsClient?: Pick<NatsClient, "request"> | undefined;
|
||||
userId?: string | undefined;
|
||||
garnetClient?: GarnetClient | undefined;
|
||||
roomContextService?: RoomContextService | undefined;
|
||||
}
|
||||
|
||||
export interface Tool<A, R, C extends ToolContext = ToolContext> {
|
||||
name: string;
|
||||
description: string;
|
||||
argsSchema: ZodType<A>;
|
||||
resultSchema: ZodType<R>;
|
||||
execute(args: A, ctx: C): Promise<R>;
|
||||
}
|
||||
```
|
||||
|
||||
`@skills/onboarding/types` import 한 줄과 `session` 필드 한 줄을 삭제, `Tool`에 generic `C` 추가. default를 `ToolContext`로 두면 기존 `Tool<A, R>` 호출도 그대로 유효.
|
||||
|
||||
### 2. `src/skills/onboarding/tools/context.ts` — 신규 파일
|
||||
|
||||
```ts
|
||||
import type { ToolContext } from "@tools/tool";
|
||||
import type { OnboardingSession } from "../types.js";
|
||||
|
||||
export interface OnboardingToolContext extends ToolContext {
|
||||
session?: OnboardingSession | null | undefined;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. tool 5개 + test 2개 이동
|
||||
|
||||
git mv로 파일을 옮기고, 옮긴 파일의 내부 import 경로만 수정.
|
||||
|
||||
| from | to |
|
||||
|---|---|
|
||||
| `src/tools/builtins/validate-nickname.ts` | `src/skills/onboarding/tools/validate-nickname.ts` |
|
||||
| `src/tools/builtins/check-onboarding-progress.ts` | `src/skills/onboarding/tools/check-onboarding-progress.ts` |
|
||||
| `src/tools/builtins/check-onboarding-progress.test.ts` | `src/skills/onboarding/tools/check-onboarding-progress.test.ts` |
|
||||
| `src/tools/builtins/lookup-community-rule.ts` | `src/skills/onboarding/tools/lookup-community-rule.ts` |
|
||||
| `src/tools/builtins/get-room-context.ts` | `src/skills/onboarding/tools/get-room-context.ts` |
|
||||
| `src/tools/builtins/verify-discord-nickname.ts` | `src/skills/onboarding/tools/verify-discord-nickname.ts` |
|
||||
| `src/tools/builtins/verify-discord-nickname.test.ts` | `src/skills/onboarding/tools/verify-discord-nickname.test.ts` |
|
||||
| `src/tools/builtins/index.ts` | (덮어쓰기, 아래 #4 참고) |
|
||||
|
||||
각 파일에서 import 경로를 다음 규칙으로 갱신:
|
||||
|
||||
- `import type { Tool, ToolContext } from "../tool.js";`
|
||||
→ `import type { Tool } from "@tools/tool";`
|
||||
→ `import type { OnboardingToolContext } from "./context.js";`
|
||||
- `from "@skills/onboarding/onboarding-templates"` → `from "../onboarding-templates.js"`
|
||||
- `from "@skills/onboarding/constants"` → `from "../constants.js"`
|
||||
- `from "@skills/onboarding/types"` → `from "../types.js"`
|
||||
- `from "@skills/onboarding/session"` → `from "../session.js"`
|
||||
- `from "@skills/onboarding/state/progress"` → `from "../state/progress.js"`
|
||||
- `from "../../config.js"` → `from "../../../config.js"` (한 단계 깊어짐)
|
||||
- 테스트 파일도 동일한 규칙 + 새 위치 기준으로 sibling import 경로 사용
|
||||
|
||||
각 tool의 export 시그니처를 `Tool<Args, Result>` → `Tool<Args, Result, OnboardingToolContext>`로 변경. `ctx` 파라미터를 사용하는 함수(`persistDiscordMemberId(memberId, ctx)` 등) 내부 타입도 맞춰서 `OnboardingToolContext`로 갱신.
|
||||
|
||||
### 4. `src/skills/onboarding/tools/index.ts` — 신규 (구 `tools/builtins/index.ts` 대체)
|
||||
|
||||
```ts
|
||||
import type { Tool } from "@tools/tool";
|
||||
import { ToolRegistry } from "@tools/registry";
|
||||
import type { OnboardingToolContext } from "./context.js";
|
||||
import { checkOnboardingProgressTool } from "./check-onboarding-progress.js";
|
||||
import { getRoomContextTool } from "./get-room-context.js";
|
||||
import { lookupCommunityRuleTool } from "./lookup-community-rule.js";
|
||||
import { validateNicknameTool } from "./validate-nickname.js";
|
||||
import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js";
|
||||
|
||||
export const onboardingTools = {
|
||||
validateNickname: validateNicknameTool,
|
||||
checkOnboardingProgress: checkOnboardingProgressTool,
|
||||
lookupCommunityRule: lookupCommunityRuleTool,
|
||||
getRoomContext: getRoomContextTool,
|
||||
verifyDiscordNickname: verifyDiscordNicknameTool,
|
||||
} as const;
|
||||
|
||||
export const onboardingToolList: readonly Tool<unknown, unknown, OnboardingToolContext>[] = [
|
||||
validateNicknameTool,
|
||||
checkOnboardingProgressTool,
|
||||
lookupCommunityRuleTool,
|
||||
getRoomContextTool,
|
||||
verifyDiscordNicknameTool,
|
||||
];
|
||||
|
||||
export function createOnboardingToolRegistry(): ToolRegistry {
|
||||
return new ToolRegistry()
|
||||
.register(validateNicknameTool)
|
||||
.register(checkOnboardingProgressTool)
|
||||
.register(lookupCommunityRuleTool)
|
||||
.register(getRoomContextTool)
|
||||
.register(verifyDiscordNicknameTool);
|
||||
}
|
||||
|
||||
export {
|
||||
checkOnboardingProgressTool,
|
||||
getRoomContextTool,
|
||||
lookupCommunityRuleTool,
|
||||
validateNicknameTool,
|
||||
verifyDiscordNicknameTool,
|
||||
};
|
||||
export type { OnboardingToolContext } from "./context.js";
|
||||
```
|
||||
|
||||
### 5. 빈 `src/tools/builtins/` 폴더 삭제
|
||||
|
||||
```bash
|
||||
rm -rf src/tools/builtins
|
||||
```
|
||||
|
||||
### 6. `src/skills/onboarding/skill.ts` — tool 객체 직접 참조
|
||||
|
||||
다음 import를 추가:
|
||||
|
||||
```ts
|
||||
import {
|
||||
checkOnboardingProgressTool,
|
||||
lookupCommunityRuleTool,
|
||||
onboardingToolList,
|
||||
validateNicknameTool,
|
||||
verifyDiscordNicknameTool,
|
||||
type OnboardingToolContext,
|
||||
} from './tools/index.js';
|
||||
```
|
||||
|
||||
기존:
|
||||
|
||||
```ts
|
||||
import { createBuiltInToolRegistry } from '@tools/builtins/index';
|
||||
import type { Tool, ToolContext } from '@tools/tool';
|
||||
```
|
||||
|
||||
→ 다음으로 변경:
|
||||
|
||||
```ts
|
||||
import type { Tool } from '@tools/tool';
|
||||
```
|
||||
|
||||
(`ToolContext` 사용처는 모두 `OnboardingToolContext`로 교체)
|
||||
|
||||
생성자 내부:
|
||||
|
||||
```ts
|
||||
this.tools = createBuiltInToolRegistry().list();
|
||||
```
|
||||
|
||||
→
|
||||
|
||||
```ts
|
||||
this.tools = onboardingToolList;
|
||||
```
|
||||
|
||||
`tools` 필드 타입을 `readonly Tool<unknown, unknown, OnboardingToolContext>[]`로 변경.
|
||||
|
||||
`buildToolContext(...)` 반환 타입을 `ToolContext` → `OnboardingToolContext`.
|
||||
|
||||
`generateLlmText` 시그니처 옵션의 `toolContext?: ToolContext | undefined` → `OnboardingToolContext | undefined`. `tools?: readonly Tool<unknown, unknown>[] | undefined` → `readonly Tool<unknown, unknown, OnboardingToolContext>[] | undefined`.
|
||||
|
||||
핵심: `selectToolsForDerived`를 객체 참조로 다시 작성:
|
||||
|
||||
```ts
|
||||
private selectToolsForDerived(
|
||||
derived: DerivedState,
|
||||
): readonly Tool<unknown, unknown, OnboardingToolContext>[] {
|
||||
if (derived.intent.kind === 'discord-verify-question') {
|
||||
return [verifyDiscordNicknameTool];
|
||||
}
|
||||
|
||||
if (derived.phase.kind === 'nickname-rejected') {
|
||||
return [
|
||||
validateNicknameTool,
|
||||
lookupCommunityRuleTool,
|
||||
checkOnboardingProgressTool,
|
||||
];
|
||||
}
|
||||
|
||||
if (derived.intent.kind === 'status-question') {
|
||||
return [checkOnboardingProgressTool];
|
||||
}
|
||||
|
||||
if (derived.intent.kind === 'discord-question') {
|
||||
return [lookupCommunityRuleTool, verifyDiscordNicknameTool];
|
||||
}
|
||||
|
||||
return this.tools;
|
||||
}
|
||||
```
|
||||
|
||||
문자열 매칭(`tool.name === '...'`) 전부 제거. tool 이름 변경/삭제 시 컴파일 에러로 잡힌다.
|
||||
|
||||
마지막으로 클래스 상단에 `Skill` 인터페이스의 `tools` 필드를 노출:
|
||||
|
||||
```ts
|
||||
get tools(): readonly Tool<unknown, unknown>[] {
|
||||
return onboardingToolList as readonly Tool<unknown, unknown>[];
|
||||
}
|
||||
```
|
||||
|
||||
(또는 그냥 public 필드로 두어도 됨. 테스트 깨지지 않게 getter 권장.)
|
||||
|
||||
### 7. `src/skills/skill.ts` — 인터페이스에 tools 추가
|
||||
|
||||
```ts
|
||||
import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types";
|
||||
import type { Tool } from "@tools/tool";
|
||||
|
||||
export interface Skill {
|
||||
readonly name: string;
|
||||
readonly tools: readonly Tool<unknown, unknown>[];
|
||||
canHandle(request: AgentRequest): boolean;
|
||||
handle(
|
||||
request: AgentRequest,
|
||||
conversationHistory: ConversationMessage[],
|
||||
): Promise<AgentResponse>;
|
||||
}
|
||||
```
|
||||
|
||||
### 8. `src/agent/runtime/tool-loop.ts` — hoist
|
||||
|
||||
`src/skills/onboarding/runtime/tool-loop.ts` → `src/agent/runtime/tool-loop.ts`로 이동.
|
||||
`src/skills/onboarding/runtime/tool-loop.test.ts` → `src/agent/runtime/tool-loop.test.ts`로 이동.
|
||||
|
||||
이동 후 import 경로 점검:
|
||||
- `import { parseToolCalls } from "@tools/parser";` 그대로 유효
|
||||
- `import type { Tool, ToolContext } from "@tools/tool";` 그대로 유효
|
||||
- `import { getActiveProcessTrace } from "./trace.js";` →
|
||||
- 결정 사항: `trace.ts`는 onboarding 전용이므로 hoist하지 않는다.
|
||||
- tool-loop가 trace 의존성을 가지면 안 됨. 따라서 **trace 호출을 옵션 콜백으로 일반화**:
|
||||
|
||||
`tool-loop.ts` 변경:
|
||||
|
||||
```ts
|
||||
export interface ToolLoopOptions {
|
||||
// ...기존...
|
||||
onToolCallStart?: (call: { name: string; args: unknown }) => {
|
||||
finish: (result: { ok: boolean; resultSummary: string }) => void;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
내부에서 `getActiveProcessTrace()?.startStep('tool-call')` 호출하던 자리를 `options.onToolCallStart?.(...)` 호출로 대체.
|
||||
|
||||
orchestrator(onboarding 전용)에서 `runWithTools` 호출 시 `onToolCallStart` 콜백을 주입:
|
||||
|
||||
```ts
|
||||
import { runWithTools } from "@agent/runtime/tool-loop";
|
||||
// ...
|
||||
return runWithTools({
|
||||
// ...기존 옵션...
|
||||
onToolCallStart: ({ name, args }) => {
|
||||
const step = getActiveProcessTrace()?.startStep('tool-call');
|
||||
return {
|
||||
finish: ({ ok, resultSummary }) => {
|
||||
step?.finish({ args, name, ok, resultSummary });
|
||||
},
|
||||
};
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
orchestrator.ts에서:
|
||||
|
||||
```ts
|
||||
import { runWithTools } from "./tool-loop.js";
|
||||
```
|
||||
|
||||
→
|
||||
|
||||
```ts
|
||||
import { runWithTools } from "@agent/runtime/tool-loop";
|
||||
```
|
||||
|
||||
`ToolContext` import도 마찬가지로 그대로.
|
||||
|
||||
`tool-loop.test.ts`도 mock 시나리오 점검 — trace 의존성 사라졌으므로 테스트는 단순화 가능하지만, 기능 회귀가 없다면 **테스트는 import 경로만 바꾸고 기존 시나리오 유지**.
|
||||
|
||||
### 9. `src/skills/onboarding/index.ts` — factory export
|
||||
|
||||
기존 (3줄짜리 re-export):
|
||||
|
||||
```ts
|
||||
export { OnboardingSkill } from './skill.js';
|
||||
export type { OnboardingSession } from './types.js';
|
||||
```
|
||||
|
||||
추가:
|
||||
|
||||
```ts
|
||||
import type { GarnetClient } from '@common/garnet';
|
||||
import type { NatsClient } from '@common/nats';
|
||||
import type { LlmClient } from '@llm/llm-client';
|
||||
import type { RoomContextService } from '@room/room-context-service';
|
||||
import type { ShadowEvalPublisher } from '@eval/shadow-bus';
|
||||
import { OnboardingSkill } from './skill.js';
|
||||
|
||||
export interface CreateOnboardingSkillOptions {
|
||||
garnetClient: GarnetClient;
|
||||
llmClient: LlmClient;
|
||||
roomContextService?: RoomContextService;
|
||||
shadowEvalPublisher?: ShadowEvalPublisher;
|
||||
natsClient?: Pick<NatsClient, 'request'>;
|
||||
}
|
||||
|
||||
export function createOnboardingSkill(opts: CreateOnboardingSkillOptions): OnboardingSkill {
|
||||
return new OnboardingSkill(
|
||||
opts.garnetClient,
|
||||
opts.llmClient,
|
||||
opts.roomContextService,
|
||||
opts.shadowEvalPublisher,
|
||||
opts.natsClient,
|
||||
);
|
||||
}
|
||||
|
||||
export { OnboardingSkill } from './skill.js';
|
||||
export type { OnboardingSession } from './types.js';
|
||||
```
|
||||
|
||||
`OnboardingSkill` 클래스의 생성자 시그니처는 건드리지 않는다 (eval/runner.ts가 직접 생성하는 곳이 있어 호환 유지).
|
||||
|
||||
### 10. `src/main.ts` — factory 사용
|
||||
|
||||
기존 `src/main.ts:218-229`:
|
||||
|
||||
```ts
|
||||
const agent = new Agent(natsClient, conversationStore);
|
||||
const shadowEvalBus = new ShadowEvalBus(garnetClient);
|
||||
const onboardingSkill = new OnboardingSkill(
|
||||
garnetClient,
|
||||
llmClient,
|
||||
roomContextService,
|
||||
shadowEvalBus,
|
||||
natsClient,
|
||||
);
|
||||
agent.registerSkill(onboardingSkill);
|
||||
```
|
||||
|
||||
→
|
||||
|
||||
```ts
|
||||
const agent = new Agent(natsClient, conversationStore);
|
||||
const shadowEvalBus = new ShadowEvalBus(garnetClient);
|
||||
const onboardingSkill = createOnboardingSkill({
|
||||
garnetClient,
|
||||
llmClient,
|
||||
roomContextService,
|
||||
shadowEvalPublisher: shadowEvalBus,
|
||||
natsClient,
|
||||
});
|
||||
agent.registerSkill(onboardingSkill);
|
||||
```
|
||||
|
||||
import 변경:
|
||||
|
||||
```ts
|
||||
import { OnboardingSkill } from '@skills/onboarding/index';
|
||||
```
|
||||
→
|
||||
```ts
|
||||
import { createOnboardingSkill } from '@skills/onboarding/index';
|
||||
```
|
||||
|
||||
### 11. `src/eval/judges/process-judge.ts` — registry import 경로 갱신
|
||||
|
||||
```ts
|
||||
import { createBuiltInToolRegistry } from "@tools/builtins/index";
|
||||
```
|
||||
→
|
||||
```ts
|
||||
import { createOnboardingToolRegistry } from "@skills/onboarding/tools/index";
|
||||
```
|
||||
|
||||
호출부 `createBuiltInToolRegistry()` → `createOnboardingToolRegistry()`로 일괄 변경.
|
||||
|
||||
### 12. `src/eval/runner.ts` — 변경 없음 권장
|
||||
|
||||
`new OnboardingSkill(...)` 직접 호출 부분은 그대로 둔다 (factory만 main.ts에서 사용). 호환성 유지를 위해 클래스도 계속 export.
|
||||
|
||||
### 13. 그 외 영향받는 import 점검 (grep으로 확인)
|
||||
|
||||
다음 패턴이 남아 있으면 안 됨:
|
||||
- `@tools/builtins` (모두 `@skills/onboarding/tools` 또는 직접 import로 교체)
|
||||
- tool 파일 안의 `@skills/onboarding/*` (모두 relative `../...`로 교체)
|
||||
- `tool.name === '...'` 형태의 문자열 매칭 (객체 참조로 교체)
|
||||
|
||||
검증 명령:
|
||||
```bash
|
||||
grep -rn "@tools/builtins" src
|
||||
# → 결과 0건이어야 함
|
||||
|
||||
grep -n "from \"@skills/onboarding" src/skills/onboarding/tools
|
||||
# → 결과 0건 (tool 파일이 자기 skill을 alias로 import 금지)
|
||||
|
||||
grep -n "tool.name ===" src/skills
|
||||
# → 결과 0건
|
||||
```
|
||||
|
||||
### 14. `docs/skill-authoring.md` — 신규 가이드
|
||||
|
||||
```markdown
|
||||
# Skill / Tool 추가 가이드
|
||||
|
||||
## 새 tool 추가
|
||||
1. `src/skills/<your-skill>/tools/<tool-name>.ts` 생성.
|
||||
2. `Tool<Args, Result, YourSkillToolContext>` 형태로 export.
|
||||
3. `src/skills/<your-skill>/tools/index.ts`의 `onboardingToolList` 같은 배열에 등록.
|
||||
4. skill 파일에서 직접 import해 `selectToolsForDerived`(또는 동등한 메서드)에 객체로 추가.
|
||||
5. tool은 절대 `@skills/...` alias로 다른 skill을 import하지 않는다 (relative import만 허용).
|
||||
|
||||
## 새 skill 추가
|
||||
1. `src/skills/<your-skill>/` 폴더 생성.
|
||||
2. `Skill` 인터페이스(`src/skills/skill.ts`) 구현 — 최소한 `name`, `tools`, `canHandle`, `handle`.
|
||||
3. `tools/` 서브폴더에 자기 tool 모음과 `<YourSkill>ToolContext extends ToolContext`.
|
||||
4. `index.ts`에 `create<YourSkill>Skill(opts)` factory 추가.
|
||||
5. `src/main.ts`의 bootstrap에서 factory 호출 후 `agent.registerSkill(...)`.
|
||||
6. LLM↔tool 루프가 필요하면 `@agent/runtime/tool-loop`의 `runWithTools` 재사용.
|
||||
|
||||
## 어디를 보면 되나
|
||||
- agent 디스패처: `src/agent/agent.ts`
|
||||
- skill 인터페이스: `src/skills/skill.ts`
|
||||
- generic tool 인터페이스: `src/tools/tool.ts`
|
||||
- generic LLM↔tool 루프: `src/agent/runtime/tool-loop.ts`
|
||||
- onboarding skill 구현: `src/skills/onboarding/`
|
||||
- onboarding tool 모음: `src/skills/onboarding/tools/`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 실행 순서 (codex가 그대로 따라가도록)
|
||||
|
||||
각 단계는 끝나면 다음 단계로 넘어가기 전에 typecheck를 돌릴 수 있다 (선택).
|
||||
|
||||
1. **`src/tools/tool.ts` 수정**: `OnboardingSession` import 제거, `session` 필드 제거, `Tool`에 generic `C extends ToolContext = ToolContext` 추가.
|
||||
2. **새 폴더 생성**: `src/skills/onboarding/tools/`, `src/agent/runtime/`.
|
||||
3. **`src/skills/onboarding/tools/context.ts` 작성** (위 #2 내용).
|
||||
4. **tool 5개 + test 2개 이동** (`git mv`로). 각 파일 import 경로 갱신 + 시그니처 `Tool<A, R, OnboardingToolContext>`로 변경.
|
||||
5. **`src/skills/onboarding/tools/index.ts` 작성** (위 #4 내용).
|
||||
6. **`src/tools/builtins/` 삭제**: `rm -rf src/tools/builtins` (이미 모두 옮겼는지 ls로 확인).
|
||||
7. **tool-loop hoist**: `git mv src/skills/onboarding/runtime/tool-loop.ts src/agent/runtime/tool-loop.ts` (test도). trace 의존성을 `onToolCallStart` 콜백으로 일반화.
|
||||
8. **`src/skills/onboarding/runtime/orchestrator.ts` 갱신**: `runWithTools` import 경로를 `@agent/runtime/tool-loop`로 변경, `onToolCallStart` 콜백으로 trace 주입.
|
||||
9. **`src/skills/skill.ts` 인터페이스 확장**: `tools: readonly Tool[]` 추가.
|
||||
10. **`src/skills/onboarding/skill.ts` 갱신**:
|
||||
- `@tools/builtins/index` import 제거.
|
||||
- 개별 tool import 추가.
|
||||
- `this.tools = onboardingToolList`.
|
||||
- `selectToolsForDerived`를 객체 참조로 재작성.
|
||||
- `ToolContext` 사용처를 `OnboardingToolContext`로 교체.
|
||||
- `tools` getter 노출.
|
||||
11. **`src/skills/onboarding/index.ts`에 factory 추가** (위 #9 내용).
|
||||
12. **`src/main.ts` 갱신** (위 #10 내용).
|
||||
13. **`src/eval/judges/process-judge.ts` import 경로 갱신** (위 #11 내용).
|
||||
14. **`docs/skill-authoring.md` 작성** (위 #14 내용).
|
||||
15. **검증**:
|
||||
```bash
|
||||
grep -rn "@tools/builtins" src # 0건
|
||||
grep -rn "tool.name ===" src/skills # 0건
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run test
|
||||
```
|
||||
셋 다 통과하면 완료.
|
||||
|
||||
---
|
||||
|
||||
## 위험 요소 및 대응
|
||||
|
||||
| 위험 | 대응 |
|
||||
|---|---|
|
||||
| `Tool<A, R>`의 default generic이 `ToolContext`라서 기존 호출부가 `OnboardingToolContext` 필드(`session`)를 못 읽을 수 있음 | onboarding 안의 모든 사용처를 `Tool<..., OnboardingToolContext>`로 명시적 선언. tool-loop는 generic하게 받으므로 무관. |
|
||||
| `selectToolsForDerived`가 `readonly Tool<unknown, unknown, OnboardingToolContext>[]`를 반환하는데 `generateLlmText` 옵션이 `Tool<unknown, unknown>[]`를 받으면 covariance 문제 발생 가능 | `generateLlmText`/`orchestrator.run`/`runWithTools`까지 일관되게 `OnboardingToolContext`로 흘려준다. tool-loop는 `Tool<unknown, unknown, C>` generic으로 받도록 수정. |
|
||||
| trace 호출을 콜백으로 빼면서 누락이 생길 수 있음 | `tool-loop.test.ts`에 "콜백이 ok=true/false 둘 다에서 호출되는지" 테스트 한두 개 추가. |
|
||||
| `eval/runner.ts`의 `new OnboardingSkill(...)`가 ctor 시그니처 의존 | ctor는 건드리지 않으므로 회귀 없음. |
|
||||
| import 깊이가 한 단계 늘어나는 케이스 (`../../../config.js`) | 그대로 두거나, 필요하면 `@config` alias 신설. 본 plan에선 alias 추가 안 함. |
|
||||
| pre-commit hook이 lint/format을 강제할 수 있음 | 마지막에 `npm run lint:fix && npm run format` 한 번 실행. |
|
||||
|
||||
---
|
||||
|
||||
## 비목표 (이번 PR에서 안 함)
|
||||
|
||||
- `src/skills/onboarding/runtime/orchestrator.ts`의 onboarding-specific planner를 generic화하는 작업 (별도 작업)
|
||||
- `prompts/tool-policy.ts`의 자연어 정책을 코드 정책으로 통합 (별도)
|
||||
- 두 번째 skill 추가
|
||||
- `ToolRegistry` API 단순화 (`pick(names)` 제거 등)
|
||||
|
||||
---
|
||||
|
||||
## 검증 체크리스트
|
||||
|
||||
- [ ] `grep -rn "@tools/builtins" src` → 0건
|
||||
- [ ] `grep -rn "from \"@skills/onboarding" src/skills/onboarding/tools` → 0건 (relative만)
|
||||
- [ ] `grep -n "tool.name ===" src/skills/onboarding/skill.ts` → 0건
|
||||
- [ ] `npm run typecheck` 통과
|
||||
- [ ] `npm run lint` 통과
|
||||
- [ ] `npm run test` 통과 (특히 `tool-loop.test.ts`, `check-onboarding-progress.test.ts`, `verify-discord-nickname.test.ts`)
|
||||
- [ ] `npm run build` 통과
|
||||
- [ ] `docs/skill-authoring.md` 존재
|
||||
@@ -0,0 +1,31 @@
|
||||
INFISICAL_PROJECT_ID=29eecc1e-7bdc-40b9-8ecd-5e5079af1483
|
||||
|
||||
SERVICE_NAME=lolympus-agent
|
||||
VERSION=0.1
|
||||
|
||||
DISCORD_ONBOARDING_GUILD_ID=923108442330234880
|
||||
DISCORD_ONBOARDING_ROLE_ID=1447892610000879688
|
||||
|
||||
ONBOARDING_TIMEOUT_MINUTES=30
|
||||
AGENT_REQUEST_TIMEOUT_MS=15000
|
||||
ONBOARDING_HEART_CHECK_API_URL=https://121.88.139.49:9000/
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
|
||||
CLI_PROXY_API_URLS=http://126.dahyeon.us:8317
|
||||
CLI_PROXY_LLM_MODEL=gpt-5.3-codex-spark
|
||||
|
||||
LLAMA_SERVER_API_URL=https://121.88.139.49:9000/
|
||||
LLAMA_SERVER_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzb3VyY2UiOiJkYWh5ZW9uLnVzIn0.v-ZewXTKnOfZO4mdSIDxAofIPs4bDAjbP2OQ_BhAFc4
|
||||
|
||||
LAST_SEEN_REPORT_TIME_ZONE=Asia/Seoul
|
||||
LAST_SEEN_REPORT_CHANNEL_ID=1484235496799469708
|
||||
|
||||
OPENROUTER_API_URL=https://openrouter.ai/api/v1
|
||||
OPENROUTER_API_KEY=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
|
||||
OPENROUTER_MODEL=google/gemma-4-26b-a4b-it:free,google/gemma-4-31b-it:free
|
||||
|
||||
RIOT_API_KEY=RGAPI-9f49e888-98aa-4a71-be2e-4a189d140989
|
||||
# Uncomment temporarily to send historical daily last-seen reports on startup.
|
||||
#LAST_SEEN_REPORT_BACKFILL_DAYS=7
|
||||
|
||||
LLM_JUDGE_MODEL=gpt-5.5
|
||||
@@ -1,152 +0,0 @@
|
||||
# Copy this file to env-vars/dev.env, env-vars/test.env, or env-vars/prod.env.
|
||||
# Keep real values out of git.
|
||||
|
||||
NODE_ENV=dev
|
||||
SERVICE_NAME=lolympus-agent
|
||||
VERSION=0.1
|
||||
LOG_LEVEL=trace
|
||||
|
||||
# Core infrastructure
|
||||
NATS_ENDPOINT=
|
||||
NATS_TOKEN=
|
||||
REDIS_URL=
|
||||
MONGODB_CONNECTION_STRING=
|
||||
MONGODB_PROJECT_ID=
|
||||
INFISICAL_PROJECT_ID=
|
||||
INFISICAL_CLIENT_ID=
|
||||
INFISICAL_CLIENT_SECRET=
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=
|
||||
|
||||
# Discord / onboarding
|
||||
DISCORD_INVITE_URL=
|
||||
DISCORD_ONBOARDING_GUILD_ID=
|
||||
DISCORD_ONBOARDING_ROLE_ID=
|
||||
DISCORD_MEMBER_LOOKUP_SUBJECT=lolympus.discord.lookup-members
|
||||
DISCORD_VERIFY_TIMEOUT_MS=2500
|
||||
ONBOARDING_SESSION_KEY_PREFIX=lolympus
|
||||
ONBOARDING_TIMEOUT_MINUTES=30
|
||||
ONBOARDING_HEART_CHECK_API_URL=
|
||||
DEADLINE_NEAR_THRESHOLD_MIN=30
|
||||
ESCALATION_BUDGET_PER_TURN=2
|
||||
LAST_SEEN_REPORT_TIME_ZONE=Asia/Seoul
|
||||
LAST_SEEN_REPORT_CHANNEL_ID=
|
||||
LAST_SEEN_REPORT_BACKFILL_DAYS=
|
||||
RIOT_API_KEY=
|
||||
|
||||
# Agent runtime
|
||||
AGENT_REQUEST_SUBJECT=lolympus-agent.request
|
||||
AGENT_REQUEST_TIMEOUT_MS=5000
|
||||
MAX_CONVERSATION_MESSAGES=20
|
||||
CONVERSATION_TTL_SECONDS=43200
|
||||
CONVERSATION_SUMMARY_TTL_SEC=86400
|
||||
BLACKBOARD_TTL_SEC=43200
|
||||
MAX_RESPONSE_LENGTH=600
|
||||
ROOM_CONTEXT_LIMIT=8
|
||||
|
||||
# LLM providers
|
||||
CLI_PROXY_API_URLS=
|
||||
CLI_PROXY_API_KEY=
|
||||
CLI_PROXY_LLM_MODEL=gpt-5.3-codex-spark
|
||||
AGENT_LLM_API_URLS=
|
||||
AGENT_LLM_API_KEY=
|
||||
AGENT_LLM_MODEL=
|
||||
LLAMA_SERVER_API_URL=
|
||||
LLAMA_SERVER_API_KEY=
|
||||
OPENROUTER_API_URL=https://openrouter.ai/api/v1
|
||||
OPENROUTER_API_KEY=
|
||||
OPENROUTER_MODEL=openai/gpt-5.3-codex-spark
|
||||
|
||||
# LLM behavior
|
||||
LLM_REQUEST_TIMEOUT_MS=30000
|
||||
LLM_HEALTH_TIMEOUT_MS=5000
|
||||
LLM_HEALTH_CACHE_TTL_MS=30000
|
||||
LLM_CIRCUIT_FAILURE_THRESHOLD=3
|
||||
LLM_CIRCUIT_COOLDOWN_MS=60000
|
||||
LLM_MAX_TOKENS=768
|
||||
LLM_TEMPERATURE=0.55
|
||||
CLASSIFIER_MAX_TOKENS=16
|
||||
TIER0_MODEL=
|
||||
TIER1_PLANNER_MODEL=
|
||||
TIER1_RESPONDER_MODEL=
|
||||
TIER2_CRITIC_MODEL=
|
||||
TIER0_MAX_TOKENS=384
|
||||
TIER1_MAX_TOKENS=512
|
||||
TIER2_MAX_TOKENS=512
|
||||
PLANNER_MAX_TOKENS=256
|
||||
CRITIC_MAX_TOKENS=512
|
||||
TIER0_ESTIMATED_CALL_MS=600
|
||||
TIER1_ESTIMATED_CALL_MS=1200
|
||||
TIER2_ESTIMATED_CALL_MS=1400
|
||||
|
||||
# Runtime experiments
|
||||
AGENT_ABSTENTION_ENABLED=false
|
||||
AGENT_ABSTENTION_THRESHOLD=0.35
|
||||
AGENT_ABSTENTION_CLARIFY_THRESHOLD=0.45
|
||||
AGENT_TOOL_RETRY_MAX=1
|
||||
AGENT_TOOL_LOOP_MAX_HOPS=3
|
||||
AGENT_PROGRAMMATIC_TOOL_CALLING=false
|
||||
AGENT_SKILL_MD_MODE=false
|
||||
AGENT_ROUTER_MODE=static
|
||||
AGENT_ROUTER_WEIGHTS_PATH=
|
||||
AGENT_USER_MEMORY_ENABLED=false
|
||||
AGENT_USER_MEMORY_TTL_DAYS=30
|
||||
AGENT_TRUST_MIN_TIER=T2
|
||||
AGENT_TOOL_SEARCH_ENABLED=false
|
||||
AGENT_TOOL_SEARCH_THRESHOLD=10
|
||||
AGENT_CRITIC_MAX_ITERATIONS=1
|
||||
PROMPT_VARIANT_ID=
|
||||
|
||||
# Evaluation / monitoring
|
||||
BACKGROUND_STREAM_MAXLEN=5000
|
||||
SHADOW_EVAL_SAMPLING_RATE_TIER0=1
|
||||
SHADOW_EVAL_SAMPLING_RATE_TIER1=1
|
||||
SHADOW_EVAL_SAMPLING_RATE_TIER2=1
|
||||
EVAL_STREAM_MAXLEN=10000
|
||||
EVAL_AGG_TICK_MS=300000
|
||||
EVAL_AGG_TTL_SEC=604800
|
||||
EVAL_AGG_LATENCY_SAMPLE_CAP=200
|
||||
EVAL_ARCHIVE_TICK_MS=3600000
|
||||
EVAL_ARCHIVE_TTL_DAYS=30
|
||||
EVAL_ARCHIVE_BATCH_SIZE=500
|
||||
EVAL_DRIFT_TICK_MS=86400000
|
||||
EVAL_PROMOTE_TICK_MS=86400000
|
||||
EVAL_PROMOTE_LOW_SCORE=2
|
||||
EVAL_PROMOTE_RARE_THRESHOLD=5
|
||||
EVAL_PROMOTE_PER_CATEGORY_LIMIT=10
|
||||
EVAL_REVIEW_TICK_MS=300000
|
||||
EVAL_REVIEW_QUEUE_MAXLEN=500
|
||||
EVAL_REVIEW_LABEL_MAXLEN=5000
|
||||
EVAL_REVIEW_PER_CATEGORY_LIMIT=5
|
||||
EVAL_REVIEW_DEDUPE_TTL_SEC=604800
|
||||
EVAL_CALIBRATION_MIN_CORR=0.5
|
||||
EVAL_TOURNAMENT_MAX_MATCHES=50
|
||||
EVAL_TOURNAMENT_MIN_CASES=10
|
||||
LLM_JUDGE_MODEL=gpt-5.3-codex-spark
|
||||
LLM_JUDGE_MAX_TOKENS=128
|
||||
LLM_PROPOSE_MODEL=
|
||||
LLM_PROPOSE_MAX_TOKENS=1024
|
||||
EVAL_PROCESS_LLM_JUDGE_ENABLED=false
|
||||
EVAL_PROCESS_LLM_JUDGE_SAMPLING_RATE=0.1
|
||||
EVAL_PROCESS_LLM_JUDGE_MAX_TOKENS=256
|
||||
EVAL_PRM_ENABLED=false
|
||||
EVAL_PRM_WEIGHTS_PATH=
|
||||
EVAL_PRM_MIN_LABELS=500
|
||||
EVAL_ATTRIBUTION_TICK_MS=21600000
|
||||
REVIEWER_ID=
|
||||
|
||||
# Alerts / tracing
|
||||
ALERT_THRESHOLD_P95_LATENCY_MS=3000
|
||||
ALERT_THRESHOLD_EVAL_SCORE_DROP_PCT=10
|
||||
ALERT_THRESHOLD_LLM_ERROR_RATE=0.1
|
||||
ALERT_THRESHOLD_DRIFT_PCT=15
|
||||
ALERT_RATE_LIMIT_SEC=300
|
||||
OTEL_EXPORTER=none
|
||||
OTEL_SAMPLING_RATIO=1
|
||||
|
||||
# Optional metadata service
|
||||
IMDS_DISABLED=false
|
||||
METADATA_DISABLED=false
|
||||
METADATA_BASE_URL=
|
||||
IMDS_BASE_URL=
|
||||
MACHINE_ENV_BASE_URL=
|
||||
METADATA_TIMEOUT_MS=1000
|
||||
@@ -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