README.md

metadata

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

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

git clone https://github.com/Kaushik-Paul/AI-Agentic-Coder.git
cd AI-Agentic-Coder

2) (Optional) Create and activate a virtual environment

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:

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 -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Sync dependencies

uv sync

Option B — Install with pip

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):

# ——— 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:

uv run python -m src.ai_agentic_coder.main

Using python directly:

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, 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:

# 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 file for details.