# Milestone: OpenAI-compatible 하이브리드 라우팅과 컨텍스트 최적화

## 위치

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

## 목표

OpenAI-compatible 방식으로 들어온 요청을 local/cloud provider와 여러 API 모델 후보에 안전하게 라우팅하는 하이브리드 라우팅 방향을 스케치한다.
기존 `PLAN-local-GNN.md`, `CODE_REVIEW-cloud-GNN.md` 같은 skill/예약어 기반 라우팅은 frontier 모델이 판단한 고신뢰 경로로 유지하고, DiffusionGemma 같은 로컬 모델은 자동 라우팅 보조, triage schema filler, cloud context 최적화 전처리기로 선택적으로 사용한다.
최종 라우팅은 deterministic hard gate, skill route 우선순위, local triage 결과, resource/quota/latency/cost 가중치, usage ledger feedback을 함께 보는 정책으로 구체화한다.
이 Milestone은 지식/도구 hook의 하위 기능이 아니라 IOP의 별도 라우팅 정책 도메인에서 관리되는 최상위 스케치 작업으로 둔다.

## 상태

[폐기]

## 승격 조건

- [ ] 기존 skill/예약어 기반 lane/grade 라우팅과 OpenAI-compatible 자동 라우팅의 우선순위와 override 경계를 결정한다.
- [ ] DiffusionGemma 또는 동급 local triage 모델이 채울 schema, confidence, abstain, validation 기준을 결정한다.
- [ ] 초기 판단 게이트, 분석 플랜 게이트, partial analyzer 실행, policy arbiter, 실행/기록 단계를 어떤 순서와 책임으로 나눌지 결정한다.
- [ ] DiffusionGemma를 빠른 판단과 패싱 전략으로 쓸 때 feature-only 입력, short timeout, invalid schema/timeout 시 abstain 기준을 결정한다.
- [ ] 여러 partial analyzer를 항상 호출하지 않고 skip, cascade, parallel 중 어떤 방식으로 호출할지와 분석 예산 상한을 결정한다.
- [ ] 분석 비용과 latency가 예상 token 절감, 품질 개선, local 금지 예외 탐지 이득보다 클 때 분석을 생략하는 기준을 결정한다.
- [ ] hard gate, weighted scorer, context optimizer, fallback/shadow mode를 어떤 실행 단계로 나눌지 결정한다.
- [ ] local/cloud/provider API 후보의 capability, 비용, latency, quota, historical success를 어떤 metric으로 수집하고 route score에 반영할지 결정한다.
- [ ] route score 정책을 즉시 self-mutation하지 않고, 학습 데이터가 일정량 쌓였을 때 주기적으로 policy proposal과 shadow/canary 검증을 거쳐 업데이트하는 루프를 결정한다.
- [ ] frontier teacher가 route log와 outcome을 분석해 prompt 개선, 기존 판단축 offset/threshold 조정, 새 판단축 추가 또는 기존 축 병합/삭제 후보를 policy patch proposal로 만드는 절차를 결정한다.
- [ ] 기존 판단축으로 포용 가능한 반복 패턴은 새 축을 늘리지 않고 offset/threshold 조정으로 처리하는 기준을 정리한다.
- [ ] frontier teacher와 offline replay에 전달할 route evidence pack의 원문 포함 여부, redaction, hash/preview, retention, export 금지 기준을 결정한다.
- [ ] 낮은 Gemma 계열 local 모델도 쉽게 판별할 수 있는 local 금지 예외 기준선과 negative guard label을 정리한다.
- [ ] routing overhead 대비 token/cost/latency 절감 또는 품질 안정화 이득이 충분한지 판단할 ROI gate와 중단 기준을 결정한다.
- [ ] small model confidence/deferral calibration, shadow/canary, offline replay, counterfactual sampling으로 route policy를 검증하는 기준을 정리한다.
- [ ] 이 Milestone을 별도 구현 Milestone으로 승격할 때 필요한 API/config/schema/ledger SDD 필요 여부를 재판정한다.
- [ ] 사용자가 하이브리드 라우팅 MVP 범위와 후속 구현 우선순위를 검토했다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 문서: 없음
- SDD 사유: 현재 Milestone은 하이브리드 라우팅의 제품/운영 컨셉 스케치이며, OpenAI-compatible metadata/config/schema/ledger 구현으로 승격할 때 SDD 필요 여부를 재판정한다.
- 잠금 해제 조건: 아래 체크리스트
  - [ ] 승격 조건의 미정 항목이 사용자 검토로 해소되어 있다.
  - [ ] 구현 가능한 목표, 범위, 기능 Task, 후속 구현 Milestone 후보가 분리되어 있다.
