아키텍처
헥사고날 백엔드와 하네스
구성
| 갈래 | 내용 |
|---|---|
| 백엔드 | FastAPI — 모듈러 모놀리스 + 헥사고날, Port/Adapter, Fractal 11-File Set |
| DB | PostgreSQL + alembic + pgvector (SQLAlchemy 2.0, psycopg 3) |
| 외부 호출 | httpx, google-genai, anthropic SDK |
| 계층 강제 | import-linter 로 의존 방향을 검사 |
| 프론트 | Next.js 16 (App Router), React 19, TypeScript, Tailwind 4 — 플레이 화면 · 인스펙터 · 하네스 공개 화면 |
| 개발 허브 | Jekyll — 기획·칸반·일정·데브로그 |
| 연구 기록 | 별도 Jekyll 사이트 — research.whoareryu.cloud |
Agent Harness
모델이 실패해도 게임이 무너지지 않게 하는 경로입니다. 설계 원칙은 「하네스는 프롬프트가 아니라 코드」입니다.
- JSON 파싱
- 스키마 검증
- 사실 층 검사 — 금칙어, 소실 인물, 미지 인물, 한국어 전용, 행동 어휘, 근거 인용
- 재생성 2회
- 폴백
LLM 이 말하는 7개 자리에 역할 프롬프트(agent · planner · manager · advisor · evaluator)가 있고, 구조화 출력 스키마는 enum 제약을 타입에 직접 넣었습니다. 7세 정책 프롬프트에는 on/off ablation 스위치가 있습니다.
BeyondBob Engine
어댑터 위 계층 전체가 BeyondBob Engine 입니다. 시나리오는 BaseScenario 계약을 따르는 도메인 어댑터의 인스턴스이고, 코어는 시나리오의 용어를 모릅니다. scenario_a · scenario_audit · scenario_example 이 실제로 병존하며, 어댑터에서 용어·시나리오·정답 주장 목록·프롬프트만 교체합니다.
모델 구성
슬롯별로 다르고, .env 의 provider 와 모델 이름 두 줄로 바꿉니다. 엔진 코드는 바뀌지 않습니다.
| 슬롯 | 제출용 | 로컬 개발·롤백 |
|---|---|---|
| Core (계획·관리·채점) | claude-sonnet-5 | gemma4:12b (think off) |
| NPC (인물 대화) | claude-haiku-4-5 | kanana1.5:8b |
| 임베딩 | gemini-embedding-001 (요청·반환 2560) | bge-m3 (요청 2560 · 실제 반환 1024) |
왜 외부 API 로 바꿨나
성능이 아니라 서빙 제약 때문입니다. 심사 기간에 실제로 접속 가능한 서비스여야 하는데, 로컬 구성은 GPU 1장(16 GiB)에 Core·NPC 가 함께 올라가(12.3 GiB) 가용성이 홈서버와 홈 회선에 묶입니다. 클라우드 GPU 는 45일 24시간 기준 $1,100~1,600 으로 추정했고, 외부 API 는 판당 $0.35~2.1, 완주 100명 기준 $35~210 으로 봤습니다. 로컬 구성은 비교 기준선이자 롤백 경로로 남겼습니다.