MathModelAgent: Multi-agent automation for Typst modeling papers
It automates code and Typst papers for modeling contestants while preserving Jupyter work, rather than only generating text.
GitHub jihe520/MathModelAgent Updated 2026-09-12 Branch main Stars 4.9K Forks 393
Python Vue Mathematical modeling Typst Claude Code Jupyter Redis Tavily ChromaDB

🧭 Decision Guide

Why trending now: Cannot be determined from the provided materials

Try it if you

  • You need to quickly generate Chinese or English contest papers using 17 Typst templates.
    The README “SKILLS / Intro” section states that 17 Typst paper templates are included for contests such as national contests, HuaShu Cup, Huawei Cup, and MCM/ICM.
  • You use Claude Code or Codex and want one command to connect the full modeling workflow.
    The README “Install & Usage” section provides `npx skills add jihe520/MathModelAgent --all` and runs the workflow with `/1start-mathmodel` or `$start-mathmodel`.
  • You need code saved in a Jupyter Notebook for later editing.
    The README “Features” section says the local Interpreter is based on jupyter and saves code as a notebook; deployment outputs include `notebook.ipynb`.
  • You want to enable Tavily search, a ChromaDB knowledge base, or HIL approvals.
    The README “New Feature Configuration” section lists the `SEARCH_ENABLED`, `RAG_ENABLED`, and `HIL_ENABLED` switches.

Skip it if you

  • You require the current system to guarantee a national-contest-winning paper.
    The README disclaimer explicitly says that its current level cannot directly win a national contest.
  • You cannot accept an experimental project with frequent changes and known bugs.
    The README “Contributing and Development” section describes it as experimental, with many changes and remaining bugs.
  • You must use a component with an explicitly defined commercial license or use the project commercially.
    Project metadata says the license is Not specified; the README “Copyright License” section says personal free use only and no commercial use.
  • Your Windows installation process cannot accept unsigned software or SmartScreen prompts.
    The README “Desktop Version” section warns that the Windows package is currently unsigned and may trigger Microsoft Defender SmartScreen.

Requirements

  • The desktop version requires a model API key; macOS provides `mathmodel--arm64.dmg` and `mathmodel--x64.dmg`, while Windows provides `mathmodel--x64.exe`.
  • The Docker option requires Docker and starts with `docker-compose up`.
  • Local deployment requires Python, Nodejs, and Redis; the backend uses `uv sync` and the frontend uses `pnpm i`.
  • Enabling Web Search requires a Tavily API key and `TAVILY_API_KEY=tvly-xxx` in `backend/.env.dev`.
  • The SKILLS method requires Claude Code or Codex; the README installation command is `npx skills add jihe520/MathModelAgent --all`.

First step (verbatim from README)

npx skills add jihe520/MathModelAgent --all

Watch out

  • The Windows package is unsigned; download it from the official Releases page and handle the SmartScreen prompt.
    The Windows installation warning in the README “Desktop Version” section.
  • The local backend requires `REDIS_URL=redis://localhost:6379/0` and a running `redis-server`.
    The environment variable and startup commands in the README “Local Deployment” section.
  • Web Search, RAG, and HIL are disabled by default and automatically skipped when external dependencies are not configured.
    The README “New Feature Configuration” section.
  • Runtime artifacts are stored under `backend/project/work_dir/xxx/*`, mainly including `notebook.ipynb` and `res.md`.
    The runtime output description in the README “Usage Tutorial” section.
  • The master branch has simpler CLI deployment, but the README says it will not be updated in the future.
    The master-branch note in the README “Usage Tutorial” section.

Alternatives

  • MathModelAgent Desktop Version：Use it when you do not want to install Python, Node.js, or Redis or configure SKILLS manually; the README recommends downloading the desktop version.
    README “Desktop Version (Recommended Usage)” section
  • Docker Deployment：Use it when you want to start the frontend and backend with one `docker-compose up` command and access `localhost:5173` and `localhost:8000`.
    README “Option One: Docker Deployment” section
  • Local Deployment：Use it when you need to modify the Python backend or Vue frontend or contribute to development, while maintaining Redis, Python, and Nodejs.
    README “Option Two: Local Deployment” section

