# llm_worker_rs

LLMを用いたワーカーを作成する小型のSDK・ライブラリ。

ツールの定義や呼び出し、コンテキストの管理などを責務にもつ。

## 用語定義

- **ブロック (Block)**:
  モデルが「開始→デルタ→終了」で囲む一塊の出力。OpenAIの`response.output_item`やAnthropicの`content_block`、Geminiの`candidates[].content.parts`などが該当する。
- **メタイベント (Meta Event)**:
  `ping`や`usage`など、ブロックに属さない補助イベント群。ステータス更新やハートビートとして処理される。

以降の仕様では「ブロック」を上記の生成・ツール単位の総称として扱う。

## アプローチ

module構成概念図

```
worker
├── context
├── llm_client
│   ├── scheme
│   │   └── openai, anthropic, gemini // APIスキーマ
│   ├── events
│   ├── providers
│   │   └── anthropic, googleai, ollama, etc... // プロバイダ
│   └── timeline
```

OpenAI互換のプロバイダでスキーマを使い回せるよう、schemeとプロバイダモジュールは分離されている

### scheme層

単純な変換を責務とするスキーマを定義する。

- リクエスト変換: SystemPrompt + Context + Tools... → プロバイダ固有のリクエストJSON
- レスポンス変換: Raw stream → 型付きイベント構造体のストリーム

各APIスキーマ(≠プロバイダ)ごとに実装を持ち、APIスキーマに準じたパース/バリデーションを行う。

### llm_client(providers)層

providersにリクエストを送信し、差異が吸収され統一された`Event`ストリームを出力する。

ストリーミング中のバッファリング（ToolArgumentsの累積等）もこの層で行う。

### timeline層

イベントストリームの状態を管理する。レスポンスをステートマシンで制約し、イベントをハンドラーに渡す。

このTimelineに基づき、Workerはツール実行・フックを行う。

イベントストリームを扱う目標に、Text/Input JSON/Thinkingのdeltaと、[細粒度ツールストリーミング](https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)を含む、deltaの低遅延・リアルタイム処理がある。
主要なドキュメント:[https://platform.claude.com/docs/en/build-with-claude/streaming#content-block-delta-types]

TODO: Workerをユーザーが扱うUIとした際の、Timelineの露出のさせ方

## Tools/Hooks

各種プロバイダのLLMのAPI仕様として存在するTool Callや、Function CallingをToolsとして統一的に扱ってる。また、Claude Codeに存在するようなHooksと同じような機能を搭載する。

これらはtraitとして表現され、クロージャを持ち、イベントのストリーム中に自動的に呼び出される。

Tools/Hooksを定義する為のProcedural macroを提供する。

TODO: Tool定義と合わせたTimeline Handlerの定義方法(特定のツールとセットになったHandlerの考慮)