AnnealBridge

AnnealBridge

English | 繁體中文

AI エージェント向けの組合せ最適化ミドルウェアです。 エージェントが最適化する対象を構造化 JSON で記述すると、AnnealBridge がそのエンコード方法と解法を決定し、すべての回答を元の問題と照合して検証したうえで、順位付けされた検証済みの解を MCP、CLI、または通常の Python 経由で返します。

flowchart LR
    U[Natural language] --> A[AI agent]
    A -->|OptimizationProblem JSON<br/>variables · objective · constraints| B
    subgraph B[AnnealBridge]
        direction LR
        V[validate] --> C[compile<br/>BQM / CQM] --> S[solve<br/>local or remote] --> R[re-validate against<br/>the original problem] --> K[rank]
    end
    B -->|SolveResult<br/>ranked, verified solutions| A
    A --> N[Natural-language answer]

クイックスタート

pip install annealbridge

0/1 ナップサック問題です。アイテムは4つ、容量は10で、価値を最大化します。ファイルは不要です。

from annealbridge.models import OptimizationProblem
from annealbridge.orchestration import OptimizationService

problem = OptimizationProblem.model_validate({
    "version": "1.0",
    "name": "knapsack",
    "variables": [{"name": n, "type": "binary"} for n in ["a", "b", "c", "d"]],
    "objective": {"direction": "maximize", "linear_terms": [
        {"variable": "a", "coefficient": 10}, {"variable": "b", "coefficient": 8},
        {"variable": "c", "coefficient": 7}, {"variable": "d", "coefficient": 6}]},
    "constraints": [{"id": "capacity", "type": "hard", "operator": "<=", "rhs": 10, "terms": [
        {"variable": "a", "coefficient": 6}, {"variable": "b", "coefficient": 5},
        {"variable": "c", "coefficient": 4}, {"variable": "d", "coefficient": 3}]}],
})

result = OptimizationService().solve(problem)
print(result.status)                        # success
print(result.solutions[0].variables)        # {'a': 1, 'b': 0, 'c': 1, 'd': 0}
print(result.solutions[0].objective_value)  # 17.0

ドメイン上のエラーは例外ではなく、結果として返されます。result.status の値は success、infeasible、invalid_problem、resource_limit_exceeded、backend_unavailable、configuration_error、solver_error のいずれかです。docs/output-format.md を参照してください。

オプションの追加機能：

pip install "annealbridge[mcp]"       # + MCP server (annealbridge-mcp)
pip install "annealbridge[dwave]"     # + D-Wave cloud backends
pip install "annealbridge[all]"       # everything
pip install "annealbridge[gpu]"       # + PyTorch, for simulated_bifurcation on CUDA

[gpu] は意図的に [all] に含まれていません。PyTorch は大容量のダウンロードが必要で、Windows では PyPI が配布するホイールが CPU 専用ビルドのため、CUDA を実行するにはまず PyTorch 独自のインデックスから torch をインストールする必要があります。詳しくは docs/backends.md を参照してください。

AI エージェントから使用する（MCP）

uv をインストールしたら、サーバーを claude_desktop_config.json（またはホストに相当する設定ファイル）に追加して、 ホストを再起動します。Claude Desktop、Claude Code、Codex がその設定を保存する場所は、 docs/mcp.md に記載されています。 初回起動時は、パッケージが uvx 専用のキャッシュ環境にダウンロードされます。この ダウンロードには numpy、dimod、dwave-samplers などが含まれ、数十秒かかることがあるため、 ホストの起動タイムアウトによってサーバーが切断状態と表示される場合があります。まず ターミナルで一度キャッシュを準備してください。

uvx --from "annealbridge[mcp]" annealbridge-mcp --version

環境を解決してバージョンを表示します。以降、ホストはそのキャッシュから起動します。

{
  "mcpServers": {
    "annealbridge": {
      "command": "uvx",
      "args": ["--from", "annealbridge[mcp]", "annealbridge-mcp"]
    }
  }
}

Claude Code では、次の1行で登録できます。

claude mcp add annealbridge -- uvx --from "annealbridge[mcp]" annealbridge-mcp

あとは通常のチャットで最適化できます。

あなた： 10 kgまで持てます。品目 A は価値が10で重さが6、B は価値が8で重さが5、 C は価値が7で重さが4、D は価値が6で重さが3です。どれを選べばよいですか？

