# IOP

IOP(Inference Operations Platform)는 단순한 모델 라우터나 OpenAI API proxy가 아니다.

IOP는 **Control Plane - Edge - Node** 계층 구조를 기반으로, 여러 로컬 모델 런타임과 CLI Agent 실행 환경을 통합 관리하는 실행 오케스트레이션 플랫폼을 지향한다. 모델 서빙, CLI Agent 실행, shell/git/docker/code workspace 작업, node maintenance 작업을 같은 실행 파이프라인에서 다룰 수 있도록 만드는 것이 핵심 방향이다.

IOP는 NomadCode 전용 Agent Shell이 아니라, NomadCode와 외부 agent, 운영 CLI, Client, 자동화 도구가 함께 소비할 수 있는 범용 추론/자동화 운영 엔진이다. NomadCode는 IOP의 중요한 소비자 중 하나지만, IOP의 프로토콜과 운영 계층은 특정 제품 UX에 종속되지 않는다.

모델 선택, 로컬/클라우드 라우팅, 모델별 profile, token/속도/품질 최적화, 모델 호출 로그와 품질 평가는 IOP 책임으로 둔다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 기본 모델 서빙과 부하 라우팅이 가능해진 뒤 확장하는 최적화 계층으로 본다.

현재 프로젝트는 완성된 운영 시스템이 아니라 스켈레톤 단계다. 이 README는 현재 구현의 세부 사용법보다, 프로젝트가 향하는 구조와 경계를 명확히 설명한다.

## 개요

IOP의 실행 대상은 크게 두 가지다.

- **모델 서빙**
  - OpenAI-compatible model 호출
  - Ollama
  - vLLM
  - MLX
  - 그 외 로컬/원격 모델 런타임
- **Agent / Automation 실행**
  - CLI Agent
  - Shell
  - Git
  - Docker
  - Code workspace 작업
  - NomadCode 계열 자동화 작업
  - 외부 build/deploy 자동화 도구와 domain-specific agent

IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다. 다만 모든 실행자를 `iop-node` 하위 프로세스로 흡수하지는 않는다. 자체 도메인과 배포 단위를 가진 자동화 도구는 Edge에 직접 붙는 specialized domain agent로 다룰 수 있다.

## 핵심 개념

IOP의 중심 개념은 `adapter + target` 기반 실행이다.

- `adapter`는 실행 방식을 나타낸다.
- `target`은 해당 adapter 안에서 실행할 구체 대상을 나타낸다.
- `execution`은 adapter와 target을 해석해 실제 Node에서 수행되는 단위다.

예시는 다음과 같다.

```text
adapter = ollama
target  = qwen3.6

adapter = vllm
target  = gemma4

adapter = cli
target  = cline-dgx

adapter = cli
target  = codex-local
```

외부 OpenAI API 호환 계층에서는 호환성을 위해 `model` 필드가 남을 수 있다. 그러나 내부 실행 개념에서는 모델 이름만으로 전체 실행을 설명하지 않고, `adapter`, `target`, `execution`, `node adapter`, `adapter execution` 같은 용어를 우선한다. IOP의 외부 실행 호출 계약은 OpenAI-compatible API 방식을 기본 표면으로 채택하되, IOP 고유의 workspace, session, agent, approval, artifact, notification 의미는 별도 `iop` wrapper field를 만들지 않고 `metadata` 또는 IOP native endpoint의 명시 필드로 전달한다. 외부 프로젝트가 참조할 OpenAI-compatible 요청 계약 원문은 [agent-contract/outer/openai-compatible-api.md](agent-contract/outer/openai-compatible-api.md)에 둔다.

## 아키텍처

IOP는 Control Plane이 Edge를 통해 시스템을 제어하고, Edge가 자신의 로컬 실행 그룹을 운영하는 구조를 지향한다. Control Plane은 Edge를 제어하기 쉽게 연결하는 레이어이며, Edge 설정과 실질 상태의 원본을 소유하지 않는다.

```text
Control Plane
├─ Edge Group A
│  ├─ Node 1
│  ├─ Node 2
│  └─ Specialized Agent 1
└─ Edge Group B
   ├─ Node 3
   └─ Specialized Agent 2
```

