NaturalCAD: add hosted backend flow and Space fixes

Dockerfile

@@ -16,7 +16,7 @@ ENV HOME=/home/user \
 WORKDIR $HOME/app
 
 RUN conda create -n cad python=3.10 -y && \
-    conda install -n cad -c conda-forge ocp=7.8.1 -y && \
+    conda install -n cad -c conda-forge ocp=7.8.1 vtk=9.3 -y && \
     conda clean -a -y
 
 ENV PATH=$CONDA_DIR/envs/cad/bin:$PATH

README.md

@@ -16,6 +16,11 @@ pinned: false
 
 **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">
@@ -37,6 +42,26 @@ Turn natural-language prompts into quick CAD studies, test the interaction with
 
 ## Local run
 
+Simplest path:
+
+```bash
+npm run backend:local
+npm run frontend: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`
+- the frontend helper defaults `NATURALCAD_BACKEND_URL` 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
@@ -44,8 +69,29 @@ python app.py
 
 ## Deployment posture
 
-Right now the priority is a lean Hugging Face Space MVP.
-If the CAD dependency stack or runtime limits become painful, the frontend can stay on Hugging Face while execution moves to a container or VM later.
+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
+- Fly.io backend = API, auth, rate limiting, job/spec logging, Supabase writes
+- Supabase = Postgres + artifact storage
+- managed inference endpoint later = swappable model layer behind the backend
+
+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:
+- `DATABASE_URL`
+- `SUPABASE_URL`
+- `SUPABASE_ANON_KEY`
+- `SUPABASE_SERVICE_ROLE_KEY`
+- `SUPABASE_BUCKET`
+- `API_SHARED_SECRET`
 
 ## Key docs
 

apps/backend-api/.dockerignore

@@ -0,0 +1,5 @@
+fly.toml
+.git/
+__pycache__/
+.envrc
+.venv/

