# 機能設計書 6-テキスト生成ノード

## 概要

本ドキュメントは、Giselleにおけるテキスト生成ノード機能の設計を定義する。AIモデル（Anthropic Claude、Google Gemini、OpenAI GPT、Perplexity）を使用してテキストを生成するオペレーションノードの型定義とデータ構造を規定する。

### 本機能の処理概要

テキスト生成ノードは、ワークフロー内でAI言語モデルを使用してテキストを生成するためのオペレーションノードである。複数のAIプロバイダーに対応し、ツール連携（GitHub、PostgreSQL、Web検索）も可能な柔軟な構成を持つ。

**業務上の目的・背景**：Giselleのワークフローにおいて、AI言語モデルによるテキスト生成は中核的な機能である。ユーザーはプロンプトを設定し、入力データを基にAIモデルがテキストを生成する。本機能により、複数のAIプロバイダー（Anthropic、Google、OpenAI、Perplexity）から適切なモデルを選択し、ツール連携を活用した高度なテキスト生成が可能となる。生成結果はワークフロー内の他のノードに渡され、後続処理に活用される。

**機能の利用シーン**：ワークフローエディタ画面でテキスト生成ノードを追加・編集する時、タスク実行時にテキスト生成ステップが実行される時、GitHub連携やWeb検索を含む複合的なテキスト生成を行う時などに利用される。

**主要な処理内容**：
1. テキスト生成ノードの型定義（TextGenerationContent）
2. 対応言語モデルプロバイダーの定義（Anthropic、Google、OpenAI、Perplexity）
3. ツール連携設定の定義（GitHub、PostgreSQL、OpenAI Web検索、Anthropic Web検索）
4. 出力フォーマットの指定（テキスト、JSON）

**関連システム・外部連携**：language-modelパッケージによる各AIプロバイダーの言語モデル定義と連携。ツール連携時はGitHub API、PostgreSQLデータベース、Web検索APIと連携。

**権限による制御**：ツール認証設定（PAT、シークレット）により、外部サービスへのアクセス権限を管理する。

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "textGeneration" | Yes | ノードコンテンツ種別 | リテラル型 |
| llm | TextGenerationLanguageModelData | Yes | 使用する言語モデル設定 | discriminatedUnion |
| prompt | string | No | プロンプトテンプレート | 文字列 |
| tools | ToolSet | No | ツール連携設定 | オブジェクト |
| output | Output | Yes | 出力フォーマット設定 | デフォルト: {format: "text"} |

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

| プロバイダー | 型 | 含まれるフィールド |
|------------|-----|------------------|
| anthropic | AnthropicLanguageModelData | provider, id, configurations |
| google | GoogleLanguageModelData | provider, id, configurations |
| openai | OpenAILanguageModelData | provider, id, configurations |
| perplexity | PerplexityLanguageModelData | provider, id, configurations |

### ツールセット構造

| ツール名 | 型 | 説明 |
|---------|-----|------|
| github | GitHubTool | GitHub API連携 |
| postgres | PostgresTool | PostgreSQLクエリ実行 |
| openaiWebSearch | OpenAIWebSearchTool | OpenAI Web検索 |
| anthropicWebSearch | AnthropicWebSearchTool | Anthropic Web検索 |

## 出力仕様

### 出力データ

テキスト生成ノードの出力は、設定されたOutputフォーマットに従う：

| 出力形式 | 説明 |
|---------|------|
| text | プレーンテキスト形式の生成結果 |
| json | 構造化JSON形式の生成結果（スキーマ指定可能） |

### 出力先

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

## 処理フロー

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

```
1. TextGenerationLanguageModelData定義
   └─ 4種類のプロバイダーをdiscriminatedUnionで統合

2. ToolSet定義
   └─ GitHubTool（ツール選択、認証設定）
   └─ PostgresTool（ツール選択、シークレットID）
   └─ OpenAIWebSearchTool（検索コンテキストサイズ、位置情報）
   └─ AnthropicWebSearchTool（最大使用回数、許可/ブロックドメイン）

3. TextGenerationContent定義
   └─ type: "textGeneration"固定
   └─ llm: モデル設定
   └─ prompt: プロンプトテンプレート
   └─ tools: ツール設定
   └─ output: 出力形式
```

### フローチャート