Control Plane은 Node에 직접 연결하지 않는다. 전체 시스템 제어는 Edge를 통해 이뤄지고, Edge는 자신이 관리하는 Node 설정, Node registry, 로컬 런타임 상태의 원본을 가진다. 여러 Control Plane이 있더라도 Edge는 실질 데이터 이전 없이 다른 Control Plane으로 연결 대상을 옮길 수 있어야 한다.

핵심 문장은 다음과 같다.

> Control Plane은 Edge를 통해 시스템을 제어하고, Edge는 자신의 설정과 로컬 런타임 상태를 소유하고 운영한다.

운영 표면은 두 층으로 나눈다. `iop-edge` CLI는 Control Plane 없이도 bootstrap, local config, 진단, node 등록 command 발급, smoke, 단일 Edge 유지보수를 할 수 있는 field/fallback interface로 유지한다. Control Plane은 여러 Edge의 연결/health를 확인하고 fleet-wide 명령, 정책, 감사, 팀 운영 UX를 제공하는 기본 운영면으로 확장한다. 둘 다 필요한 작업은 Edge가 소유한 shared operation으로 분류하고, CLI와 Control Plane이 각각 구현을 복제하지 않는다.

### 제어면(Control Plane)

Control Plane은 자체 서버와 Client 표면을 통해 Edge를 제어하는 운영 계층이다. Edge 데이터의 canonical store가 아니라, 연결된 Edge에 제어 요청을 보내고 결과를 보기 쉽게 만드는 attachable layer다.

주요 책임은 다음과 같다.

- 여러 Edge 연결 관리
- Edge 상태 조회
- Edge 설정 변경
- Edge에 명령 전달
- Edge 이벤트 수신
- Edge 연결/health와 제어 결과 관찰
- Runtime 영역과 Automation 영역을 나눠 보여주는 운영 화면 제공

Control Plane과 Edge는 소켓 기반 연결을 사용하고, 이벤트, 상태, 명령 결과를 실시간으로 주고받는 구조를 지향한다.

Control Plane은 전통적인 Kubernetes식 중앙 스케줄러가 아니다. 다음 책임은 Control Plane에 두지 않는다.

- Node 직접 연결
- Node 직접 스케줄링
- Edge 내부 DB 대체
- 모든 런타임 상태의 단일 원본화
- Edge 설정, Node registry, runtime/automation 상태의 원본 저장소 역할
- 매 요청마다 Node 할당 판단

### Edge

Edge는 단순 API gateway가 아니라 백엔드 전용 실행 그룹 컨트롤러다.

하나의 Edge는 여러 Node를 관리하며, 특정 디바이스 그룹, 로컬 모델 그룹, 자동화 실행 그룹을 하나로 묶는 단위가 된다. Edge는 모델 서빙과 CLI Agent 실행을 모두 처리할 수 있어야 한다.

Edge의 핵심 역할은 다음과 같다.

- Node registry
- Domain agent registry
- Edge-managed Node bootstrap/configuration
- Agent bootstrap/enrollment
- Adapter/Profile configuration
- Runtime routing
- Edge service API surface
- Job assignment
- Stream relay
- Session handling
- Local runtime state
- Execution history aggregation
- Event aggregation

Edge는 자신의 데이터를 자체적으로 가진다. Control Plane은 Edge의 데이터를 조회하고 제어 요청을 전달하지만, 설정과 런타임 데이터의 원본은 Edge다.

현재 edge 내에는 edge-local ops console이 있다. ops console의 `/` 명령은 `apps/edge/internal/service`를 호출하는 얇은 어댑터이며, 향후 HTTP/API handler도 같은 service를 호출하는 방향이다. HTTP/API를 central/remote management surface로, ops console을 edge-local diagnostic surface로 구분한다. 실행 이벤트와 node lifecycle 이벤트는 `apps/edge/internal/events` bus를 통해 fanout한다.

새 command나 운영 기능은 먼저 `Edge-local 필수`, `Control Plane 기본`, `shared operation` 중 하나로 분류한다. Edge-local 필수 범위에는 bootstrap/config/env/setup/node register/nodes list/smoke 같은 Control Plane 없는 field 경로가 들어가고, Control Plane 기본 범위에는 multi-edge 연결/health 확인, fleet-wide command, 정책/감사, 반복 운영 리포트가 들어간다.

### Node

Node는 실제 실행자다.

Node는 모델 런타임, CLI Agent, 도구 실행을 담당한다. Node는 Control Plane이 아니라 Edge에 연결되며, Edge가 전달한 실행 요청을 adapter execution으로 수행하고 이벤트와 결과를 되돌려준다.

