path: root/doc/Specifications.md

# Specifications.md

## 1. 目的

本システムは、LLMがMCP経由でローカルGPU上のStable Diffusion 1.x互換モデルを利用して画像生成・画像誘導生成・インペイントを実行できるMCPサーバを提供する。

LLM側には生成意図に必要な最小限の入力のみを公開し、モデル構成・VAE・LoRA・ControlNet・生成パラメータなどの実行環境設定はMCPサーバ側で管理する。

---

## 2. スコープ

| 区分 | 内容 |
|---|---|
| 対応モデル | Stable Diffusion 1.x互換モデル |
| モデル差し替え | 対応 |
| VAE | 常時使用。checkpoint内蔵VAEまたは外部VAEへの差し替え |
| LoRA | 複数指定・重み指定に対応 |
| ControlNet | ControlNet 1.1 Depth / Openpose / Inpaint |
| MCP経由のモデル変更 | 非対応 |
| モデル・生成設定 | TOML設定ファイルで管理 |
| CLI | `--config`, `--version` のみ |
| パッケージ管理 | uv |
| 実装言語 | Python 3.11 |
| GPU | NVIDIA CUDA GPUを主対象 |
| 主対象VRAM | 8GB級 |
| バッチ生成 | 1枚固定 |
| 同時生成 | 1ジョブのみ |
| 出力形式 | PNG |
| MCPトランスポート | `stdio`、`streamable-http` |

---

## 3. 機能要件

### 3.1 MCPツール

| Tool | 用途 | 必須入力 | 任意入力 |
|---|---|---|---|
| `generate_image` | Text-to-Image | `positive_prompt` | `negative_prompt`, `size` |
| `generate_guided_image` | Depth / Openposeによる誘導生成 | `positive_prompt`, `control_mode`, `input_image` | `negative_prompt`, `size` |
| `inpaint_image` | 指定領域の再生成 | `positive_prompt`, `input_image`, `mask_image` | `negative_prompt`, `size` |

### 3.2 `generate_image`

| 項目 | 仕様 |
|---|---|
| positive_prompt | 必須文字列 |
| negative_prompt | 任意文字列。未指定時は空文字 |
| size | 許可済みサイズの列挙値 |
| 出力 | PNG画像1枚 |
| seed | 内部生成。結果メタデータへの記録は可 |

### 3.3 `generate_guided_image`

| 項目 | 仕様 |
|---|---|
| positive_prompt | 必須文字列 |
| negative_prompt | 任意文字列 |
| control_mode | `depth`, `openpose`, `openpose_full` |
| input_image | 必須 |
| size | 許可済みサイズの列挙値 |
| ControlNet同時利用 | 1種類のみ |

### 3.4 `inpaint_image`

| 項目 | 仕様 |
|---|---|
| positive_prompt | 必須文字列 |
| negative_prompt | 任意文字列 |
| input_image | 必須 |
| mask_image | 必須 |
| size | 許可済みサイズの列挙値 |
| 出力 | PNG画像1枚 |

---

## 4. ControlNet要件

| モード | モデル | 入力 | 前処理 |
|---|---|---|---|
| Depth | ControlNet 1.1 Depth | 元画像 | Midas固定 |
| Openpose | ControlNet 1.1 Openpose | 元画像 | body |
| Openpose Full | ControlNet 1.1 Openpose | 元画像 | body + hand + face |
| Inpaint | ControlNet 1.1 Inpaint | 元画像 + mask | 専用Inpaint入力 |

### 制約

| 項目 | 仕様 |
|---|---|
| Multi-ControlNet | 非対応 |
| Preprocessor選択 | MCPには公開しない |
| ControlNet strength | MCPには公開しない |
| ControlNetモデル切替 | 設定ファイルで管理 |
| GPU常駐 | 必要時ロード方式を許容 |

---

## 5. 画像サイズ

初期対応サイズはStable Diffusion 1.xの512px基準に限定する。

| ID | 解像度 | 用途 |
|---|---:|---|
| `square_512` | 512 x 512 | 標準 |
| `landscape_512` | 512 x 384 | 横長 |
| `portrait_512` | 384 x 512 | 縦長 |

自由なwidth/height指定はMCPには公開しない。

---

## 6. モデル設定要件

### 6.1 設定方法

| 項目 | 仕様 |
|---|---|
| 設定形式 | TOML |
| 設定指定 | CLI `--config PATH` |
| デフォルト設定 | アプリケーション側で最小限保持可 |
| CLI上書き | 行わない |
| MCP経由変更 | 行わない |
| 起動時検証 | 必須 |

### 6.2 モデル構成

