@modular-prompt/driver 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modular-prompt/driver",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,6 +13,7 @@
   "files": [
     "dist",
     "scripts",
+    "skills",
     "src/mlx-ml/python"
   ],
   "dependencies": {
@@ -23,8 +24,8 @@
     "google-auth-library": "^9.15.1",
     "js-yaml": "^4.1.0",
     "openai": "^5.19.1",
-    "@modular-prompt/core": "0.1.12",
-    "@modular-prompt/utils": "0.2.3"
+    "@modular-prompt/core": "0.1.13",
+    "@modular-prompt/utils": "0.2.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",
@@ -54,7 +55,8 @@
     "download-model": "node scripts/download-model.js",
     "lint": "eslint src/**/*.ts",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "copy-skills": "mkdir -p skills/driver-usage && cp ../../skills/driver-usage/SKILL.md skills/driver-usage/SKILL.md",
+    "clean": "rm -rf dist skills tsconfig.tsbuildinfo",
     "postinstall": "node scripts/setup-mlx.js || true",
     "setup-mlx": "node scripts/setup-mlx.js"
   }

package/skills/driver-usage/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: driver-usage
+description: modular-promptのドライバー（AIDriver）の使い方ガイド。各ドライバーの初期化、Config、query/streamQuery、ツール定義、構造化出力、AIServiceによるモデル選択を参照する。
+---
+
+# ドライバー使い方ガイド
+
+## ドライバーとは
+
+`@modular-prompt/driver` は、コンパイル済みプロンプト（CompiledPrompt）をAIモデルに送信し、結果を受け取るための統一インターフェースを提供する。各AIサービスのAPI差異をドライバー層が吸収するため、プロンプト側のコードを変えずにモデルを切り替えられる。
+
+### 基本的な使い方
+
+```typescript
+import { compile } from '@modular-prompt/core';
+import { OpenAIDriver } from '@modular-prompt/driver';
+
+const driver = new OpenAIDriver({ model: 'gpt-4o' });
+const compiled = compile(myModule, context);
+
+// 通常クエリ
+const result = await driver.query(compiled);
+console.log(result.content);
+
+// ストリーミング
+const { stream, result: resultPromise } = await driver.streamQuery(compiled);
+for await (const chunk of stream) {
+  process.stdout.write(chunk);
+}
+const finalResult = await resultPromise;
+
+await driver.close();
+```
+
+## AIDriver インターフェース
+
+全ドライバーが実装する共通インターフェース:
+
+```typescript
+interface AIDriver {
+  query(prompt: CompiledPrompt, options?: QueryOptions): Promise<QueryResult>;
+  streamQuery(prompt: CompiledPrompt, options?: QueryOptions): Promise<StreamResult>;
+  close(): Promise<void>;
+}
+```
+
+### QueryOptions
+
+```typescript
+interface QueryOptions {
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  stream?: boolean;
+  tools?: ToolDefinition[];
+  toolChoice?: ToolChoice;
+}
+```
+
+### QueryResult
+
+```typescript
+interface QueryResult {
+  content: string;               // テキストレスポンス
+  structuredOutput?: unknown;    // 構造化出力（schema指定時）
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  toolCalls?: ToolCall[];        // ツール呼び出し
+  finishReason?: FinishReason;   // 'stop' | 'length' | 'error' | 'tool_calls'
+}
+```
+
+### StreamResult
+
+```typescript
+interface StreamResult {
+  stream: AsyncIterable<string>;  // テキストチャンクのストリーム
+  result: Promise<QueryResult>;   // 最終結果（ストリーム完了後に解決）
+}
+```
+
+## 各ドライバーのConfig
+
+### OpenAIDriver
+
+```typescript
+import { OpenAIDriver } from '@modular-prompt/driver';
+
+const driver = new OpenAIDriver({
+  apiKey: process.env.OPENAI_API_KEY,  // 環境変数で代替可
+  model: 'gpt-4o-mini',               // デフォルト: 'gpt-4o-mini'
+  baseURL: 'https://...',             // カスタムエンドポイント（オプション）
+  organization: '...',                // Organization ID（オプション）
+  defaultOptions: {
+    temperature: 0.7,
+    maxTokens: 2000,
+    frequencyPenalty: 0,               // OpenAI固有
+    presencePenalty: 0,                // OpenAI固有
+    stop: ['---'],                     // 停止シーケンス
+    responseFormat: { type: 'json_object' },
+    seed: 42
+  }
+});
+```
+
+### AnthropicDriver
+
+```typescript
+import { AnthropicDriver } from '@modular-prompt/driver';
+
+const driver = new AnthropicDriver({
+  apiKey: process.env.ANTHROPIC_API_KEY,  // 環境変数で代替可
+  model: 'claude-3-5-sonnet-20241022',    // デフォルト
+  defaultOptions: {
+    maxTokens: 4096,
+    temperature: 0.7,
+    topK: 40,                              // Anthropic固有
+    stopSequences: ['---']
+  }
+});
+```
+
+### VertexAIDriver
+
+```typescript
+import { VertexAIDriver } from '@modular-prompt/driver';
+
+const driver = new VertexAIDriver({
+  project: 'my-gcp-project',     // 環境変数 GOOGLE_CLOUD_PROJECT で代替可
+  location: 'us-central1',       // デフォルト: 'us-central1'
+  model: 'gemini-2.0-flash-001', // デフォルト
+  temperature: 0.05,
+  defaultOptions: {
+    maxTokens: 1000,
+    topP: 0.95,
+    topK: 40
+  }
+});
+```
+
+Google Cloud認証（ADCまたはサービスアカウント）が必要。
+
+### GoogleGenAIDriver
+
+```typescript
+import { GoogleGenAIDriver } from '@modular-prompt/driver';
+
+const driver = new GoogleGenAIDriver({
+  apiKey: process.env.GOOGLE_GENAI_API_KEY,  // 必須
+  model: 'gemini-2.0-flash-exp',
+  temperature: 0.7,
+  defaultOptions: {
+    maxTokens: 2048,
+    topP: 0.95,
+    topK: 40,
+    thinkingConfig: { thinkingLevel: 'HIGH' }  // GoogleGenAI固有
+  }
+});
+```
+
+APIキーのみで利用可能（Google AI Studioから取得）。
+
+### OllamaDriver
+
+```typescript
+import { OllamaDriver } from '@modular-prompt/driver';
+
+const driver = new OllamaDriver({
+  baseURL: 'http://localhost:11434/v1',  // デフォルト
+  model: 'llama3.2'                      // デフォルト
+});
+```
+
+OpenAI互換APIでローカルLLMにアクセス。
+
+### MlxDriver
+
+```typescript
+import { MlxDriver } from '@modular-prompt/driver';
+
+const driver = new MlxDriver({
+  model: 'mlx-community/Llama-3.2-3B-Instruct-4bit',  // 必須
+  defaultOptions: {
+    temperature: 0.7,
+    maxTokens: 500,
+    repetitionPenalty: 1.1,     // MLX固有
+    repetitionContextSize: 20   // MLX固有
+  }
+});
+
+// 使用後は必ずclose()（Pythonサブプロセス終了）
+await driver.close();
+```
+
+Apple Silicon専用。Python 3.11以上が必要。
+
+### テスト・デバッグ用ドライバー
+
+```typescript
+import { TestDriver, EchoDriver } from '@modular-prompt/driver';
+
+// TestDriver: モックレスポンス
+const testDriver = new TestDriver({
+  responses: ['応答1', '応答2'],    // キューから順に返す
+  delay: 100                        // レイテンシのシミュレート（ms）
+});
+
+// レスポンスプロバイダ関数
+const testDriver2 = new TestDriver({
+  responses: (prompt, options) => {
+    if (prompt.metadata?.outputSchema) {
+      return JSON.stringify({ result: 'ok' });
+    }
+    return 'テキスト応答';
+  }
+});
+
+// EchoDriver: フォーマット済みプロンプトをそのまま返す（AI呼び出しなし）
+const echoDriver = new EchoDriver({
+  format: 'debug',        // 'text' | 'messages' | 'raw' | 'both' | 'debug'
+  includeMetadata: true
+});
+```
+
+## ツール定義（Function Calling）
+
+### ToolDefinition
+
+```typescript
+const tools: ToolDefinition[] = [
+  {
+    name: 'get_weather',
+    description: '指定都市の天気を取得',
+    parameters: {
+      type: 'object',
+      properties: {
+        city: { type: 'string', description: '都市名' },
+        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
+      },
+      required: ['city']
+    }
+  }
+];
+```
+
+### ToolChoice
+
+```typescript
+type ToolChoice =
+  | 'auto'             // モデルが自動判断（デフォルト）
+  | 'none'             // ツール使用禁止
+  | 'required'         // 必ず1つ以上のツールを使用
+  | { name: string };  // 特定ツールを強制
+```
+
+### ツール呼び出しの処理
+
+```typescript
+const result = await driver.query(compiled, { tools, toolChoice: 'auto' });
+
+if (result.toolCalls) {
+  for (const call of result.toolCalls) {
+    console.log(call.name);       // 関数名
+    console.log(call.id);         // 呼び出しID
+    console.log(call.arguments);  // 引数オブジェクト
+  }
+}
+```
+
+対応ドライバー: OpenAI、Anthropic、VertexAI、GoogleGenAI
+
+### ツール結果の返し方（会話ループ）
+
+ツール呼び出し結果をモデルに返す会話ループは利用者側で実装する。`QueryOptions.messages` にツール結果を含めて再クエリする。
+
+```typescript
+const result1 = await driver.query(compiled, { tools, toolChoice: 'auto' });
+
+if (result1.toolCalls) {
+  // ツールを実行して結果を収集
+  const toolResults = await Promise.all(
+    result1.toolCalls.map(async (tc) => {
+      const data = await executeFunction(tc.name, tc.arguments);
+      return {
+        role: 'tool' as const,
+        toolCallId: tc.id,
+        name: tc.name,
+        kind: 'data' as const,   // 'text' | 'data' | 'error'
+        value: data
+      };
+    })
+  );
+
+  // ツール結果を含めて再クエリ
+  const result2 = await driver.query(compiled, {
+    tools,
+    messages: [
+      { role: 'assistant', content: result1.content, toolCalls: result1.toolCalls },
+      ...toolResults
+    ]
+  });
+}
+```
+
+### ToolResultKind
+
+ツール結果の種類を示すタグ:
+- `'text'` - プレーンテキスト
+- `'data'` - 構造化データ（オブジェクト等）
+- `'error'` - エラー情報
+
+## 構造化出力
+
+プロンプトの `schema` セクションに JSONElement を定義すると、ドライバーが自動的に構造化出力を処理する。
+
+```typescript
+const myModule: PromptModule = {
+  objective: ['ユーザー情報を抽出する'],
+  schema: [{
+    type: 'json',
+    content: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' }
+      },
+      required: ['name', 'age']
+    }
+  }]
+};
+
+const result = await driver.query(compile(myModule, ctx));
+const data = result.structuredOutput as { name: string; age: number };
+```
+
+ドライバーごとの実装方式:
+- **ネイティブサポート**: OpenAI（`response_format`）、VertexAI / GoogleGenAI（`responseSchema`）
+- **JSON抽出型**: Anthropic、MLX（プロンプト指示 + レスポンスからJSON抽出）
+
+## AIService（モデル選択）
+
+複数モデルを登録し、能力（capabilities）ベースで最適なモデルを自動選択する。
+
+### 設定
+
+```typescript
+import { AIService } from '@modular-prompt/driver';
+
+const service = new AIService({
+  models: [
+    {
+      model: 'gpt-4o',
+      provider: 'openai',
+      capabilities: ['streaming', 'japanese', 'tools', 'structured'],
+      priority: 10,
+      cost: { input: 0.01, output: 0.03 }
+    },
+    {
+      model: 'claude-3-5-sonnet-20241022',
+      provider: 'anthropic',
+      capabilities: ['streaming', 'japanese', 'tools', 'reasoning'],
+      priority: 8
+    }
+  ],
+  drivers: {
+    openai: { apiKey: process.env.OPENAI_API_KEY },
+    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY }
+  },
+  defaultOptions: {
+    temperature: 0.7,
+    maxTokens: 2048
+  }
+});
+```
+
+### ModelSpec
+
+```typescript
+interface ModelSpec {
+  model: string;
+  provider: DriverProvider;
+  capabilities: DriverCapability[];
+  priority?: number;              // 高いほど優先
+  disabled?: boolean;             // 無効化フラグ
+  maxInputTokens?: number;
+  maxOutputTokens?: number;
+  maxTotalTokens?: number;
+  tokensPerMinute?: number;       // TPM制限
+  requestsPerMinute?: number;     // RPM制限
+  cost?: { input: number; output: number };
+  metadata?: Record<string, unknown>;
+}
+```
+
+### DriverCapability（能力フラグ）
+
+| 能力 | 説明 |
+|------|------|
+| `streaming` | ストリーミング応答 |
+| `local` | ローカル実行 |
+| `fast` | 高速応答 |
+| `large-context` | 大規模コンテキスト |
+| `multilingual` | 多言語対応 |
+| `japanese` | 日本語特化 |
+| `coding` | コーディング特化 |
+| `reasoning` | 推論・思考特化 |
+| `chat` | チャット特化 |
+| `tools` | ツール使用 |
+| `vision` | 画像認識 |
+| `audio` | 音声処理 |
+| `structured` | 構造化出力 |
+| `json` | JSON出力 |
+| `function-calling` | 関数呼び出し |
+
+### モデル選択
+
+```typescript
+// 能力ベースでドライバーを自動作成
+const driver = await service.createDriverFromCapabilities(
+  ['japanese', 'streaming'],
+  {
+    preferLocal: true,           // ローカル優先
+    preferProvider: 'anthropic', // 特定プロバイダー優先
+    excludeProviders: ['openai'],
+    preferFast: true,            // 高速優先
+    lenient: true                // 条件緩和モード（条件を後ろから減らして再検索）
+  }
+);
+```

