🧠 AutoForge

⚡ Autonomous AI Software Engineer — Powered by LangGraph & Multi-Model LLMs (Groq, Gemini, OpenAI, Claude)

Plan → Code → Validate → Execute → Self-Heal

A fully autonomous, multi-agent software engineering system that plans, writes, validates, executes, and self-heals Python code inside an isolated Docker sandbox — powered by your choice of LLM (Groq, Gemini Free Tier, OpenAI GPT-4o, or Anthropic Claude).

---

🔥 Key Features

Feature	Description
🧠 Multi-Model Support	Choose your engine: Lightning-fast Groq (Llama), Free Tier Google Gemini, OpenAI GPT-4o, or Anthropic Claude 3.5. Configure seamlessly via .env.
🐳 Docker Sandbox Execution	All generated code runs inside ephemeral python:3.11-slim containers with 10s timeouts — your host machine is never at risk
⚡ WebSocket Live Terminal	Real-time streaming of Docker sandbox output directly to the UI, providing an interactive terminal experience
🔬 AST-Powered Validator	Self-healing code pipeline — an ast.NodeVisitor statically analyzes every generated script for unsafe operations, hardcoded secrets, and missing try/except blocks before execution
🐙 GitHub Integration	Autonomous repository navigation — the Coder can browse directories and read files from any GitHub repo using built-in PyGithub tools
🔍 Tavily Web Search	Real-time API documentation lookup via Tavily — with strict intent-routing to prevent tool over-triggering
🔄 Self-Healing Debugger	If code crashes in the sandbox, tracebacks are automatically fed back to a Debugger agent that rewrites stdlib-only fixes in a closed loop
💾 Persistent Memory	PostgreSQL-backed checkpointing — conversation state survives page reloads with sliding-window context injection
🖥️ Pro IDE Frontend	Modern Next.js frontend with live pipeline graph, syntax-highlighted code editor, real-time terminal, and seamless chat experience

---

🏗️ Architecture — The ReAct Pipeline

┌─────────────────────────────────────────────────────────────────────┐
│                    LangGraph State Machine                          │
│                                                                     │
│  START ──▸ Router ──┬──▸ Planner ──▸ Coder ──▸ Validator ──┬──▸ Terminal  │
│                     │         ▲              │               │      │      │
│                     │         └──────────────┘  (reject)     │      │      │
│                     │         (self-reflection loop)         │      ▼      │
│                     │                                        │  Debugger   │
│                     │                                        │      │      │
│                     │                                        └──────┘      │
│                     ├──▸ Research Agent ──▸ END                            │
│                     └──▸ Knowledge Agent ──▸ END                           │
└─────────────────────────────────────────────────────────────────────┘
                                     │
                   ┌─────────────────▼─────────────────┐
                   │     Docker Sandbox (ephemeral)      │
                   │     python:3.11-slim · 10s timeout  │
                   └────────────────────────────────────┘

🔁 How the Pipeline Works

1. 🧭 Router — Classifies user intent (coding / research / generic) to avoid unnecessary Docker spin-ups
2. 📋 Planner — Generates a mission brief with artifact targeting and strategy selection
3. 💻 Coder — Groq Llama 3.3 generates Python code using a ReAct tool-calling loop (GitHub + Tavily)
4. ✅ Validator — AST-based static analysis catches dangerous ops, secrets, and missing error handling
5. 🐳 Terminal — Executes validated code inside an ephemeral Docker container
6. 🔧 Debugger — Feeds tracebacks back for autonomous self-healing repairs (up to 5 attempts)

---

📋 Prerequisites

Requirement	Version	Purpose
Python	3.9+	Runtime
Node.js	18+	Frontend Runtime
Docker Desktop	Latest	Sandboxed code execution
PostgreSQL	16+ (via Docker Compose)	LangGraph state persistence
Groq API Key	—	🧠 Primary LLM engine (get one free)
Tavily API Key	—	🔍 Web search tool (get one free)
GitHub Token	—	🐙 Repository access (optional)

---

🚀 Quick Start

1️⃣ Clone & Install

git clone https://github.com/Harsh-Sharma29/AutoForge.git
cd AutoForge

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

2️⃣ Configure Environment

cp .env.example .env

Edit .env with your API keys:

# LLM Configuration (groq, gemini, openai, anthropic)
LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.5-flash

# API Keys (Provide the one corresponding to your LLM_PROVIDER)
GEMINI_API_KEY=AIza...
GROQ_API_KEY=gsk_your_groq_api_key_here
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

TAVILY_API_KEY=tvly-your_tavily_key_here
GITHUB_ACCESS_TOKEN=ghp_your_github_token_here

# Database (auto-configured by Docker Compose)
DATABASE_URL=postgresql://autoforge:autoforge@localhost:5432/autoforge?sslmode=disable
AUTOFORGE_API_URL=http://localhost:8005
NEXT_PUBLIC_API_URL=http://localhost:8005

