In my earlier put up, I 4 core improvements that makes ORPilot a production-oriented open-source LLM-for-OR software, particularly interview agent, knowledge assortment agent, parameter computation agent and intermediate illustration (IR). Among the many 4 improvements, the IR is crucial one which differentiates ORPilot from an educational prototype and endows it with the potential to be a production-level software, because it offers with two points {that a} manufacturing atmosphere cares most about: reproducibility and portability. On this put up, I provides you with a deep dive into ORPilot’s IR construction.
What Is IR?
There’s a downside that nearly no one talks about when discussing AI-generated optimization fashions: what occurs after the primary clear up?
You get your mannequin working. You get an optimum resolution. After which three weeks later, it’s good to re-run it with up to date demand knowledge. Or your colleague on a unique machine wants to breed the consequence. Or your organization decides to change from Gurobi to an open-source solver due to licensing prices. Otherwise you need to ask “what if we improve the capability of a facility by 20%?” With most present LLM-for-OR instruments, the reply to all of those questions is similar: it’s good to begin over, name the LLM once more, pay the API price once more, generate the solver code once more, and hope to get the identical mannequin construction. Nonetheless, the open-source AI optimization modeling agent ORPilot supplies an alternate resolution to this downside: Intermediate Illustration (IR).
The IR is a solver-agnostic, typed JSON schema that captures the whole mathematical construction of an optimization mannequin. Not the optimization code, however the mannequin itself, expressed in a kind that’s unbiased of any explicit solver.
ORPilot’s IR construction has 5 top-level sections.
(1) Units: named collections of entities, reminiscent of Employees, Duties, Crops, Durations. Every set is aware of the place its members come from: a CSV file, a scalar depend, or a hardcoded checklist.
(2) Parameters: listed numerical knowledge from CSV recordsdata, every linked to its area (which units index it) and to the precise column names wanted to load it.
(3) Variables: choice variables with kind (steady, binary, integer), area, bounds, and structural flags.
(4) Goal: a symbolic expression tree over variables and parameters — sums, variations, merchandise, listed sums in solver-neutral kind.
(5) Constraints: named symbolic constraints with domains, expression bushes, and sense (<= or = or >=). Each constraint is a whole, self-describing object.
Let’s make this concrete by a particular employee process task downside beneath.
Employee-Job Task Downside Instance
On this downside, 4 staff have to be assigned to 4 duties, one process per employee, one employee per process. Every (employee, process) pair has a value from a CSV file. We attempt to decrease the overall task price. This can be a traditional task downside, which is an integer program.
The information lives in two recordsdata:
(1) units.csv (all set members in a single place):
set_name ingredient
staff w1
staff w2
staff w3
staff w4
duties t1
duties t2
duties t3
duties t4
(2) assignment_costs.csv (the fee matrix):
worker_id task_id price
w1 t1 2.0
w1 t2 4.0
… … …
Right here is the total IR for this downside:
{
"problem_class": "AssignmentProblem",
"model_type": "Blended Integer Program",
"sense": "decrease",
"units": {
"Employees": {
"measurement": null,
"index_symbol": "w",
"supply": "units.csv",
"column": "ingredient",
"filter_column": "set_name",
"filter_value": "staff",
"ordered": false
},
"Duties": {
"measurement": null,
"index_symbol": "t",
"supply": "units.csv",
"column": "ingredient",
"filter_column": "set_name",
"filter_value": "duties",
"ordered": false
}
},
"parameters": {
"assignment_cost": {
"area": ["Workers", "Tasks"],
"kind": "float",
"supply": "assignment_costs.csv",
"column": "price",
"index_columns": ["worker_id", "task_id"],
"missing_default": "inf"
}
},
"variables": {
"assign": {
"description": "1 if employee w is assigned to process t, 0 in any other case",
"label": "assignments",
"area": ["Workers", "Tasks"],
"kind": "binary",
"lower_bound": 0,
"upper_bound": 1,
"upper_bound_set": null,
"exclude_diagonal": false,
"domain_filter": null
}
},
"constraints": {
"one_task_per_worker": {
"area": ["Workers"],
"expression": {
"operation": "indexed_sum",
"over": ["Tasks:t"],
"physique": {"kind": "variable", "identify": "assign", "indices": ["w", "t"]}
},
"sense": "=",
"rhs": {"kind": "fixed", "worth": 1}
},
"one_worker_per_task": {
"area": ["Tasks"],
"expression": {
"operation": "indexed_sum",
"over": ["Workers:w"],
"physique": {"kind": "variable", "identify": "assign", "indices": ["w", "t"]}
},
"sense": "=",
"rhs": {"kind": "fixed", "worth": 1}
}
},
"goal": {
"sense": "decrease",
"expression": {
"operation": "indexed_sum",
"over": ["Workers:w", "Tasks:t"],
"physique": {
"operation": "multiply",
"left": {"kind": "parameter", "identify": "assignment_cost", "indices": ["w", "t"]},
"proper": {"kind": "variable", "identify": "assign", "indices": ["w", "t"]}
}
}
}
}Let’s stroll via what every part is doing and why the design selections had been made.
Units
The “units” subject signifies the place set members come from. Crucial design choice in “units” is the info supply conference. ORPilot requires all set members to stay in a single file known as units.csv, utilizing a two-column format: “set_name” and “ingredient”. Each set — entities (staff, duties, crops) and time units (intervals, months) is a filtered slice of this file. On this downside, the “Employees” subject says: load members from units.csv, learn the “ingredient” column, hold solely rows the place “set_name” column equals “staff”. The consequence at compile time shall be Employees = [“w1”, “w2”, “w3”, “w4”].
This conference has two advantages. First, all grasp knowledge is in a single place. Including a employee means including a row to units.csv, not modifying a number of recordsdata. Second, the “filter_value” subject is verified in opposition to the precise distinct values in units.csv at IR-generation time, catching typos earlier than the solver code produces empty units. The “index_symbol” subject (“w” for Employees, “t” for Duties) is the loop variable identify that can seem within the complied solver code, e.g., “for w in Employees, for t in Duties”. It have to be chosen to keep away from image conflicts throughout nested loops (see the shadow rule beneath). The “ordered” subject is fake for each units right here, however it turns into essential for time-indexed fashions. An ordered set helps temporal lag references, e.g., referencing stock[t-1] from inside a period-t constraint.
Parameters
The “parameters” subject hyperlinks knowledge to the mannequin. The “assignment_cost” parameter has six structural fields.
(1) “area”: [“Workers”, “Tasks”] — this parameter is listed by each units, producing a 2D desk.
(2) “kind”: “float” — the info kind of this parameter is float.
(3) “supply”: “assignment_costs.csv” — the precise filename (with extension) that holds the info.
(4) “column”: “price” — the CSV column that holds the numeric values to load.
(5) “index_columns”: [“worker_id”, “task_id”] — the CSV columns that function keys, in the identical order as “area”. The “index_columns” subject is likely one of the most consequential items of the IR. With out it, the compiler can’t decide which columns within the CSV correspond to which area units. Traditionally, a standard failure mode was the compiler guessing the mistaken key column identify and silently loading the mistaken knowledge. The IR enforces that the right column names are at all times provided explicitly.
(6) “missing_default”: “inf” — tells the compiler that any (employee, process) pair not current within the CSV ought to be handled as having infinite price, that means that route is unavailable. That is the right semantic for price and penalty parameters.
Variables
The “variables” subject defines the choices to be made within the optimization mannequin. The “assign” variable is binary, listed over “area”: [“Workers”, “Tasks”]. In order that at compile time, the compiler builds (assuming utilizing PuLP solver):
assign = {(w, t): pulp.LpVariable(f"assign_{w}_{t}", cat="Binary") for w in Employees for t in Duties}Some key structural flags not used right here however price understanding are “exclude_diagonal”, “domain_filter” and “upper_bound_set”.
For variables listed over the identical set twice, like “arc[Location, Location]” in a routing mannequin, setting “exclude_diagonal=true” tells the compiler to skip the (i, i) diagonal. No location travels to itself. The compiler emits an
if l1 == l2:
proceedguard and makes use of “.get(key, 0)” for all accesses so lacking keys by no means trigger “KeyError”.
When a value desk has fewer rows than the total Cartesian product of its area units (e.g. solely legitimate routes exist within the CSV), setting “domain_filter” to that parameter’s identify restricts the variable to solely these combos. The compiler emits the comprehension with “if (i, j) in transport_cost” so non-existent routes are by no means created as variables.
For integer variables whose pure higher sure is the cardinality of a set (e.g. MTZ place variables in subtour elimination), setting “upper_bound_set”=”Prospects” causes the compiler to emit “len(Prospects)” because the higher sure, conserving the mannequin knowledge agnostic even when the set measurement varies between runs.
Constraints
The “constraints” incorporates an expression bushes that describe the constraints outlined for this mannequin. That is the place the IR diverges most sharply from a code file. Constraints will not be saved as strings or code, however they’re expression bushes. Every constraint has: (1) “area”: the units the compiler will loop over to generate one constraint occasion per mixture. For instance, “area”: [“Workers”] means one constraint per employee. (2) “expression”: the left-hand aspect, as a recursive tree of nodes. (3) sense: the signal for this constraint, “=” or “<=” or “>=”. (4) “rhs”: the right-hand aspect, additionally an expression tree (however containing solely constants and parameters, by no means variables, which have to be moved to the LHS). Let’s take a look at the “one_task_per_worker” constraint intently.
"one_task_per_worker": {
"area": ["Workers"],
"expression": {
"operation": "indexed_sum",
"over": ["Tasks:t"],
"physique": {"kind": "variable", "identify": "assign", "indices": ["w", "t"]}
},
"sense": "=",
"rhs": {"kind": "fixed", "worth": 1}
},Within the “expression” node above, The “over” subject makes use of the alias “Duties:t” to explicitly identify the loop variable “t” for this internal sum. That is required as a result of “t” is already the index_symbol of the Duties set, and when the outer constraint area doesn’t embrace Duties, the compiler gained’t have a “t” in scope, however the alias forces it to exist contained in the sum. Each time a set in “over” already seems within the constraint’s area (with the identical index_symbol), use an alias to keep away from shadowing the outer loop variable. In any other case the internal “t” would shadow the outer “t”, and the sum would at all times compute assign[t, t] (a self-loop diagonal) fairly than the supposed sum.
Goal
Within the IR, the target is written as beneath.
"goal": {
"sense": "decrease",
"expression": {
"operation": "indexed_sum",
"over": ["Workers:w", "Tasks:t"],
"physique": {
"operation": "multiply",
"left": {"kind": "parameter", "identify": "assignment_cost", "indices": ["w", "t"]},
"proper": {"kind": "variable", "identify": "assign", "indices": ["w", "t"]}
}
}
}The outer “indexed_sum” iterates over each Employees and Duties concurrently, utilizing aliases “Employees:w” and “Duties:t” to call each loop variables explicitly. The physique is a multiply node, parameter × variable, which is the one type of multiplication the IR permits in a linear mannequin. The result’s one time period per (employee, process) pair, summed into the overall price.
That is the only goal form: a single listed sum. Extra complicated targets mix a number of listed sums utilizing subtract. Say the mannequin had each task price and a bonus for sure assignments: maximize sum(bonus[w,t] × assign[w,t]) – sum(price[w,t] × assign[w,t]). That might be encoded as:
subtract(
indexed_sum(over Employees,Duties: bonus[w,t] × assign[w,t]),
indexed_sum(over Employees,Duties: price[w,t] × assign[w,t])
)
One essential rule about subtract: by no means nest a subtract on the correct aspect of one other subtract. As a result of subtract is a binary operation, left minus proper, placing one other subtract on the correct flips the internal time period’s signal:
subtract(A, subtract(B, C))
= A – (B – C)
= A – B + C ← C was presupposed to be subtracted however finally ends up ADDED
Say the target is income – shipping_cost – holding_cost. A standard failure mode of LLMs is that they generally would group the 2 prices collectively on the correct:
subtract(income, subtract(shipping_cost, holding_cost))
= income – (shipping_cost – holding_cost)
= income – shipping_cost + holding_cost
That is mistaken because the holding price turns into a income. The mannequin nonetheless runs and the solver nonetheless returns “optimum”, however the goal worth is
mistaken, inflated by 2 × holding_cost. The proper kind is a flat left-to-right chain:
subtract(subtract(income, shipping_cost), holding_cost)
= (income – shipping_cost) – holding_cost
= income – shipping_cost – holding_cost
ORPilot has an IR semantic validator that catches the right-side nesting sample earlier than compilation and names the particular time period whose signal was flipped, so the LLM can repair the chain ordering.
From IR to Solver Code
The IR compiler is a deterministic piece of software program — no LLM concerned. Given the identical ir.json and the identical CSV knowledge recordsdata, it at all times produces an identical solver code. At all times. The compiler presently helps 5 backends: PuLP, Pyomo, OR-Instruments, Gurobi and CPLEX. Switching backends requires zero mannequin adjustments. The IR is similar; solely the compilation goal adjustments. This implies you may archive ir.json alongside your knowledge and reproduce any previous consequence precisely, with out making a single API name. You may swap from Gurobi to PuLP by operating: orpilot compile-ir output/ir.json --solver pulp --run. One command, zero LLM calls, identical mannequin construction. You may run CI/CD validation on solver outputs by committing ir.json and operating the compiler in your pipeline. You may share ir.json with a colleague on a unique machine and so they can clear up the identical mannequin without having your LLM API key and even understanding the issue from scratch.
The IR Compilation Pipeline
After getting a validated ir.json, ORPilot presents a light-weight compilation pipeline: ir.json + CSV Information → IR Compiler → Solver Code → Code Execution. This pipeline includes zero LLM calls finish to finish. It’s quick, low cost, and absolutely deterministic. The one LLM name in the entire workflow was the one which produced the ir.json within the first place. The CLI command is: orpilot compile-ir output/ir.json –run. That compiles the IR, executes the mannequin, and generates an answer report. To modify solvers: orpilot compile-ir output/ir.json –solver pyomo –run.
The IR Semantic Validator
Earlier than an IR is saved and compiled, ORPilot runs a semantic validator that catches modeling errors which might be structurally legitimate JSON however mathematically mistaken. The validator presently catches three main classes, that are all widespread failure modes of LLMS throughout experiments.
1. Stock steadiness signal errors. It detects when all stream variables in a steadiness constraint find yourself on the identical aspect (e.g. inv = influx + outflow as an alternative of inv = influx – outflow). The proper id is: ending_inv = beginning_inv + influx – outflow. Violations of this produce fashions which might be both infeasible (the over-constrained case) or unbounded (the under-constrained case), and the signal error is nearly unattainable to identify in compiled code.
2. Lacking init constraint. If a temporal-lag steadiness constraint exists, the validator requires a corresponding “_init” variant representing the constraint within the preliminary time interval. A lacking init constraint might go away the primary interval unconstrained, producing an unbounded mannequin even when the subsequent-period constraint is appropriate.
3. Nested subtract in goal. Typically the IR builder LLM would write subtract(A, subtract(B, C)) whereas it intends to sequentially subtract price B and C from income A. Nonetheless, mathematically this expression evaluates to A – (B – C) = A – B + C, flipping C’s signal from price to income. The mannequin nonetheless solves to “optimum” however the goal worth is inflated by 2 × C. The validator detects right-side nesting and names the affected time period so the LLM can rewrite the target as a flat left-to-right chain.
When validation fails, the particular error message is fed again to the LLM as a focused retry immediate. The LLM doesn’t see “invalid IR”, however it sees a message like “inventory_balance signal error: variable discharge seems to be destructive (coefficient -1) however ought to be subtracted from influx, not added to it.”
Why IR Issues For What-If Evaluation
The IR’s reproducibility and portability properties have a pure extension: systematic what-if evaluation. As soon as a mannequin is solved and its IR is saved, a enterprise person usually desires to discover how the optimum resolution adjustments below totally different assumptions. What if demand will increase by 20% in Q3? What if the price of uncooked materials rises to $15 per unit? What if we add a constraint that no single provider accounts for greater than 40% of whole procurement? The IR construction makes two classes of what-if queries trivially low cost. The primary class is knowledge adjustments. If the query solely modifies parameter values (leaving the mannequin construction intact), you solely have to replace the CSV recordsdata. The IR JSON is unchanged. Run the compiler
in opposition to the brand new knowledge and re-solve. This can be a zero-LLM-call operation. You may run lots of of eventualities this fashion with no API price.
The second class is structural adjustments. If the query modifies a constraint, provides a brand new one, or adjustments the target, you edit the IR JSON straight. As a result of the IR is a typed, schema-validated doc with a well-defined expression tree, such edits are localized. Including a constraint is a matter of appending a brand new constraint object, however not looking via lots of of traces
of solver-specific code looking for the place to make the change.
This can be a qualitatively totally different relationship along with your optimization mannequin than what some other present software presents. As a substitute of a one-shot artifact, you’ve a dwelling, editable mannequin construction which you could interrogate and modify independently of the LLM.
The Larger Image
The IR addresses one thing basic concerning the relationship between AI and manufacturing software program: AI outputs should be verifiable, moveable, and sturdy. A solver code file generated by an LLM is an opaque blob. If one thing is mistaken, you want the LLM to repair it. If you wish to change one thing, you both perceive solver API syntax effectively sufficient to edit it your self, otherwise you name the LLM once more. The mannequin lives solely as code. The IR decouples the modeling intelligence (which requires an LLM) from the computational step (which doesn’t require an LLM). The LLM’s job is to provide a clear, structured JSON artifact. As soon as that artifact exists and is validated, it’s owned by you, not by the LLM. This design selection, greater than anything in ORPilot, is what makes it appropriate for manufacturing deployment fairly than tutorial demonstration.
