MathModelAgent Work Directory Structure: Standard Layout for Modeling Tasks

The standard MathModelAgent work directory is created under backend/project/work_dir/<task_id>/ and contains notebook.ipynb for execution logs and res.md for the final report, along with optional Word documents and raw JSON outputs.

MathModelAgent is an open-source framework for automated mathematical modeling that organizes every task inside a dedicated workspace. When you submit a modeling problem, the backend generates a unique task-specific directory that houses all code execution records, final reports, and uploaded datasets. Understanding this MathModelAgent work directory structure is essential for debugging agent outputs and retrieving generated assets.

Standard Directory Layout Overview

Every modeling task receives its own isolated workspace under the path:

backend/project/work_dir/<task_id>/

The task_id is a unique identifier generated by create_task_id() (e.g., "20250428-200915-ebc154d4"), and the physical directory is created by create_work_dir() in backend/app/utils/common_utils.py lines 21‑28. This directory serves as the central repository for all artefacts produced by the Coder Agent, Writer Agent, and data processing tools.

A complete task directory typically contains:

• notebook.ipynb — A Jupyter notebook recording every code cell executed by the Coder Agent
• res.md — The final markdown-formatted report assembled by the Writer Agent
• res.docx — Optional Word document converted from the markdown report
• res.json — Raw JSON representation of segmented responses for debugging
• Data files — Uploaded datasets (.csv, .xlsx) copied into the directory for interpreter access
• static/ mount — The entire work_dir is served as static files via FastAPI

The README explicitly documents this layout, naming notebook.ipynb and res.md as the two primary deliverables (lines 61‑64).

Creating the Work Directory

The directory initialization happens through utility functions in common_utils.py. When a new task arrives, the backend executes:

from app.utils.common_utils import create_work_dir, create_task_id

task_id = create_task_id()                     # e.g., "20250428-200915-ebc154d4"

work_dir = create_work_dir(task_id)            # → "project/work_dir/20250428-200915-ebc154d4"

The create_work_dir() function constructs the path under project/work_dir and ensures the folder exists before any agents begin writing files.

Core Output Files Explained

notebook.ipynb (Execution Log)

The Coder Agent persists every code execution into notebook.ipynb using the NotebookSerializer class defined in backend/app/tools/notebook_serializer.py (lines 8‑35). This serializer initializes the notebook path by joining the work directory with the filename:

from app.tools.notebook_serializer import NotebookSerializer

serializer = NotebookSerializer(work_dir=work_dir)   # Creates notebook.ipynb inside work_dir

As implemented in lines 28‑36, the serializer sets self.notebook_path = os.path.join(work_dir, notebook_name), ensuring all code cells, outputs, and errors are captured for reproducibility.

res.md (Final Report)

The Writer Agent assembles the final modeling report into res.md through the UserOutput class in backend/app/models/user_output.py. The save_result() method (lines 58‑60) writes the markdown file directly into the work directory:

from app.models.user_output import UserOutput

output = UserOutput(work_dir=work_dir, ques_count=3, data_recorder=None)

# ... populate agent responses ...

output.save_result()                               # Writes res.md to work_dir

This method specifically targets os.path.join(self.work_dir, "res.md"), producing a human-readable document containing model-building steps, analysis, and conclusions.

Auxiliary Outputs

Beyond the core files, the directory may contain:

• res.docx — Generated via md_2_docx() in common_utils.py (lines 90‑107) when Word document export is requested
• res.json — Raw structured data saved alongside the markdown for programmatic access or debugging

Data Files and Static Access

Uploaded datasets are copied directly into the task directory so the Python interpreter can read them via relative paths. Additionally, the entire work directory tree is exposed to the frontend through FastAPI's static file mounting in backend/app/main.py (lines 48‑52):

app.mount(
    "/static",
    StaticFiles(directory="project/work_dir"),
    name="static",
)

This configuration makes every task's assets reachable at http://<host>/static/<task_id>/notebook.ipynb or .../res.md, enabling direct download of results.

Summary

• The MathModelAgent work directory structure is rooted at backend/project/work_dir/<task_id>/, created by create_work_dir() in common_utils.py
• notebook.ipynb stores executable code history via NotebookSerializer for full reproducibility
• res.md contains the final formatted report written by UserOutput.save_result() in user_output.py
• Optional Word documents and JSON debug files accompany the core outputs
• The directory is mounted as static files in FastAPI, allowing direct HTTP access to generated artefacts

Frequently Asked Questions

Where is the MathModelAgent work directory physically located?

The work directory is created under backend/project/work_dir/<task_id>/ relative to the application root, as implemented in app/utils/common_utils.py. The task_id is a unique timestamp-based identifier generated by create_task_id().

What is the purpose of notebook.ipynb?

The notebook.ipynb file serves as a complete execution log of the Coder Agent's activity. It captures every code cell, output, and error message through the NotebookSerializer class, allowing users to replay or debug the modeling process step-by-step.

How does the final report get saved to res.md?

The UserOutput class in app/models/user_output.py provides the save_result() method, which assembles the Writer Agent's responses into markdown format and writes the file to res.md inside the task's work directory. This occurs automatically when the agent workflow completes.

Can generated files be downloaded directly?

Yes. The backend mounts the entire work_dir as a static directory in FastAPI (/static endpoint), making files like notebook.ipynb and res.md accessible via direct HTTP requests at paths like /static/<task_id>/res.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}