rara/agent-roadmap/sdd/rag-serving/retrieval-and-answer-pipeline/SDD.md

SDD: Retrieve와 Answer Pipeline

위치

• Milestone: Milestone 문서
• Phase: PHASE.md

상태

[승인됨]

SDD 잠금

• 상태: 해제
• 사용자 리뷰: 없음
• 잠금 항목:
  • 없음

문제 / 비목표

• 문제: 공개 handler와 release resolver는 존재하지만 실제 integration pipeline, JSON·SSE parity, evidence·trace 보존과 provider failure mapping이 구현되지 않아 정상 요청도 의도적으로 unavailable 상태다.
• 비목표:
  • request 시점 index 작성과 promotion
  • 특정 provider SDK의 공개 노출
  • raw query·answer의 무기한 저장

Source of Truth

영역	기준	메모
Roadmap	Milestone 문서	온라인 pipeline 범위와 상태 원장
Code	RAG OpenAPI	공개 HTTP·SSE 계약
External Provider	active release의 integration instance identity	retrieval·model 호출 대상
User Decision	없음	release identity와 evidence-first 응답 방향이 확정되어 있다

State Machine

상태	진입 조건	다음 상태	근거
received	요청 JSON 검증이 시작됨	resolved, failed	HTTP request
resolved	active release와 policy가 해석됨	retrieving, failed	release query
retrieving	backend search가 실행됨	reranking, generating, completed, failed	provider result
reranking	candidate evidence가 재정렬됨	generating, completed, failed	rerank result
generating	answer provider와 SSE stream이 실행됨	completed, failed	generation event
completed	response와 expiry가 있는 trace가 확정됨	없음	completed response
failed	공개 오류와 가능한 trace가 확정됨	없음	error response

Interface Contract

• 계약 원문: RAG OpenAPI
• 입력:
  • project_id, knowledge_base_id, release_alias: release selector
  • query, top_k, filters: retrieval 입력
  • stream, generation: answer mode와 generation 설정
• 출력:
  • trace_id와 release: 요청과 versioned policy identity
  • evidence: rank, score, content, citation과 metadata
  • answer, usage 또는 SSE metadata·evidence·delta·completed·error
• 금지:
  • active가 아닌 release를 alias fallback으로 제공하지 않는다.
  • JSON과 SSE에서 같은 실패를 상충하는 코드·의미로 반환하지 않는다.
  • expiry 없는 RAG trace를 저장하지 않는다.

Acceptance Scenarios

ID	Milestone Task	Given	When	Then
S01	release-resolution	active·missing release selector	retrieve·answer 요청	active identity를 반환하거나 stable not-found를 반환한다
S02	retrieval-policy	versioned embedding·backend policy	retrieve 실행	capability에 맞는 provider와 filter·top-k를 적용한다
S03	rerank-context	retrieval candidates와 budget	rerank·assembly	stable evidence rank와 bounded context를 만든다
S04	generation	evidence와 generation policy	non-stream answer	answer, evidence, release와 usage를 반환한다
S05	sse-contract	streaming answer	provider delta·terminal event	metadata부터 completed 또는 error까지 순서 있게 전송한다
S06	trace-retention	trace enabled·disabled와 raw retention policy	요청 완료	필요한 identity는 남고 원문·expiry는 policy를 따른다
S07	provider-failures	timeout·unavailable·partial stream·capability mismatch	provider 호출	stable 공개 오류와 올바른 HTTP·SSE terminal을 반환한다

Evidence Map

Scenario	Required Evidence	agent-task 연결	완료 Evidence 기대
S01	release resolver contract test	agent-task/m-retrieval-and-answer-pipeline/...	release-resolution active·not-found evidence
S02	fake embedding·retrieval provider matrix	agent-task/m-retrieval-and-answer-pipeline/...	retrieval-policy policy evidence
S03	rerank·context budget golden test	agent-task/m-retrieval-and-answer-pipeline/...	rerank-context evidence ordering
S04	non-stream HTTP contract test	agent-task/m-retrieval-and-answer-pipeline/...	generation response evidence
S05	SSE event sequence contract test	agent-task/m-retrieval-and-answer-pipeline/...	sse-contract terminal sequence
S06	retention·redaction DB test	agent-task/m-retrieval-and-answer-pipeline/...	trace-retention expiry evidence
S07	provider fault matrix와 HTTP smoke	agent-task/m-retrieval-and-answer-pipeline/...	provider-failures JSON·SSE parity

Cross-repo Dependencies

• 없음

Drift Check

• Milestone 기능 Task와 Acceptance Scenario가 일치한다.
• Evidence Map이 code-review/complete.log에서 검증 가능하다.
• 공개 계약 원문은 OpenAPI 링크로 참조했다.
• 사용자 리뷰가 필요한 항목이 없다.

사용자 리뷰 이력

• 없음

작업 컨텍스트

• 표준선: active release read-only, evidence-first, provider-neutral pipeline, JSON/SSE semantic parity
• 후속 SDD: 평가와 승격 Gate