Muhammad Faraz Malik
feat(deploy): configure Dockerfile and README YAML frontmatter for Hugging Face Spaces
c586b6e
|
Raw History Blame Contribute Delete
7.87 kB
---
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