MathModelAgent: a SKILLS-driven math modeling pipeline that ends in a Typst PDF

The problem MathModelAgent targets: three days of competition work compressed into one command

Mathematical modeling competitions give teams a fixed window, often three days, to read a problem, choose a model, write code, produce figures, and typeset a paper that judges will read. The README states the project's stated goal directly: turning the three-day competition window into one hour and automatically producing a complete paper at award level. That framing tells you who the project is for. It is not a general numerical library and it is not a notebook assistant. It is aimed at competitors and students who already know what a modeling paper looks like and want the mechanical parts handled: problem decomposition, code generation, plot production, and paper layout in a submission-ready format.

The README also records the author's own history with the problem. Two years earlier the author built a multi-agent math modeling project and open sourced it. MathModelAgent is the successor, and the design has shifted. Instead of shipping a full agent framework, the project now distills itself into SKILLS and states that it will no longer build a harness layer. That decision shapes everything else about how you install and run it.

SKILLS instead of a harness: what actually executes when you type /1start-mathmodel

The architecture is the most distinctive thing about this project, and it is also the part most likely to confuse someone arriving from a conventional Python package. MathModelAgent does not ship its own agent loop. The README says the project has been distilled so that it is entirely SKILLS-driven and that it no longer builds a harness layer. Execution happens inside a host harness, and the README gives Claude Code and Codex as the two examples, with the invocation forms claude --dangerously-skip-permissions followed by /1start-mathmodel, and codex --yolo followed by $start-mathmodel.

Inside that harness the work is split into stages, and the README describes each stage as an independent Skill that can also be called on its own, for example running only the analysis or only the paper writing. The stages named in the README run from problem analysis through modeling, coding, plotting, paper typesetting and acceptance, chained automatically after the single start command. The multi-agent framing survives in the form of named roles (modeling hand, coding hand, paper hand) and in multi-LLM support, where each agent can be pointed at a different model. Model access is routed through litellm, which the README says covers all providers. The stated cost argument is that the workflow is agentless and does not depend on an agent framework, so the token budget goes into the task rather than into framework overhead.

Two ways to run it: a signed desktop build and a SKILLS install for developers

The README pushes the desktop build first. It bundles Claude Code and the full MathModelAgent SKILLS, so the README says you do not need Python, Node.js or Redis, and you do not configure SKILLS by hand. You install it, enter one model API key, and start. Release artifacts follow the platform split: mathmodel-<version>-arm64.dmg for Apple silicon Macs, mathmodel-<version>-x64.dmg for Intel Macs, and mathmodel-<version>-x64.exe for 64-bit Windows. The README states that the macOS packages are Developer ID signed and notarized by Apple, while the Windows package is currently unsigned, so first launch may trigger a Microsoft Defender SmartScreen prompt. The desktop app checks for updates automatically; the README notes automatic updates work on macOS and are pending on Windows until a code signing certificate is configured.

For developers the install is a single command that pulls the skills into the harness: npx skills add jihe520/MathModelAgent --all. Two supporting commands are documented, /doctor for checking the environment configuration and /typst-author for Typst knowledge. The sibling repository sci-box installs the same way with npx skills add jihe520/sci-box and supplies scibox-figure for scientific chart templates in Python and Matplotlib exporting PNG, PDF or SVG, plus scibox-diagram for editable draw.io templates covering a five-layer technical roadmap, a three-column research framework, a three-column flowchart and a horizontal task pipeline.

There is also a self-hosted path that predates the SKILLS reorganization and is documented in the README. Docker is the recommended option: run docker-compose up in the project folder, then reach the frontend at http://localhost:5173 and the backend API at http://localhost:8000, with the API key set from the sidebar under the avatar. The manual route requires Python, Node.js and Redis, then cd backend, pip install uv, uv sync, and on the frontend npm install -g pnpm followed by pnpm i. Environment variables are ENV=DEV and REDIS_URL=redis://localhost:6379/0. Redis starts with redis-server, and the backend starts with uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws-ping-interval 60 --ws-ping-timeout 120 --reload. Windows users can instead double-click win_start.bat. The README notes the CLI version lives on the master branch, is simpler to deploy, and will not be updated in future.

Typst templates, a modeling knowledge base, and the 9-step acceptance pass

The concrete output of the pipeline is a PDF, and the formatting layer is where the project has the most specific material. The README says 17 Typst paper templates ship with the project, covering mainstream Chinese and international competitions including 国赛, 华数杯, 华为杯 and MCM/ICM, and that the correct template is matched automatically to the competition type. The author notes the templates were converted from open source LaTeX templates into Typst, which is a reasonable explanation for why the set is broad rather than hand-built one at a time.

Alongside the templates there is a built-in modeling knowledge base. According to the README it contains modeling conventions, a model selection decision tree covering methods such as AHP, TOPSIS, ARIMA and GA, common error patterns, and the MCM/ICM scoring criteria. Each stage consults it automatically. The stated purpose is to reduce model hallucination, which is the right thing to be worried about when an LLM is choosing a method for you.

The acceptance stage is described as 9 automated checks: text leakage detection, numerical consistency validation, Typst compilation, and PDF visual inspection, with the goal of catching basic errors before submission. Text leakage detection is the interesting one, because it implies the pipeline checks whether prompt or reasoning text has bled into the paper body, which is a failure mode specific to LLM-generated documents. Numerical consistency validation addresses the other common failure, where a number in the abstract does not match the number in the results table.

What the roadmap admits is not finished

