# AgentIC — HuggingFace Spaces Deployment Guide

> **This document covers:** what was cleaned from git history, what is safe and what is not, how AgentIC operates on HuggingFace (including HITL), how the CI/CD pipeline works, and how to maintain the setup.

---

## 1. What Was Removed From Git History — And Why It Is Safe

HuggingFace rejects pushes that contain any file >10 MiB **anywhere in the entire commit history**, not just at the latest commit. Three rounds of `git-filter-repo` were run to rewrite history and remove large binary files that had been committed in old commits.

### Files Removed

| Path | What it was | Impact on AgentIC |
|---|---|---|
| `.venv-agentic/` | Local Python virtual environment accidentally committed | **Zero impact.** Docker builds its own isolated venv via `pip install -r requirements.txt` during image build. |
| `designs/minicount/runs/` | OpenLane GDSII build output from a previous run | **Zero impact.** Run outputs are generated fresh per build job, written to the container's local filesystem. |
| `designs/simple_counter/runs/` | OpenLane GDSII build output | **Zero impact.** Same as above. |
| `artifacts/*.gds` | Generated GDS chip layout files | **Zero impact.** GDS files are outputs, not inputs. They are regenerated at runtime. |
| `artifacts/*.vcd` | Simulation waveform files | **Zero impact.** Generated fresh per simulation run. |
| `oss-cad-suite/` | Pre-built EDA tool binaries (~500 MB) | **Zero impact.** Docker installs `verilator`, `iverilog`, `yosys`, and `sby` via `apt` and builds from source inside the image. |

### What Was NOT Removed — Everything AgentIC Needs Is Intact

| Path | Purpose |
|---|---|
| `src/agentic/agents/` | Designer, testbench, verifier, SDC, doc agents |
| `src/agentic/orchestrator.py` | Core build state machine |
| `src/agentic/tools/vlsi_tools.py` | All EDA tool wrappers (iverilog, verilator, yosys, sby) |
| `src/agentic/config.py` | LLM + env config |
| `src/agentic/contracts.py` | AgentResult, StageResult, FailureClass definitions |
| `src/agentic/core/` | ArchitectModule, SelfReflect, ReAct, WaveformExpert, DeepDebugger |
| `src/agentic/golden_lib/templates/` | 8 golden RTL templates (counter, FIFO, FSM, UART, SPI, timer, shift reg, PWM) |
| `server/api.py` | FastAPI backend — all endpoints including HITL approve/reject |
| `server/approval.py` | Human-in-the-loop approval manager |
| `server/stage_summary.py` | Stage event and summary formatting |
| `web/src/` | Full React frontend — DesignStudio, HumanInLoopBuild, Dashboard, etc. |
| `designs/simple_counter/src/*.v` | Reference Verilog + testbench |
| `designs/simple_counter/config.tcl` | OpenLane config template |
| `requirements.txt` | All Python dependencies |
| `scripts/` | CI and setup scripts |

---

## 2. How AgentIC Operates on HuggingFace

### Architecture

```
Browser / Frontend (React)
         │  HTTP + SSE
         ▼
FastAPI  (server/api.py)  ← uvicorn on port 7860
         │
         ├── POST /build          → starts a background build job
         ├── GET  /build/stream/{job_id}  → Server-Sent Events stream
         ├── POST /approve        → HITL approval gate
         ├── POST /reject         → HITL rejection
         └── GET  /build/result/{job_id} → final artifacts
         │
         ▼
Orchestrator (src/agentic/orchestrator.py)
         │
         ├── CrewAI agents  (LLM calls to NVIDIA API)
         ├── EDA tools      (iverilog, verilator, yosys, sby — installed in Docker)
         └── File system    (writes Verilog, configs, logs to /app/designs/ inside container)
```

### What runs where

| Component | Runs on HuggingFace | Notes |
|---|---|---|
| FastAPI server | Yes | `uvicorn server.api:app --host 0.0.0.0 --port 7860` |
| React web app | **No** — served separately | The `web/` frontend must be built and hosted on Vercel/Netlify/Cloudflare Pages, or served statically from FastAPI |
| LLM inference | No — remote API call | Agent calls `NVIDIA_API_KEY` → `integrate.api.nvidia.com` |
| `iverilog` simulation | Yes | Installed in Docker via apt |
| `verilator` coverage | Yes | Installed in Docker via apt |
| `yosys` synthesis | Yes | Installed in Docker via apt |
| `sby` formal verification | Yes | Built from source in Docker |
| OpenLane GDSII hardening | **Optional / skipped by default** | Set `skip_openlane: true` in build request |

### Persistent Storage

HuggingFace Spaces **do not have persistent disk by default**. This means:
- Build artifacts (Verilog files, simulation logs) are written to the container filesystem and **lost when the Space restarts**.
- For persistent storage, mount a HuggingFace Dataset as a volume (HF Pro feature) or use an external object store (S3, R2).
- For demo / RTL-only workflows this is fine — the agent regenerates outputs each run.

---

## 3. HITL (Human-in-the-Loop) Build — Does It Still Work?

**Yes, HITL works exactly as before.** Nothing in the approval flow was removed.

### How HITL Works

The HITL flow is controlled by the `server/approval.py` `ApprovalManager` and the `/approve` / `/reject` API endpoints.

