CompletionKit

プロンプトにもテストが必要です。

すべてのプロンプトを実データで実行します。定義した基準に照らして、LLM の判定者が各出力をスコアリングします。プロンプト、モデル、温度、データセットなど、何でも変更できます。再実行すれば、何が改善し、何が壊れたかを正確に確認できます。スコアから問題が分かると、CompletionKit は実行結果に対する判定者の実際のフィードバックに基づいて、改善したプロンプトを提案します。差分を確認し、新しいバージョンとして適用して、改善を検証できます。

「このプロンプトはうまく動いているようだ」と、「このプロンプトは200件の入力で5点満点中4.3点を獲得し、前バージョンの3.8点から上がった」の違いです。

completionkit.com で始める → | RubyGems

すぐに使いたいですか？ CompletionKit Cloud は同じエンジンを完全ホスト型で提供します。インストールも Rails の運用も不要です。プランはcompletionkit.com/pricingをご覧ください。

実行方法は3通り

エンジン、UI、REST API、MCP サーバーはどの方法でも同じです。用途に合ったデプロイ方法を選んでください。最初の2つはスタックに依存しません。CompletionKit を製品として実行し、独自アプリの言語にかかわらず、HTTP と MCP を通じて利用できます。3つ目は、すでに Rails で開発しているチーム向けです。

1. ホスト型 — completionkit.com（推奨）

最も手軽な方法です。サインアップすれば、Rails アプリに触れることなく、セルフホストする場合と同じエンジンを利用できます。db:migrate、Puma、Solid Queue、プロバイダーキーの管理は不要です。マルチテナントのワークスペースにチームでログインすれば、すぐに使い始められます。プランはcompletionkit.com/pricingをご覧ください。

2. セルフホスト — 同梱のスタンドアロンアプリ

自己管理のインフラで、単体の製品として実行できます。統合も Ruby での開発も不要です。起動したら、独自アプリのスタックを問わず、Web UI、REST API、MCP サーバーからすべてを操作できます。Postgres と、アプリを実行できるホスト（Fly、Render、Heroku、Docker など）が必要です。

git clone https://github.com/homemade-software-inc/completion-kit.git
cd completion-kit/standalone
bundle install
bin/rails completion_kit:install:migrations
bin/rails db:migrate

Web サーバーと Solid Queue ワーカーの両方を実行してください。2つのターミナルでそれぞれ実行します。

bin/rails server

bin/jobs

または、foremanを使って1つのターミナルで実行します：foreman start -f Procfile.dev。

http://localhost:3000 にアクセスします。プロバイダーの認証情報（Settings）を追加し、プロンプトを作成して、CSV データセットをアップロードし、実行します。本番環境の設定については、セルフホストのデプロイをご覧ください。

3. Rails エンジン — 既存の Rails アプリにマウントする

gem "completion-kit"

bin/rails generate completion_kit:install
bin/rails db:migrate

エンジンは /completion_kit にマウントされます。Generate／judge のフローでは Active Job のジョブ（CompletionKit::GenerateRowJob、CompletionKit::JudgeReviewJob、CompletionKit::RunCompletionCheckJob）がキューに登録されるため、ホストアプリには実際にジョブを処理する Active Job アダプター（Solid Queue、Sidekiq、GoodJob など）が必要です。:async アダプターは本番環境には適していません。永続性も再試行もなく、Web サーバーの Puma のスレッドプール内でジョブを実行するため、LLM の呼び出しが長引くとリクエスト処理がブロックされます。

ホストアプリのレイアウトとの統合。 ホストアプリでエンジンのレイアウトをオーバーライドする場合（エンジンのコントローラーで layout "application" を指定する場合や、エンジンのビューを独自のシェル内でレンダリングする場合など）は、そのレイアウトにエンジンのスタイルシートと JavaScript の両方を含めてください。

<%= stylesheet_link_tag "completion_kit/application", media: "all" %>
<%= javascript_include_tag "completion_kit/application", defer: true, nonce: true %>