- 결정 필요: 아래 체크리스트
  - [ ] skill/예약어 기반 라우팅 결과가 있을 때 자동 triage가 advisory로만 동작할지, hard gate 위반 시 cloud escalation을 제안할 수 있을지 결정한다.
  - [ ] 명시 route가 없는 OpenAI-compatible 요청에서 `iop-auto` 같은 자동 routing alias를 도입할지 결정한다.
  - [ ] DiffusionGemma 출력 schema를 route decision의 source of truth가 아니라 feature extraction/advisory signal로만 둘지 결정한다.
  - [ ] 초기 판단 게이트에서 fast path로 빠져나갈 조건과 deeper analysis로 보낼 조건을 결정한다.
  - [ ] 분석 플랜 게이트가 negative guard, task triage, context judge, frontier adjudicator 중 어떤 analyzer를 skip/cascade/parallel로 호출할지 결정하는 기준을 정리한다.
  - [ ] analyzer 호출의 최대 latency, 최대 token/cost, 예상 절감액 대비 허용 비용 같은 analysis budget 기준을 결정한다.
  - [ ] DiffusionGemma에 전체 원문을 넣을지, deterministic feature bundle과 짧은 intent excerpt만 넣을지 결정한다.
  - [ ] DiffusionGemma guard가 timeout, schema invalid, confidence low를 반환할 때 기존 scorer로 pass할지, abstain/cloud escalation으로 처리할지 결정한다.
  - [ ] explicit `cloud` route를 local로 downgrade하는 동작을 금지할지, 어떤 사용자 opt-in에서 허용할지 결정한다.
  - [ ] explicit `local` route가 context/capability/tool/schema/privacy hard gate를 위반할 때 fail-fast, cloud escalation 권고, 또는 자동 cloud 전환 중 어떤 정책을 쓸지 결정한다.
  - [ ] fallback과 retry를 shadow/로그만 남길지, 같은 lane/grade 후보로 1회 자동 fallback할지, 사용자 승인 기반으로 둘지 결정한다.
  - [ ] 학습 모드가 frontier teacher 분석으로 policy proposal을 만들 때 필요한 최소 샘플 수, 업데이트 주기, 승인/검증 gate를 결정한다.
  - [ ] frontier teacher가 제안할 수 있는 policy patch type을 prompt 개선, offset/weight 조정, threshold 조정, 새 판단축 추가, 기존 축 병합/삭제로 제한할지 결정한다.
  - [ ] 새 판단축 추가 전에 기존 축 조정으로 설명 가능한지 확인하는 evidence 기준과 최소 반복 실패 cluster 크기를 결정한다.
  - [ ] policy patch proposal의 evidence schema, rollback 조건, version 승격/폐기 기준을 결정한다.
  - [ ] frontier teacher 또는 cloud evaluator에 full prompt/response를 보낼 수 있는지, 기본은 feature/hash/redacted preview만 사용할지 결정한다.
  - [ ] route learning sample의 retention 기간, 사용자/조직/Edge별 opt-out, 민감 metadata 제거 기준을 결정한다.
  - [ ] local로 보내면 안 되는 예외를 deterministic hard gate, 낮은 Gemma classifier, frontier teacher label 중 어느 단계에서 잡을지 결정한다.
  - [ ] 작은 local model이 판별할 negative guard 기준을 keyword/metadata/context feature/schema feature처럼 단순한 신호로 시작할지, 학습된 classifier로 확장할지 결정한다.
  - [ ] hard constraint와 negative guard를 weighted score보다 앞에 두는 precedence order를 확정한다.
  - [ ] small model의 self-reported confidence를 그대로 쓸지, calibration/evaluation 기반 confidence로 제한할지 결정한다.
  - [ ] 선택되지 않은 route의 품질을 추정하기 위한 shadow/canary/counterfactual sampling 비율, 비용 상한, 데이터 보존 기준을 결정한다.
  - [ ] routing layer 자체의 추가 latency와 token/cost가 어느 수준을 넘으면 fast path 또는 기존 scorer를 우선할지 결정한다.
  - [ ] Claude, GPT, Gemini, GLM 같은 API provider 호출을 IOP 내부에서 어떤 `adapter + target` 후보로 표현하고 capability/catalog를 어떻게 관리할지 결정한다.

