optlens

optlens

LP および MILP モデル向けの、ソルバーに依存しないデバッガー兼解説ツールです。実行不可能なモデルや、解が信頼できないモデルを渡すと、optlens は競合する制約、それを解消するために必要な最小限の変更、および各変更のコストを特定します。結果はすべて、エージェントや人が読めるテキストで出力されます。自分の Python から、プラグイン経由で Claude Code から、または任意の MCP クライアントから利用できます。

optlens は、すでに構築済みのモデルを対象に動作します。モデルの作成は行いません。

ウェブサイト：optlens.dev

インストール

Python 3.12 以降：

pip install "optlens[scip,mcp]"   # core: numpy, scipy, HiGHS

以下のクイックスタートを実行するか、テストを実行するには、リポジトリをクローンして、そのクローンからインストールします （git clone https://github.com/jjd-lab/optlens && cd optlens && pip install ".[scip,mcp]"）。

プロキシや VPN の背後など、GitHub に接続できないネットワークもあります。その場合は、リポジトリの ZIP などを使って、別の方法でソースをコピーしてください。pip install "<folder>[scip,mcp]" でインストールし、claude plugin marketplace add <folder> で Claude Code プラグインを追加します。

extra	追加されるもの
scip	SCIP（pyscipopt）：ネイティブの MIP IIS を備えた、2 つ目のオープンソースソルバー
gurobi	gurobipy：Gurobi。ライセンスは各自で用意してください。バージョンは使用する Gurobi と一致している必要があります。Compute Server またはトークンサーバーは、新しいクライアントを拒否します（「No compatible runtime available」）。そのため、たとえば pip install "gurobipy==12.*" で、そのメジャーバージョンをインストールしてください。open_model で、インストールされている gurobipy のバージョンを確認できます。
pyomo, pulp	Pyomo および PuLP のモデルを読み込みます
mcp	MCP サーバー optlens-mcp および Claude Code プラグイン

クイックスタート

import optlens as od
from optlens.session import Session, Version

if __name__ == "__main__":  # solves run in worker processes, which start by re-importing this script
    md = od.load("tests/fixtures/ex_milp_tutorial__rhs_tighten__0.mps")  # LP or MPS
    s = Session({"v0": Version(md, None, "original model")})
    print(s.get_model_overview())   # size, status (here INFEASIBLE), constraint families
    print(s.compute_iis())          # the conflicting constraints, grouped by family
    print(s.fix_menu())             # the smallest change per family that restores feasibility
    print(s.modify_and_resolve(changes=[{"action": "set_rhs", "name": "resource[Monika]", "upper": 1}]))

ファイルに保存し、リポジトリのルートから実行します。ソルバーを実行するスクリプトには、必ず if __name__ == "__main__": ガードを残してください。ソルバーはワーカープロセスで実行されます。Windows では spawn でプロセスが起動し、それぞれのプロセスがスクリプトを再インポートします。ガードがないと、各ソルバープロセスでスクリプトが再実行されます。

すべての Session メソッドはテキストを返し、optlens.session.TOOLS にはエージェント向けの対応する JSON スキーマが格納されています。セッションでは、実行可能性緩和、バージョンとしての what-if 編集、理由を尋ねる質問、感度と限界値、疑わしいデータ値、バージョン間またはモデル間の比較も扱えます。

Pyomo、gurobipy、PuLP で構築されたモデルは、オブジェクトから、またはモデルを構築するファイルから直接読み込めます。optlens は、ファイル内の if __name__ == "__main__": ブロックを実行せず、最初の求解呼び出し（optimize()、solve()）で処理を停止します。その呼び出しのモデルを読み込みます。求解は行われないため、大規模な gurobipy モデルも、サイズ制限のある Gurobi ライセンスで読み込めます。

md = od.from_object(model)                      # a Pyomo ConcreteModel, gurobipy Model or PuLP LpProblem
md = od.load("my_model.py")                     # the model it solves, else its one model or build_model()
md = od.load("my_model.py:make_scenario")       # a named model, or a function with no arguments that returns one

Gurobi が書き出した LP ファイル（HiGHS が拒否する角括弧付きの名前）も、gurobipy なしで読み込めます。

optlens は二次目的関数（QP、MIQP）をサポートしています。凸 QP は HiGHS で求解されます。混合整数または非凸のモデルは、optlens が自動的に SCIP に送ります。感度範囲を除き、線形モデルと同じ質問をすべて行えます。目的関数が非凸の場合、シャドープライスも利用できません。optlens は、モデルの読み込み時に二次制約、指示制約などの一般制約、および SOS を拒否します。optlens.dev/ask には、質問、形式、ソルバーの一覧が掲載されています。

ソルバー

