Spaces:
Running
Running
| title: NaturalCAD | |
| emoji: 🍃 | |
| colorFrom: gray | |
| colorTo: blue | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # NaturalCAD | |
| <p align="center"> | |
| <img src="docs/assets/naturalcad-icon-selected.jpg" alt="NaturalCAD icon" width="220" /> | |
| </p> | |
| **NaturalCAD** is a public prompt-to-CAD demo built around build123d. | |
| Current local preview posture: | |
| - browser preview uses GLB when available | |
| - STEP remains the main CAD handoff artifact | |
| - STL remains available as a mesh export | |
| Turn natural-language prompts into quick CAD studies, test the interaction with real users, and learn what deserves to become a bigger product. | |
| <p align="center"> | |
| <img src="docs/assets/naturalcad-hero-reference.jpg" alt="NaturalCAD example output" width="680" /> | |
| </p> | |
| ## Current app path | |
| - `app.py` - Hugging Face Space entrypoint | |
| - `requirements.txt` - Space runtime dependencies | |
| - `apps/gradio-demo` - primary MVP app | |
| ## Other repo areas | |
| - `apps/cad-worker` - Modal worker for LLM + build123d execution | |
| - `apps/web-visualizer` - earlier React/Vite prototype | |
| - `docs/` - product and deployment planning | |
| - `archive/` - older or superseded material kept for reference (includes legacy backend) | |
| ## Local run | |
| Simplest path: | |
| ```bash | |
| npm run frontend:local | |
| ``` | |
| That runs the Gradio app and points to `NATURALCAD_BACKEND_URL`. | |
| Optional local backend (legacy) for contract testing: | |
| ```bash | |
| npm run backend:local | |
| ``` | |
| That uses the repo helper scripts: | |
| - `scripts/run-local-backend.sh` | |
| - `scripts/run-local-frontend.sh` | |
| Notes: | |
| - frontend local dev needs Python 3.10-3.13 because `build123d` does not currently publish wheels for Python 3.14+ | |
| - by default the frontend helper uses `~/.openclaw/workspace/.venvs/cadrender312` | |
| - for hosted testing, set `NATURALCAD_BACKEND_URL` to the Modal endpoint | |
| - if `NATURALCAD_BACKEND_URL` is unset, the helper defaults to `http://127.0.0.1:8010` | |
| - if `apps/backend-api/.env` exists, the frontend helper also reuses `API_SHARED_SECRET` as `NATURALCAD_API_KEY` | |
| - if you want a different frontend venv, set `NATURALCAD_FRONTEND_VENV=/path/to/venv` | |
| Manual fallback: | |
| ```bash | |
| pip install -r requirements.txt | |
| python app.py | |
| ``` | |
| ## Deployment posture | |
| Right now the priority is a lean Hugging Face Space MVP with a separate hosted backend. | |
| Current recommended shape: | |
| - Hugging Face Space = public UI + local preview/runtime | |
| - Modal worker = prompt validation, auth/rate-limit gates, OpenRouter inference, build123d execution | |
| - Supabase = Postgres + artifact storage | |
| - OpenRouter = swappable model provider layer | |
| If the CAD dependency stack or runtime limits become painful, the frontend can stay on Hugging Face while execution moves further toward a worker/container architecture later. | |
| ### Hosted env wiring | |
| Hugging Face Space: | |
| - variable: `NATURALCAD_BACKEND_URL` | |
| - secret: `NATURALCAD_API_KEY` | |
| Backend: | |
| - `OPENROUTER_API_KEY` | |
| - `OPENROUTER_MODEL` (optional, default set in worker) | |
| - `SUPABASE_URL` | |
| - `SUPABASE_SERVICE_ROLE_KEY` | |
| - `SUPABASE_BUCKET` | |
| - `NATURALCAD_API_KEY` | |
| ## Safer GitHub push workflow | |
| Before any push, run: | |
| ```bash | |
| ./scripts/prepush-check.sh | |
| ``` | |
| See `docs/github-push-safety.md` for the full branch and review policy. | |
| ## Key docs | |
| - `docs/hf-space-mvp.md` | |
| - `docs/hf-space-deploy-checklist.md` | |
| - `docs/startup-shutdown-playbook.md` | |
| - `docs/publish-checklist.md` | |
| - `docs/backend-v0.md` | |
| - `docs/security-policy-v0.md` | |
| - `docs/engine-assembly-milestone.md` | |