Muhammad Faraz Malik
feat(deploy): configure Dockerfile and README YAML frontmatter for Hugging Face Spaces
c586b6e |
Download README.md from MF180/autonomous-bug-fixing-agent: direct link, hf CLI and curl.
- Browser
- Download file 7.87 kB
-
https://huggingface.co/MF180/autonomous-bug-fixing-agent/resolve/main/README.md
- Command line
-
hf download hf://MF180/autonomous-bug-fixing-agent/README.md
-
curl -L -o README.md https://huggingface.co/MF180/autonomous-bug-fixing-agent/resolve/main/README.md
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 | |
| [](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 | |