On this page
First local Optimization Assurance Workbench
9 October 2026. A usable local CSV-to-report workflow now wraps the exact facility checker and an optional conventional solver. It preserves stable IDs and original bytes, checks declared assumptions, separates submitted plans from solver proposals and independent bounds, and exports a standalone HTML review plus JSON evidence. The source approximation backend is still deferred; no customer value or paid demand is established.
Open a generated review
| Example | What to inspect |
|---|---|
| Six-location review | Submitted sites cost 24; all six candidate pairs prove a best cost of 17, an improvement of seven synthetic distance units |
| Solver-reported optimum | OR-Tools reports OPTIMAL and its plan is independently costed at 17; with enumeration disabled and lower bound three, independent optimality stays unknown |
| Exact lower-bound certificate | Twenty-four locations and twelve sites; checked cost and named-ID dual both equal 12, proving optimum without enumeration |
| Unsupported capacity | A finite capacity is explicitly unsupported; no unconstrained result is substituted |
| Directed-distance input | Failed metric symmetry names the IDs and explains reference ineligibility without declaring the general planning problem invalid |
| Infeasible submitted plan | Three selected sites exceed budget two; the rejected submission remains distinct from a separately checked alternative |
| Duplicate location ID | Import errors prevent a mathematical result |
| Escaped input text | A script-like title is displayed as literal text, never executed |
All examples are generated controls. No geographic measurements or customer data were used. Original first-render reports and tool bytes remain preserved in edition v1.
Run the local workflow
From this repository, with Python 3.10 or newer:
python3 research/tools/facility_review_workbench.py research/prototypes/facility-review-workbench-2026-10-09-v2/valid/review/inputs --output /tmp/facility-review-001
Choose a fresh output directory for each review. Existing outputs are refused and preserved. Open the emitted report.html; it needs no server or account. The default uses the standard library and the existing exact reference. For an environment with OR-Tools installed, add --solver ortools. This run used the preserved OR-Tools 9.15.6755 environment, with no installation changes.
--subset-budget 0 disables enumeration. --lookup-budget caps enumeration distance lookups. Neither setting disables model, metric, plan or supplied-dual checks. Solver time is fixed at two seconds, one worker, seed 125. Solver scaling is exact and refused above denominator scale 1,000,000 or conservative integer objective range 2^60; it never rounds the input to fit.
Input contract
| File | Required contents |
|---|---|
| study.json | Schema, title, units, supplied distance provenance, integer k, explicit model and additional-constraint list |
| locations.csv | location_id,label,is_client,is_candidate,demand_weight,capacity,mandatory |
| distances.csv | from_id,to_id,distance, exactly one cell for every ordered location pair, including diagonal |
| plan.csv | selected_site_id, one selected candidate per row |
| Optional dual.json | Alpha keyed by client ID; beta keyed by client then candidate ID; lambda as an exact number string |
The input directory must contain only these recognized files. Extra files or subdirectories are refused so a separate constraint file cannot be silently omitted.
IDs are case-sensitive ASCII strings up to 64 characters, starting with a letter/digit and continuing with letters, digits, underscore, period, colon or hyphen. IDs such as 01 and 1 remain distinct. The normalized internal order is lexicographic; nearest-site ties use that stable ID order. CSV columns may be reordered, but names must match exactly and duplicates/extra columns are rejected. Booleans are exactly true or false. UTF-8 BOM is accepted while original bytes remain unchanged.
Distances accept bounded decimal or rational strings and convert exactly to canonical rationals. No binary floating conversion or input rounding occurs. The mathematical reference supports an unweighted nearest-distance sum: client demand is one, non-client demand zero, capacities blank/unlimited, mandatory flags false and no extra constraints. Weighted/capacitated/mandatory or other declared models receive an explicit unsupported status. Such features may be valid business requirements; they need separate implementations.
A complete strict metric is required for this first module: zero diagonal, positive distances between distinct IDs, symmetry and every triangle. Rectangular client-site matrices, road-direction effects, duplicate physical positions and uncertain measurements do not automatically satisfy that contract. Supplied provenance remains unverified. Caps are 48 locations, two MiB per input file and 128-bit rational numerator/denominator. Enumeration allows at most 100,000 k-subsets and five million distance lookups. These counters omit metric checks, bit arithmetic, allocations and wall time.
Evidence and status distinctions
Each export contains original input bytes, normalized IDs/model, submitted assignments/cost, solver configuration/status/model hash when requested, independent comparison and optional dual audit. JSON preserves detailed statuses; HTML uses readable labels. An invalid dual is rejected and cannot promote an optimality claim. A valid plan's objective is different from proof of its optimality. Source theorem eligibility, exact frozen calculations and physical-data fidelity remain separate.
manifest.json hashes every emitted report/input file other than itself and records Python/tool identities. Those checksums bind local bytes, not external authenticity. The human sign-off field is explicitly unsupplied. Historical tool copies are inert evidence and must not be executed.
86 intake/model/solver/export controls cover row/column permutations, leading-zero IDs, tie handling, decimal exactness, unsupported constraints, malformed data, certificates, solver scaling, original-byte archives and refusal to overwrite a prior review. Sixteen display controls preserve computation results while replacing internal status labels with readable text. Two directory-boundary controls verify explicit refusal of unrecognized files and subdirectories. Total: 104 new passing controls. Local HTML layout was inspected; source proofs and commercial benefit remain unverified.
Product decision
This is the first local review/export release, with eight hosted synthetic examples. The live site remains a static research catalog; it has no customer upload endpoint, account database or hosted optimization API. A browser intake interface, additional real-world constraints, automated dual generation and a paid study remain future work. Evaluate the exported report against an actual consultancy review process before expanding the application or charging recurring fees. First-product plan.