# Milestone: 누적 요청 컨텍스트 구성과 최적화

## 위치

- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../PHASE.md)

## 목표

Agent, Open WebUI 같은 OpenAI-compatible chat client, 일반 API caller와 cloud 요청처럼 이전 message, tool 결과, 검색 자료가 누적되어 들어오는 요청에서 target 모델에 전달할 컨텍스트를 비용과 품질 기준으로 구성·축소하는 방향을 스케치한다.
이 Milestone은 특정 caller나 RAG에 종속되지 않는 요청 단위 컨텍스트 처리 계층의 책임만 정리하며, 구체적인 입력 표현, 호출 지점, 최적화 알고리즘과 실패 정책은 계획 승격 전에 재검토한다.

## 상태

[스케치]

## 승격 조건

- [ ] 최초 지원할 누적 요청 표면과 입력 source 범위를 결정한다.
- [ ] system/developer/user message, tool schema/result, 검색/RAG 결과와 원문 source pointer의 보존 경계를 결정한다.
- [ ] 사용자 요청, 상위 호출 계층 또는 provider dispatch가 확정한 target과 token budget을 컨텍스트 최적화 계층이 소비하는 단방향 책임 경계를 확정한다.
- [ ] 선택, dedupe, rerank, chunk, summary/compression과 bypass 후보 중 MVP 범위를 결정한다.
- [ ] 품질 손실, 원문 추적, token/cost 절감, latency를 함께 평가할 기준과 fallback 후보를 정한다.
- [ ] Advisor, Context Hook, RAG 운영 프로젝트, provider dispatch와의 연동·제외 경계를 확정한다.
- [ ] 구현 가능한 API/stream/schema와 후속 구현 Milestone으로 승격할 때 SDD 필요 여부를 재판정한다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 문서: 없음
- SDD 사유: 현재 Milestone은 caller-neutral 누적 요청 컨텍스트 최적화의 제품·책임 경계를 정리하는 스케치이며, API/schema와 runtime 호출 계약으로 승격할 때 SDD 필요 여부를 재판정한다.
- 잠금 해제 조건: 아래 체크리스트
  - [ ] 승격 조건의 미정 항목이 사용자 검토로 해소되어 있다.
  - [ ] 구현 가능한 MVP 범위와 후속 Milestone이 분리되어 있다.
- 결정 필요: 아래 체크리스트
  - [ ] 최초 MVP가 직접 처리할 request surface와 source 조합을 결정한다.
  - [ ] 최적화 실행을 기본 적용, 명시 opt-in, 정책 기반 적용 중 어떤 방식으로 시작할지 결정한다.
  - [ ] 호출 지점을 provider dispatch 직전, prompt assembly 단계, Context Hook 중 어디에 둘지 결정한다.
  - [ ] 품질 손실 또는 `cannot-fit` 발생 시 원문 fallback, 다른 target 재요청, 안전 중단 중 어떤 의미를 반환할지 결정한다.

## 범위

- Agent 요청뿐 아니라 Open WebUI와 일반 OpenAI-compatible client처럼 message history가 누적되어 들어오는 요청의 컨텍스트 구성 후보
- cloud provider로 전달되는 누적 message, tool 결과, 검색 자료와 RAG retrieval 결과를 포함할 수 있는 caller-neutral 입력 방향
- target 모델의 context window와 token budget을 입력으로 받아 선택, dedupe, rerank, chunk, summary/compression을 적용하는 후보
- system/developer/user/tool 역할, tool/schema payload, exact-source 구간과 provenance/source pointer를 보존하는 방향
- 짧은 입력, 압축 불가 입력, 품질 손실 위험이 큰 입력의 bypass/abstain/cannot-fit 후보
- token/cost 절감, 품질 변화, 핵심 근거 보존, pointer 유효성, latency를 함께 보는 평가 방향

## 기능

### Epic: [context-opt] Accumulated Request Context

특정 agent나 RAG에 묶이지 않고 누적 요청을 target별 context package로 구성하는 컨셉 산출물을 묶는다.

