ライブラリ (Libraries)

ライブラリ (Library) は、エディタ内で使用できるノードのパッケージ（まとまり）です。エンジンに同梱されているもの、Git URL からインストールするもの、自身で作成するものなどがあります。このページは、ライブラリをインストールして利用するクリエイターやアーティスト向けに書かれています（ライブラリ開発者向けの情報は、カスタムノード開発ガイドおよび Worker によるノード分離を参照してください）。

複数ライブラリ間の競合が心配な場合は、共存保証セクションをご確認ください。要約すると、2 つのライブラリの Python 依存関係が互いを壊すことは絶対にありませんが、同じノード名を持つ 2 つのライブラリが存在する場合は名前の曖昧さが発生する可能性があり、その際はエンジンが通知します。

初期状態で用意されているもの

エンジンは Sandbox Library（サンドボックスライブラリ）をサポートしています。これは、完全なライブラリを作成することなく、独自のカスタムノードを素早く開発・試作するためのスクラッチパッド用ライブラリです。初期状態ではセットアップされていないため、Settings → Library → Sandbox Settings で Sandbox Library Directory をディスク上の実在するフォルダに指定してください。指定すると、エンジンはそのディレクトリから .py ノードファイルを自動的に検出し、エディタの Sandbox カテゴリに表示されます。

gtn init の実行時には、Advanced Media Library（拡散モデル、画像生成、動画処理）の登録オプションが提示されます。その時点で登録することも、後から gtn init を再実行して追加することも可能です。手順については FAQ を参照してください。

その他の公式ライブラリやコミュニティライブラリは、エディタを通じて自身でインストールします。

エディタでのライブラリのインストール

エディタの Libraries パネルがメインのインストール画面です。ヘッダーの Manage メニュー → Library Management から開きます。

右上の Add Library をクリックして Add Library モーダルを開きます。Git URL（コミュニティライブラリをホストしている GitHub リポジトリなど）を貼り付け、Install をクリックします。エディタがリポジトリをクローンし、ライブラリの griptape_nodes_library.json マニフェストを読み取り、依存関係をインストールして登録します。モーダル内の Advanced Options を使用すると、デフォルトブランチの代わりに特定のブランチ、タグ、またはコミットハッシュを指定できます。

何をインストールすればよいかわからない場合は、モーダル下部にある Browse Community Libraries ボタンをクリックすると、厳選されたインストール可能なライブラリ一覧が開きます。

インストールが正常に完了すると、新しいライブラリがパネルのリストに表示されます。各エントリには以下が表示されます：

ライブラリ名とバージョン。
含まれているノードの総数。
ファイルマネージャーでライブラリのディレクトリを開く Open アクション。
ライブラリの Git リモート、リファレンス（ブランチまたはタグ）、および現在のコミットハッシュを表示する Advanced 展開メニュー。バグ報告を行う際は、ここに表示されているコミットハッシュが正確なバージョン情報となります。

リスト上部のチップを使用して、All（すべて）、Updates（更新あり）、または Errors（エラー）で絞り込むことができます。ライブラリに問題が発生した場合は、まず Errors を確認してください。インストールの失敗、依存関係のインストール失敗、読み込み時のエラーが集約されて表示されます。

ライブラリの更新 (Updating libraries)

Libraries パネル内のフィルターチップの隣にあるアイコンボタンから、以下の操作が可能です：

Check for updates — インストール済みのすべてのライブラリをスキャンして新しいバージョンを検索します。更新が利用可能なものはすべて Updates フィルターに表示されます。
Refresh — ライブラリリストを再読み込みします（新しくインストールしたものが正常に認識されたか確認するのに便利です）。

バックグラウンドでの定期的な更新チェックについては、Configuration Editor → Libraries でエンジンの自動チェック頻度を設定できます。

Update Notifications（更新通知）オプション：

