@modular-prompt/driver 0.15.0 → 0.17.0

package/docs/mlx-api-selection.md

@@ -0,0 +1,301 @@
+# MLX Driver API Selection
+
+MLX Driverは、chat APIとcompletion APIの2つのAPIを提供しています。このドキュメントでは、どちらのAPIを使用するかを決定するロジックと、カスタマイズ方法について説明します。
+
+## デフォルトのAPI選択ロジック
+
+`ModelSpecManager.determineApi()`は、以下の順序でAPIを選択します：
+
+### 1. カスタムロジック（最優先）
+
+`customProcessor.determineApi()`が提供されている場合、それが最優先されます。
+
+```typescript
+const driver = new MlxDriver({
+  model: 'some-model',
+  modelSpec: {
+    customProcessor: {
+      determineApi: (context) => {
+        // カスタムロジック
+        if (/* 特定の条件 */) {
+          return 'completion';
+        }
+        // デフォルトロジックに委譲
+        return undefined;
+      }
+    }
+  }
+});
+```
+
+### 2. 強制モード
+
+`apiStrategy`が`'force-chat'`または`'force-completion'`の場合、その設定が優先されます。
+
+```typescript
+modelSpec: {
+  apiStrategy: 'force-completion'  // 常にcompletion APIを使用
+}
+```
+
+### 3. 機能チェック
+
+- `hasApplyChatTemplate: false`の場合: completion APIを使用
+- `supportsCompletion: false`の場合: chat APIを使用
+
+### 4. 優先モード
+
+#### `prefer-chat`
+
+1. メッセージを検証
+2. 有効な場合: chat APIを使用
+3. 無効な場合: completion APIにフォールバック
+
+```typescript
+modelSpec: {
+  apiStrategy: 'prefer-chat',
+  chatRestrictions: {
+    singleSystemAtStart: true,
+    requiresUserLast: true
+  }
+}
+```
+
+#### `prefer-completion`
+
+常にcompletion APIを使用します。
+
+### 5. `auto`モード（デフォルト）
+
+1. メッセージを検証
+2. chat制限に違反している場合: completion APIを使用
+3. chat制限が3個以上の場合: completion APIを使用
+4. それ以外: chat APIを使用
+
+---
+
+## カスタムAPI選択ロジック
+
+`customProcessor.determineApi()`を使用して、独自のロジックを実装できます。
+
+### ApiSelectionContext
+
+カスタムロジックには、以下の情報が提供されます：
+
+```typescript
+interface ApiSelectionContext {
+  messages: MlxMessage[];              // 処理対象のメッセージ
+  validation: ValidationResult;        // メッセージの検証結果
+  capabilities: {                      // モデルの機能情報
+    hasApplyChatTemplate?: boolean;
+    supportsCompletion?: boolean;
+  };
+  chatRestrictions?: ChatRestrictions; // チャット制限
+  apiStrategy: ApiStrategy;            // 設定されたapiStrategy
+}
+```
+
+### 戻り値
+
+- `'chat'`: chat APIを使用
+- `'completion'`: completion APIを使用
+- `undefined`: デフォルトロジックに委譲
+
+---
+
+## ヘルパー関数
+
+### createModulerPromptApiSelector()
+
+modular-promptの典型的なパターン（system → user → system(cue)）に最適化されたセレクター。
+
+#### 検出するパターン
+
+```typescript
+[
+  { role: 'system', content: 'instructions...' },
+  { role: 'user', content: 'input data...' },
+  { role: 'system', content: 'Please output in JSON format' }  // cue
+]
+```
+
+#### 問題となる制限
+
+- `singleSystemAtStart: true` - systemメッセージは先頭1つのみ
+- `maxSystemMessages: 1` - システムメッセージは1個まで
+
+上記パターンと制限の組み合わせでは、cueメッセージを配置できないため、completion APIを強制します。
+
+#### 使用例
+
+```typescript
+import { createModulerPromptApiSelector } from '@modular-prompt/driver/mlx-ml/model-spec';
+
+const driver = new MlxDriver({
+  model: 'gemma-2-2b-it-4bit',
+  modelSpec: {
+    customProcessor: {
+      determineApi: createModulerPromptApiSelector()
+    }
+  }
+});
+```
+
+### createSystemMessageBasedSelector(minSystemMessages)
+
+システムメッセージの数に基づくセレクター。
+
+#### パラメータ
+
+- `minSystemMessages`: この数以上のsystemメッセージがある場合に判定（デフォルト: 2）
+
+#### 使用例
+
+```typescript
+import { createSystemMessageBasedSelector } from '@modular-prompt/driver/mlx-ml/model-spec';
+
+const driver = new MlxDriver({
+  model: 'some-model',
+  modelSpec: {
+    customProcessor: {
+      determineApi: createSystemMessageBasedSelector(3)
+    }
+  }
+});
+```
+
+### combineSelectors(selectors)
+
+複数のセレクターを組み合わせるコンビネーター。
+
+#### 動作
+
+セレクターを順番に実行し、最初に`undefined`以外を返したセレクターの結果を使用します。
+
+#### 使用例
+
+```typescript
+import {
+  combineSelectors,
+  createModulerPromptApiSelector,
+  createSystemMessageBasedSelector
+} from '@modular-prompt/driver/mlx-ml/model-spec';
+
+const driver = new MlxDriver({
+  model: 'some-model',
+  modelSpec: {
+    customProcessor: {
+      determineApi: combineSelectors([
+        // 1. modular-promptパターンをチェック
+        createModulerPromptApiSelector(),
+        // 2. システムメッセージ数をチェック
+        createSystemMessageBasedSelector(3),
+        // 3. カスタムロジック
+        (context) => {
+          if (context.messages.length > 100) {
+            return 'completion';
+          }
+          return undefined;
+        }
+      ])
+    }
+  }
+});
+```
+
+---
+
+## ユースケース別の推奨設定
+
+### 1. modular-promptで使用する場合
+
+```typescript
+import { createModulerPromptApiSelector } from '@modular-prompt/driver/mlx-ml/model-spec';
+
+const driver = new MlxDriver({
+  model: 'gemma-2-2b-it-4bit',
+  modelSpec: {
+    customProcessor: {
+      determineApi: createModulerPromptApiSelector()
+    }
+  }
+});
+```
+
+### 2. chat APIを優先したいが、制限違反時はフォールバック
+
+```typescript
+const driver = new MlxDriver({
+  model: 'some-model',
+  modelSpec: {
+    apiStrategy: 'prefer-chat'
+  }
+});
+```
+
+### 3. 常にcompletion APIを使用
+
+```typescript
+const driver = new MlxDriver({
+  model: 'some-model',
+  modelSpec: {
+    apiStrategy: 'force-completion'
+  }
+});
+```
+
+### 4. 完全カスタムロジック
+
+```typescript
+const driver = new MlxDriver({
+  model: 'some-model',
+  modelSpec: {
+    customProcessor: {
+      determineApi: (context) => {
+        // 独自のロジック
+        const systemMessages = context.messages.filter(m => m.role === 'system');
+        const hasComplexPattern = systemMessages.length > 2;
+
+        if (hasComplexPattern && context.chatRestrictions?.singleSystemAtStart) {
+          return 'completion';
+        }
+
+        // デフォルトロジックに委譲
+        return undefined;
+      }
+    }
+  }
+});
+```
+
+---
+
+## トラブルシューティング
+
+### chat APIでエラーが発生する
+
+**症状**: 「システムメッセージが複数ある」などのエラー
+
+**原因**: chat制限に違反している
+
+**解決策**:
+1. `apiStrategy: 'force-completion'`を設定
+2. または`createModulerPromptApiSelector()`を使用
+
+### completion APIしか使われない
+
+**症状**: chat APIを使いたいのにcompletion APIが選択される
+
+**原因**: デフォルトロジックがchat制限を厳しいと判断
+
+**解決策**:
+1. `apiStrategy: 'prefer-chat'`を設定
+2. または`chatRestrictions: undefined`で制限をクリア
+
+---
+
+## 関連ドキュメント
+
+- [型定義](../src/mlx-ml/model-spec/types.ts)
+- [ヘルパー関数](../src/mlx-ml/model-spec/helpers.ts)
+- [ModelSpecManager](../src/mlx-ml/model-spec/manager.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modular-prompt/driver",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,8 +15,13 @@
     "scripts",
     "skills",
     "src/mlx-ml/python",
-    "src/pytorch/python"
+    "src/pytorch/templates",
+    "docs"
   ],
