🔁 Lesson Loop

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

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

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

• 📋 기획 문서: PRD.md

• 📊 실험 분석: evals/results/ANALYSIS.md · 원자료: RESULTS.md

• 🖼 실행 결과 캡처: docs/screenshots/ — 화면 7장

• 📄 결과물 예시: docs/sample_lesson_pack.md — 실제로 만들어 낸 레슨 팩

• 🔧 도구 스키마 원본: 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.

빠르게 실행하기

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 을 연다.

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

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

환경변수

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

화면

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

실제 화면

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

연결된 도구 8종

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

설계에서 지킨 것

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

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

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

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

중간에 끊겨도 이어진다

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

• 승인 대기 중 브라우저를 닫아도 나중에 링크로 돌아와 이어서 승인하면 그 지점부터 진행된다

• 서버를 재시작해도 running 상태로 얼어붙은 run을 시작 시 자동으로 이어 돌린다 (recover_interrupted)

• 실패한 run도 화면의 "이어서 재개" 버튼으로 저장된 단계부터 다시 민다

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

사람 개입 지점

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

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

실험 & 평가

# 설정 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 — 실제 커리큘럼에 넣을 법한 개념 10개. 각 항목에 must_cover(반드시 다뤄야 할 하위 개념)와 must_cite_domain(기대하는 1차 출처)이 붙어 있다.

• 비교 설정: app/configs.py — 파이프라인 모양 · 도구 설명 상세도 · 검수 유무 · 계획 유무 · 모델

• 해석·개선 이력·실패 사례 분석: evals/results/ANALYSIS.md

• 배치 원자료: evals/results/RESULTS.md

• 배치 간 비교(현재 채점 기준으로 재계산): python -m evals.rescore

• 수용 기준 자동 점검: python -m evals.acceptance --base <주소> --live

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

배포

현재 상태: 공개 URL로 배포하지는 않았다. 대신 로컬에서 실제로 돌린 화면을 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에 올린다

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

4. Space의 README.md는 YAML 프론트매터가 필요하다. 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

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의 A1~A7을 스크립트로 다시 확인한다.

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

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

확장

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

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

python mcp_server.py

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

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

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

자동 트리거

# 웹훅 (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의 FETCH_ALLOWLIST).

• 본문은 인용 목적의 발췌만 저장하고, 결과물에는 원문 URL을 항상 표기한다.

• MDN·Wikipedia의 공개 검색 엔드포인트를 쓴다. Wikipedia의 User-Agent 정책에 맞춰 연락처가 담긴 UA를 보낸다.

• 가져온 본문은 항상 <untrusted_document>로 감싸 모델에게 "데이터이지 지시가 아님"을 명시한다. 문서에 프롬프트 인젝션이 심겨 있어도 도구 권한은 코드가 막는다.