Enable sidebar notifications — 更新が利用可能な場合、Libraries タブにバッジを表示し、各ライブラリに行ボタンを表示します。
Notification color / animation — バッジの視覚スタイルやアニメーション。
Check on startup — エンジン起動ごとに更新をスキャンします。
Check periodically — 定期的な実行スケジュール（しない、毎時など）。
Check Now — 今すぐ手動スキャンを実行します。

これらを特別に変更する必要はなく、ほとんどのユーザーにとってデフォルト設定のままで問題ありません。

ライブラリの無効化と削除 (Toggling and removing libraries)

Configuration Editor → Libraries 画面には、Library Registration → Libraries To Register も表示されます。このリストの各エントリは、エンジンが起動時に読み込むライブラリです。各エントリには 3 つのコントロールがあります：

左側のトグルスイッチ — オフにすると、ディスク上にファイルを保持したまま、エンジン起動時の読み込みのみを停止します。
中央の Shared / Isolated ドロップダウン — ライブラリを実行するプロセス空間を選択します（詳細は後述）。
右側のゴミ箱アイコン — リストからエントリを完全に削除します。ディスク上のクローンは残るため、ディスク容量を解放したい場合は手動でフォルダを削除してください。

Shared/Isolated library mode

Shared vs. Isolated

このドロップダウンでは、ライブラリが実行されるプロセスを選択します：

Shared（共有） — ライブラリはメインのエンジンプロセス内部で、他の共有ライブラリと一緒に実行されます。
Isolated（分離） — ライブラリは独自の独立した専用プロセス内で実行されます。Python の依存関係が他のすべてのライブラリから完全に隔離され、万が一そのライブラリがクラッシュしてもエンジン全体が巻き込まれて停止することはありません。

ドロップダウンには、エンジンが実際に適用するモードが表示されます：ここで明示的に上書きしない限り、ライブラリ作者が推奨するモードが適用されます。隔離したい重量級のライブラリには Isolated を選択し、同一プロセス内で軽量に動かしたい場合は Shared を選択します。一部のライブラリは作者によって分離実行と互換性がないとマークされており、その場合はドロップダウンが Shared にロック されます。

このドロップダウンは、エンジンバージョンがサポートしている場合（0.86.0 以降）にのみ表示されます。変更は次回のライブラリ更新（リフレッシュ）時に有効になります。

下部にある Add Library ボタンを使用すると、ディスク上にすでにある griptape_nodes_library.json（手動でクローンしたライブラリやローカルで開発中のライブラリ）をエンジンに登録できます。

共存保証 (Coexistence guarantees)

複数のライブラリを並行してインストールできる本質的な利点は、それらが互いに干渉して壊れることがないという点です。これを保証するために 3 つのレイヤーが機能しています：

Python 依存関係の完全分離

登録されたすべてのライブラリには、それぞれ専用の 仮想環境 (virtual environment) が割り当てられます。エンジンのシステムパッケージや他のライブラリとは一切状態を共有しない、完全に独立した Python パッケージ環境です。ライブラリ A が torch==2.4.1 を固定し、ライブラリ B が torch==2.0.0 を固定していても問題ありません。両者は別々の .venv ディレクトリにインストールされ、各ライブラリのノードが実行される際にそれぞれの環境が使用されます。

これはライブラリが Shared であっても Isolated であっても同様に成り立ちます（プロセス分離を参照）。いずれの場合も .venv はディスク上のライブラリマニフェストの隣に配置されます。違いは、それらのパッケージをどのプロセスがロードするかという点だけです（Shared の場合はメインエンジンプロセス、Isolated の場合はそのライブラリ専用のプロセス）。クリエイターの視点からは、依存関係の分離レベルは全く同じです。

バージョンの競合するライブラリ同士を同時にインストールしても、pip の依存関係解決エラーが発生することはありません。 これが本ページにおける最も重要な保証です。

編集時依存関係と実行時依存関係

