AI/오픈소스분석자료/Guardrails_분석_및_기능명세.md

# Guardrails 프로젝트 분석 및 기능명세

분석 대상: `C:\Users\lasta\MyProject\AI\참고\guardrails-main`  
분석일: 2026-05-13  
목적: 범용 온톨로지 구축 플랫폼에서 LLM 생성 결과의 구조화, 검증, 실패 복구, 재질문, 운영형 검증 API의 기준 소스로 활용하기 위한 상세 분석

## 1. 프로젝트 개요

Guardrails는 Python 기반 LLM 신뢰성/구조화 출력 프레임워크이다. 핵심 목표는 LLM 입출력에 검증 규칙을 적용하고, 실패 시 정해진 정책에 따라 수정, 필터링, 예외, 재질문을 수행하며, 최종적으로 애플리케이션이 신뢰할 수 있는 구조화 데이터를 받도록 하는 것이다.

이 프로젝트는 온톨로지 구축 플랫폼에서 특히 유용하다. 온톨로지 생성 과정은 개념, 클래스, 속성, 관계, 제약조건, 근거 문장, provenance 같은 구조화 산출물이 필요하고, LLM 응답이 스키마를 어기거나 부정확한 관계를 만들면 이후 그래프 저장소와 추론 엔진까지 오염된다. Guardrails는 이 지점에서 “LLM 출력 검증 게이트” 역할을 그대로 수행할 수 있다.

주요 특징은 다음과 같다.

- `Guard` 중심의 LLM 호출 래퍼 및 검증 실행
- RAIL XML, Pydantic 모델, JSON Schema, 문자열 기반 출력 스키마 지원
- validator 기반 입력/출력 검증
- 실패 시 `reask`, `fix`, `filter`, `refrain`, `noop`, `exception`, `fix_reask`, `custom` 정책 적용
- JSON 출력 파싱, 타입 보정, 추가 키 제거, JSON Schema 검증
- 검증 실패 영역만 재질문하는 reask 루프
- 동기/비동기/스트리밍 검증 실행
- Guardrails Hub validator 설치/등록 체계
- CLI 및 독립 서버 실행 지원
- LangChain, LlamaIndex, LiteLLM, OpenAI, HuggingFace 등 LLM/프레임워크 연동
- telemetry, history, validator log 기반 실행 추적
- Text2SQL, document store, vector DB 같은 예시 애플리케이션 제공

## 2. 기술 스택

- 언어: Python 3.10 이상
- 데이터 모델: Pydantic v2, dataclass
- 스키마/파싱: JSON Schema 2020-12, lxml, jsonschema, jsonref
- LLM 연동: OpenAI SDK, LiteLLM, HuggingFace, Manifest optional
- CLI: Typer, Click, Rich
- 재시도/실행 보조: tenacity, contextvars
- 벡터 검색 optional: FAISS, numpy
- SQL optional: SQLAlchemy, sqlvalidator, sqlglot
- 관측성: OpenTelemetry, Guardrails Hub telemetry
- 프레임워크 통합: LangChain Core Runnable, LlamaIndex
- 서버 optional: `guardrails-api`
- 라이선스: Apache License 2.0

## 3. 최상위 구조

```text
guardrails-main/
  guardrails/                    # SDK 본체
    guard.py                     # Guard 메인 엔트리포인트
    async_guard.py               # AsyncGuard
    validator_base.py            # Validator 베이스 및 registry
    validator_service/           # 동기/비동기 validator 실행 엔진
    run/                         # Runner, StreamRunner, AsyncRunner
    schema/                      # RAIL/Pydantic/primitive schema 처리
    actions/                     # reask/filter/refrain 실패 처리 객체
    classes/                     # history, validation outcome/logs, execution models
    llm_providers.py             # LLM 호출 어댑터
    formatters/                  # JSON formatter, JSONFormer 어댑터
    cli/                         # configure/create/start/validate/hub/db/watch
    hub/                         # Hub validator install/registry
    integrations/                # LangChain, LlamaIndex, Databricks
    applications/                # Text2SQL 예시
    document_store.py            # 문서/페이지 저장 및 vector DB 검색 추상화
    vectordb/                    # VectorDBBase, Faiss
  docs/                          # 공식 문서, 예제, API reference
  tests/                         # 단위/통합 테스트
  server_ci/                     # 서버 Docker/CI 검증 구성
```

패키지의 실질적인 공개 API는 `Guard`, `AsyncGuard`, `Validator`, `OnFailAction`, `ValidationOutcome`, validator registry, schema 변환 함수군이다. 
우리 프로젝트에서 기준 소스로 삼을 우선순위는 `guard.py`, `validator_base.py`, `validator_service/`, `run/`, `schema/`, `actions/`, `classes/validation*`, `classes/history/` 순서가 적절하다.

