AI/README.md

# Ontology Platform

온톨로지 플랫폼은 웹에서 구조화된 지식(엔티티/관계)을 자동 추출, 검증, 저장하는 고속 시스템입니다.

**Phase 0-4** 전체 구현 완료 | 추출(10초) → 검증(<100ms) → 그래프 저장 → 벡터 검색

## 🚀 빠른 시작

### 1. 설치

```bash
# 기본 설치 (Phase 0-1: 추출)
pip install fastapi uvicorn pydantic trafilatura httpx

# Phase 2 추가 (동적 페이지)
pip install crawl4ai

# Phase 4 추가 (Neo4j)
pip install neo4j sentence-transformers
```

### 2. Phase 0-1만 사용 (가장 간단)

```bash
# API 서버 시작
python -m uvicorn ontology_platform.ont_platform.api.phase0_app:app --reload

# URL에서 추출
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://example.com"
```

### 3. Phase 4 (그래프 검색) 포함

```bash
# Neo4j 시작
docker-compose -f docker-compose.neo4j.yml up -d

# API 서버 시작
python -m uvicorn ontology_platform.ont_platform.api.phase0_app:app --reload

# 추출 → 수집 → 검색
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://example.com"
curl -X POST "http://localhost:8000/api/v1/search/ingest" -d '{"entities": [...], "relations": [...]}'
curl "http://localhost:8000/api/v1/search/vector?query=machine+learning"
```

## 📋 Phase별 기능

| Phase | 기능 | 시간 | 상태 |
|-------|------|------|------|
| 0-1 | HTML 추출 (Trafilatura) | 10-15초 | ✅ |
| 2 | 동적 페이지 (Crawl4AI) | 20-30초 | ✅ |
| 3A | 경량 검증 (Pydantic) | <100ms | ✅ |
| 3B | SPARQL 검증 | <500ms | ✅ |
| 4 | Neo4j + 벡터 검색 | 50-200ms | ✅ |

## 🎯 사용 예시

### 예시 1: 기본 추출 (10초)

```bash
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://wikipedia.org/wiki/Python"
```

응답:
```json
{
  "url": "https://wikipedia.org/wiki/Python",
  "title": "Python - Wikipedia",
  "entities": [
    {
      "id": "E_1",
      "label": "Python",
      "type": "ProgrammingLanguage",
      "confidence": 0.95
    }
  ],
  "relations": [...],
  "extraction_time_sec": 9.5,
  "validation_passed": true
}
```

### 예시 2: 동적 페이지 (25초)

```bash
curl -X POST "http://localhost:8000/api/v1/extract/url?url=https://app.example.com&profile=dynamic_page"
```

### 예시 3: 그래프 수집 + 검색

```bash
# 1. 추출
RESULT=$(curl -s -X POST "http://localhost:8000/api/v1/extract/url?url=https://example.com")

# 2. Neo4j에 수집
curl -X POST "http://localhost:8000/api/v1/search/ingest" \
  -H "Content-Type: application/json" \
  -d "{\"entities\": $(echo $RESULT | jq '.entities'), \"relations\": $(echo $RESULT | jq '.relations')}"

# 3. 벡터 검색
curl "http://localhost:8000/api/v1/search/vector?query=programming&limit=10"

# 4. 그래프 통계
curl "http://localhost:8000/api/v1/search/stats"

# 5. 엔티티 이웃
curl "http://localhost:8000/api/v1/search/entity/E_1?depth=1"
```

## 🔧 설정

### Phase 선택 (validators.py)

```python
# 경량 검증 (기본)
guard = OntologyGuard(validator_type="lightweight")

# SPARQL 검증
guard = OntologyGuard(validator_type="ontocast")
```

### Neo4j 연결 (neo4j_adapter.py)

```python
# 기본값
config = Neo4jConfig()  # localhost:7687

# 커스텀
config = Neo4jConfig(
    uri="bolt://custom-host:7687",
    username="user",
    password="pass",
    database="mydb"
)
adapter = Neo4jAdapter(config=config)
```

## 📊 API 문서

서버 시작 후:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

### 주요 엔드포인트

```
POST   /api/v1/extract/url              추출
GET    /api/v1/search/stats             통계
POST   /api/v1/search/vector            벡터 검색
GET    /api/v1/search/entity/{id}       이웃 탐색
POST   /api/v1/search/ingest            그래프 수집
```

## 🧪 테스트

```bash
# Phase 0-1
python test_phase0_extraction.py

# Phase 2
python test_phase2_crawl.py

# Phase 3A
python test_phase3_validation.py

# Phase 3B
python test_phase3_option_b.py

# Phase 4
python test_phase4_integration.py
```

## 📦 의존성

- **FastAPI**: API 프레임워크
- **Trafilatura**: HTML 추출
- **Crawl4AI**: 동적 크롤링 (선택)
- **Pydantic**: 데이터 검증
- **Neo4j**: 그래프 DB (선택)
- **SentenceTransformers**: 벡터 임베딩 (선택)

## 🐳 Docker

```bash
# Neo4j만
docker-compose -f docker-compose.neo4j.yml up -d

# 전체 스택 (향후)
docker-compose up -d
```

## 📚 상세 문서

- [구현 요약](IMPLEMENTATION_SUMMARY.md) - Phase 0-4 전체 개요
- [Phase 2](PHASE2_COMPLETION.md) - Crawl4AI 동적 크롤링
- [Phase 3A](PHASE3_COMPLETION.md) - 경량 검증
- [Phase 3B](PHASE3_OPTION_B.md) - SPARQL 검증
- [Phase 4](PHASE4_COMPLETION.md) - Neo4j 그래프 + 벡터 검색

## 🎓 설계 원칙

1. **Phase-gated**: 각 Phase는 선택사항
2. **Pluggable**: 여러 검증 방식 지원
3. **Async**: 높은 동시성
4. **Resilient**: 의존성 부재 시에도 동작

## 💡 다음 단계

### Phase 5: GraphRAG (선택)
- RDF ↔ Property Graph 변환
- Entity Resolver
- Subgraph retrieval

### Advanced Features
- Critic loop (자동 수정)
- Few-shot learning
- Zero-shot 분류

## 🔗 관련 링크

- [Neo4j 문서](https://neo4j.com/docs/)
- [SentenceTransformers](https://www.sbert.net/)
- [Trafilatura](https://trafilatura.python-engineering.com/)
- [FastAPI](https://fastapi.tiangolo.com/)

## 📝 라이센스

MIT License

---

**Version**: 0.4.0 (Phase 0-4 완료)  
**Updated**: 2026-05-14