Maintainability-Aware Code Generation Pipeline (MACGPi)

MACGPi is a maintainability-focused, LLM-powered code generation pipeline designed to produce production-quality, testable, and well-documented software artifacts. It is built to run with the mini-swe-agent orchestration and integrates prompt templates, phase schemas, and validation tooling to guide generation, evaluation, and iteration.

MACGPi requires a separate vLLM server running to communicate with. This is not orchestrated by the architecture.

Key Features

• Maintainability-first prompts and schemas for reproducible artifact generation
• Phase-based pipeline (planning, implementation, evaluation) with JSON schemas
• Templates and evaluators to produce structured outputs and machine-validated results
• Lightweight integration with batch runners and local experimentation

Repository Layout

• macgpi/ — core package and prompts used by the pipeline
• prompts/ — phase templates and JSON schemas.
• configs/ — configuration files.

See the prompts directory for examples and canonical templates:

• prompts/01_plan/schema.json
• prompts/03_evaluate/template.md
• prompts/03_evaluate/schema.json

Getting Started

Prerequisites

• Python 3.10+ recommended (or the project's specified environment)
• Conda/Anaconda is commonly used in this workspace for environment management

Quick local steps

1. Create or activate a Python environment (optional):

conda create -n macgpi python=3.10 -y
conda activate macgpi

2. Install project dependencies (if a requirements.txt or pyproject.toml exists):

pip install -r requirements.txt

3. Ensure a vLLM server is running with the required LLM.

4. Run MACGPi

python3 -m macgpi <problem description> <model name> <output directory> [options] 

CLI parameters

Required parameters

• input (str): The input prompt/problem description which MACGPI should solve as a string.
• model_name (str): The model name of an LLM that the vLLM server is hosting. A list of models for your vLLM server can be found by calling GET <model_host>:<model_port>/v1/models.
• output_dir (str): The destination of the produces code and documentation artifacts.

Optional parameters

• --model-host (str): The hostname of the local vLLM server (default "localhost").
• --model-port (int): The port of the local vLLM server (default 8000).
• --prompt-dir (str): The directory in which the phases and their corresponding prompts/schemas are located (default macgpi/prompts).
• --model-config (str): The path to the config file for the LLM (default macgpi/configs/model.config.yaml, containing the default mini-swe-agent model config). See this page for more information.
• --agent-config (str): The path to the config file for the agent (default macgpi/configs/agent.config.yaml, containing the default mini-swe-agent agent config). See this page for more information.
• --log-level (str): The verbosity of MACGPi and underlying models. Either DEBUG, INFO, WARNING, or ERROR (default INFO)

Working with Prompts and Schemas

• Templates live in prompts/ and are paired with machine-readable schemas to constrain output. The implement and revise phases do not require a schema.
• Each phase has a subdirectory under the prompts directory, which the phase config points to.

Customizing prompts

MACGPi is customizable. You can swap the system prompts for your own prompts using the same phase design or even design your own phase pipeline.

Assigning the --prompt-dir to a different prompt directory redirects MACGPis engine to use the custom prompts. Each phase should have a subdirectory with a prompt and schema, as defined in the phase config. The inputs for the prompts can only be altered by updating the MACGPi pipeline configuration.

The default inputs can be seen in the table below. All phases are provided a output_dir argument, containing the generated artifact root. The prompts can use this argument or ignore it. All phases that make use of an output schema have the schema_format and output_file inputs. The schema is always taken from the phase directory, and the output file is defined per phase in the MACGPi pipeline configuration. The rest of the inputs change per phase.

Phase	Inputs
01_plan	system_prd (project description)
02_implement	system_prd (project description), implementation_plan (path to the implementation plan generated by phase 01_plan)
03_evaluate	system_prd (project description), implementation_plan (path to the implementation plan generated by phase 01_plan)
04_revise	system_prd (project description), implementation_plan (path to the implementation plan generated by phase 01_plan), evaluation_report (path to the evaluation report generated by phase 03_evaluate)

Respecting these inputs, the prompt can be modified at will.

Pipeline configuration

Fully customizing the MACGPi pipeline is possibly by editing the phase config (default macgpi/configs/macgpi_phases.json) and assigning a custom prompt directory with the --prompt-dir argument.

Configuration format

The configuration is a JSON format, containing the single top-level objects, entry, and phases.

The entry property contains a string containing the entry point of the application. This should be equal to a phase configured in the phases object. If not present, the first phase in the phases list is used as the entry point.

The phases object is required and contains the definitions of all MACGPi phases. The first phase in this object is the entry point for the pipeline. After that the definitions decide the flow of the pipeline. Each phase object defines its inputs, outputs, subsequent phase, prompt location, etc. A full list of object properties is shown below.

• inputs: A list of files (relative to the artifact root) which are the inputs to the prompt. The name used as the key is the name with which it will be accessible in the prompt. E.g. "system_prd": "path/to/prd" (see phase_1 in the example configuration) means that the contents of the file located at path/to/prd will be accessible in the prompt using {{ system_prd }}.
• path: The path (relative to the prompt directory) of the phase prompt(s) and, optionally, the schema file. Note that phases can contain multiple prompts (see MultiPrompt Phases).
• schema: Whether or not the output must adhere to a schema. This schema is expected to be readable in a schema.json file located in path.
• output_file: The path (relative to the artifact root), to which the output file will be written.
• next: The name of the phase which should be visited after this phase is completed. If empty or finish, MACGPi will terminate. A special dynamic value is reserved for LLM-decided phase flow. With this option, the LLM output will decide the next phase. If dynamic is used, the output schema MUST contain a next value, with the name of the next phase (or finish for termination), decided by the LLM. This means that dynamic can ONLY be used when the phase makes use of a schema.
• max_visits: The maximum amount of times a phase is allowed to be visited. If this limit is exceeded, the pipeline stops. If not provided, a maximum of 1 is inferred.
• max_visits_exceeded_next: The phase that will be entered in the max_visits is exceeded. This should only happen if next is dynamic, or next is the current phase.

An example configuration can be seen below.

{
    "entry": "phase_1",
    "phases": {
        "phase_1": {
            "inputs": {
                "system_prd": "path/to/prd"
            },
            "schema": true,
            "path": "phase_1/",
            "output_file": "path/to/phase1_output",
            "next": "phase_2"
        },
        "phase_2": {
            "inputs": {
                "system_prd": "path/to/prd",
                "phase_1_output": "path/to/phase1_output"
            },
            "schema": false,
            "path": "phase_02/",
            "next": "dynamic",
            "max_visits": 5,
            "max_visits_exceeded_next": "finish
        },
    }
}

Multiprompt phases

In some cases, you might want to perform multiple distinct prompts in the same phase. For example, using Structured Chain-of-Thought (SCoT) requires two prompts, one for generating the SCoT and another for translating it to functional code. It can be argued that those two prompts belong to the same phase, the implementation phase.

With MACGPi multiprompt phases are possible. By simply adding more template files to the path directory. All template files should have the format template*.md, that is, they should be markdown files starting with template.

MACGPi reads all files conforming to this structure and runs them in alphabetical order. It is therefore recommended, but not strictly enforced, to format the templates as follows:

• template_01_<description>.md
• template_02_<description>.md
• template_03_<description>.md
• etc.

This is to prevent confusion of execution order.