## 4. 핵심 런타임 아키텍처

### 4.1 기본 실행 흐름

```mermaid
flowchart TD
    A["사용자: Guard 생성"] --> B["스키마 로드: RAIL/Pydantic/String/JSON Schema"]
    B --> C["validator map 구성"]
    C --> D["Guard.__call__ 또는 Guard.parse"]
    D --> E["Runner 생성"]
    E --> F["입력 메시지 검증"]
    F --> G["LLM 호출 또는 기존 llm_output 사용"]
    G --> H["출력 파싱: JSON/string"]
    H --> I["JSON Schema 검증 및 타입 보정"]
    I --> J["validator_service.validate"]
    J --> K{"실패 발생?"}
    K -- no --> L["ValidationOutcome 반환"]
    K -- yes --> M["OnFailAction 적용"]
    M --> N{"reask 필요?"}
    N -- yes --> O["reask 메시지/부분 스키마 생성"]
    O --> G
    N -- no --> L
```

### 4.2 핵심 객체 관계

- `Guard`: 사용자 진입점. 스키마, validator, 실행 옵션, history, server/client 여부를 가진다.
- `Runner`: 한 번의 Guard 호출을 실제로 실행한다. LLM 호출, 파싱, 스키마 검증, validator 실행, reask 반복을 담당한다.
- `Validator`: 값 하나를 검증하는 규칙 단위이다. `_validate()`를 구현하고 `PassResult` 또는 `FailResult`를 반환한다.
- `ValidatorServiceBase`: validator 실행 전후 로그, 실패 정책 적용, 여러 validator 결과 병합을 담당한다.
- `SequentialValidatorService`: 동기 Guard에서 validator를 순차 실행한다.
- `AsyncValidatorService`: async validator를 병렬 실행하고 결과를 병합한다.
- `ValidationOutcome`: 최종 결과 DTO. 원본 LLM 출력, 검증된 출력, reask, 통과 여부, 오류, 검증 요약을 포함한다.
- `Call`, `Iteration`, `Inputs`, `Outputs`: 실행 history와 단계별 로그 모델이다.
- `ProcessedSchema`: RAIL/Pydantic/primitive 입력을 JSON Schema, validator 목록, validator map, execution options로 변환한 결과이다.

## 5. Guard 기능명세

### 5.1 Guard 생성 방식

`Guard`는 네 가지 생성 경로를 제공한다.

| 생성 방식 | 함수 | 입력 | 용도 |
| --- | --- | --- | --- |
| 기본 생성 후 validator 추가 | `Guard().use(...)` | validator 인스턴스 | 단순 문자열/출력 검증 |
| RAIL 파일 | `Guard.for_rail(path)` | `.rail` 파일 경로 | XML 기반 스키마/프롬프트/validator 정의 |
| RAIL 문자열 | `Guard.for_rail_string(xml)` | RAIL XML 문자열 | DB/설정에서 동적 로드 |
| Pydantic 모델 | `Guard.for_pydantic(model)` | Pydantic BaseModel 또는 모델 리스트 | Python 타입 기반 구조화 출력 |
| 문자열 출력 | `Guard.for_string(validators)` | validator 목록 | 일반 텍스트 응답 검증 |

온톨로지 플랫폼에서는 `Guard.for_pydantic()`을 우선 기준으로 삼는 것이 좋다. 개념 추출, 관계 추출, 속성 정규화, 증거 문장 연결 등은 Pydantic 모델로 명확히 표현할 수 있고, 이 모델을 그대로 API contract와 테스트 fixture에 재사용할 수 있다. RAIL은 사용자 정의 DSL/설정 파일 기반 검증을 지원할 때 보조 수단으로 쓰는 편이 적절하다.

### 5.2 Guard 실행 방식

| 실행 방식 | 함수 | 설명 |
| --- | --- | --- |
| LLM 호출 포함 | `guard(llm_api=..., messages=..., prompt_params=...)` | Guard가 LLM 호출부터 검증까지 수행 |
| 기존 출력 검증 | `guard.parse(llm_output=...)` | 이미 생성된 LLM 출력 문자열을 파싱/검증 |
| 별칭 | `guard.validate(llm_output)` | `parse()`와 동일 |
| 서버 모드 | `settings.use_server=True` 또는 `Guard(use_server=True)` | Guardrails API 서버에 검증 위임 |
| 스트리밍 | `stream=True` | `StreamRunner` 사용 |

