iop/agent-roadmap/phase/knowledge-tool-optimization-extension/PHASE.md

Phase: 지식과 도구 최적화 확장

상태

[계획]

목표

Ollama serving 경로와 운영 기반이 안정화된 뒤, 단계 호출, tool/schema 강제, output validation, retry/fallback과 누적 요청 컨텍스트 구성을 IOP의 추론 최적화 계층으로 확장한다. 첫 vertical slice인 IOP Hot Path는 OpenAI-compatible model=iop 한 번의 요청 안에서 빠른 cloud Gemini 3.6 Flash와 RTX 5090 local target ornith-fast를 조합하고, model advisory와 Edge 최종 판정, request-local execution profile, route evidence의 기본을 구축한다. 그 다음 analysis directive/generation/verification을 올바른 request-local plan/review 단계로 일반화하고, Edge가 요청 난이도·기능·예산에 따라 실행 형태와 stage별 adapter/target을 고르는 cloud-first 하이브리드 라우팅으로 연결한다. cloud-first 운영 근거가 충분히 쌓이면 동일한 decision contract를 쓰는 RAG 기반 local routing model을 shadow/canary로 검증해 운영 기본 경로로 점진 전환한다. caller-neutral 누적 요청 컨텍스트 최적화, repository 장기 기억 RAG, advisor와 Context Hook은 routing evidence RAG와 서로 다른 후속 기능으로 분리한다. 이 Phase는 특정 Agent Shell에 종속되지 않고 OpenAI-compatible, A2A, IOP native protocol 중 맞는 표면에서 공통 최적화 책임을 제공하는 방향을 다룬다.

Milestone 흐름

완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 milestones/ 경로를 가리킨다. 이 흐름은 해당 Phase 안의 상태 정리이며, Phase를 가로지르는 실행 순서는 아니다. Milestone은 완료, 검토중, 진행중, 계획, 스케치 또는 보류 상태 그룹으로 정리한다. Phase를 가로지르는 실제 다음 작업 선택은 전역 마일스톤 실행 순서를 우선한다.

• [완료] Tool Call Runtime 검증 재시도 MVP

  • 경로: tool-call-runtime-validation-retry
  • 요약: 명시적 tools[]/tool_choice 계약이 있는 OpenAI-compatible 요청에서 IOP 내부 provider 응답의 마지막 tool call을 검증하고, schema 불일치 시 같은 요청을 bounded exact replay로 재시도하는 runtime-only MVP를 구현한다.

• [완료] OpenAI-compatible Think 제어 MVP

  • 경로: openai-compatible-think-control
  • 요약: OpenAI-compatible Chat Completions 요청에서 thinking/reasoning 생성과 응답 노출을 요청별로 제어하고 provider별 option 매핑과 unsupported 정책을 구현한다.

• [완료] OpenAI-compatible Tool Call Boundary Hardening

  • 경로: openai-compatible-tool-call-boundary-hardening
  • 요약: provider-pool/OpenAI-compatible 응답에서 raw text tool-call block, unknown tool name, chat-template sentinel token이 클라이언트 화면으로 새지 않도록 Edge tool-call 경계를 검증/정규화한다.

• [완료] Stream Evidence Gate Core

  • 경로: stream-evidence-gate-core
  • 요약: codec의 response-start/event를 첫 safe release까지 stage하고 500-rune rolling, bounded terminal/fragment hold, pre-read 기본값/절대 상한 16 MiB raw-canonical ingress snapshot과 request-snapshot 기반 Filter Registry를 제공한다. Gate Coordinator가 single-flight all-complete evaluation/commit을, RecoveryPlan Coordinator와 host adapter가 strategy별 budget과 최초 실행 제외 기본값/절대 상한 3회의 request 전체 cap 아래 abort·optional one-shot plan prepare·lossless rebuild·cycle별 single re-admission을 담당한다.

• [계획] [output-01] OpenAI-compatible 출력 검증 필터

  • 경로: [output-01] OpenAI-compatible 출력 검증 필터
  • 요약: 실제 의미 필터 전에 local/dev deterministic diagnostic mock으로 실제 codec/Core/Arbiter/recovery/ReleaseSink의 pass·observe-only·blocking recovery와 raw-free timeline을 관측하는 smoke를 선행한다. 이후 OpenAI-compatible Chat Completions와 Responses provider stream의 반복, assistant-history anchor, 동일 tool/action, schema/provider error를 caller-neutral하게 판정하는 Core Filter 구현체를 제공한다. filter는 model/provider별 on/off와 semantic decision/RecoveryIntent만 소유하고, 병렬 평가·all-complete arbitration·retry budget·request rebuild/re-admission은 Stream Evidence Gate Core의 공통 Coordinator를 소비한다.

• [계획] [output-02] OpenAI-compatible Incomplete Tool Call Syntax Gate

  • 경로: [output-02] OpenAI-compatible Incomplete Tool Call Syntax Gate
  • 요약: terminal provider 응답에서 완성된 tool call 수와 raw/reasoning/content tool-call marker scanner 결과가 불일치하는 케이스를 runtime에서 deterministic하게 판정해 incomplete tool-call syntax로 분류한다.

• [스케치] [output-03] OpenAI-compatible Runtime Output Integrity Filter

  • 경로: [output-03] OpenAI-compatible Runtime Output Integrity Filter
  • 요약: terminal assistant 응답이 content, valid tool call, 명시 허용 structured/error finish 중 하나를 만족해야 한다는 runtime invariant를 정의하고, empty terminal, reasoning-only, incomplete tool-call syntax 같은 deterministic violation을 공통 filter pipeline과 bounded retry 정책으로 묶는다.

