iop/agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-hot-path-one-shot-execution.md

Milestone: IOP Hot Path One-shot 실행 경로

위치

• Roadmap: ROADMAP.md
• Phase: PHASE.md

목표

OpenAI-compatible 경계에 외부 model=iop으로 보이는 단일 one-shot 실행 표면을 제공하고, 내부에서는 빠른 cloud Gemini 3.6 Flash와 RTX 5090 local target ornith-fast를 조합하는 Hot Path를 스케치한다. 단순 요청은 Gemini가 즉시 완료하고, 일정 볼륨과 난이도가 있는 요청은 짧은 micro-plan, ornith-fast 실행, Gemini 리뷰와 최대 1회의 보정으로 끝낸다. 이 경로의 1차 목적은 최대 품질이 아니라 end-to-end 속도를 최대화하면서 실사용에 충분한 품질을 확보하는 것이며, durable Plan/Milestone 작업 루프와는 독립된 제품 경로로 유지한다.

상태

[스케치]

승격 조건

• Hot Path가 지원할 OpenAI-compatible endpoint, streaming 여부와 외부 model=iop 응답 계약을 확정한다.
• Gemini triage가 사용할 2~3단계 난이도·볼륨 등급, 등급별 허용 범위와 Hot Path 제외 조건을 확정한다.
• 사용자 요청을 ornith-fast 실행 입력으로 바꾸는 micro-plan의 최소 구조와 context 상한을 확정한다.
• Gemini 리뷰와 최대 1회 보정의 입력, 종료 판정, timeout·실패·부분 결과 처리 방식을 확정한다.
• 최대 속도를 1차 목표로 측정할 latency budget과 실사용 품질 하한을 함께 확정한다.
• provider/model alias, route policy, stage budget과 관측 항목의 설정 소유권을 확정한다.
• API/config/composite lifecycle 계약 구현으로 승격할 때 SDD와 후속 구현 단위를 확정한다.

구현 잠금

• 상태: 잠금
• SDD: 불필요
• SDD 문서: 없음
• SDD 사유: 현재는 Hot Path의 제품 목적과 후보 경계를 정리하는 스케치이며, OpenAI-compatible API, config와 복합 호출 lifecycle을 구현 가능한 계획으로 승격할 때 SDD가 필요하다.
• 잠금 해제 조건: 아래 체크리스트
  • 승격 조건의 미정 항목이 해소되어 있다.
  • 구현 가능한 MVP 범위와 후속 확장 범위가 분리되어 있다.
  • 계획 승격 시 필요한 SDD가 작성되고 잠금이 해제되어 있다.
• 결정 필요: 아래 체크리스트
  • Hot Path 내부 등급을 2단계와 3단계 중 어느 형태로 고정하고 각 경계를 어떤 신호로 판정할지 결정한다.
  • 첫 MVP가 Chat Completions, Responses, streaming과 workspace/tool 실행 중 어디까지 지원할지 결정한다.
  • Hot Path 범위 초과, target unavailable, timeout 또는 보정 실패 시 같은 요청 안에서 허용할 terminal fallback을 결정한다. 자동으로 durable 작업 루프에 진입시키지는 않는다.
  • latency SLO, 요청·출력·context·도구 실행 상한과 대표 품질 평가의 최소 통과선을 결정한다.

범위

