# `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`: セッション永続化データ

## 基本的な使用方法

```rust
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,
        _ => {}
    }
}
```

### ツール登録と実行

```rust
// 個別ツール登録
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?;
```

### フックシステム

```rust
// カスタムフック実装例
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サーバーの並列初期化による高速化