`__call__`은 기본적으로 `messages`가 필요하다. 이미 응답을 보유한 후처리 파이프라인에서는 `parse()`를 사용해야 한다.

### 5.3 Guard 입력/출력 계약

입력 주요 필드:

- `llm_api`: OpenAI/LiteLLM/HuggingFace/사용자 callable
- `messages`: chat message 목록
- `prompt_params`: prompt template 치환 값
- `metadata`: validator에 전달되는 외부 컨텍스트
- `num_reasks`: 검증 실패 시 재질문 최대 횟수
- `full_schema_reask`: 실패 필드만 물을지 전체 스키마를 다시 생성할지 결정
- `llm_output`: LLM 호출 없이 검증할 기존 출력

출력 `ValidationOutcome`:

- `rawLlmOutput`: 원본 LLM 문자열
- `validatedOutput`: 검증과 보정이 반영된 최종 값
- `validationPassed`: 최종 통과 여부
- `reask`: 재질문이 필요한 실패 객체
- `validationSummaries`: 실패 validator 요약
- `error`: 실행 중 오류
- `callId`: history 식별자

## 6. Schema 기능명세

### 6.1 RAIL 처리

`guardrails/schema/rail_schema.py`는 RAIL XML을 JSON Schema와 validator map으로 변환한다.

지원되는 주요 RAIL 타입:

- `string`
- `integer`
- `float`
- `bool`
- `date`
- `time`
- `datetime`
- `percentage`
- `enum`
- `list`
- `object`
- `choice`

RAIL 요소의 `validators` 속성은 validator 문자열을 파싱하고, `on-fail-*` 속성은 validator별 실패 정책으로 변환된다. 객체 필드는 JSON path 형태의 validator map에 연결된다. 예를 들어 `$.entities.*.label` 같은 경로에 특정 validator를 붙일 수 있다.

온톨로지 플랫폼 적용:

- RAIL은 운영자가 UI에서 검증 정책을 XML/DSL로 저장하는 기능을 만들 때 유용하다.
- 초기 구현에서는 Pydantic 모델 기반 스키마를 우선하고, RAIL은 “고급 사용자/템플릿 import” 기능으로 뒤에 붙이는 것이 안정적이다.

### 6.2 Pydantic 처리

`guardrails/schema/pydantic_schema.py`는 Pydantic 모델을 JSON Schema로 변환하고, 필드별 validator metadata를 추출한다.

적용 가능한 온톨로지 모델 예:

```python
class OntologyEntity(BaseModel):
    id: str
    label: str
    type: Literal["class", "individual", "property"]
    description: str
    evidence: list[str]

class OntologyRelation(BaseModel):
    source_id: str
    predicate: str
    target_id: str
    confidence: float
    evidence: list[str]
```

이런 모델을 `Guard.for_pydantic()`에 넣으면 LLM 응답을 JSON 구조로 강제하고, 누락 필드/타입 오류/추가 키/validator 실패를 한 실행 흐름 안에서 처리할 수 있다.

### 6.3 Primitive/String 처리

`primitive_to_schema()`는 단순 문자열 또는 기본 타입 검증용 schema를 만든다. 문서 요약, label 후보, relation predicate 후보처럼 단일 문자열 출력을 검증할 때 적합하다.

## 7. Validator 기능명세

### 7.1 Validator 기본 구조

`Validator`는 모든 검증 규칙의 베이스 클래스이다.

필수 구현:

- `_validate(value, metadata) -> ValidationResult`

선택 구현:

- `_inference_local(model_input)`
- `_inference_remote(model_input)`
- `async_validate(value, metadata)`
- `validate_stream(...)`
- `async_validate_stream(...)`

반환 타입:

- `PassResult`: 검증 성공. 선택적으로 `value_override`, `validated_chunk`, `metadata` 포함
- `FailResult`: 검증 실패. `error_message`, `fix_value`, `metadata` 포함

Validator 인스턴스는 `rail_alias`로 registry에 등록되어야 한다. Guard는 validator reference를 `id`, `on`, `on_fail`, `kwargs` 형태로 직렬화한다.

### 7.2 Validator 실행 위치

Validator는 다음 위치에 붙을 수 있다.

- `output` 또는 `$`: 전체 출력
- `messages`: 입력 메시지
- JSON path: `$.field`, `$.items.*.name` 등 구조화 출력의 특정 필드

온톨로지 플랫폼에서는 다음 경로 매핑이 중요하다.

