iop/agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-hybrid-request-execution-routing.md

Milestone: [route-04] Execution Preset 하이브리드 Mode 라우팅

목표

• 폐기된 OpenAI-compatible Hybrid Routing · Context Optimization의 핵심 의도 중 IOP 내부 요청 난이도·실행 형태 라우팅과 학습 가능한 decision evidence만 현재 책임 경계에 맞게 복원한다.
• 외부 호출자가 선택한 model이 execution preset을 먼저 고정하고, IOP Edge가 요청 난이도, 기능 요구, 컨텍스트 규모, 지연·비용 예산과 model 가용성을 종합해 그 preset의 allowed_modes 안에서 최종 mode를 결정한다.
• 초기 운영에서는 cloud model이 의미·난이도 advisory를 제공하고 deterministic hard gate와 Edge arbiter가 최종 권한을 갖는다. cloud selector의 timeout/schema/provider 실패는 다른 mode로 조용히 우회하지 않고 표준 model/API 오류로 종료한다.
• 기존 provider-direct 실행, IOP 단일 요청 Agent 실행의 fixed light와 Heavy Plan/Review 실행과 검증 MVP의 heavy를 같은 preset mode contract로 연결한다.
• route-02의 fixed light preset과 single-request runtime을 그대로 지원한다. 이 마일스톤은 advisory-only selector와 mode별 entry stage를 분리하는 explicit selection strategy를 추가하며 기존 fixed preset의 의미를 암묵적으로 바꾸지 않는다.
• route decision/evidence를 축적해 후속 RAG 기반 Local Routing Model 운영 전환이 selector 구현만 대체하고 preset/runtime은 그대로 재사용할 수 있게 한다.

상태

[스케치]

복원 원칙

• archive의 폐기 문서는 당시 스냅샷으로 유지하고 직접 수정하지 않는다.
• 폐기 설계의 artifact lane, grade와 자동화 runtime을 복원하지 않는다. 현재 기준은 exposed model → execution preset → allowed mode decision이다.
• preset은 selection strategy, selector와 mode별 model/stage 조합을 소유한다. 이 milestone의 router는 preset을 바꾸거나 preset 밖 model/target을 만들지 않는다. route-02의 fixed strategy와 새 advisory-then-dispatch strategy는 config에서 명시적으로 구분한다.
• Plan/Review artifact와 internal tool cycle은 선택된 light/heavy handler와 IOP Node tool executor가 소유한다. route evidence에는 raw plan/review, prompt, output과 tool argument/result를 저장하지 않는다.
• target agent나 외부 workflow 제품의 process, state, contract나 runtime은 연결하지 않는다.
• IOP Node는 Edge가 확정한 stage model과 request-scoped workspace tool을 실행·취소하고 상태·usage를 보고하되 preset이나 mode를 판정하지 않는다.

선행 작업

• IOP 단일 요청 Agent 실행
• Heavy Plan/Review 실행과 검증 MVP

승격 조건

• preset_id, allowed mode, advisory, hard-gate reason, confidence와 policy version을 포함한 mode decision contract가 확정된다.
• cloud selector와 Edge arbiter 사이의 권한 경계 및 model output 불신 원칙이 확정된다.
• 여러 preset이 direct/light/heavy/추가 mode를 서로 다르게 조합할 때 selector input과 mode handler registry 경계가 확정된다.
• 기존 fused preset 호환성, advisory-only selector와 mode별 direct-executor/planner entry stage schema가 확정된다.
• selector/target unavailable, timeout, low-confidence와 schema failure가 표준 오류로 수렴하는 규칙이 확정된다.
• route evidence의 저장 위치, 보존 기간, 민감정보 제거, 학습 후보 승격 기준이 확정된다.
• API/config/event schema가 수반되는 구현 전 필수 SDD가 작성·승인된다.

구현 잠금

• 상태: 잠금
• SDD: 불필요
• SDD 문서: 없음
• SDD 사유: 현재는 복원된 cloud-first mode router와 후속 local selector의 경계를 정의하는 개념 스케치다. decision/evidence schema와 운영 policy 구현 전에 필수 SDD가 필요하다.
• 잠금 해제 조건: 아래 체크리스트
  • 승격 조건의 decision·failure·evidence 항목이 모두 해소되어 있다.
  • route-02/03에서 재사용할 preset/mode/runtime 계약과 이 milestone의 일반화 범위가 분리되어 있다.
  • 기존 fused preset을 재해석하지 않는 selection strategy와 mode entry migration/validation이 확정되어 있다.
  • cloud-first 운영과 RAG local selector 후속 범위가 분리되어 있다.
  • 필요한 SDD가 작성·승인되어 있다.
• 결정 필요: 아래 체크리스트
  • cloud selector model, 입력 feature, confidence 의미와 stage budget을 결정한다.
  • preset별 mode 난이도·비용·지연 policy와 deterministic hard gate를 결정한다.
  • route evidence 최소 표본·품질·보존 기간과 민감정보 제거 기준을 결정한다.

범위

1. Mode decision contract

