# 🔁 Lesson Loop

**개념 이름 하나를 넣으면, 출처 조사부터 검수까지 스스로 돌려서 바로 수업에 쓸 수 있는 레슨 팩을 파일로 만들어 주는 에이전틱 워크플로 서비스.**

학습 콘텐츠 제작자는 개념 하나마다 같은 6단계를 손으로 반복한다 — 원문 찾기 → 학습목표 쪼개기 → 루브릭 만들기 → 문항 쓰기 → **근거 대조** → 파일 정리. 개념당 2~3시간이 든다. Lesson Loop는 이 절차 전체를 대신 돌리고, 사람은 두 지점에서만 확인한다.

> 자동화하는 것은 "문항 생성"이 아니라 **"출처 조사 → 생성 → 근거 대조 → 사람 승인"이라는 절차**다.
> 그래서 모든 문항은 출처 원문의 **실제 문장**을 근거로 갖는다. 근거를 못 대면 코드가 저장을 거부한다.

- 📋 기획 문서: **[PRD.md](PRD.md)**
- 📊 실험 분석: **[evals/results/ANALYSIS.md](evals/results/ANALYSIS.md)** · 원자료: [RESULTS.md](evals/results/RESULTS.md)
- 🖼 **실행 결과 캡처: [docs/screenshots/](docs/screenshots/)** — 화면 7장
- 📄 결과물 예시: **[docs/sample_lesson_pack.md](docs/sample_lesson_pack.md)** — 실제로 만들어 낸 레슨 팩
- 🔧 도구 스키마 원본: [docs/tools_schema.json](docs/tools_schema.json)

---

## 1분 요약

```
개념 "HTTP 캐싱"  ─┐
                  ▼
  ① 계획      기획자가 하위 주제와 영어 검색어를 뽑는다
  ② 조사      web_search → fetch_page 로 1차 출처(MDN·RFC·Wikipedia)를 확보
  ⏸ 사람 확인  출처를 빼거나 직접 추가한다              ← 가장 싼 교정 지점
  ③ 작성      학습목표·루브릭·문항. 인용문은 원문에서 그대로 복사
  ④ 검수      다른 에이전트가 원문과 대조. 문제 있으면 해당 문항만 재작성
  ⏸ 사람 확인  발행 승인                                 ← 되돌리기 어려운 작업 직전
  ⑤ 발행      lesson_pack.md + lesson_pack.json
```

평가 세트 10개 실측 (gpt-4o-mini): **완료율 10/10 · 근거율 100% (190문항 전부) · 중앙값 71~83초 · 평균 $0.021 · 평균 26단계.**
자세한 수치와 개선 이력은 [ANALYSIS.md](evals/results/ANALYSIS.md).

---

## 빠르게 실행하기

```bash
git clone https://github.com/C-Lake864/lesson-loop.git && cd lesson-loop
python -m venv .venv && .venv/Scripts/activate     # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                                # .env를 열어 OPENAI_API_KEY를 채운다
uvicorn app.main:app --reload --port 8000
```

브라우저에서 <http://localhost:8000> 을 연다.

**웹 없이 한 판 돌려 보기** (트레이스가 터미널에 그대로 흐른다):

```bash
python -m app.cli "HTTP 캐싱" --questions 5 --auto
```

### 환경변수

| 변수 | 필수 | 기본값 | 설명 |
| --- | :-: | --- | --- |
| `OPENAI_API_KEY` | ✅ | — | 서버에서만 쓰인다. 프론트엔드로 절대 내려가지 않는다 |
| `LESSONLOOP_MODEL` | | `gpt-4o-mini` | 기본 모델 |
| `LESSONLOOP_REVIEW_MODEL` | | (동일) | 검수자만 다른 모델로 올리고 싶을 때 |
| `LESSONLOOP_MAX_STEPS` | | `50` | run당 LLM 호출 상한 |
| `LESSONLOOP_MAX_COST_USD` | | `0.50` | run당 비용 상한 (넘으면 자동 중단) |
| `LESSONLOOP_MAX_SECONDS` | | `420` | run당 시간 상한 |
| `LESSONLOOP_MAX_REVISIONS` | | `1` | 검수 → 재작성 최대 횟수 |
| `TAVILY_API_KEY` | | — | 있으면 검색 1순위로 사용. 없어도 동작한다 |
| `LESSONLOOP_WEBHOOK_TOKEN` | | — | 설정하면 `POST /api/webhook/run` 활성화 |
| `LESSONLOOP_SCHEDULER` | | `0` | `1`이면 큐를 cron으로 자동 실행 |
| `LESSONLOOP_RATE_LIMIT_PER_HOUR` | | `10` | IP당 시간당 실행 수 |

