# Phase 5 Reference Analysis

## 1. 참조한 오픈소스 목록

- `참고/ontocast-main`
- `참고/neo4j-graphrag-python-main`
- `참고/knowledge_agent-main`
- `참고/OpenDeepResearcher-main`
- `참고/instructor-main`
- `참고/guardrails-main`
- Phase 1 계열 참고: `playwright-main`, `trafilatura-master`, `crawl4ai-main`, `firecrawl-main`

## 2. 각 오픈소스에서 참고한 코드 구조

- ontocast: Pydantic report model, RDF triple payload, graph update/fix model, external evidence request 분리.
- neo4j-graphrag: `NodeType`, `RelationshipType`, `GraphSchema`, constraint/property schema, storage/query layer 분리.
- knowledge_agent: LangGraph state machine, role별 node, state에 todo/complete/report를 축적하는 loop.
- OpenDeepResearcher: query generation, source fetch, relevance evaluation, context extraction, iterative refinement loop.
- instructor: response model 중심 structured output, retry/validation exception 경계.
- guardrails: validation outcome, validator/reask/on-fail action 분리.

## 3. 현재 프로젝트에 직접 적용한 구조

- Ontology schema를 DB registry로 분리: `OntologyEntityType`, `OntologyRelationType`.
- Claim과 graph fact를 분리: `Claim`은 provenance/evidence, `OntologyTriple`은 graph fact.
- Schema evolution을 review 대상으로 분리: `OntologyProposal`.
- Ontology가 모르는 영역을 별도 객체로 관리: `KnowledgeGap`.
- Domain-specific relation/type alias는 `crawler_platform/app/adapters`로 분리.
- Knowledge gap을 research queue item으로 변환하는 `GapTaskPlanner` 추가.

## 4. 제외한 구조와 제외 이유

- Neo4j 전용 driver/query 구조: 현재 저장소는 SQLAlchemy/SQLite 중심이라 storage abstraction만 반영.
- LangGraph/MCP runtime: 현재 앱에 무거운 agent runtime을 넣기보다 queue/state 구조만 반영.
- OpenDeepResearcher의 외부 검색 API 호출: 네트워크/API 의존이 크므로 research task 추상화만 반영.
- Instructor/Guardrails 라이브러리 직접 의존: 현재 provider 독립 구조를 유지하기 위해 schema/retry/validation 개념만 반영.

## 5. 새 core architecture 방향

```text
Crawler / Browser
→ Main Content Extraction
→ Semantic Cleaning
→ Structured Document
→ Structured Extraction
→ Validation
→ Ontology Registry
→ Claim / Evidence
→ Ontology Triple
→ Knowledge Gap
→ Gap-driven Research Queue
→ Governance Proposal
```

## 6. 기존 domain-specific hardcoding 제거 방향

- `relation_schema.py`에서 perfume relation rule을 제거하고 perfume adapter로 이동.
- `entity_normalizer.py`에서 perfume alias를 제거하고 adapter 기반 normalization으로 변경.
- Core validation은 config/registry/adapter constraint만 사용하도록 변경.
- Multi-domain test에서 `academic` domain의 `authoredBy` relation이 perfume adapter 없이 동작함을 검증.

## 7. 남은 Phase 6 후보

- page classifier와 content zone도 adapter 기반으로 분리.
- external search planner를 gap-driven research loop에 연결.
- schema proposal approve/reject API와 migration history 추가.
- source conflict resolver를 triple merge 단계에 더 깊게 연결.