@modular-prompt/driver

AIモデルドライバーパッケージ - 様々なAIプロバイダーとの統一されたインターフェースを提供。

インストール

npm install @modular-prompt/driver

基本的な使い方

import { compile } from '@modular-prompt/core';
import { OpenAIDriver } from '@modular-prompt/driver';

const driver = new OpenAIDriver({ model: 'gpt-4o-mini' });
const prompt = compile(myModule, context);

// クエリ
const result = await driver.query(prompt, { temperature: 0.7 });
console.log(result.content);

// ストリーミング
const { stream, result: resultPromise } = await driver.streamQuery(prompt);
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

await driver.close();

エラーハンドリング

すべてのドライバーは QueryResult を通じて統一されたエラー情報を提供します。

const result = await driver.query(prompt);

if (result.finishReason === 'error') {
  // errors フィールドでエラー詳細を確認
  if (result.errors) {
    for (const entry of result.errors) {
      console.error(`[${entry.prefix}] ${entry.message}`);
    }
  }
}

// logEntries で全レベルのログを確認可能
if (result.logEntries) {
  console.log(`Query produced ${result.logEntries.length} log entries`);
}

詳細は Driver APIリファレンス を参照してください。

利用可能なドライバー

| ドライバー | プロバイダー | 備考 | |-----------|------------|------| | OpenAIDriver | OpenAI | OpenAI互換API対応 | | AnthropicDriver | Anthropic | Claude（Vertex経由も可） | | VertexAIDriver | Google Cloud | Gemini + Model Garden（Qwen, Llama等） | | GoogleGenAIDriver | Google | APIキーのみで利用可能 | | OllamaDriver | Ollama | ローカルLLM | | MlxDriver | MLX | Apple Silicon専用（VLM対応） | | VllmDriver | vLLM | CUDA GPU推論（Linux） | | TestDriver | - | モックレスポンス | | EchoDriver | - | プロンプトをそのまま返す |

各ドライバーの詳細な設定・オプションは skills/driver-usage/SKILL.md を参照。

主な機能

• 統一インターフェース: query() / streamQuery() / close() の3メソッド
• ツール呼び出し: Function Calling対応（OpenAI、Anthropic、VertexAI、GoogleGenAI）
• 構造化出力: JSONスキーマによる出力制御
• AIService: 能力ベースのモデル自動選択

カスタムドライバーの作成

AIDriver インターフェースを実装:

import type { AIDriver, CompiledPrompt, QueryOptions, QueryResult, StreamResult } from '@modular-prompt/driver';

export class CustomDriver implements AIDriver {
  async query(prompt: CompiledPrompt, options?: QueryOptions): Promise<QueryResult> {
    // 実装
  }

  async streamQuery(prompt: CompiledPrompt, options?: QueryOptions): Promise<StreamResult> {
    // 実装
  }

  async close(): Promise<void> {
    // リソースのクリーンアップ
  }
}

ローカルモデルのセットアップ

MLX（Apple Silicon）

MLXドライバーはインストール時に自動でPython環境をセットアップします。手動で実行する場合:

cd node_modules/@modular-prompt/driver
npm run setup-mlx

前提条件: Python 3.11以上、Apple Silicon Mac、uv。

VLMモデルのtext-only使用

VLM（Vision Language Model）対応モデルを画像なしのテキストのみで使用する場合は、textOnlyオプションを使用します。

import { MlxDriver } from '@modular-prompt/driver';

const driver = new MlxDriver({
  model: 'mlx-community/Qwen2-VL-2B-Instruct-4bit',
  textOnly: true,  // VLMモデルをtext-onlyモードで起動
  defaultOptions: {
    temperature: 0.7,
    maxTokens: 500
  }
});

const result = await driver.query(prompt);
console.log(result.content);

await driver.close();

textOnly: trueを指定すると、VLM対応モデルをmlx-lm（高速起動）で起動し、画像処理なしのテキストのみで使用できます。

特殊トークンの確認

モデルがサポートする特殊トークンを確認できます:

npx tsx scripts/check-special-tokens.ts <model-name>
# 例:
npx tsx scripts/check-special-tokens.ts mlx-community/gemma-3-270m-it-qat-8bit

Thinking系モデルの推論深度制御

reasoningEffort オプションで推論深度を制御できます（llm-jp-4-thinking等に対応）:

const result = await driver.query(prompt, {
  reasoningEffort: 'high',  // 'low' | 'medium' | 'high'
  temperature: 0.7
});

// thinking チャネルの内容を取得
if (result.thinkingContent) {
  console.log('Thinking:', result.thinkingContent);
}
console.log('Response:', result.content);

対応モデル:

• llm-jp-4-*-thinking シリーズ（Harmonyフォーマット）
• reasoningEffort は Python側の apply_chat_template に渡されます

Harmonyフォーマット: llm-jp-4が採用するOpenAI Harmony Response Format。スペシャルトークン（<|start|>, <|channel|>, <|message|> 等）でメッセージを分割し、analysis チャネルを thinkingContent、final チャネルを content に振り分けます。

技術詳細: Harmonyフォーマットの後処理設計、ResponseProcessorアーキテクチャ、tool call形式については prompts/memos/harmony-format-postprocessing.v1.md を参照してください。

vLLM（CUDA GPU）

vLLMドライバーは独立したPythonエンジンプロセスとして起動します。

# 環境のセットアップ
cd node_modules/@modular-prompt/driver/src/vllm/python
uv sync

# エンジンの起動
uv --project . run python __main__.py \
  --model Qwen/Qwen2.5-7B-Instruct \
  --socket /tmp/vllm.sock \
  --tool-call-parser hermes

前提条件: Python 3.10以上、CUDA対応GPU、Linux。

詳細は ローカルモデルセットアップガイド を参照してください。

Skills（Claude Code向け）

このパッケージには skills/driver-usage/SKILL.md が同梱されています。Claude Codeのスキルとして利用でき、ドライバーの使い方をガイドします。

ライセンス

MIT