package/src/mlx-ml/python/token_utils.py

@@ -124,7 +124,15 @@ def get_special_tokens(tokenizer):
         "scratchpad": ("<|scratchpad|>", "<|/scratchpad|>"),
         "analysis": ("<|analysis|>", "<|/analysis|>"),
         "summary": ("<|summary|>", "<|/summary|>"),
-        "explanation": ("<|explanation|>", "<|/explanation|>")
+        "explanation": ("<|explanation|>", "<|/explanation|>"),
+
+        # tool_call バリエーション（追加）
+        "tool_call_explicit": ("<|tool_call_start|>", "<|tool_call_end|>"),
+        "tool_call_xml": ("<tool_call>", "</tool_call>"),
+        "tool_calls_section": ("<|tool_calls_section_begin|>", "<|tool_calls_section_end|>"),
+        "function_call_tags": ("<start_function_call>", "<end_function_call>"),
+        "longcat_tool_call": ("<longcat_tool_call>", "</longcat_tool_call>"),
+        "minimax_tool_call": ("<minimax:tool_call>", "</minimax:tool_call>"),
     }
     
     # 単体トークン（存在する場合のみ）
@@ -143,7 +151,10 @@ def get_special_tokens(tokenizer):
         # 一般的なマークダウン風
         "code_inline": "`",
         "code_block_start": "```",