• 모든 decision은 provider-specific 응답이 아니라 IOP 공통 envelope로 정규화한다.
• 최소 필드는 decision_id, request_id, preset_id, allowed_modes, selected mode, hard-gate reason, advisory 요약, confidence, timing과 policy version이다.
• cloud selector는 mode와 난이도 근거를 제안할 수 있지만 preset, stage target, tool parameter와 실행 권한을 갖지 않는다.
• Edge arbiter는 preset snapshot, capability, health, context와 budget으로 advisory를 검증하고 최종 mode를 확정한다.
• advisory-then-dispatch strategy에서 mode가 확정되면 해당 preset의 mode별 entry stage부터 ordered stage/model/options를 handler에 전달한다. direct는 direct executor, light/heavy는 각 planner entry를 가질 수 있다.
• 기존 fixed light strategy는 route-02 의미대로 plan entry로 바로 시작하며, 운영자가 명시적으로 migration하지 않는 한 advisory-only selector를 암묵 추가하지 않는다.

2. Preset별 mode 조합

• balanced preset은 direct/light/heavy, plan-only preset은 light/heavy, high-think one-shot preset은 direct만 허용할 수 있다.
• direct는 fast/weak와 동의어가 아니며 preset stage binding에 따라 strong cloud와 high thinking을 사용할 수 있다.
• light/heavy의 차이는 model 강도가 아니라 Plan/Review lifecycle과 작업 형태다.
• 미래 mode는 registered handler가 있을 때 같은 decision contract에 추가하고, 알 수 없는 mode는 config validation에서 거부한다.

3. Cloud-first 판단과 오류

• request facts와 deterministic hard gate를 먼저 계산한 뒤 cloud selector에는 필요한 최소 semantic context와 preset allowed mode만 전달한다.
• hard gate는 endpoint/tool/workspace capability, context ceiling, deadline, cost ceiling과 target health를 포함한다.
• cloud selector timeout·provider 오류·low-confidence·schema failure, 선택 mode의 capability/target unavailable은 endpoint 표준 오류로 종료한다.
• fallback이나 default mode가 필요하면 preset에 명시된 별도 policy로만 추가할 수 있으며 이 milestone의 암묵 기본값으로 두지 않는다.

4. Route evidence

• request 원문 전체가 아니라 redacted feature snapshot, selector advisory, Edge override, selected mode, stage outcome, latency/cost와 error reason을 학습 가능한 evidence로 정규화한다.
• 요청 실행 로그와 Usage Ledger 기반과 Provider-Device-Model Qualification 리포트와 Lifecycle 관리의 운영 지표를 참조하되 mode policy 소유권은 Edge에 유지한다.
• evidence schema는 후속 local selector가 같은 입력·출력 계약을 shadow replay할 수 있어야 한다.
• 민감정보 제거와 retention을 통과하지 못한 기록은 학습 corpus 후보에 포함하지 않는다.

기능

Epic: [mode-decision] Preset Mode Decision

• [decision-contract] selection strategy, preset/allowed mode/selected mode/advisory/hard-gate를 연결하는 versioned decision envelope를 정의한다.
• [cloud-selector] cloud model selector의 최소 입력/출력, timeout, confidence와 표준 오류 계약을 구현한다.
• [edge-arbiter] preset allowlist, capability, health, context와 budget으로 advisory를 검증하고 최종 mode를 확정한다.
• [mode-dispatch] 확정 mode를 registered handler와 preset의 mode entry/ordered stage binding에 연결하고 기존 fused preset 호환성을 유지한다.

Epic: [preset-policy] Preset Policy

• [preset-composition] direct-only, plan-only, balanced와 custom mode 조합을 검증한다.
• [mode-threshold] preset별 난이도·기능·지연·비용 threshold와 hard-gate reason을 정의한다.
• [failure-policy] selector/mode/target 실패가 암묵 fallback 없이 표준 API 오류로 닫히는 정책을 구현한다.

Epic: [route-evidence] Route Evidence

• [route-events] selector/arbiter/stage outcome을 하나의 request/decision identity로 연결한다.
• [dataset-curation] redaction, retention, 중복 제거와 outcome label 규칙을 정의한다.
• [eval-gate] cloud 판단과 실제 결과의 일치도·regret·비용·지연 평가 기준을 정의한다.
• [local-handoff] 후속 RAG local selector가 소비할 corpus/export contract를 고정한다.

제외 범위

• 외부 model 선택을 무시하고 router가 다른 preset으로 전환하는 기능
• preset 밖 model/target/tool을 cloud model이 직접 선택하는 기능
• 범용 external workflow 제품과의 상태·artifact·process 공유
• IOP Node가 preset, 요청 난이도 또는 mode policy를 자율 판정하는 기능
• 이 milestone에서 RAG local selector를 production primary로 승격하는 작업
• repository 장기 기억 RAG와 routing evidence corpus의 통합

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 복원 범위와 preset 중심 선후 관계를 정리한 스케치이며 승격 조건과 기능 Task가 아직 충족되지 않았다.
• 검토 항목: 없음
• 리뷰 코멘트: 없음

작업 컨텍스트

• Phase: 지식과 도구 최적화 확장
• 복원 근거: OpenAI-compatible Hybrid Routing · Context Optimization
• 선행: IOP 단일 요청 Agent 실행, Heavy Plan/Review 실행과 검증 MVP
• 후속: RAG 기반 Local Routing Model 운영 전환
• 큐 배치: [route-03] 바로 뒤인 [route-04] 4번이다.
• 확인 필요: 구현 잠금 > 결정 필요