OptiAgent

Natural language to verified optimization. OptiAgent turns a plain-English planning problem plus your tabular data into a linear program, solves it, audits the formulation for the mistakes LLMs actually make, and explains the result and its sensitivities.

The LLM never produces the final numbers. It only fills typed structures; numbers come from your files (loaded by code) or from your text (checked against it), the model is built and solved deterministically, and you approve the exact formulation before anything is solved.

How it works

Description (+ optional CSV/Excel)
  → Analyze (LLM): problem type, requirements, clarifying questions
  → Extract (LLM): typed problem from text, or a column mapping for uploaded data
      ↳ grounding: every number must appear in your text (retry with feedback if not)
  → Confirm (you): formulation in plain English + math, generated by code
      ↳ audit: values, limits, forbidden pairs and wording cross-checked against your text,
               sanity tests, and an independent LLM review of each requirement
      ↳ traceability: every requirement and every number gets an origin and a status
               (verified / represented / unresolved / unsupported); requests the model cannot
               express (fixed costs, budgets, multi-period, lot sizes, ...) are flagged, not dropped
  → Solve (OR-Tools GLOP) → verify twice:
      ↳ against the model (constraints, bounds, objective recomputed)
      ↳ against your data, independent of the model builder, including a duality certificate
        that proves the plan optimal (a plan that fails is never shown as a business plan)
  → Explain: shadow prices, exact one-unit effects, ranges, alternative optima, what-if
      ↳ or, if infeasible: the minimum shortfall per destination/task, with the method stated

"Plan verified" and "formulation traced" are separate claims: the first is proven mathematics, the second is checked by deterministic text and data rules that can miss unusual phrasings. Both are shown on every result. See docs/AUDIT.md for what is and is not established.

Supported in v1: transportation and assignment problems.

Every approved solve is saved as a project (SQLite, data/optiagent.db) with its own page, a printable report (save as PDF from the browser) and CSV export of the plan. Each sample dataset can be downloaded as a template for your own data.

Repository layout

core/    optiagent_core   – schema, model builder, solver, checks, analysis (HiGHS), ingestion, formulation
agent/   optiagent_agent  – Ollama client, analyze/extract pipeline, grounding, audit, requirement review
api/     optiagent_api    – FastAPI service
eval/    optiagent_eval   – generated + hand-written benchmarks, error injection, runner, report
web/                      – Next.js + TypeScript + Tailwind + shadcn/ui frontend

core has no LLM or web dependencies, so it can be tested on its own.

Prerequisites

• uv (installs Python 3.12 automatically)
• Node 24 and pnpm
• Ollama with qwen3:8b (ollama pull qwen3:8b)
• Docker Desktop (optional: Postgres and Redis, or the whole stack)

Running locally

cp .env.example .env

# API → http://localhost:8000/docs
uv sync
uv run uvicorn optiagent_api.main:app --reload

# Web → http://localhost:3000
cd web
pnpm install
pnpm dev

If port 8000 is taken, run the API on another port and start the web app with NEXT_PUBLIC_API_URL=http://localhost:<port> pnpm dev.

Deploying

See DEPLOY.md: Vercel (web), Render (API), Neon (Postgres), Groq or OpenRouter (AI) and Clerk (sign-in), all on free plans.

With Docker

docker compose up --build                      # API on 8000, web on 3000
API_PORT=8001 docker compose up --build        # if 8000 is taken

Ollama stays on the host; the API container reaches it through host.docker.internal. Saved projects and uploads are kept in named volumes.

After changing API models, regenerate the TypeScript types with pnpm gen:api (in web/).

Checks

uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
cd web && pnpm lint && pnpm typecheck && pnpm build

CI runs the same checks on every push.

Evaluation

uv run python -m optiagent_eval.verification                      # all deterministic checks (no LLM)
uv run python -m optiagent_eval.mutations                         # audit vs injected errors (no LLM)
uv run python -m optiagent_eval.run --model qwen3:8b --mode full  # also: no-verify, direct
uv run python -m optiagent_eval.report                            # writes eval/REPORT.md

Results and caveats are in eval/REPORT.md and on the Benchmarks page.

Roadmap

Phase	Deliverable	Status
0	Foundations: monorepo, API, web shell, Docker, CI	Done; CI green (Docker stack not yet run locally)
1	Solver engine: schema, builder, GLOP solve, solution checks	Done
2	CSV/Excel ingestion, column mapping, results UI with flow diagram	Done
3	LLM analysis, extraction, clarification, human confirmation	Done
4	Formulation audit + error-injection benchmark	Done
5	Sensitivity, exact one-unit effects, infeasibility diagnosis, what-if	Done
6	Benchmarks, baselines, failure analysis	Done (report)
7	Saved projects, printable report, CSV export, templates; auth, real-data demo, deploy	In progress
8	v2: MILP with fixed costs, CP-SAT rostering	Planned