| 경로 | 검증 예 |
| --- | --- |
| `$` | 전체 ontology extraction result가 최소 엔티티/관계를 포함하는지 |
| `$.entities.*.id` | ID 형식, 중복 여부 |
| `$.entities.*.label` | 빈 문자열 금지, 길이 제한, 금칙어 |
| `$.relations.*.source_id` | 존재하는 entity ID인지 |
| `$.relations.*.predicate` | 허용 ontology predicate인지 |
| `$.relations.*.confidence` | 0.0~1.0 범위 |
| `$.relations.*.evidence.*` | 원문에 존재하는 근거 문장인지 |

### 7.3 OnFailAction 명세

| 액션 | 동작 | 온톨로지 적용 |
| --- | --- | --- |
| `exception` | 즉시 예외 발생 | 저장 전 엄격 검증, 배치 실패 처리 |
| `noop` | 실패해도 원본 유지 | soft warning만 남길 때 |
| `fix` | `FailResult.fix_value`로 교체 | label trim, confidence clipping |
| `fix_reask` | fix 후 재검증, 실패하면 reask | 자동 보정 가능하지만 위험한 필드 |
| `reask` | 실패 위치를 ReAsk 객체로 표시 | 관계/근거/타입 오류 재생성 |
| `filter` | 실패 값을 제거 | 부적합 entity/relation 삭제 |
| `refrain` | 전체 응답을 비움 | 안전성/정책 위반 시 결과 폐기 |
| `custom` | 사용자 함수 호출 | 그래프 DB 조회 기반 보정 |

온톨로지 구축에서는 `exception`보다 `reask`, `filter`, `fix`, `custom`의 조합이 실용적이다. 예를 들어 relation의 source/target ID가 존재하지 않으면 `reask`, confidence 범위 오류는 `fix`, evidence가 원문에 없으면 `filter` 또는 `reask`가 적합하다.

## 8. Runner 및 ReAsk 기능명세

### 8.1 Runner 단계

`Runner.step()`은 다음 순서로 실행된다.

1. `Inputs`, `Outputs`, `Iteration` 생성
2. 입력 메시지 준비 및 입력 validator 실행
3. LLM API 호출 또는 전달받은 `llm_output` 사용
4. 원본 출력 파싱
5. JSON Schema 검증
6. validator map 기반 검증
7. 실패 정책 후처리
8. reask 객체 수집
9. reask가 있고 예산이 남으면 다음 loop 준비

### 8.2 ReAsk 처리

`guardrails/actions/reask.py`는 실패 유형을 다음 객체로 표현한다.

- `FieldReAsk`: 특정 필드 값 검증 실패
- `SkeletonReAsk`: 전체 구조/schema 검증 실패
- `NonParseableReAsk`: LLM 출력 파싱 실패

`get_reask_setup()`은 실패 객체, 기존 출력, 스키마, validator map을 바탕으로 다음 LLM 호출에 사용할 메시지와 스키마를 만든다. 부분 reask가 가능하면 실패 필드만 다시 요청하고, `full_schema_reask=True`이면 전체 구조를 다시 요청한다.

온톨로지 플랫폼 적용:

- entity/relation 한두 개 필드 오류는 부분 reask가 비용과 품질 면에서 유리하다.
- Pydantic 모델 기반 전체 ontology extraction은 `full_schema_reask=True`가 안정적인 경우가 많다.
- production에서는 reask 횟수를 1~2회로 제한하고, 실패한 relation만 “검토 필요” 큐로 보내는 정책이 좋다.

## 9. ValidatorService 기능명세

### 9.1 동기 실행

`SequentialValidatorService`는 validator를 순차 실행한다. 동기 Guard에서 async validator를 사용하면 명시적으로 오류를 낸다. 스트리밍 검증에서는 chunk 누적, validator별 partial accumulator, fix 결과 병합을 수행한다.

### 9.2 비동기 실행

`AsyncValidatorService`는 같은 경로에 붙은 validator들을 `asyncio.gather()`로 병렬 실행한다. 결과 처리 규칙은 다음과 같다.

- `Filter` 또는 `Refrain`이 나오면 즉시 해당 값 반환
- `FieldReAsk`가 여러 개면 fail result를 병합
- `fix`, `fix_reask`, `custom` 결과가 여러 개면 diff/merge 로직으로 병합
- child object/list는 재귀적으로 검증

온톨로지 플랫폼에서 원문 근거 확인, 외부 사전 조회, 그래프 DB 중복 조회, embedding similarity 검증처럼 I/O가 많은 validator는 async 기반으로 구현하는 것이 좋다.

## 10. LLM Provider 및 Formatter 명세

### 10.1 LLM 호출 어댑터

`llm_providers.py`는 여러 호출 방식을 `PromptCallableBase` 형태로 감싼다.

