🤖 AI Software Engineer

Autonomous multi-agent pipeline: Planner → Architect → Coder → Tester ⇄ Debugger → Reviewer

Given a feature request, it plans, writes code + tests, runs them, self-debugs on failure (up to N retries), and produces a PR summary — optionally opening a real GitHub PR.

Built for free-tier tools only: Groq (free LLM API), GitHub REST API (free), local SQLite/files. No Docker, no Postgres, no paid keys required.

---

🧱 Stack

🕸️ LangGraph	Agent orchestration / conditional retry loop
⚡ Groq API (Llama 3.3 70B)	Free-tier LLM, or swap in local Ollama
🔌 MCP SDK	mcp_servers/terminal_server.py — a real MCP server exposing sandboxed shell execution (standalone or via any MCP client, e.g. Claude Desktop)
🐙 PyGithub	Free GitHub REST API wrapper for opening PRs
🚀 FastAPI	Optional HTTP wrapper (api.py)
✅ pytest	Test execution

---

⚙️ Setup (Mac, VS Code)

cd ai-swe-agent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env:

1. 🔑 Get a free Groq key: https://console.groq.com/keys
2. 🐙 (Optional, for real PRs) Create a GitHub PAT with repo scope: https://github.com/settings/tokens → set GITHUB_TOKEN and GITHUB_REPO=you/your-repo

If you skip the GitHub token, the agent still runs fully — it just writes code to ./workspace locally instead of opening a PR.

---

▶️ Run

python main.py "Add a function that validates email addresses using regex, with tests"

You'll see a live trace of each agent, then the generated PR summary. Code lands in ./workspace/.

🌐 Or via API

uvicorn api:app --reload

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"feature_request": "Add a function that reverses a linked list, with tests"}'

---

🔁 How the loop works

Planner → Architect → Coder → Tester ──pass──▶ Reviewer → (PR)
                                 ▲
                                 │ fail (retries left)
                                 ▼
                             Debugger

MAX_DEBUG_RETRIES (default 3) caps the Tester ⇄ Debugger loop so it can't run forever. If retries are exhausted, the Reviewer still runs and honestly reports the failure in the PR notes instead of pretending it passed.

---

🖥️ Using the terminal MCP server directly

python mcp_servers/terminal_server.py

This exposes run_command and list_workspace_files over MCP stdio — you can point Claude Desktop or any MCP client at it directly if you want an interactive session instead of the scripted pipeline. The pipeline itself calls pytest via a direct subprocess for speed/reliability; swap agents/tester.py to call this MCP server instead if you want a pure end-to-end MCP demo for interviews.

---

📁 Project structure

ai-swe-agent/
├── agents/              # planner, architect, coder, tester, debugger, reviewer
├── mcp_servers/         # terminal_server.py (real MCP server)
├── state.py             # shared LangGraph state schema
├── graph.py             # graph wiring + conditional retry edge
├── main.py              # CLI entrypoint
├── api.py               # optional FastAPI wrapper
├── requirements.txt
└── .env.example

---

🎤 Notes for demo/interview framing

• 🔍 Every agent is a single, inspectable LLM call + tool call — easy to explain node by node.
• 🔁 The Tester ⇄ Debugger conditional edge is the "interesting" LangGraph concept to walk through.
• 🖥️ Swap ChatGroq for ChatOllama in agents/common.py for a fully offline/local demo.