docs/hf-space-deploy-checklist.md

NaturalCAD Hugging Face Space Deploy Checklist

Minimum checklist

• Gradio app runs cleanly from apps/gradio-demo/app/main.py
• requirements.txt contains everything needed for Space runtime, including build123d
• prompt-to-model flow works without requiring local-only paths that break in Space
• example prompts produce valid outputs
• timeouts are in place
• artifacts are bounded and not unbounded temp junk
• lightweight run logging is enabled
• README explains local run and Space intent clearly

MVP notes

For public testing, the demo should degrade gracefully. If the backend is unavailable, the app should still be able to produce a simple local fallback result rather than fully dying.

For the lean MVP, backend use should be optional, not assumed. If NATURALCAD_BACKEND_URL is unset, the Space should stay usable without waiting on a dead localhost request.

If the Hugging Face Space runtime cannot support the CAD dependency stack cleanly, keep the Space as the frontend and offload execution to a container or VM.

Current hosted setup

Space env:

• variable: NATURALCAD_BACKEND_URL
• secret: NATURALCAD_API_KEY

Backend host:

• current recommended host: Modal web endpoint (generate_cad_endpoint)
• endpoint method: POST /
• backend requires header x-api-key: <NATURALCAD_API_KEY>
• response should include job_id, generated_code, and artifact urls

Worker env/secrets:

• OPENROUTER_API_KEY
• OPENROUTER_MODEL (optional)
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• SUPABASE_BUCKET
• NATURALCAD_API_KEY

Runtime note:

• the Space Docker image must include the native stack needed by build123d / OCP
• final stabilization attempt uses a pure python:3.10-slim + pip runtime instead of the mixed Conda/OCP path
• the goal is to let build123d resolve one coherent wheel stack directly, instead of mixing conda native packages with pip Python packages
• current Dockerfile includes a build123d import smoke test during image build so broken native combinations fail earlier

Data to capture

• timestamp
• run id
• prompt
• mode
• output type
• geometry family
• backend available or not
• success or failure
• runtime seconds
• error string if any

Security checks before publish

• NATURALCAD_API_KEY is set on Space and Modal
• backend endpoint rejects requests without x-api-key
• rate limiting is active (IP + key)
• prompt length caps enforced
• generated code safety guard enabled
• no tracked artifacts/logs/*.jsonl