ライブラリは、マニフェスト内で依存関係を 2 つのグループに分割して定義できます：

pip_dependencies — 編集時 (edit-time): エディタ内にノードを表示し、キャンバスに配置し、パラメータを編集するために最低限必要な依存関係。このグループは軽量に保たれます。
pip_dependencies_exec — 実行時 (execution): ノードが実際に実行される際にのみ必要となる重量級のパッケージ群（torch、diffusers など）。

実行時依存関係は独立した専用環境（ライブラリの .venv の隣にある .venv-exec）にインストールされ、ノードが実際に処理を実行するプロセス内でのみロードされます（メインエンジンプロセスにロードされることは絶対にありません）。これにより、エディタを軽量に保ったまま数ギガバイトに及ぶ機械学習スタックに依存するライブラリを導入でき、重い依存関係が衝突する 2 つのライブラリであっても同じキャンバス上で並行して編集できます。

マニフェストで pip_dependencies_exec を宣言しない場合でも常に安全です。すべての依存関係が編集時として扱われ、単一環境のライブラリとしてインストール・実行されます。

実行時依存関係を宣言した場合の挙動変化

実行時依存関係を明示的に宣言したライブラリは、以下の 3 つの点で動作が異なります：

ノードはライブラリ自身の専用プロセスで実行される。 メインエンジンはノードの表示、編集、保存を行えますが（編集時依存関係を保持しているため）、実際の実行は重量級パッケージが存在するプロセス内で行われます。そのプロセスがまだ起動していない場合、ノードの実行は予期せぬクラッシュではなく、その旨を正しくレポートします。
ノードコードは状態を直接読み取るのではなくエンジンに要求する。 process() 内部で設定、シークレット、ファイルなどのマネージャーに直接アクセスしようとするとエラーが発生し、代わりに使用すべきリクエストメソッドが案内されます。ライブラリのプロセス自身は設定やシークレットを直接保持していないため、直接読み取ろうとすると誤った場所から応答してしまうためです。静的ファイルの保存は通常通り機能します。
プロセス境界を越えられない値はプロセス内に留める必要がある。 ノードが serializable=False とマークされた値（生モデルのハンドル、テンソルなど）を出力しようとするとエラーが発生し、2 つの対処法が提示されます：値をシリアライズ可能にするか、ライブラリ側でキャッシュして小さなディスクリプタを出力し、次のノードでそれを受け渡すようにします。

プロセス分離: Isolated モード

ライブラリを Isolated（エンジンのメインプロセス内ではなく、専用の独立プロセス内）で実行すると、以下のメリットが得られます：

フォールトトレランス（耐障害性）: 万が一ライブラリがクラッシュしても、そのライブラリのプロセスのみが終了し、エンジンの残りの部分や他のライブラリは中断されることなく動き続けます。
リソースの完全分離: ライブラリがメモリに読み込むすべてのリソース（モデルの重み、GPU メモリ、バックグラウンドスレッド）はライブラリ自身のプロセス内に閉じ込められ、他のライブラリの動作を圧迫することがありません。

重量級の機械学習ライブラリ（拡散モデル、Transformers、カスタム CUDA スタックなど）で最大の効果を発揮します。軽量なライブラリ（単純な HTTP 処理やデータ変換ノードなど）は、通常 Shared のままで快適に動作します。ライブラリの無効化と削除で説明した Shared / Isolated ドロップダウンを使用して、ライブラリごとにこれを柔軟に切り替えることができます。

ライブラリ作者はマニフェスト（griptape_nodes_library.json）内で分離の互換性と推奨モードを宣言します（worker_mode_compatibility および suggested_worker_mode）。スキーマの詳細は Worker によるノード分離を参照してください。ユーザーとしては、エディタ上のドロップダウンを操作するだけで十分です。

ノード名が重複した場合の挙動（未解決の課題）

