コンテンツにスキップ

ライブラリの作成 (Authoring Libraries)

ノードはライブラリとしてパッケージ化・配布されます。本ページでは、ライブラリマニフェスト（griptape_nodes_library.json）、宣言（Declarations）、依存関係管理、ドキュメントの規約、および標準ライブラリへのノードのコントリビューション手順について解説します。

ノードライブラリの作成 (Creating Node Libraries)

共有のために複数のノードをライブラリとしてまとめます。griptape_nodes_library.json を作成します：

{
  "name": "Library Name",
  "library_schema_version": "0.11.0",
  "settings": [
    {
      "description": "このライブラリのノードが必要とする API キー",
      "category": "app_events.on_app_initialization_complete",
      "contents": {
        "secrets_to_register": ["MY_SERVICE_API_KEY", "MY_OTHER_API_KEY"]
      }
    }
  ],
  "metadata": {
    "author": "Author Name",
    "description": "ライブラリの説明",
    "library_version": "1.0.0",
    "engine_version": "0.55.0",
    "tags": ["AI", "Image Processing"],
    "dependencies": {
      "pip_dependencies": ["pillow", "requests"],
      "pip_install_flags": ["--upgrade"]
    },
    "declarations": [
      { "type": "lifecycle_stage", "stage": "STABLE" },
      {
        "type": "model_catalog",
        "providers": {
          "anthropic": {
            "display_name": "Anthropic",
            "terms_url": "https://www.anthropic.com/legal/commercial-terms",
            "models": {
              "claude_opus_byok": {
                "display_name": "Claude Opus 4 (BYOK)",
                "family": "Claude 4",
                "provider_model_id": "claude-opus-4",
                "key_support": "REQUIRES_CUSTOMER_KEY"
              }
            }
          }
        }
      }
    ]
  },
  "widgets": [
    {
      "name": "MyWidget",
      "path": "widgets/MyWidget.js",
      "description": "ノード用のカスタム UI コンポーネント"
    }
  ],
  "categories": [
    {
      "image": {
        "title": "画像処理",
        "description": "画像操作ノード",
        "color": "border-purple-500",
        "icon": "Image"
      }
    }
  ],
  "nodes": [
    {
      "class_name": "MyImageNode",
      "file_path": "image/my_image_node.py",
      "metadata": {
        "category": "image",
        "description": "AI による画像処理",
        "display_name": "AI Image Processor",
        "icon": "image",
        "group": "processing",
        "declarations": [
          { "type": "model_usage", "model_ids": ["claude_opus_byok"] }
        ]
      }
    }
  ],
  "workflow_nodes": [
    {
      "node_type": "UpscaleAndTag",
      "workflow_path": "workflows/upscale_and_tag.py",
      "metadata": {
        "category": "image",
        "description": "画像をアップスケールしてタグ付け",
        "display_name": "Upscale and Tag"
      }
    }
  ],
  "workflows": ["workflows/example_workflow.py"],
  "is_default_library": false
}

ライブラリ構成 (Library Structure)

  • settings: ライブラリのノードが使用するシークレット/API キーを登録します
    • 必要なシークレットを宣言するには secrets_to_register 配列を使用します
    • カテゴリは app_events.on_app_initialization_complete に設定する必要があります
    • シークレットは GriptapeNodes.handle_request(GetSecretValueRequest(key=...)) を介して読み取られます
  • metadata.dependencies: ライブラリのロード時にインストールされる PIP パッケージ
  • metadata.declarations / ノードごとの metadata.declarations: 型付きアイデンティティプロパティ（ライフサイクルステージ、任意の Python 実行）およびライブラリレベルのモデルカタログとノードごとの参照。詳細は下記の ライブラリとノードの宣言 を参照してください。
  • beta_features: エディタの「ベータ機能」ページからユーザーが有効化できる実験的機能。詳細は下記の ベータ機能 を参照してください。
  • widgets: カスタム JS ウィジェットコンポーネントを登録します（カスタムウィジェット を参照）
  • categories: UI 上で色やアイコンを用いてノードをグループ化します
  • nodes: ノードクラス、ファイルパス、およびメタデータを一覧表示します
  • advanced_library_path: AdvancedNodeLibrary サブクラスを宣言するオプションの Python ファイル。ロード/アンロード時にコードを実行したり、独自のリクエスト型を所有したり、マニフェストに記載されていないノード型を動的に登録する場合に使用します（高度なライブラリ を参照）
  • workflow_nodes: Python クラスではなく、保存されたワークフローファイルから生成されるノード。詳細は下記の ワークフローファイルからのノード生成 を参照してください。
  • workflows: テンプレートワークフローファイル