+  "bin": {
+    "modular-prompt-runtime": "./scripts/runtime-cli.js",
+    "modular-runtime": "./scripts/runtime-cli.js"
+  },
   "dependencies": {
     "@anthropic-ai/sdk": "0.61.0",
     "@anthropic-ai/vertex-sdk": "0.14.4",
@@ -54,7 +59,7 @@
     "directory": "packages/driver"
   },
   "scripts": {
-    "build": "tsc -b --force && cp src/runtime/paths-core.mjs src/runtime/manifest-core.mjs dist/runtime/",
+    "build": "tsc -b --force && cp src/runtime/paths-core.mjs src/runtime/manifest-core.mjs src/runtime/setup-commands-core.mjs src/runtime/pytorch-template-core.mjs dist/runtime/",
     "test": "vitest",
     "test:run": "vitest run",
     "test:system": "vitest run --config vitest.config.system.ts",
@@ -63,10 +68,12 @@
     "lint": "eslint src/**/*.ts",
     "typecheck": "tsc --noEmit",
     "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",
+    "clean": "rm -rf dist skills docs tsconfig.tsbuildinfo",
     "setup-mlx": "node scripts/runtime-cli.js setup mlx",
     "setup-pytorch": "node scripts/runtime-cli.js setup pytorch",
     "runtime:status": "node scripts/runtime-cli.js setup --status",
-    "runtime:cleanup": "node scripts/runtime-cli.js cleanup"
+    "runtime:sync-pytorch": "node scripts/runtime-cli.js sync pytorch",
+    "runtime:cleanup": "node scripts/runtime-cli.js cleanup",
+    "copy-docs": "node ../../scripts/copy-package-docs.mjs driver"
   }
 }

