6.2 KiB
6.2 KiB
Phase 0 — 다음 작업자 핸드오프
본 문서는 이 프로젝트를 이어받는 AI 에이전트 또는 개발자가 즉시 작업을 시작하기 위한 핸드오프 노트다.
현재 상태 (지금까지 완료된 것)
- 0.1 일부: 폴더 골격,
pyproject.toml,README.md,.env.example,.gitignore,NOTICE생성 - 설계 문서: ../통합설계서.md 배치 완료 (모든 작업의 기준)
즉시 시작할 작업 (순서대로)
0.1 (잔여): OntoCast vendored copy
근거: 통합설계서 §9.1, OntoCast 분석 §13.1
# 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이어야 자연스러움
조치:
- 해당 함수의 분기 로직을
answer_index == num_ontologies + 1또는 동등한 표현으로 수정 - 수정 사실을 파일 상단 주석으로 명시 (Apache 2.0 의무): 예)
# MODIFIED 2026-MM-DD: Fixed None index inconsistency, see docs/통합설계서.md §5 Phase 0 - 회귀 테스트 작성:
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"로 주석 처리되어 있고, 다중 파일 처리 시 마지막 파일 기준으로만 상태가 업데이트됨.
조치:
- 입력 파일 목록을 순회하며 각 파일을 독립
ContentUnit으로 만들어AgentState.content_units에 누적 - 동일 corpus 내 파일들이 함께 처리되도록 보장 (각 파일이 별도 doc IRI를 가짐)
- 회귀 테스트: 2개 PDF를 한 번에 처리 → 둘 다 처리되어야 함
0.4: Robyn → FastAPI 재작성
근거: 통합설계서 §11 (기술 스택), OntoCast 분석 §13 (API 명세)
조치:
platform/api/main.py생성 (FastAPI app 인스턴스)- OntoCast 분석 §13.1~§13.4의 4개 endpoint를 FastAPI로 동일 시맨틱 재작성:
GET /healthGET /infoPOST /process(JSON + multipart)POST /flush(관리자 권한 + confirmation token, 분석 §21.1 #6)
- OntoCast의
ToolBox의존성 주입은 FastAPIDepends로 변환 uvicorn platform.api.main:app --reload로 기동 가능해야 함
중요: OntoCast 코어 모듈(stategraph/, agent/, onto/, tool/)은 건드리지 않는다. API 레이어만 재작성.
0.5: Pydantic Settings 정리
근거: 통합설계서 §5 Phase 0 (5번), OntoCast 분석 §15
조치:
platform/config.py생성pydantic-settings의BaseSettings로.env로딩- Phase 0에서는 filesystem 모드만 활성화 (Fuseki/Neo4j는 Phase 4에서):
STORAGE_BACKEND=filesystem강제- Neo4j/Fuseki 변수가 채워져 있어도 무시
- OntoCast의 기존
Config클래스는 우리Settings에서 만들어 주입
0.6: End-to-end 통합 테스트
근거: 통합설계서 §5 Phase 0 Acceptance Gate
조치:
vendored/ontocast/data/의 예제 JSON 또는 PDF 1개를 fixture로 복사 →tests/fixtures/tests/integration/test_phase0_e2e.py작성:- FastAPI
TestClient로/process호출 - 응답에
ontologyTTL과factsTTL 둘 다 포함 working_directory/에 ontology/facts 파일 생성 확인- BudgetTracker가 LLM call/triple count를 0보다 큰 값으로 기록
- FastAPI
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
작업 시 준수사항
- PR 단위: 위의 0.1~0.7 각각을 별도 PR/커밋으로 분리. 하나의 PR에 여러 단계를 섞지 않는다.
- PR 설명에 근거 인용: 예) "통합설계서 §5 Phase 0 (3번)에 따라 다중 파일 처리 확장. OntoCast 분석 §13.1 인용."
- vendored/ 수정 시 라이선스 의무:
- 수정한 파일 상단에
# MODIFIED YYYY-MM-DD: <한 줄 설명>주석 추가 - 원본 LICENSE/NOTICE 파일은 절대 삭제하지 않는다
- 수정한 파일 상단에
- 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)를 참조.