Not stated in the README

  • The README does not specify supported model names, per-model API costs, or recommended model combinations.
  • The README does not provide the exact latest desktop Release version, package sizes, or hardware requirements.
  • The README does not provide a complete list of which contests are covered by the 17 Typst templates.
  • The README does not provide execution time, accuracy, or public benchmark results for the 9-step acceptance flow.
  • The README does not explain the actual costs or data-privacy boundaries of Tavily, E2B, and Daytona.
  • The README does not clarify whether generated papers receive manual factual verification or citation-quality evaluation.
  • Project metadata says License is Not specified, while the README references `docs/md/License.md`; their legal relationship requires further confirmation.

💡 Deep Analysis

6
Yes I use 64-bit Windows, have not installed Python, Node.js, or Redis, and only want to try the project quickly after configuring one model API key. Should I choose the desktop version?
For: A mathematical-modeling student on 64-bit Windows without Python, Node.js, or Redis, who only wants to try the desktop version quickly

Yes. A 64-bit Windows user who does not want to configure a development environment should start with the desktop build, but must handle the SmartScreen warning caused by the unsigned installer.

  • The README recommends the desktop version and says it bundles Claude Code and the complete MathModelAgent SKILLS. Python, Node.js, and Redis are unnecessary; after installation, one model API key is enough to start.
  • Windows 64-bit maps to mathmodel--x64.exe, avoiding the Redis, backend, frontend, and pnpm setup required by local deployment.
  • The README explicitly warns that the Windows installer is currently unsigned and may trigger Microsoft Defender SmartScreen. It instructs users to download from the official Releases page and select “More info” → “Run anyway.”
  • If the user later needs to modify source code or develop Skills, desktop is no longer the best path; the README positions local deployment for project developers.
  • Desktop edition: no Python, Node.js, or Redis required; only one model API key
  • Desktop edition: Windows 64-bit `mathmodel--x64.exe`
  • WARNING: the Windows installer is currently unsigned and may trigger Microsoft Defender SmartScreen
  • 方案二: local deployment is recommended for project developers
Not stated in the README：The README does not specify the minimum Windows version or installer checksums；It does not state whether the desktop version supports offline operation or local models
No I want to enable Tavily search, ChromaDB plus reranking, the six HIL actions, and fallback models in an existing modeling application. Is this already suitable as a production-grade quality-control solution?
For: A modeling-application developer wanting to improve paper quality with Tavily, ChromaDB plus reranking, HIL, and fallback models

No. It should not be used directly as a production-grade quality-control system; it is better treated as an experimental reference implementation that combines several quality mechanisms.

  • The README exposes SEARCH_ENABLED, TAVILY_API_KEY, RAG_ENABLED, HIL_ENABLED, and FALLBACK_*/EVALUATOR_* settings for web search, retrieval, human approval, fallback models, and feedback reruns.
  • HIL supports six actions—confirm, edit, regenerate, ask, skip, and abort. The SKILLS section also claims nine automatic acceptance steps, including leakage detection, numerical consistency, Typst compilation, and PDF checks.
  • However, the project is still labeled an experimental iterative demo, benchmark is listed in the roadmap, and no failure rate, throughput, cost, or real-problem evaluation is provided.
  • Tavily, model APIs, ChromaDB/reranking, and evaluators introduce external dependencies. Configuration availability does not prove that the quality gates have been production-validated.
  • New feature configuration: `SEARCH_ENABLED` + `TAVILY_API_KEY`, `RAG_ENABLED`, `HIL_ENABLED`, `FALLBACK_*`, `EVALUATOR_*`
  • SKILLS: nine automatic acceptance steps
  • HIL: supports confirm / edit / regenerate / ask / skip / abort
  • Roadmap: add benchmark
  • Video demo: “项目处于实验探索迭代demo阶段”