重要: secrets_to_register 配列は、ライブラリが必要とするシークレットをシステムに通知します。ユーザーには、UI または環境変数を介してこれらのシークレットを設定するよう促されます。

フラットなディレクトリ構造を使用してください。エンジンは自動的にライブラリを登録およびロードします。

ワークフローファイルからのノード生成

ノードは必ずしも Python クラスである必要はありません。workflow_nodes エントリで保存されたワークフローを指定すると、エンジンがノード型を自動生成します：

"workflow_nodes": [
  {
    "node_type": "UpscaleAndTag",
    "workflow_path": "workflows/upscale_and_tag.py",
    "metadata": {
      "category": "image",
      "description": "画像をアップスケールしてタグ付け",
      "display_name": "Upscale and Tag"
    }
  }
]
フィールド 意味
node_type ノードが登録される名前。保存されたワークフロー内に記録される識別子です。
workflow_path griptape_nodes_library.json からの相対パスで指定された、保存済みワークフロー .py へのパス。
metadata nodes 配列で使用されるものと同じノードメタデータブロック: カテゴリ、説明、表示名など。

ワークフローには Start Flow ノードと End Flow ノードが必要です。 これらがノードのパラメータを定義します：

  • Start Flow ノード上のすべての非制御パラメータが、ノードの 入力 (Input) パラメータになります。
  • End Flow ノード上のすべての非制御パラメータが、ノードの 出力 (Output) パラメータになります。
  • ノード自身が Flow In と Flow Out を提供するため、ワークフロー内部の制御パラメータは外部に公開されません。
  • End Flow ノードの組み込み Status パラメータ（was_successful, result_details）も外部には公開されません。これらは End Flow ノード自身の実行を報告するものであり、公開対象ではありません。自身で作成したパラメータがこれらの名前を持つ場合、Status という名前のパラメータグループ内に配置されている場合にのみ除外されます。

単一の Start Flow または End Flow ノードで使用されているパラメータ名は、そのままの名前を維持します。2 つの Start Flow ノードが両方とも prompt を公開している場合、どちらも失われないようノード名で修飾されます（Start_Flow.prompt, Start_Flow_2.prompt）。パラメータ名に空白を含めることはできないため、ノード名のスペースはアンダースコアに変換されます。Start Flow ノードと End Flow ノードの両方に現れる名前は、入力と出力の両方を兼ねる単一のパラメータになります。

ノードが実行されると、エンジンはワークフローをノード自身のフローの子サブフローとしてロードし、ノードの入力値を Start Flow ノードにコピーして実行し、End Flow の値を取り出してノードの出力として設定します。サブフローは同一セッション内の後続の実行で再利用され、保存されたワークフロー内に書き出されることはないため、ユーザーのファイルには背後にあるワークフローのコピーではなく、ノードそのもののみが記録されます。

配布する前に、エディタからワークフローを保存してください。 パラメータの形状は、ワークフローファイルの先頭にあるメタデータヘッダーから読み取られます（エディタが保存時に書き込みます）。保存された形状が存在しないワークフロー（Start Flow や End Flow ノードがない、またはヘッダーのない手書きファイル）はライブラリの問題として報告され、ノードは登録されません。

ワークフローは単体のワークフローとしても登録されるため、エディタのワークフロー選択ツールに表示されます。ノードの背後でのみ機能するワークフローをこの一覧から除外したい場合は、メタデータヘッダーで is_internal = true を設定してください。

ライブラリとノードの宣言 (Library and Node Declarations)

宣言（Declarations）は、ライブラリまたは個々のノードに型付きメタデータをアタッチします。declarations 配列の各エントリは、宣言クラスを選択する type 識別子を持つオブジェクトです。現在のボキャブラリには、ライフサイクルステージプロパティ、ノードごとの参照を持つライブラリレベルのモデルカタログ、および任意の Python 実行プロパティが含まれます。将来のエンジンリリースでは、同じフィールドの下にさらに多くの宣言型が追加される予定です。

metadata.declarations（ライブラリレベル）とノードごとの metadata.declarations の両方がリストを受け入れます。リスト内の順序は関係ありません。このフィールドのデフォルトは [] であるため、古いスキーマバージョン（0.6.0, 0.4.0, 0.1.0）のライブラリも変更なしでロードされます。

lifecycle_stage

