# 機能設計書 7-画像生成ノード

## 概要

本ドキュメントは、Giselleにおける画像生成ノード機能の設計を定義する。AIモデル（OpenAI DALL-E、Google Imagen、Fal）を使用して画像を生成するオペレーションノードの型定義とデータ構造を規定する。

### 本機能の処理概要

画像生成ノードは、ワークフロー内でAI画像生成モデルを使用して画像を生成するためのオペレーションノードである。複数のAIプロバイダーに対応し、プロンプトに基づいて画像を生成する。

**業務上の目的・背景**：Giselleのワークフローにおいて、テキストから画像を生成する機能はクリエイティブな用途やビジュアルコンテンツの自動生成に不可欠である。本機能により、複数のAI画像生成プロバイダー（OpenAI、Google、Fal）から適切なモデルを選択し、プロンプトに基づいた画像生成が可能となる。生成された画像はワークフロー内で後続処理に活用できる。

**機能の利用シーン**：ワークフローエディタ画面で画像生成ノードを追加・編集する時、タスク実行時に画像生成ステップが実行される時、プロンプトベースの画像生成を行う時などに利用される。

**主要な処理内容**：
1. 画像生成ノードの型定義（ImageGenerationContent）
2. 対応言語モデルプロバイダーの定義（OpenAI、Google、Fal）
3. 各プロバイダー固有の設定（configurations）の定義

**関連システム・外部連携**：language-modelパッケージによる各AIプロバイダーの画像生成モデル定義と連携。

**権限による制御**：APIキー設定により、外部サービスへのアクセス権限を管理する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 補助機能 | AIモデルを使用した画像生成ノードの追加・編集 |

## 機能種別

データ型定義 / ノード構造定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "imageGeneration" | Yes | ノードコンテンツ種別 | リテラル型 |
| llm | ImageGenerationLanguageModelData | Yes | 使用する画像生成モデル設定 | discriminatedUnion |
| prompt | string | No | 画像生成プロンプト | 文字列 |

### 言語モデルデータ構造

| プロバイダー | 型 | 含まれるフィールド |
|------------|-----|------------------|
| openai | OpenAIImageLanguageModelData | provider, id, configurations |
| google | GoogleImageLanguageModelData | provider, id, configurations |
| fal | FalLanguageModelData | provider, id, configurations |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| image | ImageData | 生成された画像データ |

### 出力先

- ワークフロー内の後続ノード（接続経由）
- タスク実行結果（Generation）

## 処理フロー

### データ構造定義フロー

```
1. 各プロバイダーのLanguageModelData定義
   └─ FalLanguageModelData
   └─ OpenAIImageLanguageModelData
   └─ GoogleImageLanguageModelData

2. ImageGenerationLanguageModelData定義
   └─ 3種類のプロバイダーをdiscriminatedUnionで統合

3. ImageGenerationContent定義
   └─ type: "imageGeneration"固定
   └─ llm: モデル設定
   └─ prompt: 画像生成プロンプト
```

### フローチャート

```mermaid
flowchart TD
    A[ImageGenerationContent] --> B{プロバイダー選択}
    B -->|openai| C[OpenAIImageLanguageModelData]
    B -->|google| D[GoogleImageLanguageModelData]
    B -->|fal| E[FalLanguageModelData]

    A --> F[prompt設定]
    F --> G[画像生成プロンプト]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | プロバイダー選択 | llmフィールドで1つのプロバイダーを選択 | 常に適用 |
| BR-002 | プロンプト任意 | promptは省略可能 | 常に適用 |

### 計算ロジック

特になし（型定義のため）

## データベース操作仕様

本機能は型定義のため、直接のデータベース操作は発生しない。ワークスペースのノードとしてストレージに保存される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | Zodスキーマ検証失敗 | 入力データの確認 |
| INVALID_PROVIDER | プロバイダー不正 | 未対応のプロバイダー指定 | 対応プロバイダーを使用 |

### リトライ仕様

型定義のため該当なし

## トランザクション仕様

型定義のため該当なし

## パフォーマンス要件

型定義のため該当なし

## セキュリティ考慮事項

- 各プロバイダーのAPIキーの安全な管理が必要
- 画像生成プロンプトの内容に関するコンテンツポリシー遵守

## 備考

- ImageGenerationContentReferenceはノード参照時の軽量版として使用
- isImageGenerationLanguageModelData関数でデータ検証が可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | image-generation.ts | `packages/protocol/src/node/operations/image-generation.ts` | ImageGenerationContent全体構造 |

**読解のコツ**: テキスト生成ノードと同様のdiscriminatedUnionパターンを理解する。

#### Step 2: 言語モデル定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | image-generation.ts | `packages/protocol/src/node/operations/image-generation.ts` | 各プロバイダーのLanguageModelData（8-31行目） |

**主要処理フロー**:
- **8-13行目**: FalLanguageModelData定義
- **15-22行目**: OpenAIImageLanguageModelData定義
- **24-31行目**: GoogleImageLanguageModelData定義
- **33-40行目**: ImageGenerationLanguageModelData（discriminatedUnion）

#### Step 3: ImageGenerationContentを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | image-generation.ts | `packages/protocol/src/node/operations/image-generation.ts` | ImageGenerationContent定義（59-64行目） |

**主要処理フロー**:
- **59行目**: type: "imageGeneration"固定
- **60行目**: llm: ImageGenerationLanguageModelData
- **63行目**: prompt: z.string().optional()

### プログラム呼び出し階層図

```
ImageGenerationContent (image-generation.ts)
    │
    ├─ type: z.literal("imageGeneration")
    │
    ├─ llm: ImageGenerationLanguageModelData
    │      └─ z.discriminatedUnion("provider", [...])
    │             ├─ OpenAIImageLanguageModelData
    │             ├─ GoogleImageLanguageModelData
    │             └─ FalLanguageModelData
    │
    └─ prompt: z.string().optional()
```

### データフロー図

```
[ワークフローエディタ]              [プロトコル層]              [実行層]

ノード設定UI ───▶ ImageGenerationContent
    │                     │
    │                     ├─ llm設定 ───▶ 画像生成モデル選択
    │                     │
    │                     └─ prompt設定 ───▶ 生成プロンプト
    │
    ▼
Workspace.nodes[] ───▶ ストレージ保存
                              │
                              ▼
                       タスク実行時参照 ───▶ AI画像生成呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| image-generation.ts | `packages/protocol/src/node/operations/image-generation.ts` | ソース | ImageGenerationContent定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | ImageGenerationNode型、isImageGenerationNode関数 |
| index.ts | `packages/language-model/src/index.ts` | ソース | 言語モデル基本定義 |