• OpenAI-compatible 외부 model=iop을 실제 단일 provider 모델이 아니라 IOP가 소유하는 composite Hot Path route로 노출하는 방향
• cloud target Gemini 3.6 Flash가 최초 triage, 단순 요청의 직접 응답, micro-plan 생성과 local 결과 리뷰를 담당하는 고정 baseline
• RTX 5090에서 제공되는 local target ornith-fast가 micro-plan에 따라 일정 볼륨의 one-shot 작업을 수행하는 고정 baseline
• 요청의 볼륨, 난이도, context, tool/workspace capability와 위험 신호를 이용한 2~3단계 내부 등급 후보
• 단순 요청은 local hop과 review 없이 Gemini 응답으로 바로 종료하는 최단 경로
• local 실행 요청은 durable Plan 문서가 아닌 bounded micro-plan prompt를 만들고 ornith-fast 결과를 Gemini가 리뷰한 뒤 필요한 경우 최대 1회만 보정하는 경로
• 품질 향상을 위한 추가 model hop보다 end-to-end latency, time-to-first-useful-result와 bounded completion을 우선하는 stage budget
• 외부에는 한 번의 iop model 요청과 최종 응답으로 보이되 내부에는 triage, direct/local route, review, correction, latency와 terminal outcome을 안전하게 관측하는 방향

기능

Epic: [hot-entry] IOP Model과 Hot Path 진입

외부의 단일 모델 호출을 내부 composite route와 속도 우선 등급 판정으로 연결하는 capability를 묶는다.

• [iop-model-surface] OpenAI-compatible model=iop이 기존 model route 규칙을 보존하면서 Hot Path composite execution으로 진입하고 /v1/models와 성공·오류 응답에서 일관된 외부 identity를 제공한다.
• [gemini-triage] Gemini 3.6 Flash가 요청 볼륨, 난이도, context, capability와 위험 신호를 bounded 구조로 판정하고 direct 또는 local-work 등급과 판단 근거를 반환한다.
• [direct-complete] direct 등급은 local 호출과 별도 review 없이 같은 Gemini 호출의 결과를 최종 응답으로 사용해 가장 짧은 종료 경로를 제공한다.
• [route-boundary] invalid·불확실·범위 초과 판정이 Hot Path 안에서 무제한 추론이나 durable workflow 진입을 만들지 않고 계약된 terminal 결과로 끝난다.

Epic: [local-work] Micro-plan과 RTX 5090 실행

일정 볼륨의 요청을 긴 계획 없이 local model에 넘겨 속도와 작업 성능을 함께 확보하는 capability를 묶는다.

• [micro-plan] Gemini가 목표, 필요한 입력, 산출물, 제약과 짧은 검증 기준만 포함한 bounded micro-plan을 만들며 이를 durable Plan/Milestone artifact로 저장하지 않는다.
• [ornith-execute] ornith-fast가 선택된 RTX 5090 local route에서 micro-plan과 허용된 요청 context를 받아 one-shot 결과를 생성한다.
• [execution-budget] local 실행은 요청별 context, 출력, 도구, timeout과 cancellation 상한 안에서 끝나며 session continuation이나 background task queue를 요구하지 않는다.

Epic: [review-correct] 단일 리뷰와 보정

추가 지연을 제한하면서 local 결과의 실사용 품질을 보완하는 capability를 묶는다.

• [gemini-review] Gemini가 원 요청, micro-plan, ornith-fast 결과와 허용된 검증 evidence를 함께 보고 pass, correction 또는 terminal failure를 판정한다.
• [single-correction] correction이 필요하면 계약된 방식으로 최대 1회만 보정하고 추가 review loop나 재계획을 만들지 않는다.
• [terminal-result] pass, 보정 완료, timeout, unavailable과 실패가 하나의 외부 응답 또는 오류로 끝나며 내부 stage 상태가 사용자 응답에 누출되지 않는다.

Epic: [speed-balance] 속도 우선 품질·운영 기준

Hot Path가 최대 품질 경쟁이 아니라 빠른 실용 경로라는 목표를 측정하고 유지하는 capability를 묶는다.