ライブラリまたは特定のノードのライフサイクルステージ。値：

値 意味
STABLE 成熟。本番環境での使用を想定。
BETA 機能的に完全だが、安定化の途上。
ALPHA 初期の実験的実装。破壊的変更が予想される。
LABS 探索的。将来削除される可能性がある。
DEPRECATED 削除予定。既存の使用箇所は代替品へ移行すべき。

セマンティクス：

  • ライブラリレベルでの欠落は、意図的に STABLE とは区別されます。 lifecycle_stage 宣言のないライブラリは「未指定」です — コンシューマ（UI など）は暗黙的に STABLE と想定するのではなく、明示的にその旨を表示すべきです（<ライブラリ作成者によってライフサイクルステージが指定されていません>）。
  • ノードレベルでの欠落は「ライブラリのステージを継承する」ことを意味します。 ノードレベルの lifecycle_stage はライブラリの値を上書きします。

model_catalog

ライブラリ内のノードが使用できるサードパーティモデルのライブラリレベルの宣言であり、provider → model レジストリとして構成されます。両方のレベルの識別子は辞書のキーです（このキーがノードの参照や管理者ポリシーで使用される安定したハンドルになります）。各エントリは UI 用の display_name と、オプションの terms_url および notes を保持します。各 Model はさらに、key_support（必須）、オプションの family グルーピングタグ、およびオプションの上流 provider_model_id を宣言します。

key_support の値は、どのような種類の API キーが呼び出しを認可するかを管理者に伝えます：

値 意味
REQUIRES_CUSTOMER_KEY ユーザー提供の API キー（BYOK）のみ。
SUPPORTS_CUSTOMER_KEY_OR_GRIPTAPE_KEY ユーザーキーと Griptape 提供キーの両方をサポート。
REQUIRES_GRIPTAPE_KEY Griptape 提供キーのみ。
NO_KEY_REQUIRED モデルがローカルで実行されるか、API キーを必要としない（例: Ollama ホストモデル）。

notes（プロバイダーとモデルの両方で利用可能）は、エントリと並んで表示される自由形式の作成者ガイダンスです。「BYOK ではプロバイダー固有のプロンプトドライバーの挿入が必要」など、他のフィールドに収まらない注意事項に使用します。

{
  "type": "model_catalog",
  "providers": {
    "anthropic": {
      "display_name": "Anthropic",
      "terms_url": "https://www.anthropic.com/legal/commercial-terms",
      "models": {
        "claude_opus_byok": {
          "display_name": "Claude Opus 4 (BYOK)",
          "family": "Claude 4",
          "provider_model_id": "claude-opus-4",
          "key_support": "REQUIRES_CUSTOMER_KEY"
        },
        "claude_opus_griptape": {
          "display_name": "Claude Opus 4 (Griptape Key)",
          "family": "Claude 4",
          "provider_model_id": "claude-opus-4",
          "key_support": "REQUIRES_GRIPTAPE_KEY"
        }
      }
    },
    "kling": {
      "display_name": "Kling",
      "terms_url": "https://app.klingai.com/global/about/terms",
      "models": {
        "kling_v2": {
          "display_name": "Kling v2",
          "provider_model_id": "kling-v2-master",
          "key_support": "REQUIRES_GRIPTAPE_KEY"
        }
      }
    },
    "ollama": {
      "display_name": "Ollama",
      "key_support": "NO_KEY_REQUIRED",
      "notes": "ローカルランタイム。モデルは実行時に列挙され、ここでは宣言されません。"
    }
  }
}

知っておくべき重要なルール：

  • family は単なるタグです。 表示上で関連モデルをグループ化します（上記の 2 つの Claude 4 エントリなど）。コンテナではなくモデルのアイデンティティの一部でもないため、明確なファミリーを持たないプロバイダーでは省略可能です。
  • key_support はデフォルトでモデル上に配置されます。 各 Model が独自に値を宣言します。キー要件が異なる同じ上流モデルは、2 つの異なる辞書キーの下に 2 つのモデルとして定義されます（上記の claude_opus_byok と claude_opus_griptape を参照）。ModelProvider もオプションで key_support を受け入れますが、これはモデルを一切宣言しない場合にのみ使用されます（key_support=NO_KEY_REQUIRED が唯一の意味を持つシグナルである Ollama のようなローカルランタイムプロバイダーなど）。
  • モデル ID はライブラリ全体で一意である必要があります。 Pydantic は各プロバイダーの models 辞書内の一意性を強制します。プロバイダー間での重複衝突は、ライブラリロード時に DuplicateModelIdProblem として検出されます。
  • 1 つのライブラリに定義できる model_catalog は最大 1 つです。 2 つ宣言するとバリデーション時に拒否されます。プロバイダーを 1 つにマージしてください。

