# Phase 0 — 다음 작업자 핸드오프

본 문서는 이 프로젝트를 이어받는 AI 에이전트 또는 개발자가 즉시 작업을 시작하기 위한 핸드오프 노트다.

## 현재 상태 (지금까지 완료된 것)

- [x] **0.1 일부**: 폴더 골격, `pyproject.toml`, `README.md`, `.env.example`, `.gitignore`, `NOTICE` 생성
- [x] **설계 문서**: [../통합설계서.md](../통합설계서.md) 배치 완료 (모든 작업의 기준)

## 즉시 시작할 작업 (순서대로)

### 0.1 (잔여): OntoCast vendored copy

**근거**: 통합설계서 §9.1, OntoCast 분석 §13.1

```powershell
# 1. 원본을 vendored/ontocast로 복사 (.git 제외)
Copy-Item -Path "C:\Users\lasta\MyProject\AI\참고\ontocast-main\*" `
          -Destination "C:\Users\lasta\MyProject\AI\ontology_platform\vendored\ontocast\" `
          -Recurse -Exclude ".git",".github",".venv","node_modules"

# 2. 원본 LICENSE 및 NOTICE를 vendored/ontocast/ 안에 그대로 유지
# 3. NOTICE 파일의 "(원본 저장소 URL 기입)" 부분을 실제 URL로 채우기
# 4. git init (아직 안 했다면)
cd C:\Users\lasta\MyProject\AI\ontology_platform
git init
git add .
git commit -m "Initial scaffold: folder skeleton, design doc, NOTICE"
```

**확인 사항**:
- [ ] `vendored/ontocast/` 안에 원본 LICENSE 파일이 있어야 한다
- [ ] `vendored/ontocast/pyproject.toml`은 그대로 두되, 우리 `pyproject.toml`이 우선
- [ ] NOTICE 파일의 OntoCast 항목에 실제 source URL 기입

### 0.2: `select_ontology.py` 버그 수정

**근거**: 통합설계서 §5 Phase 0, OntoCast 분석 §13.1 / §9.1 (1번)

**문제**: `vendored/ontocast/ontocast/agent/select_ontology.py`에서 None 선택 인덱스 불일치.
- 코드는 `answer_index == 0`을 None으로 처리
- 그러나 dynamic model은 `1..num_ontologies+1` 범위 사용
- 실제 None 선택은 `num_ontologies + 1`이어야 자연스러움

**조치**:
1. 해당 함수의 분기 로직을 `answer_index == num_ontologies + 1` 또는 동등한 표현으로 수정
2. **수정 사실을 파일 상단 주석으로 명시** (Apache 2.0 의무): 예) `# MODIFIED 2026-MM-DD: Fixed None index inconsistency, see docs/통합설계서.md §5 Phase 0`
3. 회귀 테스트 작성: `tests/unit/test_select_ontology.py`
   - 케이스 1: ontology가 0개일 때 → None 반환
   - 케이스 2: ontology가 N개, LLM이 1~N 선택 → 해당 ontology 반환
   - 케이스 3: ontology가 N개, LLM이 N+1 선택 → None 반환

### 0.3: `convert_document.py` 다중 파일 처리 확장

**근거**: 통합설계서 §5 Phase 0, OntoCast 분석 §13.1 (3번) / §21.1 (4번)

**문제**: `convert_document()`가 "processing only one file"로 주석 처리되어 있고, 다중 파일 처리 시 마지막 파일 기준으로만 상태가 업데이트됨.

**조치**:
1. 입력 파일 목록을 순회하며 각 파일을 독립 `ContentUnit`으로 만들어 `AgentState.content_units`에 누적
2. 동일 corpus 내 파일들이 함께 처리되도록 보장 (각 파일이 별도 doc IRI를 가짐)
3. 회귀 테스트: 2개 PDF를 한 번에 처리 → 둘 다 처리되어야 함

### 0.4: Robyn → FastAPI 재작성