3️⃣ Start Infrastructure

The quickest way to start the entire stack (Database, Backend, and Frontend) is via Docker Compose:

docker compose up -d --build

⚠️ Make sure Docker Desktop is running before this step.

4️⃣ Launch the Application (Manual Method)

If you prefer to run the components manually instead of using Docker Compose for everything:

Open two separate terminals:

Terminal 1 — 🖥️ FastAPI Backend:

cd backend
python -m uvicorn src.api.server:app --host 127.0.0.1 --port 8005

Terminal 2 — 🎨 Next.js Frontend:

cd frontend
npm install
npm run dev

5️⃣ Open the IDE

Navigate to http://localhost:3005, enter a coding prompt, and click 🚀 Execute Pipeline.

---

🤖 Multi-Agent System

Agent	Responsibility
🧭 Router	Intent classification — coding / research / generic — before any expensive work
📋 Planner	Mission brief, artifact targeting, and strategy selection
💻 Coder	Groq Llama 3.3 code synthesis with ReAct tool-calling loop and multi-file workspace output
✅ Validator	Pre-sandbox AST-based static analysis (dangerous ops, secrets, error handling)
🐳 Terminal	Docker sandbox execution with 10-second timeout
🔧 Debugger	Traceback-driven self-healing repair loop (stdlib-only rewrites)
📚 Research	Technical research answers (no sandbox)
💡 Knowledge	Generic Q&A (no sandbox)

---

🔒 Cyclic Loop Safeguards

Loop	Cap	Exit Condition
Coder ↔ Validator	3 attempts	Pass validation, or force Terminal
Coder ↔ ToolNode	3 rounds	Max tool-calling rounds reached
Terminal ↔ Debugger	5 attempts	is_verified=True, empty errors, or cap reached
LangGraph global	recursion_limit=50	Hard ceiling on total node invocations

---

📡 API Reference

Method	Endpoint	Description
GET	/api/v1/health	System health: Postgres status, API key status, telemetry
POST	/api/v1/session/new	Generate a new backend-authoritative thread_id
GET	/api/v1/history/{thread_id}	Retrieve conversation history for a session
POST	/api/v1/execute	Execute the LangGraph pipeline (SSE streaming response)

---

📁 Project Structure

AutoForge/ ├── docker-compose.yml # Full stack: Postgres + Backend + Frontend ├── .env.example # Environment template ├── backend/ │ ├── main.py # CLI LangGraph entry point │ ├── Dockerfile # FastAPI backend image │ ├── requirements.txt # Python dependencies │ └── src/ │ ├── api/ │ │ └── server.py # FastAPI backend — SSE streaming, endpoints │ ├── core/ │ ├── agents/ │ └── tools/ └── frontend/ ├── Dockerfile # Next.js frontend image ├── package.json # Node dependencies └── src/ # Next.js App Router code

---

⚙️ Configuration Reference

Variable	Required	Description
LLM_PROVIDER	✅	groq, gemini, openai, or anthropic
LLM_MODEL	✅	e.g. gemini-2.5-flash, gpt-4o, llama3-70b-8192
GEMINI_API_KEY	⚠️	Required if LLM_PROVIDER=gemini (Free Tier available)
GROQ_API_KEY	⚠️	Required if LLM_PROVIDER=groq
TAVILY_API_KEY	⚠️ Recommended	Tavily web search for real-time docs
GITHUB_ACCESS_TOKEN	❌ Optional	GitHub repository access
DATABASE_URL	✅	PostgreSQL connection string
AUTOFORGE_API_URL	✅	FastAPI backend URL (http://localhost:8000)
HUGGINGFACEHUB_API_TOKEN	❌ Optional	HuggingFace Hub token for failover LLM

---

🎯 Example Prompts

Type	Example	Pipeline Path
💻 Coding	Write a Python script that fetches JSON from an API and handles a missing items key.	Router → Planner → Coder → Validator → Terminal ↔ Debugger
🐙 GitHub	Read the README from langchain-ai/langchain and summarize it.	Router → Planner → Coder (GitHub tools) → Validator → Terminal
📚 Research	Explain how LangGraph conditional routing works.	Router → Research → END
💡 Generic	What are the trade-offs between monoliths and microservices?	Router → Knowledge → END

---

🔐 Security Model

Control	Status
Ephemeral containers (auto-removed)	✅
Read-only volume mount for scripts	✅
10-second execution timeout	✅
AST-based Validator (static analysis)	✅
API error payload interception	✅
Dangerous pattern detection (eval, exec, os.remove)	✅
Hardcoded credential detection	✅

Threat model: Suitable for trusted developer workflows and portfolio demonstrations.

---

📄 License

MIT

---

Built with ❤️ by Harsh Sharma

Powered by 🧠 Groq · 🦜 LangGraph · 🐳 Docker · 🐙 PyGithub · 🔍 Tavily