전체 목록은 [.env.example](.env.example) 참고. **`.env`는 절대 커밋하지 않는다** (`.gitignore`에 있음).

---

## 화면

| 화면 | 경로 | 담는 것 |
| --- | --- | --- |
| 새 실행 | `/` | 개념 입력, 예산 슬라이더, 설정 선택, 큐, 연결된 도구 8종의 스키마 |
| 실행 상세 | `/run/{id}` | **실시간 트레이스**(SSE) · 출처 · 결과물 라이브 뷰 · 승인 패널 · 다운로드 |
| 평가·비용 | `/evals` | 설정별 비교표 · 단계별 병목 · 실패 사례 표 |
| API 문서 | `/api/docs` | FastAPI 자동 생성 |

트레이스의 각 스텝에는 **어떤 도구를 왜 불렀고 무엇을 받았는지**가 인자·결과 JSON째로 남고, 소요 시간·토큰·비용이 함께 찍힌다.

### 실제 화면

| | |
| --- | --- |
| [![실행 폼](docs/screenshots/01-home.png)](docs/screenshots/01-home.png)<br>**① 새 실행** — 예산 슬라이더, 설정 선택, 연결된 도구 8종 | [![승인 대기](docs/screenshots/03a-hitl-approval.png)](docs/screenshots/03a-hitl-approval.png)<br>**② 사람 승인 대기** — 출처 제외·추가·요청 남기기 |
| [![발행 완료](docs/screenshots/03-run-published.png)](docs/screenshots/03-run-published.png)<br>**③ 발행 완료** — 파일 크기 확인 후 뜨는 배너, 결과물, 검수 지적, 롤백 | [![평가 대시보드](docs/screenshots/06-evals-dashboard.png)](docs/screenshots/06-evals-dashboard.png)<br>**④ 평가·비용** — 단계별 병목, 설정별 비교, 실패 사례 |

전체 트레이스(115스텝)와 인자·결과 JSON까지 펼친 화면, 도구 스키마 전문은
**[docs/screenshots/](docs/screenshots/)** 에 있다. 전부 `python docs/capture.py`로 재현된다.

---

## 연결된 도구 8종

| 도구 | 종류 | 부작용 | 권한 | 승인 |
| --- | --- | --- | --- | :-: |
| `web_search` | 외부 API | 없음 | 검색어만 전송 | |
| `fetch_page` | 외부 HTTP | 없음 | **도메인 allowlist만**, 사설 IP 차단, 15초·200KB 상한, 주제 관련성 검사 | |
| `read_sources` | DB 읽기 | 없음 | 현재 run의 출처만 | |
| `save_draft` | DB 쓰기 | 있음 | 현재 run에만 insert | |
| `save_questions` | DB 쓰기 | 있음 | 현재 run에만 insert | |
| `read_draft` | DB 읽기 | 없음 | 현재 run만 | |
| `save_review` | DB 쓰기 | 있음 | 현재 run에만 insert | |
| `export_pack` | **파일 생성** | **되돌리기 어려움** | `artifacts/{run_id}/` 밖으로 못 나감 | **✅ 필수** |

각 도구의 입력·출력 스키마는 실행 화면 오른쪽 "연결된 도구"에서 펼쳐 볼 수 있고, `GET /api/meta`로도 받을 수 있다.

### 설계에서 지킨 것

**부작용은 전부 도구를 통과한다.** 에이전트는 DB에 직접 쓰지 않고 파일도 직접 만들지 않는다. 그래서 모든 부작용이 100% 로그에 남는다.