返答の裏側では、エージェントがリクエストを問題 JSON として作成し、 solve_optimization を呼び出します。すべての解は元の制約に照らして再検証され、 網羅的な exact バックエンドでは optimality_proven: true が付与されます。サーバーが 拒否したドキュメントは、すべてのエラーとそれぞれの修正方法を含む invalid_problem として返され、エージェントは修正を適用して再送します。リモート バックエンドや大規模な問題を解く前には、まず validate_optimization_problem を呼び出すため、 ミスによるコストは発生しません。バックエンドの一覧や完全なスキーマが必要な場合は、 get_optimization_capabilities を呼び出します。

エージェント： A と C を選びます。合計価値は17で、重さはちょうど10 kgです。次点は A と D（16、重さ9 kg）と B と C（15、重さ9 kg）です。これが証明済みの最適解です。

表現はエージェントが作成しますが、数値はツールの結果です。別のツールである recommend_backend は、問題に適したバックエンドを順位付けして提案しますが、あくまで参考情報です。 バックエンドを指定しておらず、条件に合うローカルバックエンドが複数ある場合、サーバーの 指示に従ってエージェントは上位候補を表示し、どれを実行するかを尋ねます。エージェントが 代わりに選ぶことはありません。

ホストの入力メニューにプロンプトが表示される場合、pick_subset、assign、 schedule_shifts の3つのプロンプトを使うと、日常的な形式の問題ドキュメントをユーザー自身の 文章からエージェントが作成し、それを解くまでの手順を進められます。サーバーはリソースも 提供します。annealbridge://examples/ 以下の7つのサンプルドキュメントと、 annealbridge://schema にある完全な問題スキーマを利用できるため、エージェントは推測する代わりに、 完全なサンプルやスキーマそのものを読み込めます。

用途に適さないもの。 AnnealBridge は、連続（実数値）変数、非線形の目的関数、 非線形制約を扱いません。答えが最適であること、または実行可能な答えが存在しないことを証明できるのは exact のみです。デフォルトでは、コンパイル後の変数を最大24個（スラックビットを含む）まで 扱います。その他のローカルバックエンド（simulated_annealing、tabu、 simulated_bifurcation）はヒューリスティックであり、最良の答えが最適解とは限りません。 下記のバックエンド表と docs/limitations.md を参照してください。

stdio に対応するMCPホストであれば、どれも同じ方法で利用できます。streamable-http トランスポートも 利用でき、uvx の代わりに pipx や、絶対パスを指定した pip インストール済みサーバーも使えます。 uvx は初回実行時に解決した環境を再利用するため、既存のインストールに新しいリリースを反映するには、 uv cache clean annealbridge を実行してホストを再起動する必要があります。詳しくは docs/mcp.md を参照してください。

コマンドラインから使用する

以下の問題 JSONを knapsack.json として保存し、次を実行します。

annealbridge solve knapsack.json

Problem:   knapsack
Backend:   exact
Status:    success
Attempts:  1
Elapsed:   2.7 ms

Best solution (rank 1)
  objective (maximize):  17
  soft violation score:  0
  item_a = 1
  item_b = 0
  item_c = 1
  item_d = 0

Hard constraints: 1 / 1 satisfied
Soft constraints: 0 violations
Optimality proven: yes

Elapsed はサービス独自の実時間で、実行ごとに変わります。完全な SolveResult を表示するには --json を、バックエンドを上書きするには --backend simulated_annealing を追加してください。また、validate、recommend、capabilities、example、export-schema もお試しください。docs/cli.md をご覧ください。

問題 JSON

上記の MCP と CLI の例で使用したドキュメントであり、examples/knapsack.json の簡略版です。

{
  "version": "1.0",
  "name": "knapsack",
  "variables": [
    {"name": "item_a", "type": "binary"},
    {"name": "item_b", "type": "binary"},
    {"name": "item_c", "type": "binary"},
    {"name": "item_d", "type": "binary"}
  ],
  "objective": {
    "direction": "maximize",
    "linear_terms": [
      {"variable": "item_a", "coefficient": 10},
      {"variable": "item_b", "coefficient": 8},
      {"variable": "item_c", "coefficient": 7},
      {"variable": "item_d", "coefficient": 6}
    ]
  },
  "constraints": [
    {
      "id": "capacity",
      "type": "hard",
      "terms": [
        {"variable": "item_a", "coefficient": 6},
        {"variable": "item_b", "coefficient": 5},
        {"variable": "item_c", "coefficient": 4},
        {"variable": "item_d", "coefficient": 3}
      ],
      "operator": "<=",
      "rhs": 10
    }
  ],
  "solver": {"backend": "exact"}
}

