modelctl 인터페이스: CLI, TUI, MCP

modelctl은 세 가지 방법으로 구동할 수 있습니다. 세 방법 모두 동일한 하위 CLI 명령(convert / validate / quantize / package)을 실행하므로 결과는 같습니다 — 작업 방식에 맞는 인터페이스를 고르세요:

인터페이스	적합한 용도	추가 설치
CLI (`modelctl`)	스크립팅, CI 파이프라인, 단발성 명령	코어(없음)
TUI (`modelctl-tui`)	대화형 사용 — 폼, 실시간 출력, 플래그 암기 불필요	`[tui]`
MCP 서버 (`modelctl-mcp`)	타입이 정의된 도구를 호출하는 코딩 AI 에이전트(Claude Code, Cursor 등)	`[mcp]`

TUI와 MCP 서버는 CLI를 감싼 얇은 서브프로세스 래퍼이며 동일한 자동 라우팅을 공유합니다: venv-torch / venv-tf 환경을 감지해 각 명령을 필요한 프레임워크가 있는 환경으로 보내므로, 잘못된 환경에서 단계를 실행할 일이 없습니다. 둘 다 torch/tensorflow를 직접 import하지 않으므로 의존성 충돌이 없습니다.

CLI (`modelctl`)

표준 인터페이스입니다. 네 개의 서브커맨드, 명확한 exit 코드, ✓/✗ 검사 출력 — 셸과 CI를 위해 만들어졌습니다.

# TorchScript 모델을 ONNX로 변환
modelctl convert --source model.pt --format pytorch --output model.onnx \
  --input-shape 1,3,224,224 --opset 18

# 검증 (스키마 · 엣지 런타임 대비 opset · 런타임 로드 · 테스트 추론)
modelctl validate --model model.onnx --target-ort 1.18

# Dynamic INT8 양자화
modelctl quantize --model model.onnx --output model.int8.onnx

# 체크섬이 포함된 오프라인 번들로 패키징
modelctl package --model model.onnx --name pump-anomaly-v1

일반적인 CLI 세션: 각 명령이 ✓/✗ 검사를 출력하고 실패 시 0이 아닌 코드로 종료합니다.

CLI 고유 사항:

설정 파일: modelctl convert --config model.yaml은 YAML 설정을 읽습니다. 우선순위는 CLI 플래그 > YAML > 기본값입니다.
Exit 코드는 실패 단계에 대응합니다(3 = 의존성 누락, 4 = convert, 5 = validate, 6 = package, 7 = quantize) — CI를 여기에 걸어 게이팅하세요.
재현 가능한 번들: --timestamp를 넘기거나 SOURCE_DATE_EPOCH를 설정해 metadata.json / checksums.sha256이 실행마다 byte-identical이 되게 하세요.

TUI (`modelctl-tui`)

선택 사항인 Textual 프런트엔드입니다: 명령을 고르고, 폼을 채우고, ✓/✗ 출력이 실시간으로 흐르는 것을 성공/오류 배지와 함께 지켜보세요.

pip install 'modelctl[tui]'
modelctl-tui        # venv-torch / venv-tf가 있는 디렉터리에서 실행

화면 구성

┌ modelctl-tui ──────────── envs: venv-torch[core, pytorch, quantize]  venv-tf[core, quantize, tensorflow] ┐
│ Command                          │ Output                                                  │
│  ( ) convert                     │ $ venv-torch/bin/modelctl validate --model model.onnx   │
│  (•) validate                    │ ✓ ONNX schema valid                                     │
│  ( ) quantize                    │ ✓ Opset supported                                       │
│  ( ) package                     │ ✓ ONNX Runtime load successful                          │
│ Options                          │ ✓ Test inference successful                             │
│  --model *   [model.onnx      ]  │                                                         │
│  --target-ort [1.18           ]  │                                                         │
│  [ Run ]                         │                                                         │
│  → will run in: venv-torch [...] │  ● SUCCESS exit 0                                       │
└──────────────────────────── q quit  ctrl+r run  ctrl+e re-detect envs ────────────────────┘