HiGHS はコアに含まれており、SCIP と Gurobi は追加で利用できます。OPTLENS_SOLVER（highs、scip、gurobi、またはデフォルトの auto）、MCP サーバーの open_model の solver、または Session(..., prefer=...) で選択してください。Gurobi を使わない auto の場合、モデルごとに HiGHS または SCIP が使われます。より大きな MIP の初回の求解では、両方を並行して実行します。

• すべての求解には厳格な時間制限があります。 ソルバーが独自の制限を常に守るとは限りません。SCIP はかつて、30 秒の制限に対して 862 秒実行されました。そのため、各求解はワーカープロセスで実行され、optlens は制限時間に達するとプロセスを停止します。
• Gurobi はすべてのステップを自ら実行します。 Gurobi セッションは、求解、IIS の計算、緩和、レンジ計算、チェックをすべて Gurobi 上で行います。ほかのソルバーにステップを任せることはありません。Gurobi を選択していて、インストールされていない、またはモデルがサイズ制限付きライセンスの上限を超えているためモデルを実行できない場合、ツールはソルバーを切り替えるのではなく、停止してその理由を伝えます。 auto の場合、ここで Gurobi を実行できれば optlens は Gurobi を使います。これは、1 変数の求解を一度行って確認します。利用可能なライセンスがないインストール済みの gurobipy や、ライセンスサーバーに拒否されるバージョンは対象外となり、open_model がその理由を示します。Gurobi で実行できないモデルの場合は、HiGHS または SCIP に切り替え、その旨を伝えます。
• HiGHS と SCIP は互いに補完します。 これは、一方だけがあるステップを実行できる場合に起こります。HiGHS には MIP IIS がありませんが、SCIP にはあります。また、一方が制限時間内に判定結果を出せない場合は、もう一方が一度だけ試します。結果には、そのステップを実行したソルバーが記載されます。
• すべての IIS を検証します。 ソルバーが返す IIS に、単独では実行可能な制約が含まれることがあります。optlens はその IIS を棄却し、制約を一つずつ取り除いて、同じソルバー上で再構築します。これは、既知の gurobipy 13.0.3 のバグへの対策です。computeIIS は、端数の上限値を丸めると 0 になるバイナリ変数の 1 変数行を除外します。たとえば、open >= 1 のとき、160 open <= 100 では実行可能な open >= 1 だけが返されます。
• Gurobi は小規模モデルと大規模モデル一つでテスト済みです。 大規模モデルは 279k 行のホテルモデルで、求解、感度分析、IIS、緩和、修復メニューをテストしています。ほかの大規模モデルはテストされていません。報告を歓迎します。

数十万の制約を持つ大規模モデルでは、IIS の探索は矛盾箇所の近くから始まります。モデル全体を探索するのではなく、HiGHS が示す実行不可能性の証明を起点にします。

エージェントで使う

上記の手順でインストールすると、optlens-mcp が PATH に追加されます。その後、一度接続します。エージェントは24個のツールと、それらを使う方法を得ます。まずモデルを開き、原因から説明し、すべての数値を solve から取得し、修正を推奨する前に再度 solve します。

エージェント	接続方法
Claude Code	claude plugin marketplace add jjd-lab/optlens の後に claude plugin install optlens@optlens を実行します（または、セッション内で同じ内容を /plugin コマンドとして実行します）
Codex CLI	codex mcp add optlens -- optlens-mcp
Cursor	.cursor/mcp.json（または ~/.cursor/mcp.json）に設定します：{"mcpServers": {"optlens": {"command": "optlens-mcp"}}}
VS Code (Copilot)	.vscode/mcp.json に設定します：{"servers": {"optlens": {"type": "stdio", "command": "optlens-mcp"}}}
Claude Desktop	claude_desktop_config.json（Settings > Developer > Edit Config）に設定します：{"mcpServers": {"optlens": {"command": "optlens-mcp"}}}
その他の MCP クライアント	optlens-mcp を stdio サーバーとして実行します

コマンドは、エージェントから参照できる PATH 上にある必要があります。そうでない場合は、optlens-mcp のフルパスを指定してください。例：.venv/bin/optlens-mcp。OPTLENS_SOLVER（highs、scip、gurobi または auto）で、使用するソルバーを選択します。

時間制限。 solve は45秒で停止するため、呼び出しは1分以内に応答します。OPTLENS_CALL_LIMIT（秒単位、30以上）は、1回のツール呼び出しにかけられる最大時間です。ツールの time_limit には、その時間より最大15秒短い時間を指定できます。エージェントがさらに時間を求めるのは、solve が制限時間に達した時点でも改善中だった場合のみです。結果には、改善中だったかどうかが示されます。制限時間は、クライアントが1回のツール呼び出しを待つ時間に合わせて設定してください。open_model は適用中の制限時間を示し、制限時間により途中で終了した結果にはその旨が記載されます。