Node는 가능한 한 단순한 실행 단위로 유지한다. 정책, 전체 시스템 조정, 다중 Edge 운영 판단을 Node에 밀어 넣지 않고, 전달받은 실행을 안정적으로 수행하는 데 집중한다.

### 도메인 에이전트(Domain Agent)

Domain agent는 특정 자동화 도메인을 자체 바이너리와 자체 실행 모델로 가진 Edge 연결 실행자다.

자체 도메인과 배포 단위를 가진 외부 자동화 도구는 Edge에 직접 붙거나 generic integration boundary를 통해 연결할 수 있다. `iop-node`를 통해 실행되는 하위 프로세스가 아니라, 독립적인 에이전트 등록 정보와 bootstrap command를 사용해 설치되고 Edge에 직접 outbound 연결하는 흐름을 가질 수 있다. Edge는 이러한 specialized domain agent를 별도 agent type으로 인식하고, 작업 실행, 취소, 상태, capability, 결과 수집 등을 메시지 기반으로 제어할 수 있도록 설계한다.

이 경계에서 `iop-node`는 generic execution agent이고, 도메인 에이전트는 specialized agent다.

### Worker 구조

Edge, Node, Control Plane은 별도 `iop-worker` 앱으로 분리하지 않고, 각 Go 서비스 내부의 공통 Worker 모듈을 사용한다. 공통 처리 모델은 `Job Queue`, `Worker Pool`, `Job Status`, `Retry`, `Timeout`, `Cancel`이며, Worker가 담당하는 역할은 서비스별 책임에 맞춰 분리한다.

- **Edge Worker**
  - 사용자 요청 처리 흐름에 붙는 짧은 병렬/비동기 작업을 담당한다.
  - intent 분석, history refinement, routing 보조, 응답 validation, fallback 판단, stream 종료 후 usage/log/metric 기록을 처리한다.
- **Node Worker**
  - 모델 런타임과 로컬 프로세스에 붙는 작업을 담당한다.
  - runtime adapter 처리, model process 상태 감시, local queue 처리, streaming relay 보조, local metric/log flush를 처리한다.
- **Control Plane Worker**
  - 운영/관리/스케줄 기반 작업을 담당한다.
  - node health 수집, model registry 동기화, policy/config 배포, drain/reload 명령, benchmark/job 실행, 운영 리포트와 cleanup 작업을 처리한다.

## 실행 모델

### 어댑터와 대상(Adapter / Target)

IOP 내부 실행은 model 중심이 아니라 adapter 중심으로 정리한다.

- `adapter`: `mock`, `ollama`, `vllm`, `cli` 같은 실행 구현
- `target`: adapter 안에서 선택되는 모델, profile, agent, toolchain
- `execution`: 특정 adapter와 target으로 수행되는 단일 실행
- `node adapter`: Node 안에 등록되어 실제 실행을 담당하는 adapter
- `adapter execution`: Node adapter가 수행하는 실행 단위

현재 코드에는 `RunRequest`, `ExecutionSpec`, `RuntimeEvent`, `NodeCommandRequest`, `EdgeNodeEvent`처럼 이 방향을 담기 위한 타입들이 있다. `RunEvent`는 adapter execution stream에, `EdgeNodeEvent`는 node 연결/해제 같은 edge-node lifecycle과 이후 제어/상태성 이벤트에 사용한다. 세부 계약과 schema는 [agent-contract/index.md](agent-contract/index.md)에서 inner/outer 계약으로 라우팅한다.

### 런타임 도메인(Runtime Domain)

Runtime Domain은 모델 서빙 중심 실행 영역이다.

- OpenAI-compatible `/v1/models`, `/v1/chat/completions` baseline
- OpenAI-compatible `/v1/responses` 계획 표면
- Ollama, vLLM, MLX 같은 모델 런타임
- 로컬/클라우드 모델 라우팅
- 모델 profile과 부하 라우팅
- 추론 요청 처리
- usage, 호출 로그, 품질 평가 신호
- 모델 런타임 adapter 확장