ノードのモデル選択ドロップダウンには、プロバイダー自身のモデル ID（Kling v2 ではなく kling-v2-master）が格納され、ModelAccessComponent がそれを権限制御レイヤーがチェックするカタログキーに解決します。代わりに表示名を保存すると選択を解決できず、ライセンスポリシーに対するチェックも行えなくなります。ドロップダウンが過去に別の形式で保存されていた場合は、カタログエントリの名前を変更して合わせるのではなく、コンポーネントの deprecated_values マッピングを使用してそれらの保存値を移行してください：

self._model_access = ModelAccessComponent(
    node=self,
    parameter=model_param,
    model_choices=["kling-v2-master", "kling-v2-1-master"],
    default_model="kling-v2-master",
    deprecated_values={"Kling v2": "kling-v2-master", "Kling v2.1": "kling-v2-1-master"},
)

各キーは値が代入されるあらゆる場所（ワークフローのロードを含む）で受け入れられ、マッピング先の選択肢に移行されます。古いキーがドロップダウンの選択肢として提示されることはないため、モデルを廃止（リタイア）する場合は、それを model_choices から deprecated_values に移動して後継モデルを指定します。マッピング先の値は必ず model_choices のいずれかでなければならず、キーが既存の選択肢に含まれていてはなりません（どちらの誤りもノード構築時に例外を送出します）。廃止するモデルが default_model であった場合は、同じ編集で default_model も後継モデルに向けてください — default_model は常に現在の選択肢を指す必要があり、廃止されたキーを指定することはできません。

model_usage

ノードは辞書キーによってカタログの 1 つ以上のモデルを参照します。ノードが特定の明確なモデルセットにバインドされる場合に使用します。各エントリは、ライブラリロード時にカタログ内のどこかのモデルに解決される必要があり、未解決の参照は UnresolvedModelUsageReferenceProblem として表面化します。

{ "type": "model_usage", "model_ids": ["claude_opus_byok", "kling_v2"] }
model_provider_usage

ノードは 1 つ以上のプロバイダー全体を参照します。ノードが実行時にプロバイダーが提供するすべてのモデルを動的に列挙する場合に使用します。各エントリはカタログで宣言されたプロバイダーに解決される必要があり、未解決の参照は UnresolvedModelProviderUsageReferenceProblem として表面化します。

{ "type": "model_provider_usage", "provider_ids": ["anthropic", "ollama"] }

これら 2 つの使用宣言は独立しています。ノードは任意の組み合わせを持つことができます（例: 「このプロバイダーが提供するすべてのモデルに加えて、別のプロバイダーからのこれら 2 つの特定モデル」など）。

arbitrary_python_execution

ノードが実行時に提供された任意の Python コードを実行すること（クリエイターが作成したスクリプトなど）を宣言します。ノードレベル専用です。これはセキュリティに関わる重要なアイデンティティファクトであり、コンシューマ（UI）はノードが実行される前に警告を表示できます。この宣言がない場合、ノードは任意の Python を実行しないことを意味します。

フィールド 意味
executes_arbitrary_python ノードが未検証の実行時提供 Python を実行する場合に true。 
"declarations": [
  { "type": "arbitrary_python_execution", "executes_arbitrary_python": true }
]

宣言の組み合わせ

ノードは宣言を自由に組み合わせることができます。たとえば、2 つのモデルを使用する Labs ノードの場合：

"metadata": {
  "category": "labs",
  "description": "複数の宣言を示す Labs ノード。",
  "display_name": "Labs Node",
  "declarations": [
    { "type": "lifecycle_stage", "stage": "LABS" },
    { "type": "model_usage", "model_ids": ["claude_opus_byok", "kling_v2"] }
  ]
}

今後のエンジンリリースで追加される新しい宣言型は、スキーマバージョンの更新なしに、この同じ declarations フィールドの下に加法的に追加されます。

ベータ機能 (Beta Features)

ベータ機能を使用すると、ライブラリ内に新しい機能を同梱しつつ、ユーザーが試すことを選択するまで無効化しておくことができます。機能はエディタの ベータ機能 設定ページの Engine グループに表示され、ユーザーがオン/オフを切り替えます。各機能の description にライブラリのノード名を記載し、どのライブラリに属するかがユーザーに分かるようにしてください。