npx skills add jihe520/MathModelAgent --all
Not stated in the README：The README does not provide test coverage, error rates, latency, or cost for the quality mechanisms；It does not specify the reranker, evaluator scoring criteria, or production alerting behavior；The project data lists the license as Unknown, so licensing boundaries for commercial integration are unclear
Yes I already use Claude Code and Codex. I want replaceable SKILLS for modeling, coding, and paper stages, and I need to modify Typst templates for the national contest or MCM/ICM. Is this suitable as a workflow foundation?
For: An advanced user of Claude Code or Codex who wants to customize modeling workflows and contest templates through SKILLS

Yes. It is suitable because the modeling workflow is decomposed into independently callable SKILLS, with extensible templates and knowledge bases. However, it is a foundation template rather than a fully validated general workflow platform.

  • The README explicitly says it “no longer builds a Harness layer” and can be driven directly by Harnesses such as Claude Code and Codex.
  • /1start-mathmodel chains analysis, modeling, coding, plotting, paper formatting, and acceptance checks, while individual Skills can also run analysis or paper writing separately.
  • The project includes 17 Typst templates for the national contest, Huashu Cup, Huawei Cup, and MCM/ICM; templates, prompts, and knowledge bases are extensible.
  • The README also calls the Skill a “basic template,” while English support, LaTeX, vision models, and R/MATLAB remain in the roadmap. Thus Typst customization is a good fit, but other formats and languages should not be assumed mature.
  • SKILLS: driven entirely by SKILLS; no Harness layer
  • SKILLS: one `/1start-mathmodel` command completes the workflow
  • SKILLS: each stage is an independent Skill; templates and knowledge bases are extensible
  • SKILLS: 17 Typst paper templates
  • Thinking: “此 SKILL 是一个基础模板” / “This SKILL is a basic template”
npx skills add jihe520/MathModelAgent --all
Not stated in the README：The README does not define input/output contracts or version-compatibility rules for each Skill；It provides no regression results or benchmark across different Harnesses
It depends We are entering the Chinese national contest, have only 3 days, and want to use the desktop app on an Apple-silicon Mac to handle analysis, code, figures, and a Typst paper. Is this suitable as our direct submission tool?
For: A mathematical-modeling student team entering the Chinese National Undergraduate Mathematical Contest in Modeling, with only 3 days and wanting to use the desktop app to generate a Typst paper quickly

It depends: it is suitable for compressing the modeling workflow and producing a draft, but not for submitting an unchecked paper directly.

  • The SKILLS section covers problem analysis, modeling, coding, plotting, paper formatting, and acceptance checks, and provides 17 Typst templates, including a Chinese national-contest direction.
  • An Apple-silicon Mac can use mathmodel--arm64.dmg; the desktop version requires no Python, Node.js, or Redis installation, only a model API key.
  • The project explicitly describes itself as an “experimental iterative demo,” and its disclaimer says that winning the national contest directly with the current level is impossible. The team remains responsible for assumptions, data, code, and conclusions.
  • The nine-step acceptance flow checks numerical consistency, Typst compilation, and PDF visualization, but the README does not establish that mathematical conclusions meet contest-winning standards.
  • SKILLS: end-to-end automation; 17 Typst paper templates
  • Desktop edition: macOS Apple silicon `mathmodel--arm64.dmg`
  • Video demo: “项目处于实验探索迭代demo阶段”
  • Disclaimer: “目前水平直接参加国赛获奖是不可能的”
Not stated in the README：The README provides no accuracy, completion-time, or award-rate results on real national-contest problems；It does not specify whether the desktop build contains every latest SKILL and all 17 templates
It depends I supervise university research training, cannot let data leave the local environment, and want Jupyter notebooks for code history while disabling Tavily, E2B, and Daytona. Is this suitable for a private environment?
For: A university research-training instructor handling unpublished modeling data and wanting to disable web search and cloud execution

