Initial commit

README.md

@@ -8,4 +8,103 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## ⚙️ AI 서버 (ai_server/)
+
+### 역할 & 데이터 흐름
+
+1. **게임 서버 요청 수신(`app.py`)**
+   - 최소 입력만 와도 동작: `{ text, npc_id, player_id, ... }`
+   - 옵션: 상태/컨텍스트 부족 시 `rag/docs/npc_config.json` 등에서 NPC 메타를 조회해 보강
+
+2. **전처리·프롬프트 구성(`pipeline/preprocess.py`, `utils/context_parser.py`, `manager/prompt_builder.py`)**
+   - 태그/컨텍스트/플레이어 발화를 묶어 `<SYS>`, `<CTX>`, `<PLAYER>`, `<NPC>` 포맷으로 구성
+
+3. **추론 요청(`utils/hf_client.py`, `models/fallback_model.py`, `pipeline/generator.py`)**
+   - 조건 불충족 input → `fallback_model.py`에서 대체 응답 생성
+   - 조건 충족 input → `generator.py`에서 payload 구성 후 HF Space `/predict_main` POST
+
+4. **후처리(`pipeline/postprocess.py`)**
+   - 모델 응답에서 **대사 텍스트, delta, flag**를 파싱·정규화
+   - flags → 시그모이드+threshold, delta → 범위 클램프·라운딩
+
+5. **게임 서버 응답(`schemas.py`)**
+   - 표준 JSON으로 반환
+   ```json
+   {
+     "text": "NPC의 대답...",
+     "delta": {"trust": 0.10, "relationship": 0.08},
+     "flags": {"give_item": true, "npc_main_story": false},
+     "meta": {"npc_id": "mother_abandoned_factory"}
+   }
+   ```
+
+---
+
+### 📁 디렉토리 구조
+
+```bash
+ai-server/
+├── app.py                  # FastAPI 엔트리포인트
+├── config.py               # 서버 설정 및 모델 경로 관리
+├── schemas.py              # 요청/응답 데이터 구조 정의
+├── requirements.txt        # 의존성 패키지 목록
+├── pipeline/               # 대화 흐름 처리 모듈
+│   ├── preprocess.py       # 입력 전처리 및 프롬프트 구성
+│   ├── postprocess.py      # 모델 출력 후처리
+│   └── generator.py        # 모델 추론 요청 처리
+├── rag/                    # RAG 기반 flag 해석 모듈
+│   ├── rag_manager.py
+│   └── docs/npc_config.json
+├── utils/                  # 유틸리티 모듈
+│   ├── hf_client.py        # HF API 통신
+│   └── context_parser.py   # 대화 맥락 파싱
+├── models/                 # 모델 로딩 및 fallback 처리
+│   └── model_loader.py
+```
+
+---
+
+### 🧩 최신 RAG 타입별 매핑 (11종)
+
+| **type** | **조회 시점** | **조회 조건** | **사용 모듈/함수** | **주요 목적** |
+|----------|--------------|---------------|--------------------|---------------|
+| `trigger_def` | preprocess_input | npc_id, quest_stage | retrieve(...) | 메인 경로 조건 판정 |
+| `fallback` | preprocess_input | npc_id, quest_stage | retrieve(...) | fallback prompt 구성 |
+| `forbidden_trigger_list` | preprocess_input | npc_id | _load_forbidden_trigger_data | 금지 트리거 감지 |
+| `trigger_meta` | preprocess_input | npc_id, trigger | _load_trigger_meta | 특수 fallback 시 delta/action 확정 |
+| `lore` | build_main_prompt | npc_id, quest_stage/any | RAG main docs | 세계관/배경 설명 |
+| `description` | build_main_prompt | npc_id, quest_stage | RAG main docs | 현재 상황 설명 |
+| `flag_def` | postprocess_pipeline | npc_id, quest_stage, flag_name | pre_data["rag_main_docs"] | flag threshold/예시 문장 |
+| `main_res_validate` | postprocess_pipeline | npc_id, quest_stage | pre_data["rag_main_docs"] | 응답 검증 기준 |
+| `npc_persona` | build_main_prompt | npc_id | retrieve(...) | NPC 성격·특성 반영 |
+| `dialogue_turn` | postprocess_pipeline | npc_id, quest_stage | retrieve(...) | 대화 예시 참조 |
+| *(없음)* | fallback_final_check | pre_data["trigger_meta"] | - | 응답 의미 일치 검증 |
+
+---
+
+### 📌 데이터 흐름 요약
+
+1. **preprocess_input()**
+   - trigger_def → 메인 조건 판정
+   - forbidden_trigger_list + trigger_meta → 특수 fallback 감지
+   - fallback → 일반 fallback 스타일
+
+2. **build_main_prompt()**
+   - lore + description + npc_persona → 메인 prompt 컨텍스트 구성
+
+3. **build_fallback_prompt()**
+   - fallback_style + trigger_meta → fallback prompt 구성
+
+4. **postprocess_pipeline()**
+   - flag_def → flag threshold/예시
+   - main_res_validate → 응답 검증
+
+5. **fallback_final_check()**
+   - trigger_meta → delta/action 의미 일치 검증
+
+---
+
+### 🔗 테스트
+업데이트 예정
+
+---