Metadata-Version: 2.4
Name: pyfix-agent
Version: 2.0.1
Summary: An autonomous, multi-turn AI debugging agent built from scratch using AST surgery.
Author: Jaswin Reddy
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: huggingface_hub>=0.20.0

# 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:

```bash
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:

```bash
# 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):**
```bash
export HF_TOKEN="your_huggingface_token_here"
```

**PowerShell (Windows):**
```powershell
$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.

```bash
# 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.
