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	가벼운 웹 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
커뮤니티 – 리포지토리 내 QR 코드를 통해 참여 가능한 WeChat 그룹 (지원 및 서비스 계정 배포용).
자매 프로젝트 – DSLIGHTING (종단간 데이터 과학 보조자)는 README에서 링크됨.

⚖️ 라이선스

소스 코드는 CC BY‑NC 4.0 (비영리 사용 및 출처 표시)로 배포됩니다.

TL;DR: MM‑Agent는 연구 기반의 진정한 오픈소스 플랫폼으로, LLM을 자율적인 수학 모델링 보조자로 전환합니다. 문제 분석부터 LaTeX 대응 보고서까지 모든 과정을 처리합니다. 완전한 웹 데모와 명령줄 인터페이스를 제공하여 학생과 연구자 모두 즉시 사용 가능합니다.