-        "code_block_end": "```"
+        "code_block_end": "```",
+
+        # ツール関連の単体トークン（追加）
+        "tool_calls_marker": "[TOOL_CALLS]",
     }
     
     # ペアトークンの処理
@@ -192,6 +203,24 @@ def detect_tool_call_format(tokenizer):
     if hasattr(tokenizer, 'init_kwargs'):
         tool_parser_type = tokenizer.init_kwargs.get('tool_parser_type')
 
+    # 既知パーサーからの逆引き（最優先）
+    KNOWN_TOOL_PARSERS = {
+        "json_tools": {"call_start": "<tool_call>", "call_end": "</tool_call>"},
+        "pythonic": {"call_start": "<|tool_call_start|>", "call_end": "<|tool_call_end|>"},
+        "function_gemma": {"call_start": "<start_function_call>", "call_end": "<end_function_call>"},
+        "mistral": {"call_start": "[TOOL_CALLS]", "call_end": ""},
+        "kimi_k2": {"call_start": "<|tool_calls_section_begin|>", "call_end": "<|tool_calls_section_end|>"},
+        "longcat": {"call_start": "<longcat_tool_call>", "call_end": "</longcat_tool_call>"},
+        "glm47": {"call_start": "<tool_call>", "call_end": "</tool_call>"},
+        "qwen3_coder": {"call_start": "<tool_call>", "call_end": "</tool_call>"},
+        "minimax_m2": {"call_start": "<minimax:tool_call>", "call_end": "</minimax:tool_call>"},
+    }
+
+    if tool_parser_type and tool_parser_type in KNOWN_TOOL_PARSERS:
+        result = {"tool_parser_type": tool_parser_type}
+        result.update(KNOWN_TOOL_PARSERS[tool_parser_type])
+        return result
+
     # chat_template テキストを取得
     template = getattr(tokenizer, 'chat_template', None)
     if not template and hasattr(tokenizer, 'init_kwargs'):
