MathModelAgent: Automating a 3-Day Math Modeling Contest in 1 Hour

Forum topic · ✨步子哥 · 2026-09-12

Summary

MathModelAgent is an open-source agent project designed specifically for mathematical modeling competitions. It automates the entire workflow—problem analysis, model selection (AHP, TOPSIS, ARIMA, GA), coding, debugging, paper writing, and typesetting—producing a submission-ready PDF in about one hour, versus the traditional three-day team contest format. Architecturally, it takes a SKILLS-only approach: instead of building its own agent harness, it uses Claude Code, Codex, or Cursor as the execution layer and encodes domain knowledge in Markdown skill files. It orchestrates three heterogeneous agents (modeler, coder, writer) that can use different LLMs, runs a 9-step automated QA pipeline (prompt-leak detection, numerical consistency checks, Typst compilation, PDF visual inspection), ships 17 Typst templates matching major contests (CUMCM, MCM/ICM, and others), offers 6 fine-grained human-in-the-loop actions, and applies 4-layer fault tolerance with retries, model fallback, evaluator shadow mode, and feedback reruns. A desktop version for macOS/Windows bundles the full environment. The project reflects a broader trend: agent value shifts from larger models to structured skill design.

The standard rhythm of a mathematical modeling contest: three days and three nights, three people—one modeling, one coding, one writing the paper—followed by an all-nighter on typesetting. Then you submit a PDF.

MathModelAgent's author compresses this into 1 hour. Not 1 hour of assistance—1 hour of fully automated execution: analyzing the problem, modeling, writing code, debugging, writing the paper, typesetting, and outputting a PDF ready for direct submission.

The project gained 264 stars in a single day. Its ambition is stated in the first line of the README: an Agent designed for mathematical modeling that automatically completes the modeling and generates a complete, directly submittable paper.

SKILLS-Driven: No Harness Layer

MathModelAgent's most counterintuitive design decision: the project only builds the SKILLS layer, not the Harness layer.

What does this mean? Most agent projects write their own agent framework—task planning, tool calling, memory management, error recovery, all in-house. MathModelAgent abandons that path, using Claude Code / Codex / Cursor directly as the Harness (runtime environment) and writing only skill files.

Each skill is a Markdown file describing a specific stage's task (problem analysis, modeling, coding, paper writing, acceptance). The Harness (Claude Code, etc.) reads the skill files and executes according to their descriptions.

The author states it plainly in the README:

> Two years ago I built my own Agent frameworks; now and going forward, more agent products are built directly on Harnesses like Codex / Claude Code / Pi plus SKILLS.

This is a paradigm judgment: the agent framework layer is being absorbed by the Harness layer. You don't need to write your own task planner—Claude Code is already a good task planner. You don't need to write your own tool calling—the MCP protocol has standardized it. What you need is domain knowledge, and the best carrier for domain knowledge is skill files.

Multi-Agent Division of Labor: Modeler, Coder, Writer

MathModelAgent is not a single agent internally—it's a collaboration among three roles:

Modeler: analyzes the problem, selects models (AHP, TOPSIS, ARIMA, GA, etc.), outputs mathematical formulas and modeling reasoning
Coder: writes code based on the modeling plan, runs it, and generates charts
Writer: integrates modeling reasoning, code results, and figures into a paper, typeset per template

Each agent can use a different model—the modeler gets a strong reasoning model (e.g., Claude Opus), the coder a strong code model (e.g., GPT-4), the writer a strong writing model. This is heterogeneous model division of labor, not "one model does everything."

9-Step Acceptance: No Rookie Errors Allowed

"Rookie errors" in math modeling papers are fatal—wrong formulas, inconsistent data, missing figures, messy formatting. MathModelAgent's acceptance pipeline has 9 steps:

1. Text leak detection (no prompts or internal reasoning in the paper) 2. Numerical consistency checks (numbers in the paper must match code output) 3. Typst compilation (the paper must compile to PDF) 4. PDF visual inspection (the compiled PDF must look normal) 5–9. Other formatting and content checks

These 9 steps are an automated QA pipeline, not human review. The agent doesn't just write the paper—it reviews its own paper.

17 Typst Templates: Covering Major Contests

Contest paper format requirements are specific—each competition has its own template. MathModelAgent ships 17 Typst templates that auto-match the contest type.

Choosing Typst over LaTeX is an interesting judgment. Typst is a modern Rust-based typesetting system that compiles orders of magnitude faster than LaTeX with simpler syntax. For an agent, generating Typst source is easier than generating LaTeX source—simpler syntax, fewer errors, faster compile feedback.

HIL: Pausing for You at Key Points

Fully automated doesn't mean fully unmanned. MathModelAgent's HIL (Human-in-the-Loop) mechanism pauses at key nodes for user approval, with 6 decision actions:

confirm: approve and continue
edit: modify, then continue
regenerate: regenerate
ask: ask the agent a question
skip: skip this step
abort: terminate the entire run

This is "human on the loop" rather than "human in the loop"—you don't watch every step, only key nodes.

Four-Layer Fault Tolerance: When Agents Fail

Agents can't succeed 100% of the time. MathModelAgent's four layers:

1. Bounded retry: retry a few times on failure 2. Fallback hand-off: if retries fail, switch to a backup model 3. Evaluator shadow mode: a parallel evaluator scores output to catch quality issues 4. Feedback rerun: inject feedback and rerun

This is an engineering approach to fault tolerance—don't expect the agent to be right the first time; assume it will be wrong and design mechanisms to recover.

Desktop Version: Out of the Box

MathModelAgent has a desktop version (macOS / Windows) bundling Claude Code and the full SKILLS set. Users don't need Python, Node.js, or Redis—download the dmg/exe, install, enter an API key, and go.

This is a key step in agent productization: transferring the pain of environment setup from the user to the developer. The developer packages the entire runtime; the user just uses it.

Points Worth Noting

MathModelAgent isn't the most complex agent project, but it represents a trend:

1. SKILLS layer independent of the Harness layer—agent frameworks are being absorbed by Harnesses like Claude Code; domain knowledge lives in skill files 2. Multi-agent heterogeneous division of labor—different roles use different models instead of one model doing everything 3. Automated acceptance pipeline—the agent not only produces but also self-reviews 4. 6 HIL decision actions—fine-grained human-machine collaboration, not just "confirm/cancel" 5. Typst replacing LaTeX—an agent-friendly typesetting system: fast compilation, simple syntax, fewer errors

The project's deeper judgment: the future of agents isn't bigger models—it's better skill design. Model capability is already strong enough; the bottleneck is how to feed domain knowledge to models in a structured way. MathModelAgent does this with skill files, and the result is a 3-day contest finished in 1 hour.

Not every task can be compressed this way, but tasks with standard workflows, clear output formats, and verifiable quality standards all fit this pattern. Mathematical modeling is just the first vertical domain to be skill-ified.

---

GitHub: https://github.com/jihe520/MathModelAgent