• [스케치] [judge-01] LLM 판별 기반 Missing Tool Call 재시도 Gate

  • 경로: [judge-01] LLM 판별 기반 Missing Tool Call 재시도 Gate
  • 요약: Pi/dev-corp 같은 tool-bearing 요청에서 provider가 tool 사용 의도를 reasoning했지만 tool call 없이 종료하는 케이스를 LLM judge와 buffered retry 후보로 재검토하고, 정확한 종료/재시도 정책이 정의될 때까지 구현을 잠근다.

• [스케치] [route-01] IOP Hot Path One-shot 실행 경로

  • 경로: [route-01] IOP Hot Path One-shot 실행 경로
  • 요약: 외부 model=iop 요청을 Gemini 3.6 Flash 즉답 또는 micro-plan, RTX 5090 ornith-fast 실행, Gemini 단일 리뷰·보정으로 처리하면서 model advisory, Edge arbiter, request-local profile과 route evidence의 첫 vertical slice를 구축한다.

• [스케치] [route-02] 단계 호출과 검증 최적화 MVP

  • 경로: [route-02] 단계 호출과 검증 최적화 MVP
  • 요약: Hot Path의 micro-plan/review를 analysis directive, generation, verification의 bounded request-local 실행 형태로 일반화하고 Edge가 선택할 stage binding 계약을 스케치한다.

• [스케치] [route-03] OpenAI-compatible 하이브리드 요청 수준·실행 형태 라우팅

  • 경로: [route-03] OpenAI-compatible 하이브리드 요청 수준·실행 형태 라우팅
  • 요약: 폐기된 하이브리드 라우팅 설계에서 IOP Edge 책임만 복원해 cloud model advisory와 deterministic hard gate를 결합하고, Edge가 요청 난이도에 맞는 execution shape와 stage별 adapter/target을 최종 결정한다.

• [스케치] [route-04] RAG 기반 Local Routing Model 운영 전환

  • 경로: [route-04] RAG 기반 Local Routing Model 운영 전환
  • 요약: cloud-first route evidence가 충분한 품질·규모 gate를 통과하면 같은 decision contract를 쓰는 RAG local router를 shadow, canary, primary 순서로 승격하고 cloud judge를 fallback·audit으로 유지한다.

• [스케치] [judge-02] Tool Call 판정 모델 Gate 리뷰

  • 경로: [judge-02] Tool Call 판정 모델 Gate 리뷰
  • 요약: 명시적 tool schema만으로 판정할 수 없는 자연어/텍스트/agent-specific tool call 후보를 별도 validator 모델로 분류할지, 어떤 조건에서 허용할지 사용자 리뷰가 필요한 결정 항목으로 스케치한다.

• [스케치] [context-01] Provider 입력 컨텍스트 선택과 축소

  • 경로: [context-01] Provider 입력 컨텍스트 선택과 축소
  • 요약: provider 입력으로 누적된 history를 현재 요청 관련성에 따라 과거 요청-답변 단위로 먼저 절단하고, 유지한 답변·tool/search 결과 안에서도 필요한 문단·코드 블록·구간만 남기는 caller-neutral 방향을 스케치한다. provider 응답을 사용자에게 전달하는 출력 경계는 다루지 않는다.

• [스케치] [memory-01] 장기 기억과 RAG 업데이트 사이클 (2차)

  • 경로: [memory-01] 장기 기억과 RAG 업데이트 사이클 (2차)
  • 요약: 특정 repo 장기 기억, RAG 저장소, update cycle, MCP 기반 context 절약은 MVP 이후 2차 후보로 스케치한다.

• [스케치] [advisor-01] Advisor와 Context Hook 확장 (2차)

  • 경로: [advisor-01] Advisor와 Context Hook 확장 (2차)
  • 요약: advisor 역할과 여러 최적화·검증 기능을 실행 흐름에 연결할 수 있는 Context Hook의 호출·실패·노출 경계를 별도 2차 후보로 스케치한다.

Phase 경계

• 이 Phase는 Ollama 경로와 Edge model group queue가 안정적인 serving 경로로 검증된 뒤 시작한다.
• 이 Phase는 Control Plane/Client 운영 기반과 운영 관측 MVP 없이 현재 provider 확장 Phase 안으로 당겨 구현하지 않는다.
• 기본 /v1/models, /v1/chat/completions, Edge-Node relay, Ollama option/API passthrough 안정화는 Ollama 서빙 안정화 기반 Phase 책임이다.
• 추가 추론 서버 provider의 adapter/config/target/model 매핑 표준화는 추론 서버 provider 확장 Phase 책임이다.
• Hot Path, request-local 단계 호출, 하이브리드 라우팅은 순서대로 첫 profile, 올바른 실행 형태 일반화, Edge 범용 선택 정책을 구성한다.
• IOP Edge는 요청 사실과 model advisory를 바탕으로 execution shape와 stage별 adapter/target을 최종 확정한다. IOP Node는 확정된 stage 실행·취소·상태·usage 보고만 담당한다.
• 이 Phase의 plan/review는 하나의 요청 안에서만 유지되는 transient inference stage다. durable Plan/Milestone/CODE_REVIEW artifact, 승인·continuation·workspace mutation 같은 workflow process는 범위 밖이다.
• cloud model은 초기 semantic judge/teacher 역할을 하고, 충분한 정제 evidence가 쌓인 뒤 RAG local router로 운영 기본을 전환한다. 두 경우 모두 최종 권한은 deterministic hard gate를 적용하는 Edge arbiter에 남는다.
• routing evidence RAG는 route 판정 전용이고, repository 장기 기억 RAG·누적 요청 context·advisor·Context Hook과 corpus/index/평가를 공유하지 않는다.