125 lines
6.2 KiB
Markdown
125 lines
6.2 KiB
Markdown
|
# 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)를 참조.
|