지원 범주:

- OpenAI 호환 callable
- LiteLLM
- Manifest
- HuggingFace model/pipeline
- 임의 Python callable
- async callable

`get_llm_ask()`와 `get_async_llm_ask()`는 전달된 `llm_api`, `model`, kwargs를 보고 적절한 callable wrapper를 선택한다.

### 10.2 구조화 출력 Formatter

`formatters/json_formatter.py`는 JSON Schema를 기반으로 구조화 생성을 보조한다. Pydantic 기반 Guard에서 `output_formatter="jsonformer"` 같은 방식으로 formatter를 붙일 수 있다.

온톨로지 플랫폼에서는 모델별 structured output 기능이 다르므로 다음 순서로 적용하는 것이 좋다.

1. 모델이 native JSON Schema/function calling을 지원하면 provider native 기능 사용
2. 그렇지 않으면 Guardrails prompt suffix와 JSON 파싱/검증 사용
3. 로컬 HuggingFace 모델에는 JSONFormer 같은 formatter 검토

## 11. CLI 및 서버 기능명세

### 11.1 CLI 명령

`guardrails.cli`는 다음 명령군을 제공한다.

- `guardrails configure`: `.guardrailsrc` 설정 및 Hub token/telemetry 설정
- `guardrails create`: validator 목록으로 config 템플릿 생성
- `guardrails start`: Guardrails API 서버 실행
- `guardrails validate`: RAIL과 LLM 출력 파일 기반 검증
- `guardrails hub install/list/uninstall/submit`: Hub validator 관리
- `guardrails db upgrade/downgrade`: DB migration
- `guardrails watch`: 개발 보조

온톨로지 플랫폼에서는 CLI를 직접 노출하기보다 내부 관리 명령 또는 admin API로 래핑하는 것이 좋다.

### 11.2 서버 모드

README와 `guardrails/cli/start.py` 기준으로 Guardrails는 `guardrails-api` 패키지가 설치되어 있으면 독립 서버로 실행될 수 있다. 서버는 Guard 설정을 로드하고 REST API 또는 OpenAI 호환 endpoint로 검증을 제공한다.

적용 방안:

- 단일 애플리케이션 초기 단계: 라이브러리 내장 방식 권장
- 여러 서비스가 공통 검증 정책을 공유하는 단계: Guardrails 서버를 별도 배포
- SaaS형 온톨로지 플랫폼: tenant별 guard config를 서버에 등록하고, extraction worker가 검증 API를 호출

## 12. History, Logging, Telemetry 명세

Guardrails는 각 호출을 `Call`로 기록하고, reask를 포함한 각 시도를 `Iteration`으로 남긴다. 각 validator 실행은 `ValidatorLogs`에 기록된다.

기록되는 주요 정보:

- 입력 메시지
- prompt params
- 원본 LLM 출력
- 파싱 결과
- schema 검증 결과
- validator별 시작/종료 시간
- validator별 검증 전/후 값
- 실패 메시지
- 최종 guarded output
- call status

온톨로지 구축에서는 이 history가 매우 중요하다. 엔티티/관계가 왜 생성되었고, 어떤 검증을 통과/실패했으며, 어떤 값이 자동 보정되었는지 감사 로그로 남길 수 있다. 단, 기본 history는 메모리 `Stack`이므로 production에서는 DB sink를 별도로 구현해야 한다.

## 13. DocumentStore, VectorDB, Text2SQL 분석

### 13.1 DocumentStore

`document_store.py`는 문서와 페이지를 저장하고 vector DB로 유사 페이지를 검색하는 추상화이다.

핵심 객체:

- `Document`: `id`, `pages`, `metadata`
- `Page`: `PageCoordinates`, `text`, `metadata`
- `DocumentStoreBase`: `add_document`, `search`, `add_text`, `add_texts`, `flush`
- `EphemeralDocumentStore`: SQLAlchemy metadata store + vector DB 조합

온톨로지 플랫폼에서는 이미 별도의 크롤링/문서 저장 구조가 있다면 이 모듈을 그대로 핵심 저장소로 쓰기보다는 “validator나 few-shot example retrieval용 경량 참고 구현”으로 쓰는 것이 적절하다.

### 13.2 Text2SQL

`applications/text2sql.py`는 Guardrails를 이용한 응용 예시이다. SQL 스키마와 예시 질의를 prompt에 넣고, 생성된 SQL을 RAIL validator로 검증한다.

온톨로지 플랫폼에 주는 시사점:

- LLM 생성 결과를 도메인별 validator로 감싸는 패턴이 잘 드러난다.
- 예시 검색 + Guard 검증 + reask 루프 구조는 “문서 기반 온톨로지 추출”에도 동일하게 적용할 수 있다.
- SQL 대신 ontology schema, SHACL shape, OWL/RDF vocabulary를 context로 넣으면 같은 패턴을 재사용할 수 있다.

## 14. 테스트 기반 기능 범위

테스트 폴더는 다음 기능을 검증한다.

- Guard 기본 호출, parse, validate
- AsyncGuard 및 async streaming
- RAIL 파싱, Python/Pydantic schema 변환
- JSON parsing, structured data, formatter
- on_fail action: reask, fix, filter, refrain, noop, exception
- multi reask
- validator base 및 validator service
- CLI 동작
- Guardrails server
- OpenAI/LiteLLM embedding/provider 연동
- document store
- LangChain/LlamaIndex integration
- telemetry
- Hub install/registry

즉, Guardrails의 주요 기능은 테스트로 비교적 넓게 커버되어 있다. 우리 프로젝트에서 소스 일부를 거의 그대로 가져온다면, 관련 테스트도 함께 가져와서 “원본 호환성 테스트”로 유지하는 것이 좋다.

## 15. 범용 온톨로지 구축 플랫폼 적용 설계

### 15.1 Guardrails의 역할

Guardrails는 온톨로지 플랫폼에서 다음 레이어로 배치한다.

```mermaid
flowchart LR
    A["문서 수집/Crawl4AI/Firecrawl"] --> B["청킹 및 전처리"]
    B --> C["LLM Ontology Extraction"]
    C --> D["Guardrails 검증 게이트"]
    D --> E["정규화/중복 병합"]
    E --> F["Graph DB / RDF Store"]
    D --> G["검토 큐 / ReAsk / 실패 로그"]
```

핵심 책임:

- LLM 응답을 지정된 ontology extraction schema로 강제
- 스키마 위반, 타입 오류, 누락 필드 차단
- entity/relation 단위 validator 실행
- 자동 수정 가능한 값 보정
- 잘못된 relation 또는 근거 없는 triple 제거
- 재질문으로 복구 가능한 오류 복구
- 검증 로그와 provenance 저장

### 15.2 그대로 사용 권장 모듈

다음 모듈은 변형 없이 또는 import 경로만 조정해서 기본 소스로 사용해도 좋다.

| 모듈 | 사용 이유 |
| --- | --- |
| `guardrails/classes/validation_outcome.py` | 결과 DTO가 잘 정리되어 있음 |
| `guardrails/classes/validation/*` | Pass/Fail/log/summary 구조 재사용 가치 높음 |
| `guardrails/actions/*` | reask/filter/refrain 표현이 범용적 |
| `guardrails/types/on_fail.py` | 실패 정책 enum 그대로 사용 가능 |
| `guardrails/utils/parsing_utils.py` | LLM JSON 파싱/타입 보정 유용 |
| `guardrails/schema/validator.py` | JSON Schema 검증 재사용 가능 |
| `guardrails/schema/pydantic_schema.py` | Pydantic 기반 schema 변환 핵심 |
| `guardrails/validator_service/*` | validator 실행/병합/실패 처리 엔진 |
| `guardrails/run/runner.py` | reask loop 기준 구현 |

### 15.3 래핑 또는 수정 권장 모듈

| 모듈 | 이유 | 권장 방식 |
| --- | --- | --- |
| `guardrails/guard.py` | OpenAI/서버/telemetry/rc 의존이 섞여 있음 | `OntologyGuard` facade로 감싸기 |
| `guardrails/validator_base.py` | Hub/remote inference/rc 의존 있음 | 온톨로지 전용 `BaseOntologyValidator` 추가 |
| `guardrails/llm_providers.py` | provider별 변화가 잦음 | 현재 프로젝트 LLM gateway에 맞춘 adapter 작성 |
| `guardrails/hub/*` | 외부 Hub 의존 | 초기에는 제외 또는 optional |
| `guardrails/telemetry/*` | 외부 OTEL 설정 필요 | 내부 audit log로 대체 가능 |
| `guardrails/cli/*` | 제품 CLI와 책임 중복 | admin command로 필요한 기능만 이식 |
| `document_store.py` | 저장소 모델이 단순함 | 기존 crawler_platform 저장소와 통합 |

### 15.4 온톨로지 전용 Validator 목록

초기 구축에 필요한 validator 명세는 다음과 같다.

| Validator명 | 대상 경로 | 기능 | 실패 정책 |
| --- | --- | --- | --- |
| `EntityIdFormatValidator` | `$.entities.*.id` | ID prefix/slug/UUID 규칙 검증 | `fix` 또는 `exception` |
| `UniqueEntityIdValidator` | `$.entities` | 엔티티 ID 중복 검증 | `reask` |
| `EntityTypeValidator` | `$.entities.*.type` | class/individual/property 등 허용 타입 검증 | `reask` |
| `LabelRequiredValidator` | `$.entities.*.label` | 빈 label, 너무 긴 label 차단 | `fix_reask` |
| `RelationEndpointExistsValidator` | `$.relations.*` | source_id/target_id가 entities에 존재하는지 검증 | `reask` |
| `PredicateVocabularyValidator` | `$.relations.*.predicate` | 허용 predicate 또는 ontology vocabulary 매핑 | `custom` 또는 `reask` |
| `NoSelfRelationValidator` | `$.relations.*` | 금지된 self-loop relation 차단 | `filter` |
| `ConfidenceRangeValidator` | `$.relations.*.confidence` | 0~1 범위 보정 | `fix` |
| `EvidenceExistsValidator` | `$.relations.*.evidence.*` | evidence가 source document chunk에 존재하는지 | `filter` 또는 `reask` |
| `NoHallucinatedClassValidator` | `$.entities.*` | 원문 근거 없는 class 생성 차단 | `reask` |
| `OntologyAcyclicValidator` | `$` | subclass hierarchy cycle 탐지 | `custom` |
| `SHACLShapeValidator` | `$` | SHACL/OWL 제약 검증 | `exception` 또는 `reask` |

### 15.5 온톨로지 추출 Guard 명세

권장 Pydantic 출력 모델:

```python
class OntologyEvidence(BaseModel):
    text: str
    source_id: str
    start_offset: int | None = None
    end_offset: int | None = None

class OntologyEntity(BaseModel):
    id: str
    label: str
    type: Literal["class", "individual", "object_property", "data_property"]
    description: str | None = None
    aliases: list[str] = []
    evidence: list[OntologyEvidence] = []
    confidence: float

class OntologyRelation(BaseModel):
    id: str
    source_id: str
    predicate: str
    target_id: str
    evidence: list[OntologyEvidence] = []
    confidence: float

class OntologyExtractionResult(BaseModel):
    entities: list[OntologyEntity]
    relations: list[OntologyRelation]
    warnings: list[str] = []
```

Guard 생성 정책:

- `Guard.for_pydantic(OntologyExtractionResult)`
- `num_reasks=1` 기본, 고가치 문서만 2
- schema/parsing 오류는 `full_schema_reask=True`
- field validator 오류는 부분 reask 우선
- 최종 실패 결과는 graph store 저장 금지, 검토 큐로 이동

## 16. 정확한 기능명세

### 16.1 기능: 구조화 출력 생성 검증

- 입력: LLM chat messages, ontology schema, source chunk metadata
- 처리:
  - LLM 호출
  - JSON 또는 문자열 파싱
  - JSON Schema 검증
  - 추가 키 제거
  - 타입 보정
  - field validator 실행
- 출력: `ValidationOutcome[OntologyExtractionResult]`
- 예외:
  - 파싱 불가: `NonParseableReAsk`
  - schema 불일치: `SkeletonReAsk`
  - validator 실패: `FieldReAsk` 또는 on_fail 정책 결과

### 16.2 기능: 기존 LLM 출력 사후 검증

- 입력: `llm_output` 문자열
- 처리: `Guard.parse()` 경로로 LLM 호출 없이 검증
- 출력: `ValidationOutcome`
- 사용처: 비동기 worker가 이미 받은 LLM 결과를 저장 전 검증

### 16.3 기능: 입력 메시지 검증

- 입력: `messages`
- 처리: validator map의 `messages` 경로 validator 실행
- 출력: 검증된 messages
- 실패: 입력 prompt가 정책/길이/금칙어를 위반하면 LLM 호출 전 차단
- 사용처: 사용자 정의 ontology extraction prompt 안전성 검증

### 16.4 기능: Field-level 검증

- 입력: 구조화 출력의 특정 JSON path
- 처리: path에 등록된 validator 실행
- 출력: 통과 값, 수정 값, 제거 값, reask 값 중 하나
- 사용처: entity label, relation endpoint, predicate, evidence 검증

### 16.5 기능: 실패 자동 보정

- 입력: `FailResult.fix_value`
- 처리: on_fail=`fix` 또는 `fix_reask`
- 출력: 보정된 값
- 사용처: 공백 제거, 소문자화, confidence clipping, ID slug 변환

### 16.6 기능: 실패 재질문