```mermaid
flowchart TD
    A[TextGenerationContent] --> B{プロバイダー選択}
    B -->|anthropic| C[AnthropicLanguageModelData]
    B -->|google| D[GoogleLanguageModelData]
    B -->|openai| E[OpenAILanguageModelData]
    B -->|perplexity| F[PerplexityLanguageModelData]

    A --> G{ツール設定}
    G -->|github| H[GitHubTool]
    G -->|postgres| I[PostgresTool]
    G -->|openaiWebSearch| J[OpenAIWebSearchTool]
    G -->|anthropicWebSearch| K[AnthropicWebSearchTool]

    A --> L[Output設定]
    L --> M{format}
    M -->|text| N[テキスト出力]
    M -->|json| O[JSON出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | プロバイダー選択 | llmフィールドで1つのプロバイダーを選択 | 常に適用 |
| BR-002 | ツール認証 | GitHubToolはPATまたはシークレットIDで認証 | GitHubツール使用時 |
| BR-003 | デフォルト出力 | outputは未指定時"text"形式 | 常に適用 |
| BR-004 | Web検索ドメイン制限 | AnthropicWebSearchToolで許可/ブロックドメイン指定可能 | Anthropic Web検索使用時 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

型定義のため該当なし

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

型定義のため該当なし

## パフォーマンス要件

型定義のため該当なし（Zodパース時間は無視できる程度）

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

- GitHubTool認証情報（PAT、シークレット）の安全な管理が必要
- PostgresToolのシークレットIDは暗号化されたシークレットストアを参照
- Web検索ツールのドメイン制限でアクセス範囲を制御可能

## 備考

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

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: Zod v4の`z.discriminatedUnion`による複数プロバイダーの統合パターンを理解する。

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

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

**主要処理フロー**:
- **11-18行目**: AnthropicLanguageModelData定義
- **19-24行目**: GoogleLanguageModelData定義
- **25-30行目**: OpenAILanguageModelData定義
- **32-39行目**: PerplexityLanguageModelData定義
- **51-59行目**: TextGenerationLanguageModelData（discriminatedUnion）

#### Step 3: ツール定義を理解する

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

**主要処理フロー**:
- **69-78行目**: ToolAuthPat、ToolAuthSecret定義
- **79-83行目**: GitHubTool定義
- **85-89行目**: PostgresTool定義
- **91-103行目**: OpenAIWebSearchTool定義
- **105-110行目**: AnthropicWebSearchTool定義
- **112-118行目**: ToolSet統合定義

#### Step 4: TextGenerationContent全体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | text-generation.ts | `packages/protocol/src/node/operations/text-generation.ts` | TextGenerationContent定義（120-127行目） |

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

```
TextGenerationContent (text-generation.ts)
    │
    ├─ type: z.literal("textGeneration")
    │
    ├─ llm: TextGenerationLanguageModelData
    │      └─ z.discriminatedUnion("provider", [...])
    │             ├─ AnthropicLanguageModelData
    │             ├─ GoogleLanguageModelData
    │             ├─ OpenAILanguageModelData
    │             └─ PerplexityLanguageModelData
    │
    ├─ prompt: z.string().optional()
    │
    ├─ tools: ToolSet
    │      ├─ github?: GitHubTool
    │      │      └─ auth: ToolAuthPat | ToolAuthSecret
    │      ├─ postgres?: PostgresTool
    │      ├─ openaiWebSearch?: OpenAIWebSearchTool
    │      └─ anthropicWebSearch?: AnthropicWebSearchTool
    │
    └─ output: Output.default({format: "text"})
```

### データフロー図

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

ノード設定UI ───▶ TextGenerationContent
    │                     │
    │                     ├─ llm設定 ───▶ 言語モデル選択
    │                     │
    │                     ├─ prompt設定 ───▶ プロンプトテンプレート
    │                     │
    │                     ├─ tools設定 ───▶ ツール連携
    │                     │
    │                     └─ output設定 ───▶ 出力形式
    │
    ▼
Workspace.nodes[] ───▶ ストレージ保存
                              │
                              ▼
                       タスク実行時参照 ───▶ AIモデル呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| text-generation.ts | `packages/protocol/src/node/operations/text-generation.ts` | ソース | TextGenerationContent定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | TextGenerationNode型、isTextGenerationNode関数 |
| index.ts | `packages/language-model/src/index.ts` | ソース | 言語モデル基本定義 |
| secret.ts | `packages/protocol/src/secret.ts` | ソース | SecretId定義 |
| structured-output.ts | `packages/protocol/src/structured-output.ts` | ソース | Output定義 |