JavaScript を含めないと、ページ内の動作が何も通知されずに機能しなくなります。対象となるのは、クリック可能なテーブル行、ダイアログ、コピーボタン、API トークンの表示、実行フォーム、実行状況のリアルタイム更新、タグのパンくずリストのリアルタイム更新、相対時刻の更新、CSV 行のホバー展開、モデル更新の進行状況、最初のエラーへのフォーカス、現地時刻へのフォーマットです。

コンテンツセキュリティポリシー。 エンジンのページにはインラインのイベントハンドラーやスクリプトがなく、エンジンのレイアウトではスクリプトタグにリクエストの nonce が設定されるため、nonce ベースの script-src を使ってもページは動作します。ビューでは引き続きインラインの style 属性を使うため、nonce ディレクティブから style-src を除外し、現時点では 'unsafe-inline' を許可してください。

リクエストごとに新しいランダム値を生成するのではなく、セッション全体を通して有効な nonce を使ってください。Turbo Drive は、新しいページ本文ごとに csp-nonce メタタグの nonce を使ってスクリプトを再生成しますが、ブラウザーは最初に読み込んだページのポリシーヘッダーを適用し続けます。そのため、リクエストごとに異なる nonce を使うと、最初の Drive 遷移以降、nonce 付きスクリプトがブロックされます。

以下の例のように、ランダムな nonce をセッションに保存し、API コントローラーでは nonce をスキップして、Cookie を使わない API や MCP の呼び出しにセッション Cookie が付かないようにしてください。Rails の既定値である ->(request) { request.session.id.to_s } もセッション全体で有効ですが、新規訪問者への最初のレスポンスでは空になります。そのため、nonce のみでスクリプトを許可するポリシーでは、セッションが作成されるまで最初のページのスクリプトがブロックされます。

Rails.application.configure do
  config.content_security_policy do |policy|
    policy.default_src :self
    policy.script_src  :self
    policy.style_src   :self, :unsafe_inline
  end

  config.content_security_policy_nonce_generator = lambda do |request|
    next if request.controller_instance.is_a?(ActionController::API)

    request.session[:csp_nonce] ||= SecureRandom.base64(16)
  end
  config.content_security_policy_nonce_directives = %w(script-src)
end

プロバイダー

CompletionKit は、各プロバイダーの API から利用可能なモデルを自動的に検出します。

プロバイダー	環境変数	対応範囲
OpenAI	OPENAI_API_KEY	GPT-5、GPT-4.1、GPT-4o など
Anthropic	ANTHROPIC_API_KEY	Claude Opus、Sonnet、Haiku
Ollama / ローカルエンドポイント	OLLAMA_API_ENDPOINT（デフォルト：http://localhost:11434/v1）、OLLAMA_API_KEY（任意）	ollama pull で取得した任意のモデル、または OpenAI 互換のローカルサーバー（vLLM、LM Studio、llama.cpp）
OpenRouter	OPENROUTER_API_KEY	1 つの API キーで、30 以上のプロバイダーの 100 以上のモデルを利用
Azure AI Foundry	環境変数なし — Providers UI または ProviderCredential で追加（api_key と api_endpoint は必須、api_version は任意）	Azure OpenAI のデプロイメントと Foundry プロジェクト

これらは環境変数として設定するか、生成されたイニシャライザーで設定してください。Web UI の Settings からプロバイダーの認証情報を追加することもできます。

OLLAMA_API_KEY または config.ollama_api_key の Ollama キーは、OLLAMA_API_ENDPOINT または config.ollama_api_endpoint で指定した Ollama エンドポイントにのみ送信されます。どちらも設定されておらず、デフォルトで有効な config.allow_loopback_endpoints がオンの場合は、http://localhost:11434/v1 に送信されます。独自のキーがないプロバイダー認証情報には、同じエンドポイントを指定している場合に限り、このキーが渡されます。それ以外のエンドポイントを指定すると、CompletionKit はキーを送信しないため、認証情報自体にキーを保存してください。認証情報に保存されたキーは、常にその認証情報のエンドポイントに送信されます。2 つのエンドポイントは、スキーム、ホスト、ポート、パスが一致する場合に同一とみなされます。スキームとホストの大文字・小文字、明示されたデフォルトポート、末尾のスラッシュ、末尾の /v1 は一致判定に影響しません。保存されたキーが空白の場合、キーなしとして扱われます。

