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

[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](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