@@ -207,21 +236,36 @@ def detect_tool_call_format(tokenizer):
 
     # テンプレートテキストからデリミタを抽出
     if template:
-        # tool_call タグの検出（<tool_call>, <|tool_call|> 等）
-        call_match = re.search(r'(<\|?tool_call\|?>)\s*\\n.*?(<\/?\|?tool_call\|?>|<\|?/tool_call\|?>)', template)
-        if call_match:
-            result["call_start"] = call_match.group(1)
-            result["call_end"] = call_match.group(2)
-        else:
-            # フォールバック: tool_call を含む開閉タグペアを探す
-            tags = re.findall(r'<[|/]?tool_call[|]?>', template)
-            if len(tags) >= 2:
-                # 開タグと閉タグを分離
-                open_tags = [t for t in tags if '/' not in t]
-                close_tags = [t for t in tags if '/' in t]
-                if open_tags and close_tags:
-                    result["call_start"] = open_tags[0]
-                    result["call_end"] = close_tags[0]
+        # 複数のtool_call関連パターンを順に試行
+        tool_call_patterns = [
+            # <tool_call>...</tool_call>, <|tool_call|>...<|/tool_call|>
+            (r'<\|?tool_call\|?>', r'</?\|?tool_call\|?>|<\|?/tool_call\|?>'),
+            # <|tool_call_start|>...<|tool_call_end|>
+            (r'<\|tool_call_start\|>', r'<\|tool_call_end\|>'),
+            # <start_function_call>...<end_function_call>
+            (r'<start_function_call>', r'<end_function_call>'),
+            # <|tool_calls_section_begin|>...<|tool_calls_section_end|>
+            (r'<\|tool_calls_section_begin\|>', r'<\|tool_calls_section_end\|>'),
+            # <longcat_tool_call>...</longcat_tool_call>
+            (r'<longcat_tool_call>', r'</longcat_tool_call>'),
+            # <minimax:tool_call>...</minimax:tool_call>
+            (r'<minimax:tool_call>', r'</minimax:tool_call>'),
+        ]
+
+        for start_pattern, end_pattern in tool_call_patterns:
+            start_match = re.search(start_pattern, template)
+            end_match = re.search(end_pattern, template)
+            if start_match and end_match:
+                result["call_start"] = start_match.group(0)
+                result["call_end"] = end_match.group(0)
+                break
+
+        # Mistral特殊ケース
+        if "call_start" not in result:
+            mistral_match = re.search(r'\[TOOL_CALLS\]', template)
+            if mistral_match:
+                result["call_start"] = "[TOOL_CALLS]"
+                result["call_end"] = ""
 
         # tool_response タグの検出
         resp_tags = re.findall(r'<[|/]?tool_response[|]?>', template)
@@ -325,6 +369,20 @@ def get_capabilities(tokenizer):
         "features": get_tokenizer_features(tokenizer)
     }
 
+    # tool_call_formatの情報をspecial_tokensに反映（補完）
+    features = capabilities.get("features", {})
+    chat_template = features.get("chat_template")
+    if chat_template:
+        tcf = chat_template.get("tool_call_format")
+        if tcf and tcf.get("call_start") and "tool_call" not in capabilities["special_tokens"]:
+            call_start = tcf["call_start"]
+            call_end = tcf.get("call_end", "")
+            if call_end:  # ペアがある場合のみ
+                capabilities["special_tokens"]["tool_call"] = {
+                    "start": {"text": call_start, "id": -1},
+                    "end": {"text": call_end, "id": -1}
+                }
+
     # チャット制約を検出して追加
     chat_restrictions = detect_chat_restrictions(tokenizer)
     if chat_restrictions: