rara/agent-ops/rules/project/domain/rag-data-plane/rules.md

domain	last_rule_review_commit	last_rule_updated_at
rag-data-plane	d4546ecbfd	2026-07-18

rag-data-plane

목적 / 책임

게시된 release를 기준으로 온라인 retrieve와 answer 요청을 처리한다. evidence, release identity, trace identity와 JSON/SSE 응답 계약의 일관성을 책임진다.

포함 경로

• apps/rag-api/ — 온라인 RAG API 프로세스 조립과 실행 진입점
• packages/go/rag/ — release 해석, 요청 검증, retrieve/answer handler와 engine port
• api/openapi/ — 공개 HTTP/JSON 및 SSE 계약 원본

제외 경로

• packages/go/controlplane/, db/migrations/ — release를 생성·승격하는 제어 플레인
• packages/go/integration/ — retrieval과 generation 공급자를 추상화하는 공통 port
• packages/go/workflow/, packages/python/ — 비동기 workflow와 adaptation 실행

주요 구성 요소

• rag.Handler — /v1/retrieve, /v1/answer 요청 검증과 응답 변환
• rag.PostgreSQLReleaseResolver — project, knowledge base, alias로 PostgreSQL의 active release 해석
• rag.Engine — retrieval과 generation 구현을 교체하기 위한 도메인 port
• rag.UnavailableEngine — integration 미구성 상태를 503으로 노출하는 기본 engine
• api/openapi/rara-v1.yaml — 공개 요청·응답 및 오류 스키마

유지할 패턴

• 성공한 온라인 요청은 knowledge base와 release alias를 해석하고 응답에 release와 trace identity를 포함한다.
• release alias가 없으면 production, top_k가 없으면 10을 사용하며 검증 범위는 OpenAPI와 handler가 일치해야 한다.
• engine 구현은 capability-aware integration 뒤에 두고 handler가 특정 제품 SDK에 의존하지 않게 한다.
• stream=true 응답의 completed/error SSE event 집합을 변경할 때는 OpenAPI 설명과 handler를 함께 갱신한다.

다른 도메인과의 경계

• control-plane: release의 생성·승격·롤백은 control-plane 책임이며 이 도메인은 활성 release를 읽기만 한다.
• workflow-execution: index 작성·평가 같은 비동기 단계는 workflow에서 실행하고 이 도메인은 승격된 결과만 제공한다.
• platform-common: database, HTTP server, observability와 공급자 port는 공통 adapter를 사용한다.

금지 사항

• 요청 시점에 candidate release를 암묵적으로 production으로 승격하지 않는다.
• handler에 특정 vector store, reranker, model provider를 직접 결합하지 않는다.
• 공개 handler 변경 시 OpenAPI와 JSON/SSE 오류 계약 검토를 생략하지 않는다.