```
Build job starts (POST /build, skip_openlane: false or true)
         │
         ▼
Stage: RTL_GEN → VERIFICATION → FORMAL_VERIFY → COVERAGE → REGRESSION → SDC_GEN
         │
         ▼ (if skip_openlane=false)
Stage: FLOORPLAN
         │  ← pauses here, emits SSE event type: "approval_required"
         ▼
Frontend (HumanInLoopBuild page) shows the stage summary
User clicks Approve or Reject
         │
POST /approve  or  POST /reject
         │
         ▼ (if approved)
Stage: HARDENING → CONVERGENCE_REVIEW → ECO_PATCH → SIGNOFF → SUCCESS
```

### Key endpoints

| Endpoint | Purpose |
|---|---|
| `POST /build` | Start a build. Body: `{ "design_name": "...", "description": "...", "skip_openlane": false }` |
| `GET /build/stream/{job_id}` | SSE stream — receive all stage events, agent thoughts, approval gates in real time |
| `GET /approval/status` | Check if any job is currently waiting for approval |
| `POST /approve` | Approve the pending stage and continue the build |
| `POST /reject` | Reject — build stops with failure record |
| `GET /build/result/{job_id}` | Fetch final Verilog, metrics, logs after completion |

### skip_openlane flag

If you only want RTL generation + verification (no physical implementation), send:
```json
{ "skip_openlane": true }
```
The orchestrator skips FLOORPLAN, HARDENING, SIGNOFF, and CONVERGENCE_REVIEW entirely. **This is the recommended setting on HuggingFace** since OpenLane requires Docker-in-Docker and PDK files which are not included.

---

## 4. CI/CD Pipeline — How deploy.yml Works

File: `.github/workflows/deploy.yml`

```yaml
on:
  push:
    branches:
      - main
```

**Trigger:** Any commit pushed to the `main` branch on GitHub.

### Step-by-step flow

```
Developer pushes to GitHub main
         │
GitHub Actions runner starts (ubuntu-latest)
         │
Step 1: actions/checkout@v4 (fetch-depth: 0)
         └── Clones the full git history with LFS support
         │
Step 2: git config user identity
         └── Sets bot email/name for git operations
         │
Step 3: git remote add hf
         └── Adds HuggingFace remote using HF_TOKEN secret
         │
Step 4: git push hf main --force
         └── Force-pushes to huggingface.co/spaces/vxkyyy/AgentIC
         │
         ▼ (on HuggingFace side)
HF detects new commit → reads Dockerfile → builds Docker image
         └── apt install: verilator, iverilog, yosys + deps
         └── git clone YosysHQ/sby → make install
         └── pip install -r requirements.txt
         └── Starts: uvicorn server.api:app --host 0.0.0.0 --port 7860
         │
Space goes live at https://huggingface.co/spaces/vxkyyy/AgentIC
```

### Secrets used

| Secret | Where set | Used by |
|---|---|---|
| `HF_TOKEN` | GitHub repo → Settings → Secrets | `deploy.yml` to authenticate git push to HF |
| `NVIDIA_API_KEY` | HuggingFace Space → Settings → Secrets | Injected as env var at container runtime |

### What deploy.yml does NOT do

- It does not run tests before deploying (the existing `ci.yml` handles that separately)
- It does not build the Docker image on GitHub — HuggingFace builds it
- It does not push Docker Hub — the image is built inside HF's infrastructure

---

## 5. Setup Checklist

### One-time setup

- [ ] Create HF Space at https://huggingface.co/new-space — SDK: Docker, name: AgentIC
- [ ] Generate HF write token at https://huggingface.co/settings/tokens
- [ ] Add `HF_TOKEN` to GitHub repo Secrets
- [ ] Add `NVIDIA_API_KEY` to HF Space Secrets
- [ ] Add `NVIDIA_MODEL` = `meta/llama-3.3-70b-instruct` to HF Space Secrets
- [ ] Add `NVIDIA_BASE_URL` = `https://integrate.api.nvidia.com/v1` to HF Space Secrets
- [ ] First push: `git push hf main --force`

### Every deploy after that

```bash
git add .
git commit -m "feat: ..."
git push origin main   # GitHub Actions auto-deploys to HF
```

---

## 6. Local Testing

```bash
cd ~/AgentIC

# Build
docker build -t agentic:local .

# Run (reads your .env file)
docker compose up

# API docs
curl http://localhost:7860/docs

# Stop
docker compose down

# Rebuild after code change
docker compose up --build
```

---

## 7. .env File Safety

| File | Committed to git | Purpose |
|---|---|---|
| `.env` | **NO** (in `.gitignore`) | Your real local API keys |
| `.env.example` | **YES** (no values) | Documents which keys are needed |
| `.dockerignore` | **YES** | Prevents `.env` entering Docker build context |

To verify `.env` is safe:
```bash
git ls-files .env     # must print nothing
```

---

## 8. Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| HF Space shows "Building" for >10 min | apt/pip install failure | Check HF Logs tab |
| `ModuleNotFoundError: server` | Wrong uvicorn module path | CMD in Dockerfile must be `server.api:app` |
| `500` on all API calls | `NVIDIA_API_KEY` missing | Add it to HF Space Secrets |
| GitHub Actions `401` | `HF_TOKEN` expired or wrong user | Regenerate token, update GitHub Secret |
| HITL approval never triggers | `skip_openlane: true` in request | Physical stages are skipped — HITL only fires before FLOORPLAN |
| Build artifacts gone after restart | Container filesystem is ephemeral | Expected on free HF tier — use HF Datasets volume for persistence |
| `port 7860 refused` locally | Container not started | Run `docker compose up` first |