It depends. The project provides a local Jupyter interpreter and Docker/local deployment, giving it a basis for private use, but the README does not establish that all model calls and temporary files remain local.

  • The feature list says the local interpreter is Jupyter-based and saves code as notebooks, preserving the experiment process; Docker can provide the frontend and backend on the local machine.
  • Web Search, RAG, HIL, Fallback, and Evaluator are optional and disabled by default; when external dependencies are missing, they can be skipped automatically, reducing unnecessary external connections.
  • However, the project still requires a model API key and supports cloud code interpreters such as E2B and Daytona. Disabling search does not mean model providers will not receive prompts or data.
  • For unpublished data, API retention, logs, temporary files, and container behavior matter. The README provides no data-flow diagram or compliance commitment.
  • Features: local Interpreter is based on Jupyter and saves code as a notebook
  • New feature configuration: optional features are disabled by default and skipped when dependencies are unavailable
  • Features: cloud code interpreters include E2B and Daytona
  • Docker deployment: frontend `http://localhost:5173`, backend `http://localhost:8000`
docker-compose up
Not stated in the README：The README does not describe model-provider retention, training use, or regional-storage policies；It does not document cleanup for logs, temporary files, or sensitive data in notebooks；It does not prove that Docker mode blocks all outbound network requests
Yes I need to modify the Python backend and Vue frontend, and already have Node.js, Redis, pnpm, and uv. Should I choose local deployment rather than the desktop version?
For: A Python developer debugging MathModelAgent from source, with Node.js, Redis, pnpm, and uv available

Yes. Local deployment fits developers who need to modify the Python backend, Vue frontend, or workflow, although it requires substantially more environment coordination than the desktop build.

  • The README labels local deployment as “recommended for project developers,” requiring Python, Node.js, and Redis, with backend and frontend started separately.
  • Backend dependencies use uv sync, while the frontend uses pnpm; the development environment also requires ENV=DEV and REDIS_URL=redis://localhost:6379/0.
  • The source-based path allows direct changes to SKILLS, templates, prompts, and knowledge-base components, which suits customization. The project data also shows Python, Vue, TeX, Typst, and TypeScript as major components.
  • The tradeoff is that the README does not promise stable source interfaces. The current version is v0.0.19, and startup commands differ across Windows, macOS, and Linux. For usage without code changes, desktop or Docker is simpler.
  • 方案二：本地部署（推荐项目开发者部署）
  • Local deployment: install Python, Node.js, and Redis
  • Dependency installation: `uv sync`; frontend: `pnpm i`
  • Environment variables: `export ENV=DEV` and `export REDIS_URL=redis://localhost:6379/0`
  • Project data: latest release is v0.0.19; languages include Python, Vue, TypeScript, and Typst
docker-compose up
Not stated in the README：The README does not provide an exact compatibility matrix for source branch, Python, Node.js, and Redis versions；It does not document functional or version differences between the desktop and source builds

✨ Highlights

  • One /1start-mathmodel command runs a 9-step acceptance flow
  • Includes 17 Chinese and English Typst contest templates
  • Saves code in Jupyter and preserves notebook.ipynb results
  • Supports Tavily, ChromaDB, and 6 HIL actions
  • The project remains experimental, with README-documented bugs

🔧 Engineering

  • Uses multi-agents for analysis, coding, modeling, and paper layout
  • The local Interpreter uses Jupyter and saves editable notebooks
  • Typst templates generate formatted, submission-ready PDF papers
  • Optional Tavily search and ChromaDB with Rerank knowledge retrieval

⚠️ Risks

  • The README calls it experimental, with many bugs and frequent changes
  • The unsigned Windows package may trigger SmartScreen warnings
  • Local deployment requires Python, Nodejs, and Redis
  • The disclaimer says its current level cannot directly win national contests
  • License metadata is unspecified; README limits use to personal non-commercial use

👥 For who?

  • Modeling contestants who need Typst contest templates and automated papers
  • Developers willing to install SKILLS for Claude Code or Codex
  • Teams needing Jupyter execution traces and editable notebooks
  • Developers wanting WebUI deployment with Docker, Redis, and Vue