docs/DEPLOY_HUGGINGFACE.md

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:

{ "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

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

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

---

6. Local Testing

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:

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