# MathModelAgent Work Directory Structure: Standard Layout for Modeling Tasks

> Understand the standard MathModelAgent work directory structure at backend project work dir task id. Learn about notebook.ipynb execution logs and res.md for your final report.

- Repository: [Sanjin/mathmodelagent](https://github.com/jihe520/mathmodelagent)
- Tags: how-to-guide
- Published: 2026-03-04

---

**The standard MathModelAgent work directory is created under `backend/project/work_dir/<task_id>/` and contains `notebook.ipynb` for execution logs and [`res.md`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/res.md)** — The final markdown-formatted report assembled by the Writer Agent
- **`res.docx`** — Optional Word document converted from the markdown report
- **[`res.json`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/common_utils.py). When a new task arrives, the backend executes:

```python
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`](https://github.com/jihe520/mathmodelagent/blob/main/backend/app/tools/notebook_serializer.py) (lines 8‑35). This serializer initializes the notebook path by joining the work directory with the filename:

```python
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`](https://github.com/jihe520/mathmodelagent/blob/main/res.md) through the `UserOutput` class in [`backend/app/models/user_output.py`](https://github.com/jihe520/mathmodelagent/blob/main/backend/app/models/user_output.py). The `save_result()` method (lines 58‑60) writes the markdown file directly into the work directory:

```python
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`](https://github.com/jihe520/mathmodelagent/blob/main/common_utils.py) (lines 90‑107) when Word document export is requested
- **[`res.json`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/backend/app/main.py) (lines 48‑52):

```python
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`](https://github.com/jihe520/mathmodelagent/blob/main/.../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`](https://github.com/jihe520/mathmodelagent/blob/main/common_utils.py)
- **`notebook.ipynb`** stores executable code history via `NotebookSerializer` for full reproducibility
- **[`res.md`](https://github.com/jihe520/mathmodelagent/blob/main/res.md)** contains the final formatted report written by `UserOutput.save_result()` in [`user_output.py`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/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`](https://github.com/jihe520/mathmodelagent/blob/main/res.md) accessible via direct HTTP requests at paths like `/static/<task_id>/res.md`.