暗号化

プロバイダーの API キーは、Active Record encryption を使用して保存時に暗号化されます。本番環境でアプリを起動する前に、3 つの暗号化キーを設定する必要があります。

次のコマンドで生成します。

bin/rails db:encryption:init

次に、環境変数として設定します。

COMPLETION_KIT_ENCRYPTION_PRIMARY_KEY=<generated value>
COMPLETION_KIT_ENCRYPTION_DETERMINISTIC_KEY=<generated value>
COMPLETION_KIT_ENCRYPTION_KEY_DERIVATION_SALT=<generated value>

または、config/credentials.yml.enc の active_record_encryption 配下に追加します。開発環境では、スタンドアロンアプリが組み込みのフォールバック値を使用するため、ローカルではこの手順を省略できます。

認証

CompletionKit は、デプロイされたすべての環境で認証を必要とします。開発環境とテスト環境では、デフォルトでルートが公開されています（ログに警告が記録されます）。それ以外の環境では、認証が設定されていないと 403 が返されます。

Basic Auth（シンプルな構成におすすめ）

CompletionKit.configure do |c|
  c.username = "admin"
  c.password = ENV["COMPLETION_KIT_PASSWORD"]
end

カスタム認証（Devise など）

CompletionKit.configure do |c|
  c.auth_strategy = ->(controller) { controller.authenticate_user! }
end

有効にできるモードは 1 つだけです。

レビュアー名

Web UI でジャッジのスコアに判定を記録すると、CompletionKit はレビュアー名を付けて保存します。各レビュアーは、レスポンスとメトリクスの組み合わせごとに判定を 1 つ保持するため、各ユーザーに個別の名前を設定してください。そうしないと、判定が互いに上書きされます。current_reviewer に、コントローラーを受け取り、サインイン中のユーザー名を返す呼び出し可能オブジェクトを設定します。

CompletionKit.configure do |c|
  c.auth_strategy = ->(controller) { controller.authenticate_user! }
  c.current_reviewer = ->(controller) { controller.current_user&.email }
end

この呼び出し可能オブジェクトは、String または nil を返す必要があります。ユーザーレコードなど、それ以外の値を返すと CompletionKit::ConfigurationError が発生します。current_reviewer が未設定の場合、または空の値を返す場合、判定は username で保存されます。username が設定されていない場合は "operator" で保存されます。Web UI は X-Remote-User ヘッダーを自動では読み取りません。アプリの前段にあるプロキシがこのヘッダーを設定する場合は、次のように渡してください。

CompletionKit.configure do |c|
  c.current_reviewer = ->(controller) { controller.request.headers["X-Remote-User"] }
end

信頼できるプロキシが常にこのヘッダーを上書きする場合に限り、使用してください。そうでない場合、任意のクライアントがこのヘッダーを送信して、任意のレビュアー名を名乗ることができます。

REST API と MCP サーバーでは、それぞれの created_by パラメーターからレビュアー名を取得します。

レート制限

REST API、MCP エンドポイント、Web UI には、IP アドレスごとに 1 分間のレート制限が適用されます。デフォルトの制限値は余裕を持たせてあります。イニシャライザーで調整してください。

CompletionKit.configure do |c|
  c.api_rate_limit = 120  # REST API + MCP, requests per minute (default 120)
  c.web_rate_limit = 300  # web UI, requests per minute (default 300)
end

制限には Rails.cache を使用します。共有キャッシュストア（Solid Cache、Redis）は、複数のアプリインスタンス間で正確に制限できます。プロセスごとのストアでも、各インスタンスで個別に制限されます。

入力制限

アップロード、プロンプトテンプレート、正規表現のチェックパターンには制限があり、大きな入力や悪意のある入力によってワーカーが占有されないようにします。初期化子で調整してください：

CompletionKit.configure do |c|
  c.max_upload_bytes = 25 * 1024 * 1024  # largest dataset CSV or import file (default 25 MB)
  c.max_template_bytes = 1024 * 1024     # largest prompt template (default 1 MB)
  c.regex_timeout = 1.0                  # seconds a regex check may spend matching one row (default 1.0)
