pyfix-agent 2.0.0

An autonomous, multi-turn AI debugging agent built from scratch using AST surgery.

PyFix Agent: Autonomous ReAct Debugging Loop

An autonomous, multi-turn AI debugging agent built entirely from scratch in Python.

Unlike standard wrappers that simply ask an LLM to "fix this code," PyFix Agent implements a custom ReAct (Reasoning and Acting) state machine and utilizes Abstract Syntax Tree (AST) manipulation to surgically patch Python files in real-time. It evaluates its own fixes by executing the code inside a subprocess, iterating dynamically until the script passes or it reaches the maximum iteration limit.

---

Installation

You can install PyFix Agent directly from PyPI:

pip install pyfix-agent

This will automatically register the pyfix-agent executable in your terminal path.

Install from Source

If you want to run or modify the source code locally:

# Clone the repository
git clone https://github.com/LightY-01/pyfix-agent.git
cd pyfix-agent

# Install package in editable mode
pip install -e .

Configuration

Export your Hugging Face Hub token to your environment variables to ensure secure API access:

Bash (Linux/macOS):

export HF_TOKEN="your_huggingface_token_here"

PowerShell (Windows):

$env:HF_TOKEN="your_huggingface_token_here"

---

CLI Usage Guide

Point the agent at any broken Python script. Use the --verbose flag to watch the ReAct state machine's internal thought process.

# Run the agent CLI
pyfix-agent --script my_broken_code.py --verbose --max_iter 5

# Run using a specific Hugging Face model
pyfix-agent --script my_broken_code.py --model "mistralai/Mixtral-8x7B-Instruct-v0.1" --verbose

CLI Command Options

Argument	Type	Default	Description
--script	str	Required	Path to the broken Python script to debug
--max_iter	int	5	Maximum number of debugging iterations
--verbose	flag	False	Enable logging of reasoning, tracebacks, actions, and observations in ReAct format
--model	str	Qwen/Qwen2.5-72B-Instruct:cheapest	Model endpoint ID on Hugging Face Serverless API

---

How It Works

1. Execution Engine: Runs the target script via Python subprocesses, capturing standard outputs, standard errors, and stack traces with safety timeout thresholds.
2. Context Memory: Maintains a chronological conversation history array, allowing the LLM to learn from its previously failed patching attempts without losing the original code context.
3. AST Surgery: Parses the LLM's response and uses Python's native ast.NodeTransformer to swap out broken function nodes with the corrected logic, leaving the rest of the file entirely untouched. It also automatically extracts and moves any newly declared import statements to the top level of the script.