**승인은 프롬프트가 아니라 코드가 확인한다.** `export_pack`은 DB에 승인 토큰이 있는지 확인하고, 없으면 도구 레이어에서 거부한다. 프롬프트를 아무리 설득해도 우회할 수 없다.

**실패는 예외로 터뜨리지 않는다.** 모든 도구 오류는 `{"ok": false, "error": {"code", "message", "hint"}}`로 모델에게 돌아간다. 에이전트가 스스로 회복할 기회를 주기 위해서다. 회복 시도까지 전부 트레이스에 남는다.

| 실패 유형 | 처리 |
| --- | --- |
| 타임아웃·5xx | 재시도 2회 (0.5s → 2s) |
| 검색 백엔드 실패 | **4단 폴백**: Tavily → 문서 사이트 자체 검색(MDN·Wikipedia) → DuckDuckGo → 내장 시드 코퍼스 |
| 페이지를 못 가져옴 | 시드 코퍼스에 같은 URL이 있으면 그것으로 대체 |
| allowlist 밖 / 주제 무관 | 재시도 없이 구조화 오류 반환 → 에이전트가 다른 URL 선택 |
| 스키마·근거 검증 실패 | 무엇이 왜 틀렸는지 + **원문에서 가장 가까운 구간**을 함께 반환 |
| 같은 도구·같은 인자 3회 | 루프 감지 → 차단 |

**무한 루프는 세 겹으로 막는다.** ① 예산(단계 50 / 비용 $0.50 / 시간 420초 / 도구 호출 80회) ② 같은 호출 반복 감지 ③ 정체 감지 — 도구를 계속 부르면서 마무리 도구를 안 부르면 "지금 가진 정보로 마무리하라"는 지시를 주입한다.

---

## 중간에 끊겨도 이어진다

에이전트의 대화 히스토리가 매 회차 DB에 통째로 저장된다. 그래서:

- **승인 대기 중 브라우저를 닫아도** 나중에 링크로 돌아와 이어서 승인하면 그 지점부터 진행된다
- **서버를 재시작해도** `running` 상태로 얼어붙은 run을 시작 시 자동으로 이어 돌린다 (`recover_interrupted`)
- **실패한 run도** 화면의 "이어서 재개" 버튼으로 저장된 단계부터 다시 민다

```bash
# 직접 확인해 보기: 실행 중에 서버를 죽였다 살린다
uvicorn app.main:app --port 8000     # Ctrl+C 로 중단 후 다시 실행
# → 로그에 "[lessonloop] 중단된 run N개를 재개했다."
```

---

## 사람 개입 지점

| 지점 | 위치 | 할 수 있는 것 |
| --- | --- | --- |
| **HITL #1** | 조사 완료 → 작성 시작 전 | 출처 개별 제외 · URL 직접 추가 · 작성자에게 요청 남기기 · 거부 후 재조사 |
| **HITL #2** | 발행 직전 | 결과물 미리보기 확인 · 승인 · 발행 취소 |
| 상시 | 실행 중 언제든 | 중단(산출물 보존) · 실패 후 재개 · 초안 이전 버전으로 롤백 |

`auto_approve`를 켜면 두 지점을 자동 통과한다. 평가용이며, 켜면 화면에 경고가 뜬다.

**"완료했다"는 말과 결과물은 다르다.** 발행 완료 배너는 파일이 디스크에 실제로 쓰였고 크기가 0이 아님을 되읽어 확인한 뒤에만 뜨고, 파일명·바이트 수·문항 수·근거율을 함께 찍는다.

---

## 실험 & 평가

```bash
# 설정 4종 × 시나리오 4종을 돌리고 표로 남긴다
python -m evals.run --configs baseline,no_review,tools_terse,single_agent \
                    --only http-caching,css-box-model,hash-table,tx-isolation \
                    --workers 3
```