- 입력: `FieldReAsk`, `SkeletonReAsk`, `NonParseableReAsk`
- 처리:
  - 실패 위치와 오류 메시지 기반 reask prompt 생성
  - 부분 schema 또는 전체 schema 생성
  - LLM 재호출
  - 기존 출력과 새 출력 병합
- 출력: 재검증된 `ValidationOutcome`
- 제한: `num_reasks` 초과 시 실패 상태 반환

### 16.7 기능: 실패 필터링

- 입력: validator 실패 값
- 처리: on_fail=`filter`
- 출력: 해당 값 제거
- 사용처: hallucinated relation, evidence 없는 triple 제거

### 16.8 기능: 응답 보류

- 입력: validator 실패 값
- 처리: on_fail=`refrain`
- 출력: 빈 응답 또는 None
- 사용처: 보안/정책상 온톨로지 생성을 중단해야 하는 문서

### 16.9 기능: 검증 로그 저장

- 입력: validator 실행 결과
- 처리: `ValidatorLogs` 생성
- 출력:
  - validator name
  - registered name
  - property path
  - value before/after
  - validation result
  - start/end time
- 사용처: ontology triple audit, 품질 대시보드, 사용자 검토 UI

### 16.10 기능: 서버형 검증 API

- 입력: guard config, validation request
- 처리: Guardrails API 서버에서 검증 수행
- 출력: serialized `ValidationOutcome`
- 사용처: extraction worker와 검증 정책 서버 분리

## 17. 통합 로드맵

### Phase 1: 내장 검증 라이브러리로 사용

- Guardrails 원본을 `참고`로 유지
- 현재 프로젝트에 `ontology_guard/` 또는 `crawler_platform/validation/` 패키지 생성
- Pydantic ontology schema 정의
- 최소 validator 5개 구현
- `Guard.for_pydantic()` 기반 extraction 검증 PoC 작성

### Phase 2: 원본 핵심 모듈 이식

- `actions`, `validation classes`, `on_fail`, `parsing_utils`, `schema validator` 이식
- Hub/telemetry/CLI 의존 제거
- 내부 LLM gateway adapter 작성
- 테스트 fixture와 원본 unit test 일부 이식

### Phase 3: 온톨로지 품질 게이트 확장

- SHACL/OWL/RDF validator 추가
- graph DB lookup validator 추가
- evidence alignment validator 추가
- reask 실패 결과 검토 큐 구현
- validator log persistence 구현

### Phase 4: 서버형 정책 엔진

- Guard config 저장소 구현
- tenant/project별 guard policy 관리
- extraction worker가 validation service 호출
- 품질 지표 dashboard 구축

## 18. 리스크 및 주의사항

- Guardrails는 외부 Hub, telemetry, `.guardrailsrc` 의존이 코드 곳곳에 있다. 그대로 제품 본체에 넣기 전 이 의존을 명확히 비활성화해야 한다.
- `Validator` 생성 시 rc 파일이 없으면 오류가 나는 경로가 있으므로, 독립 플랫폼에서는 설정 로더를 대체하거나 기본 rc를 생성해야 한다.
- 서버 모드는 별도 `guardrails-api` optional dependency에 의존한다.
- LLM provider wrapper는 외부 SDK 변화에 민감하다. 우리 프로젝트에서는 provider adapter를 별도로 두는 것이 안전하다.
- 기본 history는 메모리 기반이다. 운영 감사 로그로 쓰려면 DB 저장 계층이 필요하다.
- reask는 비용과 지연을 증가시킨다. 문서 중요도와 실패 유형별로 횟수를 다르게 설정해야 한다.
- 자동 `fix`는 편하지만 ontology 의미를 바꿀 위험이 있다. 의미적 필드는 `reask` 또는 `custom` 검증이 더 안전하다.

## 19. 결론

Guardrails는 범용 온톨로지 구축 플랫폼의 “LLM 출력 신뢰성 계층”으로 매우 적합하다. 특히 Pydantic schema 기반 구조화 출력, JSON Schema 검증, field-level validator, on_fail 정책, reask loop, ValidationOutcome/history/log 구조는 거의 그대로 기본 소스로 삼을 수 있다.

다만 원본 전체를 무비판적으로 복사하기보다는, Hub/telemetry/CLI/provider 의존이 강한 부분은 얇은 adapter로 감싸고, 온톨로지 전용 validator와 audit persistence를 추가하는 방식이 좋다. 초기 기준 구현은 `Guard.for_pydantic(OntologyExtractionResult)`와 custom ontology validators 조합으로 시작하는 것이 가장 빠르고 안정적이다.