整数変数（境界を指定した "type": "integer"、"version": "1.1"）、集合内の二値変数のうちちょうど k 個、最大 k 個、または最小 k 個を指定する基数制約（スラック変数なしでコンパイルするハードな最大 1 制約を含む。"cardinality_constraints"、"version": "1.2"）、インデックス集合上で大規模な規則的モデルを一度記述し、サーバーに展開させるテンプレート（"index_sets"、"parameters"、"variable_families" と *_templates リスト、"version": "1.3"）、二次目的関数項、重み付きソフト制約、バックエンドごとのソルバー設定については、docs/problem-format.md で説明しています。annealbridge export-schema は、エージェントが構造化出力に使用できる JSON Schema を出力します。

すぐに実行できるサンプルがリポジトリに 7 つあります — ナップサック、 割り当て、 TSP、 整数ナップサック、 シフトスケジューリング、 試験時間割 （基数制約）、および テンプレートを使った TSP （インデックス集合上で一度記述した TSP。annealbridge expand は展開後の内容を出力します）。 インストール済みパッケージにも同じファイルが含まれています。annealbridge example で一覧を表示し、annealbridge example knapsack > knapsack.json で保存できます（または annealbridge example knapsack | annealbridge solve - でそのままパイプに渡せます）。MCP サーバーは、同じ 7 つのドキュメントを annealbridge://examples/ 以下のリソースとして提供します。

仕組み

エージェントは OptimizationProblem を生成します。これは、バイナリ変数または上限・下限付き整数変数、線形または二次の目的関数、そしてハードまたはソフトの線形制約と基数制約で構成されます。それ以外は生成しません。次に AnnealBridge は、決定論的に以下を実行します。

1. テンプレートを明示的なエントリーに展開したうえで、問題を検証し、すべてのエラーを一度の処理で収集します。
2. ペナルティ、スラック、整数エンコーディングを自ら計算し、問題を BQM または CQM にコンパイルします。
3. ローカルまたはリモートのバックエンドで解きます。
4. ソルバーのエネルギーを決して信用せず、元の JSON に照らしてすべての候補を再検証します。
5. 実行可能解を順位付けし、制約ごとの評価とともに上位 K 件を返します。

オプトインの solver.postprocess ステップでは、順位付けの前に元の変数で最良のサンプルを修復し、局所的に改善することもできます。生成された結果は他の候補と同様に再検証され、各解の source で識別されます。任意の solver.wall_clock_limit_seconds を設定すると、ローカルのヒューリスティックバックエンドでの求解にかかる時間を制限できます。制限時間に達した場合、結果には完了済みの内容が含まれ、再検証と順位付けも行われたうえで、その旨が示されます（wall_clock_limit_reached）。MCP クライアントが求解をキャンセルすると、処理はそのまま実行され続けずに停止します。

エージェントが QUBO 行列、ペナルティ重み、スラック変数、整数エンコーディングを記述することはありません。また、すべてのステップは AI、ネットワーク、ベンダーアカウントなしでテストできます。

バックエンド

1 つのプロトコルの背後に 8 つのバックエンドがあります。

バックエンド	種類	パス	備考
exact	ローカル	BQM	すべての割り当てを列挙します。デフォルトではコンパイル済み変数が 24 個です
simulated_annealing	ローカル	BQM	ヒューリスティックです。汎用の選択肢で、小規模またはハード制約付きの問題では 3 つの中で最良です。num_reads、num_sweeps、seed に対応します
tabu	ローカル	BQM	ヒューリスティックなマルチスタート・タブーサーチで、密な QUBO に強いです。密な問題が大規模になった場合の第一候補です。num_reads、seed に対応します
simulated_bifurcation	ローカル	BQM	ヒューリスティックな密行列ダイナミクス（Goto et al. 2021）です。大規模な密な制約なし QUBO に適しており、ハード制約がペナルティにコンパイルされる問題では性能が劣ります。num_reads、num_sweeps、seed に対応し、[gpu] を使った CUDA にも対応します
dwave_qpu	リモート	BQM	EmbeddingComposite 経由の D-Wave 量子アニーラー
leap_hybrid_bqm	リモート	BQM	D-Wave Leap ハイブリッド BQM ソルバー
leap_hybrid_cqm	リモート	CQM	D-Wave Leap ハイブリッド CQM ソルバー。ネイティブ制約に対応します
fujitsu_da	リモート	BQM	Fujitsu Digital Annealer。HTTPS 経由の QUBO API V4 を使用し、SDK は不要です

リモートバックエンドには、ベンダーの認証情報と ANNEALBRIDGE_ALLOW_REMOTE=true の両方が必要です。両方がそろっていない場合は backend_unavailable を返します。annealbridge recommend は、問題を解かずにバックエンドを 順位付けし、指定されたバックエンドを変更することはありません。セットアップと バックエンドごとの動作については、docs/backends.md を参照してください。

