# Milestone: Model Alias Provider Pool과 Provider Catalog

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`

## 목표

`qwen3.6:35b` 같은 외부 OpenAI-compatible model key를 `models[]` catalog 항목으로 정의하고, 각 model이 사용할 provider id와 provider별 실제 served model name을 Edge config에서 연결하는 MVP를 만든다.
provider 정의는 Node 아래에 두고, 같은 Node 안의 여러 provider와 provider별 `models[]` list를 기준으로 Edge가 provider 선택, load-ratio routing, target rewrite를 소유한다.
API provider, CLI provider, local inference provider catalog는 이 provider pool을 운영자가 읽기 전용으로 관찰하기 위한 health/capacity/in-flight/model/lifecycle 상태 모델로 연결한다.
provider/device/model별 qualification report와 benchmark/품질 비교는 이 Milestone의 직접 구현 범위가 아니라 후속 심화 Milestone으로 분리한다.

## 상태

[완료]

## 승격 조건

- 충족: `agent-roadmap/sdd/operational-observability-provider-management/provider-catalog-device-status/SDD.md`에서 D01-D06 사용자 결정이 해결되었고, `user_review_0.log`에 결정 이력이 남아 있다.
- 충족: `models[]`, `nodes[].providers[]`, provider별 served model list, Edge-owned target rewrite, `in_flight / capacity` load-ratio 선택, read-only catalog 경계가 구현 계획을 만들 수 있을 만큼 정리되었다.
- 충족: runtime control, resource telemetry, detailed lifecycle/qualification report는 후속 Milestone 범위로 분리되었다.

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/sdd/operational-observability-provider-management/provider-catalog-device-status/SDD.md`
- 잠금 해제 조건:
  - [x] SDD 잠금이 해제되어 있다
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [x] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다
  - [x] `models[]` provider pool의 config/API 계약, provider candidate 선택 기준, target rewrite 책임, catalog 상태 필드, 운영 표면 책임 경계가 구현 계획을 만들 수 있을 만큼 확정되어 있다
- 결정 필요: 없음

## 범위

- `models[]` 기반 model catalog와 provider id -> served model name 매핑 계약
- `nodes[].providers[]` 기반 provider 정의, provider type/category, provider별 served model list 계약
- Edge-owned provider 선택, `in_flight / capacity` load-ratio routing, target rewrite 책임 경계
- API, CLI, local inference provider category와 read-only catalog 표시 기준
- health, capacity, in-flight, derived load ratio, models, queued 상태 추적 기준
- provider별 coarse lifecycle capability flags 표시 기준
- vLLM, vLLM-MLX, Lemonade, SGLang 같은 provider의 운영 표시 후보
- provider validation과 운영 catalog의 책임 분리

## 기능

### Epic: [model-pool] Model Alias Provider Pool

`models[]` catalog model을 중심으로 provider 후보를 묶고 Edge가 실행 후보를 고르는 최소 산출물을 구현한다.

- [x] [alias-contract] `models[].id`가 OpenAI-compatible `model` key이자 provider pool의 canonical routing key가 되며, `models[].providers`가 provider id -> served model name map으로 검증된다.
- [x] [candidate-schema] `nodes[].providers[]`가 provider id, type, category, served `models[]`, health, capacity, in-flight, queued, coarse lifecycle capability를 표현한다.
- [x] [target-rewrite] Edge가 선택한 provider id의 `models[].providers[provider_id]` 값을 concrete target으로 rewrite해 Node에 전달하고, Node/provider adapter는 rewrite하지 않는다.
- [x] [selection-policy] Edge가 available provider 중 `in_flight / capacity` load ratio가 가장 낮은 후보를 우선 선택하고, 동률은 deterministic tie-break로 처리하며, queue timeout을 적용한다.
- [x] [pool-compat] 기존 `openai.model_routes`, `adapter + target`, Node provider instance 설정과 새 `models[]`/provider catalog 계약의 호환/마이그레이션 방향이 정리되어 있다.

### Epic: [provider-catalog] Provider Operations Catalog

운영자가 model provider pool과 provider 상태를 같은 기준으로 비교하기 위한 read-only catalog 산출물을 묶는다.

