README.md

---
title: AI-Agentic-Coder
app_file: src/ai_agentic_coder/main.py
sdk: gradio
sdk_version: 6.14.0
---

# AI Agentic Coder

[![Live Website](https://img.shields.io/badge/Live_Website-6c63ff?logo=rocket&logoColor=white&labelColor=5a52d3)](https://projects.kaushikpaul.co.in/ai-agentic-coder)

An AI-powered agentic coding assistant that:
- Turns your natural language requirements into a working Python module
- Designs the module, implements the code, writes simple tests, and builds a demo UI
- Packages the output and launches the generated Gradio app with a public URL

Backed by a multi-agent CrewAI pipeline, the app coordinates “engineering lead”, “backend”, “frontend”, “QA”, and a “runner” agent to deliver end-to-end results.

## Live Demo
- Visit the hosted Space: https://projects.kaushikpaul.co.in/ai-agentic-coder

## Features
- **Idea → Running App in Minutes**
  - One-click pipeline: design the module → implement code → generate tests → scaffold a Gradio demo → auto-package into a zip → upload to Google Cloud Storage → launch the app → return live/public URLs.
- **Multi‑Agent Orchestration (CrewAI)**
  - Specialized agents for engineering lead, backend, frontend, QA, and runtime. Tasks are declared in YAML and executed sequentially for predictable outcomes.
- **Production‑Friendly Reliability**
  - Built‑in retry limits and execution timeouts for coding/testing agents, plus automatic cleanup of previous app processes to avoid port conflicts.
- **Model‑Flexible by Design**
  - Switch between OpenRouter and OpenCode Go from `.env`. Models are configured with environment variables instead of hardcoded YAML values.
- **Modern Developer UX**
  - Polished Gradio UI with non‑blocking background execution, streaming progress, one‑click example loader, and strict URL extraction/validation on completion.
- **Secure Artifact Delivery**
  - Packages all generated code and dependencies into a zip file, uploads to Google Cloud Storage, and returns a time-limited, signed download URL. The app is automatically launched in a background process, and its public URL is captured and returned—no manual builds or deployments needed.
- **Extensible & Maintainable**
  - Add agents, tasks, or custom tools (e.g., `python_code_run_tool.py`) without touching the core pipeline. Everything is declarative and composable.
- **Runs Local or in the Cloud**
  - Works out of the box on your machine and is ready for Hugging Face Spaces deployment with the same entry point.

## Architecture Overview
- **Crew & Agents:** `src/ai_agentic_coder/crew.py`
  - Agents configured in `src/ai_agentic_coder/config/agents.yaml`
  - Tasks configured in `src/ai_agentic_coder/config/tasks.yaml`
- **Tools:**
  - Python code runner and GCS uploader: `src/ai_agentic_coder/tools/python_code_run_tool.py`
- **UI:** `src/ai_agentic_coder/gradio_ui.py`
- **Entry point:** `src/ai_agentic_coder/main.py`
- **Outputs:** `src/ai_agentic_coder/output/`
  - Design doc, backend module, test module, demo app, and utility artifacts

### Pipeline (from tasks.yaml)
1. `design_task` → writes `src/ai_agentic_coder/output/{module_name}_design.md`
2. `code_task` → writes `src/ai_agentic_coder/output/{module_name}` (e.g., `accounts.py`)
3. `frontend_task` → writes `src/ai_agentic_coder/output/app.py` (Gradio demo with share=True)
4. `test_task` → writes `src/ai_agentic_coder/output/test_{module_name}`
5. `python_code_run_task` → uploads zip to GCS, runs the app, and returns two URLs; also writes `src/ai_agentic_coder/output/gradio_public_url.txt`

## Prerequisites
- Python 3.10–3.12 (project targets >=3.10 per `pyproject.toml`)
- A modern browser (Chrome, Edge, Safari, Firefox)
- API keys and credentials (see Configuration)
- Docker Engine running (local only) — required for sandboxed "safe" execution of generated code. If you opt out and force `unsafe` mode locally (see Configuration → Execution Mode), Docker is not required.

## Quick Start

### 1) Clone the repo
```bash
git clone https://github.com/Kaushik-Paul/AI-Agentic-Coder.git
cd AI-Agentic-Coder
```

### 2) (Optional) Create and activate a virtual environment
```bash
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
```

### 3) Install dependencies
#### Option A — Install with uv (recommended)
1) Install uv
- Linux/macOS:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
# ensure ~/.local/bin is on your PATH
export PATH="$HOME/.local/bin:$PATH"
```
- Windows (PowerShell):
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

2) Sync dependencies
```bash
uv sync
```

#### Option B — Install with pip
```bash
pip install -r requirements.txt
```

### 4) Create a .env file
Create a `.env` file in the project root with the following variables (adjust as needed):

```ini
# ——— LLM provider ———
# Defaults to OpenCode Go when USE_OPENROUTER is false or omitted.
USE_OPENROUTER=false
OPENCODE_GO_API_KEY=your_opencode_go_key
OPENCODE_GO_MODEL=minimax-m2.7
# Optional: auto, openai, or anthropic. auto reads OpenCode Go model metadata and falls back safely.
OPENCODE_GO_API_STYLE=auto

# To use OpenRouter instead:
# USE_OPENROUTER=true
# OPENROUTER_API_KEY=your_openrouter_key
# OPENROUTER_MODEL=moonshotai/kimi-k2:free

# Optional shared tuning:
LLM_TEMPERATURE=0.2
LLM_TIMEOUT=300

# ——— Google Cloud Storage (used by PythonCodeRunTool) ———
GCP_PROJECT_ID=your_gcp_project_id
GCP_BUCKET_NAME=your_public_or_private_bucket_name
# Base64-encoded service account JSON. Example to generate:
#   cat service_account.json | base64 -w 0
GCP_SERVICE_KEY=base64_encoded_service_account_json
```

### 5) Run the app
Using uv:
```bash
uv run python -m src.ai_agentic_coder.main
```
Using python directly:
```bash
python -m src.ai_agentic_coder.main
```
Gradio will print a local URL (e.g., http://127.0.0.1:7860). Open it in your browser.

## Built with CrewAI
This project leverages [CrewAI](https://docs.crewai.com/en/introduction), a powerful framework for orchestrating role-playing, autonomous AI agents. CrewAI enables the creation of sophisticated AI workflows where different agents can work together to accomplish complex tasks.

Key features used in this project:
- **Agents**: Specialized AI agents for design, backend, frontend, testing, and running
- **Tasks**: Well-defined tasks that agents perform sequentially
- **Tools**: Custom Python tool to package, upload, and run generated code
- **Delegation**: Sequential, YAML-driven orchestration of the pipeline

## Configuration

### LLMs and Agents
- File: `src/ai_agentic_coder/model_client.py`
- Provider selection is driven by `.env`: `USE_OPENROUTER=true` uses `OPENROUTER_MODEL`; otherwise the app uses OpenCode Go with `OPENCODE_GO_MODEL`.
- OpenCode Go defaults to `minimax-m2.7`. The app checks OpenCode Go model metadata to choose the correct API style, so Anthropic-style models use `/messages` and OpenAI-compatible models use `/chat/completions`. You can override detection with `OPENCODE_GO_API_STYLE=openai` or `OPENCODE_GO_API_STYLE=anthropic`.

### Tasks & Outputs
- File: `src/ai_agentic_coder/config/tasks.yaml`
- Pipeline and outputs are described in the Architecture section.

### UI Behavior
- File: `src/ai_agentic_coder/gradio_ui.py`
- You provide: `Requirements`, `Module Name` (without .py), `Class Name`.
- The app displays a progress bar during execution and, on success, two URLs: a signed download URL and a live app URL.
- Generated demos are served through the main Gradio app at `/generated-app/`, which works on Hugging Face Spaces without relying on Gradio tunnel/share URLs.

### Execution Mode (Docker vs non‑Docker)
- Files: `src/ai_agentic_coder/crew.py`
- Local runs use CrewAI `code_execution_mode="safe"`, executing generated code inside Docker for isolation.
- On Hugging Face Spaces, the project automatically switches to `"unsafe"` mode (no Docker) for compatibility:
  - See: `crew.py` — `is_running_in_hf_space()` and `run_in_docker = "unsafe" if is_running_in_hf_space() else "safe"`.
  - Agents with code execution enabled inherit this setting: `backend_engineer`, `test_engineer` (see their `code_execution_mode=run_in_docker`).
- Requirement: Ensure Docker is running when executing locally (see Quick Start step 0).
- Opting out locally: If you don’t need Docker isolation on your machine, you can force non‑Docker execution by setting the variable unconditionally in `crew.py`:

```python
# src/ai_agentic_coder/crew.py
# Force no Docker even on local runs
run_in_docker = "unsafe"
```

This removes the need to have Docker running locally.

## Usage
1. Open the app in your browser.
2. Paste or write your requirements (what you want to build).
3. Enter a module name (e.g., `accounts`) and class name (e.g., `Account`).
4. Click “Run AI Coder”.
5. Wait a few minutes while the pipeline runs. When done, you’ll see:
   - A 30-minute signed Google Cloud Storage URL to download the generated artifacts as a zip
   - A live URL of the generated Gradio demo app, proxied through the main app

## Outputs
Generated files are saved under `src/ai_agentic_coder/output/`:
- `{module_name}_design.md` — Detailed design produced by the engineering lead agent
- `{module_name}.py` — The generated backend module
- `app.py` — A minimal Gradio UI demonstrating the backend (launched with share=True)
- `test_{module_name}` — Unit test module for the backend
- `gradio_public_url.txt` — CrewAI task output containing the returned URLs
- `latest_run_result.json` — Exact tool result used by the UI, so signed URL query parameters are preserved

## Deployment
- The project is already hosted on Hugging Face Spaces: https://projects.kaushikpaul.co.in/ai-agentic-coder
- To deploy with the helper script:
  - Set `HF_TOKEN` with write access to the Space.
  - Optionally set `HF_SPACE_ID`; it defaults to `kaushikpaul/AI-Agentic-Coder`.
  - Run `uv run python scripts/deploy_space.py`.
- To deploy your own Space manually:
  - Set Space SDK to “Gradio” and point to `src/ai_agentic_coder/main.py` as the entry file.
  - Add required secrets in the Space settings:
    - `USE_OPENROUTER`
    - `OPENCODE_GO_API_KEY`, `OPENCODE_GO_MODEL` or `OPENROUTER_API_KEY`, `OPENROUTER_MODEL`
    - `GCP_PROJECT_ID`, `GCP_BUCKET_NAME`, `GCP_SERVICE_KEY` (base64-encoded service account JSON)
  - Ensure the Python version matches (3.10–3.12) and install via `requirements.txt` or `pyproject.toml`.

## Troubleshooting
- **Missing or invalid API keys/credentials**
  - Verify `.env` values. Ensure the selected LLM provider key and GCP service key are valid; confirm bucket exists and is accessible.
- **GCS upload errors**
  - Confirm `GCP_SERVICE_KEY` contains a valid base64-encoded service account JSON with `storage.objects.create` and signing capability. The service account should also be able to access the target bucket.
- **Live URL not detected**
  - The generated preview is available at `/generated-app/` for `AI_AGENTIC_CODER_PREVIEW_TTL_MINUTES` minutes, defaulting to 30. A new run stops the previous preview and reuses the same route.
  - If your app is behind a custom domain or proxy, set `AI_AGENTIC_CODER_BASE_URL` so returned preview links use the exact public origin.
- **Virtualenv issues on Windows**
  - Use `.venv\Scripts\activate` and ensure `python` points to the venv interpreter.

## Tech Stack
- **Python**: 3.10–3.12
- **Frameworks/Libraries**: CrewAI, Gradio 6, google-cloud-storage, python-dotenv, requests, httpx
- **Orchestration**: YAML-configured agents and tasks via CrewAI
- **UI**: Gradio Blocks with live progress and URL surfacing

## Security & Privacy
- Do not commit `.env` files or secrets.
- Use least-privilege GCP service accounts. Prefer short-lived signed URLs for distribution (already used here).

## License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.