usail-hkust/LLM-MM-Agent

🔥🔥🔥 [NeurIPS2025] MM-Agent: LLM as Agents for Real-world Mathematical Modeling Problem

📚 What is MM‑Agent?

MM‑Agent is an open‑source system that lets a large language model act as a mathematical‑modeling copilot. It mimics the way human teams tackle real‑world modeling problems (e.g., the MCM/ICM contests) by breaking the work into four stages:

Problem analysis – read an unstructured description, identify objectives, data, and constraints.
Mathematical modeling – select a suitable formulation from a curated library (the Hierarchical Mathematical Modeling Library, HMML) and write the governing equations.
Computational solving – generate, run, and iteratively improve code (using OpenAI’s GPT‑4o or DeepSeek‑R1) to solve the model.
Solution reporting – automatically produce a LaTeX‑style report with results, visualisations, and discussion.

The goal is to give users—especially students preparing for contests or researchers needing a quick prototype—an end‑to‑end workflow that goes from a plain‑text problem statement to a ready‑to‑submit paper.

🚀 Core Features (Jargon‑Light)

Feature	What it does for you
End‑to‑end pipeline	One command creates a project, ingests the problem and data, builds a model, runs code, and writes a report.
Automated model selection	The agent queries the HMML (≈ 100 pre‑defined modeling schemas) to pick a method that fits the problem’s domain and constraints.
Intelligent code generation	LLM‑driven code is written, executed, and refined automatically; you can watch the generated Python scripts.
Interactive data analysis	Built‑in visualisation utilities let the agent explore the data and embed plots in the final report.
Professional paper writing	Produces a LaTeX document with sections, equations, tables, and bibliography, ready for compilation.
Project management UI	A lightweight web UI (Next.js frontend + FastAPI backend) lets you track multiple modeling projects, view logs, and download PDFs.

🛠️ How to Get Started

Clone & set up

git clone https://github.com/usail-hkust/LLM-MM-Agent.git
cd LLM-MM-Agent
conda create -n math_modeling python=3.10 && conda activate math_modeling
pip install -r requirements.txt

Run the demo locally (includes the Next.js front‑end, FastAPI back‑end, SQLite storage, and sandbox support):
```
bash demo/scripts/run.sh
```
The demo is a stripped‑down version of the production service—no secret keys are shipped.
Run the agent from the command line
```
python MMAgent/main.py --key YOUR_OPENAI_API_KEY --task 2024_C
```
Replace 2024_C with any problem ID from the MM‑Bench benchmark (e.g., the 2024 MCM problem C).

📦 What’s Inside the Repository?

MMAgent/ – core Python code that orchestrates the four workflow stages, talks to the LLM, and manages the HMML knowledge base.
demo/ – a ready‑to‑run example containing:
- frontend/ (Next.js) – UI for uploading problem statements, viewing generated code, and downloading the final PDF.
- backend/ (FastAPI) – API endpoints that call the agent, store project metadata in SQLite, and run sandboxed code.
- scripts/run.sh – one‑click start script.
requirements.txt – Python dependencies (PyTorch 2.0+, openai, fastapi, uvicorn, etc.).
figs/ & assets/ – diagrams, screenshots, and the demo video used in the README.

📊 Who Might Use This?

Students preparing for mathematical‑modeling contests (MCM/ICM) who want a “modeling copilot”.
Researchers needing a quick prototype for a new optimization or simulation problem.
Educators looking for a teaching aid that demonstrates the full modeling workflow.
Developers interested in building LLM‑driven agents for other domain‑specific tasks (the code is modular and can be repurposed).

📚 Related Resources

Paper – MM‑Agent: LLMs as Agents for Real‑world Mathematical Modeling Problems (NeurIPS 2025, also on arXiv: 2505.14148).
Live demo – hosted on Hugging Face Spaces: https://huggingface.co/spaces/MathematicalModelingAgent/MathematicalModelingAgent
Community – WeChat group (QR code in the repo) for support and service‑account distribution.
Sibling project – DSLIGHTING (an end‑to‑end data‑science assistant) linked from the README.

⚖️ License

The source code is released under CC BY‑NC 4.0 (non‑commercial use with attribution).

TL;DR: MM‑Agent is a genuine, research‑backed open‑source platform that turns LLMs into autonomous mathematical‑modeling assistants, handling everything from problem parsing to LaTeX‑ready reports. It ships with a full web demo and a command‑line interface, making it usable out‑of‑the‑box for students and researchers alike.