apps/backend-api/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.14.0 AS builder
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+WORKDIR /app
+
+RUN python -m venv .venv
+COPY requirements.txt ./
+RUN .venv/bin/pip install -r requirements.txt
+
+FROM python:3.14.0-slim
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+WORKDIR /app
+COPY --from=builder /app/.venv .venv/
+COPY . .
+CMD ["/app/.venv/bin/uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

apps/backend-api/README.md

@@ -23,12 +23,17 @@ python3 -m venv .venv
 - `POST /v1/jobs`
 - `GET /v1/jobs/{job_id}`
 - `POST /v1/generate-spec`
+- `POST /v1/jobs/{job_id}/artifacts` (multipart upload: `kind` + `file`)
 
 ## Current integration state
 - `apps/gradio-demo` now creates backend jobs through `POST /v1/jobs`
-- the backend currently returns a validated in-memory spec
+- the backend currently returns a validated compositional in-memory spec (v1.1 semantic shape)
 - the Gradio app still performs local build123d execution for now
 - next step is moving execution from the Gradio app into a real worker
+- backend models now include an early **compositional spec v1.1** shape for the next generation stage, so model output is not forced into a rigid family-first schema too early
+
+See also:
+- `docs/compositional-spec-v1.1.md`
 
 ## Notes
 This is the v0 scaffold. It currently uses in-memory storage by default, but now includes a Postgres schema and a repository layer that can switch to `DATABASE_URL` when Supabase is ready.
@@ -37,3 +42,27 @@ This is the v0 scaffold. It currently uses in-memory storage by default, but now
 - schema file: `db/schema.sql`
 - env placeholders added for `DATABASE_URL` and Supabase keys
 - repository layer falls back to memory until the database is configured
+- artifact uploads now write to Supabase Storage when these env vars are set:
+  - `SUPABASE_URL`
+  - `SUPABASE_SERVICE_ROLE_KEY`
+  - `SUPABASE_BUCKET`
+  - optional: `STORAGE_MAX_UPLOAD_BYTES`
+
+## Fly.io deployment notes
+- backend app can be deployed directly from `apps/backend-api`
+- internal service port should be `8000`
+- backend Docker image should start with `uvicorn`, not `fastapi run`
+- recommended startup command is already baked into `apps/backend-api/Dockerfile`
+- Hugging Face Space should call this backend via:
+  - variable: `NATURALCAD_BACKEND_URL`
+  - secret: `NATURALCAD_API_KEY`
+- backend should keep the matching value in `API_SHARED_SECRET`
+
+### Suggested setup order
+1. Create Supabase project
+2. Run `db/schema.sql` in SQL editor
+3. Create Storage bucket (default: `naturalCAD-artifacts` if matching the current deployed config)
+4. Add backend env vars and restart API
+5. Deploy backend host (Fly.io is the current path)
+6. Wire Hugging Face Space env vars and rebuild
+7. Confirm Gradio app calls `/v1/jobs/{job_id}/artifacts` after STL/STEP export

apps/backend-api/app/config.py

@@ -19,6 +19,8 @@ class Settings:
     supabase_url: str = os.getenv("SUPABASE_URL", "")
     supabase_service_role_key: str = os.getenv("SUPABASE_SERVICE_ROLE_KEY", "")
     supabase_anon_key: str = os.getenv("SUPABASE_ANON_KEY", "")
+    supabase_bucket: str = os.getenv("SUPABASE_BUCKET", "naturalcad-artifacts")
+    storage_max_upload_bytes: int = int(os.getenv("STORAGE_MAX_UPLOAD_BYTES", "26214400"))
 
 
 settings = Settings()

apps/backend-api/app/main.py

@@ -1,30 +1,92 @@
 from __future__ import annotations
 
 import hashlib
+import os
+import posixpath
 import re
 import time
 from typing import cast
 
-from fastapi import FastAPI, Header, HTTPException, Request
+import httpx
+from fastapi import FastAPI, File, Form, Header, HTTPException, Request, UploadFile
 
 from .config import settings
 from .models import (
-    CadSpec,
-    CadStyle,
+    ArtifactKind,
+    ArtifactRecord,
+    ArtifactUploadResponse,
+    ConstraintRecord,
     CreateJobRequest,
+    DedupeHint,
+    FamilyHint,
     GenerateSpecRequest,
     GenerateSpecResponse,
+    GeometryFeature,
+    GeometryPlan,
     HealthResponse,
     JobRecord,
     ModeType,
     OutputType,
+    SemanticCadSpec,
+    SemanticPart,
+    SemanticStyle,
 )
+from .repository import create_artifact as repo_create_artifact
 from .repository import get_job as repo_get_job, save_job
+from .repository import list_artifacts as repo_list_artifacts
 from .store import _CACHE, _JOBS, _REQUESTS
 
 app = FastAPI(title=settings.app_name, version="0.4.0")
 
 
+def _storage_ready() -> bool:
+    return bool(settings.supabase_url and settings.supabase_service_role_key and settings.supabase_bucket)
+
+
+def _build_public_artifact_url(storage_key: str) -> str:
+    return f"{settings.supabase_url}/storage/v1/object/public/{settings.supabase_bucket}/{storage_key}"
+
+
+def _upload_bytes_to_supabase_storage(storage_key: str, blob: bytes, content_type: str) -> None:
+    if not _storage_ready():
+        raise HTTPException(status_code=503, detail="Artifact storage not configured")
+
+    url = f"{settings.supabase_url}/storage/v1/object/{settings.supabase_bucket}/{storage_key}"
+    headers = {
+        "apikey": settings.supabase_service_role_key,
+        "Authorization": f"Bearer {settings.supabase_service_role_key}",
+        "x-upsert": "true",
+        "content-type": content_type,
+    }
+    with httpx.Client(timeout=30.0) as client:
+        resp = client.post(url, content=blob, headers=headers)
+    if resp.status_code >= 300:
+        raise HTTPException(status_code=502, detail=f"Supabase upload failed: {resp.text[:300]}")
+
+
+def _artifact_url_for(storage_key: str) -> str | None:
+    if not settings.supabase_url:
+        return None
+    return _build_public_artifact_url(storage_key)
+
+
+def _artifact_to_record(row: dict) -> ArtifactRecord:
+    return ArtifactRecord(
+        id=str(row.get("id")),
+        job_id=str(row.get("job_id")),
+        kind=cast(ArtifactKind, row.get("kind", "other")),
+        storage_key=str(row.get("storage_key")),
+        size_bytes=row.get("size_bytes"),
+        url=_artifact_url_for(str(row.get("storage_key"))),
+        created_at=row.get("created_at"),
+    )
+
+
+def _job_with_artifacts(job: dict) -> JobRecord:
+    artifacts = [_artifact_to_record(a) for a in repo_list_artifacts(str(job["id"]))]
+    return JobRecord(**job, artifacts=artifacts)
+
+
 def _check_auth(header_value: str | None) -> None:
     if settings.api_shared_secret and header_value != settings.api_shared_secret:
         raise HTTPException(status_code=401, detail="Invalid shared secret")
@@ -114,114 +176,191 @@ def _extract_count(prompt: str, nouns: list[str], default: int) -> int:
     return default
 
 
-def _style_from_prompt(prompt: str, default_family: str) -> CadStyle:
-    heaviness = 0.6
-    family = default_family
-    if any(word in prompt for word in ["heavy", "massive", "thick", "brutal"]):
-        heaviness = 0.85
-    elif any(word in prompt for word in ["light", "slim", "thin", "delicate"]):
-        heaviness = 0.35
-
-    if any(word in prompt for word in ["industrial", "steel", "metal"]):
-        family = "industrial"
-    elif any(word in prompt for word in ["structural", "truss", "frame"]):
-        family = "structural"
-    elif any(word in prompt for word in ["smooth", "soft", "shell", "canopy"]):
-        family = "smooth"
-    elif any(word in prompt for word in ["diagram", "profile", "elevation", "line"]):
-        family = "diagrammatic"
+def _style_keywords_from_prompt(prompt: str, default_keyword: str) -> list[str]:
+    keywords = [default_keyword]
+    for word in ["industrial", "structural", "smooth", "diagrammatic", "heavy-duty", "lightweight", "architectural"]:
+        if word in prompt and word not in keywords:
+            keywords.append(word)
+    if any(word in prompt for word in ["steel", "metal", "brutal"]):
+        keywords.append("industrial")
+    if any(word in prompt for word in ["truss", "frame", "girder"]):
+        keywords.append("structural")
+    if any(word in prompt for word in ["roof", "canopy", "shell"]):
+        keywords.append("smooth")
+    return list(dict.fromkeys(keywords))
 
-    return CadStyle(family=family, heaviness=heaviness)
 
-
-def _infer_spec(prompt: str, mode: ModeType, output_type: OutputType) -> CadSpec:
+def _infer_semantic_spec(prompt: str, mode: ModeType, output_type: OutputType) -> SemanticCadSpec:
     p = prompt.lower()
 
     if output_type == "2d_vector" or mode == "sketch":
         family = "truss_elevation" if any(word in p for word in ["truss", "beam", "frame", "elevation"]) else "plate_profile"
         if family == "truss_elevation":
-            params = {
+            dimensions = {
                 "span": _extract_number(p, ["span", "length", "width"], 140),
                 "height": _extract_number(p, ["height", "rise"], 24),
                 "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
                 "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
                 "preview_thickness": 1,
             }
+            geometry = GeometryPlan(
+                primitive_strategy=["sketch", "extrude"],
+                features=[
+                    GeometryFeature(name="chords", feature_type="parallel_members", count=2),
+                    GeometryFeature(name="posts", feature_type="vertical_members", count=int(dimensions["panel_count"]) + 1),
+                ],
+            )
+            semantic_part = SemanticPart(category="diagram", function="structural elevation", topology=["top chord", "bottom chord", "posts"], symmetry="bilateral")
         else:
-            params = {
+            dimensions = {
                 "width": _extract_number(p, ["width", "span"], 80),
                 "height": _extract_number(p, ["height"], 50),
                 "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
                 "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
                 "preview_thickness": 1,
             }
-        return CadSpec(
+            geometry = GeometryPlan(
+                primitive_strategy=["sketch", "extrude"],
+                features=[
+                    GeometryFeature(name="base_profile", feature_type="rectangle"),
+                    GeometryFeature(name="holes", feature_type="circular_cutouts", count=int(dimensions["hole_count"])),
+                ],
+            )
+            semantic_part = SemanticPart(category="profile", function="cut pattern", topology=["base plate", "openings"], symmetry="bilateral")
+        return SemanticCadSpec(
+            intent=prompt.strip(),
+            mode=mode,
             output_type="2d_vector",
-            geometry_family=family,
-            parameters=params,
-            style=_style_from_prompt(p, "diagrammatic"),
+            semantic_part=semantic_part,
+            family_hint=FamilyHint(name=family, generation_mode="reuse", confidence=0.75, novelty_score=0.25),
+            geometry=geometry,
+            dimensions=dimensions,
+            constraints=[],
+            style=SemanticStyle(keywords=_style_keywords_from_prompt(p, "diagrammatic"), symmetry=semantic_part.symmetry, manufacturing_bias="sheet_metal"),
+            dedupe=DedupeHint(canonical_signature=f"{family}|{sorted(dimensions.items())}"),
+            notes=["Concept-grade sketch/profile interpretation."],
         )
 
     if output_type == "surface":
         family = "canopy_surface" if any(word in p for word in ["roof", "canopy", "shell", "surface"]) else "lofted_panel"
         if family == "canopy_surface":
-            params = {
+            dimensions = {
                 "span": _extract_number(p, ["span", "width"], 160),
                 "depth": _extract_number(p, ["depth", "length"], 90),
                 "peak_height": _extract_number(p, ["peak", "height", "rise"], 38),
                 "thickness": _extract_number(p, ["thickness"], 2),
             }
+            features = [
+                GeometryFeature(name="base_section", feature_type="rectangle_profile"),
+                GeometryFeature(name="top_section", feature_type="scaled_rectangle_profile"),
+            ]
+            topology = ["base perimeter", "raised perimeter", "lofted shell"]
         else:
-            params = {
+            dimensions = {
                 "width": _extract_number(p, ["width", "span"], 80),
                 "depth": _extract_number(p, ["depth", "length"], 50),
                 "rise": _extract_number(p, ["rise", "height"], 18),
                 "thickness": _extract_number(p, ["thickness"], 2),
             }
-        return CadSpec(
+            features = [
+                GeometryFeature(name="lower_frame", feature_type="rectangle_profile"),
+                GeometryFeature(name="upper_frame", feature_type="scaled_rectangle_profile"),
+            ]
+            topology = ["lower frame", "upper frame", "lofted skin"]
+        return SemanticCadSpec(
+            intent=prompt.strip(),
+            mode=mode,
             output_type="surface",
-            geometry_family=family,
-            parameters=params,
-            style=_style_from_prompt(p, "smooth"),
+            semantic_part=SemanticPart(category="surface", function="enclosure/canopy", topology=topology, symmetry="bilateral"),
+            family_hint=FamilyHint(name=family, generation_mode="extend", confidence=0.7, novelty_score=0.45),
+            geometry=GeometryPlan(primitive_strategy=["loft", "offset"], features=features),
+            dimensions=dimensions,
+            constraints=[ConstraintRecord(kind="min", target="thickness", value=1.0)],
+            style=SemanticStyle(keywords=_style_keywords_from_prompt(p, "smooth"), symmetry="bilateral", manufacturing_bias="generic"),
+            dedupe=DedupeHint(canonical_signature=f"{family}|{sorted(dimensions.items())}"),
+            notes=["Surface interpretation remains concept-grade and may simplify shell behavior."],
         )
 
     if any(word in p for word in ["truss", "beam", "frame", "girder"]):
-        return CadSpec(
+        dimensions = {
+            "span": _extract_number(p, ["span", "length"], 140),
+            "height": _extract_number(p, ["height", "rise"], 24),
+            "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
+            "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
+        }
+        return SemanticCadSpec(
+            intent=prompt.strip(),
+            mode=mode,
             output_type="3d_solid",
-            geometry_family="truss_beam",
-            parameters={
-                "span": _extract_number(p, ["span", "length"], 140),
-                "height": _extract_number(p, ["height", "rise"], 24),
-                "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
-                "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
-            },
-            style=_style_from_prompt(p, "structural"),
+            semantic_part=SemanticPart(category="structure", function="spanning member", topology=["top chord", "bottom chord", "posts"], symmetry="bilateral"),
+            family_hint=FamilyHint(name="truss_beam", generation_mode="reuse", confidence=0.82, novelty_score=0.28),
+            geometry=GeometryPlan(
+                primitive_strategy=["extrude", "array", "boolean_compound"],
+                features=[
+                    GeometryFeature(name="top_chord", feature_type="beam_member"),
+                    GeometryFeature(name="bottom_chord", feature_type="beam_member"),
+                    GeometryFeature(name="posts", feature_type="vertical_members", count=int(dimensions["panel_count"]) + 1),
+                ],
+            ),
+            dimensions=dimensions,
+            constraints=[ConstraintRecord(kind="min", target="panel_count", value=3)],
+            style=SemanticStyle(keywords=_style_keywords_from_prompt(p, "structural"), symmetry="bilateral", manufacturing_bias="machined"),
+            dedupe=DedupeHint(canonical_signature=f"truss_beam|{sorted(dimensions.items())}"),
+            notes=["Maps to the current truss generator for execution."],
         )
 
     if any(word in p for word in ["tower", "block", "monolith"]):
-        return CadSpec(
+        dimensions = {
+            "width": _extract_number(p, ["width"], 30),
+            "length": _extract_number(p, ["length", "depth"], 30),
+            "height": _extract_number(p, ["height"], 120),
+            "notch": _extract_number(p, ["notch", "cut"], 10),
+        }
+        return SemanticCadSpec(
+            intent=prompt.strip(),
+            mode=mode,
             output_type="3d_solid",
-            geometry_family="tower_block",
-            parameters={
-                "width": _extract_number(p, ["width"], 30),
-                "length": _extract_number(p, ["length", "depth"], 30),
-                "height": _extract_number(p, ["height"], 120),
-                "notch": _extract_number(p, ["notch", "cut"], 10),
-            },
-            style=_style_from_prompt(p, "industrial"),
+            semantic_part=SemanticPart(category="mass", function="vertical block study", topology=["primary mass", "subtractive notches"], symmetry="bilateral"),
+            family_hint=FamilyHint(name="tower_block", generation_mode="extend", confidence=0.74, novelty_score=0.52),
+            geometry=GeometryPlan(
+                primitive_strategy=["box", "boolean_subtract"],
+                features=[
+                    GeometryFeature(name="main_mass", feature_type="box"),
+                    GeometryFeature(name="notches", feature_type="subtractive_blocks", count=2),
+                ],
+            ),
+            dimensions=dimensions,
+            constraints=[],
+            style=SemanticStyle(keywords=_style_keywords_from_prompt(p, "industrial"), symmetry="bilateral", manufacturing_bias="generic"),
+            dedupe=DedupeHint(canonical_signature=f"tower_block|{sorted(dimensions.items())}"),
+            notes=["Keeps tower prompts broad while still routing to the existing massing generator."],
         )
 
-    return CadSpec(
+    dimensions = {
+        "width": _extract_number(p, ["width", "span"], 80),
+        "height": _extract_number(p, ["height"], 50),
+        "thickness": _extract_number(p, ["thickness"], 6),
+        "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
+        "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
+    }
+    return SemanticCadSpec(
+        intent=prompt.strip(),
+        mode=mode,
         output_type="3d_solid",
-        geometry_family="bracket_plate",
-        parameters={
-            "width": _extract_number(p, ["width", "span"], 80),
-            "height": _extract_number(p, ["height"], 50),
-            "thickness": _extract_number(p, ["thickness"], 6),
-            "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
-            "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
-        },
-        style=_style_from_prompt(p, "industrial"),
+        semantic_part=SemanticPart(category="support", function="mounting/support part", topology=["plate body", "openings"], symmetry="bilateral"),
+        family_hint=FamilyHint(name="bracket_plate", generation_mode="extend", confidence=0.6, novelty_score=0.58),
+        geometry=GeometryPlan(
+            primitive_strategy=["extrude", "boolean_subtract"],
+            features=[
+                GeometryFeature(name="base_plate", feature_type="rectangular_plate"),
+                GeometryFeature(name="holes", feature_type="circular_cutouts", count=int(dimensions["hole_count"])),
+            ],
+        ),
+        dimensions=dimensions,
+        constraints=[ConstraintRecord(kind="min", target="thickness", value=2.0)],
+        style=SemanticStyle(keywords=_style_keywords_from_prompt(p, "industrial"), symmetry="bilateral", manufacturing_bias="machined"),
+        dedupe=DedupeHint(canonical_signature=f"bracket_plate|{sorted(dimensions.items())}"),
+        notes=["Default concept-grade support interpretation. Replace with true model output later for broader novelty."],
     )
 
 
@@ -257,12 +396,13 @@ def _generate_spec(payload: GenerateSpecRequest) -> GenerateSpecResponse:
             "Using conservative defaults and a simple geometry family.",
         ])
 
-    spec = _infer_spec(safe_prompt, payload.mode, payload.output_type)
+    spec = _infer_semantic_spec(safe_prompt, payload.mode, payload.output_type)
     response = GenerateSpecResponse(
         prompt_hash=key,
         spec=spec,
         notes=notes + [
-            "Prompt mapped into a structured CAD spec.",
+            "Prompt mapped into a structured compositional CAD spec.",
+            "This is still a stub translator, not the final model stage.",
             "Replace the stub router with a real HF endpoint later.",
         ],
         suspicious_input=suspicious_input,
@@ -314,6 +454,7 @@ def create_job(payload: CreateJobRequest, request: Request, x_api_key: str | Non
     )
     job.status = cast(str, "queued")
     save_job(job)
+    job.artifacts = []
     return job
 
 
@@ -323,7 +464,38 @@ def get_job(job_id: str, x_api_key: str | None = Header(default=None)) -> JobRec
     job = repo_get_job(job_id)
     if not job:
         raise HTTPException(status_code=404, detail="Job not found")
-    return JobRecord(**job)
+    return _job_with_artifacts(job)
+
+
+@app.post("/v1/jobs/{job_id}/artifacts", response_model=ArtifactUploadResponse)
+async def upload_job_artifact(
+    job_id: str,
+    kind: ArtifactKind = Form(...),
+    file: UploadFile = File(...),
+    x_api_key: str | None = Header(default=None),
+) -> ArtifactUploadResponse:
+    _check_auth(x_api_key)
+
+    job = repo_get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    if not _storage_ready():
+        raise HTTPException(status_code=503, detail="Supabase storage not configured")
+
+    blob = await file.read()
+    if not blob:
+        raise HTTPException(status_code=400, detail="Empty file upload")
+    if len(blob) > settings.storage_max_upload_bytes:
+        raise HTTPException(status_code=413, detail="File too large for configured upload limit")
+
+    suffix = os.path.splitext(file.filename or "")[1].lower()
+    safe_suffix = suffix if suffix in {".stl", ".step", ".stp", ".png", ".jpg", ".jpeg", ".webp"} else ""
+    storage_key = posixpath.join("jobs", job_id, f"{kind}{safe_suffix}")
+    content_type = file.content_type or "application/octet-stream"
+
+    _upload_bytes_to_supabase_storage(storage_key, blob, content_type)
+    saved = repo_create_artifact(job_id, kind, storage_key, len(blob))
+    return ArtifactUploadResponse(artifact=_artifact_to_record(saved))
 
 
 @app.get("/")

apps/backend-api/app/models.py

@@ -8,6 +8,10 @@ from pydantic import BaseModel, Field
 ModeType = Literal["part", "assembly", "sketch"]
 OutputType = Literal["2d_vector", "surface", "3d_solid"]
 JobStatus = Literal["submitted", "validated", "queued", "running", "completed", "failed"]
+ArtifactKind = Literal["stl", "step", "preview", "other"]
+GenerationMode = Literal["reuse", "extend", "new"]
+SymmetryType = Literal["bilateral", "radial", "asymmetric", "none"]
+ValueType = int | float | str | bool
 
 
 class GenerateSpecRequest(BaseModel):
@@ -37,17 +41,90 @@ class CadSpec(BaseModel):
     style: CadStyle
 
 
+class SemanticPart(BaseModel):
+    category: str | None = None
+    function: str | None = None
+    topology: list[str] = Field(default_factory=list)
+    symmetry: SymmetryType = "none"
+
+
+class GeometryFeature(BaseModel):
+    name: str
+    feature_type: str
+    count: int | None = None
+    attributes: dict[str, ValueType] = Field(default_factory=dict)
+
+
+class GeometryPlan(BaseModel):
+    primitive_strategy: list[str] = Field(default_factory=list)
+    features: list[GeometryFeature] = Field(default_factory=list)
+
+
+class ConstraintRecord(BaseModel):
+    kind: str
+    target: str
+    value: ValueType | None = None
+    reference: str | None = None
+    notes: str | None = None
+
+
+class SemanticStyle(BaseModel):
+    keywords: list[str] = Field(default_factory=list)
+    symmetry: SymmetryType = "none"
+    manufacturing_bias: str = "generic"
+
+
+class FamilyHint(BaseModel):
+    name: str | None = None
+    generation_mode: GenerationMode = "new"
+    parent_family: str | None = None
+    confidence: float | None = None
+    novelty_score: float | None = None
+
+
+class DedupeHint(BaseModel):
+    canonical_signature: str | None = None
+    similar_to_job_id: str | None = None
+    is_likely_duplicate: bool = False
+
+
+class SemanticCadSpec(BaseModel):
+    spec_version: str = "1.1"
+    intent: str
+    mode: ModeType = "part"
+    output_type: OutputType = "3d_solid"
+    units: str = "mm"
+    semantic_part: SemanticPart = Field(default_factory=SemanticPart)
+    family_hint: FamilyHint = Field(default_factory=FamilyHint)
+    geometry: GeometryPlan = Field(default_factory=GeometryPlan)
+    dimensions: dict[str, ValueType] = Field(default_factory=dict)
+    constraints: list[ConstraintRecord] = Field(default_factory=list)
+    style: SemanticStyle = Field(default_factory=SemanticStyle)
+    dedupe: DedupeHint = Field(default_factory=DedupeHint)
+    notes: list[str] = Field(default_factory=list)
+
+
 class GenerateSpecResponse(BaseModel):
     ok: bool = True
     cached: bool = False
     prompt_hash: str
-    spec: CadSpec
+    spec: CadSpec | SemanticCadSpec
     notes: list[str] = []
     model: str = "stub/template-router"
     suspicious_input: bool = False
     fallback_level: str = "normal"
 
 
+class ArtifactRecord(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    job_id: str
+    kind: ArtifactKind
+    storage_key: str
+    size_bytes: int | None = None
+    url: str | None = None
+    created_at: str | None = None
+
+
 class JobRecord(BaseModel):
     id: str = Field(default_factory=lambda: str(uuid4()))
     status: JobStatus = "submitted"
@@ -56,9 +133,15 @@ class JobRecord(BaseModel):
     output_type: OutputType = "3d_solid"
     session_id: str | None = None
     prompt_hash: str | None = None
-    spec: CadSpec | None = None
-    notes: list[str] = []
+    spec: CadSpec | SemanticCadSpec | None = None
+    notes: list[str] = Field(default_factory=list)
     error: str | None = None
+    artifacts: list[ArtifactRecord] = Field(default_factory=list)
+
+
+class ArtifactUploadResponse(BaseModel):
+    ok: bool = True
+    artifact: ArtifactRecord
 
 
 class HealthResponse(BaseModel):

apps/backend-api/app/repository.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from .db import connect, get_database_state, serialize_json
 from .models import JobRecord
-from .store import _JOBS
+from .store import _ARTIFACTS, _JOBS
 
 
 def save_job(job: JobRecord) -> None:
@@ -83,3 +83,74 @@ def get_job(job_id: str) -> dict[str, Any] | None:
         "notes": notes_json or [],
         "error": error_text,
     }
+
+
+def create_artifact(job_id: str, kind: str, storage_key: str, size_bytes: int | None) -> dict[str, Any]:
+    db_state = get_database_state()
+    if not db_state.enabled:
+        row = {
+            "id": f"{job_id}:{kind}:{len(_ARTIFACTS[job_id]) + 1}",
+            "job_id": job_id,
+            "kind": kind,
+            "storage_key": storage_key,
+            "size_bytes": size_bytes,
+            "created_at": None,
+        }
+        _ARTIFACTS[job_id].append(row)
+        return row
+
+    with connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                insert into artifacts (job_id, kind, storage_key, size_bytes)
+                values (%s, %s, %s, %s)
+                returning id, job_id, kind, storage_key, size_bytes, created_at
+                """,
+                (job_id, kind, storage_key, size_bytes),
+            )
+            row = cur.fetchone()
+        conn.commit()
+
+    artifact_id, r_job_id, r_kind, r_storage_key, r_size_bytes, r_created_at = row
+    return {
+        "id": str(artifact_id),
+        "job_id": str(r_job_id),
+        "kind": r_kind,
+        "storage_key": r_storage_key,
+        "size_bytes": r_size_bytes,
+        "created_at": r_created_at.isoformat() if r_created_at else None,
+    }
+
+
+def list_artifacts(job_id: str) -> list[dict[str, Any]]:
+    db_state = get_database_state()
+    if not db_state.enabled:
+        return list(_ARTIFACTS.get(job_id, []))
+
+    with connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                select id, job_id, kind, storage_key, size_bytes, created_at
+                from artifacts
+                where job_id = %s
+                order by created_at asc
+                """,
+                (job_id,),
+            )
+            rows = cur.fetchall() or []
+
+    out: list[dict[str, Any]] = []
+    for artifact_id, r_job_id, r_kind, r_storage_key, r_size_bytes, r_created_at in rows:
+        out.append(
+            {
+                "id": str(artifact_id),
+                "job_id": str(r_job_id),
+                "kind": r_kind,
+                "storage_key": r_storage_key,
+                "size_bytes": r_size_bytes,
+                "created_at": r_created_at.isoformat() if r_created_at else None,
+            }
+        )
+    return out

apps/backend-api/app/store.py

@@ -5,3 +5,4 @@ from collections import defaultdict, deque
 _REQUESTS: dict[str, deque[float]] = defaultdict(deque)
 _CACHE: dict[str, dict] = {}
 _JOBS: dict[str, dict] = {}
+_ARTIFACTS: dict[str, list[dict]] = defaultdict(list)

apps/backend-api/fly.toml

@@ -0,0 +1,22 @@
+# fly.toml app configuration file generated for natural-cad on 2026-04-11T20:14:32-07:00
+#
+# See https://fly.io/docs/reference/configuration/ for information about how to use this file.
+#
+
+app = 'natural-cad'
+primary_region = 'ord'
+
+[build]
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+  auto_stop_machines = 'stop'
+  auto_start_machines = true
+  min_machines_running = 0
+  processes = ['app']
+
+[[vm]]
+  memory = '1gb'
+  cpus = 1
+  memory_mb = 1024

apps/backend-api/requirements.txt

@@ -3,4 +3,5 @@ uvicorn[standard]>=0.30.0
 pydantic>=2.8.0
 python-dotenv>=1.0.1
 httpx>=0.27.0
+python-multipart>=0.0.9
 psycopg[binary]>=3.2.0

apps/gradio-demo/README.md

@@ -13,13 +13,34 @@ Gradio prototype for NaturalCAD, a public natural-language CAD modeler built on
 
 - Prompt-driven model generation through the NaturalCAD backend when available
 - Local fallback generation if the backend is unavailable
-- Run build123d geometry and see STL preview
+- Run build123d geometry and see a GLB preview in the browser
 - Download STL and STEP exports
+- Upload generated STL/STEP artifacts to backend storage when backend is configured
 - View backend + execution logs
 - Lightweight run logging for MVP testing data (`artifacts/logs/runs.jsonl`)
 
 ## Run locally
 
+From the repo root, the easiest path is:
+
+```bash
+npm run backend:local
+npm run frontend:local
+```
+
+Those commands use:
+- `scripts/run-local-backend.sh`
+- `scripts/run-local-frontend.sh`
+
+Frontend notes:
+- local Gradio 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`
+- it defaults `NATURALCAD_BACKEND_URL` to `http://127.0.0.1:8010`
+- if `apps/backend-api/.env` exists, it reuses `API_SHARED_SECRET` as `NATURALCAD_API_KEY`
+- override with `NATURALCAD_FRONTEND_VENV=/path/to/venv` if needed
+
+Manual fallback:
+
 Start the backend first:
 
 ```bash
@@ -41,14 +62,17 @@ Current Space-oriented dependency note:
 - if Hugging Face Space cannot reliably support the CAD dependency stack, we can keep the UI there and offload execution to a container or VM later without changing the product direction
 
 Optional environment variables:
-- `NATURALCAD_BACKEND_URL` (leave unset for a pure Space-only MVP, or set it to enable backend-assisted spec generation)
+- `NATURALCAD_BACKEND_URL` (leave unset for a pure Space-only MVP, or set it to enable backend-assisted spec generation + artifact upload)
 - `NATURALCAD_API_KEY`
 - `NATURALCAD_BACKEND_TIMEOUT` (default `4` seconds)
 - `BUILD123D_PYTHON` (defaults to the current Python runtime, which is better for Hugging Face Space deployment)
 
+When backend is enabled and returns a `job.id`, the app will POST STL/STEP files to:
+- `POST /v1/jobs/{job_id}/artifacts`
+
 Runtime artifacts:
-- latest files in `artifacts/`
-- archived runs in `artifacts/runs/`
+- latest files in `artifacts/` (`model.glb`, `model.stl`, `model.step`)
+- archived runs in `artifacts/runs/` (GLB preview is ephemeral and regenerated locally)
 - lightweight run logs in `artifacts/logs/runs.jsonl`
 
 Open http://localhost:7860

apps/gradio-demo/app/main.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import json
+import mimetypes
 import os
 import shutil
 import subprocess
@@ -17,6 +18,7 @@ from pathlib import Path
 from urllib import error, request
 
 import gradio as gr
+import trimesh
 
 BUILD123D_PYTHON = os.getenv("BUILD123D_PYTHON", sys.executable)
 BACKEND_URL = os.getenv("NATURALCAD_BACKEND_URL", os.getenv("NL_CAD_BACKEND_URL", "")).strip()
@@ -56,7 +58,74 @@ result = bp.part
 '''
 
 
+def _legacy_spec_from_semantic(spec: dict) -> dict:
+    if "geometry_family" in spec and "parameters" in spec:
+        return spec
+
+    family_hint = spec.get("family_hint") or {}
+    geometry = spec.get("geometry") or {}
+    semantic_part = spec.get("semantic_part") or {}
+    dimensions = dict(spec.get("dimensions") or {})
+    output_type = spec.get("output_type", "3d_solid")
+
+    geometry_family = family_hint.get("name")
+    if not geometry_family:
+        topology = " ".join(semantic_part.get("topology") or []).lower()
+        feature_types = " ".join((f.get("feature_type", "") for f in geometry.get("features") or [] if isinstance(f, dict))).lower()
+        if "truss" in topology or "truss" in feature_types or "span" in dimensions and "panel_count" in dimensions:
+            geometry_family = "truss_beam" if output_type != "2d_vector" else "truss_elevation"
+        elif output_type == "surface":
+            geometry_family = "canopy_surface"
+        elif "tower" in topology or "mass" in topology or "notch" in feature_types:
+            geometry_family = "tower_block"
+        else:
+            geometry_family = "bracket_plate"
+
+    params = dict(dimensions)
+    if output_type == "2d_vector":
+        params.setdefault("preview_thickness", 1)
+    if geometry_family == "bracket_plate":
+        params.setdefault("width", 80)
+        params.setdefault("height", 50)
+        params.setdefault("thickness", 6)
+        params.setdefault("hole_count", 4)
+        params.setdefault("hole_diameter", 10)
+    elif geometry_family == "truss_beam":
+        params.setdefault("span", 140)
+        params.setdefault("height", 24)
+        params.setdefault("panel_count", 7)
+        params.setdefault("member_size", 3)
+    elif geometry_family == "truss_elevation":
+        params.setdefault("span", 140)
+        params.setdefault("height", 24)
+        params.setdefault("panel_count", 7)
+        params.setdefault("member_size", 3)
+        params.setdefault("preview_thickness", 1)
+    elif geometry_family == "tower_block":
+        params.setdefault("width", 30)
+        params.setdefault("length", 30)
+        params.setdefault("height", 120)
+        params.setdefault("notch", 10)
+    elif geometry_family == "canopy_surface":
+        params.setdefault("span", 160)
+        params.setdefault("depth", 90)
+        params.setdefault("peak_height", 38)
+        params.setdefault("thickness", 2)
+    elif geometry_family == "lofted_panel":
+        params.setdefault("width", 80)
+        params.setdefault("depth", 50)
+        params.setdefault("rise", 18)
+        params.setdefault("thickness", 2)
+
+    return {
+        "geometry_family": geometry_family,
+        "output_type": output_type,
+        "parameters": params,
+    }
+
+
 def render_code_from_spec(spec: dict) -> str:
+    spec = _legacy_spec_from_semantic(spec)
     geometry_family = spec.get("geometry_family", "bracket_plate")
     output_type = spec.get("output_type", "3d_solid")
     params = spec.get("parameters", {})
@@ -258,16 +327,65 @@ def create_job(prompt: str, mode: str, output_type: str) -> tuple[dict | None, s
         return None, json.dumps({"error": f"backend unavailable: {exc}"}, indent=2)
 
 
+def upload_job_artifact(job_id: str, kind: str, path: str) -> tuple[dict | None, str]:
+    if not BACKEND_URL or not job_id:
+        return None, ""
+
+    file_path = Path(path)
+    if not file_path.exists():
+        return None, json.dumps({"error": f"artifact path missing: {path}"}, indent=2)
+
+    boundary = f"----naturalcad-{uuid.uuid4().hex}"
+    content_type = mimetypes.guess_type(file_path.name)[0] or "application/octet-stream"
+    file_bytes = file_path.read_bytes()
+
+    body = bytearray()
+    body.extend(f"--{boundary}\r\n".encode())
+    body.extend(b'Content-Disposition: form-data; name="kind"\r\n\r\n')
+    body.extend(kind.encode())
+    body.extend(b"\r\n")
+
+    body.extend(f"--{boundary}\r\n".encode())
+    body.extend(
+        f'Content-Disposition: form-data; name="file"; filename="{file_path.name}"\r\n'.encode()
+    )
+    body.extend(f"Content-Type: {content_type}\r\n\r\n".encode())
+    body.extend(file_bytes)
+    body.extend(b"\r\n")
+    body.extend(f"--{boundary}--\r\n".encode())
+
+    headers = {"Content-Type": f"multipart/form-data; boundary={boundary}"}
+    if BACKEND_API_KEY:
+        headers["x-api-key"] = BACKEND_API_KEY
+
+    req = request.Request(
+        f"{BACKEND_URL.rstrip('/')}/v1/jobs/{job_id}/artifacts",
+        data=bytes(body),
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with request.urlopen(req, timeout=BACKEND_TIMEOUT_SECONDS) as response:
+            data = json.loads(response.read().decode())
+            return data, json.dumps(data, indent=2)
+    except error.HTTPError as exc:
+        detail = exc.read().decode() if exc.fp else str(exc)
+        return None, json.dumps({"error": f"artifact upload http {exc.code}", "detail": detail}, indent=2)
+    except Exception as exc:  # noqa: BLE001
+        return None, json.dumps({"error": f"artifact upload failed: {exc}"}, indent=2)
+
+
 def _append_run_log(entry: dict) -> None:
     with RUN_LOG_PATH.open("a", encoding="utf-8") as fh:
         fh.write(json.dumps(entry) + "\n")
 
 
-def run_build123d(code: str, prompt: str = "") -> tuple[str | None, str | None, str, str, str | None, float]:
+def run_build123d(code: str, prompt: str = "") -> tuple[str | None, str | None, str | None, str, str, str | None, float]:
     if not code or not code.strip():
-        return None, None, "No code provided.", "No geometry was generated.", None, 0.0
+        return None, None, None, "No code provided.", "No geometry was generated.", None, 0.0
 
     logs: list[str] = []
+    glb_path: str | None = None
     stl_path: str | None = None
     step_path: str | None = None
     started_at = time.time()
@@ -278,6 +396,7 @@ def run_build123d(code: str, prompt: str = "") -> tuple[str | None, str | None,
         source_file.write_text(code)
         stl_file = RUNS_DIR / f"{run_id}.stl"
         step_file = RUNS_DIR / f"{run_id}.step"
+        glb_file = RUNS_DIR / f"{run_id}.glb"
 
         logs.append(f"Run ID: {run_id}")
         if prompt.strip():
@@ -337,10 +456,24 @@ print("STEP exported to {step_file}")
             if result.returncode == 0 and stl_file.exists() and step_file.exists():
                 latest_stl = ARTIFACTS_DIR / "model.stl"
                 latest_step = ARTIFACTS_DIR / "model.step"
+                latest_glb = ARTIFACTS_DIR / "model.glb"
                 shutil.copy2(stl_file, latest_stl)
                 shutil.copy2(step_file, latest_step)
                 stl_path = str(latest_stl)
                 step_path = str(latest_step)
+
+                try:
+                    preview_mesh = trimesh.load_mesh(stl_file, force="mesh")
+                    preview_mesh.apply_transform(
+                        trimesh.transformations.rotation_matrix(-1.5707963267948966, [1, 0, 0])
+                    )
+                    preview_mesh.export(glb_file)
+                    shutil.copy2(glb_file, latest_glb)
+                    glb_path = str(latest_glb)
+                    logs.append(f"GLB preview exported to {latest_glb}")
+                except Exception as exc:  # noqa: BLE001
+                    logs.append(f"GLB preview export failed: {exc}")
+
                 logs.append(f"Export successful. Archived artifacts at runs/{run_id}.*")
             else:
                 logs.append(f"Runner exited with code {result.returncode}.")
@@ -352,7 +485,7 @@ print("STEP exported to {step_file}")
 
     duration = time.time() - started_at
     summary = f"Model ready in {duration:.2f}s."
-    return stl_path, step_path, "\n".join(logs), summary, run_id, duration
+    return glb_path, stl_path, step_path, "\n".join(logs), summary, run_id, duration
 
 
 def generate_from_prompt(prompt: str, mode: str, output_type: str):
@@ -394,14 +527,14 @@ def generate_from_prompt(prompt: str, mode: str, output_type: str):
             return None, None, None, backend_log, "Backend created no CAD spec."
 
     code = render_code_from_spec(spec)
-    stl_path, step_path, logs, summary, run_id, execution_seconds = run_build123d(code, prompt)
+    glb_path, stl_path, step_path, logs, summary, run_id, execution_seconds = run_build123d(code, prompt)
     combined_logs = "\n\n".join([
         "Backend job created:" if backend_ok else "Backend unavailable, using local fallback:",
         backend_log,
         "Local execution log:",
         logs,
     ])
-    success = bool(stl_path)
+    success = bool(step_path and (glb_path or stl_path))
     _append_run_log({
         "timestamp": datetime.now(timezone.utc).isoformat(),
         "run_id": run_id,
@@ -417,11 +550,25 @@ def generate_from_prompt(prompt: str, mode: str, output_type: str):
         "execution_seconds": round(execution_seconds, 3),
         "error": None if success else "Generation failed.",
     })
-    if not stl_path:
+    if not step_path:
         return None, None, None, combined_logs, "Generation failed. Try a simpler prompt or an example."
 
+    job_id = str((job_data or {}).get("id", ""))
+    if backend_ok and job_id:
+        upload_logs: list[str] = []
+        _, stl_upload_log = upload_job_artifact(job_id, "stl", stl_path)
+        if stl_upload_log:
+            upload_logs.append("STL upload:\n" + stl_upload_log)
+        if step_path:
+            _, step_upload_log = upload_job_artifact(job_id, "step", step_path)
+            if step_upload_log:
+                upload_logs.append("STEP upload:\n" + step_upload_log)
+        if upload_logs:
+            combined_logs = "\n\n".join([combined_logs, "Artifact uploads:", *upload_logs])
+
     final_summary = summary if not client_notice else f"{summary}\n\n⚠️ {client_notice}"
-    return stl_path, stl_path, step_path, combined_logs, final_summary
+    preview_path = glb_path or stl_path
+    return preview_path, stl_path, step_path, combined_logs, final_summary
 
 
 def use_example(prompt: str, mode: str, output_type: str):

docs/backend-v0.md

@@ -235,6 +235,28 @@ Recommendation:
 ### Phase 4
 - tighten retention, add auth tiers, add cancellation, add preview generation
 
+## Spec direction for the next phase
+
+NaturalCAD should move next toward a **loose compositional / semantic JSON spec** rather than a rigid family-first schema.
+
+Reason:
+- rigid family routing too early will bias the model toward repetitive safe defaults
+- concept-grade generation needs room for novelty, unexpected topology, and broader prompt coverage
+- reuse and dedupe should exist, but as later optimization layers rather than the main creative frame
+
+Recommended next spec target:
+- `intent`
+- `semantic_part`
+- `family_hint` (optional, not dominant)
+- `geometry`
+- `dimensions`
+- `constraints`
+- `style`
+- `dedupe`
+
+Reference:
+- `docs/compositional-spec-v1.1.md`
+
 ## What not to do in v0
 
 - no public arbitrary Python execution

docs/compositional-spec-v1.1.md

@@ -0,0 +1,137 @@
+# NaturalCAD Compositional Spec v1.1
+
+## Why this exists
+
+NaturalCAD is currently targeting **concept-grade** generation, not fabrication-grade precision.
+That means the next spec should stay loose enough to support novel and unexpected objects, instead of forcing every prompt into a tiny menu of safe default families.
+
+This spec is meant to capture:
+- intent
+- semantic part meaning
+- topology/composition
+- geometry features and operations
+- dimensions
+- constraints
+- style cues
+
+It is intentionally less rigid than a true later-phase spec-to-model contract.
+
+## Design goals
+
+1. Preserve novelty and surprise
+2. Avoid collapsing every prompt into the same default family
+3. Capture enough structure to support execution and logging
+4. Leave room for later hardening into stricter parametric generators
+
+## Shape
+
+```json
+{
+  "spec_version": "1.1",
+  "intent": "Offset wall support with ribbed spine and staggered mounting tabs",
+  "mode": "part",
+  "output_type": "3d_solid",
+  "units": "mm",
+  "semantic_part": {
+    "category": "support",
+    "function": "wall-mounted load transfer",
+    "topology": ["main spine", "2 mounting tabs", "reinforcing ribs"],
+    "symmetry": "asymmetric"
+  },
+  "family_hint": {
+    "name": "support_bracket",
+    "generation_mode": "extend",
+    "parent_family": null,
+    "confidence": 0.64,
+    "novelty_score": 0.72
+  },
+  "geometry": {
+    "primitive_strategy": ["extrude", "boolean_subtract", "fillet"],
+    "features": [
+      {
+        "name": "spine",
+        "feature_type": "tapered_plate",
+        "attributes": {"taper_ratio": 0.7}
+      },
+      {
+        "name": "tabs",
+        "feature_type": "offset_mounts",
+        "count": 2,
+        "attributes": {"tab_offset": 18}
+      },
+      {
+        "name": "ribs",
+        "feature_type": "triangular_gusset",
+        "count": 3,
+        "attributes": {"rib_depth": 10}
+      }
+    ]
+  },
+  "dimensions": {
+    "overall_height": 120,
+    "overall_width": 60,
+    "overall_depth": 45
+  },
+  "constraints": [
+    {
+      "kind": "min",
+      "target": "wall_thickness",
+      "value": 6
+    }
+  ],
+  "style": {
+    "keywords": ["industrial", "structural", "heavy-duty"],
+    "symmetry": "asymmetric",
+    "manufacturing_bias": "machined"
+  },
+  "dedupe": {
+    "canonical_signature": null,
+    "similar_to_job_id": null,
+    "is_likely_duplicate": false
+  },
+  "notes": [
+    "Treat as a concept-grade structural support rather than a fabrication-verified design."
+  ]
+}
+```
+
+## Interpretation notes
+
+### `intent`
+A concise restatement of what the prompt is trying to produce.
+
+### `semantic_part`
+Describes what the object is and how it is composed, without prematurely locking it into a rigid generator family.
+
+### `family_hint`
+Optional. This should be treated as a backend hint, not as the main creative frame.
+- `reuse`: known generator likely fits
+- `extend`: known generator likely fits with variation
+- `new`: likely needs a new generator path or a looser execution strategy
+
+### `geometry`
+Captures operations and features. This is closer to executable structure than pure natural language, while still leaving room for novelty.
+
+### `dimensions`
+Stores named scale-driving values. These should stay loose in concept-grade mode, then become more constrained in later phases.
+
+### `constraints`
+Carries guardrails and relationships, but should not yet be treated as full fabrication-grade tolerance logic.
+
+### `dedupe`
+Supports later duplicate detection and lineage without dominating the first-pass generation stage.
+
+## Current recommendation
+
+Use this spec as the next target for:
+- backend model output
+- prompt logging
+- evaluation
+- future prompt-to-build123d translation
+
+Current repo status:
+- `POST /v1/generate-spec` now emits this general semantic shape through a stub translator
+- the Gradio app temporarily adapts the semantic spec back into the older generator families for execution
+- this keeps the contract moving forward without breaking the current build123d demo path
+
+Do not over-tighten it yet. NaturalCAD still needs room for new and unexpected objects.

docs/hf-space-deploy-checklist.md

@@ -20,6 +20,21 @@ For the lean MVP, backend use should be optional, not assumed. If `NATURALCAD_BA
 
 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: Fly.io
+- current recommended backend port: `8000`
+- backend should expose `GET /v1/health`, `POST /v1/generate-spec`, `POST /v1/jobs`, and `POST /v1/jobs/{job_id}/artifacts`
+
+Runtime note:
+- the Space Docker image must include the native stack needed by `build123d` / `OCP`
+- current Dockerfile installs both `ocp=7.8.1` and `vtk=9.3` in the Conda env to avoid the missing `libvtkWrappingPythonCore3.10-9.3.so` runtime error
+
 ## Data to capture
 
 - timestamp

package.json

@@ -2,6 +2,10 @@
   "name": "live-visualizer",
   "private": true,
   "version": "0.1.0",
+  "scripts": {
+    "backend:local": "./scripts/run-local-backend.sh",
+    "frontend:local": "./scripts/run-local-frontend.sh"
+  },
   "workspaces": [
     "apps/*",
     "packages/*"

scripts/run-local-backend.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+BACKEND_DIR="$ROOT/apps/backend-api"
+
+cd "$BACKEND_DIR"
+
+if [[ ! -d .venv ]]; then
+  python3 -m venv .venv
+fi
+
+source .venv/bin/activate
+pip install -r requirements.txt
+exec uvicorn app.main:app --reload --port "${NATURALCAD_BACKEND_PORT:-8010}"

scripts/run-local-frontend.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VENV_DEFAULT="$HOME/.openclaw/workspace/.venvs/cadrender312"
+VENV_PATH="${NATURALCAD_FRONTEND_VENV:-$VENV_DEFAULT}"
+BACKEND_ENV_PATH="$ROOT/apps/backend-api/.env"
+
+if [[ ! -x "$VENV_PATH/bin/python3" ]]; then
+  echo "NaturalCAD frontend venv not found at: $VENV_PATH" >&2
+  echo "Set NATURALCAD_FRONTEND_VENV=/path/to/venv if you want to use a different one." >&2
+  exit 1
+fi
+
+if [[ -z "${NATURALCAD_BACKEND_URL:-}" ]]; then
+  export NATURALCAD_BACKEND_URL="http://127.0.0.1:8010"
+fi
+
+if [[ -z "${NATURALCAD_API_KEY:-}" && -f "$BACKEND_ENV_PATH" ]]; then
+  backend_secret="$(grep '^API_SHARED_SECRET=' "$BACKEND_ENV_PATH" | tail -n 1 | cut -d= -f2-)"
+  if [[ -n "$backend_secret" ]]; then
+    export NATURALCAD_API_KEY="$backend_secret"
+  fi
+fi
+
+cd "$ROOT"
+source "$VENV_PATH/bin/activate"
+pip install -r requirements.txt
+exec python3 app.py