File size: 7,869 Bytes
c586b6e 9925aa8 9fd94fe f9a912c b001ca7 9fd94fe cb00361 9925aa8 cb00361 9925aa8 cb00361 9925aa8 069c249 cb00361 9925aa8 cb00361 07e21d3 cb00361 9925aa8 cb00361 9925aa8 cb00361 9925aa8 c26f194 9925aa8 cb00361 9925aa8 875e34b 9925aa8 cb00361 9925aa8 cb00361 9925aa8 cb00361 9925aa8 cb00361 eb60226 cb00361 f9a912c b001ca7 f9a912c b001ca7 f9a912c b001ca7 f9a912c 5410c90 b001ca7 cb00361 9925aa8 cb00361 9925aa8 cb00361 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | ---
title: Autonomous Bug-Fixing Agent
emoji: 🐞
colorFrom: red
colorTo: indigo
sdk: docker
app_port: 8501
pinned: false
short_description: Autonomous Python Bug-Fixing AI Agent (LangGraph + Groq)
---
# Autonomous Bug-Fixing Agent
[](https://autonomous-bug-fixing-agent.streamlit.app)
- **Live Demo (AWS CloudFront HTTPS + EC2):** [https://d3gctx9v0f6g4u.cloudfront.net](https://d3gctx9v0f6g4u.cloudfront.net) ([http://98.89.45.201](http://98.89.45.201))
- **Live Demo (Streamlit Cloud):** [https://autonomous-bug-fixing-agent.streamlit.app](https://autonomous-bug-fixing-agent.streamlit.app)
An autonomous Python bug-fixing agent orchestrated with **LangGraph** and powered by **Groq**. It ingests a GitHub issue or bug report, inspects a repository, writes a failing `pytest` reproduction test, executes tests in an isolated sandbox, iterates on search/replace code fixes (up to 8 attempts), and **pauses for human-in-the-loop approval** before committing or exporting a patch.
## How It Works
```mermaid
flowchart TD
A[ingest_issue] --> B[inspect_repo]
B --> C[write_repro_test]
C --> D[run_repro_test]
D -->|fails as expected| E[propose_fix]
D -->|passes: not reproduced| C
E --> F[apply_fix] --> G[run_tests]
G -->|pass| H[human_approval -- interrupt]
G -->|fail, under 8 iterations| I[analyze_failure] --> E
H -->|approve| J[commit_and_pr]
H -->|reject + feedback| I
```
The full architecture specification is in [SPEC.md](SPEC.md).
## Core Agent Pillars
| Pillar | Implementation |
|---|---|
| **LLM** | Groq (`openai/gpt-oss-120b`) with structured JSON outputs ([`src/agent/llm.py`](src/agent/llm.py)) |
| **Framework** | LangGraph state machine & conditional edge routers ([`src/agent/graph.py`](src/agent/graph.py)) |
| **Memory** | `AgentState` + `MemorySaver` / `PostgresSaver` checkpointing ([`src/agent/state.py`](src/agent/state.py)) |
| **Tools** | Path-jailed Workspace, Git/GitHub REST API & Sandbox test runners ([`src/tools/`](src/tools/), [`src/sandbox/`](src/sandbox/)) |
## Key Features
- **LangGraph Orchestration ([src/agent/graph.py](src/agent/graph.py), [src/agent/state.py](src/agent/state.py)):** Explicit `TypedDict` state with Pydantic v2 sub-models, pure conditional edge routers, and `MemorySaver` / `PostgresSaver` checkpointing.
- **Groq Free-Tier Guardrails ([src/agent/llm.py](src/agent/llm.py), [src/agent/prompts.py](src/agent/prompts.py)):**
- `tenacity` exponential backoff for 429 rate-limit and transient API errors.
- Hard cap of 8 fix iterations (`RunBudget`).
- Active context pruning (`summarize_past_attempts`) and tail-truncated sandbox outputs to stay well under Groq's 8K tokens/min free tier.
- Structured JSON output validation with automatic repair.
- **Pluggable Sandbox ([src/sandbox/](src/sandbox/)):**
- `DockerSandbox` ([src/sandbox/docker_runner.py](src/sandbox/docker_runner.py)): Locked-down container (non-root user, `cap_drop=["ALL"]`, memory/CPU/PID limits, network disabled).
- `LocalSandbox` ([src/sandbox/local_runner.py](src/sandbox/local_runner.py)): Subprocess fallback for environments without a Docker daemon (e.g., Streamlit Community Cloud), with environment secret scrubbing and process-tree timeout kills.
- **Path-Jailed Workspace ([src/tools/file_tools.py](src/tools/file_tools.py)):** Works on an isolated copy (`base/` + `work/`) so your target repository is never modified until approval. Supports built-in sample repos, local folders, or shallow-cloning any GitHub repository URL.
- **Single-URL Repository Audit & PDF Report ([src/ui/streamlit_app.py](src/ui/streamlit_app.py), [src/ui/report_pdf.py](src/ui/report_pdf.py)):** Paste a single GitHub repository URL to scan all files for bugs/defects, view a side-by-side Before/After diff and live telemetry bar, and download a printable PDF audit & fix report.
- **Human-in-the-Loop Gate ([src/agent/nodes.py](src/agent/nodes.py)):** `commit_and_pr` is reachable **only** after `human_approval` resumes from `langgraph.types.interrupt()`.
## Project Layout
```
src/
agent/ state.py · llm.py · prompts.py · nodes.py · graph.py
sandbox/ base.py · docker_runner.py · local_runner.py · factory.py · Dockerfile
tools/ file_tools.py · git_tools.py
ui/ streamlit_app.py · mock_graph.py · report_pdf.py
tests/
unit/ test_state.py · test_docker_runner.py · test_routing.py · test_mock_graph.py · test_streamlit_app.py
fixtures/ buggy_repo/
deploy/ cloudshell_deploy.sh · ec2_userdata.sh
Dockerfile · docker-compose.yml · SPEC.md · requirements.txt · pyproject.toml
```
## Getting Started
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # Linux/macOS: source .venv/bin/activate
pip install -e ".[dev,ui]"
copy .env.example .env # Set GROQ_API_KEY in .env
```
Optional — build the Docker sandbox image if running with Docker:
```bash
docker build -t bugfix-agent-sandbox:latest src/sandbox
```
## Running the Streamlit Web App
```bash
streamlit run src/ui/streamlit_app.py
```
In the sidebar you can:
1. Choose **Live Groq Agent** or **Scripted Demo (no API calls)**.
2. Select a repository source (**Built-in sample buggy repo**, **Local folder path**, or **GitHub URL (shallow clone)**).
3. Enter the bug title & description, then click **▶️ Start run**.
4. Review the generated reproduction test, unified diff, and pytest output when the agent pauses at `human_approval`, then click **Approve**, **Request changes**, or **Reject**.
### Deploying to AWS Free Tier (EC2 + CloudFront HTTPS + S3 + DynamoDB + Lambda)
Run the one-command bootstrap scripts in **AWS CloudShell** ([`deploy/`](deploy/)):
```bash
# 1. Launch EC2 Docker instance
curl -sSL https://raw.githubusercontent.com/farazmalik180/autonomous-bug-fixing-agent/main/deploy/cloudshell_deploy.sh | tr -d '\r' | GROQ_API_KEY="gsk_..." bash
# 2. Provision CloudFront HTTPS CDN
curl -sSL https://raw.githubusercontent.com/farazmalik180/autonomous-bug-fixing-agent/main/deploy/aws_https_cloudfront.sh | tr -d '\r' | bash
# 3. Provision S3 Report Bucket, DynamoDB Run History & Lambda Webhook
curl -sSL https://raw.githubusercontent.com/farazmalik180/autonomous-bug-fixing-agent/main/deploy/aws_free_tier_stack.sh | tr -d '\r' | bash
```
- **Live AWS CloudFront HTTPS URL:** [https://d3gctx9v0f6g4u.cloudfront.net](https://d3gctx9v0f6g4u.cloudfront.net)
- **Live AWS EC2 Direct URL:** [http://98.89.45.201](http://98.89.45.201) ([http://98.89.45.201:8501](http://98.89.45.201:8501))
- **Live AWS Lambda Webhook URL:** [https://xmo5agqoh4bd7gkxaahbbpiqi40mjqst.lambda-url.us-east-1.on.aws/](https://xmo5agqoh4bd7gkxaahbbpiqi40mjqst.lambda-url.us-east-1.on.aws/)
- **AWS S3 Archive Bucket:** `s3://bugfix-agent-reports-706999906997-us-east-1`
- **AWS DynamoDB History Table:** `BugFixAgentRuns`
### Deploying to Streamlit Community Cloud
1. Push this repository to GitHub.
2. In [share.streamlit.io](https://share.streamlit.io), create a new app pointing to `src/ui/streamlit_app.py`.
3. Under **App settings → Secrets**, add:
```toml
GROQ_API_KEY = "gsk_..."
SANDBOX_BACKEND = "local"
```
## Running the Tests
```bash
pytest
```
Tests marked `docker` execute real containers and are **skipped automatically** when no Docker daemon is reachable.
## Roadmap
- [x] **Phase 0:** Architecture specification (`SPEC.md`) & project scaffolding
- [x] **Phase 1:** `state.py` & `docker_runner.py` with unit tests
- [x] **Phase 2:** Path-jailed `file_tools.py`, `git_tools.py`, and `local_runner.py`
- [x] **Phase 3:** Groq client (`llm.py`), context pruner (`prompts.py`), LangGraph `nodes.py` & `graph.py`
- [x] **Phase 4 & 5:** End-to-end verification on `tests/fixtures/buggy_repo` & interactive Streamlit UI
|