## 범위

- OpenAI-compatible 요청의 local/cloud/API provider 자동 선택 컨셉
- 기존 skill/예약어/lane/grade routing과 자동 triage routing의 병행 운영 원칙
- DiffusionGemma 같은 local model을 이용한 요청 분석 schema filling, confidence/abstain, parser validation, retry/repair 후보
- 초기 판단 게이트: 요청이 fast path인지, 모델 분석 없이 바로 라우팅/실행해도 되는지, deeper analysis가 필요한지 판단하는 비용 최소화 단계
- 분석 플랜 게이트: negative guard, task triage, context judge, frontier adjudicator 같은 partial analyzer 중 어떤 것을 skip, cascade, parallel로 호출할지 결정하는 단계
- analysis budget: analyzer 호출에 쓸 최대 latency/token/cost와 예상 token 절감, 품질 개선, local 금지 예외 탐지 이득을 비교해 분석 생략 여부를 정하는 후보
- DiffusionGemma fast guard: 전체 원문 대신 deterministic feature bundle, 짧은 user intent excerpt, detected keywords, output shape, metadata를 입력으로 받아 빠른 pass/abstain/escalation 판단을 수행하는 후보
- context size, compressibility, exact-source 필요성, tool/function calling, strict JSON/schema, multimodal, privacy/local-only, latency SLA, provider availability를 포함한 hard gate 후보
- route score 가중치 후보: capability fit, explicit route bonus, historical success, resource availability, quota remaining, latency fit, cost saving, local triage confidence, local risk, context loss risk, queue penalty
- local model을 cloud context optimizer로 사용해 chunk, dedupe, rerank, summary, source pointer를 만들고 cloud token cost를 줄이는 방향
- shadow mode, route log, usage ledger feedback으로 자동 라우팅 threshold를 보정하는 운영 루프
- 주기적 learning mode: 실제 라우팅은 현재 policy version으로 유지하되, 축적된 요청/결과를 frontier teacher가 분석해 다음 scoring policy 후보를 제안하고 shadow/canary 검증 후 승격하는 방향
- policy patch loop: frontier teacher가 직접 runtime policy를 변경하지 않고 prompt 개선, offset/weight/threshold 조정, 새 판단축 추가, 기존 축 병합/삭제 후보를 versioned proposal로 남기는 방향
- teacher evidence pack: frontier teacher와 offline replay에 전달할 route evidence는 기본적으로 feature, hash, redacted preview, route/outcome metric을 우선하고, full prompt/response/raw payload 포함은 별도 결정으로 제한하는 후보
- 판단축 확장 원칙: 기존 판단축이 반복 패턴을 포용할 수 있으면 새 축을 추가하지 않고 offset/threshold를 조정하며, 새 축은 기존 축으로 설명되지 않는 반복 실패 cluster가 충분할 때만 후보로 둔다.
- local 금지 예외 탐지: 낮은 Gemma 계열 모델도 판별 가능한 negative guard 기준선, cloud escalation reason, abstain/fail-fast 후보
- precedence order: privacy, explicit cloud, unsupported tool/schema/modality, context overflow, negative guard 같은 hard constraint를 weighted score보다 앞에 두는 정책 후보
- calibration/evaluation: small model confidence와 deferral 판단을 그대로 신뢰하지 않고 offline replay, shadow/canary, counterfactual sampling, calibration metric으로 검증하는 후보
- ROI gate: routing layer의 추가 latency/token/cost가 예상 절감 또는 품질 안정화 이득보다 큰 경우 fast path 또는 기존 scorer를 우선하는 중단 기준 후보