各機能は、griptape_nodes_library.json のトップレベル（name, metadata, nodes と並ぶ位置）にある beta_features リストで宣言します。metadata の一部ではありません：

"beta_features": [
  {
    "id": "sharpen_after_upscale",
    "name": "アップスケール後にシャープ化",
    "description": "Upscale Image ノードにシャープ化設定を追加します。",
    "owner": "@your-github-handle",
    "remove_by": "2027-03-31"
  }
]

remove_by には、機能を追加した日から 180 日以内の日付を設定してください。

フィールド 意味
id 文字と数字を単一のアンダースコアで繋いだ小文字の文字列で、文字から始まる必要があります。ライブラリ内で一意。
name ベータ機能ページに表示される短いラベル。
description 何がどこで変更されるかをユーザーに伝える 1〜2 文の説明。
default オプション。選択を行っていないユーザーに対して機能を有効にするかどうか。デフォルトは false。
owner 機能の完成または削除を担当する責任者。
remove_by 機能を標準化するか削除する期限となる YYYY-MM-DD 形式の日付。追加日から最大 180 日以内。

ノード内からは self.is_beta_feature_enabled("<id>") で機能をチェックします。ユーザーの選択、または未選択の場合は default を返します。機能が使用するパラメータは常に作成し、機能の有効無効に基づいて非表示または表示のみを切り替えてください。 これにより、機能を有効にして保存されたワークフローであっても、無効にしている別のユーザー環境で問題なく開くことができます（逆も同様）。

from typing import Any

from griptape_nodes.exe_types.core_types import Parameter
from griptape_nodes.exe_types.node_types import DataNode


class UpscaleImage(DataNode):
    def __init__(self, name: str, metadata: dict[str, Any] | None = None) -> None:
        super().__init__(name, metadata)

        self.add_parameter(
            Parameter(name="image", input_types=["ImageArtifact"], type="ImageArtifact", tooltip="アップスケールする画像")
        )
        self.add_parameter(Parameter(name="upscaled_image", output_type="ImageArtifact", tooltip="アップスケールされた画像"))

        # すべてのユーザーに対して作成され、ベータ機能を有効にしたユーザーにのみ表示される。
        self.add_parameter(
            Parameter(
                name="sharpen",
                input_types=["float"],
                type="float",
                default_value=0.0,
                tooltip="アップスケール後に画像をシャープ化する強度",
            )
        )
        if not self.is_beta_feature_enabled("sharpen_after_upscale"):
            self.hide_parameter_by_name("sharpen")

    def process(self) -> None:
        image = self.get_parameter_value("image")
        upscaled = upscale(image)

        if self.is_beta_feature_enabled("sharpen_after_upscale"):
            upscaled = sharpen(upscaled, self.get_parameter_value("sharpen"))

        self.parameter_output_values["upscaled_image"] = upscaled

知っておくべき重要なルール：

  • 1 つのエントリに誤りがあっても、ライブラリ全体のロードは停止しません。 欠落したフィールド、無効な id、または重複した id はライブラリの問題として報告され、その機能のみが除外されます。他の機能やノードは正常に動作します。
  • 宣言していない id をチェックすると false が返され、該当機能を指定した警告ログが出力されます。
  • __init__ でのチェックはノード作成時にのみ実行されます。 ユーザーが機能のオン/オフを切り替えた場合、キャンバス上に配置済みのノードは、ユーザーがリフレッシュするか再追加するかワークフローを開き直すまで、表示されていたパラメータを維持します。process 内でのチェックは、次回の実行時に新しい値を即座に確認します。
  • remove_by の期限を過ぎると、機能は常に default の値を使用します。 ベータ機能ページから消去され、機能を標準機能として組み込むか削除するまでライブラリの問題として報告されます。180 日を超える remove_by も問題として報告されます。
  • ユーザーの選択はライブラリごとに保存されます。 設定内の library_beta_features 配下に、小文字化されスペースや記号がアンダースコアに変換されたライブラリ名でキー付けされます（"Acme Image Tools" は library_beta_features.acme_image_tools.sharpen_after_upscale になります）。英字 a〜z と数字のみが保持されるため、それらを含まないライブラリ名はベータ機能を持つことができず、キーが重複する 2 つのロードされたライブラリは問題として報告されます。
  • ライブラリスキーマ 0.14.0 より前にリリースされたエンジンは beta_features を無視します。 ベータ機能を追加する場合は、library_schema_version を 0.14.0 以降に設定してください。

