llm-worker-rs/docs/worker.md

worker ライブラリ

workerは、LLM（大規模言語モデル）との対話を抽象化し、複数のLLMプロバイダを統一的に扱うための共通ライブラリです。動的ツール登録システム、フックシステム、MCPプロトコル統合を提供します。

アーキテクチャ

Core Crate Patternを採用：worker-types（基本型）→ worker-macros（マクロ）→ worker（メインライブラリ）

循環依存を解消し、型安全性と保守性を向上させています。

概要

LLMプロバイダ（Gemini, Claude, OpenAI, Ollama, XAI）を統一インターフェースで利用できます。Worker構造体が中心となり、プロンプト管理、ツール登録、フックシステム、MCPサーバー統合を提供します。

主要なコンポーネント

Worker

LLMとの対話における中心的な構造体です。

• LLMクライアントの保持: LlmClient enumを通じて複数プロバイダの統一インターフェースを提供
• プロンプト管理: PromptComposerによるテンプレートベースのプロンプト組み立て
• ストリーミング処理: リアルタイムイベントストリーム（process_task_stream）とメッセージ履歴管理（process_task_with_history）
• 動的ツール管理: 実行時ツール登録・実行、MCPサーバー統合
• フックシステム: メッセージ送信、ツール利用、ターン完了時の拡張ポイント
• セッション管理: メッセージ履歴の保存・復元機能

Tool トレイト

動的ツール登録の基盤。worker-typesで定義され、#[tool]マクロで自動実装可能です。

StreamEvent

LLMストリーミング応答のイベント型。テキストチャンク、ツール呼び出し、ツール結果、完了通知、デバッグ情報、フックメッセージをサポートします。

LlmClient Enum

各LLMプロバイダクライアントの統合enum。LlmClientTraitを実装し、統一されたストリーミング対話と接続確認機能を提供します。

フックシステム

• WorkerHook トレイト: カスタムフック実装の基盤
• HookManager: フック登録・実行管理
• HookEvent: OnMessageSend、PreToolUse、PostToolUse、OnTurnCompleted
• HookContext: フック実行時のコンテキスト情報

その他の主要型

• Message: LLM対話のメッセージ（role + content + tool_calls）
• LlmDebug: デバッグログ制御と詳細出力
• ModelInfo: モデル情報とサポート機能
• SessionData: セッション永続化データ

基本的な使用方法

use worker::{Worker, LlmProvider, types::{Message, Role, StreamEvent}};
use futures_util::StreamExt;

// Worker初期化
let mut worker = Worker::new(
    LlmProvider::Gemini, 
    "gemini-1.5-flash", 
    &api_keys, 
    None
)?;

// ツール登録（オプション）
worker.register_tool(Box::new(some_tool))?;

// メッセージ送信とストリーム処理（履歴あり）
let mut stream = worker.process_task_with_history(
    "Hello, how are you?".to_string(), 
    None
).await;

while let Some(Ok(event)) = stream.next().await {
    match event {
        StreamEvent::Chunk(text) => print!("{}", text),
        StreamEvent::ToolCall(call) => println!("Tool: {}", call.name),
        StreamEvent::ToolResult { tool_name, result } => {
            println!("Result from {}: {:?}", tool_name, result);
        },
        StreamEvent::Completion(_) => break,
        _ => {}
    }
}

ツール登録と実行

// 個別ツール登録
worker.register_tool(Box::new(ReadFileTool::new()))?;

// MCPサーバーからのツール登録
let mcp_config = McpServerConfig {
    name: "filesystem".to_string(),
    command: "npx".to_string(),
    args: vec!["-y".to_string(), "@modelcontextprotocol/server-filesystem".to_string()],
    env: HashMap::new(),
};
worker.register_mcp_tools(mcp_config).await?;

// 複数MCPサーバーの並列初期化
worker.queue_mcp_server(config1);
worker.queue_mcp_server(config2);
worker.init_mcp_servers().await?;

// ツール実行
let result = worker.execute_tool("read_file", json!({"path": "./file.txt"})).await?;

フックシステム

// カスタムフック実装例
struct MyHook;

#[async_trait::async_trait]
impl WorkerHook for MyHook {
    fn name(&self) -> &str { "my_hook" }
    fn hook_type(&self) -> &str { "OnMessageSend" }
    fn matcher(&self) -> &str { "" }
    
    async fn execute(&self, mut context: HookContext) -> (HookContext, HookResult) {
        // メッセージ前処理
        let new_content = format!("[処理済み] {}", context.content);
        context.set_content(new_content);
        (context, HookResult::Continue)
    }
}

// フック登録
worker.register_hook(Box::new(MyHook));

主要API

• register_tool(): ツール登録
• register_mcp_tools(): MCPサーバーからのツール登録
• register_hook(): フック登録
• get_tools(): 登録済みツール一覧
• execute_tool(): ツール実行
• process_task_stream(): LLMストリーミング対話（履歴なし）
• process_task_with_history(): メッセージ履歴付きストリーミング対話
• get_session_data(): セッションデータ取得
• load_session(): セッション復元

型システム

Core Crate Patternにより型を分離：

• worker-types: 基本型（Tool, Message, StreamEvent等）
• worker: 実装とエラー型（WorkerError等）

後方互換性のためworker::types::経由で全型にアクセス可能。

主要型

• ToolResult<T>: ツール実行結果
• DynamicToolDefinition: ツール定義情報
• WorkerError: ライブラリ固有エラー型

LLMプロバイダサポート

全プロバイダでストリーミング対話、ツール呼び出し、モデル一覧取得、接続確認を完全実装：

• Gemini (Google)
• Claude (Anthropic)
• OpenAI
• Ollama
• XAI (Grok)

主要機能

• Core Crate Pattern: 循環依存解消による保守性向上
• 動的ツール登録: 実行時ツール追加・実行
• #[tool]マクロ: 関数からツール自動生成
• フックシステム: メッセージ送信・ツール利用・ターン完了時の拡張ポイント
• ストリーミング対話: リアルタイムLLM応答とイベント処理
• 複数プロバイダ: 統一インターフェースでの5つのLLMプロバイダサポート
• MCP統合: Model Context Protocolサーバーとの動的連携
• セッション管理: メッセージ履歴の永続化・復元
• ワークスペース検出: Git情報を含む作業環境の自動認識
• 型安全性: 強い型チェックとエラーハンドリング
• 並列処理: MCPサーバーの並列初期化による高速化