## 기능

### Epic: [hybrid-route] Hybrid Routing Concept

skill route와 자동 route를 경쟁시키지 않고 서로 다른 신뢰도의 라우팅 신호로 결합하기 위한 컨셉 산출물을 묶는다.

- [ ] [route-sources] skill/예약어 기반 `PLAN-{lane}-GNN.md`와 `CODE_REVIEW-{lane}-GNN.md` 라우팅을 권위 있는 경로로 두고, 자동 triage를 advisory 또는 명시 route 부재 시 기본 경로로 쓰는 우선순위가 정리되어 있다.
- [ ] [analysis-plan] 초기 판단 게이트가 fast path와 deeper analysis를 나누고, 분석 플랜 게이트가 analyzer를 skip/cascade/parallel 중 어떤 방식으로 호출할지 정하는 구조가 정리되어 있다.
- [ ] [analysis-budget] analyzer 호출의 최대 latency/token/cost와 예상 token 절감, 품질 개선, local 금지 예외 탐지 이득을 비교해 분석을 생략하거나 축소하는 기준이 정리되어 있다.
- [ ] [triage-schema] DiffusionGemma 또는 동급 local 모델이 채울 `task_type`, `difficulty`, `context_dependency`, `compressibility`, `required_capabilities`, `local_success_probability`, `cloud_quality_need`, `fallback_required`, `abstain`, `risk_reasons` schema 후보가 정리되어 있다.
- [ ] [fast-guard] DiffusionGemma를 빠른 판단과 패싱용 guard로 사용할 때 원문 전체 대신 feature bundle과 짧은 intent excerpt를 주고, timeout/invalid schema/low confidence는 abstain 또는 기존 scorer pass로 처리하는 기준이 정리되어 있다.
- [ ] [hard-gates] context window, tool/function calling, strict JSON/schema, multimodal input, privacy/local-only, latency SLA, provider availability, explicit local/cloud/user mode 같은 deterministic gate 후보가 정리되어 있다.
- [ ] [constraint-order] privacy, explicit cloud, unsupported capability, context overflow, negative guard 같은 hard constraint가 weighted score보다 앞서는 precedence rule이 정리되어 있다.
- [ ] [score-policy] hard gate를 통과한 후보에 대해 explicit route bonus, capability fit, historical success, resource/quota, latency, cost, triage confidence, risk/queue penalty를 조합하는 weighted scorer 후보가 정리되어 있다.
- [ ] [roi-gate] routing overhead, analyzer cost, latency 증가가 예상 token/cost 절감 또는 품질 안정화 이득보다 큰 경우 분석을 생략하거나 기존 scorer로 회귀하는 ROI 기준이 정리되어 있다.
- [ ] [context-opt] 100k 이상 같은 단순 token threshold보다 compressible/exact-source 기준을 우선하고, local context optimizer가 cloud prompt를 줄이는 경로가 정리되어 있다.
- [ ] [fallback-shadow] D01류 실행 실패 정책과 충돌하지 않도록 초기에는 shadow/advisory/route log 중심으로 운영하고, 자동 fallback은 별도 결정 뒤 구현하는 기준이 정리되어 있다.
- [ ] [learning-loop] route score를 즉시 변경하지 않고, 일정량의 route log/outcome/teacher label이 쌓였을 때 policy proposal, offline evaluation, shadow/canary, version 승격 또는 폐기를 수행하는 주기적 학습 루프가 정리되어 있다.
- [ ] [teacher-proposal] frontier teacher가 route log/outcome을 분석해 prompt 개선, offset/weight/threshold 조정, 새 판단축 추가, 기존 축 병합/삭제를 versioned policy patch proposal로 제안하는 구조가 정리되어 있다.
- [ ] [teacher-data] frontier teacher와 offline replay에 전달할 route evidence pack의 redaction, hash/preview, full payload 금지/허용 조건, retention, opt-out 기준이 정리되어 있다.
- [ ] [axis-governance] 기존 판단축으로 포용 가능한 패턴은 offset/threshold로 조정하고, 새 판단축은 충분한 반복 실패 cluster와 evidence가 있을 때만 추가하는 기준이 정리되어 있다.
- [ ] [calibration-eval] small model confidence와 deferral 판단을 calibration metric, offline replay, shadow/canary, counterfactual sampling으로 검증하는 기준이 정리되어 있다.
- [ ] [negative-guards] local로 보내면 안 되는 예외 케이스를 낮은 Gemma 계열 모델이 쉽게 판별할 수 있도록 단순 feature, label, escalation reason, abstain 기준으로 정리되어 있다.
- [ ] [api-provider] Claude, GPT, Gemini, GLM 등 API provider와 local provider를 IOP 내부 `adapter + target` 후보로 표현하는 catalog/capability 방향이 정리되어 있다.
- [ ] [ops-feedback] route decision, 후보 점수, 선택/실패 사유, token 절감량, 품질/성공 결과를 usage ledger와 qualification/report 후보에 연결하는 feedback loop가 정리되어 있다.
- [ ] [user-review] 사용자가 skill route 우선, 자동 triage 보조, weighted scorer, context optimizer, fallback/shadow 운영 방향을 검토했다.