헤더 — 감지된 환경과 그 기능(core / pytorch / tensorflow / quantize).
Command + Options (왼쪽) — 폼은 명령마다 바뀌며, *는 필수 항목을 표시합니다.
실행 힌트 — Run 아래 줄이 명령이 실행될 환경, 또는 아직 실행할 수 없는 이유를 알려줍니다.
Output (오른쪽) — 실시간 ✓/✗ 스트림과 ● SUCCESS exit 0 / ● FAILED exit N 배지.

실제 TUI 화면. venv-torch로 라우팅된 validate 실행을 보여줍니다.

키 바인딩

키	동작
`ctrl+r`	선택한 명령 실행(Run과 동일)
`ctrl+e`	환경 재감지(venv 생성/수정 후)
`q`	종료

MCP 서버 (`modelctl-mcp`)

선택 사항인 Model Context Protocol stdio 서버로, 동일한 명령을 코딩 에이전트에게 타입이 정의된 도구로 노출합니다. 에이전트가 셸 접근 없이 엣지 박스용 모델을 준비할 수 있습니다.

pip install 'modelctl[mcp]'

에이전트에 등록하세요 — Claude Code라면 claude.json에(Cursor도 유사):

{
  "mcpServers": {
    "modelctl": {
      "command": "modelctl-mcp",
      "cwd": "/path/with/venv-torch-and-venv-tf"
    }
  }
}

cwd에는 venv-torch/ / venv-tf/ 디렉터리(라우터의 기본 탐색 루트)가 있어야 합니다 — 또는 에이전트가 먼저 list_environments를 호출해 라우팅 가능한 대상을 확인하게 하세요.

도구

도구	용도	주요 파라미터
`list_environments`	환경과 기능 탐색	—
`convert`	PyTorch / TensorFlow → ONNX	`source`, `format`, `output`, `input_shape`
`validate`	스키마, opset, 런타임 로드, 테스트 추론	`model`; 선택 `target_ort`, `no_runtime`
`quantize`	Dynamic INT8 양자화	`model`; 선택 `output`, `input_shape`
`package`	검증 후 체크섬 포함 오프라인 릴리스로 번들링	`model`, `name`; 선택 `version`, `quantize`, `out_root`

모든 도구는 동일한 결과 형태를 반환합니다: command, env_label, exit_code, ok, stdout, stderr, 그리고 artifact_path(성공 시 생성된 파일/번들) — 에이전트는 ok를 확인한 뒤 artifact_path를 사용해야 합니다.

코딩 에이전트 세션: list_environments → convert → validate, 각각 타입이 정의된 결과를 반환합니다.

자동 라우팅: 올바른 환경 선택

quantize와 tensorflow extra는 하나의 Python 환경을 공유할 수 없습니다 (ml_dtypes 버전 충돌). 그래서 툴링이 venv 두 개를 유지합니다. TUI와 MCP 서버는 각 환경의 기능을 조사해 명령별로 라우팅합니다:

명령	필요한 기능	일반적인 라우팅 대상
`validate`, `package`(quantize 없이)	core	아무 환경
`convert --format pytorch`	pytorch	`venv-torch`
`convert --format tensorflow`	tensorflow	`venv-tf`
`quantize`, 또는 모든 `--quantize` 플래그	quantize	`venv-torch`

설계상 만족시킬 수 없는 조합이 하나 있습니다: TensorFlow convert와 quantize를 함께 쓰는 경우입니다. 두 인터페이스 모두 실행 중간에 실패하는 대신 이를 먼저 알려줍니다 — TUI는 힌트와 함께 Run을 비활성화하고, MCP는 오류를 반환합니다 — 두 단계로 나누세요: 먼저 convert(tensorflow)로 .onnx를 만들고, 그 .onnx를 quantize하세요.

다음 단계

modelctl로 모델 준비하기 convert → validate → quantize → package 전체 작업 흐름과 플래그 레퍼런스.

modelctl 모범 사례 해야 할 것/하지 말 것: 프로필, 검증 게이트, 재현 가능한 번들, CI.

모델 배포 ONNX 번들을 업로드하고 플로우에서 모델을 사용합니다.