docs/plans/mvp.md

카르밀라 인터랙티브 노벨 — MVP 구현 계획

승인일: 2026-07-03 · 상태: M0~M6 전체 완료 = MVP 완성 (2026-07-03, feature/mvp-m1-m4) 실행: .venv/bin/uvicorn engine.router:app --port 8777 → http://localhost:8777 (웹 리더) .venv/bin/python scripts/play.py (CLI) · adk web . → engine (포켓 단독) LLM: 루트 .env의 OPENAI_API_KEY 자동 로딩. 실 LLM으로 회피사다리·심층해금·수렴 E2E 검증 완료 follow-up: SequentialAgent → google.adk.workflow 마이그레이션 검토 · E06-09 유보(중립) 3안 선택지 미노출 · R-약점반응 구조화(현재 raw 주입) · 타 화자(아버지 등) 채팅 포켓 · 세션 영속화 원칙: CLAUDE.md 준수 (google-adk 공식 패턴, 서사 진행은 코드가·대사는 LLM이, 스포일러 필터 강제)

MVP 정의

E01~E06(챕터1)을 처음부터 끝까지 플레이 가능한 수직 슬라이스.

• 카드 단위 읽기(L0, 캐논 고정) → 선택지/자유채팅 개입 포켓(L1) → 숨은 상태 누적 → 엔딩 3종 수렴(L2)
• 엔진: google-adk. 실행: CLI + adk web. 리딩 UI는 MVP 이후(M5)
• GraphRAG/Neo4j는 MVP 제외 — kb_query는 pre_kb 유지, repository 인터페이스만 준비
• reference/는 개념 검증 프로토타입. 참고만 하고 코드는 ADK로 새로 구축 (유저 확정)

데이터 모델 (A안 아키텍처 — reference v10에서 검증된 개념)

레이어	파일	내용
정체성 (불변)	content/characters.yaml	인물 시트(ENOS), player=laura, 지식경계, kb_query 훅
챕터 메타	content/chapters/*.yaml	entry/exit beats, beat_range, 엔딩 3종 규칙, R카드 등록
내러티브	content/beatcards/E0*/*.yaml	카드: narration 블록/choices/next/canon/복선 태그/연출

• 콘텐츠 원천(권위): 카르밀라/0701_카르밀라/비트카드/ MD (대표님 소유)
• 변환 YAML은 파생물: scripts/beatcard_convert.py(개발팀 소유)로 생성
• 숨은 상태 3값 (P0 4종 엔진 명세): 신뢰축(시소) · 쇠약도(단조 증가, 신뢰와 독립) · 앎(유저, 도입 1회 확립 후 불변). 숫자/게이지 유저 비노출
• 엔딩 규칙: doubt≥30→처단(캐논) / trust≥60∧doubt<20→영원 / default→구원

코드 vs LLM 경계

개념	구현	타입
카드 진행(next 링크, canon 읽기)	services/story.py 상태머신	결정적 코드
선택지 → 신뢰축 반영	선택 매핑 + state 커밋	결정적 코드
자유채팅 개입 포켓	guard → character → director	ADK 파이프라인
R-회피사다리/약점반응	guard 규칙 + character instruction 주입	BaseAgent + instruction
숨은 상태	session.state + FunctionTool → 포켓 종료 시 커밋	ADK state
수렴 판정	director 구조화 출력 + services/pocket.py 코드 재검증	LlmAgent + 코드
엔딩 분기	ending_rules 조건식 평가	결정적 코드
스포일러 방어	beat_id ≤ 현재 필터 + before_model 콜백	콜백

개입 포켓 파이프라인 (escalate 격리 규칙 적용)

pocket_session (SequentialAgent)
├── pocket_context_loader                  ← BaseAgent: 카드 브리프 + 신뢰 레벨 결 로드
├── turn_loop (LoopAgent max=카드별 상한)
│   ├── input_guard                        ← BaseAgent: 세계관 이탈/정체직격/약점 감지
│   ├── character                          ← LlmAgent: 카르밀라 (시트+화법6규칙+R카드+신뢰별 결)
│   └── director                           ← LlmAgent: 비트 달성/이탈/신뢰반영/수렴 → escalate
└── pocket_closer (LoopAgent max=1)        ← 강제 수렴 내레이션 + 상태 커밋 → 다음 카드 복귀

마일스톤

• M0 — 스캐폴드 (0.5일): git init(로컬만, 원격 푸시는 추후) · engine/ 뼈대 · 의존성 · CLAUDE.md 데이터 모델 섹션 갱신 · 본 문서
• M1 — 콘텐츠 계약 (1일): 비트카드/챕터/캐릭터 Pydantic 스키마 + python -m engine.schemas.validate content/ · 변환 스크립트 · next 링크 무결성 검사(고아/끊긴 체인). 검증 기준: 기존 61카드 통과
• M2 — 결정적 리딩 루프 (1일): entry_beat부터 canon 페이징 · 선택지 신뢰축 반영 · 쇠약도 단조 증가 · LLM 없이 CLI로 E01~E06 통독 + 엔딩 3종 도달 확인
• M3 — ADK 개입 포켓 (2~3일, 핵심): 턴 파이프라인 · 카르밀라 instruction · director 구조화 판정(FunctionTool→state) · guard · adk web으로 포켓 1개(E06-09 권장) 집중 검증
• M4 — 전체 관통 (1~2일): 리딩 루프 ↔ 포켓 연결 · E01→엔딩 전체 플레이 · 턴 로깅 플러그인 · 시연(CLI + adk web)
• M5 — MVP 이후: FastAPI router + 리딩 UI · GraphRAG(kb_query 활성화) · 평가 하네스 · style_critic 루프

폴더 구조

sorac/
├── engine/
│   ├── agent.py / app.py / model.py / router.py
│   ├── schemas/        beatcard.py · chapter.py · character.py · validate.py
│   ├── services/       story.py · pocket.py · state.py · retrieval.py(2단계 스텁)
│   ├── repositories/   content.py · playlog.py
│   ├── agents/         input_guard.py · pocket_context_loader.py
│   ├── sub_agents/     character/ · director/
│   ├── tools/          state/ (update_trust.py, mark_beat.py) · retrieval/(스텁)
│   ├── callbacks/ · plugins/logging.py · instructions/
├── content/            beatcards/ · chapters/ · characters.yaml (M1에서 적재)
├── scripts/            beatcard_convert.py
├── tests/
└── docs/plans/mvp.md   (본 문서)

결정 로그

• 데모 프론트: 엔진 우선, UI 최소 (유저 확정)
• E01_구현계획.drawio 무시 (유저 지시) — 씬 설계 근거로 쓰지 않음
• 비트카드 MD가 콘텐츠 권위, reference 내 YAML은 파생물 (승인)
• CLAUDE.md "YAML 4종" 섹션 → A안 3레이어로 갱신 (승인)
• E07~E15: MD만 존재, MVP 범위 밖