## 완료 리뷰

- 상태: 폐기
- 요청일: 2026-07-18
- 완료 근거: 최초 요청 라우팅은 에이전트 작업 루프의 독립 라우팅 모듈 컨셉으로 흡수하고, 누적 요청 컨텍스트 최적화는 별도 Milestone으로 분리한다. RAG 운영과 학습·튜닝 축은 후속 독립 프로젝트 검토로 유보한다.
- 검토 항목: 없음
- agent-ui 상태 반영: 해당 없음
- 리뷰 코멘트: 한 Milestone에 라우팅, 컨텍스트 최적화, 정책 학습을 함께 두던 구조를 폐기하고 각 책임의 수명주기에 맞게 분리한다.

## 범위 제외

- OpenAI-compatible metadata/config/proto/API schema 구현 확정
- 실제 route scorer, provider adapter, cloud API 호출 코드 구현
- DiffusionGemma 또는 특정 local model serving 배포 구현
- full prompt/response/raw provider payload를 기본 route learning dataset으로 저장하거나 외부 teacher에 보내는 정책 확정
- 자동 retry/fallback, 중복 실행 방지, partial output 정리의 최종 정책 구현
- billing/chargeback, 조직 IAM, 장기 retention 정책
- RAG 장기 기억 저장소나 Agent Shell 전용 advisor UX

## 작업 컨텍스트

