DEPLOY.md

Deploying this directory as a HuggingFace Space

This directory is a self-contained static HuggingFace Space ready to push. Total bundle size is ~124 MB (the bulk is the two 60K data packs at 61 MB each); the index.html + scripts + weights together are under 3 MB.

One-time setup

You need: a HuggingFace account, the huggingface_hub Python CLI, and an HF write token.

pip install -U huggingface_hub
huggingface-cli login          # paste your token from https://huggingface.co/settings/tokens

Install Git LFS once (required for the 60 MB data packs):

brew install git-lfs           # macOS;  apt-get install git-lfs  on Linux
git lfs install

Create the space and push

# 1. Create an empty static space named cortex-conv on huggingface.co/spaces/<your-username>/cortex-conv
huggingface-cli repo create cortex-conv --type space --space-sdk static

# 2. Clone the empty space repo somewhere
git clone https://huggingface.co/spaces/<your-username>/cortex-conv ~/cortex-conv-space

# 3. Mirror this directory into the clone
rsync -a --delete --exclude=.git /Users/exobit/developer/fnm-gpu/hf_space/  ~/cortex-conv-space/

# 4. Push (the .gitattributes file already routes the JSON packs to LFS)
cd ~/cortex-conv-space
git lfs track "*.json"
git add .gitattributes README.md index.html PAPER_COMPANION.md tests/ weights/ mnist/ fashion/
git commit -m "initial: cortex-conv ships pre-trained at 96.8% MNIST"
git push

The Space will build automatically (a static space is just a file server, no build step). Open https://huggingface.co/spaces/<your-username>/cortex-conv and the page should load at 96.8% MNIST test accuracy within ~3 seconds on first visit.

Verifying the deployed space

Visit the Space URL with a Chrome/Edge/Safari browser that supports WebGPU. Within 3 seconds you should see:

• Test accuracy: 96.8%
• Status label: idle (cortex-conv · webgpu+pretrained · 34,106 params)
• Equation header: CORTEX-CONV (2-conv 16,16, γ=0.1, banked V1 mask, drive-clamp · 34,106 params) · CORTEX NEURON · ADAGO · MNIST

If WebGPU is unavailable in the visitor's browser, the page falls back to a CPU-only path with the embedded 6K MNIST and runs much slower.

Notes

• HuggingFace Spaces by default serve from CDN with proper MIME types for .json and .js — no extra config needed.
• The sdk: static line in README.md frontmatter is what tells HF this is a static site (not a Gradio or Streamlit app).
• Updates: after editing files in /Users/exobit/developer/fnm-gpu/hf_space/, repeat the rsync + git add + git commit + git push steps. HuggingFace re-deploys automatically on every push.
• To regenerate the bundled weights snapshot after architecture changes, run tools/train_cortex_dump.cjs from the project root (not from hf_space/), then copy the resulting weights/cortex_conv_mnist_R28.json into hf_space/weights/.