AI/PHASE3_OPTION_B.md

# Phase 3 Option B: OntoCast GraphUpdate 검증 (Hybrid 접근법)

**완료일**: 2026-05-14  
**상태**: ✅ Acceptance Gate 3 Option B 검수 준비 완료

## 개요

Phase 3 Option B는 **점진적 OntoCast 통합** (Hybrid approach)입니다.

### 핵심 전략
- **Phase 0-2 유지**: 현재 경량 구조 그대로
- **GraphUpdate 검증 추가**: OntoCast의 SPARQL 쿼리 검증
- **Critic loop 준비**: Phase 4+에서 추가 가능하도록 설계

```
시간 축
────────────────────────────────────────
Phase 0-2: 경량 추출 (완료)
Phase 3 MVP (A): 엔티티 검증 (완료)
Phase 3 Option B: SPARQL 검증 (지금 이것) ← 지금 여기
Phase 4+: Critic loop + Fuseki (향후)
```

## 구현 내용

### 1. SPARQL 검증기 (`SPARQLValidator`)

**SPARQL 쿼리 기본 검증**:
```python
✓ 문법 검사: 괄호/중괄호 균형, 키워드 확인
✓ SQL 인젝션 패턴 감지
✓ 프리픽스 선언 확인
✓ 쿼리 크기 경고 (너무 큰 쿼리 감지)
```

### 2. OntoCastValidator (Phase 3 Option B)

**GraphUpdate 검증**:
```python
단계 1: SPARQL 문법 검증
  - 빈 쿼리 감지
  - 괄호 불균형 감지
  - 위험한 패턴 감지 (SQL injection 등)

단계 2: 작업 순서 검증
  - 안전한 순서: INSERT → UPDATE → DELETE
  - 불안전한 순서 감지 (DELETE 후 INSERT 등)

단계 3: 프리픽스 검증
  - 선언되지 않은 프리픽스 감지
  - 표준 RDF 프리픽스 자동 인식

단계 4: 작업 수량 체크
  - 빈 작업 목록 경고
  - 과도하게 큰 작업 경고 (100개 초과)
```

### 3. 테스트 결과 (모두 통과 ✅)

| 테스트 | 설명 | 결과 |
|-------|------|------|
| Valid SPARQL | 올바른 INSERT 작업 | ✅ 통과 |
| Invalid syntax | 괄호 불균형 | ✅ 감지 |
| Safe order | INSERT → UPDATE → DELETE | ✅ 통과 |
| Unsafe order | DELETE 후 INSERT | ✅ 감지 |
| Undeclared prefix | 선언되지 않은 프리픽스 | ✅ 경고 |
| Utility functions | SPARQLValidator 직접 사용 | ✅ 통과 |

## 아키텍처: Phase 0-2와의 호환성

```
┌─────────────────────────────────────┐
│  OntologyGuard (통합 인터페이스)     │
└──────────┬──────────────────────────┘
           │
     ┌─────┴──────────┐
     │                │
  경량 검증        OntoCast 검증
(Phase 3 MVP)   (Phase 3 Option B)
  ↓                ↓
엔티티/관계      SPARQL 쿼리
검증             검증
```

두 검증을 **동시에 사용 가능**:
```python
# 둘 다 활성화
guard_entity = OntologyGuard(validator_type="lightweight")
guard_sparql = OntologyGuard(validator_type="ontocast")

# 또는 런타임에 선택
validator_type = "ontocast" if use_ontocast else "lightweight"
guard = OntologyGuard(validator_type=validator_type)
```

## 파일 구조

```
신규 생성:
  ✨ ont_platform/core/validation/ontocast_validator.py
     ├── SPARQLValidator: 기본 SPARQL 검증
     ├── OntoCastValidator: GraphUpdate 검증
     └── GraphUpdate: 검증 결과 모델

수정:
  ✏️ ont_platform/core/validation/validators.py
     (ValidatorFactory에 OntoCast 지원 추가)
  ✏️ ont_platform/core/validation/__init__.py
     (OntoCastValidator export)

테스트:
  ✨ test_phase3_option_b.py (6개 테스트, 모두 통과)
```

## Acceptance Gate 3 Option B 상태

### ✅ 완료된 항목

- [x] SPARQL 문법 검증
  - 괄호/중괄호 균형 ✓
  - 키워드 확인 ✓
  - SQL 인젝션 패턴 감지 ✓

- [x] 안전한 작업 순서 검증 (INSERT → UPDATE → DELETE)
  - 불안전한 순서 감지 ✓
  - 순서 강제 가능 ✓

- [x] 프리픽스 선언 검증
  - 미선언 프리픽스 감지 ✓
  - 표준 RDF 프리픽스 자동 인식 ✓

- [x] Phase 0-2 회귀 없음
  - 경량 검증 여전히 작동 ✓
  - API 호환성 유지 ✓

### ⏳ 향후 추가 예정 (Phase 4+)

#### Critic Loop 통합
```python
# Phase 4에서 구현될 것
if validation_errors:
    suggestions = generate_critic_suggestions(errors)
    retry_result = await llm.retry(original_query, suggestions)
```

#### RDF 일관성 검증
```python
# Fuseki 사용 가능 시
if fuseki_available:
    # 1. 쿼리 실행 시뮬레이션
    # 2. 결과 그래프 검증
    # 3. 일관성 확인
    validate_rdf_consistency(update)
```

#### GraphUpdate 추적
```python
# 감사 로그
graph_update_history.append({
    "timestamp": now,
    "operation_count": len(operations),
    "validation_status": "passed",
    "execution_time": elapsed_ms,
})
```

## 향후 옵션

### Phase 3 Option A (경량 MVP) vs Option B (Hybrid) 비교

| 항목 | Option A (MVP) | Option B (Hybrid) |
|------|---|---|
| 엔티티 검증 | ✅ | ✅ |
| SPARQL 검증 | ❌ | ✅ |
| OntoCast 의존성 | ❌ | 부분적 |
| Critic loop | ❌ (Phase 4+) | 준비됨 (Phase 4+) |
| 구현 복잡도 | 낮음 | 중간 |
| Phase 0-2 호환성 | ✅ | ✅ |

## 설계의 확장성

### ValidatorFactory 플러그인 구조

현재:
```python
ValidatorFactory.create("lightweight")   # Option A
ValidatorFactory.create("ontocast")      # Option B (지금)
```

향후 추가 가능:
```python
ValidatorFactory.create("guardrails")    # Phase 3+ (제3 선택지)
ValidatorFactory.create("full_ontocast") # Phase 4+ (완전통합)
```

## Phase 3 완료 상태 요약

| 선택지 | 상태 | 특징 |
|-------|------|------|
| **A: 경량 MVP** | ✅ 완료 | 엔티티/관계 검증만 |
| **B: Hybrid** | ✅ 완료 | + SPARQL 검증 |
| **C: Guardrails** | ⏳ 준비 | + Reask 루프 |

**현재**: 옵션 A + B 모두 선택 가능한 상태

## 다음 단계

### Phase 4: Neo4j GraphRAG (권장)
- RDF ↔ Property Graph 프로젝션
- Vector 검색 + Entity Resolver
- GraphUpdate 실행 시뮬레이션

### 또는: Phase 3+ (향후)
- Guardrails 통합 (더 정교한 reask)
- Full OntoCast (Critic loop 본격화)
- Fuseki 연동 (RDF 저장소)

## 참고 문헌

- 설계서 §5 Phase 3 (p. 222-224)
- OntoCast sparql_models.py (GraphUpdate 모델)
- SPARQL 1.1 명세 (검증 규칙)