2 つのライブラリが同じ名前のノードクラスを登録した場合（例えば両方が MyImageNode を提供している場合）、エンジンは両方を受け入れます。インストール時にエンジンが警告を出すことはありません。 そのノードをキャンバスに作成する際：

ワークフローがライブラリ名を明示的に指定している場合は正常に動作します。
指定していない場合、エンジンはエラーを発生させ、曖昧さを解消できるように両方のライブラリ名を提示します。

これはエンジンが自動解決しない唯一の競合要因です。名前の衝突が疑われる場合、最も確実な対処法は、使用しない方のライブラリを Libraries To Register リストから削除することです。

トラブルシューティング

「ライブラリをインストールしたのにノードが表示されない」

Libraries パネルを開き、フィルターを Errors に切り替えてください。インストールの失敗、依存関係のインストール失敗、読み込みエラーが発生したすべてのライブラリがここに集約されます。該当するライブラリをクリックすると、具体的なエラーメッセージを確認できます。

主な原因：

ライブラリが、お使いの Python バージョンや OS プラットフォームに対応する wheel（ビルド済み Python パッケージ）が存在しないパッケージを指定している場合（例: サポートされていない CUDA バージョン向けの torch wheel など）。
ネットワークによってインストールがブロックされた場合（企業プロキシ、またはインストール処理中のオフライン状態）。
ディスク容量不足（エンジンが明示的にエラーを通知します）。

根本的な原因を解決した後、インストールを再実行してください（Add Library モーダルで URL を再入力するか、後述の CLI で --overwrite を使用します）。

「エディタ上でノードが壊れているように見える、または赤く表示される」

エンジンがそのノードを構築できなかったことを意味します — 通常はそのノードが属するライブラリのロードに失敗したことが原因です。ワークフローファイルが破損するのを防ぐため、エディタはプレースホルダーノードに自動的に置き換えます。Libraries パネルの Errors フィルターで根本的なロードエラーを確認してください。問題を修正した後にワークフローを再度開くと、本来のノードに戻ります。

生のエラーログテキストを確認したい場合

エンジンが実行されているターミナルウィンドウ（エンジンを起動したシェル）に、スタックトレースを含む詳細なエラーログが出力されています。Isolated モードで実行されているライブラリからのエラーは、Worker-<id> プレフィックス付きで表示されます。

CLI での代替操作

自動化、ヘッドレスエンジンでの運用、または好みに応じてコマンドラインを使用したい場合、エディタのライブラリ操作には対応する gtn コマンドが用意されています：

エディタの操作	CLI での対応コマンド
Add Library → Install	`gtn libraries download <git_url>`
Check for updates → 保留中の更新をインストール	`gtn libraries sync`
ローカルの変更を上書きして同期	`gtn libraries sync --overwrite`
Advanced Media Library を再登録	`gtn init` を実行し、`y` と回答

コマンドの完全なリファレンスについては、コマンドラインインターフェースを参照してください。

ライブラリのディスク上の保存場所

設定ファイル: ~/.config/griptape_nodes/griptape_nodes_config.json（または各 OS の対応パス — エンジン設定を参照）。内部の app_events.on_app_initialization_complete.libraries_to_register リストが、エディタの Libraries To Register リストと同期しています。
クローン / venv: エディタがライブラリをクローンしたディレクトリ内に保存されます。ライブラリの .venv は griptape_nodes_library.json の隣に作成されます。
サンドボックスライブラリ: サンドボックスディレクトリは設定で個別に指定します。デフォルトの場所はプラットフォームによって異なります。

特定のライブラリバージョンにプロジェクトを固定する方法（プロジェクトをアクティブにした際に、自動的に一致するライブラリをプロビジョニングし、必要に応じて上書きする方法）については、エンジンおよびライブラリバージョンの固定を参照してください。

ライブラリ開発者向けの情報は、カスタムノードおよび Worker によるノード分離を参照してください。