end

テンプレートが max_template_bytes を超えるプロンプトは、テンプレートの保存時に検証に失敗します。上限を引き下げる前に保存されたプロンプトは、テンプレートを変更するまでは引き続き使用できます。

データセットの CSV の先頭行はヘッダー行です。ヘッダー行が空、または 64 KB を超える CSV を保存しようとすると、データセットの検証に失敗します。64 KB の上限は固定で、設定では変更できません。

また、UTF-8 として無効なバイト列を含む CSV を保存しようとすると、データセットの検証に失敗します。スプレッドシートは UTF-8 の CSV としてエクスポートしてください。

時間制限を超えて実行される正規表現チェックは、その行で失敗し、タイムアウトしたことを示します。制限は regex_timeout と、より短い場合はアプリの Regexp.timeout のいずれかです。そのため、エンジンがアプリで設定したより厳しい制限を緩和することはありません。エンジンは各パターンに制限を設定し、プロセス全体の Regexp.timeout は変更しません。regex_timeout には 0.001 秒以上の有限値を設定するか、nil を指定して Regexp.timeout のみを使用してください。0 や Float::INFINITY など、それ以外の値を指定すると、初期化子の実行時に ArgumentError が発生します。

仕組み

これは繰り返しのプロセスです。実行するたびに、前回の結果と比較できるスコアが得られます。

1. プロンプトを作成します。 {{variable}} プレースホルダーを使用します。
2. データセットをアップロードします。 列ヘッダーが変数名と一致する CSV を使用します。
3. モデルに対して実行し、 定義した基準に照らして LLM ジャッジで出力を採点します。
4. 反復します。 プロンプト、モデル、温度、またはデータセットを変更して再実行します。CompletionKit はプロンプトのバージョンを管理するため、以前の結果といつでも比較できます。
5. 提案を取得します。 スコアが下がった場合は、CompletionKit に AI 生成の改善案を依頼できます。提案は一般的なプロンプトエンジニアリングのアドバイスではなく、ジャッジによる各応答への実際のフィードバックに基づいています。差分を確認し、新しいバージョンとして適用してください。

概念

• プロンプト。 {{variable}} プレースホルダーを含む、バージョン管理されたテンプレートです。実行済みのプロンプトを編集すると新しいバージョンが作成されるため、以前の結果を再現できます。
• データセット。 実際の入力を含む CSV です。各行が 1 つのテストケースになります。
• 実行。 データセットに対してプロンプトを 1 回実行したものです。すべての入力（モデル、温度、メトリクス）を記録し、すべての出力とスコアを保存します。
• 応答。 データセットの 1 行に対するモデルの出力で、レビューが紐付けられます。
• メトリクス。 名前、指示、評価手順、1〜5 つ星の採点尺度を持つ評価軸です。LLM ジャッジはこれを使って各応答を採点します。
• メトリクスグループ。 実行にまとめて適用できる、再利用可能なメトリクスのグループです。
• タグ。 プロンプト、実行、メトリクス、データセットに付与できる領域ラベルです。10 色のパレットから自動的に割り当てられます。各一覧ページをタグで絞り込めます（?tag[]=...）。
• プロバイダー認証情報。 モデルプロバイダーの API キーです。保存時に暗号化され、API 経由で返されることはありません。

REST API

すべてのリソースには、ベアラートークンを使った JSON API 経由でアクセスできます：

CompletionKit.configure { |c| c.api_token = ENV["COMPLETION_KIT_API_TOKEN"] }

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/completion_kit/api/v1/prompts

実行中のアプリで /completion_kit/api_reference を開くと、クリップボードにコピーできる curl の例を含む、エンドポイントごとのドキュメントを確認できます。

MCP サーバー

CompletionKit は /completion_kit/mcp で Model Context Protocol サーバーを実行し、すべてのリソースをツールとして公開します。MCP 対応クライアント（Claude Code、Cursor など）から直接操作できます：