이 영역에서도 내부적으로는 `adapter + target` 개념을 사용한다. 예를 들어 OpenAI 호환 요청의 `model` 값은 내부에서 특정 adapter와 target으로 해석될 수 있다. 외부 클라이언트 호환은 OpenAI-compatible request/response shape를 우선 유지하고, IOP 전용 routing/context/policy 힌트는 `metadata`로 확장한다.
RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 이 기본 serving/load routing 기반이 정리된 뒤 Runtime 최적화 계층으로 확장한다.

### 자동화 도메인(Automation Domain)

Automation Domain은 CLI Agent와 도구 실행 중심 영역이다.

- CLI Agent 실행
- Shell, Git, Docker 작업
- code workspace 작업
- Plane 작업과 유지보수 작업
- Claude CLI, Antigravity CLI, Codex CLI, OpenCode, Cline 같은 실행 대상

NomadCode는 IOP 안에 완전히 흡수된 제품이 아니라, IOP Automation Domain 위에서 동작할 수 있는 대표 사용처로 본다.

```text
IOP Core
└─ 공통 실행 오케스트레이션 계층

NomadCode
└─ IOP Automation Domain을 활용하는 개발 업무 자동화 도메인
```

## 현재 상태

현재 iop는 스켈레톤 단계다.

- Edge-Node 소켓 기반 구조를 우선 검증 중이다.
- Node 등록, 설정 전달, 실행 요청, 스트리밍 이벤트 흐름이 점진적으로 정리되고 있다.
- Edge 내부에는 API 전환을 고려한 `apps/edge/internal/service`와 in-process event fanout인 `apps/edge/internal/events`가 있다.
- cli adapter(node execution implementation) 쪽 구현이 먼저 진행되고 있다.
- OpenAI-compatible API는 현재 `/v1/models`, `/v1/chat/completions` baseline을 기준으로 정리되어 있으며, `/v1/responses` 호환은 후속 모델 서빙/라우팅 단계의 필수 표면으로 둔다.
- edge-local ops console의 `/` 명령은 수동 테스트 표면이며, 장기 인터페이스는 별도 HTTP/API 표면으로 추가한다.
- 현재 실행 이력은 Node local SQLite store에서 검증 중이다. Edge 단위 이력 집계와 로컬 실행 그룹 상태 소유권은 로드맵에 따라 정리한다.
- `mock` adapter와 dummy/TODO 구현은 개발 단계에서 정상적인 구성이다.
- Ollama/vLLM 등 모델 runtime adapter는 단계적으로 확장한다.
- Control Plane은 향후 여러 Edge 관리와 Client 제공을 위해 추가된다.
- `packages/flutter/iop_console`에는 공통 `agent_shell` 패키지를 사용하는 `IopConsoleShell`과 `IopAgentPanel` scaffold가 있다. 이 패키지는 IOP 운영/유지보수 agent 표면의 시작점이며, IOP 단독 앱과 NomadCode 같은 외부 소비자에 임베드되는 UI 모두에서 재사용 가능한 방향으로 둔다.

현재 앱 구성은 다음과 같다.

| 경로 | 현재 의미 |
|---|---|
| `apps/client` | IOP Client UI의 기준 구현인 Flutter 애플리케이션. `packages/flutter/iop_console`을 mount하며 Flutter Web 산출물이 compose `web` 서비스로 배포된다 |
| `packages/flutter/iop_console` | IOP-owned embeddable Flutter console package. 좌측 rail shell과 `agent_shell` 기반 IOP agent panel을 제공한다 |
| `apps/node` | Edge에 연결되어 adapter execution을 수행하는 Node agent |
| `apps/edge` | Node/domain agent registry, 설정 전달, bootstrap, routing, stream relay를 담당하는 Edge skeleton |
| `apps/control-plane` | 여러 Edge를 연결하고 Client과 통신할 Go 기반 운영 제어 서버 스캐폴드 |
| `apps/worker` | 현재 placeholder이며, Worker 구조는 우선 각 Go 서비스 내부 공통 모듈 방향으로 둔다 |
| `packages/go` | 설정, 인증, 정책, 작업, 관측성, 버전 등 Go 공통 패키지 |
| `packages/flutter` | Flutter 재사용 패키지 root. 현재 `iop_console` package를 둔다 |
| `proto` | 앱 간 메시지 계약 원본과 생성물 |
| `configs` | 현재 개발용 설정 예시 |