- [x] [category-map] MVP provider category가 `api`, `cli`, `local_inference`로 정리되고 read-only catalog 표시 필드에 반영된다.
- [x] [device-status] provider health, capacity, in-flight, derived load ratio, served models, queued 상태가 catalog/status 표면에 정리된다.
- [x] [lifecycle-cap] Ollama, Lemonade, vLLM, SGLang 등의 lifecycle 차이가 coarse capability flags로 표시되고 상세 qualification report는 후속 범위로 분리된다.
- [x] [boundary] provider adapter 구현, Edge-owned provider pool routing, read-only operations catalog, 후속 runtime control의 책임 경계가 정리되어 있다.
- [x] [ops-review] Edge config와 Edge-owned read-only catalog/status를 기준으로 `iop-edge` CLI, Control Plane, Client가 어떤 정보를 소비하는지 확인할 수 있다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-06-21
- 완료 근거: `agent-task/archive/2026/06/m-provider-catalog-device-status/01_pool_schema/complete.log`, `02+01_edge_dispatch/complete.log`, `03_catalog_status_http/complete.log`, `04+03_client_catalog_view/complete.log`의 Roadmap Completion과 Spec Completion 기준으로 모든 기능 Task와 S01-S10 Acceptance Scenario가 PASS 근거를 갖는다.
- 완료 근거: `device-status`는 Control Plane `/edges/{id}/status`의 `provider_snapshots` JSON과 `load_ratio=0` 보존 regression test, `ops-review`는 Client Nodes panel provider catalog/status 렌더링과 health color mapping widget test를 근거로 완료 반영했다.
- 완료 근거: 2026-06-21 종료 전 코드레벨 검토에서 config validation, provider-pool dispatch/target rewrite, Control Plane status JSON, Client provider catalog 렌더링 경로를 재확인했고 `go test ./...`, `flutter test`, `flutter analyze --no-fatal-infos`, `git diff --check`가 통과했다.
- 남은 차단 항목: 없음
- 리뷰 필요:
  - [x] 사용자가 완료 결과 코드레벨 검토 후 종료를 요청했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 종료 가능으로 판정하고 다음 후보를 `사용량, 토큰, 로그 운영 추적 MVP`로 지정한다.

## 범위 제외

- vLLM, vLLM-MLX, Lemonade, SGLang provider adapter 구현 자체
- provider pool scheduler 코드 구현과 config migration 실행
- provider/device/model qualification report 저장/조회/비교
- 자동 benchmark, 품질 평가, provider marketplace, cross-Edge provider balancing
- cloud fallback과 품질 평가 feedback 구현
- provider runtime enable/disable, drain, fallback 우선순위 변경, capacity override
- runtime process/container detail과 CPU/GPU/RAM/VRAM resource telemetry

## 작업 컨텍스트

- 관련 경로: `apps/edge`, `apps/node`, `apps/control-plane`, `apps/client`, `packages/go/config`, `proto/iop/runtime.proto`
- 기존 구조: 현재 OpenAI route는 외부 `model`을 단일 `adapter + target`으로 resolve하고, Edge queue는 `ModelGroupKey`를 쓰지만 후보 필터링은 같은 `adapter + target` 기준으로 동작한다.
- 새 표준선(선택): provider 실행 구현의 외부 계약은 `models[].id`를 canonical key로 두고, 내부 dispatch 직전에 Edge가 provider id별 served model name으로 target을 rewrite한다.
- MVP 표면: Edge config와 Edge-owned read-only catalog/status API를 기준으로 두고, `iop-edge` CLI는 읽기 전용 확인 표면, Control Plane/Client는 Edge 상태 소비자로 둔다.
- 선행 작업: Node provider 상태와 Capacity Queue 기반, Edge 모델 그룹 Queue 스케줄링 전환
- 후속 작업: provider pool scheduler 구현, Provider-Device-Model Qualification 리포트와 Lifecycle 관리, provider enable/disable, benchmark/품질 평가
- 작업 메모: [pool-compat] `apps/edge/README.md`와 `configs/edge.yaml`에 기존 `openai.model_routes`/`adapter + target`/Node provider instance 설정을 새 `models[]` provider pool의 1:1 migration 입력 및 fallback/compat 경로로 유지하는 방향을 정리했다. SDD 대상 Milestone의 공식 Task 체크는 `complete.log`의 Roadmap/Spec Completion 근거로 처리한다.
- 작업 메모: [sync] `01_pool_schema` 완료 로그로 `alias-contract`, `candidate-schema`를, `02+01_edge_dispatch` 완료 로그로 `target-rewrite`, `selection-policy`를 Roadmap/Spec Completion 기준 완료 처리했다.
- 작업 메모: [sync-correction] `pool-compat`는 `01_pool_schema`의 공식 Roadmap/Spec Targets에는 빠졌지만, SDD S05 Evidence Map이 요구한 migration/compat note와 기존 `model_routes` regression evidence가 `apps/edge/README.md`, `configs/edge.yaml`, `packages/go/config/config_test.go`, `apps/edge/internal/openai/server_test.go`에 남아 있어 완료로 보정했다.
- 작업 메모: [provider-catalog-small] `api`, `cli`, `local_inference` category는 `config.Category*`와 `ProviderSnapshot.category`에 반영되어 있고, coarse lifecycle capability는 `nodes[].providers[].lifecycle_capabilities`와 `ProviderSnapshot.lifecycle_capabilities` 및 `iop-edge nodes list` configured provider 요약으로 확인 가능하다. 상세 lifecycle/qualification과 runtime control은 SDD/범위 제외 기준에 따라 후속 Milestone으로 분리한다.
- 작업 메모: [sync-complete] `03_catalog_status_http` 완료 로그로 `device-status`를, `04+03_client_catalog_view` 완료 로그로 `ops-review`를 Roadmap/Spec Completion 기준 완료 처리했다.
- 확인 필요: 없음