設計上の保証

• 双方向のビジネスレベルの契約。 変数、目的、制約を入力し、制約ごとの評価を含むランキング済みの解を出力します。どちらの方向にもソルバーの内部実装は漏れません。
• 2つのコンパイル経路。 アニーラー向けの BQM（自動ペナルティ、バイナリスラック、エンコードされた整数）と、Leap ハイブリッド CQM ソルバー向けの CQM（ネイティブ制約と整数）です。バックエンドは、対応機能を宣言して選択されます。
• 内部を公開しない有界整数。 "version": "1.1" では、エンコーディングを隠したまま整数変数が追加されます。1.0 の動作はゴールデンテストで固定されています。
• 計数ルールをそのまま表現。 "version": "1.2" では、バイナリ変数に対するカーディナリティ制約（one-hot、最大 k 個、最小 k 個）が追加され、ハードな最大1個制約はスラック変数なしでペアワイズペナルティにコンパイルされます。1.0 と 1.1 の動作は互換性ゴールデンテストで固定されています。
• 大規模モデルを一度だけ記述。 "version": "1.3" では、インデックスセット、パラメータテーブル、変数ファミリー、テンプレートが追加されます。サーバーは、それ以外の処理を行う前に、これらを通常の変数、項、制約に展開します。エラーはテンプレートを示し、サイズ上限を超える場合は、展開結果を途中で切り捨てるのではなく、全体を拒否します。1.0～1.2 の動作は既存のゴールデンテストで固定されています。
• 例外ではなく、構造化された失敗。 すべての結果は status を持つ SolveResult です。すべての失敗には、安定したエラーコードと recommended_action が含まれます。infeasible は失敗ではなく、回答です。
• 暗黙の判断はありません。 利用できないバックエンドは報告され、別のバックエンドに切り替わることはありません。上限を超えるパラメータは拒否され、上限値に丸められることはありません。宣言されていないフィールドは拒否され、無視されることはありません。検証時の警告は、すべてのソルバー結果に付属します。
• デフォルトで安全。 リモート実行とリモート再試行は、有効化されるまでオフです。すべての上限は環境変数で設定され、超過するとエラーとして適用されます。ベンダーの認証情報は、結果、ログ、エラーメッセージから秘匿されます。streamable-http トランスポートには認証がありません。プライベートネットワーク上で使用してください。docs/security.md と SECURITY.md を参照してください。
• アーキテクチャをテストで強制。 インポート境界、「オーケストレーション、検証、インターフェース各レイヤーにバックエンド名を含めないこと」、「パイプラインに手を加えず新しいバックエンドを追加できること」は、慣習ではなくテストで保証されています。

ドキュメント

以下のページはdocs/にあります。

ページ	内容
docs/problem-format.md	入力 JSON：変数、目的関数、制約、ソルバーの設定
docs/output-format.md	SolveResult とそのすべてのフィールド
docs/errors.md	エラーカタログ、警告コード、理由コード、終了コード
docs/cli.md	annealbridge コマンドライン
docs/mcp.md	MCP サーバー：ツール、プロンプト、リソース、ホスト設定、Inspector
docs/backends.md	8 つのバックエンド、D-Wave と Fujitsu のセットアップ、バックエンドの追加
docs/configuration.md	すべての ANNEALBRIDGE_* 変数とベンダーの認証情報
docs/architecture.md	レイヤー、パッケージ構成、設計原則
docs/security.md	デフォルト設定、制限、認証情報のマスキング、ベンダーに送信される情報
docs/testing.md	テスト構成、ゴールデンテスト、実環境テスト、CI
docs/limitations.md	既知の制限と対象範囲外の項目

開発

git clone https://github.com/TheTsungYing/AnnealBridge.git
cd AnnealBridge
pip install -e ".[all,dev]"
pytest

pytest はスキップも xfail もなく、ネットワークにも一切アクセスせずに、すべてのテストを実行します。ベンダーの実環境テストはオプトインです（pytest -m remote）。チェックアウトせずに開発版をインストールするには、次を実行します。 pip install "annealbridge[all] @ git+https://github.com/TheTsungYing/AnnealBridge.git". アーキテクチャのルール、設計原則、プルリクエストのチェックリストについては、CONTRIBUTING.mdを参照してください。

バージョン 0.4.0 では、問題の仕様（1.0 / 1.1 / 1.2 / 1.3）、8 つのバックエンド、CLI、MCP ツールが完成し、テストでカバーされています。現時点で設計上サポートしていない項目はdocs/limitations.mdに、変更内容はCHANGELOG.mdに記載されています。

ライセンス

MIT