usail-hkust/LLM-MM-Agent

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

📚 什么是 MM‑Agent？

MM‑Agent 是一个开源系统，让大型语言模型（LLM）充当 数学建模协作者。它模仿人类团队应对现实世界建模问题（如 MCM/ICM 竞赛）的方式，将工作分为四个阶段：

问题分析 – 读取非结构化描述，识别目标、数据和约束条件。
数学建模 – 从一个精心整理的库（分层数学建模库，HMML）中选择合适的建模形式，并编写控制方程。
计算求解 – 使用 OpenAI 的 GPT‑4o 或 DeepSeek‑R1 自动生成、运行并迭代优化代码以求解模型。
解决方案报告 – 自动生成包含结果、可视化图表和讨论的 LaTeX 格式报告。

目标是为用户（尤其是准备竞赛的学生或需要快速原型的研究人员）提供一个从纯文本问题描述到可提交论文的端到端工作流。

🚀 核心功能（避免术语堆砌）

功能	为你带来的价值
端到端流水线	一条命令即可创建项目、导入问题和数据、构建模型、运行代码并撰写报告。
自动模型选择	代理查询 HMML（约 100 个预定义建模模板），选择与问题领域和约束相匹配的方法。
智能代码生成	LLM 驱动的代码自动编写、执行和优化；你可以实时查看生成的 Python 脚本。
交互式数据分析	内置可视化工具使代理能够探索数据，并将图表嵌入最终报告中。
专业论文撰写	生成包含章节、公式、表格和参考文献的 LaTeX 文档，可直接编译。
项目管理 UI	轻量级 Web UI（Next.js 前端 + FastAPI 后端）支持跟踪多个建模项目、查看日志并下载 PDF。

🛠️ 如何开始

克隆与设置

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

本地运行演示（包含 Next.js 前端、FastAPI 后端、SQLite 存储和沙箱支持）：
```
bash demo/scripts/run.sh
```
演示版是生产服务的简化版本——不包含任何密钥。
通过命令行运行代理
```
python MMAgent/main.py --key YOUR_OPENAI_API_KEY --task 2024_C
```
将 2024_C 替换为 MM‑Bench 基准中的任意问题 ID（例如 2024 MCM 问题 C）。

📦 仓库内容

MMAgent/ – 核心 Python 代码，协调四个工作流阶段，与 LLM 通信，并管理 HMML 知识库。
demo/ – 可直接运行的示例，包含：
- frontend/ (Next.js) – 用于上传问题描述、查看生成代码和下载最终 PDF 的 UI。
- backend/ (FastAPI) – 调用代理的 API 端点，将项目元数据存储在 SQLite 中，并在沙箱中运行代码。
- scripts/run.sh – 一键启动脚本。
requirements.txt – Python 依赖项（PyTorch 2.0+、openai、fastapi、uvicorn 等）。
figs/ 与 assets/ – README 中使用的图表、截图和演示视频。

📊 谁会使用这个？

准备数学建模竞赛（MCM/ICM）的学生，希望拥有一个“建模协作者”。
需要快速原型的研究人员，用于新优化或仿真问题。
寻找教学辅助工具的教育者，以展示完整的建模流程。
对构建其他领域特定任务的 LLM 驱动代理感兴趣的开发者（代码模块化，可复用）。

📚 相关资源

论文 – MM‑Agent: LLMs as Agents for Real‑world Mathematical Modeling Problems（NeurIPS 2025，也发布于 arXiv: 2505.14148）。
在线演示 – 部署在 Hugging Face Spaces：https://huggingface.co/spaces/MathematicalModelingAgent/MathematicalModelingAgent
社区 – 仓库中的二维码可加入 WeChat 群组，用于支持和账号分发。
姊妹项目 – DSLIGHTING（端到端数据科学助手），在 README 中链接。

⚖️ 许可证

源代码采用 CC BY‑NC 4.0（非商业用途，需署名）发布。

TL;DR: MM‑Agent 是一个基于研究的真正开源平台，将 LLM 转变为自主的数学建模助手，从问题解析到 LaTeX 就绪报告全程自动化。它自带完整 Web 演示和命令行接口，学生和研究人员可开箱即用。