llm_worker_rs/docs/plan/worker_api_plan.md

Worker API/DSL 実装計画

目的

• Open Responses(以後"OR")に準拠した正規化を前提に、 Item/Part の2段スコープを扱える Worker API を設計する。
• APIの煩雑化を防ぐため、worker.on_xxx として公開するのを避けつつ、 Text/Thinking/Tool など型の違いを静的に扱える DSL を提供する。

方針

• 内部は Timeline が Event を正規化し、Item/Part/Meta を単一ストリームとして扱う。
• API では Item/Part 型ごとに ctx を持てるようにし、DSL で記述の冗長さを削減する。
• まず macro_rules! 版を作り、必要なら proc-macro に拡張する。
• Item/Part の型パラメータはクレートが公開する Kind 型を使う。

仕様の前提

• Item は OR の item (message, function_call, reasoning など) に対応する。
• Part は OR の content part (output_text, reasoning_text など) に対応する。
• Item は必ず start/stop を持つ。Part は Item 内で複数発生し得る。
• Item/Part の型指定は Item<Message> / Part<ReasoningText> のように書く。

設計ステップ

1. 内部イベントモデルの整理

• Event を Item/Part/Meta の3層に整理する。
• ItemEvent / PartEvent は型パラメータで区別する。
• 例: ItemEvent, PartEvent<Message, OutputText>

2. スコープの二段化

• Item ctx: Item 型ごとに1つ
• Part ctx: Part 型ごとに1つ
• Part のイベントでは常に item ctx と part ctx の両方を渡す。

3. Handler trait の再定義

• Item/Part を型で指定できる trait を導入する。
• 例:
  • trait ItemHandler
  • trait PartHandler<I, P>
• PartHandler には ItemHandler の ItemCtx を必須で渡す。
• Part の ctx 型は PartKind::Ctx 方式 or enum 方式で切り替える。

4. Timeline との結合

• Timeline は ItemStart で ItemCtx を生成
• PartStart で PartCtx を生成
• Delta/Stop は対応 ctx に流す
• ItemStop で ItemCtx を破棄

5. DSL (macro_rules!) の導入

• まず宣言的 DSL を提供する。
• 例:
  • handler! { Item { type ItemCtx = ...; Part { type PartCtx = ...; } } }
• DSL は ItemHandler / PartHandler 実装を生成する。
• Item/Part の Kind 型はクレートが公開する型を参照する。

6. 拡張ポイント

• 追加 Part (output_image など) を DSL に追加しやすい形にする。
• 必要なら proc-macro に移行して構文自由度を上げる。

実装順序

1. Event/Item/Part の型定義の整理
2. Item/Part ctx を持つ Timeline 実装
3. Handler trait の定義・既存コードの移行
4. macro_rules! DSL の実装
5. 既存ユースケースの移植

TODO

• Item と Part の型対応表を整理する
• OR と既存 llm_client の差分を再確認する
• Tool args の delta を OR 拡張として扱うか検討する
• macro_rules! で表現可能な DSL の最小文法を確定する