OR Solver

A full-stack operations-research application that turns linear-programming problems written in English or French into validated mathematical models, solves them with PuLP, and explains the result in plain language.

How it works

flowchart LR
    USER[Natural-language problem] --> UI[React interface]
    UI --> API[NestJS API]
    API --> LLM[Gemini parser]
    LLM --> MODEL[Validated LP model]
    MODEL --> SOLVER[FastAPI + PuLP]
    SOLVER --> RESULT[Optimal / infeasible / unbounded]
    RESULT --> EXPLAIN[Gemini explanation]
    EXPLAIN --> UI

Loading

The language model never performs the optimization itself. It converts user intent into a structured model; the deterministic solver handles the mathematics. The backend coordinates validation, solver communication, errors, and result explanation.

Features

• English and French natural-language input
• Minimization and maximization problems
• Linear constraints and variable bounds
• Structured LLM-to-solver boundary
• Explicit optimal, infeasible, unbounded, and error states
• Human-readable Markdown explanations
• Chat-style React interface
• Independently deployable API and solver services
• Docker Compose startup with health checks

Example

Input:

A factory produces products A and B.

Profit: A = €30, B = €50
Machine time: 2A + 4B <= 100
Labor: 3A + 2B <= 90
A, B >= 0

Find the production plan that maximizes profit.

The application converts this request into a model equivalent to:

maximize 30A + 50B
subject to
  2A + 4B <= 100
  3A + 2B <= 90
  A, B >= 0

It then returns the solver status, decision-variable values, objective value, and a readable explanation. More sample prompts are available in EXAMPLES.md.

Architecture

Service	Technology	Responsibility
frontend	React, Vite, TypeScript	Chat input, progress, and result presentation
backend	NestJS, TypeScript	LLM orchestration, validation, API contract, and error handling
python-solver	FastAPI, PuLP	Deterministic LP solving and solver-status normalization

Quick start with Docker

Requirements

• Docker and Docker Compose
• A Google AI Studio API key

git clone https://github.com/aminebensaid66/Linear_Program_Project.git
cd Linear_Program_Project
cp .env.example .env

Add the required Gemini credential to .env, then run:

docker compose -f docker_compose.yaml up --build

Component	URL
Web application	http://localhost:5173
NestJS API	http://localhost:3000
Python solver	http://localhost:8000

Stop the stack with:

docker compose -f docker_compose.yaml down

Local development

Python solver

cd python-solver
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

NestJS backend

cd backend
npm install
npm run start:dev

React frontend

cd frontend
npm install
npm run dev

API

The frontend submits the natural-language problem to the NestJS API. The backend returns a normalized response containing the parsed problem, solver state, decision variables, objective value, and explanation.

The solver also exposes a health endpoint used by Docker Compose before starting dependent services.

Reliability and security boundaries

• Treat LLM output as untrusted input and validate it before invoking PuLP.
• Never commit API keys; use .env locally and a secret manager in deployment.
• Keep the deterministic solver isolated from explanation generation.
• Surface infeasible and unbounded outcomes instead of presenting fabricated solutions.
• Apply request-size, timeout, and rate limits before public deployment.

Repository structure

.
├── frontend/          # React/Vite client
├── backend/           # NestJS orchestration API
├── python-solver/     # FastAPI/PuLP service
├── EXAMPLES.md
├── docker_compose.yaml
└── .env.example

Current status

The project demonstrates an end-to-end architecture for AI-assisted mathematical optimization. Before production use, add persistent observability, authentication, rate limiting, broader parser evaluation, and automated end-to-end tests.

License

No license has been declared yet. All rights are reserved unless a license is added.