Skip to content

docs: README 갱신 — AI 활용 + API 활용 방점 (v1.0 → v2 현행화) #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LsMin124 merged 1 commit into from
Jun 25, 2026
Merged

docs: README 갱신 — AI 활용 + API 활용 방점 (v1.0 → v2 현행화) #178

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
297 changes: 180 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,133 +1,222 @@
# IPE — Infinite Problem Engine

> **알고리즘 문제 생성 + 결정론적 검증 파이프라인**. LangGraph + Claude 4.7
> Opus/Sonnet 으로 problem spec → algorithm design → code → symbolic verifier
> 4-node pipeline. 19 algorithm × 4 invariants 누적 catalog.

[![Status](https://img.shields.io/badge/status-v1.0%20D%EC%95%88%20(19%20algo%2C%20anchor%20freeze)-blue)](CHANGES.md)
[![Tests](https://img.shields.io/badge/tests-418%20passed-brightgreen)](tests/)
[![e2e](https://img.shields.io/badge/Phase%202c%20RCA3-52%2F57%20(91.2%25)-brightgreen)](CHANGES.md#67)
[![Engaged](https://img.shields.io/badge/samples_engaged-99.1%25-brightgreen)](CHANGES.md#67)
[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen)](https://github.com/LsMin124/IPE/actions)
> **AI 멀티에이전트가 알고리즘 문제를 생성하고, 결정론적 검증으로 정답을 보증하며,
> REST API 로 서비스에 공급하는 파이프라인.** LangGraph 상태그래프 위에서 Claude
> (Opus 4.8 / Sonnet 4.6) 가 시드 → 형식 동결 → 은닉 지문 → 정해/검산 코드를 짜고,
> LLM 과 독립된 symbolic verifier · golden↔brute differential 이 정답성을 결정한다.

[![Tests](https://img.shields.io/badge/tests-903%20passed-brightgreen)](tests/)
[![mypy](https://img.shields.io/badge/mypy--strict-100%20files-blue)](pyproject.toml)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
[![Models](https://img.shields.io/badge/Claude-Opus%204.8%20%2F%20Sonnet%204.6-8A2BE2)](ipe/v2/config.py)
[![API](https://img.shields.io/badge/contract-v3.2-orange)](docs/integration/pipeline-service-api-contract.md)

> 🌐 인터랙티브 대시보드: [lsmin124.github.io/IPE](https://lsmin124.github.io/IPE/)

---

## 무엇

IPE 는 **알고리즘 문제 생성 + 결정론적 검증** 시스템:
IPE 는 **AI 로 문제를 만들고, 결정론으로 정답을 보증**하는 시스템이다.

- **AI 멀티에이전트 생성** — 다수의 Claude 노드가 역할을 나눠 알고리즘 문제를 설계·서술·구현
- **은닉 + 위장** — 정답 알고리즘을 숨기고 현실 도메인 스토리로 위장 (응시자가 환원을 발견해야 함)
- **결정론적 검증** — 정답성은 LLM 판단이 아니라 **symbolic verifier + golden↔brute differential** 이 결정
- **QA 비평 게이트** — 모호성·공정성·난이도·정답 유출을 병렬 critic 이 심사
- **BOJ 티어 난이도 calibration** — 생성 문제를 Bronze~Platinum 으로 자동 등급화
- **서비스 공급** — FastAPI REST API 로 백엔드에 비동기 job 형태로 제공

핵심 명제: **"생성은 AI 가, 정답 보증은 결정론이."** LLM 은 창의적 설계·서술·코딩을
맡고, 채점 정답(expected output)은 검증된 golden 코드 **실행** 으로 부트스트랩하며,
정답성은 LLM 과 독립된 알고리즘별 수학적 invariant 로 교차검증한다.

---

## 🤖 AI 활용

### 1. 멀티에이전트 파이프라인 (LangGraph 상태그래프)

문제 생성을 단일 LLM 호출이 아니라 **역할 분리된 노드들의 상태그래프**로 분해한다.
각 노드는 frozen Pydantic 상태(`V2State`)를 읽고 자기 산출만 채운다.

| 노드 | 역할 | 모델 | 종류 |
|---|---|---|---|
| **strategist** | 은닉 코어 + 합성 기법 + 위장 도메인 결정 (발산) | Sonnet 4.6 | LLM |
| **formalizer** | 입출력 형식 계약(`io_schema`) **FREEZE** | Opus 4.8 | LLM (정밀) |
| **narrative** | 은닉 지문 렌더 (도메인 스토리) | Sonnet 4.6 | LLM (창작) |
| **faithfulness** | 지문 ↔ 형식계약 충실성 round-trip 검증 | Opus 4.8 | LLM (검증) |
| **spec_bridge** | blueprint → solver spec 투영 | — | 결정론 |
| **designer** | 알고리즘 설계 + 불변식 도출 | Sonnet 4.6 | LLM |
| **golden coder ×K** | 정해 코드 (모델 다양성으로 병렬) | Opus 4.8 + Sonnet 4.6 | LLM |
| **brute coder** | 독립 무차별 검산 코드 (golden 과 distinct) | Sonnet 4.6 | LLM |
| **reconciler** | golden ↔ brute differential 합의 | — | 결정론 |
| **executor** | 샌드박스 실행 + symbolic verifier dispatch | — | 결정론 |
| **input_generator** | 시드 기반 입력 **결정론** 생성 | — | 결정론 |
| **suite_assembler** | golden 실행으로 expected 부트스트랩 | — | 결정론 |
| **qa reviewer ×N** | 모호성·공정성·난이도·유출 병렬 비평 | Sonnet 4.6 | LLM (critic) |
| **difficulty** | BOJ 티어 calibration (anchor 기반) | Sonnet 4.6 | LLM |

### 2. 모델 티어링 — 작업 난이도에 맞춘 분담

| 모델 | 쓰임 | 이유 |
|---|---|---|
| **Claude Opus 4.8** | 형식 동결(formalizer) · 충실성 검증(faithfulness) · 정해 1 | 계약을 못 박고 모순을 잡는 정밀·추론 작업 |
| **Claude Sonnet 4.6** | 전략·서술·설계·QA 비평·무차별 검산·난이도 | 발산·창작·검산은 빠르고 다양하게 |
| **모델 다양성** | golden(Opus+Sonnet) vs brute(Sonnet) | 같은 코드를 **다른 모델**이 독립 작성 → 우연한 동일 버그가 상쇄되어 differential 신뢰도↑ |

### 3. 구조화 출력 (typed tool call)

모든 LLM 노드는 자유 텍스트가 아니라 **검증된 Pydantic 스키마**로 반환한다
(`langchain_anthropic` + `with_structured_output`). 형식 위반 시 모델이 재시도하므로
파싱 실패·환각 필드가 파이프라인에 새지 않는다.

### 4. 단일-IR — consistency-by-construction

문제의 모든 표면(입력 형식 / 제약 / 지문 / 정해)을 하나의 동결 IR(`ProblemBlueprint`)
**투영**으로 만든다. 같은 사실을 여러 LLM 이 따로 서술해 어긋나던 모순(O(N²) 표면)을
구조적으로 붕괴시킨다. 예: 정렬성·문자집합·참조 의미(위치 인덱스 vs 개수)·출력 형식의
도메인 의미를 IR 한 곳에 핀하고 모든 곳이 그것을 **읽는다**.

### 5. 자기교정 루프 (faithfulness round-trip · QA back-route)

- **faithfulness**: 지문이 형식계약을 왜곡하면 narrative 를 재생성 (예산 바운드).
- **QA critic 패널**: 모호성/공정성/난이도/(은닉 시)정답유출을 병렬 심사 → fail 시
지문/스펙을 패치하고 재리뷰하는 back-route 루프.

### 6. AI 판단 vs 결정론의 경계

> **정답성은 절대 LLM 이 결정하지 않는다.** expected output 은 검증된 golden 코드
> 실행으로 채우고, 정답 보증은 알고리즘별 수학적 invariant(예: Dijkstra ↔ Bellman-Ford
> 교차검증, segment tree ↔ naive O(NQ))로 교차검증한다. LLM 은 *무엇을 만들지* 를,
> 결정론은 *그것이 맞는지* 를 맡는다.

---

## 🔌 API 활용

### A. Anthropic API (Claude 호출)

- `langchain_anthropic.ChatAnthropic` 로 호출, 모든 노드가 `with_structured_output(...)`
으로 **typed tool call** 반환.
- 모델 ID: `claude-opus-4-8`, `claude-sonnet-4-6` (난이도/검산은 Sonnet).
- 인증: `.env` 의 `ANTHROPIC_API_KEY`.
- 비용 실측: 1 run ≈ $0.4~0.6, 출하당 ≈ $1~2 (재시도 포함, 모드·합성수에 따라).

### B. 서비스 API (FastAPI) — 백엔드 공급 계약

파이프라인을 **stateless REST 서비스**로 노출한다. 문제 영속화는 서비스 백엔드 DB 가
전담하고, 이 서버는 진행 중 job 만 in-memory 로 유지한다.

| 메서드 · 경로 | 역할 |
|---|---|
| `GET /healthz` | 헬스체크 |
| `POST /v1/problems/generate` | 비동기 생성 시작 → `202 {job_id}`. `idempotency_key` 로 중복 방지, 용량 초과 시 `429 + Retry-After`. |
| `GET /v1/jobs/{job_id}` | job 폴링 — `running`/`completed`/`failed` + 완료 시 문제 패키지 |

요청 본문(`mode` 가 노브 4종을 결정):

```jsonc
{ "mode": "p1", // p1=단일·공개·QA3 / p2=합성·은닉·QA4
"seed_algorithm": "dijkstra", // p1=고정 타겟, p2=힌트(은닉)
"with_qa": true,
"idempotency_key": "req-..." }
```
target_algorithm → [architect → designer → coder → executor] → 검증된 문제 + 코드
(Opus) (Sonnet) (Opus) (verifier)

```bash
# 서버 기동
IPE_API_KEY=... uv run uvicorn 'ipe.v2.api:create_app' --factory --port 8000
```

각 algorithm 의 **수학적 invariants** 를 코드로 결정론적 검증 (LLM judgment
와 독립된 anchor). 19 algorithm × 4 invariants = 76 invariants 누적.
- 계약 SSOT: [`docs/integration/pipeline-service-api-contract.md`](docs/integration/pipeline-service-api-contract.md) (**v3.2**)
- 배포 가이드: [`docs/integration/pipeline-deploy.md`](docs/integration/pipeline-deploy.md) · DB 접근: [`docs/integration/db-access-handoff.md`](docs/integration/db-access-handoff.md)
- 패키지 필드(문제/정해/채점셋/메타 — `meta.difficulty`/`problem_number`/`algorithm` N:M 등)는 계약이 SSOT.

---

### v0 → v1 D안 architecture 진화
## 파이프라인 아키텍처 (P1 / P2 모드)

```text
START → strategist → formalizer → narrative → faithfulness ──(왜곡)─→ narrative 재생성
(시드) (FREEZE) (은닉지문) (round-trip) (예산 바운드)
│(faithful)
▼
spec_bridge → designer → dispatch ─┬→ golden_0..K (Opus+Sonnet) ─┐
(순수 투영) (불변식) └→ brute (Sonnet, distinct) ──┴→ reconciler
(differential)
reconciler ─(합의)→ sample/edge filler → executor (샌드박스 + symbolic verifier)
│(pass)
▼
generator_designer → input_generator → suite_assembler (결정론 채점셋, golden→expected)
│
▼
qa_{ambiguity·fairness·difficulty·(leakage)} 병렬 → aggregator ─(pass)→ 출하
▲ (fail) spec_patch / narrative_revise back-route ┘
```

| 시점 | run-level | 비고 |
| 노브 | **P1** (단일·공개) | **P2** (합성·은닉) |
|---|---|---|
| v0 single LLM baseline | 27% | 단일 LLM call 의 정확도 anchor |
| v1 Phase 1 (Dijkstra MVR) | 100% (3/3) | D안 architecture 시작 |
| v1 Phase 2a (5 algo) | 93.3% (14/15) | baseline + 4 algo |
| v1 Phase 2b (13 algo) | 87.2% (34/39) | +8 algo (Search/DS/DP/Sort/String/...) |
| v1 Phase 2c (19 algo) | 82.5% (47/57) | +6 algo (Graph/DS/DP) |
| **v1 Phase 2c RCA3 final** | **91.2% (52/57)** | **architect prompt 일반화 — v1.0 anchor ✅** |
| `hidden` | False | True |
| `composition` | 빈값 (단일 알고리즘) | ≥1 (총 2개+ 합성) |
| `qa_kinds` | ambiguity·fairness·difficulty | + leakage (4종) |
| `seed_algorithm` | 고정 공개 타겟 | 힌트 (은닉) |

**+64pp vs v0 baseline + 99.1% samples_engaged**. catalog ×3.8 확장. 추가
측정은 diminishing returns 로 판단해 anchor freeze. P3 후속 (PR #104 Option B
routing 확장, PR #105 outputs/ persistence) 까지 반영.
자세한 노드 의미: [`ipe/v2/graph.py`](ipe/v2/graph.py) docstring.

---

## 19 Algorithm Catalog (Phase 2c)
## 19 Algorithm Catalog

| family | algorithm | verifier 핵심 invariant |
|---|---|---|
| Graph | Dijkstra | Bellman-Ford cross-check (non-negative weight) |
| Graph | BFS | Floyd-Warshall cross-check (edge=1) |
| Graph | Dijkstra | Bellman-Ford 교차검증 (non-negative weight) |
| Graph | BFS | Floyd-Warshall 교차검증 (edge=1) |
| Graph | Topological Sort | edges_respect_order + Kahn DAG check |
| Graph | Bellman-Ford | Floyd-Warshall cross-check (negative weight) |
| Graph | Floyd-Warshall | V × Bellman-Ford cross-check (all-pairs) |
| Graph | Kruskal MST | Prim cross-check |
| Graph | Max Flow | brute min-cut (max-flow min-cut theorem) |
| Search | Binary Search | linear scan cross-check |
| Graph | Bellman-Ford | Floyd-Warshall 교차검증 (negative weight) |
| Graph | Floyd-Warshall | V × Bellman-Ford 교차검증 (all-pairs) |
| Graph | Kruskal MST | Prim 교차검증 |
| Graph | Max Flow | brute min-cut (max-flow min-cut 정리) |
| Search | Binary Search | linear scan 교차검증 |
| Search | LIS | patience sort O(N log N) |
| Array | Two Sum | brute O(N²) pair enumeration |
| Array | Two Sum | brute O(N²) pair 열거 |
| Sort | Sort cluster | Python `sorted()` |
| String | String Match cluster | brute O(NM) substring search |
| DS | Segment Tree | naive O(NQ) range sum |
| DS | Heap (Min-PQ) | sorted-list simulation |
| DS | Heap (Min-PQ) | sorted-list 시뮬레이션 |
| DS | Fenwick Tree (BIT) | naive prefix-sum |
| DSU | Union-Find | BFS over union edges |
| DP | Knapsack 0/1 | brute O(2^N) subset enum |
| DP | Knapsack 0/1 | brute O(2^N) subset 열거 |
| DP | Coin Change | DP O(N*A) tabulation |
| NumTheory | Sieve of Eratosthenes | trial division O(N√N) |

각 algorithm 의 **수학적 invariant** 를 코드로 결정론 검증 (LLM 판단과 독립한 anchor).

---

## Quick Start

```bash
# 환경 설정
uv sync --extra dev

# .env 에 ANTHROPIC_API_KEY 설정
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# 단일 algorithm 문제 생성 (verbose 으로 spec/code 확인)
uv run python -m ipe.v1.main_v1 --algorithm dijkstra --max-iter 4 --verbose

# N=3 measurement (단일 algo)
uv run python -m ipe.v1.measurement \
--algorithm knapsack --n 3 \
--output docs/baseline/data/my-run.jsonl
# 단일 문제 생성 (P1 단일·공개 / P2 합성·은닉)
uv run python -m ipe.v2.main_v2 --algorithm dijkstra --mode p1
uv run python -m ipe.v2.main_v2 --algorithm dijkstra --mode p2 --max-iter 6 --verbose

# Phase 2c 19 algo × N=3 = 57 runs (Gate 측정)
uv run python -m ipe.v1.measurement \
--phase-2c --n 3 \
--output docs/baseline/data/phase-2c.jsonl
```

지원되는 `--algorithm` 값: `dijkstra` / `lis` / `segtree` / `two_sum` /
`bfs` / `binary_search` / `union_find` / `toposort` / `knapsack` / `sort` /
`string_match` / `max_flow` / `sieve` / `bellman_ford` / `floyd_warshall` /
`kruskal_mst` / `heap` / `fenwick` / `coin_change`
# 배치 측정 (시드 × N, 출하율/비용 집계)
uv run python -m ipe.v2.batch --seeds binary_search,lis --runs-per-seed 3 --mode p1 \
--out outputs/my-run

산출물: `docs/baseline/data/*.jsonl` (RunOutcome JSONL) — 각 line 에
`run_id, final_status, sample_pass_count, sample_total, samples_engaged,
invariant_violations[], blocking_signatures[], elapsed_seconds`.
# API 서버 (서비스 백엔드 공급)
IPE_API_KEY=... uv run uvicorn 'ipe.v2.api:create_app' --factory --port 8000

---

## 아키텍처

```text
USER CLI
↓
initial_state (V1State, Pydantic v2 frozen)
↓
LangGraph pipeline:
[architect (Opus)] → ProblemSpec
↓
[designer (Sonnet)] → AlgorithmDesign (+ invariants[])
↓
[coder (Opus)] → SolutionAttempt (Python code)
↓
[executor (no LLM)] → 4-phase verification:
├ Phase A: subprocess run per sample
├ Phase B: SymbolicVerifier dispatch (19 verifier registry)
├ Phase C: StructuredFeedback build (failure_mode + target_node)
└ Phase D: routing decision (loop or terminate)
↓
[record] → final V1State + JSONL outcome
# 난이도 백필 (DB 적재 문제를 BOJ 티어로 calibration)
uv run python -m ipe.v2.difficulty --db-url postgresql://... [--force]
```

자세한 visualization: [`docs/v1-pipeline-flow.md`](docs/v1-pipeline-flow.md).
지원 `--algorithm` (seed): `dijkstra` `bfs` `toposort` `bellman_ford` `floyd_warshall`
`kruskal_mst` `max_flow` `binary_search` `lis` `two_sum` `sort` `string_match`
`segtree` `heap` `fenwick` `union_find` `knapsack` `coin_change` `sieve`

---

Expand All @@ -137,46 +226,20 @@ LangGraph pipeline:
|---|---|
| [`docs/SPEC.md`](docs/SPEC.md) | 기능/비기능 요구사항 |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 모듈 설계 + Pydantic schema SSOT |
| [`docs/v1-pipeline-flow.md`](docs/v1-pipeline-flow.md) | v1 D안 ASCII pipeline 시각화 |
| [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md) | 5 운영 룰 (N≥3 / cross-algo regression / baseline anchor / complexity budget / RCA rollback) |
| [`docs/baseline/`](docs/baseline/) | Measurement raw data + 보고서 (Phase 2a/2b/2c) |
| [`CHANGES.md`](CHANGES.md) | 변경 이력 (§1~§66+) |

---

## 가설 (H1/H2/H3) Evidence

- **H1 (structured routing)**: API error 0 / budget_exhausted 0 / typed
feedback 으로 architect↔coder 라우팅 결정론적 (Phase 2c 47/57 runs 전부
결정적 종료)
- **H2 (algorithm-specific verifier)**: **samples_engaged 100%** 유지 across
19 algo. Verifier dispatch (LLM 독립) 가 sample-level 정답성 결정.
- **H3 (IterationContext multi-iter recovery)**: binary_search r1/r2 +
segtree r1 + toposort retries 모두 iter=2 recover. fail_oscillation 은
외부 routing 한계 (P3 후속).
| [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md) | 운영 룰 (N≥3 측정 / baseline anchor / RCA rollback 등) |
| [`docs/integration/pipeline-service-api-contract.md`](docs/integration/pipeline-service-api-contract.md) | 파이프라인 ↔ 서비스 백엔드 API 계약 (v3.2) |
| [`ipe/v2/graph.py`](ipe/v2/graph.py) | v2 LangGraph 위상 (P1/P2 노브) |
| [`CHANGES.md`](CHANGES.md) | 변경 이력 |

---

## 개발

```bash
make ci # ruff + mypy --strict + pytest
uv run pytest tests/v1 -q --ignore=tests/v1/test_e2e_real_llm.py
uv run python -m ipe.v1.main_v1 --algorithm sieve --max-iter 4 --verbose
make ci # ruff + mypy --strict + pytest (903 passed)
uv run pytest tests/v2 -q
uv run python -m ipe.v2.main_v2 --algorithm sieve --mode p1 --verbose
```

자세한 운영 룰 → [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md).

---

## 기여 / 알려진 이슈

- **Two Sum persistent fail**: architect 가 array 작성 시 multiple valid pair
생성하는 경우 expected_output mismatch. P3 routing 확장 (sample_mismatch +
invariant_violations=[] → architect back-route) 으로 systematic recovery
계획.
- **outputs/ persistence**: v1 D안 은 RunOutcome metric 만 jsonl 저장. spec/
code 영속화는 후속 (verbose flag 로 console 출력만).

PR 환영. [PRINCIPLES.md](docs/PRINCIPLES.md) 의 5 운영 룰 (N≥3 측정 / cross-algo
regression / baseline anchor / complexity budget / RCA rollback) 준수 권장.
운영 룰 → [`docs/PRINCIPLES.md`](docs/PRINCIPLES.md). 측정은 N≥3 + baseline anchor,
과측정은 diminishing returns 로 중단하는 것이 이 저장소의 규율이다.
Loading