@modular-prompt/experiment

プロンプトモジュールの比較・評価フレームワーク。

インストール

npm install @modular-prompt/experiment

概要

複数のプロンプトモジュールを同一条件下で比較・評価する。YAML設定で実験を定義し、CLIで実行。

• プロンプト比較: 異なるプロンプト構造の効果を定量的に比較
• マルチモデルテスト: 異なるLLMプロバイダーでの動作比較
• 品質評価: 繰り返し実行による安定性・一貫性の評価
• 柔軟な評価器: コードベース・AIベースの評価をサポート

クイックスタート

1. 設定ファイルを作成

# experiment.yaml
models:
  gpt4o:
    provider: openai
    model: gpt-4o

drivers:
  openai:
    apiKey: ${OPENAI_API_KEY}

modules:
  - name: my-module
    path: ./my-module.ts

testCases:
  - name: 基本テスト
    input:
      query: "TypeScriptについて説明して"

evaluators: []

2. モジュールファイルを作成

// my-module.ts
import type { PromptModule } from '@modular-prompt/core';

const module: PromptModule<{ query: string }> = {
  objective: ['ユーザーの質問に回答する'],
  instructions: [
    (ctx) => `質問: ${ctx.query}`,
  ],
};

export default module;

3. 段階的な検証と実行

experiment 設定は、次の順で段階的に確認するのがおすすめです。

1. format — LLM/API キー不要。コンパイル済みプロンプトの中身を確認（§4）
2. --dry-run — 実行計画（モデル・モジュール・テストケースの組み合わせ）を確認
3. 本番実行 — 実際に LLM を呼び出して実験

npx modular-experiment format experiment.yaml              # 1. プロンプト確認
npx modular-experiment experiment.yaml --dry-run           # 2. 実行計画確認
npx modular-experiment experiment.yaml                     # 3. 本番実行
npx modular-experiment experiment.yaml --evaluate          # 評価付き
npx modular-experiment experiment.yaml --repeat 10         # 複数回実行

4. プロンプト整形（LLM 呼び出しなし）

experiment 設定からコンパイル済みプロンプトを整形出力する。API キーやモデル起動は不要。

# デフォルト（completion 形式）
npx modular-experiment format experiment.yaml

# テストケース・モジュールでフィルター
npx modular-experiment format experiment.yaml --test-case "基本テスト" --modules my-module

# 出力形式の切り替え
npx modular-experiment format experiment.yaml --format messages   # ChatMessage[] を JSON 出力
npx modular-experiment format experiment.yaml --format compiled   # CompiledPrompt を JSON 出力

# ファイル出力
npx modular-experiment format experiment.yaml --output prompts.txt --verbose

format サブコマンドのオプション

| オプション | 説明 | デフォルト | |-----------|------|-----------| | <config> | 設定ファイルパス（YAML / TypeScript） | （必須） | | --test-case <name> | テストケース名フィルター | all | | --modules <names> | カンマ区切りのモジュール名 | all | | --format <type> | 出力形式: completion, messages, compiled | completion | | --output <path> | 出力先ファイル（未指定時は stdout） | stdout | | --verbose | 詳細ログ出力 | false |

completion 出力例:

=== my-module / 基本テスト ===
# Instructions
...

messages / compiled: JSON 形式（複数の testCase × module は配列）

出力の挙動

format 実行時、メタ情報バナー（Prompt Format ヘッダー等）は stderr ではなく stdout に出力されます。

• stdout 出力時（--output 未指定）: バナーとプロンプト本文が stdout に混在します。パイプで後段に渡す場合はバナーが混入する点に注意してください
• --output 指定時: プロンプト本文のみファイルに書き出し、バナーと完了メッセージは stdout に残ります
• パイプでクリーンなプロンプトだけ欲しい場合は --output を使ってください

注意事項

• フィルター競合: CLI の --modules と設定ファイル内の testCase.modules が矛盾すると、エラーなく空出力になることがあります（実験 runner と同様）。意図した組み合わせになっているか確認してください
• 開発用ショートカット: リポジトリルートの pnpm run experiment / scripts/experiment.mjs は run-comparison.js を直叩きするため format サブコマンド非対応です。format を使う正本は package bin 経由の npx modular-experiment format <config>

CLIオプション（実験実行）

| オプション | 説明 | デフォルト | |-----------|------|-----------| | --test-case <name> | テストケース名フィルター（指定した名前のみ実行） | all | | --model <provider> | モデルプロバイダーフィルター（例: mlx, vertexai, googlegenai） | すべての有効なモデル | | --modules <names> | カンマ区切りのモジュール名（指定したモジュールのみテスト） | all | | --repeat <count> | 実行回数（統計的な評価に有用） | 1 | | --evaluate | AI評価器を有効化（評価フェーズを実行） | false | | --evaluators <names> | カンマ区切りの評価器名（指定した評価器のみ使用） | all | | --dry-run | 実行計画の表示のみ（実験を実行しない） | false | | --verbose | 詳細なログ出力（内部処理の表示） | false | | --log-file <path> | 詳細ログのJSONL出力先ファイルパス | なし | | --trace-dir <dir> | 構造化された実行ログの出力ディレクトリ（prefix/contextごとにファイル分割、summary.json付き） | なし | | --output <path> | 実験結果のJSON出力先ファイルパス（メタデータと結果を含む） | なし |

ログ・トレースオプション詳細:

• --log-file: 全実行ログをJSONL形式で1ファイルに出力。各行が1ログエントリ。
• --trace-dir: ログをprefix/context別にファイル分割して出力。summary.jsonに全体統計を含む。読みやすい形式（タイムスタンプ + レベル + メッセージ）。
• --output: 実験結果を構造化JSON形式で保存。タイムスタンプ、使用モデル、繰り返し回数などのメタデータを含む。

設定ファイルの詳細

モデル指定: DriverSet記法

テストケースの models フィールドでは、単一のモデル名（文字列）または役割別モデルのマッピング（オブジェクト）を指定できます。

単一モデル（文字列）

すべての役割で同じモデルを使用します。

testCases:
  - name: 基本テスト
    input:
      query: "質問内容"
    models:
      - gpt4o  # すべての役割でgpt4oを使用

DriverSet（役割別モデル）

役割ごとに異なるモデルを指定できます。default は必須で、他の役割（thinking、instruct、chat、plan）はオプションです。未指定の役割は自動的に default にフォールバックします。

models:
  gemma4:
    provider: mlx
    model: gemma4-26b-a4b
  qwen:
    provider: mlx
    model: qwen3.5-9b

testCases:
  - name: 役割別モデルテスト
    input:
      query: "質問内容"
    models:
      - default: gemma4     # 通常のタスクはgemma4
        thinking: qwen      # thinking役割はqwen

利用可能なModelRole:

• default: 必須。メインのモデル
• thinking: 推論タスク用（オプション）
• instruct: 指示実行用（オプション）
• chat: 対話用（オプション）
• plan: 計画立案用（オプション）

注記: 値には設定ファイルのトップレベル models: セクションで定義されたモデル名を指定します。

Skills (for Claude Code)

This package includes skills/experiment/SKILL.md. It can be used as a Claude Code skill to guide experiment framework usage.

License

MIT