- 관련 경로: `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/node/internal/adapters/openai_compat`, `packages/go/config`, `packages/go/policy`, `proto/iop`, [openai-compatible-api.md](../../../../../agent-contract/outer/openai-compatible-api.md)
- 표준선(선택): 내부 실행은 `adapter + target` 기준을 유지하고, 외부 OpenAI-compatible 경계의 `model` 표현은 alias 또는 compatibility surface로만 취급한다.
- 표준선(선택): skill/예약어 기반 lane/grade 결과는 frontier 모델이 판단한 고신뢰 route signal이며, 자동 triage는 명시 route가 없는 요청이나 context optimizer/advisory 경로에서 우선 사용한다.
- 표준선(선택): DiffusionGemma 출력은 최종 판결이 아니라 feature extraction 결과로 보고, schema validation, confidence threshold, abstain, cloud escalation 후보를 함께 둔다.
- 표준선(선택): 초기 판단 게이트는 라우팅 결정을 완성하지 않고 분석 깊이만 결정하며, 단순 요청은 fast path로 곧바로 기존 scorer 또는 명시 route에 넘긴다.
- 표준선(선택): 분석 플랜 게이트는 모든 analyzer를 매번 호출하지 않고, 요청 특성과 분석 예산에 따라 skip, cascade, parallel 중 하나를 선택한다.
- 표준선(선택): analyzer 호출 비용이나 latency가 예상 token 절감, 품질 개선, local 금지 예외 탐지 이득보다 크면 deeper analysis를 생략하고 기존 scorer 또는 명시 route를 우선한다.
- 표준선(선택): DiffusionGemma fast guard에는 전체 원문을 기본 입력으로 넣지 않고, deterministic feature bundle, 짧은 intent excerpt, detected keywords, requested output shape 같은 작은 입력을 우선 사용한다.
- 표준선(선택): DiffusionGemma guard에는 짧은 timeout을 두고, timeout/invalid schema/low confidence는 route 실패가 아니라 `abstain` 또는 기존 scorer pass로 처리한다.
- 표준선(선택): explicit `cloud` route는 자동 local downgrade하지 않고, explicit `local` route도 hard gate 위반 시에는 fail-fast 또는 cloud escalation 권고를 남기는 방향을 우선 검토한다.
- 표준선(선택): learning mode는 현재 scoring policy를 즉시 바꾸지 않고, versioned policy proposal을 만든 뒤 offline evaluation과 shadow/canary 검증을 통과한 경우에만 주기적으로 승격한다.
- 표준선(선택): frontier teacher는 runtime policy를 직접 수정하지 않고 policy patch proposal만 생성하며, 개선 순서는 prompt 개선, 기존 축 offset/weight/threshold 조정, 새 판단축 추가 순서를 우선한다.
- 표준선(선택): frontier teacher와 offline replay에는 full prompt/response를 기본 제공하지 않고, feature, hash, redacted preview, route/outcome metric으로 구성한 evidence pack을 우선 사용한다.
- 표준선(선택): 새 판단축은 기존 판단축과 offset/threshold 조정으로 설명되지 않는 반복 실패 cluster가 충분할 때만 추가하고, signal value가 낮은 판단축은 병합 또는 삭제 후보로 둔다.
- 표준선(선택): 작은 Gemma 계열 모델이 맡는 negative guard는 복잡한 품질 판단보다 local 금지 신호를 낮은 비용으로 감지하는 역할을 우선하며, 애매하면 `abstain` 또는 cloud escalation 후보로 남긴다.
- 표준선(선택): small model confidence는 그대로 신뢰하지 않고 calibration/evaluation evidence로 보정하며, 선택되지 않은 route에 대한 shadow/canary/counterfactual sampling을 일부 유지해 selection bias를 줄인다.
- 표준선(선택): ROI gate를 통과하지 못한 analyzer와 policy proposal은 실시간 경로에서 제외하고, route log와 offline evidence로만 유지한다.
- 선행 작업: [CLI Agent Group Grade Routing](../../../../phase/automation-runtime-bridge/milestones/cli-agent-group-grade-routing.md), [요청 실행 로그와 Usage Ledger 기반](../../../../phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md), [Provider-Device-Model Qualification 리포트와 Lifecycle 관리](../../../../phase/operational-observability-provider-management/milestones/provider-device-model-qualification-report.md)
- 후속 작업: 자동 route scorer 구현, OpenAI-compatible routing alias/config 구현, local context optimizer 구현, 품질 기반 routing/fallback 고도화
- 확인 필요: `구현 잠금 > 결정 필요` 항목
