optlens

A solver-agnostic debugger and explainer for LP and MILP models. Give it a model that is infeasible, or that solves to an answer you don't trust, and it finds the conflicting constraints, the smallest changes that fix them, and what each change costs. Every result comes back as text an agent or a person can read: in your own Python, in Claude Code through the plugin, or in any MCP client.

optlens works on a model that is already built. It does not write models.

Install

Python 3.12 or later:

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

To run the quickstart below or the tests, clone the repository and install it from the clone (git clone https://github.com/jjd-lab/optlens && cd optlens && pip install ".[scip,mcp]"). On a network that cannot reach GitHub (a proxy, a VPN), copy the source over another way (a zip of the repository) and install from that folder: pip install "<folder>[scip,mcp]", and for the Claude Code plugin claude plugin marketplace add <folder>.

Quickstart

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}]))

Save it as a file and run it from the repository root. Keep the if __name__ == "__main__": guard in any script that solves: solves run in worker processes, and on Windows (which starts them with spawn) each one re-imports the script, so without the guard the script re-runs in every solver process. Every Session method returns text, and optlens.session.TOOLS holds the matching JSON schemas for an agent. A session also covers feasibility relaxation, what-if edits as versions, why-not questions, sensitivity and marginal values, suspicious data values, and comparisons between versions or models.

A model built in Pyomo, gurobipy or PuLP loads directly, from the object or from the file that builds it. The file is run without its if __name__ == "__main__": block and stops at its first solve call (optimize(), solve()), whose model is the one read; nothing is solved, so a large gurobipy model loads on Gurobi's size-limited license.

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

LP files written by Gurobi (bracketed names, which HiGHS rejects) load without gurobipy.

Quadratic objectives (QP, MIQP) are supported: a convex QP solves on HiGHS, and a mixed-integer or non-convex one goes to SCIP automatically. Every question works as for a linear model except sensitivity ranges (and shadow prices for a non-convex objective). Quadratic constraints, indicator and other general constraints, and SOS are rejected when the model loads. The full list of questions, formats and solvers: optlens.dev/ask.

Solvers

HiGHS comes with the core; SCIP and Gurobi are extras. Pick one with OPTLENS_SOLVER (highs, scip, gurobi, or auto, the default), open_model's solver in the MCP server, or Session(..., prefer=...). Under auto without Gurobi, each model goes to HiGHS or SCIP (a larger MIP's first solve races both).

• Every solve has a hard time limit. Solvers do not always honour their own (SCIP once ran 862 s on a 30 s limit), so each solve runs in a worker process that is stopped at the limit.
• Gurobi does every step itself. A Gurobi session solves, computes IIS, relaxes, ranges and checks on Gurobi; no step is handed to another solver. If you chose Gurobi and it cannot run a model (not installed, or over the size-limited license), the tool stops and says so instead of switching. Under auto it uses Gurobi when it can run here (checked once with a one-variable solve: an installed gurobipy with no usable license, or a version your license server rejects, is left out, and open_model says why) and falls back to HiGHS or SCIP for a model Gurobi cannot run, and says so.
• HiGHS and SCIP stand in for each other where only one can do a step (HiGHS has no MIP IIS; SCIP does), or when one gives no verdict within its limit (the other tries once), and the result names the solver that did it.
• Every IIS is checked. A solver's IIS whose constraints are feasible on their own is rejected and rebuilt by removing constraints one at a time on the same solver. This guards against a known gurobipy 13.0.3 bug: computeIIS leaves out a one-variable row on a binary whose fractional limit rounds it to 0 (160 open <= 100 with open >= 1 returns open >= 1 alone, which is feasible).
• Gurobi is tested on small models and on one large one (a 279k-row hotel model: solves, sensitivity, IIS, relaxations and repair menus). Other large models are untested; reports are welcome.

On large models (hundreds of thousands of constraints) the IIS search starts near the conflict, from HiGHS's infeasibility proof, instead of searching the whole model.

Use it with your agent

Install as above (it puts optlens-mcp on your PATH), then connect once; the agent gets the 22 tools and the method (open the model first, lead with the cause, every number from a solve, re-solve before recommending a fix) with them.

The command must be on the PATH the agent sees; give the full path to optlens-mcp (for example .venv/bin/optlens-mcp) if it is not. OPTLENS_SOLVER (highs, scip, gurobi or auto) chooses the solver once.

Time limits. Solves stop at 45 s, so a call answers within a minute. OPTLENS_CALL_LIMIT (seconds, at least 30) is the most one tool call may take: a tool's time_limit may ask for up to 15 s less, and the agent asks for more only when a solve stopped at its limit while still improving (results say whether it was). Set it to what your client waits for one tool call; open_model states the limits in force, and a result cut short by one says so.

Large MIPs may not finish within any of these; results then report the plan found, its bound and its gap.

Then ask: "Why is plan.mps infeasible, and what fixes it?" The agent opens the model, writes its context once (what each constraint and variable family means, as JSON in .optlens/context/ that you can review and commit), and works through the tools. For several steps or many solves it uses run_python, a persistent Python process with the engine preloaded as session and the model loaded once.

The Claude Code plugin is the same server plus a skill that carries the same method (plugin/README.md).

Security. optlens runs code on your machine, with your permissions, and has no sandbox: run_python executes the code the agent writes (its process starts without your API keys and tokens, but can read and write whatever your user can; in Claude Code you approve each call), and opening a .py model runs that file up to its first solve call. Open only models and code you trust. To report a vulnerability, see SECURITY.md.

Try it

To try the plugin without touching your own Claude Code setup, build a clean one in a folder of its own: its own venv (optlens from GitHub), its own Claude config with only the optlens plugin, and a hotel week whose data load went wrong (packs/hotel/examples/try_week), with five questions to ask:

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

It needs bash, Python 3.12+ and Claude Code (macOS or Linux; on Windows, WSL, or the PowerShell steps in plugin/README.md). --project PATH puts your own model there instead. It is a separate setup, not a security sandbox (see Security above); delete the folder to remove it.

The same week in a clean Claude Code with the plugin (rendered from a recorded session; each tool call shows its real duration):

Hotel pack

packs/hotel/ is a synthetic hotel revenue-management model (room type × night × length of stay × booking window × rate tier) with its generator, its document, domain notes and helpers. It builds models from a few thousand to 837,000 constraints, for trying optlens on something realistic and large.

Tests

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

Contact

Questions, feedback on your own models, or access to optchat, the chat agent built on optlens for business users (available on request): hello@optlens.dev. Bugs and feature requests: GitHub issues.

A planner's session with optchat on the hotel pack's model (a 14-night plan, after a data load typed one night's group target as 1,200 instead of 120). Each answer ends with the engine calls, time and cost it took; waiting time is cut to two seconds:

Contributing

Issues with your own models are the most useful contribution; see CONTRIBUTING.md and the code of conduct.

License

Apache-2.0 (LICENSE); third-party credits in NOTICE.