uv 依存関係管理を使用したライブラリ構成

モダンなアプローチ: Minimax ライブラリのパターンに従い、高速で再現性のある依存関係管理のために uv を使用します。

ディレクトリ構成

library-name/
├── pyproject.toml              # uv 設定
├── uv.lock                     # ロックファイル（自動生成）
├── LICENSE                     # ライセンスファイル
├── README.md                   # ドキュメント
├── CHANGELOG.md                # 変更履歴
├── .gitignore                  # Git 除外設定
└── library_name/
    ├── griptape_nodes_library.json  # ライブラリメタデータ
    └── node_file.py

pyproject.toml の設定

[project]
name = "library-name"
version = "1.0.0"
description = "ライブラリの説明"
authors = [
    {name = "Your Name", email = "email@example.com"}
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests",
    # ノードが実行時にインポートする他のパッケージを追加
]

[dependency-groups]
dev = ["griptape-nodes-engine", "pytest", "pyright", "ruff"]

[tool.uv.sources]
griptape-nodes-engine = { git = "https://github.com/griptape-ai/griptape-nodes-engine", rev = "latest" }

[tool.hatch.build.targets.wheel]
packages = ["library_name"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

エンジンを実行時依存関係として記述しないこと

エンジンはライブラリをロードするホストであり、ライブラリが取り込むパッケージではありません。griptape-nodes-engine は [project] dependencies から除外してください：

  • そうしないと、ライブラリのインストールによって 2 つ目のエンジン がインストールされてしまいます。エンジンはライブラリの仮想環境を独自のインポートパスの先頭に配置するため、その 2 つ目のコピーが実際に稼働しているエンジンを覆い隠してしまい（シャドウイング）、発生したエラーがライブラリのバグではなくエンジンのバグのように見えてしまいます。
  • [dependency-groups] dev を使用することで、uv sync がデフォルトで dev グループをインストールするため、テスト、型チェッカー、およびエディタは問題なくエンジンを参照できます。開発ワークフローは変わりません。
  • ライブラリが必要とするエンジンバージョンは、ライブラリ JSON の engine_version に属します。これはエンジンがロード時に実際にチェックする値であり、pyproject の指定値はロード時には一切参照されません。

両方の場所に宣言すると、同じ事実を 2 重に管理することになり、乖離の原因になります。

この仕様はライブラリパッケージングの進化により変わる予定です

ライブラリが独自の分離環境にパッケージとして解決されるようになると、エンジンは通常の制約付き依存関係（griptape-nodes-engine>=X,<Y）となり、単一の解決処理が engine_version チェックを置き換えます。それが提供されるまでは、上記のレイアウトを使用してください。

ライブラリ設定（サブディレクトリ内）

griptape_nodes_library.json はライブラリサブディレクトリ内に配置します：

{
  "name": "Library Name",
  "library_schema_version": "0.1.0",
  "settings": [
    {
      "description": "ノードが必要とする API キー",
      "category": "app_events.on_app_initialization_complete",
      "contents": {
        "secrets_to_register": ["API_KEY_NAME"]
      }
    }
  ],
  "nodes": [
    {
      "class_name": "NodeClassName",
      "file_path": "node_file.py", // サブディレクトリからの相対パス
      "metadata": {
        "category": "category_name",
        "description": "ノードの説明",
        "display_name": "Node Display Name"
      }
    }
  ]
}

README のインストール手順

uv（推奨）と pip（フォールバック）の両方のインストール方法を記載してください：

## インストール手順

### 方法 1: uv の使用（推奨）

1. このライブラリをクローンまたはダウンロードします

2. 依存関係をインストールします:

   ```bash
   cd library-name
   uv sync
   ```

3. Griptape Nodes の libraries ディレクトリに配置します

### 方法 2: 自動インストール

1. フォルダを libraries ディレクトリに配置します
2. 依存関係が pip 経由で自動的にインストールされます

ロックファイルの生成

cd library-name
uv sync

メリット:

  • 高速なインストール（Rust ベース）
  • ロックファイルによる再現可能なビルド
  • griptape-nodes との直接的な GitHub 連携
  • pip インストールとの後方互換性

ノードライブラリのドキュメントパターン

包括的な README 構成

# Library Name

簡単な説明と主な特徴。

## 機能一覧 (Features)

- 主な機能の箇条書き
- モデルの選択肢
- 独自機能の強調

## インストール手順 (Installation)

### 方法 1: uv の使用（推奨）
uv インストール手順

### 方法 2: 自動インストール
pip インストール手順

## はじめに (Getting Started)

### シンプルモード（初回利用時に推奨）
解説付きの最小構成例

### カスタムモード（上級者向け）
すべての機能を示す高度な例

## パラメータ一覧 (Parameters)

### 基本パラメータ
名前、型、説明のテーブル

### 高度なパラメータ（デフォルト非表示）
名前、型、デフォルト値、説明のテーブル

### 出力パラメータ
出力のテーブル

## モデル比較 (Model Comparison)
| モデル | 最大再生時間 | 品質 | 速度 | 文字数制限 |

## 文字数制限 (Character Limits)
モデル/モードごとの制限を示す明確なテーブル

## API レートリミット (API Rate Limits)
- 同時実行制限
- 生成時間の目安
- ファイル保持ポリシー

## ワークフローの例 (Example Workflows)
一般的なユースケースをカバーする 3〜5 個の完全な例

## エラー処理 (Error Handling)
よくあるエラーと解決策

## トラブルシューティング (Troubleshooting)
FAQ 形式のトラブルシューティングガイド

## API リファレンス (API Reference)
公式 API ドキュメントへのリンク

## ベストプラクティス (Best Practices)
最適な使用のためのヒント

## サポート (Support)
問い合わせ先やヘルプの取得方法

## 変更履歴 (Version History)
CHANGELOG へのリンク

記載すべきトラブルシューティング事例

頻繁に発生するため、ライブラリ README のトラブルシューティングに記載すべき 2 つのエラー：

エラー: "Missing required variables: file_extension, file_name_base"

完全なエラーログ:

ERROR: Attempted to resolve macro path. Failed because missing required variables: file_extension, file_name_base
ERROR: Attempted to create download URL. Failed with file_path='{outputs}/{node_name?:_}{file_name_base}{_index?:03}.{file_extension}'

原因: write_bytes() の戻り値をキャプチャしていない。saved.location ではなく dest.location を使用している。

誤ったコード:

dest = self._output_file.build_file()
dest.write_bytes(video_bytes)  # ❌ 戻り値がキャプチャされていない
artifact = VideoUrlArtifact(dest.location)  # 保存されたファイルではなく dest を使用している

解決策:

dest = self._output_file.build_file()
saved = dest.write_bytes(video_bytes)  # ✅ 保存されたファイルをキャプチャ
artifact = VideoUrlArtifact(saved.location)  # 保存されたファイルの解決済みパスを使用

解説: マクロ変数は、write_bytes() が実際にファイルを保存したときに展開されます。write_bytes() から返される saved オブジェクトに、完全に解決されたパスが含まれています。

エラー: 画像パラメータの型変換に関する問題

症状: 画像パラメータが異なる入力型を一貫して処理できない、またはノード間で URL、ファイルパス、アーティファクトを受け渡す際にエラーが発生する。

原因: 手動の型設定を伴う汎用 Parameter を使用すると、型変換ロジックが標準化されない：

# ❌ 一貫性のない型処理
Parameter(
    name="image",
    input_types=["ImageArtifact", "ImageUrlArtifact", "str"],
    type="ImageArtifact",
)

解決策: 標準化された型変換のために ParameterImage を使用する：

# ✅ 標準化された型処理
ParameterImage(
    name="image",
    tooltip="入力画像",
    allow_output=False,
)

メリット:

  • ImageArtifact の代わりに ImageUrlArtifact を宣言し、パラメータ値を軽量に保つ — パラメータのペイロードサイズ を参照
  • ImageArtifact、ImageUrlArtifact、および文字列を一貫して処理
  • URL、ファイルパス、データ URI の組み込みサポート
  • さまざまな入力形式に対する適切なエラー処理
  • 複雑なワークフローでの型変換エラーを大幅に削減

モデル比較テーブル

複数のモデルを提供するサービスの場合は、常に比較テーブルを含めてください：

| モデル | 最大再生時間 | 品質 | 速度 | 文字数制限 |
| :--- | :--- | :--- | :--- | :--- |
| V5 | 4 分 | 最高 | 最速 | プロンプト: 5000, スタイル: 1000 |
| V4_5 | 8 分 | 高 | 高速 | プロンプト: 5000, スタイル: 1000 |
| V4 | 4 分 | 良好 | 中速 | プロンプト: 3000, スタイル: 200 |

標準ライブラリへのコントリビューション

独立したライブラリを作成するのではなく、コアの griptape_nodes_library にノードを追加する場合は、以下の手順に従ってください：

1. フィーチャーブランチの作成

cd griptape-nodes
git checkout -b feature/add-color-match-node

2. ノードファイルの追加

適切なカテゴリサブディレクトリにノードを配置します：

libraries/griptape_nodes_library/griptape_nodes_library/
├── image/
│   ├── color_match.py      # 新しいノードファイル
│   ├── load_image.py
│   └── save_image.py
├── text/
├── audio/
└── ...

3. griptape_nodes_library.json の更新

libraries/griptape_nodes_library/griptape_nodes_library.json に 3 つの変更を加えます：

a. ライブラリバージョンのインクリメント

{
  "metadata": {
    "library_version": "0.59.0" // 以前は 0.58.0
  }
}

b. 新しい pip 依存関係の追加

{
  "metadata": {
    "dependencies": {
      "pip_dependencies": [
        "existing-dep",
        "color-matcher" // 新しい依存関係
      ]
    }
  }
}

c. ノードエントリの追加

{
  "nodes": [
    {
      "class_name": "ColorMatch",
      "file_path": "griptape_nodes_library/image/color_match.py",
      "metadata": {
        "category": "image",
        "description": "参照画像から対象画像にカラー特性を転送します",
        "display_name": "Color Match",
        "icon": "palette",
        "group": "edit"
      }
    }
  ]
}

4. ドキュメントの追加

docs/nodes/<category>/<node_name>.md にドキュメントページを作成します：

# Color Match

参照画像から対象画像にカラー特性を転送します。

## 概要 (What It Does)

参照画像のカラーパレットを対象画像に適用します...

## パラメータ一覧 (Parameters)

### 入力 (Inputs)

| パラメータ | 型 | 説明 |
| :--- | :--- | :--- |
| reference_image | ImageUrlArtifact | カラーパレットの参照元画像 |
| target_image | ImageUrlArtifact | 色を適用する対象画像 |

### 出力 (Outputs)

| パラメータ | 型 | 説明 |
| :--- | :--- | :--- |
| output_image | ImageUrlArtifact | カラーマッチング結果 |

## 使用例 (Example Usage)

1. 目的の色を持つ参照画像を接続
2. 変換する対象画像を接続
3. ノードを実行

## 技術仕様 (Technical Details)

ヒストグラムマッチングを伴う color-matcher ライブラリを使用...

5. mkdocs.yml ナビゲーションの更新

mkdocs.yml のナビゲーションに作成したドキュメントページを追加します：

nav:
  - Nodes Reference:
      - Image:
          - Load Image: nodes/image/load_image.md
          - Save Image: nodes/image/save_image.md
          - Color Match: nodes/image/color_match.md # 新しいエントリ

6. 品質チェックの実行

コミットする前に、フォーマットと静的解析チェックを実行します：

make format        # コードの自動フォーマット
make check/lint    # リンティング問題のチェック
make check/types   # 型エラーのチェック

問題が発生した場合は修正してから先へ進んでください。

7. コミットと PR の作成

git add .
git commit -m "feat(image): add ColorMatch node for color transfer"
git push -u origin HEAD
gh pr create --title "Add ColorMatch node" --body "## Summary
- Adds ColorMatch node for transferring colors between images
- Uses color-matcher library
- Includes documentation

## Test plan
- [ ] Load two images
- [ ] Run color match
- [ ] Verify output has reference colors"

標準ライブラリ vs 外部ライブラリ

観点 標準ライブラリ 外部ライブラリ
配置場所 griptape-nodes リポジトリ内 独立した別リポジトリ
インストール デフォルトで同梱 ユーザーがインストール
レビュー PR 承認が必要 独自に公開可能
依存関係 コアの griptape_nodes_library.json に追加 独自の griptape_nodes_library.json
バージョニング コアライブラリのバージョンに追従 独立したバージョニング
ドキュメント メインドキュメントサイトに追加 ライブラリ内の README

標準ライブラリにコントリビュートすべき場合:

  • 多くのユーザーにとって汎用的な有用性があるノード
  • プロプライエタリや有料 API への依存関係がない
  • 安定し、十分にテストされた実装
  • すべてのコード品質基準に準拠している

外部ライブラリを作成すべき場合:

  • ニッチな特定のユースケース
  • 有料 API キーを必要とする
  • 実験的、または急速に変更される可能性がある
  • 独自の独立したリリースサイクルを持ちたい