| 項目 | 仕様 |
|---|---|
| Base checkpoint | 1ファイル |
| VAE component | 必須。通常はcheckpoint内蔵VAEを使用 |
| 外部VAE | 0または1ファイル。指定時は内蔵VAEを差し替え |
| LoRA | 0個以上 |
| LoRA weight | LoRAごとに指定 |
| ControlNet | Depth / Openpose / Inpaintを個別設定 |
| Base prompt | positive / negative 各0または1ファイル |
| モデルルート | TOMLで1つのルートディレクトリを指定 |

### 6.3 推奨ディレクトリ

```text
models/
├─ checkpoints/
├─ vae/
├─ lora/
├─ controlnet/
└─ prompts/
```

設定値には原則としてファイル名を記述し、内部で用途別ディレクトリへ解決する。

---

## 7. 設定ファイル仕様

例:

```toml
[model]
root = "D:/AI/models"
checkpoint = "model.safetensors"
vae = "vae.safetensors"

[[model.lora]]
file = "detail.safetensors"
weight = 0.8

[[model.lora]]
file = "style.safetensors"
weight = 0.5

[generation]
steps = 25
cfg_scale = 7.0
scheduler = "dpmpp_2m_karras"
default_size = "square_512"

[controlnet.depth]
enabled = true
model = "control_v11f1p_sd15_depth.safetensors"
preprocessor = "midas"

[controlnet.openpose]
enabled = true
model = "control_v11p_sd15_openpose.safetensors"

[controlnet.inpaint]
enabled = true
model = "control_v11p_sd15_inpaint.safetensors"

[output]
directory = "./outputs"

[prompt]
positive_file = "positive.txt"
negative_file = "negative.txt"
```

### 7.1 Scheduler

`generation.scheduler`は次の5種類のみを許可し、既定値は`dpmpp_2m_karras`とする。

| 値 | 動作 |
|---|---|
| `dpmpp_2m_karras` | DPM++ 2M + Karras sigmas |
| `dpmpp_2m_sde_karras` | DPM++ 2M SDE + Karras sigmas |
| `euler_a` | Euler Ancestral |
| `ddim` | DDIM |
| `lcm` | Latent Consistency Model scheduler |

`lcm`選択時も`steps`と`cfg_scale`は設定値をそのまま使用する。LoRAファイル名から
LCM-LoRAを推測したり、生成設定を自動変更したりしない。

---

## 8. CLI要件

| 引数 | 仕様 |
|---|---|
| `--config PATH` | 使用するTOML設定ファイルを指定 |
| `--version` | アプリケーションのバージョンを表示 |

その他の実行設定はCLIでは提供しない。

---

## 9. 非機能要件

| 分類 | 要件 |
|---|---|
| VRAM | 8GB級GPUでの動作を主対象 |
| Precision | FP16を基本 |
| Batch | 1固定 |
| 同時実行 | 1生成のみ |
| キュー | 単一GPUキュー |
| ネットワーク | 推論時に外部通信を必須としない |
| モデルDL | 起動時の自動ダウンロードを前提としない |
| 異常系 | 設定不正・モデル不正は起動時エラー |
| ログ | 実行状態、モデル構成、エラーを記録 |
| 再現性 | seedを結果メタデータとして記録可能 |
| セキュリティ | 設定外パスへの任意アクセスを避ける |
| 保守性 | MCP層と画像生成層を分離 |

---

## 10. 主要コンポーネント

| コンポーネント | 役割 |
|---|---|
| Python 3.11 | 実装言語 |
| uv | Python・依存関係・仮想環境・lock管理 |
| MCP Python SDK | MCP server実装 |
| PyTorch | CUDA / Tensor実行 |
| Diffusers | SD1.x / VAE / LoRA / ControlNet統合 |
| Transformers | CLIP tokenizer / text encoder |
| PEFT | LoRA adapter管理 |
| Safetensors | モデルファイル読込 |
| Pillow | 画像入出力 |
| NumPy | 画像・前処理 |
| OpenCV | 必要な画像前処理 |
| tomllib | TOML設定読込 |
| pytest | テスト |
| Ruff | lint / format |
| Pyright | 静的型チェック |

---

## 11. 完了条件

| ID | 完了条件 |
|---|---|
| G1 | TOMLからcheckpoint / 任意の外部VAE / 複数LoRAをロードでき、VAE componentが常に存在する |
| G2 | `generate_image`でPNG画像を1枚生成できる |
| G3 | Depth / Openpose / Openpose Full生成が動作する |
| G4 | Inpaintが元画像+maskから動作する |
| G5 | 3ツールすべてMCP経由で呼び出せる |
| G6 | 同時生成が1ジョブに制御される |
| G7 | 不正設定・不正モデル時に起動失敗する |
| G8 | GPU不要の設定・schemaテストが自動実行できる |