{
  "mcpServers": {
    "completion-kit": {
      "url": "https://your-app.com/completion_kit/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

アプリ内の API リファレンスページには、MCP クライアントの設定にそのままコピーできるインストール用スニペットがあります。

セルフホストでのデプロイ

Rails に対応したホストであれば、どれでも使用できます（Fly、Heroku、Render、Docker など）。DATABASE_URL を使って Postgres インスタンスを指定し、プロバイダーの環境変数を設定したうえで、デプロイごとに cd standalone && bin/rails db:migrate を実行します。

変数	用途	デフォルト
COMPLETION_KIT_API_TOKEN	REST API と MCP 用の Bearer トークン	（なし、API は無効）
COMPLETION_KIT_USERNAME	Web UI のログインユーザー名	admin
COMPLETION_KIT_PASSWORD	Web UI のログインパスワード	（なし、開発環境では認証なし）

上記の暗号化のセクションにある COMPLETION_KIT_ENCRYPTION_* の3つのキーも必要です。

gem に新しいマイグレーションが追加されたら、ローカルにインストールしてコミットしてからプッシュします。

cd standalone
bin/rails completion_kit:install:migrations
bin/rails db:migrate
git add db/migrate/ && git commit -m "install new engine migration"

Docker

スタンドアロンアプリには Dockerfile が含まれているため、ホストに Ruby ツールチェーンがなくてもセルフホストできます。ビルド時のコンテキストにはリポジトリのルートを指定してください。アプリは隣接するエンジンのソースに依存しています。

docker build -f standalone/Dockerfile -t completion-kit .

CompletionKit には Rails のシークレット（SECRET_KEY_BASE）と Active Record の暗号化キーが3つ必要です。Docker ではホストに Rails ツールチェーンがなく、bin/rails db:encryption:init を実行できないため、openssl で生成します。これらは一度だけ生成し、値を変更しないでください。暗号化キーを変更すると、データベースに保存済みのプロバイダー認証情報を復号できなくなります。以下の内容をすべて環境変数ファイルに書き込みます。

cat > completion-kit.env <<EOF
DATABASE_URL=postgres://user:pass@host/completionkit
SECRET_KEY_BASE=$(openssl rand -hex 64)
COMPLETION_KIT_ENCRYPTION_PRIMARY_KEY=$(openssl rand -hex 32)
COMPLETION_KIT_ENCRYPTION_DETERMINISTIC_KEY=$(openssl rand -hex 32)
COMPLETION_KIT_ENCRYPTION_KEY_DERIVATION_SALT=$(openssl rand -hex 32)
EOF

ファイルへの書き込み時に openssl rand が実行されるため、各行には実際のランダムな値が設定されます。completion-kit.env はバージョン管理の対象から除外し、安全な場所にバックアップしてください。

同じイメージから Web プロセスとジョブワーカーを起動し、どちらもそのファイルを指定します。

docker run -d -p 3000:3000 --env-file completion-kit.env completion-kit
docker run -d --env-file completion-kit.env completion-kit ./bin/jobs

両方のプロセスで同じ SECRET_KEY_BASE と暗号化キーを共有する必要があります。単一の環境変数ファイルを使えば、これらを確実に共有できます。Web コンテナーは起動時に db:prepare を実行するため、初回起動時とデプロイのたびにマイグレーションが適用されます。

マルチテナントのホストアプリ（上級者向け）

CompletionKit をマルチテナントアプリに組み込むホスト向けに、エンジンをフォークせずに、2 つのオプションのフックでテナントごとにエンジンのレコードをスコープできます。

CompletionKit.configure do |config|
  config.tenant_scope = -> {
    org = Current.organization&.id
    org ? where(organization_id: org) : where("1=0")
  }
  config.tenant_scope_columns = [:organization_id]
end

tenant_scope は各エンジンモデルの default_scope として実行されます（回避するには unscoped を使用します）。tenant_scope_columns は、エンジンの一意性検証すべてに追加されます。テナント列と複合一意インデックスの追加は、ホスト側のマイグレーションで行います。どちらもデフォルト（nil、[]）では何も行いません。completion_kit:mark_interrupted_runs_failed rake タスクは tenant_scope を回避し、すべてのテナントの実行中の Run を失敗としてマークします。そのため、行レベルセキュリティなど、データベースでもテナンシーを適用するホストは、すべてのテナントの行を参照できるデータベースロールでこのタスクを実行する必要があります。

カスタムモデルのエンドポイントや URL 経由の CSV インポートは、デフォルトでサーバー自身のループバックインターフェースにアクセスできるため、ローカルの Ollama はそのまま動作します。エンジンの利用者がアプリサーバー自体のサービスにアクセスできないようにするには、config.allow_loopback_endpoints = false を設定してください。プライベートアドレス、リンクローカルアドレス、および予約済みアドレスは常に拒否されます。

コントローラーやビューをオーバーライドせずに、エンジンが実行一覧の表示、件数の集計、または実行の参照を行う場所すべてにホスト独自の表示ルールを適用できるフックが用意されています。

CompletionKit.configure do |config|
  config.runs_display_scope = -> { where(created_at: 90.days.ago..) }
  config.runs_display_footer_partial = "runs/display_notice"
end

runs_display_scope は Run リレーションに対して評価される呼び出し可能オブジェクトで、tenant_scope と同じく、単独の where を使うスタイルです（instance_exec 経由で実行されるため、Rails の scope ラムダのように、リレーションを self とする引数なしで記述します）。リレーションを返す必要があります。nil やチェーン不可の値を返す呼び出し可能オブジェクトは、一覧のレンダリング時にエラーになります。エンジンは、所有するすべての実行一覧および件数（実行インデックス、プロンプトとデータセットの詳細ページ、比較用ピッカー、新規実行のタグのデフォルト値、v1 API インデックスとその X-Total-Count、MCP の runs_list ツール、ダッシュボードと API リファレンスの最近の実行パネル、ダッシュボードの「Runs」統計カードの件数、プロバイダー認証情報の使用統計）に対して Run.display_scoped を通じて適用します。また、実行をたどる子レコード（メトリックの信頼性パネルのサンプルと、メトリックページに表示される合意の例）には Run.visible_run_ids を通じて適用します。グローバルな default_scope を設定すると、Run の関連付けをたどるすべての場所で影響が生じるため、一覧だけに適用する表示ルールにはこのフックを使用してください。

意図的に対象外としているものがあります。これらはすべての実行を引き続き参照する必要があるためです。ID を指定した単一実行の検索（runs#show、MCP の runs_get ツール、v1 API の show）、削除確認時のカスケード件数、実行名の自動生成に使うカウンター、ダッシュボードの統計カードの表示条件（スコープによってすべての実行が除外されるワークスペースでも、空のダッシュボードではなくアクティビティカードが表示されるよう、スコープ外の実行総数を基準にします）、および表示スコープで除外される実行で修正済みの例からも学習する、ジャッジの few-shot シードです。

runs_display_footer_partial は、ダッシュボード、インデックス、およびプロンプトとデータセットの詳細ページで実行一覧の下にレンダリングされるパーシャルを指定します。表示された実行は runs ローカルとして渡されます。表示スコープにより、いずれかの画面で一覧に表示する実行がすべて除外されると、その画面には「表示する実行はありません。」と表示され、その下にフッターのパーシャルがレンダリングされます。エンジンは、スコープが実行を除外する理由を把握できないため、パーシャルを使って表示ルールを説明してください。そのルールはホストが runs_display_scope で定義するものであり、除外された内容を説明したり、その件数を数えたりできるのはホスト側だけです。どちらもデフォルトは nil（何もしない）であり、スタンドアロンでの動作は変わりません。

コントリビューション

開発環境のセットアップ、テスト、およびプルリクエストのガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

CompletionKit 0.3.0 以降は、Business Source License 1.1 のライセンスが適用されます。CompletionKit 自体が主な価値となるホステッドサービスまたはマネージドサービスとして、CompletionKit（またはその派生物）を第三者に提供する場合を除き、本番環境での使用を含め、あらゆる目的で自由に使用できます。各リリースから 3 年後、そのバージョンは自動的に GPL-3 に再ライセンスされます。

CompletionKit 0.2.x 以前は、引き続き MIT License のもとで利用できます。

別のライセンスについては、[email protected] までお問い合わせください。