The roadmap is unusually candid and it should be read before you plan around any feature. Several items that appear in the feature list are marked in the roadmap as incomplete. Human in loop is the clearest case: the feature list advertises six decision actions (confirm, edit, regenerate, ask, skip, abort), while the roadmap marks the item unchecked with a comment that the data model is implemented but workflow integration is incomplete. Feedback, meaning evaluator scoring plus feedback injection to rerun the writer and then the coder, is unchecked with a comment that the core logic is not implemented and only a TODO comment exists in the agent base class. The four-layer fault tolerance advertised in the feature list (bounded retry, fallback hand off, evaluator shadow mode, feedback rerun) maps to the A2A hand off roadmap item, which is unchecked with a comment that both the configuration and the core logic are unimplemented, leaving only basic retry. RAG is unchecked with a comment that only configuration exists and the retrieval logic is not implemented. Web search is unchecked, and the comment says the originally planned Tavily API was not implemented and OpenAlex is used instead.

The README also carries a caution block stating the project is in an experimental demo stage with many areas to improve, and that the author is busy and will optimize when time allows. English support for MCM is listed as unfinished, LaTeX template integration is unfinished, and R and MATLAB support are unfinished. The project's own contribution guide narrows the future scope further: it says the project will only iterate on the SKILLS layer and will not build anything else. That is a useful boundary. If you want a supported Python library with a stable API, this is the wrong project, and the roadmap is the evidence.

Where a harness-based design breaks down

The harness dependency is the sharpest limitation. Because the project deliberately does not ship its own agent loop, everything runs inside Claude Code or Codex, and the documented invocations include flags that disable permission prompts. That is a deliberate trade for unattended runs, but it means the pipeline executes generated code and file writes without asking. The README's own Docker section recommends Docker as the safe and simple option, and the two recommendations sit in tension: the SKILLS path is the one the project is actively developing, and it is also the path with the least sandboxing guidance.

The stage boundaries are also only as good as the harness. The README says stages can be called individually, which is useful when you want to rerun only the paper, but there is no documented mechanism in the supplied material for resuming a partially completed run after a failure, and the fault tolerance that would cover that case is exactly the part the roadmap marks unimplemented. A long run that dies in the coding stage is therefore a manual restart, not an automatic recovery.

Finally, the acceptance pass is described but not specified. The README names the four categories of the 9 checks but does not say what thresholds trigger a failure or what happens when a check fails. Numerical consistency validation in particular has no stated tolerance, and without one it is hard to know whether small rounding differences between a table and the prose would be flagged. That is a gap worth probing in the repository rather than assuming.

How this differs from a general coding agent or a notebook assistant

The obvious alternative is to point a general coding agent at the problem and let it work. That agent can write Python and produce figures, and it may even produce a LaTeX file. What it does not carry is the domain layer. MathModelAgent's knowledge base encodes a model selection decision tree and the MCM/ICM scoring criteria, and its acceptance pass checks for text leakage and numerical consistency, which are failure modes that a general agent has no reason to look for. The Typst template set is the other difference: 17 competition templates matched automatically is a formatting asset a general agent would have to be handed.

The second alternative is the notebook route, which the README partially covers through the local code interpreter. That interpreter is described as Jupyter-based and saves code as notebooks so you can edit it afterward. That is a real advantage for inspection and a real disadvantage for automation, because a notebook expects a human to run cells and read outputs. If your goal is to understand the model rather than submit a paper, the notebook path gives you more control and the full pipeline gives you less. The project's own sibling sci-box is a third option worth noting: if all you need is the figures and diagrams, scibox-figure and scibox-diagram install independently and skip the modeling pipeline entirely.

Maintenance, licensing and what to check before the next competition

The release cadence visible in the metadata is fast, with v0.0.16 and then v0.0.17 plus a beta within roughly a day of each other in September 2026. For a project at version 0.0.x that is normal and it means you should expect the SKILLS interface to move. The desktop build mitigates this by auto-updating on macOS, but that also means the version you validated in a practice run is not necessarily the version you get on competition day. Pinning matters more here than in a typical library, and the README does not document a pinning mechanism for the SKILLS install path.

On licensing, the repository metadata supplied here reports the license as unknown, and the README does not state a license. The README does say the project is open source and free, and it credits open source LaTeX templates as the basis for the Typst conversions. Those two facts together are worth resolving before you redistribute the templates or ship a paper built from them inside a commercial product. The supplied material does not contain the license text, so the only honest step is to open the repository and read the LICENSE file, or the absence of one, directly. This is not legal advice and the terms of any upstream LaTeX template may differ from the project's own terms.

Before relying on this for a competition, three things are worth verifying in the repository itself: whether a LICENSE file exists, whether the HIL and RAG roadmap markers have moved, and whether the acceptance checks have documented thresholds. The /doctor command is the first thing to run after installation, and the example repository the contribution guide mentions is where community test cases and model comparisons are meant to accumulate.

Editorial conclusion

MathModelAgent is worth adopting if you already drive Claude Code or Codex from the terminal and want the modeling, coding, plotting and paper layout stages chained behind one command, with 17 Typst templates and a 9-step acceptance pass doing the formatting work. Skip it if you need a stable library API, if you cannot run a host harness, or if your competition requires LaTeX, because the roadmap still lists LaTeX template integration as unfinished. Before committing a weekend to it, run /doctor to confirm the environment, check the repository for a LICENSE file since the metadata reports the license as unknown, and read the roadmap markers for HIL, RAG and A2A hand off so you do not plan around features that are still TODO comments.

Official sources

1. Issues
2. jihe520/MathModelAgent on GitHub
3. Project website
4. README
5. Releases