- 평가 세트: [evals/dataset.jsonl](evals/dataset.jsonl) — 실제 커리큘럼에 넣을 법한 개념 10개. 각 항목에 `must_cover`(반드시 다뤄야 할 하위 개념)와 `must_cite_domain`(기대하는 1차 출처)이 붙어 있다.
- 비교 설정: [app/configs.py](app/configs.py) — 파이프라인 모양 · 도구 설명 상세도 · 검수 유무 · 계획 유무 · 모델
- **해석·개선 이력·실패 사례 분석: [evals/results/ANALYSIS.md](evals/results/ANALYSIS.md)**
- 배치 원자료: [evals/results/RESULTS.md](evals/results/RESULTS.md)
- 배치 간 비교(현재 채점 기준으로 재계산): `python -m evals.rescore`
- 수용 기준 자동 점검: `python -m evals.acceptance --base <주소> --live`

지표는 전부 코드가 계산한다. 에이전트가 "잘 끝냈다"고 말한 것은 세지 않는다. 특히 **근거율**은 모델의 주장이 아니라 인용문을 원문과 문자 단위로 대조해 다시 계산한 값이다.

---

## 배포

> **현재 상태**: 공개 URL로 배포하지는 않았다. 대신 로컬에서 실제로 돌린 화면을
> [docs/screenshots/](docs/screenshots/)에 캡처로 남겼고, 산출물 예시와 도구 스키마 원본도
> 저장소에 함께 두었다. 아래 절차대로 하면 그대로 배포된다.

한 프로세스가 API와 정적 프론트엔드를 함께 서빙하므로 배포 단위가 하나다.

### 방법 A — Hugging Face Spaces (카드 등록 불필요, 가장 쉬움)

1. <https://huggingface.co/new-space> → SDK **Docker**, 하드웨어 **CPU basic (free)** 로 Space 생성
2. Space의 **Settings → Variables and secrets → New secret** 에서 `OPENAI_API_KEY` 추가
   (Secret으로 넣어야 로그·소스에 노출되지 않는다)
3. 이 저장소를 Space에 올린다

   ```bash
   git remote add space https://huggingface.co/spaces/<계정>/lesson-loop
   git push space main
   ```

4. Space의 `README.md`는 YAML 프론트매터가 필요하다. [deploy/huggingface-space-README.md](deploy/huggingface-space-README.md)
   를 Space 저장소 루트의 `README.md`로 복사해 쓰면 된다 (`app_port: 7860`이 들어 있다)
5. 빌드가 끝나면 `https://<계정>-lesson-loop.hf.space/api/meta` 가 `{"llm_ready": true}` 를 반환해야 한다

### 방법 B — Render

1. Render → **New → Web Service** → 이 GitHub 저장소 연결 (`render.yaml`이 자동 인식된다)
2. **Environment** 탭에서 `OPENAI_API_KEY`를 직접 입력한다 (저장소에는 들어 있지 않다)
3. 배포 후 `/api/meta`가 `{"llm_ready": true}`를 반환하면 정상

### 방법 C — 직접 Docker

```bash
docker build -t lesson-loop .
docker run -p 7860:7860 -e OPENAI_API_KEY=sk-... lesson-loop
```

`PORT` 환경변수를 따르므로 Fly·Cloud Run 등에도 그대로 올라간다.

> **알려진 한계**: SQLite와 산출물이 컨테이너 파일시스템에 있어 재배포 시 초기화된다.
> `LESSONLOOP_DB_PATH`·`LESSONLOOP_ARTIFACT_DIR`을 영구 볼륨으로 지정하면 유지된다.
> HF Spaces에서는 Persistent Storage(유료)를 붙이거나, 데모 목적이면 그대로 두어도 무방하다.

> **배포 시 권장 설정**: 남용 방지를 위해 `LESSONLOOP_MAX_COST_USD=0.30`,
> `LESSONLOOP_RATE_LIMIT_PER_HOUR=6` 정도로 낮춰 두는 것이 좋다.

### 배포 후 수용 기준

[PRD.md §8.2](PRD.md)의 A1~A7을 스크립트로 다시 확인한다.

```bash
python -m evals.acceptance --base https://<배포주소> --live --write
```

확인 결과는 [evals/results/RESULTS.md](evals/results/RESULTS.md) 하단에 기록된다.

---

## 확장

