@modular-prompt/driver 0.16.0 → 0.17.0

package/dist/runtime/pytorch-template-core.mjs

@@ -0,0 +1,54 @@
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+
+const PRESERVED_RUNTIME_FILES = new Set(['pyproject.toml', 'uv.lock']);
+
+function copyTemplateContents(templateDir, runtimePythonDir) {
+  mkdirSync(runtimePythonDir, { recursive: true });
+  for (const entry of readdirSync(templateDir)) {
+    if (PRESERVED_RUNTIME_FILES.has(entry)) {
+      continue;
+    }
+    cpSync(join(templateDir, entry), join(runtimePythonDir, entry), {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+
+function assertTemplateExists(templateDir) {
+  if (!existsSync(templateDir)) {
+    throw new Error(`PyTorch template not found: ${templateDir}`);
+  }
+}
+
+/**
+ * 初回 setup 用に template 一式を runtime へ seed する。
+ * 既存 runtime の pyproject.toml / uv.lock はユーザー管理として保持する。
+ */
+export function seedPytorchTemplate(templateDir, runtimePythonDir) {
+  assertTemplateExists(templateDir);
+  if (!existsSync(runtimePythonDir)) {
+    mkdirSync(dirname(runtimePythonDir), { recursive: true });
+    cpSync(templateDir, runtimePythonDir, { recursive: true });
+    return;
+  }
+
+  copyTemplateContents(templateDir, runtimePythonDir);
+  for (const file of PRESERVED_RUNTIME_FILES) {
+    const templateFile = join(templateDir, file);
+    const runtimeFile = join(runtimePythonDir, file);
+    if (!existsSync(runtimeFile) && existsSync(templateFile)) {
+      cpSync(templateFile, runtimeFile, { force: true });
+    }
+  }
+}
+
+/**
+ * 既存 runtime のコードを template から同期する。
+ * pyproject.toml と uv.lock は上書きしない。
+ */
+export function syncPytorchTemplate(templateDir, runtimePythonDir) {
+  assertTemplateExists(templateDir);
+  copyTemplateContents(templateDir, runtimePythonDir);
+}

package/dist/runtime/pytorch-template-core.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pytorch-template-core.mjs","sourceRoot":"","sources":["../../src/runtime/pytorch-template-core.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAErC,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,CAAC;AAEvE,SAAS,oBAAoB,CAAC,WAAW,EAAE,gBAAgB;IACzD,SAAS,CAAC,gBAAgB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7C,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,EAAE;YAC9D,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,WAAW;IACvC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAW,EAAE,gBAAgB;IAC/D,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAClC,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,CAAC,WAAW,EAAE,gBAAgB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,OAAO;IACT,CAAC;IAED,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACpD,KAAK,MAAM,IAAI,IAAI,uBAAuB,EAAE,CAAC;QAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACzD,MAAM,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAW,EAAE,gBAAgB;IAC/D,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAClC,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;AACtD,CAAC"}

package/dist/runtime/setup-commands-core.d.mts

@@ -10,4 +10,7 @@ export const SETUP_PYTORCH_MONOREPO: "pnpm run setup-pytorch";
 /** @modular-prompt/driver を npm インストールした環境向け */
 export const SETUP_MLX_CLI: "modular-prompt-runtime setup mlx";
 export const SETUP_PYTORCH_CLI: "modular-prompt-runtime setup pytorch";
+/** PyTorch runtime のコード・依存を再同期するコマンド */
+export const SYNC_PYTORCH_MONOREPO: "pnpm run sync-pytorch";
+export const SYNC_PYTORCH_CLI: "modular-prompt-runtime sync pytorch";
 //# sourceMappingURL=setup-commands-core.d.mts.map

package/dist/runtime/setup-commands-core.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-commands-core.d.mts","sourceRoot":"","sources":["../../src/runtime/setup-commands-core.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kEAAkE;AAClE,iCAAkC,oBAAoB,CAAC;AACvD,qCAAsC,wBAAwB,CAAC;AAE/D,gDAAgD;AAChD,4BAA6B,kCAAkC,CAAC;AAChE,gCAAiC,sCAAsC,CAAC"}
+{"version":3,"file":"setup-commands-core.d.mts","sourceRoot":"","sources":["../../src/runtime/setup-commands-core.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kEAAkE;AAClE,iCAAkC,oBAAoB,CAAC;AACvD,qCAAsC,wBAAwB,CAAC;AAE/D,gDAAgD;AAChD,4BAA6B,kCAAkC,CAAC;AAChE,gCAAiC,sCAAsC,CAAC;AAExE,wCAAwC;AACxC,oCAAqC,uBAAuB,CAAC;AAC7D,+BAAgC,qCAAqC,CAAC"}

package/dist/runtime/setup-commands-core.mjs

@@ -12,3 +12,7 @@ export const SETUP_PYTORCH_MONOREPO = 'pnpm run setup-pytorch';
 /** @modular-prompt/driver を npm インストールした環境向け */
 export const SETUP_MLX_CLI = 'modular-prompt-runtime setup mlx';
 export const SETUP_PYTORCH_CLI = 'modular-prompt-runtime setup pytorch';
+
+/** PyTorch runtime のコード・依存を再同期するコマンド */
+export const SYNC_PYTORCH_MONOREPO = 'pnpm run sync-pytorch';
+export const SYNC_PYTORCH_CLI = 'modular-prompt-runtime sync pytorch';

package/dist/runtime/setup-commands-core.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"setup-commands-core.mjs","sourceRoot":"","sources":["../../src/runtime/setup-commands-core.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AACvD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG,sCAAsC,CAAC"}
+{"version":3,"file":"setup-commands-core.mjs","sourceRoot":"","sources":["../../src/runtime/setup-commands-core.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AACvD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG,sCAAsC,CAAC;AAExE,wCAAwC;AACxC,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,qCAAqC,CAAC"}

package/dist/runtime/setup-commands.d.ts

@@ -1,2 +1,2 @@
-export { SETUP_MLX_MONOREPO, SETUP_PYTORCH_MONOREPO, SETUP_MLX_CLI, SETUP_PYTORCH_CLI, } from './setup-commands-core.mjs';
+export { SETUP_MLX_MONOREPO, SETUP_PYTORCH_MONOREPO, SETUP_MLX_CLI, SETUP_PYTORCH_CLI, SYNC_PYTORCH_MONOREPO, SYNC_PYTORCH_CLI, } from './setup-commands-core.mjs';
 //# sourceMappingURL=setup-commands.d.ts.map

package/dist/runtime/setup-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-commands.d.ts","sourceRoot":"","sources":["../../src/runtime/setup-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,iBAAiB,GAClB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"setup-commands.d.ts","sourceRoot":"","sources":["../../src/runtime/setup-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC"}

package/dist/runtime/setup-commands.js

@@ -1,2 +1,2 @@
-export { SETUP_MLX_MONOREPO, SETUP_PYTORCH_MONOREPO, SETUP_MLX_CLI, SETUP_PYTORCH_CLI, } from './setup-commands-core.mjs';
+export { SETUP_MLX_MONOREPO, SETUP_PYTORCH_MONOREPO, SETUP_MLX_CLI, SETUP_PYTORCH_CLI, SYNC_PYTORCH_MONOREPO, SYNC_PYTORCH_CLI, } from './setup-commands-core.mjs';
 //# sourceMappingURL=setup-commands.js.map

package/dist/runtime/setup-commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup-commands.js","sourceRoot":"","sources":["../../src/runtime/setup-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,iBAAiB,GAClB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"setup-commands.js","sourceRoot":"","sources":["../../src/runtime/setup-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,2BAA2B,CAAC"}

package/docs/DRIVER_API.md

@@ -0,0 +1,455 @@
+# Driver APIリファレンス
+
+`@modular-prompt/driver`パッケージのAPIリファレンス。
+
+## 目次
+
+- [インターフェース](#インターフェース)
+- [利用可能なドライバー](#利用可能なドライバー)
+- [PyTorchProcess の KV cache](#pytorchprocess-の-kv-cache)
+- [PyTorchDriver の PromptCacheController](#pytorchdriver-の-promptcachecontroller)
+- [型定義](#型定義)
+- [推論キャンセル（AbortSignal）](#推論キャンセルabortsignal)
+- [トークン使用量（usage）](#トークン使用量usage)
+- [共通ユーティリティ（query-utils）](#共通ユーティリティquery-utils)
+- [エラーハンドリング](#エラーハンドリング)
+- [関連ドキュメント](#関連ドキュメント)
+
+## インターフェース
+
+### AIDriver
+
+すべてのドライバーが実装すべき基本インターフェース。
+
+```typescript
+interface AIDriver {
+  query(prompt: CompiledPrompt, options?: QueryOptions): Promise<QueryResult>;
+  streamQuery(prompt: CompiledPrompt, options?: QueryOptions): Promise<StreamResult>;
+  close(): Promise<void>;
+}
+```
+
+#### メソッド
+
+**query()**
+
+コンパイル済みプロンプトでAIモデルにクエリを送信。
+
+```typescript
+query(prompt: CompiledPrompt, options?: QueryOptions): Promise<QueryResult>
+```
+
+**streamQuery()**
+
+ストリーミングレスポンスを生成。`stream`（テキスト断片）と `result`（最終集計）は別経路です。usage は `result.usage` にのみ載せ、各チャンクには含めません。
+
+```typescript
+streamQuery(prompt: CompiledPrompt, options?: QueryOptions): Promise<StreamResult>
+```
+
+**close()**
+
+ドライバーのリソースをクリーンアップ。
+
+```typescript
+close(): Promise<void>
+```
+
+## 利用可能なドライバー
+
+### クラウドサービス
+
+| ドライバー | プロバイダー | Structured Outputs | 用途 |
+|----------|------------|-------------------|------|
+| OpenAIDriver | OpenAI | ✅ ネイティブ | GPT-4, GPT-3.5 |
+| AnthropicDriver | Anthropic | ✅ JSON抽出 | Claude |
+| VertexAIDriver | Google Cloud | ✅ ネイティブ | Gemini + Model Garden（Qwen, Llama等） |
+| GoogleGenAIDriver | Google AI | ✅ ネイティブ | Gemini (API Key) |
+
+### ローカル実行
+
+| ドライバー | プロバイダー | Structured Outputs | 用途 |
+|----------|------------|-------------------|------|
+| OllamaDriver | Ollama | ✅ ネイティブ（継承） | ローカルLLM（OpenAI互換） |
+| MlxDriver | MLX | ✅ JSON抽出 | Apple Silicon最適化（VLM対応） |
+| PyTorchDriver | PyTorch | ✅ JSON抽出 | Transformers + PyTorch（LIP、Windows/Linux 等） |
+| VllmDriver | vLLM | ✅ JSON抽出 | CUDA GPU推論（Linux） |
+
+### テスト用
+
+| ドライバー | プロバイダー | Structured Outputs | 用途 |
+|----------|------------|-------------------|------|
+| TestDriver | - | ✅ JSON抽出 | ユニットテスト、モック |
+| EchoDriver | - | ✅ JSON抽出 | デバッグ、プロンプト検証 |
+
+詳細な使用方法、設定オプション、カスタムドライバーの実装については、[packages/driver/README.md](../packages/driver/README.md)を参照してください。
+
+### PyTorchProcess の KV cache
+
+`PyTorchProcess` は、`PyTorchDriver` の自動 cache 管理を構成する低レベルの LIP 操作として、text-only Transformers LM の KV cache を扱えます。`memory://` ref は Python 子プロセス内だけで有効です。`cpu-minimal` backend では通常のファイルパスを指定すると、PyTorch backend 固有の `pytorch_kv_v1` 形式で cache と `.meta.json` を保存できます。CUDA backend は process-local cache のみを使用し、cache ファイルを作成しません。
+
+```typescript
+import { PyTorchProcess } from '@modular-prompt/driver';
+
+const pytorch = new PyTorchProcess('Qwen/Qwen2.5-0.5B-Instruct');
+const prefix = [{ role: 'system' as const, content: 'You are concise.' }];
+const messages = [...prefix, { role: 'user' as const, content: 'Hello.' }];
+
+const prefill = await pytorch.cachePrefill('memory://system-prefix', prefix);
+console.log(prefill.cache_write_tokens); // prefill で書き込んだ token 数
+
+const rendered = await pytorch.render(messages);
+if (rendered.error || rendered.formatted_prompt == null) {
+  throw new Error(rendered.error ?? 'render failed');
+}
+
+const stream = await pytorch.generate(
+  rendered.formatted_prompt,
+  { max_tokens: 64, temperature: 0 },
+  undefined,
+  undefined,
+  prefill.cache_path,
+);
+for await (const chunk of stream) {
+  process.stdout.write(String(chunk));
+}
+await pytorch.exit();
+```
+
+`cachePrefill()` に渡した prefix と、`generate()` に渡す rendered prompt の先頭 token 列は一致している必要があります。`generate()` は cache を読み込んで suffix だけを推論し、cache 自体への書き戻しは行いません。`cacheTrimTokens` を指定した場合も、trim は生成用の clone に適用されるため、登録済みの元 cache ref は変更されません。cache を使えた場合の Python 側 stream meta には `cache_read_tokens`、最初の利用時だけ `cache_write_tokens`、`cache_loaded: true` が含まれ、`cache_loaded: false` の場合は `cacheReadTokens` に算入されません。`baseCachePath` と `trimToTokens` を指定した `cachePrefill()` では、既存 cache の共通 prefix を再利用して suffix だけを prefill します。
+
+契約は次のとおりです。
+
+- `cachePrefill()` の結果には `cache_write_tokens`（prefill で新規に書き込んだ token 数）が含まれ、`PyTorchProcess.cachePrefill()` からそのまま参照できます。同じ値は最初の cache 利用時の stream meta にも付与されますが、同じ prefill 操作を後続 generate の書き込みとして重複計上するものではありません。
+- `memory://` ref は同じ Python 子プロセスの registry にだけ存在します。プロセス終了・`exit()`・restart 後は cache miss になり、`generate` は full prompt の cold path にフォールバックします。
+- `cpu-minimal` のファイル cache の `.meta.json` には `token_count`、`prefix_offsets`、`prefix_hashes`、`model_id`、dtype、device、layout が記録されます。モデル・dtype・device が現在の backend と一致しない cache は安全のため読み込まず、cold path にフォールバックします。
+- CUDA backend は cache ref と KV state を Python process-local registry に保持し、ファイルを作成しません。incremental prefill / prefix metadata を受け付けず、controller は plain prefill にフォールバックします。プロセス終了・restart 後は cache miss になります。
+- PyTorch の cache 形式は MLX / provider の形式と互換ではありません。VLM / 画像入力の cache は現在の PyTorch backend では無効です。
+
+### PyTorchDriver の PromptCacheController
+
+`PyTorchDriver` に `PyTorchCacheController` を指定すると、`LocalInferenceDriver` の通常の cache lifecycle に PyTorch の `cachePrefill()` / `generate()` を接続できます。`cache: true`（または省略時の既定値）で cacheable prefix を自動作成し、prefill・再利用の結果は `QueryResult.usage.cacheReadTokens` / `cacheWriteTokens` に反映されます。固定 `cacheDir` の `cache-index.json` と `pytorch_kv_v1` cache をプロセス再起動後に再利用できるのは `cpu-minimal` backend です。CUDA backend は process-local のため restart 後に再利用できません。
+
+固定 `cacheDir` は一つの PyTorch runtime variant / device 専用です。index は runtime identity を区別しないため、`cpu-minimal` と CUDA で同じ固定 `cacheDir` を共有することは禁止します。runtime ごとに別のディレクトリを指定してください。
+
+```typescript
+import {
+  PyTorchCacheController,
+  PyTorchDriver,
+} from '@modular-prompt/driver';
+
+const driver = new PyTorchDriver({
+  model: 'Qwen/Qwen2.5-0.5B-Instruct',
+  cacheController: new PyTorchCacheController({
+    cacheDir: '/path/to/pytorch-cache',
+  }),
+});
+
+const result = await driver.query(prompt, { cache: true });
+console.log(result.usage?.cacheReadTokens);
+console.log(result.usage?.cacheWriteTokens);
+await driver.close();
+```
+
+PyTorch の現行 backend は VLM・画像入力をサポートしないため、そのモデルでは controller は bind されず cache は無効になります。`cpu-minimal` の cache は固定 `cacheDir` で永続化できますが、CUDA の cache は process-local です。PyTorch cache は MLX cache と相互運用しません。
+
+## 型定義
+
+### ChatMessage
+
+対話メッセージの型。
+
+```typescript
+interface ChatMessage {
+  role: 'system' | 'assistant' | 'user';
+  content: string | Attachment[];  // MLX VLMモデルでは画像をAttachmentで指定可能
+  name?: string;
+}
+
+interface Attachment {
+  type: 'text' | 'image_url' | 'file';
+  text?: string;
+  image_url?: { url: string };  // driver-dependent: local path, URL, or data source
+  file?: { path: string; mime_type: string };
+}
+```
+
+`Attachment` は共通型ですが、入力源の対応範囲は driver ごとに異なります。MLX VLM の画像入力および画像 cache 経路は local file path のみ対応し、URL / data URI は未対応です。MLX は local path を `PIL.Image.open()` で読み込むため、URL や data URI を自動取得しません。他 driver の URL / data source 対応は各 driver の仕様に従います。
+
+### QueryOptions
+
+クエリ実行時のオプション。
+
+```typescript
+interface QueryOptions {
+  temperature?: number;         // 生成のランダム性 (0-2)
+  maxTokens?: number;           // 最大トークン数
+  topP?: number;                // トップPサンプリング
+  stream?: boolean;             // ストリーミング有効化
+  reasoningEffort?: 'low' | 'medium' | 'high';  // 推論深度（thinking系モデル用）
+  signal?: AbortSignal;         // 推論キャンセル（未対応ドライバーは無視）
+  cache?: boolean | 'read-only'; // プロンプトキャッシュ（ドライバー依存）
+}
+```
+
+**signal**: 進行中の推論をキャンセルするための `AbortSignal` です。
+- 呼び出し時点で `aborted` の場合、推論を開始せず `finishReason: 'error'` で `result` を resolve します
+- ストリーム消費中の abort では `result` を reject しません（キャンセル判定は `signal.aborted`）
+- 現時点で対応しているのは MLX ドライバーのみです
+
+**reasoningEffort**: 推論特化モデル（OpenAI o-series、llm-jp-4-thinking等）の思考深度を制御します。
+- 対応ドライバー: OpenAI（APIパラメータとして送信）、MLX（`apply_chat_template`に渡す）
+- 非対応ドライバーでは無視されます
+
+### QueryResult
+
+クエリ結果の型。
+
+```typescript
+interface QueryResult {
+  content: string;                     // テキストレスポンス
+  thinkingContent?: string;            // 思考・推論チャネルの内容
+  structuredOutput?: unknown;          // 構造化出力（スキーマ指定時）
+  finishReason?: 'stop' | 'length' | 'error' | 'tool_calls';
+  usage?: {
+    promptTokens: number;       // プロンプト側トークン総数（プロバイダ報告値）
+    completionTokens: number;   // 生成トークン数
+    totalTokens: number;        // promptTokens + completionTokens と整合
+    cacheReadTokens?: number;   // 今回リクエストでキャッシュから読んだトークン数
+    cacheWriteTokens?: number;  // 今回リクエストでキャッシュに新規書き込みしたトークン数
+  };
+  logEntries?: LogEntry[];             // クエリ実行中のログエントリ
+  errors?: LogEntry[];                 // エラーレベルのログエントリ
+}
+```
+
+**thinkingContent**: モデルの思考・推論過程の内容を格納します。
+- Harmonyフォーマット（llm-jp-4等）の `analysis` チャネル
+- 将来的にAnthropicのthinkingブロック等にも対応予定
+
+**usage**: トークン使用量は `stream` チャンクではなく `result.usage` にのみ載せます。
+- `promptTokens` はキャッシュ分を差し引く前のプロバイダ報告値です
+- `cacheReadTokens` / `cacheWriteTokens` はプロンプトキャッシュ対応ドライバーが任意で付与します（未取得時は省略または 0）
+- MLX ドライバーは `prompt_tokens` / `generation_tokens` をマッピングし、KV キャッシュ利用時は `cacheReadTokens` を付与します
+- PyTorch の低レベル `cachePrefill()` は操作結果の `cache_write_tokens` を返します。`PyTorchCacheController` 経由の `PyTorchDriver` では、同一 query の新規 prefill 分を `cacheWriteTokens`、実際に load できた cache の token 数を `cacheReadTokens` として `QueryResult.usage` に反映します。CPU の disk hit と CUDA の process-local hit のどちらもこの契約に従います
+
+### StreamResult
+
+ストリーミング結果の型。
+
+```typescript
+interface StreamResult {
+  stream: AsyncIterable<string>;  // ストリームチャンク
+  result: Promise<QueryResult>;   // 最終結果
+}
+```
+
+### ModelSpec
+
+モデルの仕様定義。
+
+```typescript
+interface ModelSpec {
+  model: string;                    // モデル識別子
+  provider: DriverProvider;         // プロバイダー名
+  capabilities: DriverCapability[]; // モデルの能力
+  maxInputTokens?: number;         // 最大入力トークン数
+  maxOutputTokens?: number;        // 最大出力トークン数
+  priority?: number;                // 優先度（低い値ほど優先）
+  enabled?: boolean;                // 有効/無効フラグ
+  cost?: {
+    input: number;                  // 入力コスト（per 1K tokens）
+    output: number;                 // 出力コスト（per 1K tokens）
+  };
+}
+```
+
+### DriverCapability
+
+ドライバーの能力を表すフラグ。
+
+```typescript
+type DriverCapability =
+  | 'streaming'        // ストリーミング対応
+  | 'tools'            // Function Calling対応
+  | 'vision'           // 画像入力対応
+  | 'japanese'         // 日本語対応
+  | 'reasoning'        // 推論特化
+  | 'fast'             // 高速応答
+  | 'local'            // ローカル実行
+  | 'structured-output' // Structured Outputs対応
+  | string;            // カスタム能力
+```
+
+### DriverProvider
+
+利用可能なプロバイダー。
+
+```typescript
+type DriverProvider =
+  | 'openai'
+  | 'anthropic'
+  | 'vertexai'
+  | 'ollama'
+  | 'mlx'
+  | 'vllm'
+  | 'test'
+  | 'echo'
+  | string;  // カスタムプロバイダー
+```
+
+## 推論キャンセル（AbortSignal）
+
+`QueryOptions.signal` で進行中の推論をキャンセルします。未対応ドライバーはこのオプションを無視します。
+
+### 契約
+
+| 条件 | 振る舞い |
+|---|---|
+| 呼び出し時点で `signal.aborted` | 推論を開始しない。`result` は reject せず `finishReason: 'error'` で resolve |
+| ストリーム消費中に `abort()` | バックエンドの推論を止め、`stream` を終了させる |
+| キャンセル判定 | `finishReason === 'error'` かつ `signal.aborted`（呼び出し側がキャンセルとエラーを区別） |
+| 部分応答 | キャンセル前に yield されたテキストは `result.content` に保持 |
+
+### ドライバー対応状況
+
+| ドライバー | `signal` 対応 |
+|---|---|
+| MlxDriver | ✅（Python 子プロセス連携） |
+| その他 | 未実装（無視） |
+
+### 使用例
+
+```typescript
+const controller = new AbortController();
+
+const { stream, result } = await driver.streamQuery(prompt, {
+  signal: controller.signal,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk);
+  if (shouldCancel) controller.abort();
+}
+
+const final = await result;
+if (controller.signal.aborted) {
+  // キャンセル（Pi 連携では stopReason: "aborted" に変換）
+} else if (final.finishReason === 'error') {
+  // 推論エラー
+}
+```
+
+### MLX ドライバーの実装概要
+
+TS 側が `{"method":"cancel"}\n` を Python 子プロセスの stdin に送り、Python は `stream_generate` の各チャンク前に `poll_cancel()` で非ブロッキング検知してループを抜けます。同時に Node 側の `Readable` を `destroy()` し、stdout をドレインして次リクエストがキュー詰まりしないようにします。詳細は [プロンプトキャッシュ設計](./CACHE_DESIGN.md#queryresultusage-との関係) および `packages/driver/src/mlx-ml/python/handlers/cancel.py` を参照。
+
+## トークン使用量（usage）
+
+`QueryResult.usage` はプロバイダ報告のトークン数を正規化したオブジェクトです。
+
+| フィールド | 意味 |
+|---|---|
+| `promptTokens` | プロンプト側トークン総数（キャッシュ分を差し引く前の生値） |
+| `completionTokens` | 今回の生成トークン数 |
+| `totalTokens` | 少なくとも `promptTokens + completionTokens` と整合 |
+| `cacheReadTokens` | 今回リクエストでキャッシュから読んだトークン数（任意） |
+| `cacheWriteTokens` | 今回リクエストでキャッシュに新規書き込みしたトークン数（任意） |
+
+driver は `promptTokens` を「非キャッシュ入力」に分解しません（`promptTokens - cacheRead - cacheWrite` のような計算は行いません）。
+
+### ドライバー対応状況
+
+| ドライバー | `usage` 基本3フィールド | `cacheReadTokens` / `cacheWriteTokens` |
+|---|---|---|
+| OpenAI / Anthropic / VertexAI / GoogleGenAI | ✅ | 未対応（省略） |
+| MlxDriver | ✅ | ✅（KV キャッシュ利用時） |
+| PyTorchDriver | ✅ | ✅（`PyTorchCacheController` 利用時） |
+| その他 | 状況により異なる | 未対応 |
+
+MLX では Python 側の `prompt_tokens` / `generation_tokens` をマッピングし、`cacheReadTokens` は KV ヒット分、`cacheWriteTokens` は同一クエリ内の `prepare()` による新規 prefill 分を報告します。PyTorch も同じ usage 契約に従い、`PyTorchCacheController` の `prepare()` による新規 prefill 分と、Python stream meta が報告する実際の cache load token 数をマッピングします。cache load に失敗して `cache_loaded: false` になった場合、`cacheReadTokens` はその query では算入されません。
+
+## 共通ユーティリティ（query-utils）
+
+`@modular-prompt/driver` が提供するヘルパー。カスタムドライバーやアダプタ実装で利用できます。
+
+```typescript
+import {
+  buildQueryUsage,
+  createAbortedStreamResult,
+  isAborted,
+  watchAbortSignal,
+} from '@modular-prompt/driver';
+```
+
+| 関数 | 用途 |
+|---|---|
+| `buildQueryUsage(counts)` | 生トークン数から `QueryResult.usage` を組み立て（全ゼロなら `undefined`） |
+| `createAbortedStreamResult(extras?)` | 即時 abort 用の空 `StreamResult`（`result` は resolve） |
+| `isAborted(signal?)` | `signal?.aborted ?? false` |
+| `watchAbortSignal(signal, onAbort)` | abort リスナー登録。既に aborted なら即 `onAbort` を呼ぶ |
+
+## エラーハンドリング
+
+すべてのドライバーは統一されたエラーハンドリングを提供：
+
+```typescript
+const result = await driver.query(prompt);
+
+if (result.finishReason === 'error') {
+  // エラーまたはキャンセル — signal.aborted で区別
+  if (options?.signal?.aborted) {
+    console.log('Query was cancelled');
+  } else if (result.errors) {
+    for (const entry of result.errors) {
+      console.error(`[${entry.prefix}] ${entry.message}`);
+    }
+  }
+} else if (result.finishReason === 'length') {
+  // トークン数制限により切り詰め
+  console.warn('Response was truncated');
+} else if (result.finishReason === 'stop') {
+  // 正常終了
+}
+
+// logEntries で全レベルのログを確認可能
+if (result.logEntries) {
+  console.log(`Query produced ${result.logEntries.length} log entries`);
+}
+```
+
+### ドライバー実装者向けログ規約
+
+ドライバー実装では `QueryLogger` を使用してクエリスコープのログを記録する。`console.error` / `console.warn` の直接使用は禁止。
+
+```typescript
+import { QueryLogger } from '../query-logger.js';
+
+class MyDriver implements AIDriver {
+  private queryLogger = new QueryLogger('MyDriver');
+
+  async streamQuery(prompt, options) {
+    this.queryLogger.mark();  // 各クエリの先頭で呼ぶ
+    try {
+      // ... API呼び出し
+      const result = { content, finishReason, usage };
+      return { stream, result: Promise.resolve({ ...result, ...this.queryLogger.collect() }) };
+    } catch (error) {
+      this.queryLogger.log.error('Query error:', error instanceof Error ? error.message : String(error));
+      return {
+        stream: (async function* () {})(),
+        result: Promise.resolve({ content: '', finishReason: 'error', ...this.queryLogger.collect() })
+      };
+    }
+  }
+}
+```
+
+**prefix 命名規則**: ドライバー名を使用（`OpenAI`, `Anthropic`, `VertexAI`, `GoogleGenAI`, `MLX`, `vLLM`）。詳細は [UTILITIES.md](./UTILITIES.md) の Logger セクションを参照。
+
+## 関連ドキュメント
+
+- [packages/driver/README.md](../packages/driver/README.md) - 詳細な使用方法とカスタムドライバーの実装
+- [Structured Outputs仕様](./STRUCTURED_OUTPUTS.md) - 構造化出力の詳細
+- [AIService完全ガイド](./AI_SERVICE_GUIDE.md) - 動的ドライバー選択
+- [テスト用ドライバーガイド](./TEST_DRIVERS.md) - TestDriver/EchoDriverの使い方