Bash4LLM+ の概要: LLM API 用の軽量 Bash ラッパー

Bash4LLM+ の概要: LLM API 用の軽量 Bash ラッパー

Bash4LLM+ は、Groq の OpenAI 互換 API やその他の LLM プロバイダーと連携するために設計された、依存関係のない軽量 Bash ラッパーです。単一の監査可能な Bash スクリプトで、Unix 系環境全体でのセキュリティとポータビリティを優先しながら、コマンドラインから直接大規模言語モデルと対話できます。

コア機能とアーキテクチャ

Bash4LLM+ は、標準的な Unix ユーティリティ（bash、coreutils、findutils、util-linux、gawk、curl、jq）のみを必要とする自己完結型スクリプトとして動作します。Linux、macOS、WSL、Cygwin、BSD、Android の Termux など、さまざまな環境でポータブルかつ互換性があります。

設計上のセキュリティ

このツールは、単一ユーザー環境で安全に使用できるよう、以下のセキュリティ対策を実装しています:

  • eval や /tmp を使用しない: eval の使用を回避し、共用システム /tmp ディレクトリを使用しないことで、一般的なシェル脆弱性を防止します。
  • 分離された一時ファイル: 一時ファイルはユーザー定義の $RUN_TMPDIR に格納され、制限付き権限 (umask 077) が設定されます。
  • 出力の安全性: スクリプトは LLM から受け取った出力を決して実行しません。
  • 権限管理: ファイルはプライバシーを確保するために 600 権限で保存されます。

UI 状態システム (ui_state)

Bash4LLM+ の特徴的な機能の一つが ui_state システムです。コアスクリプトは、操作メタデータを $BASH4LLM_CONFIG_DIR/ui_state 内の個別 JSON ファイルとして公開します。これにより、外部 GUI やツール（例: Home Assistant）が生ログを解析することなく CLI と統合できます。システムが追跡する情報は以下の通りです:

  • セッション状態: アクティブなセッション、メッセージ数、タイムスタンプ。
  • API 結果: HTTP ステータス、リクエスト ID、検出されたエッジケース。
  • プロバイダー機能: アクティブなプロバイダーがストリーミングやモデルリフレッシュをサポートしているか。

セッション管理とコンテキストメモリ

Bash4LLM+ はデフォルトではメモリを保持しません。コンテキストメモリは、ユーザーが --session <id> フラグで明示的にセッションを起動したときのみ有効になります。

永続履歴

セッションがアクティブな場合、ツールは $BASH4LLM_HISTORY_DIR/sessions/<session_id>.ndjson に永続的な NDJSON ファイルを作成します。このファイルは会話履歴を保存し、API に送信してコンテキストを維持します。ユーザーは --session-window [n] フラグで送信するコンテキスト量を制御でき、デフォルトは 10 メッセージです。

操作方法とコマンドインターフェース

基本的な対話

ユーザーは以下の方法でプロンプトを送信できます:

  • 直接プロンプト: ./bash4llm "prompt text"
  • パイプ入力: echo "prompt" | ./bash4llm
  • ファイル入力: ./bash4llm -f prompt.txt
  • 複数行入力: ヒアドキュメント (<<'EOF') を使用。

モデルとプロバイダーの管理

Bash4LLM+ はハードコードされたモデルを避け、プロバイダーの API（例: GET https://api.groq.com/openai/v1/models）から利用可能なモデル一覧を動的に取得します。

  • --refresh-models: ローカルのモデルホワイトリストを更新。
  • -m <model>: 単一実行時にモデルを指定。
  • --set-default <model>: アクティブプロバイダーの永続的なデフォルトモデルを設定。
  • --provider <name>: LLM プロバイダーを切り替え（--install-extras コマンドで Gemini、Hugging Face、Mistral などの追加プロバイダーをインストール可能）。

出力オプション

ユーザーは応答の受け取り方をカスタマイズできます:

  • ストリーミング: --stream フラグでリアルタイム非同期出力を有効化。
  • JSON 出力: --json または --pretty フラグで API からの生 JSON または整形済み JSON を返す。
  • 自動保存: スクリプトは設定可能なバイト閾値（デフォルト 1000 バイト）を超える出力を自動的に保存します。

技術要件とインストール

Bash4LLM+ を実行するには、bash、coreutils、findutils、util-linux、gawk、curl、jq が PATH にインストールされている必要があります。

インストールはリポジトリをクローンし、bin/bash4llm スクリプトに実行権限を付与し、必要な API キーをエクスポート（例: export GROQ_API_KEY="your_key"）するだけです。./bash4llm --install-extras コマンドで追加プロバイダーやテンプレートなどのオプション機能もインストールできます。

Sources