クライアント	ツール呼び出しの待ち時間	OPTLENS_CALL_LIMIT
Claude Code（プラグイン）	10分。プラグインにより設定されます（2分を超える呼び出しはバックグラウンドに移行します）	110。プラグインにより設定されます
Claude Code（claude mcp add）	MCP_TOOL_TIMEOUT（設定しない場合は約28時間。一部の環境では60秒に設定されています）	設定しない場合は60。さらに長くするには、サーバーのエントリーに "timeout": 600000 を追加し、110を設定します
Claude Desktop、MCP TypeScript SDK クライアント	60秒	60（デフォルト）
その他のクライアント	クライアントの設定を確認してください	クライアントがより長い時間を許可しない限り60

大規模な MIP は、これらの制限時間内に完了しないことがあります。その場合、結果には見つかった計画、その境界値、ギャップが報告されます。

次に、*「plan.mps が実行不可能なのはなぜですか？また、何を修正すればよいですか？」*と尋ねます。エージェントはモデルを開き、そのコンテキストを一度作成します。コンテキストには、各制約と変数ファミリーが何を意味するかが記載されます。これは .optlens/context/ 内の JSON で、確認してコミットできます。その後、エージェントはツールを使って作業を進めます。複数の手順を踏む場合や、多くの solve を実行する場合は、run_python を使います。これは、エンジンが session として事前に読み込まれ、モデルが一度だけ読み込まれる、永続的な Python プロセスです。

Claude Code プラグインは同じサーバーに、サーバーの手法を案内する短いスキルを追加したものです（plugin/README.md）。

セキュリティ。 optlens はお使いのマシン上で、お客様の権限を使ってコードを実行し、サンドボックスはありません。run_python はエージェントが記述したコードを実行します。プロセスは API キーやトークンなしで開始しますが、お客様のユーザーが読み書きできるものにはすべてアクセスできます。Claude Code では、呼び出しごとに承認します。.py モデルを開くと、最初の solve 呼び出しまでそのファイルが実行されます。信頼できるモデルとコードのみを開いてください。脆弱性を報告するには、SECURITY.md を参照してください。

試してみる

お使いの Claude Code の設定に手を加えずにプラグインを試すには、専用のフォルダーにクリーンな環境を構築します。このフォルダーには、GitHub から取得した optlens を含む専用の venv と、optlens プラグインだけを含む専用の Claude 設定が作成されます。また、データの読み込みに失敗したホテルの1週間分のデータ （packs/hotel/examples/try_week） も用意されており、質問を5つ尋ねられます。

git clone https://github.com/jjd-lab/optlens && optlens/scripts/sandbox.sh ~/optlens-try
~/optlens-try/start.sh          # log in on the first start; the questions are in ~/optlens-try/HOW-TO.md

macOS または Linux で、bash、Python 3.12 以降、Claude Code が必要です。Windows では、WSL または plugin/README.md に記載されている PowerShell の手順を使ってください。--project PATH を指定すると、代わりに独自のモデルがそこに配置されます。これは独立したセットアップであり、セキュリティサンドボックスではありません（上記の「セキュリティ」を参照）。削除するには、フォルダーを削除してください。

以下は、プラグインを使ったクリーンな Claude Code で、同じ1週間分のデータを確認する様子です。アニメーションは記録されたセッションから作成されており、各ツール呼び出しには実際の所要時間が表示されます。

ホテルパック

packs/hotel/ は、客室タイプ × 宿泊日 × 滞在日数 × 予約期間 × 料金階層で構成される、合成ホテル収益管理モデルです。生成ツール、ドキュメント、ドメインに関するメモ、ヘルパーが付属しています。数千から837,000件までの制約を持つモデルを構築できるため、現実的で大規模な問題で optlens を試せます。

テスト

python -m unittest discover -s tests -t .                             # the engine, from the repo root
cd packs/hotel && python -m unittest discover -s tests -t .           # the hotel pack

お問い合わせ

ご質問、独自のモデルに関するフィードバック、または optchat の利用申請は、[email protected] までご連絡ください。optchat は、ビジネスユーザー向けに optlens を基盤として構築されたチャットエージェントです。バグ報告や機能リクエストは、GitHub の issue を作成してください。

以下は、ホテルパックのモデルを使った14泊のプランについて、プランナーが optchat とやり取りする様子です。データの読み込み時に、ある1泊分のグループ目標値が120ではなく1,200と入力されていました。各回答の末尾には、エンジンの呼び出し回数、所要時間、コストが表示されます。録画では、2秒を超える待ち時間は2秒に短縮されています。

貢献

独自のモデルに関する issue が、最も役立つ貢献です。CONTRIBUTING.md と行動規範をご覧ください。

ライセンス

Apache-2.0（LICENSE）。サードパーティへの謝辞はNOTICEに記載されています。