Spaces:
Running
Running
File size: 3,393 Bytes
010bc6c e168bbf f683324 010bc6c 7907578 010bc6c e168bbf 010bc6c e168bbf c67d8f3 e168bbf 010bc6c 8cfaa29 010bc6c c4fd681 010bc6c c4fd681 010bc6c c67d8f3 c4fd681 c67d8f3 c4fd681 c67d8f3 010bc6c c67d8f3 c4fd681 c67d8f3 c4fd681 c67d8f3 c4fd681 c67d8f3 c4fd681 010bc6c 8e26f87 010bc6c 8e26f87 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | ---
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`
|