### MCP 서버 — 산출물을 다른 에이전트의 도구로

이 서비스는 도구를 쓰는 쪽이자, 자기 산출물을 도구로 내놓는 쪽이기도 하다.

```bash
python mcp_server.py
```

`.mcp.json`에 등록하면 Claude Code 같은 클라이언트가 만들어진 레슨 팩을 직접 쓸 수 있다.

```json
{ "mcpServers": { "lesson-loop": {
    "command": "python", "args": ["mcp_server.py"], "cwd": "<이 저장소 경로>" } } }
```

| MCP 도구 | 하는 일 |
| --- | --- |
| `list_packs` | 만들어진 레슨 팩 목록 |
| `get_pack` | 팩 하나 전체 (json 또는 md) |
| `search_questions` | 모든 팩을 가로질러 문항 검색 — 문제은행처럼 |
| `get_rubric` | 학습목표·루브릭만 |
| `enqueue_concept` | 새 개념을 제작 큐에 등록 |

**발행·삭제는 노출하지 않는다.** 되돌리기 어려운 일은 사람 승인 지점이 있는 웹 UI에만 남겨 뒀다.

### 자동 트리거

```bash
# 웹훅 (LESSONLOOP_WEBHOOK_TOKEN 설정 시)
curl -X POST https://<배포주소>/api/webhook/run \
  -H "X-Webhook-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"concept":"CORS","n_questions":5,"auto_approve":true}'

# 스케줄러 — 큐에 쌓인 개념을 cron에 맞춰 자동 실행
LESSONLOOP_SCHEDULER=1 LESSONLOOP_SCHEDULER_CRON="0 3 * * *" uvicorn app.main:app
```

### 그 밖에

- **멀티 에이전트** — 기획자 / 조사자 / 작성자 / 검수자 4역할. `single_agent` 설정으로 단일 에이전트와 비교할 수 있다
- **롤백** — 초안은 append-only로 버전이 쌓인다. 실행 화면에서 이전 버전으로 되살릴 수 있다
- **비용 대시보드** — `/evals`에서 단계별 누적 시간·비용으로 병목을 본다

---

## 구조

```
app/
  main.py         FastAPI — API · SSE · 정적 서빙
  orchestrator.py 단계 상태 머신 · 사람 개입 지점 · 실패 분류
  agent.py        에이전트 루프 (계획 → 도구 → 관찰 → 다음 행동)
  tools/
    base.py       권한 · 승인 · 재시도 · 루프 감지가 모이는 도구 진입점
    search.py     web_search (4단 폴백)
    fetch.py      fetch_page (allowlist · SSRF 방어 · 주제 관련성)
    draft.py      save_draft · save_questions (검증 게이트)
    store.py      read_sources (인용문 추출 포함) · save_review
    grounding.py  인용문 ↔ 원문 대조 — 환각 방지의 핵심
    export.py     export_pack (승인 필수 · 되읽어 확인)
  db.py           SQLite — run · trace · 메시지 히스토리 · 승인 · 아티팩트
  llm.py          OpenAI 호출 + 토큰·비용 계량
  prompts.py      역할별 시스템 프롬프트
  configs.py      실험 설정
static/           프론트엔드 (빌드 도구 없음)
evals/            평가 세트 · 러너 · 결과
mcp_server.py     MCP 서버
data/seed_sources.json   검색이 전부 막혔을 때의 최후 폴백 코퍼스
```

## 외부 서비스 사용에 대해

- 출처는 공개 기술 문서 사이트로 한정한다 ([app/config.py](app/config.py)의 `FETCH_ALLOWLIST`).
- 본문은 **인용 목적의 발췌**만 저장하고, 결과물에는 원문 URL을 항상 표기한다.
- MDN·Wikipedia의 공개 검색 엔드포인트를 쓴다. Wikipedia의 User-Agent 정책에 맞춰 연락처가 담긴 UA를 보낸다.
- 가져온 본문은 항상 `<untrusted_document>`로 감싸 모델에게 "데이터이지 지시가 아님"을 명시한다. 문서에 프롬프트 인젝션이 심겨 있어도 도구 권한은 코드가 막는다.