Client의 장기 UI 기준은 Flutter 앱이며, 필요한 웹 표면은 Flutter Web 산출물로 제공한다. `apps/control-plane`은 Go 기반 운영 제어 서버다. 주요 통신은 edge-node에서 사용 중인 proto-socket을 IOP Wire Protocol 기준으로 Client-Control Plane, Control Plane-Edge, Edge-Node 방향으로 확장한다. Client-Control Plane은 앱/브라우저 경계를 고려해 proto-socket WebSocket/WSS를 우선하고, `net/http`는 health/readiness/bootstrap 같은 보조 endpoint 용도로 유지한다.

## 가이드

사람이 읽는 최신 실행 가이드는 [Edge-local Dev Guide](docs/edge-local-dev-guide.md) 하나로 유지한다.

## 로드맵

제품 방향, 단계, 마일스톤, 우선순위의 단일 기준 문서는 `agent-roadmap/ROADMAP.md`다.
일반 작업에서 AI가 읽어야 하는 현재 작업 기준은 `agent-roadmap/current.md`가 가리키는 기본 마일스톤 또는 요청에 맞는 활성 마일스톤 문서다.

로드맵의 큰 축은 Edge-Node 실행 기반, Edge input surface, CLI Automation runtime, remote terminal bridge, agent bootstrap/specialized agent enrollment, 모델 서빙과 부하 라우팅, RAG/web search/MCP/tool policy/검증 최적화, Control Plane/Client, policy/history/audit, multi-edge operations로 관리한다.

## 개발 메모

- 기존 구조를 우선하며, 세부 구현은 각 작업의 domain rule과 현재 코드 경계를 먼저 확인한 뒤 진행한다.
- API, wire protocol, runtime, event/config schema 계약은 [agent-contract/index.md](agent-contract/index.md)를 기준으로 확인하고, README에는 사람용 방향과 포인터만 둔다.
- Edge-Node 내부 통신은 TCP/protobuf 기반 소켓 흐름을 우선한다.
- Client-Control Plane처럼 앱/브라우저 표면이 필요한 경계는 proto-socket WebSocket/WSS를 사용할 수 있다. Edge-Node 기본 transport를 WebSocket으로 전환하거나 gRPC, actor/FSM/plugin framework를 도입하는 것은 현재 단계의 기본 방향이 아니다.
- OpenAI-compatible API 계층은 외부 모델 호출 호환을 위한 표면이며, 내부 실행 모델 전체를 대표하지 않는다.
- OpenAI-compatible API는 현재 chat completions baseline을 가지며, Responses API 호환 표면까지 지원하는 방향으로 확장한다.
- IOP의 외부 통신 규약은 OpenAI-compatible API 방식을 기본 계약으로 채택하고, 나머지 IOP 전용 실행 문맥은 `metadata` 확장으로 전달한다. `iop` 같은 별도 wrapper field를 기본 표면에 추가하지 않는다. 구체 요청 계약은 [agent-contract/outer/openai-compatible-api.md](agent-contract/outer/openai-compatible-api.md)를 기준으로 한다.
- A2A API 계층은 agent 간 작업 위임과 상태 공유를 위한 표면이며, 단순 모델 호출 호환은 OpenAI-compatible API를 사용한다. A2A 요청 계약은 [agent-contract/outer/a2a-json-rpc-api.md](agent-contract/outer/a2a-json-rpc-api.md)를 기준으로 한다.
- IOP native protocol은 OpenAI-compatible API나 A2A API를 대체하는 것이 아니라, Edge/Node 운영 제어와 CLI/session/command/event 같은 IOP 고유 기능을 제공하는 병행 표면이다.
- Remote terminal bridge는 Edge/Node 운영 제어 기능으로 분류하며, OpenAI-compatible API가 아니라 IOP native protocol과 정책/audit 계층에서 다룬다.
- 앱별 README에는 현재 수동 테스트나 구현 세부가 더 많이 남아 있을 수 있다. 루트 README는 전체 방향과 경계를 설명하는 문서로 유지한다.

## 현재 단계에서 다루지 않는 것

이번 단계에서는 다음 내용을 루트 README에서 상세 설계로 확정하지 않는다.

- 상세 DB schema
- 상세 protobuf 설계
- 상세 event schema
- 상세 permission model
- 상세 policy engine 설계
- 상세 audit log 구조
- Edge federation 세부 설계
- mTLS 세부 구현 계획
- Control Plane UI 화면별 상세 기획
- Plane 연동 상세 workflow
- NomadCode 상세 제품 설계