- [ ] [source-boundary] Agent, Open WebUI, 일반 API caller와 cloud 요청에서 누적되는 message, tool 결과, 검색/RAG 자료를 공통으로 다룰 source 경계 후보가 정리되어 있다.
- [ ] [target-budget] 사용자 요청, 상위 호출 계층 또는 provider dispatch가 확정한 target과 token budget을 입력으로 소비하되 컨텍스트 최적화 계층이 target을 선택하거나 재라우팅하지 않는 경계가 정리되어 있다.
- [ ] [opt-candidates] 선택, dedupe, rerank, chunk, summary/compression과 bypass를 어떤 조건에서 적용할지 후보가 정리되어 있다.
- [ ] [fidelity] role, instruction precedence, tool/schema payload, exact-source 구간, provenance/source pointer와 품질 손실 위험을 보존하는 기준 후보가 정리되어 있다.
- [ ] [failure-result] timeout, invalid source pointer, high loss risk, budget 초과에서 bypass, abstain, cannot-fit 또는 원문 fallback을 반환하는 의미 후보가 정리되어 있다.
- [ ] [quality-roi] token/cost 절감과 함께 핵심 근거 recall, 응답 품질 변화, omission/hallucination, pointer validity, latency를 비교할 평가 기준 후보가 정리되어 있다.
- [ ] [integration] 라우팅, provider dispatch, RAG 저장·최신화, Advisor 판단, Context Hook lifecycle과 겹치지 않는 연동 경계가 정리되어 있다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 방향성 스케치이며 승격 조건과 기능 경계가 아직 확정되지 않았다.
- 검토 항목: 없음
- agent-ui 상태 반영: 해당 없음
- 리뷰 코멘트: 없음

## 범위 제외

- direct, Plan, Milestone 분류와 local/cloud/model/provider target 선택
- RAG ingestion, embedding/index, 장기 기억 저장, freshness/update cycle
- teaching, self-update, shadow/canary, 증류·튜닝과 학습 데이터 운영
- Advisor의 조언·검토 정책과 generic Context Hook lifecycle 구현
- 전체 conversation history 또는 최적화 결과의 중앙 영구 저장
- 세부 API field, event/schema, 패키지 구조와 특정 최적화 모델 확정

## 작업 컨텍스트

- 관련 경로: `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/node/internal/adapters/openai_compat`, `packages/go/policy`, `packages/go/metadata`
- 표준선(선택): caller가 agent인지 여부와 관계없이 누적되어 들어온 요청을 대상으로 하며, 특정 UI나 agent-family protocol에 종속된 분기를 기본 계약으로 두지 않는다.
- 표준선(선택): target과 budget은 사용자 요청, 상위 호출 계층 또는 provider dispatch가 확정하고 최적화 계층은 target별 context package만 반환한다. budget 불충족은 `cannot-fit` 같은 결과로 상위 계층에 알리되 자체 재라우팅하지 않는다.
- 표준선(선택): RAG retrieval 결과는 여러 context source 중 하나이며, RAG 저장·최신화와 튜닝 lifecycle은 이 Milestone이 소유하지 않는다.
- 표준선(선택): 현재는 구현 계약을 고정하지 않고 후보 동작과 책임 경계만 남긴다.
- 큐 배치: [Provider-Device-Model Qualification 리포트와 Lifecycle 관리](../../operational-observability-provider-management/milestones/provider-device-model-qualification-report.md) 뒤, [장기 기억과 RAG 업데이트 사이클 (2차)](long-term-memory-rag-second-wave.md) 앞
- 선행 작업: 기본 OpenAI-compatible 입력/relay 안정화, [요청 실행 로그와 Usage Ledger 기반](../../operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md)
- 후속 작업: 컨텍스트 최적화 runtime 구현, caller/provider별 replay 평가, RAG와 Context Hook 연동
- 확인 필요: `구현 잠금 > 결정 필요` 항목