package/scripts/download-model.js

@@ -15,19 +15,20 @@ function runtimeModuleUrl(name) {
 }
 
 const { getMlxPythonDir, getVenvPath } = await import(runtimeModuleUrl('paths-core.mjs'));
+const { SETUP_MLX_MONOREPO } = await import(runtimeModuleUrl('setup-commands-core.mjs'));
 
 const targetDir = getMlxPythonDir(packageRoot);
 const venvPath = getVenvPath('mlx');
 
 if (!existsSync(targetDir)) {
   console.error('❌ MLX Python directory not found.');
-  console.error('   Please run "pnpm run setup-mlx -w @modular-prompt/driver" first.');
+  console.error(`   Please run "${SETUP_MLX_MONOREPO}" first.`);
   process.exit(1);
 }
 
 if (!existsSync(join(venvPath, 'bin', 'python'))) {
   console.error('❌ MLX runtime is not set up.');
-  console.error('   Please run "pnpm run setup-mlx -w @modular-prompt/driver" first.');
+  console.error(`   Please run "${SETUP_MLX_MONOREPO}" first.`);
   process.exit(1);
 }
 

package/scripts/runtime-cli.bin.test.ts

@@ -0,0 +1,142 @@
+import { execFileSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const temporaryDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+describe('runtime CLI bin', () => {
+  it('publishes modular-prompt-runtime in npm pack', () => {
+    const temporaryDirectory = mkdtempSync(
+      join(tmpdir(), 'modular-prompt-driver-pack-'),
+    );
+    temporaryDirectories.push(temporaryDirectory);
+
+    execFileSync(
+      'npm',
+      ['pack', '--ignore-scripts', '--pack-destination', temporaryDirectory],
+      {
+        cwd: packageRoot,
+        encoding: 'utf8',
+        env: {
+          ...process.env,
+          COREPACK_ENABLE_PROJECT_SPEC: '0',
+          npm_config_cache: join(temporaryDirectory, 'npm-cache'),
+        },
+      },
+    );
+
+    const tarballName = readdirSync(temporaryDirectory).find((name) =>
+      name.endsWith('.tgz'),
+    );
+    if (!tarballName) {
+      throw new Error('npm pack did not create a tarball');
+    }
+
+    const packedPackageJson = execFileSync(
+      'tar',
+      ['-xOf', join(temporaryDirectory, tarballName), 'package/package.json'],
+      { encoding: 'utf8' },
+    );
+    const { bin } = JSON.parse(packedPackageJson) as { bin: Record<string, string> };
+
+    expect(bin['modular-prompt-runtime']).toBe('./scripts/runtime-cli.js');
+
+    const archiveEntries = execFileSync(
+      'tar',
+      ['-tzf', join(temporaryDirectory, tarballName)],
+      { encoding: 'utf8' },
+    );
+    expect(archiveEntries).toContain('package/src/pytorch/templates/cpu-minimal/pyproject.toml');
+    expect(archiveEntries).toContain('package/src/pytorch/templates/cuda/pyproject.toml');
+    expect(archiveEntries).not.toContain('package/src/pytorch/python/');
+  });
+
+  it('documents modular-prompt-runtime in package.json', () => {
+    const packageJson = JSON.parse(
+      readFileSync(join(packageRoot, 'package.json'), 'utf8'),
+    ) as { bin: Record<string, string> };
+
+    expect(packageJson.bin['modular-prompt-runtime']).toBe('./scripts/runtime-cli.js');
+  });
+
+  it('smokes torch CUDA availability and reports runtime status details', () => {
+    const temporaryDirectory = mkdtempSync(
+      join(tmpdir(), 'modular-prompt-driver-status-'),
+    );
+    temporaryDirectories.push(temporaryDirectory);
+
+    const runtimeDir = join(temporaryDirectory, 'runtimes', 'pytorch');
+    const venvPythonDir = process.platform === 'win32' ? 'Scripts' : 'bin';
+    const venvPython = join(
+      runtimeDir,
+      '.venv',
+      venvPythonDir,
+      'python' + (process.platform === 'win32' ? '.exe' : ''),
+    );
+    mkdirSync(join(runtimeDir, '.venv', venvPythonDir), { recursive: true });
+    mkdirSync(join(runtimeDir, 'python'), { recursive: true });
+    if (process.platform === 'win32') {
+      writeFileSync(venvPython, '');
+    } else {
+      writeFileSync(
+        venvPython,
+        '#!/usr/bin/env node\n' +
+          'if (process.argv[2] !== "-c" || !process.argv[3].includes("import torch")) process.exit(2);\n' +
+          'console.log("false");\n',
+      );
+      chmodSync(venvPython, 0o755);
+    }
+    writeFileSync(join(runtimeDir, 'python', 'pyproject.toml'), '[project]\nname = "test"\n');
+    writeFileSync(join(runtimeDir, 'python', '__main__.py'), '');
+    writeFileSync(
+      join(runtimeDir, 'manifest.json'),
+      JSON.stringify({
+        profile: 'pytorch',
+        variant: 'cuda',
+        cudaVersion: '12.4',
+        driverVersion: '0.0.0',
+        platform: process.platform,
+        pythonVersion: '3.12',
+        createdAt: new Date().toISOString(),
+      }),
+    );
+
+    const output = execFileSync(
+      process.execPath,
+      [join(packageRoot, 'scripts', 'runtime-cli.js'), 'setup', '--status'],
+      {
+        encoding: 'utf8',
+        env: { ...process.env, MODULAR_PROMPT_HOME: temporaryDirectory },
+      },
+    );
+
+    expect(output).toContain('pytorch: ready');
+    expect(output).toContain('variant cuda');
+    expect(output).toContain('CUDA 12.4');
+    expect(output).toContain(
+      `CUDA: ${process.platform === 'win32' ? 'unknown' : 'unavailable'}`,
+    );
+    expect(output).toContain('driver version differs');
+    expect(output).toContain('modular-prompt-runtime sync pytorch');
+    expect(existsSync(join(runtimeDir, 'python', 'pyproject.toml'))).toBe(true);
+  });
+});