**근거**: 통합설계서 §11 (기술 스택), OntoCast 분석 §13 (API 명세)

**조치**:
1. `platform/api/main.py` 생성 (FastAPI app 인스턴스)
2. OntoCast 분석 §13.1~§13.4의 4개 endpoint를 FastAPI로 동일 시맨틱 재작성:
   - `GET /health`
   - `GET /info`
   - `POST /process` (JSON + multipart)
   - `POST /flush` (관리자 권한 + confirmation token, 분석 §21.1 #6)
3. OntoCast의 `ToolBox` 의존성 주입은 FastAPI `Depends`로 변환
4. `uvicorn platform.api.main:app --reload`로 기동 가능해야 함

**중요**: OntoCast 코어 모듈(`stategraph/`, `agent/`, `onto/`, `tool/`)은 **건드리지 않는다**. API 레이어만 재작성.

### 0.5: Pydantic Settings 정리

**근거**: 통합설계서 §5 Phase 0 (5번), OntoCast 분석 §15

**조치**:
1. `platform/config.py` 생성
2. `pydantic-settings`의 `BaseSettings`로 `.env` 로딩
3. **Phase 0에서는 filesystem 모드만 활성화** (Fuseki/Neo4j는 Phase 4에서):
   - `STORAGE_BACKEND=filesystem` 강제
   - Neo4j/Fuseki 변수가 채워져 있어도 무시
4. OntoCast의 기존 `Config` 클래스는 우리 `Settings`에서 만들어 주입

### 0.6: End-to-end 통합 테스트

**근거**: 통합설계서 §5 Phase 0 Acceptance Gate

**조치**:
1. `vendored/ontocast/data/`의 예제 JSON 또는 PDF 1개를 fixture로 복사 → `tests/fixtures/`
2. `tests/integration/test_phase0_e2e.py` 작성:
   - FastAPI `TestClient`로 `/process` 호출
   - 응답에 `ontology` TTL과 `facts` TTL 둘 다 포함
   - `working_directory/`에 ontology/facts 파일 생성 확인
   - BudgetTracker가 LLM call/triple count를 0보다 큰 값으로 기록

### 0.7: Acceptance Gate 0 체크

통합설계서 §5 Phase 0 Acceptance Gate의 4개 체크박스를 PR에 인용하며 모두 확인:

- [ ] 단일 PDF 또는 JSON 입력 → ontology TTL + facts TTL이 filesystem에 생성됨
- [ ] `/health`, `/info`, `/process` (FastAPI 버전) 정상 동작
- [ ] BudgetTracker가 LLM call/triple count를 정확히 기록
- [ ] LangGraph 워크플로우(CONVERT→CHUNK→...→SERIALIZE) 전 노드가 traceable

## 작업 시 준수사항

1. **PR 단위**: 위의 0.1~0.7 각각을 별도 PR/커밋으로 분리. 하나의 PR에 여러 단계를 섞지 않는다.
2. **PR 설명에 근거 인용**: 예) "통합설계서 §5 Phase 0 (3번)에 따라 다중 파일 처리 확장. OntoCast 분석 §13.1 인용."
3. **vendored/ 수정 시 라이선스 의무**:
   - 수정한 파일 상단에 `# MODIFIED YYYY-MM-DD: <한 줄 설명>` 주석 추가
   - 원본 LICENSE/NOTICE 파일은 절대 삭제하지 않는다
4. **Phase 1로 넘어가지 말 것**: Acceptance Gate 0 통과 전까지 Trafilatura/Crawl4AI/Guardrails/Neo4j GraphRAG 의존성을 활성화하거나 import하지 않는다. (`pyproject.toml`에 명시되어 있더라도 코드에서 사용 금지)

## Phase 1 이후 핸드오프

Phase 0 완료 후, 본 폴더에 `PHASE1_NEXT_STEPS.md`를 작성하여 다음 작업자에게 동일한 형식으로 핸드오프한다. 통합설계서 §12 Phase 1 작업 단위(1.1~1.7)를 참조.