• [latency-budget] direct와 local-work 등급별 전체 latency, cloud/local stage timeout과 추가 hop 상한이 정의되고 속도 회귀를 검출할 수 있다.
• [quality-floor] 대표 one-shot 요청 세트에서 허용 가능한 정확성·완결성 하한을 정의하되 품질 점수를 높이기 위한 추가 stage는 latency budget을 넘지 않는다.
• [route-observability] target identity, 등급, stage timing, review/correction 여부와 terminal outcome을 raw prompt·output·credential 없이 관측할 수 있다.
• [hot-path-smoke] 실제 Gemini cloud target과 RTX 5090 ornith-fast를 사용해 direct, local pass, 단일 보정, 범위 초과와 target unavailable 경로를 검증한다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 방향성 스케치이며 승격 조건, 기능 Task와 실제 검증이 아직 충족되지 않았다.
• 검토 항목: 없음
• 리뷰 코멘트: 없음

범위 제외

• 최대 품질을 위해 강한 cloud 모델을 여러 번 호출하거나 reviewer ensemble, debate, self-consistency를 수행하는 경로
• durable Plan/Milestone/CODE_REVIEW artifact 생성, 여러 task 연결, background 실행, 중단 후 재개와 완료 알림을 담당하는 에이전트 작업 루프 오케스트레이션
• Hot Path 실패나 범위 초과 요청을 자동으로 Plan/Milestone 작업 루프에 편입하는 동작
• 여러 번의 review·repair, 무제한 retry, 장기 session과 사람 승인 대기 상태
• 모든 cloud/local model을 동적으로 조합하는 범용 planner/generator/verifier framework
• provider 설치, 모델 다운로드, RTX 5090 lifecycle·qualification과 credential 관리
• RAG, 장기 기억, 누적 대화 context 최적화와 학습 기반 route threshold 자동 조정

작업 컨텍스트

• 관련 경로: apps/edge/internal/openai, apps/edge/internal/service, packages/go/config, configs/edge.yaml, packages/go/streamgate
• 관련 계약: OpenAI-Compatible API Contract, Edge Config And Runtime Refresh Contract
• 표준선(선택): 외부 호출자는 OpenAI-compatible model=iop만 선택하고 내부 실행은 기존 원칙대로 adapter + target + execution으로 기록한다. Hot Path stage 선택을 위한 별도 root-level iop wrapper나 caller metadata selector를 요구하지 않는다.
• 표준선(선택): Gemini 3.6 Flash와 ornith-fast는 Hot Path baseline target으로 설정에서 명시하고, core 내부에는 외부 model id와 provider id, target 문자열의 의미를 섞어 하드코딩하지 않는다.
• 표준선(선택): end-to-end 속도와 bounded completion이 1차 최적화 목표이며, 품질은 정한 하한을 만족하는 범위에서 최대한 확보한다. 미미한 품질 향상을 위해 stage 수를 늘리지 않는다.
• 표준선(선택): micro-plan은 한 요청 안의 transient directive이며 durable Plan/Milestone artifact가 아니다. review와 correction을 포함해 전체 실행은 one-shot terminal lifecycle 안에서 닫힌다.
• 표준선(선택): Hot Path는 Chronos의 일반 요청 triage/scoped workflow와 요청 분류, artifact, continuation, retry와 완료 상태를 공유하지 않는다. provider 호출, admission, cancellation, 출력 검증과 관측 같은 하위 runtime capability만 재사용할 수 있다.
• 표준선(선택): 단계 호출과 검증 최적화 MVP는 범용 staged validation mode 후보이고, Hot Path는 고정 target 조합과 latency budget을 소유하는 별도 제품 경로다.
• 큐 배치: IOP Agent Runtime 선행 분리 Milestone 추가에 따라 현재 전역 실행 순서 4번이다. 이 번호는 dependency가 아니라 기본 선택 우선순위다.
• 선행 작업: 없음
• 참조·연결 작업: 단계 호출과 검증 최적화 MVP, 요청 실행 로그와 Usage Ledger 기반
• 후속 작업: Hot Path 구현 계획과 SDD, target·endpoint 확대, 평가 기반 threshold 조정
• 확인 필요: 구현 잠금 > 결정 필요