feat: add Docker + HuggingFace Spaces deployment pipeline

- Dockerfile: Python 3.11 slim, EDA tools (verilator/iverilog/yosys/sby), uvicorn
- .dockerignore: excludes .env, venvs, obj_dir, .sby workdirs, OpenLane
- .github/workflows/deploy.yml: auto-deploy to HF on push to main
- docker-compose.yml: local testing with .env mount
- .env.example: safe key template, no values
- README.md: HuggingFace Spaces front matter (sdk: docker)
- docs/DEPLOY_HUGGINGFACE.md: full deployment guide

.dockerignore

@@ -0,0 +1,72 @@
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Git
+.git/
+.gitignore
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Virtual environments
+.venv/
+.venv-agentic/
+venv/
+env/
+agentic_env/
+
+# Benchmark results (large data, not needed at runtime)
+benchmark/results/
+
+# SymbiYosys workdirs
+*.sby
+**/*.sby
+**/workdir/
+**/*_workdir/
+
+# Verilator object directories
+obj_dir/
+**/obj_dir/
+
+# OpenLane designs (skip entirely)
+OpenLane/
+designs/
+
+# IDE and OS files
+.vscode/
+.idea/
+*.DS_Store
+Thumbs.db
+
+# Node / web build artifacts
+web/node_modules/
+web/dist/
+client/node_modules/
+client/dist/
+
+# Large artifacts not needed at runtime
+artifacts/*.gds
+oss-cad-suite/
+
+# Docs and non-runtime
+docs/
+training/
+
+# Log files
+*.log
+run_log.txt
+
+# Test files
+tests/__pycache__/

.env.example

@@ -0,0 +1,18 @@
+# ── NVIDIA / Cloud LLM ──────────────────────────────────────────────────────
+NVIDIA_API_KEY=your_nvidia_api_key_here
+NVIDIA_MODEL=meta/llama-3.3-70b-instruct
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+
+# ── Groq (optional fallback) ─────────────────────────────────────────────────
+GROQ_API_KEY=your_groq_api_key_here
+
+# ── Local LLM (Ollama / VeriReason) ─────────────────────────────────────────
+LLM_MODEL=ollama/hf.co/mradermacher/VeriReason-Qwen2.5-3b-RTLCoder-Verilog-GRPO-reasoning-tb-GGUF:Q4_K_M
+LLM_BASE_URL=http://localhost:11434
+LLM_API_KEY=NA
+
+# ── Verilog Code-Gen override (optional) ────────────────────────────────────
+VERILOG_CODEGEN_ENABLED=false
+VERILOG_CODEGEN_MODEL=
+VERILOG_CODEGEN_BASE_URL=
+VERILOG_CODEGEN_API_KEY=

.github/workflows/deploy.yml

@@ -0,0 +1,29 @@
+name: Deploy to Hugging Face Spaces
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Push to HuggingFace Space
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Configure Git identity
+        run: |
+          git config user.email "deploy-bot@github-actions"
+          git config user.name "GitHub Actions Deploy Bot"
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git remote add hf https://huggingface:${HF_TOKEN}@huggingface.co/spaces/vickynishad/AgentIC
+          git push hf main --force

Dockerfile

@@ -0,0 +1,42 @@
+FROM python:3.11-slim
+
+# Install system dependencies and EDA tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    git \
+    curl \
+    libboost-dev \
+    zlib1g-dev \
+    libfftw3-dev \
+    libreadline-dev \
+    tcl-dev \
+    pkg-config \
+    verilator \
+    iverilog \
+    yosys \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install SymbiYosys from source
+RUN git clone --depth 1 https://github.com/YosysHQ/sby /tmp/sby \
+    && cd /tmp/sby && make install \
+    && rm -rf /tmp/sby
+
+WORKDIR /app
+
+# Install Python dependencies first (layer cache)
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir uvicorn[standard] fastapi && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# HuggingFace Spaces runs as non-root user 1000
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 7860
+
+CMD ["uvicorn", "server.api:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,3 +1,13 @@
+---
+title: AgentIC
+emoji: 🤖
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
 # AgentIC
 
 AgentIC is an autonomous digital design pipeline that takes a natural-language chip specification and drives it through RTL generation, verification, formal checks, coverage, regression, and optional physical implementation. The system is built as a gated flow around standard EDA tools and AI-assisted generation and debugging.

docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  agentic:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: agentic:local
+    container_name: agentic_local
+    ports:
+      - "7860:7860"
+    env_file:
+      - .env
+    volumes:
+      - ./artifacts:/app/artifacts
+      - ./training:/app/training
+    restart: unless-stopped

docs/DEPLOY_HUGGINGFACE.md

@@ -0,0 +1,214 @@
+# AgentIC — HuggingFace Spaces Deployment Guide
+
+> **Goal:** Run AgentIC 24/7 on HuggingFace Spaces (Docker), with automatic deploys triggered by every `git push` to your private GitHub repo.
+
+---
+
+## Architecture
+
+```
+Your PC  ──push──►  GitHub (private repo)
+                         │
+              GitHub Actions (deploy.yml)
+                         │
+                    git push --force
+                         │
+                         ▼
+         HuggingFace Spaces (Docker)
+         https://vickynishad-AgentIC.hf.space
+              uvicorn server.api:app :7860
+```
+
+---
+
+## Prerequisites
+
+| Tool | Version |
+|---|---|
+| Docker | ≥ 24 |
+| Git | any |
+| Python | 3.11 (inside container) |
+| HuggingFace account | [huggingface.co](https://huggingface.co) |
+| GitHub repo | Private, branch `main` |
+
+---
+
+## Step 1 — Create the HuggingFace Space
+
+1. Go to https://huggingface.co/new-space
+2. **Owner:** `vickynishad`
+3. **Space name:** `AgentIC`
+4. **SDK:** `Docker`
+5. **Visibility:** Public or Private (your choice)
+6. Click **Create Space**
+
+The Space will sit empty — the deploy pipeline will populate it.
+
+---
+
+## Step 2 — Generate a HuggingFace Token
+
+1. Go to https://huggingface.co/settings/tokens
+2. Click **New token**
+3. **Name:** `AgentIC-deploy`
+4. **Role:** `write`
+5. Copy the token — you'll need it in Steps 3 and 4
+
+---
+
+## Step 3 — Add GitHub Secret
+
+In your GitHub repo:
+
+**Settings → Secrets and variables → Actions → New repository secret**
+
+| Name | Value |
+|---|---|
+| `HF_TOKEN` | The HuggingFace write token from Step 2 |
+
+---
+
+## Step 4 — Add HuggingFace Space Secrets
+
+In your HF Space:
+
+**Space → Settings → Variables and secrets → New secret**
+
+Add every key from `.env.example` that you need at runtime:
+
+| Secret name | Value |
+|---|---|
+| `NVIDIA_API_KEY` | Your NVIDIA API key |
+| `GROQ_API_KEY` | Your Groq API key (optional) |
+| `NVIDIA_MODEL` | e.g. `meta/llama-3.3-70b-instruct` |
+| `NVIDIA_BASE_URL` | `https://integrate.api.nvidia.com/v1` |
+
+> HuggingFace injects Space secrets as environment variables at container runtime — **never put API keys in the Dockerfile or commit them to git.**
+
+---
+
+## Step 5 — First Manual Push to HuggingFace
+
+Run once from your machine to seed the Space:
+
+```bash
+cd ~/AgentIC
+
+# Add the HF remote (one-time)
+git remote add hf https://huggingface:YOUR_HF_TOKEN@huggingface.co/spaces/vickynishad/AgentIC
+
+# Push
+git push hf main --force
+```
+
+After ~2–5 minutes the Space will build the Docker image and start. Watch build logs at:
+`https://huggingface.co/spaces/vickynishad/AgentIC` → **Logs** tab
+
+---
+
+## Step 6 — Automatic CI/CD via GitHub Actions
+
+The file `.github/workflows/deploy.yml` is already configured. Every push to `main`:
+
+1. GitHub Actions checks out your full repo history
+2. Force-pushes to `huggingface.co/spaces/vickynishad/AgentIC`
+3. HF detects the change and rebuilds the Docker image
+4. The new container starts on port 7860
+
+No manual steps needed after the first push.
+
+---
+
+## Local Development & Testing
+
+### Test the Docker build locally
+
+```bash
+cd ~/AgentIC
+
+# Build
+docker build -t agentic:local .
+
+# Run (uses your local .env file for API keys)
+docker compose up
+
+# Verify
+curl http://localhost:7860/docs
+```
+
+### Stop the local container
+
+```bash
+docker compose down
+```
+
+### Rebuild after code changes
+
+```bash
+docker compose up --build
+```
+
+---
+
+## .env File Safety
+
+| File | Committed? | Purpose |
+|---|---|---|
+| `.env` | **NO** — in `.gitignore` | Your real local secrets |
+| `.env.example` | **YES** | Template showing key names only, no values |
+| `.dockerignore` | **YES** | Excludes `.env` from Docker build context |
+
+**Rules:**
+- Never `git add .env`
+- Never paste API keys into `Dockerfile`, `docker-compose.yml`, or any committed file
+- Use HF Space Secrets for production keys
+- Use GitHub Secrets only for deployment tokens (`HF_TOKEN`)
+
+To verify `.env` is not tracked:
+```bash
+git ls-files .env    # should print nothing
+```
+
+---
+
+## Deployed URL
+
+```
+https://vickynishad-AgentIC.hf.space
+```
+
+API docs:
+```
+https://vickynishad-AgentIC.hf.space/docs
+```
+
+---
+
+## Optional: Custom Domain (`agentic.buildstack.live`)
+
+HF free tier does not support custom domains natively. Use Cloudflare:
+
+1. In Cloudflare DNS for `buildstack.live`, add:
+   ```
+   Type:  CNAME
+   Name:  agentic
+   Target: vickynishad-agentIC.hf.space
+   Proxy: ON (orange cloud)
+   ```
+2. In Cloudflare **Rules → Page Rules** (or a Worker), proxy requests to the HF Space URL
+
+For native custom domain support, upgrade to HF Pro and use:
+**Space Settings → Custom domains → Add domain → `agentic.buildstack.live`**
+HF will give you a CNAME record to set in your DNS.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Space shows "Building" forever | Check HF Logs tab for apt/pip errors |
+| `500` errors on API calls | Check HF Space Secrets — `NVIDIA_API_KEY` missing |
+| GitHub Actions fails with `401` | `HF_TOKEN` secret expired or wrong — regenerate at huggingface.co/settings/tokens |
+| `port 7860 refused` locally | Run `docker compose up` first; give it 5 seconds to start |
+| Container crashes on start | Run `docker logs agentic_local` to see the Python traceback |