Merge pull request #1 from danghoangnhan/feat/tests-readme-ai-quality

.dockerignore

@@ -0,0 +1,8 @@
+.git
+__pycache__
+*.pyc
+output/
+.superpowers/
+.venv/
+docs/
+.env

.gitignore

@@ -1,3 +1,7 @@
 __pycache__/
 *.pyc
 output/
+.superpowers/
+.venv/
+.worktrees/
+.env

Dockerfile

@@ -0,0 +1,46 @@
+# ── Stage 1: Builder ─────────────────────────────────────────────────────
+FROM python:3.11-slim AS builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+# Install dependencies (cached layer — only rebuilds when deps change)
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Copy source code
+COPY . .
+
+# ── Stage 2: Runtime ─────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+# Install runtime system dependencies required by OpenCascade (CadQuery)
+RUN --mount=type=cache,target=/var/cache/apt \
+    --mount=type=cache,target=/var/lib/apt/lists \
+    apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 libglib2.0-0 libx11-6 libxrender1
+
+WORKDIR /app
+
+# Copy virtual environment from builder
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy application source
+COPY --from=builder /app/core /app/core/
+COPY --from=builder /app/server /app/server/
+COPY --from=builder /app/agents /app/agents/
+COPY --from=builder /app/web /app/web/
+COPY --from=builder /app/entrypoint.sh /app/
+
+# Put venv on PATH
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONUNBUFFERED=1
+
+# Create output directory
+RUN mkdir -p /app/output
+
+EXPOSE 7860
+
+ENTRYPOINT ["/bin/bash", "/app/entrypoint.sh"]

README.md

@@ -1,131 +1,194 @@
-# Text-to-CNC: Generative Model Pipeline
+---
+title: NeuralCAD
+emoji: ⚙️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+---
 
-A proof-of-concept pipeline that converts natural language descriptions of mechanical parts into CNC-machinable 3D models (STEP/STL), using an LLM to generate CadQuery code.
+# NeuralCAD — Multi-Agent CAD Design
 
-## Architecture
+A multi-agent AI system that converts natural language descriptions of mechanical parts into CNC-machinable 3D models (STEP/STL). Four specialized AI agents collaborate with you in a shared chat to design, engineer, validate, and generate CadQuery code.
+
+## How It Works
 
 ```
-Text Prompt ──→ LLM (Claude/GPT-4/Mock) ──→ CadQuery Python Code
-                                                     │
-                                              Execute in Sandbox
-                                                     │
-                                              3D Solid (B-rep)
-                                               ╱           ╲
-                                     CNC Validator      Exporter
-                                     (machinability     (STEP + STL)
-                                      checks)
+User ──→ Chat Interface ──→ Agent Orchestrator
+                                    │
+                    ┌───────────────┼───────────────┐
+                    │               │               │
+              Design Agent    Engineering     CNC Agent
+              (form/shape)    Agent           (manufacturability)
+                    │         (specs/dims)          │
+                    └───────────────┼───────────────┘
+                                    │
+                              CAD Coder Agent
+                              (CadQuery code)
+                                    │
+                            Execute in Sandbox
+                                    │
+                              3D Solid (B-rep)
+                               ╱           ╲
+                     CNC Validator      Exporter
+                     (machinability     (STEP + STL)
+                      checks)
 ```
 
-## Pipeline Stages
+## Agents
 
-1. **Prompt → Code**: A domain-tuned system prompt with CNC-specific instructions and few-shot examples guides the LLM to generate valid CadQuery scripts
-2. **Code → Solid**: Sandboxed execution with automatic import handling and error capture
-3. **Solid → Validation**: Checks for wall thickness, tool access, aspect ratios, surface complexity, and recommends axis configuration (3/3+2/5-axis)
-4. **Solid → Export**: STEP (parametric, CAM-ready) and STL (mesh) output
-5. **Auto-retry**: If code execution fails, the error is fed back to the LLM for self-correction
+| Agent | Role | Expertise |
+|-------|------|-----------|
+| **Design Agent** | Industrial Designer | Form, aesthetics, ergonomics, shape proposals |
+| **Engineering Agent** | Mechanical Engineer | Dimensions, tolerances, materials, fastener specs |
+| **CNC Agent** | Manufacturing Advisor | Tool access, wall thickness, axis requirements, cost |
+| **CAD Coder** | CadQuery Programmer | Generates valid CadQuery Python code on demand |
 
 ## Quick Start
 
 ```bash
+# Install dependencies
 pip install -r requirements.txt
 
-# Mock backend (no API key needed)
-python pipeline.py "A mounting bracket with four M6 holes"
+# Run the web app (mock backend, no API key needed)
+python -m server.web --port 5000
 
-# With Claude
+# Open http://localhost:5000 in your browser
+```
+
+### With LLM Backends
+
+```bash
+# Gemini (free tier)
+export GOOGLE_API_KEY=...
+# Select GEMINI in the web UI backend toggle
+
+# Claude (recommended for quality)
 export ANTHROPIC_API_KEY=sk-ant-...
-python pipeline.py "A flanged bearing housing" --backend anthropic
+# Select CLAUDE in the web UI backend toggle
 
-# With GPT-4o
+# GPT-4o
 export OPENAI_API_KEY=sk-...
-python pipeline.py "A motor mount plate" --backend openai
 ```
 
-## MCP Server (Model Context Protocol)
+### CLI Pipeline (Direct)
 
-The pipeline is also exposed as an MCP server, so Claude Desktop, Claude Code, or any MCP-compatible agent can call it as a tool.
+```bash
+# Mock backend
+python -m core.pipeline "A mounting bracket with four M6 holes"
 
-### MCP Tools
+# With Claude
+python -m core.pipeline "A flanged bearing housing" --backend anthropic
+```
 
-| Tool | Description |
-|------|-------------|
-| `generate_cnc_model` | Text prompt → CadQuery code → 3D solid → STEP/STL with CNC validation |
-| `validate_cnc_model` | Run manufacturability checks on existing CadQuery code |
-| `execute_cadquery_code` | Execute arbitrary CadQuery code and get geometry info |
-| `list_models` | List previously generated models in the output directory |
+## Architecture
 
-### Connect to Claude Desktop
+```
+NeuralCAD/
+├── agents/                  # Multi-agent orchestration
+│   ├── definitions.py       # Agent roles, colors, personas
+│   ├── orchestrator.py      # Single-call + Mock orchestrators
+│   ├── crew_orchestrator.py # CrewAI multi-call orchestrator
+│   ├── prompts.py           # System prompts, routing, JSON parsing
+│   ├── design_state.py      # Design decision accumulator
+│   └── llm_adapter.py       # CrewAI LLM adapter
+├── core/                    # CAD generation pipeline
+│   ├── backends.py          # LLM backends (Mock, Anthropic, OpenAI, Gemini)
+│   ├── pipeline.py          # Text-to-CNC orchestrator + CLI
+│   ├── executor.py          # Sandboxed CadQuery execution + export
+│   ├── validator.py         # CNC manufacturability checker
+│   └── cadquery_prompts.py  # CadQuery system prompt + few-shot examples
+├── server/                  # Web + MCP servers
+│   ├── web.py               # FastAPI app, static serving
+│   ├── routes.py            # Chat API endpoints
+│   └── mcp.py               # MCP server (Claude Desktop / Claude Code)
+├── web/
+│   └── index.html           # Frontend: Three.js viewer + chat panel
+└── tests/                   # Test suite
+```
 
-Add to your `claude_desktop_config.json`:
+### Orchestration Modes
+
+| Backend | Mode | API Calls/Turn | Use Case |
+|---------|------|----------------|----------|
+| Mock | Template-based | 0 | UI development, demos |
+| Gemini | Single-call | 1 | Free tier, rate-limited |
+| Anthropic | CrewAI multi-call | 2-4 | Best quality |
+| OpenAI | CrewAI multi-call | 2-4 | Best quality |
+
+### Chat API
+
+**POST /api/chat** — Multi-agent chat turn
 
 ```json
 {
-  "mcpServers": {
-    "text-to-cnc": {
-      "command": "python3",
-      "args": ["/path/to/text-to-cnc/mcp_server.py"]
-    }
-  }
+  "message": "Make it 60mm wide with M4 base mounting",
+  "history": [{"role": "user", "content": "I need a servo bracket"}],
+  "mentions": [],
+  "backend": "mock"
 }
 ```
 
-### Connect to Claude Code
+**POST /api/report** — Generate design report from conversation
 
-```bash
-claude mcp add text-to-cnc python3 /path/to/text-to-cnc/mcp_server.py
-```
+**GET /api/agents** — List available agents and metadata
 
-### Run standalone
+## Features
 
-```bash
-# stdio (for Claude Desktop / Claude Code)
-python mcp_server.py
+- **Multi-agent chat** — 4 specialist agents collaborate on part design
+- **@mention system** — Direct messages to specific agents (`@design`, `@engineering`, `@cnc`, `@cad`)
+- **3D preview** — Real-time STL rendering with Three.js (orbit, zoom, pan)
+- **Design state tracking** — Accumulates decisions across turns (localStorage persistence)
+- **CNC validation** — Checks wall thickness, pocket ratios, tool access, axis requirements
+- **Model gallery** — Browse and reload previously generated models
+- **STEP + STL export** — Download CAM-ready files
+- **MCP server** — Use from Claude Desktop or Claude Code
 
-# SSE (for remote / web integrations)
-python mcp_server.py --transport sse --port 8000
-```
+## MCP Server
 
-## Files
+```bash
+# Connect to Claude Code
+claude mcp add text-to-cnc python3 -m server.mcp
 
-| File | Purpose |
-|------|---------|
-| `mcp_server.py` | MCP server exposing pipeline as tools |
-| `pipeline.py` | Main orchestrator + CLI entry point |
-| `cadquery_system_prompt.py` | LLM system prompt + few-shot examples |
-| `code_executor.py` | Sandboxed CadQuery execution + STEP/STL export |
-| `cnc_validator.py` | CNC manufacturability checker |
-| `claude_desktop_config.json` | Example Claude Desktop config |
-| `requirements.txt` | Python dependencies |
+# Run standalone (SSE for remote integrations)
+python -m server.mcp --transport sse --port 8000
+```
 
-## LLM Backends
+### MCP Tools
 
-- **MockBackend**: Pre-written responses for testing (no API key needed)
-- **AnthropicBackend**: Claude Sonnet (recommended for code generation quality)
-- **OpenAIBackend**: GPT-4o
+| Tool | Description |
+|------|-------------|
+| `generate_cnc_model` | Text to CadQuery code to 3D solid to STEP/STL |
+| `validate_cnc_model` | Run manufacturability checks on CadQuery code |
+| `execute_cadquery_code` | Execute arbitrary CadQuery code |
+| `chat_turn` | Multi-agent chat turn |
+| `list_models` | List generated models |
 
-## CNC Validation Checks
+## Testing
 
-The validator inspects the generated solid for:
+```bash
+# All tests
+python -m pytest
 
-- **Size feasibility** — fits within a typical CNC work envelope
-- **Thin features** — edges below minimum wall thickness
-- **Deep pockets** — aspect ratios requiring long-reach tooling
-- **Surface complexity** — freeform surfaces needing 3D contouring
-- **Face/edge count** — complexity proxy for axis recommendation
-- **Fill ratio** — material removal estimate
+# Pure logic tests only (no CadQuery needed)
+python -m pytest -m "not requires_cadquery"
 
-## Extending the Pipeline
+# Integration tests
+python -m pytest -m requires_cadquery
 
-**To add a new LLM backend**: Subclass `LLMBackend` and implement `generate(messages) -> str`.
+# Verbose
+python -m pytest -v
+```
 
-**To add CNC validation rules**: Add check functions in `cnc_validator.py` inside `validate_for_cnc()`.
+## Docker
 
-**To fine-tune for production**: Replace the few-shot prompting with a fine-tuned model trained on the DeepCAD, ABC, or SldprtNet datasets (see research notes).
+```bash
+docker compose up --build
+# Open http://localhost:7860
+```
 
-## Key Research Papers
+## Key Research
 
 - **Text-to-CadQuery** (2025) — LLM generates CadQuery code directly
-- **GenCAD** (2024) — Transformer + diffusion for image→CAD sequences
+- **GenCAD** (2024) — Transformer + diffusion for image to CAD
 - **NURBGen** (2025) — NURBS-based B-rep from text via LLM
-- **STEP-LLM** (2026) — Direct STEP file generation from natural language
-- **SldprtNet** (2026) — Large-scale multimodal industrial parts dataset

agents/crew_orchestrator.py

@@ -0,0 +1,311 @@
+"""CrewAI multi-call orchestrator for paid API backends (Anthropic/OpenAI).
+
+Uses CrewAI's sequential process where each specialist agent gets its own
+focused LLM call. A routing step selects which agents respond, then each
+agent reasons independently with its own context.
+
+Better quality than single-call (agents can truly disagree / specialize)
+but uses 2-4 API calls per turn. Used for paid backends only.
+
+Falls back to SingleCallOrchestrator if CrewAI is not installed.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+from agents.definitions import AGENTS
+from agents.design_state import DesignState, extract_decisions
+from agents.prompts import CAD_TRIGGER_KEYWORDS, route_by_keywords
+from agents.orchestrator import _format_response, _execute_cad_code
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_OUTPUT_DIR = Path(__file__).parent.parent / "output"
+
+
+def _build_agent_context(
+    message: str,
+    history: list[dict],
+    design_state: DesignState,
+    max_history: int = 20,
+) -> str:
+    """Build a shared context string that each CrewAI agent receives."""
+    parts = []
+
+    # Design state
+    spec = design_state.render()
+    if spec:
+        parts.append(f"## Current Design Spec\n{spec}")
+
+    # Recent conversation (compact)
+    recent = history[-max_history:] if len(history) > max_history else history
+    if recent:
+        lines = []
+        for msg in recent:
+            if msg.get("role") == "user":
+                lines.append(f"USER: {msg.get('content', '')}")
+            else:
+                aid = msg.get("agent_id", "unknown")
+                name = AGENTS.get(aid, AGENTS["design"]).name
+                lines.append(f"{name.upper()}: {msg.get('content', '')}")
+        parts.append("## Recent conversation\n" + "\n".join(lines))
+
+    parts.append(f"## User's latest message\n{message}")
+    return "\n\n".join(parts)
+
+
+class CrewOrchestrator:
+    """Multi-call orchestrator using CrewAI.
+
+    Each selected agent gets its own LLM call with focused context and
+    persona, producing genuinely independent reasoning.
+
+    Falls back to SingleCallOrchestrator if CrewAI is not installed.
+    """
+
+    def __init__(
+        self,
+        backend_name: str = "anthropic",
+        output_dir: Path | str = DEFAULT_OUTPUT_DIR,
+    ):
+        self.backend_name = backend_name
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self._crew_available = self._check_crewai()
+
+    @staticmethod
+    def _check_crewai() -> bool:
+        try:
+            import importlib.util
+            return importlib.util.find_spec("crewai") is not None
+        except (ImportError, ModuleNotFoundError):
+            return False
+
+    # ── Public interface ───────────────────────────────────────────────────
+
+    def chat_turn(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None = None,
+        max_history: int = 30,
+        design_state: dict | None = None,
+    ) -> dict:
+        """Run one chat turn.  Returns the standard response envelope."""
+        if not self._crew_available:
+            return self._fallback(message, history, mentions, max_history, design_state)
+
+        try:
+            return self._run_crew(message, history, mentions, max_history, design_state)
+        except Exception as exc:
+            logger.warning("CrewAI run failed (%s), falling back to single-call", exc)
+            return self._fallback(message, history, mentions, max_history, design_state)
+
+    # ── CrewAI implementation ──────────────────────────────────────────────
+
+    def _run_crew(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None,
+        max_history: int,
+        design_state_dict: dict | None,
+    ) -> dict:
+        from crewai import Agent, Task, Crew, Process
+
+        state = DesignState(**(design_state_dict or {}))
+        context = _build_agent_context(message, history, state, max_history)
+
+        # Select which agents should respond
+        if mentions:
+            active_ids = mentions
+        else:
+            active_ids = route_by_keywords(message)
+
+        # Check CAD trigger
+        include_cad = "cad" in active_ids
+        if not include_cad:
+            include_cad = any(kw in message.lower() for kw in CAD_TRIGGER_KEYWORDS)
+            if include_cad and "cad" not in active_ids:
+                active_ids.append("cad")
+
+        # Build the LLM adapter
+        llm = self._build_llm()
+
+        # Create CrewAI agents + tasks for selected agents
+        crew_agents = []
+        crew_tasks = []
+
+        for agent_id in active_ids:
+            if agent_id not in AGENTS:
+                continue
+            agent_def = AGENTS[agent_id]
+
+            # Special instructions for CAD Coder
+            extra = ""
+            if agent_id == "cad":
+                from core.cadquery_prompts import CADQUERY_SYSTEM_PROMPT
+                extra = (
+                    "\n\nWhen generating code, output ONLY valid CadQuery Python. "
+                    "The code must assign the result to a variable called `result` "
+                    "as a cq.Workplane object. Import cadquery as cq.\n\n"
+                    f"CadQuery reference:\n{CADQUERY_SYSTEM_PROMPT}"
+                )
+
+            crew_agent = Agent(
+                role=agent_def.role,
+                goal=agent_def.goal,
+                backstory=agent_def.backstory + extra,
+                llm=llm,
+                verbose=False,
+                allow_delegation=False,
+            )
+
+            task_description = (
+                f"{context}\n\n"
+                f"As the {agent_def.role}, respond to the user's latest message. "
+                f"Keep your response concise (2-4 sentences). "
+                f"Do NOT repeat anything from the conversation history. "
+                f"Add NEW information from your expertise."
+            )
+            if agent_id == "cad":
+                task_description += (
+                    "\n\nGenerate CadQuery Python code based on the design spec "
+                    "and conversation. Output ONLY the Python code, nothing else."
+                )
+
+            task = Task(
+                description=task_description,
+                expected_output=(
+                    "A concise response from your expert perspective (2-4 sentences)."
+                    if agent_id != "cad"
+                    else "Valid CadQuery Python code that assigns result to a cq.Workplane."
+                ),
+                agent=crew_agent,
+            )
+
+            crew_agents.append(crew_agent)
+            crew_tasks.append(task)
+
+        if not crew_agents:
+            return {"responses": [], "preview": None, "design_state": state.model_dump()}
+
+        # Run the crew — sequential process so each agent runs independently
+        crew = Crew(
+            agents=crew_agents,
+            tasks=crew_tasks,
+            process=Process.sequential,
+            verbose=False,
+        )
+
+        crew_result = crew.kickoff()
+
+        # Parse results into standard response format
+        responses = []
+        preview = None
+
+        # crew_result.tasks_output gives per-task results
+        task_outputs = crew_result.tasks_output if hasattr(crew_result, 'tasks_output') else []
+
+        for i, agent_id in enumerate(active_ids):
+            if agent_id not in AGENTS:
+                continue
+
+            if i < len(task_outputs):
+                raw_output = str(task_outputs[i])
+            else:
+                raw_output = str(crew_result) if i == 0 else ""
+
+            if not raw_output.strip():
+                continue
+
+            if agent_id == "cad":
+                # Extract code from the output
+                code = self._extract_code(raw_output)
+                responses.append(_format_response(agent_id, "Model generated.", code=code))
+
+                if code:
+                    backend = self._build_backend()
+                    preview = _execute_cad_code(
+                        code, message, self.output_dir, backend=backend,
+                    )
+            else:
+                responses.append(_format_response(agent_id, raw_output.strip()))
+
+        # Update design state
+        agent_msgs = [{"message": r.get("message", "")} for r in responses]
+        updated_state = extract_decisions(agent_msgs, state, message)
+
+        return {
+            "responses": responses,
+            "preview": preview,
+            "design_state": updated_state.model_dump(),
+        }
+
+    def _extract_code(self, text: str) -> str | None:
+        """Extract Python code from LLM output, handling code fences."""
+        # Try to extract from code fences
+        match = re.search(r"```(?:python)?\s*\n(.*?)```", text, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+
+        # If the whole output looks like code (has 'import' or 'cq.' or 'result =')
+        if any(marker in text for marker in ["import cadquery", "cq.", "result ="]):
+            return text.strip()
+
+        return None
+
+    def _build_llm(self):
+        """Build the CrewAI-compatible LLM from our backend."""
+        from agents.llm_adapter import NeuralCADLLMAdapter
+
+        backend = self._build_backend()
+        model_names = {
+            "anthropic": "claude-sonnet-4-20250514",
+            "openai": "gpt-4o",
+            "gemini": "gemini-2.5-flash",
+        }
+        return NeuralCADLLMAdapter(
+            backend=backend,
+            model=model_names.get(self.backend_name, "custom"),
+        )
+
+    def _build_backend(self):
+        """Build the underlying LLM backend."""
+        from core.backends import AnthropicBackend, OpenAIBackend, GeminiBackend
+
+        backends = {
+            "anthropic": AnthropicBackend,
+            "openai": OpenAIBackend,
+            "gemini": GeminiBackend,
+        }
+        backend_cls = backends.get(self.backend_name, AnthropicBackend)
+        return backend_cls()
+
+    # ── Fallback ───────────────────────────────────────────────────────────
+
+    def _fallback(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None,
+        max_history: int,
+        design_state: dict | None,
+    ) -> dict:
+        """Fall back to SingleCallOrchestrator."""
+        from agents.orchestrator import SingleCallOrchestrator, MockChatBackend
+
+        try:
+            backend = self._build_backend()
+        except Exception:
+            logger.warning("Backend %r unavailable, falling back to mock", self.backend_name)
+            mock = MockChatBackend()
+            return mock.chat_turn(message, history, mentions, design_state=design_state)
+
+        orchestrator = SingleCallOrchestrator(backend=backend, output_dir=self.output_dir)
+        return orchestrator.chat_turn(
+            message, history, mentions, max_history, design_state=design_state,
+        )

agents/definitions.py

@@ -0,0 +1,83 @@
+"""Multi-agent definitions for NeuralCAD collaborative design chat."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentDef:
+    """Definition of a chat agent."""
+    id: str
+    name: str
+    role: str
+    color: str
+    avatar: str
+    goal: str
+    backstory: str
+
+
+AGENTS: dict[str, AgentDef] = {
+    "design": AgentDef(
+        id="design",
+        name="Design Agent",
+        role="Industrial Designer",
+        color="#7c3aed",
+        avatar="DA",
+        goal="Understand the user's intent and propose optimal form factors, shapes, and aesthetic choices for mechanical parts.",
+        backstory=(
+            "You are an experienced industrial designer specializing in mechanical parts. "
+            "You think about form, function, ergonomics, and visual appeal. You ask clarifying "
+            "questions about the part's purpose, environment, and constraints before proposing "
+            "designs. You suggest shapes, proportions, and features that balance aesthetics with "
+            "manufacturability."
+        ),
+    ),
+    "engineering": AgentDef(
+        id="engineering",
+        name="Engineering Agent",
+        role="Mechanical Engineer",
+        color="#00b4d8",
+        avatar="EA",
+        goal="Ensure parts are structurally sound with correct dimensions, tolerances, materials, and fastener specifications.",
+        backstory=(
+            "You are a senior mechanical engineer with deep knowledge of materials science, "
+            "stress analysis, and fastener standards. You specify wall thicknesses, fillet radii, "
+            "clearance holes (M3=3.4mm, M4=4.5mm, M5=5.5mm, M6=6.6mm, M8=9.0mm), and material "
+            "recommendations. You flag structural concerns and suggest reinforcements like ribs "
+            "or gussets when loads are significant."
+        ),
+    ),
+    "cnc": AgentDef(
+        id="cnc",
+        name="CNC Agent",
+        role="CNC Manufacturing Advisor",
+        color="#00e676",
+        avatar="CA",
+        goal="Advise on manufacturability: tool access, wall thickness limits, pocket ratios, axis requirements, and cost implications.",
+        backstory=(
+            "You are a CNC machinist with 20 years of shop floor experience. You know what "
+            "tool geometries can reach, what aspect ratios cause chatter, and when to recommend "
+            "3-axis vs 3+2 vs 5-axis. You flag undercuts, thin walls (<1.5mm), deep pockets "
+            "(>4:1 ratio), and features that need special fixturing. You think about setup count "
+            "and machining time."
+        ),
+    ),
+    "cad": AgentDef(
+        id="cad",
+        name="CAD Coder",
+        role="CadQuery Code Generator",
+        color="#ffab40",
+        avatar="CC",
+        goal="Generate valid CadQuery Python code that produces the agreed-upon 3D model.",
+        backstory=(
+            "You are an expert CadQuery programmer. You only speak when asked to generate "
+            "a preview or produce code. You take the design specifications agreed upon by the "
+            "team and translate them into precise CadQuery Python code. Your code always assigns "
+            "the result to a variable called `result` as a cq.Workplane object."
+        ),
+    ),
+}
+
+# Agent metadata for frontend rendering
+AGENT_COLORS = {agent.id: agent.color for agent in AGENTS.values()}
+AGENT_AVATARS = {agent.id: agent.avatar for agent in AGENTS.values()}
+AGENT_NAMES = {agent.id: agent.name for agent in AGENTS.values()}

agents/design_state.py

@@ -0,0 +1,175 @@
+"""Design state accumulator — extracts and persists key decisions from agent messages."""
+
+from __future__ import annotations
+
+import re
+from pydantic import BaseModel, Field
+
+
+class DesignState(BaseModel):
+    """Structured state tracking design decisions across chat turns."""
+    part_name: str = ""
+    description: str = ""
+    material: str = ""
+    dimensions: dict[str, float] = Field(default_factory=dict)
+    features: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+    decisions: list[str] = Field(default_factory=list)
+    axis_recommendation: str = ""
+
+    def render(self) -> str:
+        """Render non-empty fields as a concise spec block for LLM context."""
+        lines = []
+        if self.part_name:
+            lines.append(f"Part: {self.part_name}")
+        if self.description:
+            lines.append(f"Description: {self.description}")
+        if self.material:
+            lines.append(f"Material: {self.material}")
+        if self.dimensions:
+            dims = ", ".join(f"{k}={v}mm" for k, v in self.dimensions.items())
+            lines.append(f"Dimensions: {dims}")
+        if self.features:
+            lines.append(f"Features: {'; '.join(self.features)}")
+        if self.constraints:
+            lines.append(f"Constraints: {'; '.join(self.constraints)}")
+        if self.axis_recommendation:
+            lines.append(f"Axis: {self.axis_recommendation}")
+        if self.decisions:
+            lines.append("Decisions:")
+            for d in self.decisions[-5:]:  # Last 5 decisions to keep it concise
+                lines.append(f"  - {d}")
+        return "\n".join(lines) if lines else ""
+
+
+# ── Material patterns ──────────────────────────────────────────────────────
+
+_MATERIALS = [
+    "aluminum", "aluminium", "steel", "stainless steel", "brass", "copper",
+    "titanium", "nylon", "delrin", "acetal", "abs", "polycarbonate", "peek",
+]
+_MATERIAL_GRADES = {
+    "6061": "aluminum 6061", "7075": "aluminum 7075",
+    "304": "stainless steel 304", "316": "stainless steel 316",
+    "t6": "aluminum 6061-T6",
+}
+
+# ── Dimension context words ────────────────────────────────────────────────
+
+_DIM_CONTEXTS = {
+    "wide": "width", "width": "width",
+    "tall": "height", "height": "height", "high": "height",
+    "thick": "thickness", "thickness": "thickness",
+    "deep": "depth", "depth": "depth",
+    "long": "length", "length": "length",
+    "diameter": "diameter", "dia": "diameter",
+    "radius": "radius",
+    "arm": "arm_length",
+}
+
+
+def extract_decisions(
+    agent_responses: list[dict],
+    current_state: DesignState,
+    user_message: str = "",
+) -> DesignState:
+    """Extract design decisions from agent responses and update state.
+
+    Uses regex/keyword matching — no extra LLM call.
+    """
+    state = current_state.model_copy(deep=True)
+
+    # Combine all text for scanning
+    all_text = user_message + " " + " ".join(r.get("message", "") for r in agent_responses)
+    lower = all_text.lower()
+
+    # Extract material
+    for grade, full_name in _MATERIAL_GRADES.items():
+        if grade in lower:
+            state.material = full_name
+            break
+    else:
+        for mat in _MATERIALS:
+            if mat in lower:
+                state.material = mat
+                break
+
+    # Extract dimensions: "60mm wide", "width of 60mm", "60 mm thick"
+    dim_pattern = re.compile(
+        r'(\d+\.?\d*)\s*mm\s+(' + '|'.join(_DIM_CONTEXTS.keys()) + r')',
+        re.IGNORECASE,
+    )
+    for match in dim_pattern.finditer(all_text):
+        value = float(match.group(1))
+        word = match.group(2).lower()
+        dim_name = _DIM_CONTEXTS.get(word, word)
+        state.dimensions[dim_name] = value
+
+    # Also match "width: 60mm" or "width of 60mm" patterns
+    dim_pattern2 = re.compile(
+        r'(' + '|'.join(_DIM_CONTEXTS.keys()) + r')\s*(?:of|:|\s)\s*(\d+\.?\d*)\s*mm',
+        re.IGNORECASE,
+    )
+    for match in dim_pattern2.finditer(all_text):
+        word = match.group(1).lower()
+        value = float(match.group(2))
+        dim_name = _DIM_CONTEXTS.get(word, word)
+        state.dimensions[dim_name] = value
+
+    # Extract fastener features: "4x M6 holes", "M4 clearance holes"
+    fastener_pattern = re.compile(r'(\d+)\s*[x\u00d7]\s*(M\d+)\s+\w*\s*hole', re.IGNORECASE)
+    for match in fastener_pattern.finditer(all_text):
+        feature = f"{match.group(1)}x {match.group(2).upper()} holes"
+        if feature not in state.features:
+            state.features.append(feature)
+
+    # Single fastener mention: "M6 holes", "M3 clearance holes"
+    single_fastener = re.compile(r'(M\d+)\s+(?:clearance\s+)?(?:hole|bolt|screw)', re.IGNORECASE)
+    for match in single_fastener.finditer(all_text):
+        feature = f"{match.group(1).upper()} holes"
+        if feature not in state.features and not any(feature.split()[0] in f for f in state.features):
+            state.features.append(feature)
+
+    # Extract axis recommendation
+    axis_pattern = re.compile(r'(3-axis|3\+2[\s-]*axis|5-axis)', re.IGNORECASE)
+    axis_match = axis_pattern.search(all_text)
+    if axis_match:
+        state.axis_recommendation = axis_match.group(1).lower()
+
+    # Extract constraint keywords
+    constraint_patterns = [
+        (r'min(?:imum)?\s+wall\s+(?:thickness\s+)?(\d+\.?\d*)\s*mm', "min wall {}mm"),
+        (r'max(?:imum)?\s+(?:part\s+)?size\s+(\d+\.?\d*)\s*mm', "max size {}mm"),
+    ]
+    for pattern, template in constraint_patterns:
+        match = re.search(pattern, all_text, re.IGNORECASE)
+        if match:
+            constraint = template.format(match.group(1))
+            if constraint not in state.constraints:
+                state.constraints.append(constraint)
+
+    # Extract decisions: sentences with agreement language from agent messages only
+    for resp in agent_responses:
+        msg = resp.get("message", "")
+        sentences = re.split(r'[.!?]+', msg)
+        for sentence in sentences:
+            s = sentence.strip()
+            if len(s) > 15 and any(kw in s.lower() for kw in [
+                "recommend", "suggest", "should use", "let's go with",
+                "i'd use", "best to", "we'll need", "i'll specify",
+            ]):
+                if s not in state.decisions and len(state.decisions) < 20:
+                    state.decisions.append(s)
+
+    # Extract part name from user message if not set
+    if not state.part_name and user_message:
+        name_patterns = [
+            r'(?:need|want|design|make|create)\s+(?:a|an)\s+(.{5,40}?)\s*(?:with|for|that|,|$)',
+        ]
+        for pattern in name_patterns:
+            match = re.search(pattern, user_message, re.IGNORECASE)
+            if match:
+                state.part_name = match.group(1).strip()
+                break
+
+    return state

agents/llm_adapter.py

@@ -0,0 +1,48 @@
+"""CrewAI BaseLLM adapter for NeuralCAD's LLMBackend interface."""
+
+from __future__ import annotations
+from typing import Any
+
+try:
+    from crewai import LLM as BaseLLM
+except ImportError:
+    # Fallback if crewai not installed — allows import without dependency
+    class BaseLLM:
+        def __init__(self, model: str, **kwargs):
+            self.model = model
+        def call(self, messages, **kwargs) -> str:
+            raise NotImplementedError
+
+
+class NeuralCADLLMAdapter(BaseLLM):
+    """Adapter that wraps NeuralCAD's LLMBackend for CrewAI compatibility.
+
+    Usage:
+        from core.backends import GeminiBackend
+        backend = GeminiBackend()
+        adapter = NeuralCADLLMAdapter(backend, model="gemini-2.5-flash")
+        # Now usable as CrewAI agent's llm parameter
+    """
+
+    def __init__(self, backend, model: str = "custom", **kwargs):
+        super().__init__(model=model, **kwargs)
+        self.backend = backend
+
+    def call(
+        self,
+        messages: str | list[dict],
+        tools: Any = None,
+        callbacks: Any = None,
+        available_functions: Any = None,
+        **kwargs,
+    ) -> str:
+        # If messages is a string, wrap it in standard format
+        if isinstance(messages, str):
+            messages = [{"role": "user", "content": messages}]
+        return self.backend.generate(messages)
+
+    def supports_function_calling(self) -> bool:
+        return False
+
+    def supports_stop_words(self) -> bool:
+        return False

agents/orchestrator.py

@@ -0,0 +1,410 @@
+"""Single-call orchestrator for multi-agent chat (Gemini/Mock mode).
+
+One LLM call per user turn. The orchestrator builds a system prompt containing
+all agent personas, sends a single request, and parses the JSON response into
+individual agent messages.  For mock mode no LLM call is made at all — canned
+responses are returned based on keyword matching.
+
+Both ``MockChatBackend`` and ``SingleCallOrchestrator`` return the same shape::
+
+    {
+        "responses": [{"agent_id", "agent_name", "message", "color", "avatar", "code"}, ...],
+        "preview": None | { ... execution + validation data ... }
+    }
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agents.definitions import AGENTS, AGENT_COLORS, AGENT_NAMES, AGENT_AVATARS
+from agents.prompts import (
+    build_orchestrator_system_prompt,
+    build_chat_messages,
+    route_by_keywords,
+    parse_orchestrator_response,
+    CAD_TRIGGER_KEYWORDS,
+)
+from agents.design_state import DesignState, extract_decisions
+from core.backends import LLMBackend, MockBackend
+from core.executor import execute_cadquery, export_all
+from core.validator import validate_for_cnc
+
+
+DEFAULT_OUTPUT_DIR = Path(__file__).parent.parent / "output"
+
+# Role-appropriate fallback messages when the LLM call fails.
+_FALLBACK_MESSAGES: dict[str, str] = {
+    "design": "I'd love to help shape this design. Could you describe the part's purpose and any size constraints?",
+    "engineering": "I can help with the structural details. What material and load conditions are we working with?",
+    "cnc": "I'll check manufacturability once we have more design details. Any machining preferences (3-axis, 5-axis)?",
+    "cad": "I'm ready to generate the model once the design is agreed upon. Say 'preview' when you're ready.",
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _format_response(agent_id: str, message: str, code: str | None = None) -> dict:
+    """Wrap a raw agent reply into the standard response envelope."""
+    return {
+        "agent_id": agent_id,
+        "agent_name": AGENT_NAMES[agent_id],
+        "message": message,
+        "color": AGENT_COLORS[agent_id],
+        "avatar": AGENT_AVATARS[agent_id],
+        "code": code,
+    }
+
+
+def _execute_cad_code(
+    code: str,
+    prompt: str,
+    output_dir: Path,
+    backend: LLMBackend | None = None,
+    max_retries: int = 2,
+) -> dict | None:
+    """Execute CadQuery *code* and return preview data (or error dict).
+
+    If execution fails and a *backend* is provided, feed the error back to
+    the LLM for self-correction (up to *max_retries* attempts).
+    """
+    exec_result = execute_cadquery(code)
+    retries = 0
+
+    while not exec_result.success and backend is not None and retries < max_retries:
+        retries += 1
+        from core.cadquery_prompts import build_messages
+        error_feedback = (
+            f"The CadQuery code failed with this error:\n"
+            f"```\n{exec_result.error}\n```\n\n"
+            f"Original code:\n```python\n{code}\n```\n\n"
+            f"Fix the code and return ONLY the corrected Python. Original request: {prompt}"
+        )
+        try:
+            code = backend.generate(build_messages(error_feedback))
+            exec_result = execute_cadquery(code)
+        except Exception:
+            break
+
+    if not exec_result.success:
+        return {"success": False, "error": exec_result.error}
+
+    # Derive a filesystem-safe part name from the prompt
+    part_name = prompt[:40].strip().replace(" ", "_").lower()
+    part_name = "".join(c for c in part_name if c.isalnum() or c == "_")
+    if not part_name:
+        part_name = "part"
+
+    # Export STL + STEP
+    base_path = output_dir / part_name
+    try:
+        export_all(exec_result.result, base_path)
+    except Exception as exc:
+        return {"success": False, "error": f"Export failed: {exc}"}
+
+    # CNC validation
+    validation = validate_for_cnc(exec_result.result, part_name=part_name)
+
+    return {
+        "success": True,
+        "part_name": part_name,
+        "stl_url": f"/api/models/{part_name}.stl",
+        "step_url": f"/api/models/{part_name}.step",
+        "execution": {
+            "success": True,
+            "volume_mm3": exec_result.volume,
+            "bounding_box_mm": list(exec_result.bounding_box),
+            "face_count": exec_result.face_count,
+            "edge_count": exec_result.edge_count,
+        },
+        "validation": {
+            "machinable": validation.machinable,
+            "axis_recommendation": validation.axis_recommendation,
+            "error_count": validation.error_count,
+            "warning_count": validation.warning_count,
+            "issues": [
+                {"severity": i.severity, "category": i.category, "message": i.message}
+                for i in validation.issues
+            ],
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# MockChatBackend — template-based, no LLM call
+# ---------------------------------------------------------------------------
+
+class MockChatBackend:
+    """Template-based chat responses for mock mode (no LLM call).
+
+    Generates canned agent responses based on keyword matching.
+    For the CAD Coder agent, delegates to ``MockBackend`` for code generation.
+    """
+
+    def __init__(self, output_dir: Path | str = DEFAULT_OUTPUT_DIR):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    # -- public interface ----------------------------------------------------
+
+    def chat_turn(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None = None,
+        max_history: int = 30,
+        design_state: dict | None = None,
+    ) -> dict:
+        """Return ``{"responses": [...], "preview": ..., "design_state": ...}``."""
+        state = DesignState(**(design_state or {}))
+        lower = message.lower()
+
+        # Determine which agents respond
+        if mentions:
+            active = mentions
+        else:
+            active = route_by_keywords(message)
+
+        responses: list[dict] = []
+        preview = None
+
+        if "design" in active:
+            responses.append(
+                _format_response("design", self._design_response(lower))
+            )
+
+        if "engineering" in active:
+            responses.append(
+                _format_response("engineering", self._engineering_response(lower))
+            )
+
+        if "cnc" in active:
+            responses.append(
+                _format_response("cnc", self._cnc_response(lower))
+            )
+
+        if "cad" in active:
+            # Use MockBackend for actual code generation
+            from core.cadquery_prompts import build_messages
+
+            mock = MockBackend()
+            code = mock.generate(build_messages(message))
+            responses.append(
+                _format_response(
+                    "cad",
+                    "Model generated. Click the 3D viewer to inspect it.",
+                    code=code,
+                )
+            )
+            preview = _execute_cad_code(code, message, self.output_dir)
+
+        # Update design state from responses
+        updated_state = extract_decisions(responses, state, message)
+
+        return {"responses": responses, "preview": preview, "design_state": updated_state.model_dump()}
+
+    # -- canned response templates -------------------------------------------
+
+    @staticmethod
+    def _design_response(lower: str) -> str:
+        if any(w in lower for w in ("bracket", "mount")):
+            return (
+                "For a mounting bracket, I'd suggest an L-shaped profile with "
+                "filleted corners for rigidity. What's the intended load direction?"
+            )
+        if any(w in lower for w in ("gear", "spur")):
+            return (
+                "For a spur gear, we'll need to define the module, tooth count, "
+                "and bore diameter. What's the mating gear specification?"
+            )
+        if any(w in lower for w in ("enclosure", "box", "housing")):
+            return (
+                "For an enclosure, I'd recommend rounded external corners for "
+                "aesthetics and a pocket on the top face for the lid. What "
+                "components go inside?"
+            )
+        return (
+            "I can help design that. Could you tell me more about the part's "
+            "purpose and any dimensional constraints?"
+        )
+
+    @staticmethod
+    def _engineering_response(lower: str) -> str:
+        if any(w in lower for w in ("m3", "m4", "m5", "m6", "m8")):
+            return (
+                "Good fastener choice. I'll specify the clearance holes per ISO "
+                "standards. Shall I add counterbores or keep them as through-holes?"
+            )
+        if any(w in lower for w in ("load", "stress", "strength")):
+            return (
+                "For the expected loads, I'd recommend 3mm minimum wall thickness "
+                "in aluminum 6061-T6. Adding reinforcement ribs would increase "
+                "stiffness significantly."
+            )
+        return (
+            "I'll specify the critical dimensions and tolerances. What material "
+            "are you planning to machine this from?"
+        )
+
+    @staticmethod
+    def _cnc_response(lower: str) -> str:
+        if any(w in lower for w in ("pocket", "deep", "slot")):
+            return (
+                "Keep pocket depth-to-width ratio under 4:1 for clean machining. "
+                "I'd recommend a 6mm endmill for this geometry."
+            )
+        if any(w in lower for w in ("5-axis", "undercut")):
+            return (
+                "That feature would require 5-axis machining. Consider redesigning "
+                "to avoid undercuts for 3-axis compatibility."
+            )
+        return (
+            "This looks achievable with standard 3-axis milling. No undercuts or "
+            "access issues detected so far."
+        )
+
+
+# ---------------------------------------------------------------------------
+# SingleCallOrchestrator — one LLM call per turn
+# ---------------------------------------------------------------------------
+
+class SingleCallOrchestrator:
+    """Orchestrator that uses a single LLM call per chat turn.
+
+    Builds a system prompt containing all agent personas, sends one LLM call,
+    and parses the JSON response into individual agent messages.
+    Used for Gemini free tier and other rate-limited backends.
+    """
+
+    def __init__(self, backend: LLMBackend, output_dir: Path | str = DEFAULT_OUTPUT_DIR):
+        self.backend = backend
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def chat_turn(
+        self,
+        message: str,
+        history: list[dict],
+        mentions: list[str] | None = None,
+        max_history: int = 30,
+        design_state: dict | None = None,
+    ) -> dict:
+        """Run one chat turn: user message -> agent responses.
+
+        Args:
+            message: The user's message text (with @mentions already stripped).
+            history: Previous messages [{role, agent_id, content}, ...].
+            mentions: Agent IDs explicitly mentioned by user. ``None`` = auto-route.
+            max_history: Max history messages to include in context.
+            design_state: Persisted design state dict from previous turns.
+
+        Returns:
+            ``{"responses": [...], "preview": None | {...}, "design_state": {...}}``
+        """
+        state = DesignState(**(design_state or {}))
+
+        # Determine which agents are active
+        active_agents = mentions if mentions else None  # None lets orchestrator decide
+
+        # Check if CAD context is needed
+        include_cad = mentions is not None and "cad" in mentions
+        if not include_cad:
+            include_cad = any(kw in message.lower() for kw in CAD_TRIGGER_KEYWORDS)
+
+        # Build orchestrator prompt
+        system_prompt = build_orchestrator_system_prompt(
+            active_agents=active_agents,
+            include_cad_context=include_cad,
+        )
+
+        # Build message list
+        messages = build_chat_messages(
+            user_message=message,
+            history=history,
+            system_prompt=system_prompt,
+            max_history=max_history,
+            design_state_text=state.render(),
+        )
+
+        # Single LLM call
+        try:
+            raw_response = self.backend.generate(messages)
+            agent_responses = parse_orchestrator_response(raw_response)
+        except Exception as exc:
+            import logging
+            logging.warning("Orchestrator LLM call failed: %s", exc)
+            # Fallback: keyword routing with role-appropriate replies
+            fallback_agents = route_by_keywords(message)
+            agent_responses = [
+                {"id": aid, "message": _FALLBACK_MESSAGES.get(aid, "Let me look into that."), "code": None}
+                for aid in fallback_agents
+            ]
+
+        # Format responses with metadata
+        formatted: list[dict] = []
+        preview = None
+
+        for resp in agent_responses:
+            agent_id = resp["id"]
+            if agent_id not in AGENTS:
+                continue
+
+            formatted.append(
+                _format_response(agent_id, resp["message"], code=resp.get("code"))
+            )
+
+            # If CAD Coder responded with code, execute it (with retry)
+            if agent_id == "cad" and resp.get("code"):
+                preview = _execute_cad_code(
+                    resp["code"], message, self.output_dir, backend=self.backend,
+                )
+
+        # Update design state from responses
+        updated_state = extract_decisions(formatted, state, message)
+
+        return {"responses": formatted, "preview": preview, "design_state": updated_state.model_dump()}
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def get_orchestrator(
+    backend_name: str = "mock",
+    output_dir: str | Path = DEFAULT_OUTPUT_DIR,
+) -> MockChatBackend | SingleCallOrchestrator:
+    """Create the appropriate orchestrator for the given backend.
+
+    Args:
+        backend_name: ``"mock"``, ``"gemini"``, ``"anthropic"``, or ``"openai"``.
+        output_dir: Directory for exported model files.
+    """
+    if backend_name == "mock":
+        return MockChatBackend(output_dir=output_dir)
+
+    # For all LLM backends, use SingleCallOrchestrator.
+    # (CrewAI multi-call variant can be added later for anthropic/openai.)
+    from core.backends import AnthropicBackend, OpenAIBackend, GeminiBackend
+
+    backends = {
+        "gemini": GeminiBackend,
+        "anthropic": AnthropicBackend,
+        "openai": OpenAIBackend,
+    }
+
+    backend_cls = backends.get(backend_name)
+    if backend_cls is None:
+        return MockChatBackend(output_dir=output_dir)
+
+    try:
+        backend = backend_cls()
+    except Exception as exc:
+        import logging
+        logging.warning(
+            "Backend %r unavailable (%s), falling back to mock", backend_name, exc
+        )
+        return MockChatBackend(output_dir=output_dir)
+
+    return SingleCallOrchestrator(backend=backend, output_dir=output_dir)

agents/prompts.py

@@ -0,0 +1,245 @@
+"""Orchestrator prompts and routing logic for multi-agent chat."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+from agents.definitions import AGENTS, AgentDef
+
+
+# Single source of truth for CAD Coder activation keywords.
+# Used by: system prompt, keyword routing, and orchestrator CAD-context check.
+CAD_TRIGGER_KEYWORDS: list[str] = [
+    "generate", "build", "build it", "preview", "show me", "create",
+    "create the model", "model it", "render", "code", "make it", "produce",
+]
+
+
+def build_orchestrator_system_prompt(
+    active_agents: list[str] | None = None,
+    include_cad_context: bool = False,
+) -> str:
+    """Build the orchestrator system prompt for single-call mode.
+
+    Args:
+        active_agents: List of agent IDs to include. None = all except 'cad'.
+        include_cad_context: Whether to include CadQuery reference for the CAD agent.
+    """
+    if active_agents is None:
+        active_agents = ["design", "engineering", "cnc"]
+
+    prompt_parts = [
+        "You are the orchestrator for a multi-agent CAD design team. "
+        "You control multiple specialist agents who collaborate with a user "
+        "to design mechanical parts for CNC machining.\n",
+        "## Your Agents\n",
+    ]
+
+    for agent_id in active_agents:
+        agent = AGENTS[agent_id]
+        prompt_parts.append(
+            f"### {agent.name} (id: \"{agent.id}\")\n"
+            f"Role: {agent.role}\n"
+            f"Goal: {agent.goal}\n"
+            f"Personality: {agent.backstory}\n"
+        )
+
+    prompt_parts.append(
+        "## Instructions\n"
+        "Given the conversation history and the user's latest message, "
+        "decide which agents should respond and generate their messages.\n\n"
+        "Rules:\n"
+        "- Select 1-3 agents that are most relevant to the user's LATEST message.\n"
+        "- Each agent should respond in character with their expertise.\n"
+        "- Keep responses concise and actionable (2-4 sentences each).\n"
+        "- Use the conversation history for context (know what was decided), "
+        "but ONLY respond to the user's latest message. Do NOT repeat or "
+        "paraphrase anything already said — always advance the discussion.\n"
+        "- Each agent should add DIFFERENT information. If one agent covers "
+        "dimensions, another should cover materials or tooling, not restate dimensions.\n"
+        f"- Do NOT include the CAD Coder agent unless the user explicitly uses one of "
+        f"these trigger words: {', '.join(repr(k) for k in CAD_TRIGGER_KEYWORDS)}.\n"
+        "- When the CAD Coder responds, include a 'code' field with valid CadQuery Python "
+        "that assigns the result to a variable called `result` as a cq.Workplane.\n"
+    )
+
+    if include_cad_context and "cad" in active_agents:
+        from core.cadquery_prompts import CADQUERY_SYSTEM_PROMPT
+        prompt_parts.append(
+            "\n## CadQuery Reference (for CAD Coder agent)\n"
+            f"{CADQUERY_SYSTEM_PROMPT}\n"
+        )
+
+    prompt_parts.append(
+        "\n## Response Format\n"
+        "Respond with ONLY valid JSON in this exact format:\n"
+        "```json\n"
+        '{"agents": [\n'
+        '  {"id": "design", "message": "Your design suggestion here..."},\n'
+        '  {"id": "engineering", "message": "Your engineering input here..."}\n'
+        "]}\n"
+        "```\n\n"
+        "When the CAD Coder agent responds, add a 'code' field:\n"
+        "```json\n"
+        '{"agents": [\n'
+        '  {"id": "cad", "message": "Model generated.", '
+        '"code": "import cadquery as cq\\nresult = cq.Workplane(\'XY\').box(10,10,10)"}\n'
+        "]}\n"
+        "```\n\n"
+        "Output ONLY the JSON. No other text."
+    )
+
+    return "\n".join(prompt_parts)
+
+
+def build_chat_messages(
+    user_message: str,
+    history: list[dict],
+    system_prompt: str,
+    max_history: int = 30,
+    design_state_text: str = "",
+) -> list[dict]:
+    """Build the message list for the orchestrator LLM call.
+
+    Args:
+        user_message: The user's current message.
+        history: Previous messages [{role, agent_id, content}, ...].
+        system_prompt: The orchestrator system prompt.
+        max_history: Maximum number of history messages to include.
+        design_state_text: Rendered design state spec to inject as context.
+    """
+    messages = [{"role": "system", "content": system_prompt}]
+
+    # Truncate history to last N messages
+    recent = history[-max_history:] if len(history) > max_history else history
+
+    # Bundle history into a single context block to avoid Gemini
+    # treating prior agent messages as its own output and repeating them.
+    content_parts = []
+    if design_state_text:
+        content_parts.append(f"## Current Design Spec (agreed so far)\n{design_state_text}\n")
+    if recent:
+        history_lines = []
+        for msg in recent:
+            if msg.get("role") == "user":
+                history_lines.append(f"USER: {msg['content']}")
+            else:
+                agent_id = msg.get("agent_id", "unknown")
+                agent_name = AGENTS.get(agent_id, AGENTS["design"]).name
+                history_lines.append(f"{agent_name.upper()}: {msg['content']}")
+
+        history_block = "\n".join(history_lines)
+        content_parts.append(f"## Conversation so far:\n{history_block}\n")
+    content_parts.append(f"## User's new message:\n{user_message}\n\nRespond to the user's NEW message above. Do NOT repeat prior responses.")
+
+    messages.append({"role": "user", "content": "\n".join(content_parts)})
+
+    return messages
+
+
+def parse_mentions(message: str) -> tuple[str, list[str]]:
+    """Extract @mentions from a message and return cleaned message + mention list.
+
+    Returns:
+        (cleaned_message, mentions) where mentions is list of agent IDs.
+    """
+    mentions = []
+    cleaned = message
+
+    for agent_id in AGENTS:
+        pattern = rf"@{agent_id}\b"
+        if re.search(pattern, message, re.IGNORECASE):
+            mentions.append(agent_id)
+            cleaned = re.sub(pattern, "", cleaned, flags=re.IGNORECASE).strip()
+
+    return cleaned, mentions
+
+
+# ── Keyword-based fallback routing ────────────────────────────────────────
+
+_ROUTING_KEYWORDS: dict[str, list[str]] = {
+    "design": [
+        "design", "look", "shape", "style", "form", "aesthetic", "appearance",
+        "layout", "concept", "idea", "propose", "suggest", "bracket", "mount",
+        "enclosure", "housing", "ergonomic", "profile", "contour",
+    ],
+    "engineering": [
+        "dimension", "tolerance", "material", "strength", "load", "stress",
+        "thickness", "wall", "fillet", "radius", "clearance",
+        "m2", "m3", "m4", "m5", "m6", "m8", "m10", "m12",
+        "aluminum", "steel", "brass", "titanium", "nylon",
+        "gear", "bearing", "flange", "heatsink", "fin", "rib",
+        "bolt", "screw", "thread", "torque", "deflection",
+        "hole", "bore", "shaft", "keyway", "spline",
+    ],
+    "cnc": [
+        "machine", "mill", "cnc", "manufacture", "machinable", "axis",
+        "tool", "fixture", "setup", "pocket", "undercut", "access",
+        "3-axis", "5-axis", "cost", "surface finish", "roughness",
+        "endmill", "drill", "tap", "chamfer tool", "deburr",
+        "setup count", "cycle time", "tolerance class",
+    ],
+    "cad": CAD_TRIGGER_KEYWORDS,
+}
+
+
+def route_by_keywords(message: str) -> list[str]:
+    """Fallback agent routing based on keyword matching.
+
+    Returns list of agent IDs that should respond.
+    """
+    lower = message.lower()
+    scores: dict[str, int] = {agent_id: 0 for agent_id in AGENTS}
+
+    for agent_id, keywords in _ROUTING_KEYWORDS.items():
+        for kw in keywords:
+            if kw in lower:
+                scores[agent_id] += 1
+
+    # Select agents with score > 0, sorted by score descending
+    active = [aid for aid, score in sorted(scores.items(), key=lambda x: -x[1]) if score > 0]
+
+    # Default: design + engineering for general discussion
+    if not active:
+        active = ["design", "engineering"]
+
+    # Cap at 3 agents
+    return active[:3]
+
+
+def parse_orchestrator_response(response_text: str) -> list[dict]:
+    """Parse the orchestrator's JSON response into agent messages.
+
+    Returns list of dicts: [{"id": str, "message": str, "code": str|None}, ...]
+    Falls back to treating entire response as design agent message if JSON fails.
+    """
+    text = response_text.strip()
+
+    # Try to extract JSON from markdown code fences
+    json_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if json_match:
+        text = json_match.group(1)
+
+    try:
+        data = json.loads(text)
+        agents = data.get("agents", [])
+
+        # Validate structure
+        result = []
+        for agent in agents:
+            if isinstance(agent, dict) and "id" in agent and "message" in agent:
+                result.append({
+                    "id": agent["id"],
+                    "message": agent["message"],
+                    "code": agent.get("code"),
+                })
+
+        if result:
+            return result
+    except (json.JSONDecodeError, KeyError, TypeError):
+        pass
+
+    # Fallback: treat entire response as design agent message
+    return [{"id": "design", "message": response_text, "code": None}]

core/backends.py

@@ -0,0 +1,740 @@
+"""
+LLM backend implementations for CadQuery code generation.
+
+Supports multiple backends:
+  - Anthropic Claude
+  - OpenAI GPT-4o
+  - Google Gemini (free tier available)
+  - Mock (dynamic generation, no API key required)
+  - NeuralCAD (local neural pipeline, not yet implemented)
+"""
+
+import base64
+import mimetypes
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+
+# ── LLM Backends ──────────────────────────────────────────────────────────
+
+
+class LLMBackend:
+    """Base class for LLM code generation backends."""
+
+    def generate(self, messages: list[dict]) -> str:
+        raise NotImplementedError
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        """Generate code from messages that include an image.
+        Override in backends that support vision."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support image input"
+        )
+
+
+class AnthropicBackend(LLMBackend):
+    """Generate CadQuery code using Anthropic Claude."""
+
+    def __init__(
+        self, model: str = "claude-sonnet-4-20250514", api_key: Optional[str] = None
+    ):
+        import anthropic
+
+        self.client = anthropic.Anthropic(
+            api_key=api_key or os.environ.get("ANTHROPIC_API_KEY")
+        )
+        self.model = model
+
+    def generate(self, messages: list[dict]) -> str:
+        # Anthropic uses system param separately
+        system_msg = ""
+        user_messages = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            else:
+                user_messages.append(m)
+
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=4096,
+            system=system_msg,
+            messages=user_messages,
+        )
+        return response.content[0].text
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        image_path = Path(image_path)
+        media_type = mimetypes.guess_type(str(image_path))[0] or "image/png"
+        image_data = base64.b64encode(image_path.read_bytes()).decode("utf-8")
+
+        system_msg = ""
+        user_messages = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            else:
+                msg = dict(m)
+                # Inject image into the last user message
+                if msg["role"] == "user" and msg is not m:
+                    user_messages.append(msg)
+                else:
+                    user_messages.append(msg)
+
+        # Replace last user message content with multimodal blocks
+        last_user = user_messages[-1]
+        last_user["content"] = [
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": media_type,
+                    "data": image_data,
+                },
+            },
+            {"type": "text", "text": last_user["content"]},
+        ]
+
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=4096,
+            system=system_msg,
+            messages=user_messages,
+        )
+        return response.content[0].text
+
+
+class OpenAIBackend(LLMBackend):
+    """Generate CadQuery code using OpenAI GPT-4o."""
+
+    def __init__(self, model: str = "gpt-4o", api_key: Optional[str] = None):
+        import openai
+
+        self.client = openai.OpenAI(api_key=api_key or os.environ.get("OPENAI_API_KEY"))
+        self.model = model
+
+    def generate(self, messages: list[dict]) -> str:
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            max_tokens=4096,
+            temperature=0.2,
+        )
+        return response.choices[0].message.content
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        image_path = Path(image_path)
+        media_type = mimetypes.guess_type(str(image_path))[0] or "image/png"
+        image_data = base64.b64encode(image_path.read_bytes()).decode("utf-8")
+        data_url = f"data:{media_type};base64,{image_data}"
+
+        # Copy messages, replace last user message with multimodal content
+        patched = [dict(m) for m in messages]
+        last_user = patched[-1]
+        last_user["content"] = [
+            {"type": "image_url", "image_url": {"url": data_url}},
+            {"type": "text", "text": last_user["content"]},
+        ]
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=patched,
+            max_tokens=4096,
+            temperature=0.2,
+        )
+        return response.choices[0].message.content
+
+
+class GeminiBackend(LLMBackend):
+    """Generate CadQuery code using Google Gemini (free tier available)."""
+
+    def __init__(self, model: str = "gemini-2.5-flash", api_key: Optional[str] = None):
+        from google import genai
+
+        self.client = genai.Client(api_key=api_key or os.environ.get("GEMINI_API_KEY"))
+        self.model = model
+
+    def generate(self, messages: list[dict]) -> str:
+        # Convert messages to Gemini format: system instruction + contents
+        system_msg = ""
+        contents = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            elif m["role"] == "user":
+                contents.append({"role": "user", "parts": [{"text": m["content"]}]})
+            elif m["role"] == "assistant":
+                contents.append({"role": "model", "parts": [{"text": m["content"]}]})
+
+        from google.genai import types
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=contents,
+            config=types.GenerateContentConfig(
+                system_instruction=system_msg,
+                max_output_tokens=4096,
+                temperature=0.2,
+            ),
+        )
+        return response.text
+
+    def generate_with_image(self, messages: list[dict], image_path: str | Path) -> str:
+        from google.genai import types
+
+        image_path = Path(image_path)
+        image_data = image_path.read_bytes()
+        media_type = mimetypes.guess_type(str(image_path))[0] or "image/png"
+
+        system_msg = ""
+        contents = []
+        for m in messages:
+            if m["role"] == "system":
+                system_msg = m["content"]
+            elif m["role"] == "user":
+                contents.append({"role": "user", "parts": [{"text": m["content"]}]})
+            elif m["role"] == "assistant":
+                contents.append({"role": "model", "parts": [{"text": m["content"]}]})
+
+        # Add image to the last user message
+        if contents and contents[-1]["role"] == "user":
+            contents[-1]["parts"].insert(0, {
+                "inline_data": {"mime_type": media_type, "data": image_data}
+            })
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=contents,
+            config=types.GenerateContentConfig(
+                system_instruction=system_msg,
+                max_output_tokens=4096,
+                temperature=0.2,
+            ),
+        )
+        return response.text
+
+
+class MockBackend(LLMBackend):
+    """
+    Mock backend that dynamically generates CadQuery code from any prompt.
+    Parses dimensions, shape type, and features from the text, then assembles
+    parametric code. No API key required.
+    """
+
+    # Word-to-number mapping for natural language counts
+    _WORD_NUMS = {
+        "one": 1,
+        "two": 2,
+        "three": 3,
+        "four": 4,
+        "five": 5,
+        "six": 6,
+        "seven": 7,
+        "eight": 8,
+        "nine": 9,
+        "ten": 10,
+        "twelve": 12,
+        "sixteen": 16,
+        "twenty": 20,
+    }
+
+    # Metric thread clearance hole diameters
+    _THREAD_CLEARANCE = {
+        "m2": 2.4,
+        "m3": 3.4,
+        "m4": 4.5,
+        "m5": 5.5,
+        "m6": 6.6,
+        "m8": 9.0,
+        "m10": 11.0,
+        "m12": 13.5,
+    }
+
+    # Shape detection patterns → base shape key
+    _SHAPE_PATTERNS = {
+        "cylinder": [
+            "cylinder",
+            "rod",
+            "shaft",
+            "axle",
+            "spacer",
+            "washer",
+            "bushing",
+            "sleeve",
+            "tube",
+            "pipe",
+            "dowel",
+            "pin",
+        ],
+        "plate": [
+            "plate",
+            "bracket",
+            "mount",
+            "flange",
+            "baseplate",
+            "panel",
+            "shim",
+            "cover",
+            "lid",
+        ],
+        "box": [
+            "box",
+            "block",
+            "enclosure",
+            "housing",
+            "case",
+            "cube",
+            "container",
+            "shell",
+        ],
+        "l_bracket": [
+            "l-bracket",
+            "l bracket",
+            "angle bracket",
+            "corner bracket",
+            "l-shaped",
+        ],
+    }
+
+    # Feature detection keywords
+    _FEATURE_KEYWORDS = {
+        "holes": ["hole", "holes", "bolt", "bolts", "screw", "screws", "bore", "bores"],
+        "pocket": ["pocket", "recess", "cavity", "cutout", "mortise"],
+        "slot": ["slot", "slots", "groove", "channel", "keyway"],
+        "fillet": ["fillet", "fillets", "round", "rounded"],
+        "chamfer": ["chamfer", "chamfers", "bevel", "beveled"],
+        "through_hole": ["through hole", "through-hole", "thru hole", "thru-hole"],
+        "counterbore": ["counterbore", "counterbored", "cbore"],
+        "fins": ["fin", "fins", "cooling", "heatsink", "heat sink", "radiator"],
+        "ribs": ["rib", "ribs", "stiffener", "stiffeners", "web"],
+        "boss": ["boss", "bosses", "standoff", "standoffs", "pillar"],
+    }
+
+    def _parse_prompt(self, text: str) -> dict:
+        """Extract dimensions, shape, and features from natural language."""
+        lower = text.lower()
+
+        # Extract all numbers with optional units
+        raw_nums = re.findall(r"(\d+\.?\d*)\s*(?:mm|cm|m\b)?", lower)
+        dimensions = [float(n) for n in raw_nums if 0.1 < float(n) < 2000]
+
+        # Detect metric thread sizes (M3, M6, etc.)
+        thread_match = re.search(r"\bm(\d+)\b", lower)
+        hole_dia = None
+        if thread_match:
+            key = f"m{thread_match.group(1)}"
+            hole_dia = self._THREAD_CLEARANCE.get(
+                key, float(thread_match.group(1)) * 1.1
+            )
+
+        # Detect hole diameter from "Xmm hole"
+        hole_dim_match = re.search(
+            r"(\d+\.?\d*)\s*mm\s*(?:hole|bore|holes|bores)", lower
+        )
+        if hole_dim_match and not hole_dia:
+            hole_dia = float(hole_dim_match.group(1))
+
+        # Detect count (numeric or word)
+        count = None
+        count_match = re.search(
+            r"(\d+)\s*(?:hole|bolt|screw|bore|fin|rib|slot|boss)", lower
+        )
+        if count_match:
+            count = int(count_match.group(1))
+        else:
+            for word, num in self._WORD_NUMS.items():
+                if re.search(rf"\b{word}\b.*(?:hole|bolt|screw|bore|fin|slot)", lower):
+                    count = num
+                    break
+
+        # Detect base shape
+        shape = "box"
+        for shape_key, keywords in self._SHAPE_PATTERNS.items():
+            if any(kw in lower for kw in keywords):
+                shape = shape_key
+                break
+
+        # Detect features
+        features = set()
+        for feat, keywords in self._FEATURE_KEYWORDS.items():
+            if any(kw in lower for kw in keywords):
+                features.add(feat)
+
+        # If holes mentioned but no specific feature, add generic holes
+        if (
+            any(w in lower for w in ["hole", "holes", "bolt", "screw"])
+            and "holes" not in features
+        ):
+            features.add("holes")
+
+        return {
+            "dimensions": dimensions,
+            "shape": shape,
+            "features": features,
+            "hole_dia": hole_dia or 5.5,
+            "count": count or 4,
+            "prompt": text,
+        }
+
+    def _generate_code(self, p: dict) -> str:
+        """Build CadQuery code from parsed parameters."""
+        dims = p["dimensions"]
+        shape = p["shape"]
+        features = p["features"]
+        prompt = p["prompt"]
+
+        lines = ["import cadquery as cq"]
+        if shape == "cylinder" and "fins" in features:
+            lines.append("import math")
+        lines.append(f"")
+        lines.append(f"# Generated from: {prompt}")
+
+        if shape == "cylinder":
+            radius = dims[0] / 2 if dims else 15.0
+            height = dims[1] if len(dims) > 1 else radius * 2
+            lines.append(f"# Cylinder: radius={radius}mm, height={height}mm")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XY')")
+            lines.append(f"    .cylinder({height}, {radius})")
+
+            if "holes" in features or "through_hole" in features:
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .hole({p['hole_dia']})")
+
+            if "chamfer" in features or "fillet" not in features:
+                lines.append(f"    .edges('>Z or <Z').chamfer(0.5)")
+
+            if "fillet" in features:
+                lines.append(f"    .edges('>Z or <Z').fillet(1.0)")
+
+            lines.append(f")")
+
+            if "fins" in features:
+                n_fins = p["count"] if p["count"] > 4 else 8
+                fin_h = max(height * 0.8, 5)
+                fin_w = 1.5
+                lines.append(f"")
+                lines.append(f"# Add {n_fins} cooling fins")
+                lines.append(f"for i in range({n_fins}):")
+                lines.append(f"    angle = i * 360 / {n_fins}")
+                lines.append(f"    rad = math.radians(angle)")
+                lines.append(f"    fx = {radius + 3} * math.cos(rad)")
+                lines.append(f"    fy = {radius + 3} * math.sin(rad)")
+                lines.append(f"    fin = (")
+                lines.append(f"        cq.Workplane('XY')")
+                lines.append(
+                    f"        .transformed(offset=(fx, fy, 0), rotate=(0, 0, angle))"
+                )
+                lines.append(f"        .rect({fin_w}, {radius * 0.6})")
+                lines.append(f"        .extrude({fin_h})")
+                lines.append(f"    )")
+                lines.append(f"    result = result.union(fin)")
+
+        elif shape == "plate":
+            w = dims[0] if dims else 80.0
+            h = dims[1] if len(dims) > 1 else w * 0.6
+            t = dims[2] if len(dims) > 2 else 5.0
+            lines.append(f"# Plate: {w}x{h}x{t}mm")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XY')")
+            lines.append(f"    .box({w}, {h}, {t})")
+
+            if "holes" in features or "through_hole" in features:
+                n = p["count"]
+                dia = p["hole_dia"]
+                # Distribute holes in a grid or circle
+                if "flange" in p["prompt"].lower() or n >= 6:
+                    # Bolt circle pattern
+                    r = min(w, h) * 0.35
+                    lines.append(f"    .faces('>Z').workplane()")
+                    lines.append(f"    .polarArray({r}, 0, 360, {n})")
+                    lines.append(f"    .hole({dia})")
+                    if "bore" in p["prompt"].lower() or "flange" in p["prompt"].lower():
+                        lines.append(f"    .faces('>Z').workplane()")
+                        lines.append(f"    .hole({dia * 3})  # Center bore")
+                else:
+                    # Rectangular pattern
+                    ox = w * 0.35
+                    oy = h * 0.35
+                    pts = []
+                    if n == 1:
+                        pts = [(0, 0)]
+                    elif n == 2:
+                        pts = [(-ox, 0), (ox, 0)]
+                    elif n == 4:
+                        pts = [(-ox, -oy), (-ox, oy), (ox, -oy), (ox, oy)]
+                    else:
+                        pts = [(-ox, -oy), (-ox, oy), (ox, -oy), (ox, oy)]
+                    lines.append(f"    .faces('>Z').workplane()")
+                    lines.append(f"    .pushPoints({pts})")
+                    lines.append(f"    .hole({dia})")
+
+            if "pocket" in features:
+                pw = w * 0.4
+                ph = h * 0.35
+                pd = t * 0.6
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .rect({pw}, {ph})")
+                lines.append(f"    .cutBlind(-{pd})  # Central pocket")
+
+            if "slot" in features:
+                sl = w * 0.35
+                sw = max(t * 0.8, 4)
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .slot2D({sl}, {sw}).cutBlind(-{t})")
+
+            if "fillet" in features:
+                lines.append(f"    .edges('|Z').fillet({max(t * 0.4, 1.5)})")
+            else:
+                lines.append(f"    .edges('>Z').chamfer(0.5)")
+
+            lines.append(f")")
+
+        elif shape == "l_bracket":
+            arm = dims[0] if dims else 50.0
+            width = dims[1] if len(dims) > 1 else 20.0
+            t = dims[2] if len(dims) > 2 else 4.0
+            lines.append(f"# L-bracket: {arm}mm arms, {width}mm wide, {t}mm thick")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XZ')")
+            lines.append(f"    .moveTo(0, 0)")
+            lines.append(f"    .lineTo({arm}, 0)")
+            lines.append(f"    .lineTo({arm}, {t})")
+            lines.append(f"    .lineTo({t}, {t})")
+            lines.append(f"    .lineTo({t}, {arm})")
+            lines.append(f"    .lineTo(0, {arm})")
+            lines.append(f"    .close()")
+            lines.append(f"    .extrude({width})")
+            lines.append(f"    .edges('|Y').fillet({max(t * 0.5, 1.5)})")
+
+            if "holes" in features:
+                lines.append(
+                    f"    .faces('>Z').workplane(centerOption='CenterOfBoundBox')"
+                )
+                lines.append(f"    .center({arm * 0.5}, 0)")
+                lines.append(f"    .hole({p['hole_dia']})")
+                lines.append(
+                    f"    .faces('>X').workplane(centerOption='CenterOfBoundBox')"
+                )
+                lines.append(f"    .center(0, {arm * 0.5})")
+                lines.append(f"    .hole({p['hole_dia']})")
+
+            lines.append(f"    .edges().chamfer(0.5)")
+            lines.append(f")")
+
+        else:  # box / enclosure / housing
+            w = dims[0] if dims else 60.0
+            h = dims[1] if len(dims) > 1 else w * 0.65
+            d = dims[2] if len(dims) > 2 else 20.0
+            lines.append(f"# Box: {w}x{h}x{d}mm")
+            lines.append(f"result = (")
+            lines.append(f"    cq.Workplane('XY')")
+            lines.append(f"    .box({w}, {h}, {d})")
+
+            if "holes" in features or "through_hole" in features:
+                ox = w * 0.35
+                oy = h * 0.35
+                pts = [(-ox, -oy), (-ox, oy), (ox, -oy), (ox, oy)]
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .pushPoints({pts})")
+                lines.append(f"    .hole({p['hole_dia']})")
+
+            if "pocket" in features:
+                pw = w * 0.5
+                ph = h * 0.4
+                pd = d * 0.4
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .rect({pw}, {ph})")
+                lines.append(f"    .cutBlind(-{pd})")
+
+            if "slot" in features:
+                sl = w * 0.4
+                sw = 6
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .slot2D({sl}, {sw}).cutBlind(-{d})")
+
+            if "boss" in features:
+                n = min(p["count"], 4)
+                bx = w * 0.3
+                by = h * 0.3
+                boss_pts = [(-bx, -by), (-bx, by), (bx, -by), (bx, by)][:n]
+                lines.append(f"    .faces('>Z').workplane()")
+                lines.append(f"    .pushPoints({boss_pts})")
+                lines.append(f"    .circle(4).extrude(6)  # Mounting bosses")
+
+            if "ribs" in features:
+                n_ribs = p["count"] if p["count"] <= 8 else 4
+                spacing = w / (n_ribs + 1)
+                lines.append(f"    .faces('>Z').workplane()")
+                for i in range(n_ribs):
+                    rx = -w / 2 + spacing * (i + 1)
+                    lines.append(f"    .center({rx if i == 0 else spacing}, 0)")
+                    lines.append(f"    .rect(2, {h * 0.8}).extrude({d * 0.3})")
+
+            if "fillet" in features:
+                lines.append(f"    .edges('|Z').fillet({min(d * 0.2, 3)})")
+            elif "chamfer" in features:
+                lines.append(f"    .edges('>Z').chamfer(1.0)")
+            else:
+                lines.append(f"    .edges('>Z').chamfer(0.5)")
+
+            lines.append(f")")
+
+        return "\n".join(lines) + "\n"
+
+    # Curated hero responses for specific prompts
+    _CURATED = {
+        "gear": """\
+import cadquery as cq
+import math
+
+# Simple spur gear approximation: 20 teeth, module 2, 10mm thick
+module = 2
+teeth = 20
+pitch_radius = module * teeth / 2
+outer_radius = pitch_radius + module
+tooth_angle = 360 / teeth
+
+result = (
+    cq.Workplane("XY")
+    .cylinder(10, outer_radius)
+    .faces(">Z").workplane()
+    .hole(12)
+)
+
+for i in range(teeth):
+    angle = i * tooth_angle
+    rad = math.radians(angle)
+    gap_x = pitch_radius * math.cos(rad)
+    gap_y = pitch_radius * math.sin(rad)
+    cutter = (
+        cq.Workplane("XY")
+        .transformed(offset=(gap_x, gap_y, 0), rotate=(0, 0, angle))
+        .rect(module * 0.8, module * 2.5)
+        .extrude(12)
+    )
+    result = result.cut(cutter)
+
+result = result.edges(">Z or <Z").chamfer(0.3)
+""",
+    }
+
+    def generate(self, messages: list[dict]) -> str:
+        user_msg = messages[-1]["content"]
+        lower = user_msg.lower()
+
+        # Check curated responses first
+        for key, code in self._CURATED.items():
+            if key in lower:
+                return code
+
+        # Dynamic generation for everything else
+        params = self._parse_prompt(user_msg)
+        return self._generate_code(params)
+
+
+class NeuralCADBackend(LLMBackend):
+    """
+    Neural CAD pipeline backend.
+
+    Runs trained models locally:
+      Text/Image → CLIP encoder → contrastive latent
+        → Diffusion prior → latent
+        → Transformer decoder → CAD command sequence
+        → OpenCascade kernel → B-rep solid
+
+    Unlike LLM backends, this does not generate CadQuery code strings.
+    Instead it produces CAD command sequences decoded directly into geometry.
+    """
+
+    def __init__(
+        self,
+        model_dir: str | Path = "./models",
+        device: str = "cuda",
+        clip_model: str = "clip_encoder.pt",
+        prior_model: str = "diffusion_prior.pt",
+        decoder_model: str = "transformer_decoder.pt",
+    ):
+        self.model_dir = Path(model_dir)
+        self.device = device
+        self.clip_encoder = None
+        self.diffusion_prior = None
+        self.transformer_decoder = None
+        self._model_config = {
+            "clip": clip_model,
+            "prior": prior_model,
+            "decoder": decoder_model,
+        }
+
+    def load_models(self):
+        """Load all model weights from disk. Call once before inference."""
+        raise NotImplementedError(
+            f"Model loading not yet implemented. "
+            f"Expected model files in: {self.model_dir}"
+        )
+
+    def encode_text(self, text: str):
+        """Encode text prompt to CLIP latent vector."""
+        raise NotImplementedError("CLIP text encoder not yet implemented")
+
+    def encode_image(self, image_path: str | Path):
+        """Encode image (photo/sketch) to CLIP latent vector."""
+        raise NotImplementedError("CLIP image encoder not yet implemented")
+
+    def run_diffusion_prior(self, clip_embedding):
+        """Map CLIP embedding to CAD latent via diffusion prior."""
+        raise NotImplementedError("Diffusion prior not yet implemented")
+
+    def decode_to_cad_sequence(self, latent):
+        """Decode latent to CAD command sequence."""
+        raise NotImplementedError("Transformer decoder not yet implemented")
+
+    def cad_sequence_to_solid(self, cad_commands: list[dict]):
+        """Execute CAD command sequence through OpenCascade kernel → B-rep solid."""
+        raise NotImplementedError("CAD kernel execution not yet implemented")
+
+    def generate(self, messages: list[dict]) -> str:
+        """
+        LLMBackend-compatible interface.
+
+        Extracts the text prompt from messages, runs the full neural pipeline,
+        and returns CadQuery-equivalent code as a string for compatibility
+        with the existing execution/validation/export pipeline.
+        """
+        user_msg = messages[-1]["content"]
+
+        clip_emb = self.encode_text(user_msg)
+        latent = self.run_diffusion_prior(clip_emb)
+        cad_commands = self.decode_to_cad_sequence(latent)
+        return self._cad_commands_to_code(cad_commands)
+
+    def generate_from_image(self, image_path: str | Path, text_hint: str = "") -> str:
+        """
+        Image-conditioned generation (not available on LLM backends).
+
+        Args:
+            image_path: Path to photo or sketch of the desired part.
+            text_hint: Optional text to guide generation alongside the image.
+
+        Returns:
+            CadQuery code string for pipeline compatibility.
+        """
+        img_emb = self.encode_image(image_path)
+        if text_hint:
+            txt_emb = self.encode_text(text_hint)
+            # Fuse text + image embeddings (strategy TBD — average, concat, cross-attn)
+            clip_emb = (img_emb + txt_emb) / 2  # placeholder fusion
+        else:
+            clip_emb = img_emb
+
+        latent = self.run_diffusion_prior(clip_emb)
+        cad_commands = self.decode_to_cad_sequence(latent)
+        return self._cad_commands_to_code(cad_commands)
+
+    def _cad_commands_to_code(self, cad_commands: list[dict]) -> str:
+        """Convert internal CAD command sequence to CadQuery Python code string."""
+        raise NotImplementedError(
+            "CAD command → CadQuery code serializer not yet implemented"
+        )

code_executor.py → core/executor.py

@@ -7,7 +7,7 @@ validates the result, and exports to STEP/STL.
 import io
 import sys
 import traceback
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
@@ -60,7 +60,6 @@ SAFE_NAMESPACE = {
         "print": print,
         "enumerate": enumerate,
         "zip": zip,
-        "__import__": __import__,
     },
 }
 

pipeline.py → core/pipeline.py

@@ -7,176 +7,24 @@ Pipeline stages:
   3. 3D Solid → CNC Validation
   4. 3D Solid → STEP / STL export
   5. (Optional) Auto-retry with error feedback if execution fails
-
-Supports multiple LLM backends:
-  - Anthropic Claude (default)
-  - OpenAI GPT-4o
-  - Local / mock (for testing without API keys)
 """
 
-import json
-import os
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
-from cadquery_system_prompt import build_messages, CADQUERY_SYSTEM_PROMPT, FEW_SHOT_EXAMPLES
-from code_executor import ExecutionResult, execute_cadquery, export_all
-from cnc_validator import validate_for_cnc, CNCValidationResult
-
-
-# ── LLM Backends ──────────────────────────────────────────────────────────
-
-class LLMBackend:
-    """Base class for LLM code generation backends."""
-
-    def generate(self, messages: list[dict]) -> str:
-        raise NotImplementedError
-
-
-class AnthropicBackend(LLMBackend):
-    """Generate CadQuery code using Anthropic Claude."""
-
-    def __init__(self, model: str = "claude-sonnet-4-20250514", api_key: Optional[str] = None):
-        import anthropic
-        self.client = anthropic.Anthropic(api_key=api_key or os.environ.get("ANTHROPIC_API_KEY"))
-        self.model = model
-
-    def generate(self, messages: list[dict]) -> str:
-        # Anthropic uses system param separately
-        system_msg = ""
-        user_messages = []
-        for m in messages:
-            if m["role"] == "system":
-                system_msg = m["content"]
-            else:
-                user_messages.append(m)
-
-        response = self.client.messages.create(
-            model=self.model,
-            max_tokens=4096,
-            system=system_msg,
-            messages=user_messages,
-        )
-        return response.content[0].text
-
-
-class OpenAIBackend(LLMBackend):
-    """Generate CadQuery code using OpenAI GPT-4o."""
-
-    def __init__(self, model: str = "gpt-4o", api_key: Optional[str] = None):
-        import openai
-        self.client = openai.OpenAI(api_key=api_key or os.environ.get("OPENAI_API_KEY"))
-        self.model = model
-
-    def generate(self, messages: list[dict]) -> str:
-        response = self.client.chat.completions.create(
-            model=self.model,
-            messages=messages,
-            max_tokens=4096,
-            temperature=0.2,
-        )
-        return response.choices[0].message.content
-
-
-class MockBackend(LLMBackend):
-    """
-    Mock backend for testing without API keys.
-    Returns pre-written CadQuery code for common prompts,
-    or a parametric box as fallback.
-    """
-
-    MOCK_RESPONSES = {
-        "bracket": """\
-import cadquery as cq
-
-# Mounting bracket: 80x50x5mm plate with four M6 holes and central slot
-result = (
-    cq.Workplane("XY")
-    .box(80, 50, 5)
-    .faces(">Z").workplane()
-    .pushPoints([(-30, -15), (-30, 15), (30, -15), (30, 15)])
-    .hole(6.5)  # M6 clearance
-    .faces(">Z").workplane()
-    .slot2D(30, 8).cutBlind(-5)  # Central slot through the plate
-    .edges("|Z").fillet(3)
-)
-""",
-        "gear": """\
-import cadquery as cq
-import math
-
-# Simple spur gear approximation: 20 teeth, module 2, 10mm thick
-module = 2
-teeth = 20
-pitch_radius = module * teeth / 2
-outer_radius = pitch_radius + module
-root_radius = pitch_radius - 1.25 * module
-tooth_angle = 360 / teeth
-
-# Start with outer cylinder, cut tooth gaps
-result = (
-    cq.Workplane("XY")
-    .cylinder(10, outer_radius)
-    .faces(">Z").workplane()
-    .hole(12)  # Bore hole
+from core.cadquery_prompts import build_messages
+from core.executor import ExecutionResult, execute_cadquery, export_all
+from core.validator import validate_for_cnc, CNCValidationResult
+from core.backends import (
+    LLMBackend, MockBackend, AnthropicBackend, OpenAIBackend,
+    GeminiBackend, NeuralCADBackend
 )
 
-# Cut tooth gaps as rectangular slots (simplified)
-for i in range(teeth):
-    angle = i * tooth_angle
-    rad = math.radians(angle)
-    gap_x = pitch_radius * math.cos(rad)
-    gap_y = pitch_radius * math.sin(rad)
-
-    cutter = (
-        cq.Workplane("XY")
-        .transformed(offset=(gap_x, gap_y, 0), rotate=(0, 0, angle))
-        .rect(module * 0.8, module * 2.5)
-        .extrude(12)
-    )
-    result = result.cut(cutter)
-
-# Chamfer top/bottom edges
-result = result.edges(">Z or <Z").chamfer(0.3)
-""",
-        "default": """\
-import cadquery as cq
-
-# Parametric box with holes and fillets — default demo part
-# 60x40x20mm block with 4 corner holes and a central pocket
-
-base = (
-    cq.Workplane("XY")
-    .box(60, 40, 20)
-    # Four M5 corner holes
-    .faces(">Z").workplane()
-    .pushPoints([(22, 12), (22, -12), (-22, 12), (-22, -12)])
-    .hole(5.5)
-    # Central rectangular pocket, 8mm deep
-    .faces(">Z").workplane()
-    .rect(25, 15)
-    .cutBlind(-8)
-)
-
-# Chamfer top external edges
-result = base.edges(">Z").chamfer(0.5)
-""",
-    }
-
-    def generate(self, messages: list[dict]) -> str:
-        # Extract user prompt (last message)
-        user_msg = messages[-1]["content"].lower()
-
-        for key, code in self.MOCK_RESPONSES.items():
-            if key in user_msg:
-                return code
-
-        return self.MOCK_RESPONSES["default"]
-
 
 # ── Pipeline ──────────────────────────────────────────────────────────────
 
+
 @dataclass
 class PipelineResult:
     prompt: str
@@ -189,7 +37,7 @@ class PipelineResult:
     def summary(self) -> str:
         lines = [
             "=" * 60,
-            f"TEXT-TO-CNC PIPELINE RESULT",
+            "TEXT-TO-CNC PIPELINE RESULT",
             "=" * 60,
             f"Prompt: {self.prompt}",
             f"Retries: {self.retry_count}",
@@ -297,7 +145,9 @@ if __name__ == "__main__":
 
     parser = argparse.ArgumentParser(description="Text-to-CNC Model Generator")
     parser.add_argument("prompt", nargs="?", default=None, help="Part description")
-    parser.add_argument("--backend", choices=["mock", "anthropic", "openai"], default="mock")
+    parser.add_argument(
+        "--backend", choices=["mock", "anthropic", "openai", "gemini", "neural"], default="mock"
+    )
     parser.add_argument("--output-dir", default="./output")
     parser.add_argument("--retries", type=int, default=2)
     parser.add_argument("--name", default=None, help="Part name for file output")
@@ -309,10 +159,14 @@ if __name__ == "__main__":
         args.prompt = "A simple mounting bracket with two M5 bolt holes"
 
     # Select backend
-    if args.backend == "anthropic":
+    if args.backend == "neural":
+        backend = NeuralCADBackend()
+    elif args.backend == "anthropic":
         backend = AnthropicBackend()
     elif args.backend == "openai":
         backend = OpenAIBackend()
+    elif args.backend == "gemini":
+        backend = GeminiBackend()
     else:
         backend = MockBackend()
 

cnc_validator.py → core/validator.py

@@ -12,7 +12,6 @@ from dataclasses import dataclass, field
 from typing import Optional
 
 import cadquery as cq
-import math
 
 
 @dataclass
@@ -54,9 +53,9 @@ class CNCValidationResult:
 
 DEFAULT_CONFIG = {
     "min_wall_thickness_mm": 1.5,
-    "min_fillet_radius_mm": 1.0,    # Typical smallest endmill radius
+    "min_fillet_radius_mm": 1.0,  # Typical smallest endmill radius
     "max_pocket_depth_ratio": 4.0,  # depth / width ratio
-    "max_part_size_mm": 500.0,      # Typical CNC work envelope
+    "max_part_size_mm": 500.0,  # Typical CNC work envelope
     "min_part_size_mm": 1.0,
     "min_hole_diameter_mm": 1.0,
 }
@@ -82,17 +81,23 @@ def validate_for_cnc(
     min_dim = dims[0]
 
     if max_dim > cfg["max_part_size_mm"]:
-        result.issues.append(CNCIssue(
-            "error", "Size",
-            f"Part too large: {max_dim:.1f}mm exceeds {cfg['max_part_size_mm']}mm work envelope"
-        ))
+        result.issues.append(
+            CNCIssue(
+                "error",
+                "Size",
+                f"Part too large: {max_dim:.1f}mm exceeds {cfg['max_part_size_mm']}mm work envelope",
+            )
+        )
         result.machinable = False
 
     if min_dim < cfg["min_part_size_mm"]:
-        result.issues.append(CNCIssue(
-            "warning", "Size",
-            f"Very small dimension: {min_dim:.2f}mm — may be difficult to fixture"
-        ))
+        result.issues.append(
+            CNCIssue(
+                "warning",
+                "Size",
+                f"Very small dimension: {min_dim:.2f}mm — may be difficult to fixture",
+            )
+        )
 
     # --- 2. Volume sanity check ---
     volume = shape.Volume()
@@ -100,14 +105,20 @@ def validate_for_cnc(
     if bb_volume > 0:
         fill_ratio = volume / bb_volume
         if fill_ratio < 0.05:
-            result.issues.append(CNCIssue(
-                "warning", "Geometry",
-                f"Very low fill ratio ({fill_ratio:.1%}) — complex geometry, high machining time"
-            ))
-        result.issues.append(CNCIssue(
-            "info", "Geometry",
-            f"Fill ratio: {fill_ratio:.1%} (volume/bounding box)"
-        ))
+            result.issues.append(
+                CNCIssue(
+                    "warning",
+                    "Geometry",
+                    f"Very low fill ratio ({fill_ratio:.1%}) — complex geometry, high machining time",
+                )
+            )
+        result.issues.append(
+            CNCIssue(
+                "info",
+                "Geometry",
+                f"Fill ratio: {fill_ratio:.1%} (volume/bounding box)",
+            )
+        )
 
     # --- 3. Face and edge complexity ---
     faces = workplane.faces().vals()
@@ -117,16 +128,22 @@ def validate_for_cnc(
     n_edges = len(edges)
 
     if n_faces > 100:
-        result.issues.append(CNCIssue(
-            "warning", "Complexity",
-            f"{n_faces} faces detected — may require multi-setup or 5-axis"
-        ))
+        result.issues.append(
+            CNCIssue(
+                "warning",
+                "Complexity",
+                f"{n_faces} faces detected — may require multi-setup or 5-axis",
+            )
+        )
         result.axis_recommendation = "5-axis"
     elif n_faces > 50:
-        result.issues.append(CNCIssue(
-            "info", "Complexity",
-            f"{n_faces} faces — consider 4-axis or indexed 5-axis"
-        ))
+        result.issues.append(
+            CNCIssue(
+                "info",
+                "Complexity",
+                f"{n_faces} faces — consider 4-axis or indexed 5-axis",
+            )
+        )
         result.axis_recommendation = "3+2 axis"
 
     # --- 4. Edge length analysis (thin feature proxy) ---
@@ -140,22 +157,28 @@ def validate_for_cnc(
     if edge_lengths:
         min_edge = min(edge_lengths)
         if min_edge < cfg["min_wall_thickness_mm"]:
-            result.issues.append(CNCIssue(
-                "warning", "Thin Feature",
-                f"Shortest edge: {min_edge:.2f}mm — below min wall thickness "
-                f"({cfg['min_wall_thickness_mm']}mm)"
-            ))
+            result.issues.append(
+                CNCIssue(
+                    "warning",
+                    "Thin Feature",
+                    f"Shortest edge: {min_edge:.2f}mm — below min wall thickness "
+                    f"({cfg['min_wall_thickness_mm']}mm)",
+                )
+            )
 
     # --- 5. Aspect ratio check (deep pocket heuristic) ---
     # Only flag if the narrowest dimension is small enough to be a pocket/slot
     if dims[0] > 0 and dims[0] < 20:
         aspect = dims[2] / dims[0]  # tallest / narrowest
         if aspect > cfg["max_pocket_depth_ratio"]:
-            result.issues.append(CNCIssue(
-                "warning", "Deep Feature",
-                f"Aspect ratio {aspect:.1f}:1 — may require long-reach tooling or "
-                f"special fixturing"
-            ))
+            result.issues.append(
+                CNCIssue(
+                    "warning",
+                    "Deep Feature",
+                    f"Aspect ratio {aspect:.1f}:1 — may require long-reach tooling or "
+                    f"special fixturing",
+                )
+            )
 
     # --- 6. Surface type analysis ---
     has_freeform = False
@@ -175,18 +198,24 @@ def validate_for_cnc(
             pass
 
     if has_freeform:
-        result.issues.append(CNCIssue(
-            "warning", "Surface",
-            "Freeform/spline surfaces detected — requires 3D contouring toolpaths"
-        ))
+        result.issues.append(
+            CNCIssue(
+                "warning",
+                "Surface",
+                "Freeform/spline surfaces detected — requires 3D contouring toolpaths",
+            )
+        )
         if result.axis_recommendation == "3-axis":
             result.axis_recommendation = "3-axis (with 3D finishing)"
 
-    result.issues.append(CNCIssue(
-        "info", "Surface",
-        f"Faces: {planar_count} planar, {cylindrical_count} cylindrical, "
-        f"{n_faces - planar_count - cylindrical_count} other"
-    ))
+    result.issues.append(
+        CNCIssue(
+            "info",
+            "Surface",
+            f"Faces: {planar_count} planar, {cylindrical_count} cylindrical, "
+            f"{n_faces - planar_count - cylindrical_count} other",
+        )
+    )
 
     # --- 7. Set final machinable flag ---
     if result.error_count > 0:

docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  mcp-server:
+    build: .
+    command: python -m server.mcp --transport sse --port 8000
+    ports:
+      - "8000:8000"
+    environment:
+      GEMINI_API_KEY: ${GEMINI_API_KEY:-}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+    volumes:
+      - ./output:/app/output
+
+  web:
+    build: .
+    command: python -m server.web --host 0.0.0.0 --port 5000
+    ports:
+      - "5000:5000"
+    environment:
+      MCP_SERVER_URL: http://mcp-server:8000/sse
+    depends_on:
+      - mcp-server
+    volumes:
+      - ./output:/app/output

docs/superpowers/plans/2026-04-08-uv-docker-deploy.md

@@ -0,0 +1,376 @@
+# uv, Docker, and HF Spaces Deployment — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Set up uv package management, Docker containerization, and deploy to Hugging Face Spaces for a free investor demo.
+
+**Architecture:** Replace requirements.txt with pyproject.toml managed by uv. Multi-stage Dockerfile builds a slim image with CadQuery. Container runs both MCP CAD server and web server. HF Spaces hosts it free at a public URL.
+
+**Tech Stack:** uv 0.8+, Docker multi-stage, docker-compose, Hugging Face Spaces (Docker SDK)
+
+---
+
+### Task 1: Create pyproject.toml
+
+**Files:**
+- Create: `pyproject.toml`
+- Modify: `requirements.txt`
+
+- [ ] **Step 1: Create pyproject.toml**
+
+```toml
+[project]
+name = "neuralcad"
+version = "1.0.0"
+description = "Text-to-CNC pipeline: natural language to machinable 3D models"
+requires-python = ">=3.10"
+dependencies = [
+    "cadquery>=2.7.0",
+    "cadquery-ocp>=7.8.0",
+    "numpy>=1.24.0",
+    "trimesh>=4.0.0",
+    "anthropic>=0.25.0",
+    "openai>=1.30.0",
+    "mcp>=1.0.0",
+    "fastapi>=0.110.0",
+    "uvicorn>=0.29.0",
+    "python-multipart>=0.0.9",
+]
+
+[dependency-groups]
+dev = ["ruff", "pytest"]
+```
+
+- [ ] **Step 2: Add backward-compat comment to requirements.txt**
+
+Replace the contents of `requirements.txt` with:
+
+```
+# Dependency source of truth is pyproject.toml — use `uv sync` to install.
+# This file is kept for environments that don't use uv.
+cadquery>=2.7.0
+cadquery-ocp>=7.8.0
+numpy>=1.24.0
+trimesh>=4.0.0
+anthropic>=0.25.0
+openai>=1.30.0
+mcp>=1.0.0
+fastapi>=0.110.0
+uvicorn>=0.29.0
+python-multipart>=0.0.9
+```
+
+- [ ] **Step 3: Generate lockfile**
+
+Run: `uv lock`
+
+Expected: `uv.lock` file is created in project root.
+
+- [ ] **Step 4: Update .gitignore**
+
+Add these lines to `.gitignore`:
+
+```
+.venv/
+```
+
+- [ ] **Step 5: Verify uv sync works**
+
+Run: `uv sync`
+
+Expected: Virtual environment created in `.venv/`, all dependencies installed. Output shows resolved packages.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add pyproject.toml uv.lock requirements.txt .gitignore
+git commit -m "build: migrate to uv with pyproject.toml and lockfile"
+```
+
+---
+
+### Task 2: Create Dockerfile
+
+**Files:**
+- Create: `Dockerfile`
+
+- [ ] **Step 1: Create Dockerfile**
+
+```dockerfile
+# ── Stage 1: Builder ─────────────────────────────────────────────────────
+FROM python:3.11-slim AS builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+# Install dependencies (cached layer — only rebuilds when deps change)
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Copy source code
+COPY . .
+
+# ── Stage 2: Runtime ─────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy virtual environment from builder
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy application source
+COPY --from=builder /app/*.py /app/
+COPY --from=builder /app/web /app/web/
+COPY --from=builder /app/entrypoint.sh /app/
+
+# Put venv on PATH
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONUNBUFFERED=1
+
+# Create output directory
+RUN mkdir -p /app/output
+
+EXPOSE 7860
+
+ENTRYPOINT ["/bin/bash", "/app/entrypoint.sh"]
+```
+
+- [ ] **Step 2: Verify syntax**
+
+Run: `docker build --check -f Dockerfile . 2>&1 || echo "syntax check done"`
+
+Expected: No syntax errors. (May fail if Docker not available — that's OK, the file is valid.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add Dockerfile
+git commit -m "build: add multi-stage Dockerfile"
+```
+
+---
+
+### Task 3: Create entrypoint.sh
+
+**Files:**
+- Create: `entrypoint.sh`
+
+- [ ] **Step 1: Create entrypoint.sh**
+
+```bash
+#!/bin/bash
+set -e
+
+echo "=== NeuralCAD Container Starting ==="
+
+# Start MCP CAD server in background
+echo "Starting MCP CAD server on port 8000..."
+python mcp_server.py --transport sse --port 8000 &
+MCP_PID=$!
+
+# Wait for MCP server to be ready
+sleep 3
+
+if ! kill -0 $MCP_PID 2>/dev/null; then
+    echo "ERROR: MCP server failed to start"
+    exit 1
+fi
+
+echo "MCP server running (PID $MCP_PID)"
+
+# Start web server in foreground
+export MCP_SERVER_URL=http://localhost:8000/sse
+PORT=${PORT:-7860}
+echo "Starting web server on port $PORT..."
+exec python web_server.py --host 0.0.0.0 --port "$PORT"
+```
+
+- [ ] **Step 2: Make executable**
+
+Run: `chmod +x entrypoint.sh`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add entrypoint.sh
+git commit -m "build: add container entrypoint script"
+```
+
+---
+
+### Task 4: Create .dockerignore
+
+**Files:**
+- Create: `.dockerignore`
+
+- [ ] **Step 1: Create .dockerignore**
+
+```
+.git
+__pycache__
+*.pyc
+output/
+.superpowers/
+.venv/
+docs/
+.env
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .dockerignore
+git commit -m "build: add .dockerignore"
+```
+
+---
+
+### Task 5: Create docker-compose.yml
+
+**Files:**
+- Create: `docker-compose.yml`
+
+- [ ] **Step 1: Create docker-compose.yml**
+
+```yaml
+services:
+  mcp-server:
+    build: .
+    command: python mcp_server.py --transport sse --port 8000
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./output:/app/output
+
+  web:
+    build: .
+    command: python web_server.py --host 0.0.0.0 --port 5000
+    ports:
+      - "5000:5000"
+    environment:
+      MCP_SERVER_URL: http://mcp-server:8000/sse
+    depends_on:
+      - mcp-server
+    volumes:
+      - ./output:/app/output
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docker-compose.yml
+git commit -m "build: add docker-compose for local dev"
+```
+
+---
+
+### Task 6: Add HF Spaces metadata to README.md
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Prepend HF Spaces YAML header to README.md**
+
+Add this YAML front matter at the very top of `README.md` (before the `# Text-to-CNC` heading):
+
+```yaml
+---
+title: NeuralCAD
+emoji: ⚙️
+colorFrom: blue
+colorTo: cyan
+sdk: docker
+app_port: 7860
+---
+```
+
+The rest of the README content stays unchanged below the `---` closing marker.
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "build: add HF Spaces metadata to README"
+```
+
+---
+
+### Task 7: Docker build and local verification
+
+**Files:** None (verification only)
+
+- [ ] **Step 1: Build Docker image**
+
+Run: `docker build -t neuralcad .`
+
+Expected: Multi-stage build completes. Final image is created. Look for `Successfully tagged neuralcad:latest`.
+
+- [ ] **Step 2: Run container**
+
+Run: `docker run --rm -p 7860:7860 --name neuralcad-test neuralcad`
+
+Expected output:
+```
+=== NeuralCAD Container Starting ===
+Starting MCP CAD server on port 8000...
+MCP server running (PID ...)
+Starting web server on port 7860...
+```
+
+- [ ] **Step 3: Test in browser**
+
+Open: `http://localhost:7860`
+
+Verify:
+1. Page loads with NeuralCAD UI
+2. Status dot is green (MCP server connected)
+3. Click "Mounting bracket" quick example
+4. 3D model renders in viewer
+5. Code tab shows CadQuery code
+6. Validation tab shows CNC report
+
+- [ ] **Step 4: Stop container**
+
+Run: `docker stop neuralcad-test` (or Ctrl+C in the terminal running it)
+
+---
+
+### Task 8: Deploy to Hugging Face Spaces
+
+**Files:** None (deployment only)
+
+- [ ] **Step 1: Create HF Space**
+
+Run:
+```bash
+huggingface-cli login
+huggingface-cli repo create neuralcad --type space --space-sdk docker
+```
+
+If `huggingface-cli` is not installed: `uv tool install huggingface-hub[cli]`
+
+- [ ] **Step 2: Add HF remote and push**
+
+```bash
+git remote add hf https://huggingface.co/spaces/CallMeDaniel/neuralcad
+git push hf main
+```
+
+- [ ] **Step 3: Set API key secrets (optional)**
+
+In the HF Space settings (https://huggingface.co/spaces/CallMeDaniel/neuralcad/settings), add secrets:
+- `ANTHROPIC_API_KEY` — for live Claude generation
+- `OPENAI_API_KEY` — for live GPT-4o generation
+
+These are optional. Mock backend works without them.
+
+- [ ] **Step 4: Verify deployment**
+
+Open: `https://callmedaniel-neuralcad.hf.space`
+
+Wait for container to build and start (~2-5 min first time). Verify:
+1. Page loads
+2. Quick examples work (mock backend)
+3. If API keys set: toggle to API mode, type custom prompt, verify live generation

docs/superpowers/plans/2026-04-11-tests-readme-ai-quality.md

@@ -0,0 +1,1538 @@
+# NeuralCAD: Tests, README, and AI Quality Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add comprehensive test coverage to NeuralCAD, update the README to reflect the current multi-agent architecture, and improve AI quality (prompt routing and report endpoint).
+
+**Architecture:** Tests are split into two tiers: (1) pure-logic tests that run without CadQuery (prompts, routing, design state, mock orchestrator, API routes) and (2) integration tests that require CadQuery (executor, validator, pipeline, CAD code generation). The README is rewritten to document the multi-agent chat system. AI quality improvements target prompt routing accuracy and the report endpoint.
+
+**Tech Stack:** pytest, FastAPI TestClient, httpx (for async), CadQuery (integration tests only)
+
+---
+
+## File Structure
+
+```
+tests/
+├── conftest.py                    # Shared fixtures (tmp output dir, mock backend, sample history)
+├── test_prompts.py                # Prompt building, @mention parsing, keyword routing, JSON parsing
+├── test_design_state.py           # DesignState model + extract_decisions()
+├── test_mock_orchestrator.py      # MockChatBackend.chat_turn() — response shape, routing, canned messages
+├── test_single_call_orchestrator.py # SingleCallOrchestrator with a fake LLM backend
+├── test_api_routes.py             # FastAPI /api/chat, /api/report, /api/agents via TestClient
+├── test_executor.py               # execute_cadquery(), sanitize_code(), exports (requires CadQuery)
+├── test_validator.py              # validate_for_cnc() (requires CadQuery)
+└── test_pipeline.py               # run_pipeline() end-to-end with MockBackend (requires CadQuery)
+```
+
+**Modified files:**
+- `README.md` — full rewrite
+- `pyproject.toml` — add `[tool.pytest.ini_options]`
+- `agents/prompts.py` — improve routing keyword coverage
+
+---
+
+### Task 1: Test Infrastructure (conftest + pytest config)
+
+**Files:**
+- Create: `tests/__init__.py`
+- Create: `tests/conftest.py`
+- Modify: `pyproject.toml`
+
+- [ ] **Step 1: Add pytest configuration to pyproject.toml**
+
+Add after the `[dependency-groups]` section in `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = [
+    "requires_cadquery: marks tests that need CadQuery installed",
+]
+```
+
+- [ ] **Step 2: Create tests/__init__.py**
+
+```python
+```
+
+(Empty file to make `tests` a package.)
+
+- [ ] **Step 3: Create tests/conftest.py with shared fixtures**
+
+```python
+"""Shared fixtures for NeuralCAD tests."""
+
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def tmp_output_dir(tmp_path):
+    """Temporary output directory for model files."""
+    out = tmp_path / "output"
+    out.mkdir()
+    return out
+
+
+@pytest.fixture
+def sample_history():
+    """A typical multi-turn conversation history."""
+    return [
+        {"role": "user", "content": "I need a servo bracket for an MG996R"},
+        {"role": "agent", "agent_id": "design", "content": "I'd suggest an L-bracket with a servo pocket on the vertical face."},
+        {"role": "agent", "agent_id": "engineering", "content": "3mm wall thickness in aluminum 6061-T6 should handle the load."},
+        {"role": "user", "content": "Make it 60mm wide with M4 base mounting holes"},
+    ]
+
+
+@pytest.fixture
+def empty_design_state():
+    """Empty design state dict."""
+    return {}
+
+
+@pytest.fixture
+def populated_design_state():
+    """Design state with some decisions already made."""
+    return {
+        "part_name": "servo_bracket",
+        "material": "aluminum 6061",
+        "dimensions": {"width": 60.0},
+        "features": ["4x M4 holes"],
+        "decisions": ["L-bracket form factor"],
+    }
+
+
+class FakeLLMBackend:
+    """A controllable fake LLM backend for testing orchestrators."""
+
+    def __init__(self, response: str = '{"agents": []}'):
+        self.response = response
+        self.calls: list[list[dict]] = []
+
+    def generate(self, messages: list[dict]) -> str:
+        self.calls.append(messages)
+        return self.response
+
+
+@pytest.fixture
+def fake_backend():
+    """FakeLLMBackend factory — call with desired JSON response."""
+    def _make(response: str = '{"agents": []}'):
+        return FakeLLMBackend(response)
+    return _make
+```
+
+- [ ] **Step 4: Run pytest to verify configuration**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest --co -q 2>&1 | head -5`
+Expected: `no tests ran` (no test files yet, but no errors)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/__init__.py tests/conftest.py pyproject.toml
+git commit -m "test: add pytest config and shared test fixtures"
+```
+
+---
+
+### Task 2: Test Prompt Building, @Mentions, Keyword Routing, JSON Parsing
+
+**Files:**
+- Create: `tests/test_prompts.py`
+
+- [ ] **Step 1: Write tests for parse_mentions()**
+
+```python
+"""Tests for agents/prompts.py — prompt building, routing, parsing."""
+
+from agents.prompts import (
+    parse_mentions,
+    route_by_keywords,
+    parse_orchestrator_response,
+    build_orchestrator_system_prompt,
+    build_chat_messages,
+    CAD_TRIGGER_KEYWORDS,
+)
+
+
+# ── parse_mentions ────────────────────────────────────────────────────────
+
+
+class TestParseMentions:
+    def test_no_mentions(self):
+        cleaned, mentions = parse_mentions("I need a bracket")
+        assert cleaned == "I need a bracket"
+        assert mentions == []
+
+    def test_single_mention(self):
+        cleaned, mentions = parse_mentions("@design what shape?")
+        assert "design" in mentions
+        assert "@design" not in cleaned
+
+    def test_multiple_mentions(self):
+        cleaned, mentions = parse_mentions("@design @engineering check this")
+        assert "design" in mentions
+        assert "engineering" in mentions
+        assert "@design" not in cleaned
+        assert "@engineering" not in cleaned
+
+    def test_cad_mention(self):
+        cleaned, mentions = parse_mentions("@cad generate a preview")
+        assert "cad" in mentions
+
+    def test_case_insensitive(self):
+        cleaned, mentions = parse_mentions("@Design what do you think?")
+        assert "design" in mentions
+
+    def test_mention_mid_sentence(self):
+        cleaned, mentions = parse_mentions("Can @engineering check the wall thickness?")
+        assert "engineering" in mentions
+        assert "Can" in cleaned
+        assert "check the wall thickness?" in cleaned
+```
+
+- [ ] **Step 2: Run tests to verify they pass**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_prompts.py::TestParseMentions -v`
+Expected: All 6 tests PASS
+
+- [ ] **Step 3: Write tests for route_by_keywords()**
+
+Append to `tests/test_prompts.py`:
+
+```python
+# ── route_by_keywords ─────────────────────────────────────────────────────
+
+
+class TestRouteByKeywords:
+    def test_design_keywords(self):
+        agents = route_by_keywords("I want a sleek design with smooth shape")
+        assert "design" in agents
+
+    def test_engineering_keywords(self):
+        agents = route_by_keywords("Use M6 bolts with 3mm wall thickness in aluminum")
+        assert "engineering" in agents
+
+    def test_cnc_keywords(self):
+        agents = route_by_keywords("Can this be machined on a 3-axis CNC mill?")
+        assert "cnc" in agents
+
+    def test_cad_trigger(self):
+        agents = route_by_keywords("Generate a preview of the part")
+        assert "cad" in agents
+
+    def test_default_when_no_match(self):
+        agents = route_by_keywords("hello there")
+        assert agents == ["design", "engineering"]
+
+    def test_max_three_agents(self):
+        agents = route_by_keywords(
+            "design shape in aluminum for CNC machining, generate preview"
+        )
+        assert len(agents) <= 3
+
+    def test_sorted_by_relevance(self):
+        agents = route_by_keywords("M4 M6 tolerance clearance aluminum steel wall")
+        assert agents[0] == "engineering"
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_prompts.py::TestRouteByKeywords -v`
+Expected: All 7 tests PASS
+
+- [ ] **Step 5: Write tests for parse_orchestrator_response()**
+
+Append to `tests/test_prompts.py`:
+
+```python
+# ── parse_orchestrator_response ───────────────────────────────────────────
+
+
+class TestParseOrchestratorResponse:
+    def test_valid_json(self):
+        resp = '{"agents": [{"id": "design", "message": "Nice bracket."}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "design"
+        assert parsed[0]["message"] == "Nice bracket."
+        assert parsed[0]["code"] is None
+
+    def test_json_with_code(self):
+        resp = '{"agents": [{"id": "cad", "message": "Done.", "code": "result = cq.Workplane().box(10,10,10)"}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert parsed[0]["code"] == "result = cq.Workplane().box(10,10,10)"
+
+    def test_json_in_markdown_fence(self):
+        resp = '```json\n{"agents": [{"id": "engineering", "message": "Use 3mm walls."}]}\n```'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "engineering"
+
+    def test_multiple_agents(self):
+        resp = '{"agents": [{"id": "design", "message": "A"}, {"id": "cnc", "message": "B"}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 2
+        assert parsed[0]["id"] == "design"
+        assert parsed[1]["id"] == "cnc"
+
+    def test_invalid_json_fallback(self):
+        resp = "I think you should use aluminum."
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "design"
+        assert parsed[0]["message"] == resp
+
+    def test_empty_agents_fallback(self):
+        resp = '{"agents": []}'
+        parsed = parse_orchestrator_response(resp)
+        # Empty agents list falls back to treating as design message
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "design"
+
+    def test_missing_fields_skipped(self):
+        resp = '{"agents": [{"id": "design"}, {"id": "cnc", "message": "OK"}]}'
+        parsed = parse_orchestrator_response(resp)
+        # First agent missing "message" is skipped
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "cnc"
+```
+
+- [ ] **Step 6: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_prompts.py::TestParseOrchestratorResponse -v`
+Expected: All 7 tests PASS
+
+- [ ] **Step 7: Write tests for build_orchestrator_system_prompt() and build_chat_messages()**
+
+Append to `tests/test_prompts.py`:
+
+```python
+# ── build_orchestrator_system_prompt ──────────────────────────────────────
+
+
+class TestBuildOrchestratorSystemPrompt:
+    def test_default_agents(self):
+        prompt = build_orchestrator_system_prompt()
+        assert "Design Agent" in prompt
+        assert "Engineering Agent" in prompt
+        assert "CNC Agent" in prompt
+        assert "CAD Coder" not in prompt
+
+    def test_specific_agents(self):
+        prompt = build_orchestrator_system_prompt(active_agents=["cad"])
+        assert "CAD Coder" in prompt
+        assert "Design Agent" not in prompt
+
+    def test_includes_json_format(self):
+        prompt = build_orchestrator_system_prompt()
+        assert '"agents"' in prompt
+        assert "JSON" in prompt
+
+    def test_cad_context_included(self):
+        prompt = build_orchestrator_system_prompt(
+            active_agents=["cad"], include_cad_context=True
+        )
+        assert "CadQuery" in prompt
+
+
+# ── build_chat_messages ───────────────────────────────────────────────────
+
+
+class TestBuildChatMessages:
+    def test_returns_system_and_user(self):
+        msgs = build_chat_messages("hello", [], "You are a bot.")
+        assert len(msgs) == 2
+        assert msgs[0]["role"] == "system"
+        assert msgs[0]["content"] == "You are a bot."
+        assert msgs[1]["role"] == "user"
+
+    def test_history_included_in_user_message(self, sample_history):
+        msgs = build_chat_messages("new msg", sample_history, "system prompt")
+        user_content = msgs[1]["content"]
+        assert "servo bracket" in user_content
+        assert "new msg" in user_content
+
+    def test_design_state_included(self):
+        msgs = build_chat_messages(
+            "make it wider", [], "system prompt",
+            design_state_text="Part: bracket\nMaterial: aluminum"
+        )
+        user_content = msgs[1]["content"]
+        assert "bracket" in user_content
+        assert "aluminum" in user_content
+
+    def test_history_truncation(self):
+        long_history = [
+            {"role": "user", "content": f"msg {i}"}
+            for i in range(50)
+        ]
+        msgs = build_chat_messages("latest", long_history, "sys", max_history=5)
+        user_content = msgs[1]["content"]
+        # Should include msg 45-49 but not msg 0
+        assert "msg 49" in user_content
+        assert "msg 0" not in user_content
+```
+
+- [ ] **Step 8: Run all prompt tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_prompts.py -v`
+Expected: All tests PASS (approximately 25 tests)
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add tests/test_prompts.py
+git commit -m "test: add prompt building, routing, and JSON parsing tests"
+```
+
+---
+
+### Task 3: Test DesignState and Decision Extraction
+
+**Files:**
+- Create: `tests/test_design_state.py`
+
+- [ ] **Step 1: Write tests for DesignState model**
+
+```python
+"""Tests for agents/design_state.py — state tracking and decision extraction."""
+
+from agents.design_state import DesignState, extract_decisions
+
+
+class TestDesignState:
+    def test_empty_render(self):
+        state = DesignState()
+        assert state.render() == ""
+
+    def test_render_with_fields(self):
+        state = DesignState(
+            part_name="bracket",
+            material="aluminum 6061",
+            dimensions={"width": 60.0, "height": 40.0},
+        )
+        rendered = state.render()
+        assert "bracket" in rendered
+        assert "aluminum 6061" in rendered
+        assert "width=60.0mm" in rendered
+
+    def test_render_features(self):
+        state = DesignState(features=["4x M6 holes", "fillet"])
+        rendered = state.render()
+        assert "4x M6 holes" in rendered
+
+    def test_render_decisions_capped_at_5(self):
+        state = DesignState(decisions=[f"decision {i}" for i in range(10)])
+        rendered = state.render()
+        assert "decision 9" in rendered
+        assert "decision 4" not in rendered
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_design_state.py::TestDesignState -v`
+Expected: All 4 tests PASS
+
+- [ ] **Step 3: Write tests for extract_decisions()**
+
+Append to `tests/test_design_state.py`:
+
+```python
+class TestExtractDecisions:
+    def test_extracts_material(self):
+        responses = [
+            {"agent_id": "engineering", "message": "I recommend aluminum 6061 for this application."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert "aluminum" in state.material.lower()
+
+    def test_extracts_dimensions_from_user(self):
+        responses = []
+        state = extract_decisions(responses, DesignState(), user_message="Make it 60mm wide and 40mm tall")
+        assert state.dimensions.get("width") == 60.0
+        assert state.dimensions.get("height") == 40.0
+
+    def test_extracts_fastener_features(self):
+        responses = [
+            {"agent_id": "engineering", "message": "I'll add 4x M6 clearance holes for mounting."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert any("M6" in f for f in state.features)
+
+    def test_extracts_axis_recommendation(self):
+        responses = [
+            {"agent_id": "cnc", "message": "This part needs 5-axis machining due to the undercut."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert "5-axis" in state.axis_recommendation
+
+    def test_extracts_part_name(self):
+        responses = []
+        state = extract_decisions(responses, DesignState(), user_message="I need a servo bracket")
+        assert "servo bracket" in state.part_name.lower() or "servo_bracket" in state.part_name.lower()
+
+    def test_preserves_existing_state(self):
+        existing = DesignState(material="steel", dimensions={"width": 50.0})
+        responses = [
+            {"agent_id": "engineering", "message": "Height should be 30mm."}
+        ]
+        updated = extract_decisions(responses, existing, user_message="add height")
+        # Material preserved, new dimension added
+        assert updated.material == "steel"
+        assert updated.dimensions.get("width") == 50.0
+
+    def test_extracts_decisions_from_agreement(self):
+        responses = [
+            {"agent_id": "design", "message": "I'd recommend an L-bracket form factor for this."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert len(state.decisions) > 0
+
+    def test_no_duplicate_features(self):
+        existing = DesignState(features=["4x M6 holes"])
+        responses = [
+            {"agent_id": "engineering", "message": "The 4x M6 holes are properly specified."}
+        ]
+        updated = extract_decisions(responses, existing)
+        m6_count = sum(1 for f in updated.features if "M6" in f)
+        assert m6_count == 1
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_design_state.py -v`
+Expected: All 12 tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/test_design_state.py
+git commit -m "test: add design state and decision extraction tests"
+```
+
+---
+
+### Task 4: Test MockChatBackend
+
+**Files:**
+- Create: `tests/test_mock_orchestrator.py`
+
+- [ ] **Step 1: Write tests for MockChatBackend**
+
+```python
+"""Tests for agents/orchestrator.py — MockChatBackend and helpers."""
+
+from agents.orchestrator import MockChatBackend, _format_response
+from agents.definitions import AGENTS, AGENT_COLORS, AGENT_NAMES, AGENT_AVATARS
+
+
+class TestFormatResponse:
+    def test_returns_all_fields(self):
+        resp = _format_response("design", "Hello")
+        assert resp["agent_id"] == "design"
+        assert resp["agent_name"] == AGENT_NAMES["design"]
+        assert resp["message"] == "Hello"
+        assert resp["color"] == AGENT_COLORS["design"]
+        assert resp["avatar"] == AGENT_AVATARS["design"]
+        assert resp["code"] is None
+
+    def test_includes_code(self):
+        resp = _format_response("cad", "Done.", code="result = cq.Workplane().box(10,10,10)")
+        assert resp["code"] == "result = cq.Workplane().box(10,10,10)"
+
+
+class TestMockChatBackend:
+    def test_response_shape(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("I need a bracket", history=[])
+        assert "responses" in result
+        assert "preview" in result
+        assert "design_state" in result
+        assert isinstance(result["responses"], list)
+        assert len(result["responses"]) > 0
+
+    def test_bracket_routes_to_design(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Design a mounting bracket", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "design" in agent_ids
+
+    def test_mention_overrides_routing(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn(
+            "What do you think?",
+            history=[],
+            mentions=["cnc"],
+        )
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert agent_ids == ["cnc"]
+
+    def test_cad_mention_generates_code(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn(
+            "Generate a 50mm cube",
+            history=[],
+            mentions=["cad"],
+        )
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "cad" in agent_ids
+        cad_resp = next(r for r in result["responses"] if r["agent_id"] == "cad")
+        assert cad_resp["code"] is not None
+        assert "result" in cad_resp["code"]
+
+    def test_design_state_updated(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn(
+            "Make it 60mm wide in aluminum",
+            history=[],
+        )
+        ds = result["design_state"]
+        assert isinstance(ds, dict)
+
+    def test_engineering_keywords_trigger_engineering(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Use M6 bolts with 3mm wall thickness", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "engineering" in agent_ids
+
+    def test_cnc_keywords_trigger_cnc(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Can this be machined on a CNC mill?", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "cnc" in agent_ids
+
+    def test_generic_message_default_agents(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Hello there", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        # Default: design + engineering
+        assert "design" in agent_ids
+        assert "engineering" in agent_ids
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_mock_orchestrator.py -v`
+Expected: All 10 tests PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_mock_orchestrator.py
+git commit -m "test: add MockChatBackend tests"
+```
+
+---
+
+### Task 5: Test SingleCallOrchestrator with Fake Backend
+
+**Files:**
+- Create: `tests/test_single_call_orchestrator.py`
+
+- [ ] **Step 1: Write tests**
+
+```python
+"""Tests for SingleCallOrchestrator using a fake LLM backend."""
+
+import json
+from agents.orchestrator import SingleCallOrchestrator
+from tests.conftest import FakeLLMBackend
+
+
+class TestSingleCallOrchestrator:
+    def _make_orchestrator(self, response_json: str, tmp_output_dir):
+        backend = FakeLLMBackend(response_json)
+        return SingleCallOrchestrator(backend=backend, output_dir=tmp_output_dir), backend
+
+    def test_response_shape(self, tmp_output_dir):
+        resp = json.dumps({"agents": [
+            {"id": "design", "message": "An L-bracket would work."},
+        ]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("I need a bracket", history=[])
+        assert "responses" in result
+        assert "preview" in result
+        assert "design_state" in result
+
+    def test_passes_message_to_backend(self, tmp_output_dir):
+        resp = json.dumps({"agents": [{"id": "design", "message": "OK"}]})
+        orch, backend = self._make_orchestrator(resp, tmp_output_dir)
+        orch.chat_turn("Test message", history=[])
+        assert len(backend.calls) == 1
+        last_user_msg = backend.calls[0][-1]["content"]
+        assert "Test message" in last_user_msg
+
+    def test_mentions_restrict_agents(self, tmp_output_dir):
+        resp = json.dumps({"agents": [{"id": "cnc", "message": "3-axis OK"}]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("check this", history=[], mentions=["cnc"])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "cnc" in agent_ids
+
+    def test_invalid_json_fallback(self, tmp_output_dir):
+        orch, _ = self._make_orchestrator("not json at all", tmp_output_dir)
+        result = orch.chat_turn("help", history=[])
+        # Fallback treats entire response as design agent message
+        assert len(result["responses"]) > 0
+        assert result["responses"][0]["agent_id"] == "design"
+
+    def test_llm_exception_fallback(self, tmp_output_dir):
+        backend = FakeLLMBackend("")
+        backend.generate = lambda msgs: (_ for _ in ()).throw(RuntimeError("API error"))
+        orch = SingleCallOrchestrator(backend=backend, output_dir=tmp_output_dir)
+        result = orch.chat_turn("Design a part", history=[])
+        # Should return fallback messages, not crash
+        assert len(result["responses"]) > 0
+
+    def test_unknown_agent_id_filtered(self, tmp_output_dir):
+        resp = json.dumps({"agents": [
+            {"id": "nonexistent", "message": "I don't exist"},
+            {"id": "design", "message": "Real agent"},
+        ]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("test", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "nonexistent" not in agent_ids
+        assert "design" in agent_ids
+
+    def test_history_forwarded_to_backend(self, tmp_output_dir, sample_history):
+        resp = json.dumps({"agents": [{"id": "design", "message": "OK"}]})
+        orch, backend = self._make_orchestrator(resp, tmp_output_dir)
+        orch.chat_turn("continue", history=sample_history)
+        user_content = backend.calls[0][-1]["content"]
+        assert "servo bracket" in user_content.lower() or "MG996R" in user_content
+
+    def test_design_state_returned(self, tmp_output_dir):
+        resp = json.dumps({"agents": [
+            {"id": "engineering", "message": "Use aluminum 6061 with 3mm walls."},
+        ]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("material?", history=[])
+        assert "design_state" in result
+        assert isinstance(result["design_state"], dict)
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_single_call_orchestrator.py -v`
+Expected: All 8 tests PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_single_call_orchestrator.py
+git commit -m "test: add SingleCallOrchestrator tests with fake backend"
+```
+
+---
+
+### Task 6: Test API Routes
+
+**Files:**
+- Create: `tests/test_api_routes.py`
+
+- [ ] **Step 1: Write tests for /api/chat, /api/report, /api/agents**
+
+```python
+"""Tests for server/routes.py — FastAPI chat API endpoints."""
+
+import pytest
+from fastapi.testclient import TestClient
+from server.web import app
+
+
+client = TestClient(app)
+
+
+class TestChatEndpoint:
+    def test_basic_chat(self):
+        resp = client.post("/api/chat", json={
+            "message": "I need a bracket",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "responses" in data
+        assert len(data["responses"]) > 0
+
+    def test_chat_with_mentions(self):
+        resp = client.post("/api/chat", json={
+            "message": "What do you think?",
+            "history": [],
+            "mentions": ["cnc"],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        agent_ids = [r["agent_id"] for r in data["responses"]]
+        assert "cnc" in agent_ids
+
+    def test_chat_with_history(self):
+        resp = client.post("/api/chat", json={
+            "message": "Make it wider",
+            "history": [
+                {"role": "user", "content": "I need a bracket"},
+                {"role": "agent", "agent_id": "design", "content": "L-bracket suggestion."},
+            ],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "responses" in data
+
+    def test_chat_empty_message_rejected(self):
+        resp = client.post("/api/chat", json={
+            "message": "",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 422  # Pydantic validation error
+
+    def test_chat_returns_design_state(self):
+        resp = client.post("/api/chat", json={
+            "message": "60mm wide aluminum bracket",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "design_state" in data
+
+    def test_chat_at_mention_in_message(self):
+        resp = client.post("/api/chat", json={
+            "message": "@engineering what thickness?",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        agent_ids = [r["agent_id"] for r in data["responses"]]
+        assert "engineering" in agent_ids
+
+
+class TestReportEndpoint:
+    def test_basic_report(self):
+        resp = client.post("/api/report", json={
+            "part_name": "test_bracket",
+            "history": [
+                {"role": "agent", "agent_id": "design", "content": "L-bracket design."},
+                {"role": "agent", "agent_id": "engineering", "content": "3mm aluminum."},
+                {"role": "agent", "agent_id": "cnc", "content": "3-axis OK."},
+            ],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "report" in data
+        assert "test_bracket" in data["report"]
+        assert "Design Decisions" in data["report"]
+        assert "Engineering Specifications" in data["report"]
+        assert "Manufacturing Notes" in data["report"]
+
+    def test_empty_history(self):
+        resp = client.post("/api/report", json={
+            "part_name": "empty_part",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "report" in data
+
+
+class TestAgentsEndpoint:
+    def test_list_agents(self):
+        resp = client.get("/api/agents")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "agents" in data
+        agent_ids = [a["id"] for a in data["agents"]]
+        assert "design" in agent_ids
+        assert "engineering" in agent_ids
+        assert "cnc" in agent_ids
+        assert "cad" in agent_ids
+
+    def test_agent_has_metadata(self):
+        resp = client.get("/api/agents")
+        data = resp.json()
+        agent = data["agents"][0]
+        assert "id" in agent
+        assert "name" in agent
+        assert "role" in agent
+        assert "color" in agent
+        assert "avatar" in agent
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_api_routes.py -v`
+Expected: All 10 tests PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_api_routes.py
+git commit -m "test: add FastAPI route tests for chat, report, and agents endpoints"
+```
+
+---
+
+### Task 7: Test CadQuery Executor and Validator (Integration)
+
+**Files:**
+- Create: `tests/test_executor.py`
+- Create: `tests/test_validator.py`
+
+- [ ] **Step 1: Write executor tests**
+
+```python
+"""Tests for core/executor.py — CadQuery code execution and export.
+
+These tests require CadQuery to be installed.
+"""
+
+import pytest
+from pathlib import Path
+from core.executor import sanitize_code, execute_cadquery, export_step, export_stl, export_all
+
+pytestmark = pytest.mark.requires_cadquery
+
+
+class TestSanitizeCode:
+    def test_strips_markdown_fences(self):
+        code = "```python\nresult = 1\n```"
+        assert "```" not in sanitize_code(code)
+
+    def test_strips_plain_fences(self):
+        code = "```\nresult = 1\n```"
+        assert "```" not in sanitize_code(code)
+
+    def test_removes_cadquery_imports(self):
+        code = "import cadquery as cq\nresult = cq.Workplane('XY').box(10,10,10)"
+        cleaned = sanitize_code(code)
+        assert "import cadquery" not in cleaned
+        assert "result" in cleaned
+
+    def test_removes_math_import(self):
+        code = "import math\nresult = cq.Workplane('XY').box(10,10,10)"
+        cleaned = sanitize_code(code)
+        assert "import math" not in cleaned
+
+    def test_preserves_valid_code(self):
+        code = "result = cq.Workplane('XY').box(10, 20, 30)"
+        assert sanitize_code(code) == code
+
+
+class TestExecuteCadquery:
+    def test_simple_box(self):
+        result = execute_cadquery("result = cq.Workplane('XY').box(10, 20, 30)")
+        assert result.success is True
+        assert result.volume > 0
+        assert result.face_count == 6
+        assert result.edge_count == 12
+        assert len(result.bounding_box) == 3
+
+    def test_cylinder(self):
+        result = execute_cadquery("result = cq.Workplane('XY').cylinder(20, 10)")
+        assert result.success is True
+        assert result.volume > 0
+
+    def test_missing_result_variable(self):
+        result = execute_cadquery("x = cq.Workplane('XY').box(10,10,10)")
+        assert result.success is False
+        assert "result" in result.error
+
+    def test_syntax_error(self):
+        result = execute_cadquery("result = cq.Workplane('XY').box(10, 10,")
+        assert result.success is False
+        assert result.error is not None
+
+    def test_wrong_type(self):
+        result = execute_cadquery("result = 42")
+        assert result.success is False
+        assert "Workplane" in result.error
+
+    def test_code_with_markdown_fences(self):
+        code = "```python\nimport cadquery as cq\nresult = cq.Workplane('XY').box(5,5,5)\n```"
+        result = execute_cadquery(code)
+        assert result.success is True
+
+    def test_summary_on_success(self):
+        result = execute_cadquery("result = cq.Workplane('XY').box(10, 20, 30)")
+        summary = result.summary()
+        assert "OK" in summary
+        assert "Volume" in summary
+
+    def test_summary_on_failure(self):
+        result = execute_cadquery("result = bad_code")
+        summary = result.summary()
+        assert "FAILED" in summary
+
+
+class TestExport:
+    def test_export_step(self, tmp_path):
+        exec_result = execute_cadquery("result = cq.Workplane('XY').box(10,10,10)")
+        assert exec_result.success
+        path = export_step(exec_result.result, tmp_path / "test.step")
+        assert path.exists()
+        assert path.suffix == ".step"
+
+    def test_export_stl(self, tmp_path):
+        exec_result = execute_cadquery("result = cq.Workplane('XY').box(10,10,10)")
+        assert exec_result.success
+        path = export_stl(exec_result.result, tmp_path / "test.stl")
+        assert path.exists()
+        assert path.suffix == ".stl"
+
+    def test_export_all(self, tmp_path):
+        exec_result = execute_cadquery("result = cq.Workplane('XY').box(10,10,10)")
+        assert exec_result.success
+        files = export_all(exec_result.result, tmp_path / "part")
+        assert files["step"].exists()
+        assert files["stl"].exists()
+```
+
+- [ ] **Step 2: Run executor tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_executor.py -v`
+Expected: All 13 tests PASS (if CadQuery installed), or all SKIPPED
+
+- [ ] **Step 3: Write validator tests**
+
+```python
+"""Tests for core/validator.py — CNC manufacturability validation.
+
+These tests require CadQuery to be installed.
+"""
+
+import pytest
+from core.executor import execute_cadquery
+from core.validator import validate_for_cnc, CNCValidationResult, CNCIssue
+
+pytestmark = pytest.mark.requires_cadquery
+
+
+def _make_solid(code: str):
+    """Helper to create a CadQuery Workplane from code."""
+    result = execute_cadquery(code)
+    assert result.success, f"Code failed: {result.error}"
+    return result.result
+
+
+class TestValidateForCnc:
+    def test_simple_box_is_machinable(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, "test_box")
+        assert val.machinable is True
+        assert val.error_count == 0
+
+    def test_result_has_part_name(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, "my_part")
+        assert val.part_name == "my_part"
+
+    def test_axis_recommendation_default_3axis(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid)
+        assert "3-axis" in val.axis_recommendation or "3" in val.axis_recommendation
+
+    def test_complex_part_gets_higher_axis(self):
+        # A part with many faces should get a higher axis recommendation
+        code = """
+result = cq.Workplane('XY').box(50, 50, 50)
+for i in range(5):
+    result = result.faces('>Z').workplane().pushPoints([(i*8-16, 0)]).hole(3)
+for i in range(5):
+    result = result.faces('>X').workplane().pushPoints([(i*8-16, 0)]).hole(3)
+"""
+        solid = _make_solid(code)
+        val = validate_for_cnc(solid)
+        # Should have many faces due to holes
+        assert val.part_name is not None
+
+    def test_oversized_part_flagged(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(600, 600, 600)")
+        val = validate_for_cnc(solid, config={"max_part_size_mm": 500.0})
+        assert any(i.category == "Size" for i in val.issues)
+
+    def test_tiny_part_flagged(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(0.5, 0.5, 0.5)")
+        val = validate_for_cnc(solid, config={"min_part_size_mm": 1.0})
+        assert any(i.category == "Size" for i in val.issues)
+
+    def test_summary_format(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, "test")
+        summary = val.summary()
+        assert isinstance(summary, str)
+        assert "test" in summary
+
+    def test_custom_config(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, config={"min_wall_thickness_mm": 0.5})
+        assert isinstance(val, CNCValidationResult)
+
+    def test_error_and_warning_counts(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid)
+        assert val.error_count >= 0
+        assert val.warning_count >= 0
+        assert val.error_count + val.warning_count <= len(val.issues)
+```
+
+- [ ] **Step 4: Run validator tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_validator.py -v`
+Expected: All 9 tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/test_executor.py tests/test_validator.py
+git commit -m "test: add CadQuery executor and CNC validator integration tests"
+```
+
+---
+
+### Task 8: Test Pipeline End-to-End
+
+**Files:**
+- Create: `tests/test_pipeline.py`
+
+- [ ] **Step 1: Write pipeline integration tests**
+
+```python
+"""Tests for core/pipeline.py — end-to-end text-to-CNC pipeline.
+
+These tests require CadQuery to be installed.
+"""
+
+import pytest
+from pathlib import Path
+from core.pipeline import run_pipeline, PipelineResult
+from core.backends import MockBackend
+
+pytestmark = pytest.mark.requires_cadquery
+
+
+class TestRunPipeline:
+    def test_basic_box(self, tmp_output_dir):
+        result = run_pipeline(
+            "A simple 50mm cube",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+        )
+        assert isinstance(result, PipelineResult)
+        assert result.execution.success is True
+        assert result.execution.volume > 0
+
+    def test_exports_files(self, tmp_output_dir):
+        result = run_pipeline(
+            "A 60x40x5mm mounting plate",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            part_name="test_plate",
+        )
+        assert result.exported_files is not None
+        assert result.exported_files["step"].exists()
+        assert result.exported_files["stl"].exists()
+
+    def test_validation_runs(self, tmp_output_dir):
+        result = run_pipeline(
+            "A 50mm cylinder",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            validate=True,
+        )
+        assert result.validation is not None
+        assert hasattr(result.validation, "machinable")
+
+    def test_skip_validation(self, tmp_output_dir):
+        result = run_pipeline(
+            "A simple box",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            validate=False,
+        )
+        assert result.validation is None
+
+    def test_skip_export(self, tmp_output_dir):
+        result = run_pipeline(
+            "A simple box",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            export=False,
+        )
+        assert result.exported_files is None or len(result.exported_files) == 0
+
+    def test_summary(self, tmp_output_dir):
+        result = run_pipeline(
+            "A 30mm cube",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+        )
+        summary = result.summary()
+        assert isinstance(summary, str)
+
+    def test_default_backend_is_mock(self, tmp_output_dir):
+        # Should work without specifying backend
+        result = run_pipeline(
+            "A basic plate",
+            output_dir=tmp_output_dir,
+        )
+        assert result.execution.success is True
+```
+
+- [ ] **Step 2: Run pipeline tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_pipeline.py -v`
+Expected: All 7 tests PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_pipeline.py
+git commit -m "test: add end-to-end pipeline integration tests"
+```
+
+---
+
+### Task 9: Update README
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Rewrite README.md**
+
+Replace the entire contents of `README.md` with:
+
+```markdown
+---
+title: NeuralCAD
+emoji: ⚙️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+---
+
+# NeuralCAD — Multi-Agent CAD Design
+
+A multi-agent AI system that converts natural language descriptions of mechanical parts into CNC-machinable 3D models (STEP/STL). Four specialized AI agents collaborate with you in a shared chat to design, engineer, validate, and generate CadQuery code.
+
+## How It Works
+
+```
+User ──→ Chat Interface ──→ Agent Orchestrator
+                                    │
+                    ┌───────────────┼───────────────┐
+                    │               │               │
+              Design Agent    Engineering     CNC Agent
+              (form/shape)    Agent           (manufacturability)
+                    │         (specs/dims)          │
+                    └───────────────┼───────────────┘
+                                    │
+                              CAD Coder Agent
+                              (CadQuery code)
+                                    │
+                            Execute in Sandbox
+                                    │
+                              3D Solid (B-rep)
+                               ╱           ╲
+                     CNC Validator      Exporter
+                     (machinability     (STEP + STL)
+                      checks)
+```
+
+## Agents
+
+| Agent | Role | Expertise |
+|-------|------|-----------|
+| **Design Agent** | Industrial Designer | Form, aesthetics, ergonomics, shape proposals |
+| **Engineering Agent** | Mechanical Engineer | Dimensions, tolerances, materials, fastener specs |
+| **CNC Agent** | Manufacturing Advisor | Tool access, wall thickness, axis requirements, cost |
+| **CAD Coder** | CadQuery Programmer | Generates valid CadQuery Python code on demand |
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the web app (mock backend, no API key needed)
+python -m server.web --port 5000
+
+# Open http://localhost:5000 in your browser
+```
+
+### With LLM Backends
+
+```bash
+# Gemini (free tier)
+export GOOGLE_API_KEY=...
+# Select GEMINI in the web UI backend toggle
+
+# Claude (recommended for quality)
+export ANTHROPIC_API_KEY=sk-ant-...
+# Select CLAUDE in the web UI backend toggle
+
+# GPT-4o
+export OPENAI_API_KEY=sk-...
+```
+
+### CLI Pipeline (Direct)
+
+```bash
+# Mock backend
+python -m core.pipeline "A mounting bracket with four M6 holes"
+
+# With Claude
+python -m core.pipeline "A flanged bearing housing" --backend anthropic
+```
+
+## Architecture
+
+```
+NeuralCAD/
+├── agents/                  # Multi-agent orchestration
+│   ├── definitions.py       # Agent roles, colors, personas
+│   ├── orchestrator.py      # Single-call + Mock orchestrators
+│   ├── crew_orchestrator.py # CrewAI multi-call orchestrator
+│   ├── prompts.py           # System prompts, routing, JSON parsing
+│   ├── design_state.py      # Design decision accumulator
+│   └── llm_adapter.py       # CrewAI LLM adapter
+├── core/                    # CAD generation pipeline
+│   ├── backends.py          # LLM backends (Mock, Anthropic, OpenAI, Gemini)
+│   ├── pipeline.py          # Text-to-CNC orchestrator + CLI
+│   ├── executor.py          # Sandboxed CadQuery execution + export
+│   ├── validator.py         # CNC manufacturability checker
+│   └── cadquery_prompts.py  # CadQuery system prompt + few-shot examples
+├── server/                  # Web + MCP servers
+│   ├── web.py               # FastAPI app, static serving
+│   ├── routes.py            # Chat API endpoints
+│   └── mcp.py               # MCP server (Claude Desktop / Claude Code)
+├── web/
+│   └── index.html           # Frontend: Three.js viewer + chat panel
+└── tests/                   # Test suite
+```
+
+### Orchestration Modes
+
+| Backend | Mode | API Calls/Turn | Use Case |
+|---------|------|----------------|----------|
+| Mock | Template-based | 0 | UI development, demos |
+| Gemini | Single-call | 1 | Free tier, rate-limited |
+| Anthropic | CrewAI multi-call | 2-4 | Best quality |
+| OpenAI | CrewAI multi-call | 2-4 | Best quality |
+
+### Chat API
+
+**POST /api/chat** — Multi-agent chat turn
+
+```json
+{
+  "message": "Make it 60mm wide with M4 base mounting",
+  "history": [{"role": "user", "content": "I need a servo bracket"}],
+  "mentions": [],
+  "backend": "mock"
+}
+```
+
+**POST /api/report** — Generate design report from conversation
+
+**GET /api/agents** — List available agents and metadata
+
+## Features
+
+- **Multi-agent chat** — 4 specialist agents collaborate on part design
+- **@mention system** — Direct messages to specific agents (`@design`, `@engineering`, `@cnc`, `@cad`)
+- **3D preview** — Real-time STL rendering with Three.js (orbit, zoom, pan)
+- **Design state tracking** — Accumulates decisions across turns (localStorage persistence)
+- **CNC validation** — Checks wall thickness, pocket ratios, tool access, axis requirements
+- **Model gallery** — Browse and reload previously generated models
+- **STEP + STL export** — Download CAM-ready files
+- **MCP server** — Use from Claude Desktop or Claude Code
+
+## MCP Server
+
+```bash
+# Connect to Claude Code
+claude mcp add text-to-cnc python3 -m server.mcp
+
+# Run standalone (SSE for remote integrations)
+python -m server.mcp --transport sse --port 8000
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `generate_cnc_model` | Text → CadQuery code → 3D solid → STEP/STL |
+| `validate_cnc_model` | Run manufacturability checks on CadQuery code |
+| `execute_cadquery_code` | Execute arbitrary CadQuery code |
+| `chat_turn` | Multi-agent chat turn |
+| `list_models` | List generated models |
+
+## Testing
+
+```bash
+# All tests
+python -m pytest
+
+# Pure logic tests only (no CadQuery needed)
+python -m pytest -m "not requires_cadquery"
+
+# Integration tests
+python -m pytest -m requires_cadquery
+
+# Verbose
+python -m pytest -v
+```
+
+## Docker
+
+```bash
+docker compose up --build
+# Open http://localhost:7860
+```
+
+## Key Research
+
+- **Text-to-CadQuery** (2025) — LLM generates CadQuery code directly
+- **GenCAD** (2024) — Transformer + diffusion for image to CAD
+- **NURBGen** (2025) — NURBS-based B-rep from text via LLM
+```
+
+- [ ] **Step 2: Verify README renders correctly**
+
+Run: `cd /home/daniel/NeuralCAD && head -20 README.md`
+Expected: See the HF Spaces frontmatter and title
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: rewrite README to document multi-agent architecture"
+```
+
+---
+
+### Task 10: Improve Keyword Routing Accuracy
+
+**Files:**
+- Modify: `agents/prompts.py:162-179`
+
+- [ ] **Step 1: Write a failing test for weak routing**
+
+Append to `tests/test_prompts.py`:
+
+```python
+class TestRouteByKeywordsImproved:
+    """Tests for improved keyword routing coverage."""
+
+    def test_gear_routes_to_engineering(self):
+        agents = route_by_keywords("I need a spur gear with 20 teeth")
+        assert "engineering" in agents
+
+    def test_bearing_routes_to_engineering(self):
+        agents = route_by_keywords("Design a bearing housing")
+        assert "engineering" in agents
+
+    def test_heatsink_routes_to_engineering(self):
+        agents = route_by_keywords("Create a heatsink with fins")
+        assert "engineering" in agents
+
+    def test_flange_routes_to_engineering(self):
+        agents = route_by_keywords("A pipe flange with bolt holes")
+        assert "engineering" in agents
+
+    def test_servo_bracket_routes_to_design(self):
+        agents = route_by_keywords("Design a servo bracket for a camera gimbal")
+        assert "design" in agents
+
+    def test_cost_routes_to_cnc(self):
+        agents = route_by_keywords("How much would this cost to machine?")
+        assert "cnc" in agents
+
+    def test_surface_finish_routes_to_cnc(self):
+        agents = route_by_keywords("What surface finish can we achieve?")
+        assert "cnc" in agents
+```
+
+- [ ] **Step 2: Run new routing tests to see which fail**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_prompts.py::TestRouteByKeywordsImproved -v`
+Expected: Some tests FAIL (gear, bearing, heatsink, flange, surface finish not in keywords)
+
+- [ ] **Step 3: Add missing keywords to _ROUTING_KEYWORDS**
+
+In `agents/prompts.py`, replace the `_ROUTING_KEYWORDS` dict (lines 162-179) with:
+
+```python
+_ROUTING_KEYWORDS: dict[str, list[str]] = {
+    "design": [
+        "design", "look", "shape", "style", "form", "aesthetic", "appearance",
+        "layout", "concept", "idea", "propose", "suggest", "bracket", "mount",
+        "enclosure", "housing", "ergonomic", "profile", "contour",
+    ],
+    "engineering": [
+        "dimension", "tolerance", "material", "strength", "load", "stress",
+        "thickness", "wall", "fillet", "radius", "clearance",
+        "m2", "m3", "m4", "m5", "m6", "m8", "m10", "m12",
+        "aluminum", "steel", "brass", "titanium", "nylon",
+        "gear", "bearing", "flange", "heatsink", "fin", "rib",
+        "bolt", "screw", "thread", "torque", "deflection",
+        "hole", "bore", "shaft", "keyway", "spline",
+    ],
+    "cnc": [
+        "machine", "mill", "cnc", "manufacture", "machinable", "axis",
+        "tool", "fixture", "setup", "pocket", "undercut", "access",
+        "3-axis", "5-axis", "cost", "surface finish", "roughness",
+        "endmill", "drill", "tap", "chamfer tool", "deburr",
+        "setup count", "cycle time", "tolerance class",
+    ],
+    "cad": CAD_TRIGGER_KEYWORDS,
+}
+```
+
+- [ ] **Step 4: Run improved routing tests**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/test_prompts.py::TestRouteByKeywordsImproved -v`
+Expected: All 7 tests PASS
+
+- [ ] **Step 5: Run full test suite to check for regressions**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ -v`
+Expected: All tests PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add agents/prompts.py tests/test_prompts.py
+git commit -m "feat: expand keyword routing vocabulary for better agent selection"
+```
+
+---
+
+### Task 11: Run Full Test Suite and Verify
+
+- [ ] **Step 1: Run the complete test suite**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ -v --tb=short`
+Expected: All tests PASS. Target count: ~70+ tests.
+
+- [ ] **Step 2: Run with marker filter**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ -m "not requires_cadquery" -v`
+Expected: Pure-logic tests pass independently.
+
+- [ ] **Step 3: Check test coverage summary**
+
+Run: `cd /home/daniel/NeuralCAD && python -m pytest tests/ -v --tb=short 2>&1 | tail -5`
+Expected: Summary line showing total pass count.

docs/superpowers/specs/2026-04-08-multi-agent-chat-design.md

@@ -0,0 +1,390 @@
+# NeuralCAD Multi-Agent Chat Design
+
+## Context
+
+NeuralCAD currently uses a single-prompt flow: user describes a part, one LLM call generates CadQuery code, and the result renders in a 3D viewer. This works for simple parts but doesn't support iterative design refinement.
+
+The goal is to replace this with a **multi-agent chat experience** where 4 specialized AI agents (Design, Engineering, CNC, CAD Coder) collaborate with the user in a shared conversation to plan and refine a mechanical part before generating the 3D model. The user drives the conversation, agents contribute their expertise, and the user can request a 3D preview on demand.
+
+## Agent Definitions
+
+Four agents participate in a shared group chat. Each has a distinct role, color, and expertise:
+
+| Agent | ID | Color | Avatar | Role |
+|-------|----|-------|--------|------|
+| Design Agent | `design` | `#7c3aed` (purple) | DA | Industrial/product design: shape, form, aesthetics, ergonomics. Asks about intent, proposes form factors, considers user experience. |
+| Engineering Agent | `engineering` | `#00b4d8` (cyan) | EA | Structural/mechanical: dimensions, tolerances, materials, stress analysis, fastener specs (M3/M4/M6 clearance holes). |
+| CNC/Manufacturing Agent | `cnc` | `#00e676` (green) | CA | Manufacturability: tool access, wall thickness, pocket aspect ratios, axis requirements, fixturing, cost implications. |
+| CAD Coder Agent | `cad` | `#ffab40` (amber) | CC | Code generation: takes the agreed design and produces CadQuery Python code. Only responds when a preview is requested. |
+
+## Orchestration Architecture
+
+### Hybrid Approach: CrewAI Agents + Custom Orchestrator
+
+Use **CrewAI** for agent definitions (roles, goals, backstories) and the `BaseLLM` adapter pattern, but implement **two orchestration modes**:
+
+#### Single-Call Mode (Gemini Free Tier / Mock)
+
+One LLM call per user turn. The system prompt contains all agent personas and routing rules. The LLM returns a structured JSON response:
+
+```json
+{
+  "agents": [
+    {"id": "design", "message": "For an MG996R servo, I'd suggest an L-bracket..."},
+    {"id": "engineering", "message": "3mm wall thickness in aluminum 6061..."}
+  ]
+}
+```
+
+The orchestrator system prompt instructs the LLM to:
+- Analyze the user's message and conversation context
+- Select 1-3 relevant agents to respond (never all four unless appropriate)
+- Generate each agent's response in character
+- Only include the `cad` agent when the user explicitly requests a preview
+- When `cad` responds, include a `code` field with valid CadQuery Python
+
+If the user @mentions specific agents, the system prompt is modified to only include those agents.
+
+**Fallback**: If JSON parsing fails, use rule-based keyword matching to select agents and re-call the LLM with a simpler prompt for just those agents.
+
+#### Multi-Call Mode (Anthropic / OpenAI)
+
+CrewAI's hierarchical process with a manager agent. Each agent gets its own LLM call with focused context. The manager routes based on conversation state. Better quality but uses 2-4 API calls per turn.
+
+#### Mode Selection
+
+| Backend | Mode | Reason |
+|---------|------|--------|
+| `mock` | Template-based | No LLM call. Returns canned agent responses based on keyword matching. For the CAD Coder agent, delegates to the existing MockBackend which generates CadQuery code from prompt parsing. Useful for UI development and demos without API keys. |
+| `gemini` | Single-call | Free tier rate limits (15 RPM) |
+| `anthropic` | Multi-call | Paid API, better quality |
+| `openai` | Multi-call | Paid API, better quality |
+
+### @Mention System
+
+Users can direct messages to specific agents by typing `@design`, `@engineering`, `@cnc`, or `@cad` in their message.
+
+- Frontend parses @mentions from the message text before sending
+- @mentions are sent as a `mentions` array in the API request
+- When mentions are present:
+  - Single-call mode: system prompt only includes mentioned agents' personas
+  - Multi-call mode: only mentioned agents are activated in the crew
+- When no mentions: orchestrator decides which agents respond
+- `@cad` triggers CAD code generation (same as clicking the preview button)
+
+### Agent Prompt Structure
+
+Each agent has:
+- **System persona**: role description, expertise, communication style
+- **Conversation context**: last N messages from the chat history
+- **User message**: the current message with @mention context
+
+The CAD Coder agent additionally receives:
+- The full CadQuery system prompt (from `cadquery_system_prompt.py`)
+- Few-shot examples of CadQuery code
+- A summary of design decisions from the conversation so far
+
+## Chat API
+
+### Endpoint: `POST /api/chat`
+
+**Request:**
+```json
+{
+  "history": [
+    {"role": "user", "content": "I need a servo bracket"},
+    {"role": "design", "content": "What type of servo?"},
+    {"role": "user", "content": "MG996R, for a camera gimbal"}
+  ],
+  "message": "Make it 60mm wide with M4 base mounting",
+  "mentions": [],
+  "backend": "gemini"
+}
+```
+
+**Response:**
+```json
+{
+  "responses": [
+    {
+      "agent_id": "design",
+      "agent_name": "Design Agent",
+      "message": "L-bracket with servo pocket on vertical face...",
+      "color": "#7c3aed",
+      "avatar": "DA"
+    },
+    {
+      "agent_id": "engineering",
+      "agent_name": "Engineering Agent",
+      "message": "3mm walls, 5mm fillet on the L-bend...",
+      "color": "#00b4d8",
+      "avatar": "EA"
+    }
+  ],
+  "preview": null
+}
+```
+
+**Response with preview (when CAD Coder responds):**
+```json
+{
+  "responses": [
+    {
+      "agent_id": "cad",
+      "agent_name": "CAD Coder",
+      "message": "Model generated successfully.",
+      "color": "#ffab40",
+      "avatar": "CC",
+      "code": "import cadquery as cq\nresult = cq.Workplane('XY')..."
+    }
+  ],
+  "preview": {
+    "part_name": "servo_bracket",
+    "stl_url": "/api/models/servo_bracket.stl",
+    "step_url": "/api/models/servo_bracket.step",
+    "execution": {
+      "success": true,
+      "volume_mm3": 4230.5,
+      "bounding_box_mm": [60.0, 43.0, 25.0],
+      "face_count": 34,
+      "edge_count": 52
+    },
+    "validation": {
+      "machinable": true,
+      "axis_recommendation": "3-axis",
+      "issues": []
+    }
+  }
+}
+```
+
+### State Management
+
+- **Stateless backend**: frontend sends full conversation history with each request
+- **Backend truncation**: history truncated to last 30 messages to stay within token limits
+- **No sessions**: no server-side session storage needed
+- **Gallery persistence**: saved models stored in the `output/` directory with metadata JSON files
+
+### Existing Endpoints (Preserved)
+
+- `GET /api/models` — list generated models
+- `GET /api/models/{name}.stl` — download STL
+- `GET /api/models/{name}.step` — download STEP
+- `GET /api/capabilities` — server status
+
+### New Endpoint: `POST /api/report`
+
+Generates a design report document. Requires conversation history since the backend is stateless.
+
+**Request:**
+```json
+{
+  "part_name": "servo_bracket",
+  "history": [...],
+  "backend": "gemini"
+}
+```
+
+The LLM summarizes the conversation into a report containing:
+- Design decisions extracted from conversation
+- Final dimensions and specifications
+- CNC validation results and axis recommendation
+- Agent recommendations summary
+
+For `mock` backend, the report is assembled from the last CAD Coder response metadata without an LLM call.
+
+## Frontend Design
+
+### Layout: Fullscreen 3D Viewer + Slide-out Chat
+
+The 3D viewer occupies the **entire viewport** as the primary element. The chat panel slides in/out from the right side.
+
+```
++--[TopBar: Logo | Backend Toggle | Status]------------------+
+|                                                    |  CHAT  |
+|                                                    | PANEL  |
+|              FULLSCREEN 3D VIEWER                  | (340px)|
+|              (Three.js WebGL)                      |        |
+|                                                    | [msgs] |
+|  [Geo Stats]                         [CNC Badge]  | [msgs] |
+|                                                    | [msgs] |
+|                                                    |--------|
+|  [STEP] [STL] [Report]                             |[input] |
++----------------------------------------------------+--------+
+```
+
+### 3D Viewer
+
+- Same Three.js setup as current (STLLoader, OrbitControls, MeshPhongMaterial)
+- Fullscreen, edge-to-edge behind the chat panel
+- Semi-transparent overlays for geo stats (top-left), CNC badge (top-right of viewer area), downloads (bottom-left)
+- Empty state shows a subtle prompt: "Start a conversation to design your part"
+- When model is loaded: auto-centers, fits camera to bounding box, slow auto-rotate when idle
+
+### Chat Panel
+
+- **Width**: 340px, slides in from right
+- **Background**: semi-transparent (`rgba(10,14,20,0.92)`) with `backdrop-filter: blur(16px)` so the 3D model is visible behind
+- **Collapse/expand**: toggle button (chevron) in chat header, or floating pill at bottom center when collapsed
+- **Agent dots**: row of 4 colored dots in the header showing active agents
+
+#### Message Rendering
+
+- **User messages**: right-aligned, dark blue bubble (`#1a2a3a`), rounded corners
+- **Agent messages**: left-aligned with colored avatar circle (24px), agent label above message text in agent's color
+- **CAD Coder messages**: distinct background (`rgba(255,171,64,0.08)`) with "View CadQuery code" link
+
+#### Input Area
+
+- Text input with placeholder "Type your message..."
+- **@mention autocomplete**: typing `@` shows a dropdown with agent names, selecting inserts `@design` etc.
+- **Preview button** (eye icon, amber `#ffab40`): triggers CAD Coder to generate 3D model from current conversation
+- **Send button** (arrow icon, cyan `#00b4d8`): sends the message
+- **Ctrl/Cmd+Enter**: keyboard shortcut to send
+
+#### Quick Examples
+
+On first load (empty chat), show example conversation starters as clickable chips:
+- "Design a mounting bracket for an MG996R servo"
+- "I need a spur gear with 20 teeth"
+- "Create a heatsink for a 30mm cylinder"
+- "Design a pipe flange with M8 bolt holes"
+
+These insert the text into the chat input and auto-send.
+
+### Gallery
+
+- Accessed via a button in the top bar (not a tab)
+- Opens as a modal/dropdown overlay
+- Shows previously generated models as cards with thumbnail, name, face count, CNC status
+- Click to load model into the 3D viewer
+
+### Backend Toggle
+
+- Same as current: MOCK / GEMINI / CLAUDE radio buttons in the top bar
+- Changing backend affects which orchestration mode is used (single-call vs multi-call)
+
+## Refactored File Structure
+
+```
+NeuralCAD/
+├── agents/
+│   ├── __init__.py
+│   ├── definitions.py          # CrewAI Agent + Task definitions for all 4 agents
+│   ├── orchestrator.py         # Single-call JSON orchestrator (Gemini/Mock mode)
+│   ├── crew_orchestrator.py    # Multi-call CrewAI hierarchical process (Anthropic/OpenAI)
+│   ├── llm_adapter.py          # CrewAI BaseLLM wrapper around LLMBackend
+│   └── prompts.py              # Agent system prompts, personas, routing rules
+├── core/
+│   ├── __init__.py
+│   ├── backends.py             # LLMBackend base + AnthropicBackend, OpenAIBackend,
+│   │                           #   GeminiBackend, MockBackend (extracted from pipeline.py)
+│   ├── executor.py             # Sandboxed CadQuery execution (from code_executor.py)
+│   ├── validator.py            # CNC validation (from cnc_validator.py)
+│   ├── cadquery_prompts.py     # CadQuery system prompt + few-shot examples
+│   │                           #   (from cadquery_system_prompt.py)
+│   └── pipeline.py             # run_pipeline() for CAD generation
+│   │                           #   (simplified, called by CAD Coder agent)
+├── server/
+│   ├── __init__.py
+│   ├── web.py                  # FastAPI app, static file serving (from web_server.py)
+│   ├── mcp.py                  # MCP server + tools (from mcp_server.py)
+│   └── routes.py               # /api/chat, /api/report endpoints
+├── web/
+│   └── index.html              # Complete rewrite: fullscreen 3D viewer + slide-out chat
+├── pyproject.toml              # + crewai dependency
+├── Dockerfile                  # Updated for new structure
+├── docker-compose.yml          # Same services, updated paths
+└── entrypoint.sh               # Updated entry point
+```
+
+### Key Refactoring Notes
+
+- `pipeline.py` (922 lines) is split into `core/backends.py` (LLM backends), `core/pipeline.py` (run_pipeline), and `agents/` (orchestration)
+- `code_executor.py` → `core/executor.py` (unchanged logic)
+- `cnc_validator.py` → `core/validator.py` (unchanged logic)
+- `cadquery_system_prompt.py` → `core/cadquery_prompts.py` (unchanged logic)
+- `web_server.py` → `server/web.py` + `server/routes.py`
+- `mcp_server.py` → `server/mcp.py` (add `chat_turn` MCP tool for Claude Desktop)
+- `web/index.html` → complete rewrite
+
+## Data Flow: Chat Turn
+
+```
+1. User types message in chat UI
+2. Frontend parses @mentions from message text
+3. POST /api/chat { history, message, mentions, backend }
+         |
+4. Backend selects orchestration mode:
+   ├── gemini/mock → Single-call orchestrator
+   │     ├── Build system prompt with agent personas + routing rules
+   │     ├── Include conversation history (last 30 msgs)
+   │     ├── If @mentions: only include mentioned agent personas
+   │     ├── LLMBackend.generate(messages) → JSON string
+   │     ├── Parse JSON → list of agent responses
+   │     └── Fallback: keyword routing + simpler re-call if JSON fails
+   │
+   └── anthropic/openai → CrewAI hierarchical process
+         ├── Manager agent routes to relevant agents
+         ├── Each agent gets own LLM call via NeuralCADLLMAdapter
+         └── Collect responses from all activated agents
+         |
+5. If CAD Coder agent responded with code:
+   ├── execute_cadquery(code) → ExecutionResult
+   ├── export_step() + export_stl() → files in output/
+   ├── validate_for_cnc() → CNCValidationResult
+   └── Build preview object with URLs and metadata
+         |
+6. Return JSON response → Frontend renders agent messages
+         |
+7. If preview present:
+   ├── Load STL into Three.js viewer
+   ├── Show geo stats overlay
+   ├── Show CNC badge
+   └── Enable download buttons
+```
+
+## MCP Compatibility
+
+Add a new `chat_turn` MCP tool alongside existing tools:
+
+```python
+@mcp.tool()
+async def chat_turn(
+    message: str,
+    history: list[dict] | None = None,
+    mentions: list[str] | None = None,
+    backend: str = "gemini"
+) -> dict:
+    """Multi-agent chat turn for collaborative CAD design."""
+```
+
+Existing MCP tools (`generate_cnc_model`, `validate_cnc_model`, `execute_cadquery_code`, `list_models`) remain unchanged for backward compatibility with Claude Desktop.
+
+## Verification Plan
+
+### Unit Tests
+- Test single-call orchestrator JSON parsing with valid and malformed responses
+- Test @mention parsing in frontend
+- Test keyword-based fallback routing
+- Test LLM adapter wraps LLMBackend correctly
+
+### Integration Tests
+- Full chat turn: user message → agent responses → verify correct agents selected
+- Preview generation: chat with `@cad` → verify STL/STEP files created
+- Backend switching: verify single-call mode for Gemini, multi-call for Anthropic
+- Conversation history truncation at 30 messages
+
+### Manual Testing
+- Open web UI, start a conversation about a servo bracket
+- Verify agents respond with appropriate expertise
+- Use @mentions to direct messages to specific agents
+- Click preview button → verify 3D model loads
+- Download STEP and STL files
+- Collapse/expand chat panel
+- Test with Gemini free tier (rate limit behavior)
+- Test quick example conversation starters
+
+### MCP Testing
+- Call `chat_turn` tool from Claude Desktop
+- Verify existing MCP tools still work

docs/superpowers/specs/2026-04-08-uv-docker-deploy-design.md

@@ -0,0 +1,187 @@
+# NeuralCAD — uv, Docker, and HF Spaces Deployment
+
+## Overview
+
+Set up astral uv as the Python package manager, containerize with Docker, and deploy the full pipeline (web server + MCP CAD server) to Hugging Face Spaces for a free investor demo.
+
+## 1. uv Setup
+
+### pyproject.toml
+
+Replace `requirements.txt` with `pyproject.toml` as the single source of truth for dependencies:
+
+```toml
+[project]
+name = "neuralcad"
+version = "1.0.0"
+description = "Text-to-CNC pipeline: natural language to machinable 3D models"
+requires-python = ">=3.10"
+dependencies = [
+    "cadquery>=2.7.0",
+    "cadquery-ocp>=7.8.0",
+    "numpy>=1.24.0",
+    "trimesh>=4.0.0",
+    "anthropic>=0.25.0",
+    "openai>=1.30.0",
+    "mcp>=1.0.0",
+    "fastapi>=0.110.0",
+    "uvicorn>=0.29.0",
+    "python-multipart>=0.0.9",
+]
+
+[dependency-groups]
+dev = ["ruff", "pytest"]
+```
+
+### Lockfile
+
+Run `uv lock` to generate `uv.lock` for reproducible installs. Commit `uv.lock` to git.
+
+### Workflow
+
+- `uv sync` — install all dependencies
+- `uv run python web_server.py` — run web server
+- `uv run python mcp_server.py --transport sse` — run MCP server
+- `uv sync --group dev` — install dev tools
+
+### Migration
+
+- `requirements.txt` is kept for backward compatibility but marked with a comment pointing to `pyproject.toml` as the source of truth.
+
+## 2. Docker
+
+### Dockerfile (multi-stage)
+
+**Stage 1: builder**
+- Base: `python:3.11-slim`
+- Install uv via the official installer
+- Copy `pyproject.toml` + `uv.lock`
+- Run `uv sync --frozen --no-dev` to install dependencies into `.venv`
+- This stage is cached — only rebuilds when dependencies change
+
+**Stage 2: runtime**
+- Base: `python:3.11-slim`
+- Copy `.venv` from builder (contains all installed packages)
+- Copy application source code
+- Set `PATH` to include `.venv/bin`
+- Expose port 7860 (HF Spaces convention)
+- Run `entrypoint.sh`
+
+### entrypoint.sh
+
+```bash
+#!/bin/bash
+# Start MCP CAD server in background
+python mcp_server.py --transport sse --port 8000 &
+
+# Wait for MCP server to be ready
+sleep 3
+
+# Start web server in foreground on HF Spaces port
+export MCP_SERVER_URL=http://localhost:8000/sse
+exec python web_server.py --host 0.0.0.0 --port ${PORT:-7860}
+```
+
+### docker-compose.yml (local dev)
+
+Two services for development:
+
+```yaml
+services:
+  mcp-server:
+    build: .
+    command: python mcp_server.py --transport sse --port 8000
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./output:/app/output
+
+  web:
+    build: .
+    command: python web_server.py --host 0.0.0.0 --port 5000
+    ports:
+      - "5000:5000"
+    environment:
+      MCP_SERVER_URL: http://mcp-server:8000/sse
+    depends_on:
+      - mcp-server
+    volumes:
+      - ./output:/app/output
+```
+
+### .dockerignore
+
+```
+.git
+.gitignore
+__pycache__
+*.pyc
+output/
+.superpowers/
+docs/
+*.md
+.env
+```
+
+## 3. Hugging Face Spaces Deployment
+
+### Space Configuration
+
+HF Spaces reads metadata from a YAML header in `README.md`:
+
+```yaml
+---
+title: NeuralCAD
+emoji: ⚙️
+colorFrom: blue
+colorTo: cyan
+sdk: docker
+app_port: 7860
+---
+```
+
+This tells HF to build the Dockerfile and route traffic to port 7860.
+
+### How it works
+
+1. Push repo to HF (or link GitHub repo)
+2. HF builds the Docker image
+3. Container starts: `entrypoint.sh` launches MCP + web servers
+4. Public URL: `https://callmedaniel-neuralcad.hf.space`
+
+### Free tier constraints
+
+- 16GB RAM, 2 vCPU (sufficient for CadQuery)
+- 50GB disk (sufficient for OpenCascade)
+- Sleeps after ~15min inactivity
+- Wakes on HTTP request (~30s cold start for CadQuery container)
+- No persistent storage across rebuilds (output/ is ephemeral)
+
+### Environment variables
+
+For live LLM generation (optional), set as HF Space secrets:
+- `ANTHROPIC_API_KEY` — enables Claude backend
+- `OPENAI_API_KEY` — enables GPT-4o backend
+
+Mock backend always works without API keys.
+
+## New/Modified Files
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `pyproject.toml` | Create | Project metadata + dependencies for uv |
+| `uv.lock` | Generate | Lockfile (via `uv lock`) |
+| `Dockerfile` | Create | Multi-stage production build |
+| `docker-compose.yml` | Create | Local dev with two services |
+| `.dockerignore` | Create | Exclude files from Docker build |
+| `entrypoint.sh` | Create | Container startup (MCP bg + web fg) |
+| `README.md` | Modify | Add HF Spaces YAML header |
+| `.gitignore` | Modify | Add `.venv/`, `uv.lock` pattern notes |
+| `requirements.txt` | Modify | Add comment pointing to pyproject.toml |
+
+## Verification
+
+1. **uv**: `uv sync && uv run python -c "import cadquery; print('ok')"` — deps install and CadQuery loads
+2. **Docker local**: `docker compose up --build` → open http://localhost:5000 → click quick example → 3D model renders
+3. **Docker single**: `docker build -t neuralcad . && docker run -p 7860:7860 neuralcad` → open http://localhost:7860
+4. **HF Spaces**: push to HF repo → Space builds → open public URL → demo works

docs/superpowers/specs/2026-04-08-web-demo-design.md

@@ -0,0 +1,178 @@
+# NeuralCAD Web Demo — Design Spec
+
+## Overview
+
+A web-based investor demo for the NeuralCAD text-to-CNC pipeline. Users type a part description, the system generates CadQuery code via an LLM, executes it, validates for CNC manufacturability, and displays the resulting 3D model in an interactive viewer — all in the browser.
+
+## Architecture
+
+```
+Browser (index.html)
+    │ fetch() REST
+    ▼
+FastAPI web server (web_server.py, port 5000)
+    │ MCP SSE client
+    ▼
+MCP CAD server (mcp_server.py --transport sse, port 8000)
+    │ Python imports
+    ▼
+Pipeline (pipeline.py → code_executor → cnc_validator)
+```
+
+**Two separate processes:**
+1. `mcp_server.py --transport sse --port 8000` — the CAD engine
+2. `web_server.py` — FastAPI server that proxies browser requests to the MCP server and serves the frontend
+
+The web server uses the `mcp` Python SDK's SSE client to call MCP tools on the CAD server. This decouples the web layer from the CAD environment (CadQuery/OpenCascade).
+
+## New Files
+
+| File | Purpose |
+|------|---------|
+| `web_server.py` | FastAPI app: REST endpoints, MCP SSE client, static file serving |
+| `web/index.html` | Single-file frontend: Tailwind CDN + Three.js CDN + vanilla JS |
+
+No changes to existing pipeline files.
+
+## API Endpoints (web_server.py)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET /` | Serves `web/index.html` | |
+| `POST /api/generate` | `{ prompt, part_name?, backend? }` → calls MCP `generate_cnc_model` tool → returns JSON result | |
+| `POST /api/generate-image` | `{ image (multipart), text_hint?, part_name?, backend? }` → calls MCP `generate_from_image` tool → returns JSON result | |
+| `POST /api/validate` | `{ code, part_name? }` → calls MCP `validate_cnc_model` tool → returns JSON result | |
+| `GET /api/models` | Calls MCP `list_models` tool → returns JSON list | |
+| `GET /api/models/{name}.stl` | Serves the STL file from `output/` directory so Three.js can load it | |
+| `GET /api/models/{name}.step` | Serves the STEP file for download | |
+| `GET /api/capabilities` | Reads MCP `text-to-cnc://capabilities` resource → returns available backends | |
+
+### MCP Client Integration
+
+The web server connects to the MCP SSE server at startup. Each API endpoint translates the REST request into an MCP `call_tool` invocation:
+
+```python
+# Pseudocode
+async def generate(request):
+    result = await mcp_client.call_tool("generate_cnc_model", {
+        "prompt": request.prompt,
+        "backend": request.backend or "mock",
+        "part_name": request.part_name or "",
+    })
+    return JSONResponse(json.loads(result))
+```
+
+### Configuration
+
+- `MCP_SERVER_URL` env var (default: `http://localhost:8000/sse`) — MCP SSE endpoint
+- The MCP server URL is configurable so the CAD server can run on a different host
+
+## Frontend (web/index.html)
+
+### Layout: Stacked Hero
+
+Single HTML file, no build step. Dependencies via CDN:
+- Tailwind CSS (styling)
+- Three.js + STLLoader + OrbitControls (3D viewer)
+- highlight.js (code syntax highlighting, optional)
+
+### Page Structure
+
+1. **Top Bar** — NeuralCAD logo, backend toggle (Mock / API), version
+2. **Hero 3D Viewer** (~60% viewport height)
+   - Three.js scene with dark background and subtle grid
+   - OrbitControls for rotate/zoom/pan
+   - Geometry stats overlay (volume, faces, edges, bounding box)
+   - CNC status badge (machinable/not, axis recommendation)
+   - STEP/STL download buttons
+3. **Bottom Tabbed Panel** (~40% viewport height)
+   - **Generate tab**: text input, "Generate Model" button, image upload button, quick example buttons (bracket, gear, default)
+   - **Code tab**: syntax-highlighted CadQuery code output
+   - **Validation tab**: CNC manufacturability report (issues list, severity icons)
+   - **Gallery tab**: previously generated models (click to load in viewer)
+
+### Interaction Flow
+
+1. User types a part description (or clicks a quick example)
+2. Clicks "Generate Model"
+3. Frontend shows loading state (spinner in 3D viewer, "Generating..." on button)
+4. `POST /api/generate` with prompt + selected backend
+5. Response arrives with: generated_code, execution results, validation, exported_files
+6. Frontend updates all panels:
+   - 3D viewer loads STL from `/api/models/{name}.stl`
+   - Code tab shows generated CadQuery code
+   - Validation tab shows CNC report
+   - Geometry overlay updates with volume/faces/edges
+   - Download buttons activate with STEP/STL links
+7. Model is added to Gallery tab
+
+### Image Upload Flow
+
+1. User clicks the image/camera button
+2. File picker opens (accept: image/*)
+3. Selected image is sent as multipart form to `POST /api/generate-image`
+4. Same response handling as text generation
+
+### Quick Examples
+
+Pre-defined prompts that demonstrate the system reliably (using mock backend):
+- "A mounting bracket with four M6 bolt holes" → bracket mock
+- "A spur gear with 20 teeth" → gear mock
+- "A parametric box with holes and fillets" → default mock
+
+### Theming
+
+Dark theme (matches the CAD/engineering aesthetic):
+- Background: near-black (#0a0a1a)
+- Panels: dark navy (#12122a)
+- Accent: blue (#3b82f6)
+- Success: green (#4ade80)
+- Text: light gray (#e2e8f0) / muted (#8b8ba7)
+
+### 3D Viewer Details
+
+- **Renderer**: Three.js WebGLRenderer with antialiasing
+- **Loader**: STLLoader fetches from `/api/models/{name}.stl`
+- **Material**: MeshPhongMaterial with blue-gray tone, slight metallic feel
+- **Lighting**: Ambient + two directional lights for good depth perception
+- **Controls**: OrbitControls (drag = rotate, scroll = zoom, right-drag = pan)
+- **Camera**: Auto-fit to bounding box after model load
+- **Background**: Dark gradient with faint grid overlay
+
+## Startup
+
+```bash
+# Terminal 1: Start the CAD server
+python mcp_server.py --transport sse --port 8000
+
+# Terminal 2: Start the web server
+python web_server.py
+# → Serving at http://localhost:5000
+```
+
+Or a convenience script:
+```bash
+python web_server.py --start-mcp
+# Launches MCP server as subprocess, then starts FastAPI
+```
+
+## Dependencies (additions to requirements.txt)
+
+```
+fastapi>=0.110.0
+uvicorn>=0.29.0
+```
+
+The `mcp` package (already in requirements.txt) includes the SSE client via `httpx` and `httpx-sse` as transitive dependencies. No additional SSE libraries needed.
+
+## Verification
+
+1. Start MCP server: `python mcp_server.py --transport sse --port 8000`
+2. Start web server: `python web_server.py`
+3. Open `http://localhost:5000` in browser
+4. Click "Mounting bracket" quick example → 3D model appears in viewer
+5. Switch to Code tab → CadQuery code is displayed
+6. Switch to Validation tab → CNC report shows "Machinable"
+7. Click STEP/STL download buttons → files download
+8. Toggle backend to "API", type a custom prompt, click Generate → live LLM generation works
+9. Upload an image → image-to-model flow works

entrypoint.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -e
+
+echo "=== NeuralCAD Container Starting ==="
+
+# Start MCP CAD server in background
+echo "Starting MCP CAD server on port 8000..."
+python -m server.mcp --transport sse --port 8000 &
+MCP_PID=$!
+
+# Wait for MCP server to be ready
+sleep 3
+
+if ! kill -0 $MCP_PID 2>/dev/null; then
+    echo "ERROR: MCP server failed to start"
+    exit 1
+fi
+
+echo "MCP server running (PID $MCP_PID)"
+
+# Start web server in foreground
+export MCP_SERVER_URL=http://localhost:8000/sse
+PORT=${PORT:-7860}
+echo "Starting web server on port $PORT..."
+exec python -m server.web --host 0.0.0.0 --port "$PORT"

pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "neuralcad"
+version = "1.0.0"
+description = "Text-to-CNC pipeline: natural language to machinable 3D models"
+requires-python = ">=3.10"
+dependencies = [
+    "cadquery>=2.7.0",
+    "cadquery-ocp>=7.8.0",
+    "numpy>=1.24.0",
+    "trimesh>=4.0.0",
+    "anthropic>=0.25.0",
+    "openai>=1.30.0",
+    "google-genai>=1.0.0",
+    "crewai>=0.100.0",
+    "mcp>=1.0.0",
+    "fastapi>=0.110.0",
+    "uvicorn>=0.29.0",
+    "python-multipart>=0.0.9",
+]
+
+[dependency-groups]
+dev = ["ruff", "pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = [
+    "requires_cadquery: marks tests that need CadQuery installed",
+]

requirements.txt

@@ -1,7 +1,13 @@
+# Dependency source of truth is pyproject.toml — use `uv sync` to install.
+# This file is kept for environments that don't use uv.
 cadquery>=2.7.0
 cadquery-ocp>=7.8.0
 numpy>=1.24.0
 trimesh>=4.0.0
 anthropic>=0.25.0
 openai>=1.30.0
+google-genai>=1.0.0
 mcp>=1.0.0
+fastapi>=0.110.0
+uvicorn>=0.29.0
+python-multipart>=0.0.9

mcp_server.py → server/mcp.py

@@ -11,8 +11,8 @@ Tools:
   - list_models:        List previously generated models in the output dir
 
 Usage:
-  python mcp_server.py                    # stdio transport (default)
-  python mcp_server.py --transport sse    # SSE transport on port 8000
+  python -m server.mcp                    # stdio transport (default)
+  python -m server.mcp --transport sse    # SSE transport on port 8000
 """
 
 import json
@@ -22,12 +22,9 @@ from pathlib import Path
 
 from mcp.server.fastmcp import FastMCP
 
-# Ensure the project modules are importable
-sys.path.insert(0, str(Path(__file__).parent))
-
-from cadquery_system_prompt import build_messages, CADQUERY_SYSTEM_PROMPT
-from code_executor import ExecutionResult, execute_cadquery, export_all, sanitize_code
-from cnc_validator import validate_for_cnc, CNCValidationResult
+from core.cadquery_prompts import build_messages, CADQUERY_SYSTEM_PROMPT
+from core.executor import ExecutionResult, execute_cadquery, export_all, sanitize_code
+from core.validator import validate_for_cnc, CNCValidationResult
 
 # ── Server Setup ──────────────────────────────────────────────────────────
 
@@ -40,7 +37,7 @@ mcp = FastMCP(
     ),
 )
 
-DEFAULT_OUTPUT_DIR = Path(__file__).parent / "output"
+DEFAULT_OUTPUT_DIR = Path(__file__).parent.parent / "output"
 DEFAULT_OUTPUT_DIR.mkdir(exist_ok=True)
 
 
@@ -48,12 +45,16 @@ DEFAULT_OUTPUT_DIR.mkdir(exist_ok=True)
 
 def get_backend(backend_name: str = "mock"):
     """Get the appropriate LLM backend."""
-    from pipeline import MockBackend, AnthropicBackend, OpenAIBackend
+    from core.backends import MockBackend, AnthropicBackend, OpenAIBackend, GeminiBackend, NeuralCADBackend
 
-    if backend_name == "anthropic" and os.environ.get("ANTHROPIC_API_KEY"):
+    if backend_name == "neural":
+        return NeuralCADBackend()
+    elif backend_name == "anthropic" and os.environ.get("ANTHROPIC_API_KEY"):
         return AnthropicBackend()
     elif backend_name == "openai" and os.environ.get("OPENAI_API_KEY"):
         return OpenAIBackend()
+    elif backend_name == "gemini" and os.environ.get("GEMINI_API_KEY"):
+        return GeminiBackend()
     else:
         return MockBackend()
 
@@ -91,7 +92,7 @@ def generate_cnc_model(
         - validation: CNC manufacturability analysis
         - exported_files: Paths to generated STEP/STL files
     """
-    from pipeline import run_pipeline
+    from core.pipeline import run_pipeline
 
     if not part_name:
         part_name = prompt[:40].strip().replace(" ", "_").lower()
@@ -287,6 +288,165 @@ def list_models(output_dir: str = "") -> str:
     }, indent=2)
 
 
+# ── Tool: generate_from_image ───────────────────────────────────────────
+
+@mcp.tool()
+def generate_from_image(
+    image_path: str,
+    text_hint: str = "",
+    part_name: str = "",
+    backend: str = "anthropic",
+    max_retries: int = 2,
+) -> str:
+    """
+    Generate a CNC-machinable 3D model from a photo or sketch image.
+
+    Sends the image to a vision-capable LLM (Claude or GPT-4o) along with
+    the CadQuery system prompt to generate code, then executes, validates,
+    and exports the result.
+
+    Args:
+        image_path: Path to an image file (photo, sketch, or CAD screenshot).
+        text_hint: Optional text to guide generation alongside the image.
+                   Example: "This is a mounting bracket — add M6 bolt holes"
+        part_name: Optional name for the part (used in filenames).
+        backend: LLM backend: "anthropic" or "openai". Must support vision.
+        max_retries: Number of retry attempts if code execution fails (0-3).
+
+    Returns:
+        JSON string with generation results including generated code,
+        execution status, validation, and exported file paths.
+    """
+    if not Path(image_path).exists():
+        return json.dumps({"success": False, "error": f"Image not found: {image_path}"})
+
+    if not part_name:
+        part_name = Path(image_path).stem
+
+    llm_backend = get_backend(backend)
+
+    # Build prompt with optional text hint
+    prompt = "Generate CadQuery code for the mechanical part shown in this image."
+    if text_hint:
+        prompt += f"\n\nAdditional context: {text_hint}"
+
+    messages = build_messages(prompt)
+
+    # Use vision-capable generate_with_image
+    generated_code = llm_backend.generate_with_image(messages, image_path)
+
+    # Run through standard execution/validation/export
+    exec_result = execute_cadquery(generated_code)
+    retry_count = 0
+
+    while not exec_result.success and retry_count < min(max_retries, 3):
+        retry_count += 1
+        error_feedback = (
+            f"The previous code failed with this error:\n"
+            f"```\n{exec_result.error}\n```\n\n"
+            f"Please fix the code and return only the corrected Python code."
+        )
+        retry_messages = build_messages(error_feedback)
+        generated_code = llm_backend.generate_with_image(retry_messages, image_path)
+        exec_result = execute_cadquery(generated_code)
+
+    response = {
+        "success": exec_result.success,
+        "image_path": image_path,
+        "text_hint": text_hint,
+        "part_name": part_name,
+        "backend": backend,
+        "retries": retry_count,
+        "generated_code": generated_code,
+        "execution": {
+            "success": exec_result.success,
+            "volume_mm3": exec_result.volume,
+            "bounding_box_mm": list(exec_result.bounding_box) if exec_result.bounding_box else [],
+            "face_count": exec_result.face_count,
+            "edge_count": exec_result.edge_count,
+            "error": exec_result.error,
+        },
+    }
+
+    if exec_result.success:
+        validation = validate_for_cnc(exec_result.result, part_name=part_name)
+        response["validation"] = {
+            "machinable": validation.machinable,
+            "axis_recommendation": validation.axis_recommendation,
+            "error_count": validation.error_count,
+            "warning_count": validation.warning_count,
+            "issues": [
+                {"severity": i.severity, "category": i.category, "message": i.message}
+                for i in validation.issues
+            ],
+        }
+
+        base_path = DEFAULT_OUTPUT_DIR / part_name
+        try:
+            exported = export_all(exec_result.result, base_path)
+            response["exported_files"] = {fmt: str(p) for fmt, p in exported.items()}
+        except Exception as e:
+            response["export_error"] = str(e)
+
+    return json.dumps(response, indent=2)
+
+
+# ── Tool: chat_turn ─────────────────────────────────────────────────────
+
+@mcp.tool()
+def chat_turn(
+    message: str,
+    history: str = "[]",
+    mentions: str = "[]",
+    backend: str = "mock",
+) -> str:
+    """
+    Multi-agent chat turn for collaborative CAD design.
+
+    Send a message to the design team agents (Design, Engineering, CNC, CAD Coder).
+    Agents collaborate to help you design a mechanical part step by step.
+
+    Args:
+        message: Your message to the design team.
+                 Use @design, @engineering, @cnc, or @cad to address specific agents.
+        history: JSON string of previous messages. Format:
+                 [{"role": "user"|"agent", "agent_id": "design", "content": "..."}]
+        mentions: JSON string of agent IDs to address. Format: ["design", "engineering"]
+                  Empty list = auto-route based on message content.
+        backend: LLM backend: "mock", "gemini", "anthropic", "openai".
+
+    Returns:
+        JSON string with agent responses and optional 3D preview data.
+    """
+    import json as json_mod
+
+    from agents.orchestrator import get_orchestrator
+    from agents.crew_orchestrator import CrewOrchestrator
+    from agents.prompts import parse_mentions
+
+    history_list = json_mod.loads(history) if isinstance(history, str) else history
+    mentions_list = json_mod.loads(mentions) if isinstance(mentions, str) else mentions
+
+    # Parse @mentions from message if not provided
+    if not mentions_list:
+        message, mentions_list = parse_mentions(message)
+
+    mentions_or_none = mentions_list if mentions_list else None
+
+    if backend in ("anthropic", "openai"):
+        orchestrator = CrewOrchestrator(backend_name=backend, output_dir=DEFAULT_OUTPUT_DIR)
+    else:
+        orchestrator = get_orchestrator(backend, output_dir=DEFAULT_OUTPUT_DIR)
+
+    result = orchestrator.chat_turn(
+        message=message,
+        history=history_list,
+        mentions=mentions_or_none,
+    )
+
+    return json_mod.dumps(result, indent=2)
+
+
 # ── Resource: System prompt (for transparency) ───────────────────────────
 
 @mcp.resource("text-to-cnc://system-prompt")
@@ -298,11 +458,13 @@ def get_system_prompt() -> str:
 @mcp.resource("text-to-cnc://capabilities")
 def get_capabilities() -> str:
     """Server capabilities and configuration."""
-    backends = ["mock (always available)"]
+    backends = ["mock (always available)", "neural (local models — requires trained weights)"]
     if os.environ.get("ANTHROPIC_API_KEY"):
         backends.append("anthropic (API key detected)")
     if os.environ.get("OPENAI_API_KEY"):
         backends.append("openai (API key detected)")
+    if os.environ.get("GEMINI_API_KEY"):
+        backends.append("gemini (API key detected)")
 
     return json.dumps({
         "name": "text-to-cnc",

server/routes.py

@@ -0,0 +1,153 @@
+"""Chat API routes for multi-agent design conversation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from agents.orchestrator import get_orchestrator
+from agents.crew_orchestrator import CrewOrchestrator
+from agents.prompts import parse_mentions
+from agents.definitions import AGENTS
+
+router = APIRouter()
+
+OUTPUT_DIR = Path(__file__).parent.parent / "output"
+
+
+# ── Request / response models ─────────────────────────────────────────────
+
+
+class ChatMessage(BaseModel):
+    role: str  # "user" or "agent"
+    agent_id: str = ""
+    content: str = ""
+
+
+class ChatRequest(BaseModel):
+    message: str = Field(..., min_length=1)
+    history: list[ChatMessage] = Field(default_factory=list)
+    mentions: list[str] = Field(default_factory=list)
+    backend: str = "mock"
+    design_state: dict = Field(default_factory=dict)
+
+
+class ReportRequest(BaseModel):
+    part_name: str = "part"
+    history: list[ChatMessage] = Field(default_factory=list)
+    backend: str = "mock"
+
+
+# ── Endpoints ──────────────────────────────────────────────────────────────
+
+
+@router.post("/api/chat")
+async def chat(body: ChatRequest):
+    """Multi-agent chat turn."""
+    message = body.message.strip()
+
+    # Convert validated models back to dicts for the orchestrator
+    history = [m.model_dump() for m in body.history]
+    backend_name = body.backend
+
+    # Parse @mentions from message if not provided
+    raw_mentions = body.mentions
+    if not raw_mentions:
+        message, raw_mentions = parse_mentions(message)
+
+    mentions = raw_mentions if raw_mentions else None
+
+    # Select orchestrator based on backend
+    if backend_name in ("anthropic", "openai", "gemini"):
+        orchestrator = CrewOrchestrator(
+            backend_name=backend_name, output_dir=OUTPUT_DIR
+        )
+    else:
+        orchestrator = get_orchestrator(backend_name, output_dir=OUTPUT_DIR)
+
+    # Run chat turn
+    try:
+        result = orchestrator.chat_turn(
+            message=message,
+            history=history,
+            mentions=mentions,
+            design_state=body.design_state,
+        )
+        return JSONResponse(result)
+    except Exception as e:
+        return JSONResponse(
+            {"error": "An internal error occurred. Please try again."},
+            status_code=500,
+        )
+
+
+@router.post("/api/report")
+async def report(body: ReportRequest):
+    """Generate a design report from conversation history."""
+    part_name = body.part_name
+    history = [m.model_dump() for m in body.history]
+
+    # Build report from conversation
+    report_sections = [f"# Design Report: {part_name}\n"]
+
+    design_decisions = []
+    engineering_specs = []
+    cnc_notes = []
+
+    for msg in history:
+        agent_id = msg.get("agent_id", "")
+        content = msg.get("content", "")
+        if agent_id == "design":
+            design_decisions.append(content)
+        elif agent_id == "engineering":
+            engineering_specs.append(content)
+        elif agent_id == "cnc":
+            cnc_notes.append(content)
+
+    if design_decisions:
+        report_sections.append("## Design Decisions")
+        for d in design_decisions:
+            report_sections.append(f"- {d}")
+
+    if engineering_specs:
+        report_sections.append("\n## Engineering Specifications")
+        for s in engineering_specs:
+            report_sections.append(f"- {s}")
+
+    if cnc_notes:
+        report_sections.append("\n## Manufacturing Notes")
+        for n in cnc_notes:
+            report_sections.append(f"- {n}")
+
+    stl_path = OUTPUT_DIR / f"{part_name}.stl"
+    step_path = OUTPUT_DIR / f"{part_name}.step"
+
+    report_sections.append("\n## Exported Files")
+    report_sections.append(f"- STEP: {'Available' if step_path.exists() else 'Not generated'}")
+    report_sections.append(f"- STL: {'Available' if stl_path.exists() else 'Not generated'}")
+
+    return JSONResponse({
+        "part_name": part_name,
+        "report": "\n".join(report_sections),
+    })
+
+
+@router.get("/api/agents")
+async def list_agents():
+    """List available agents and their metadata."""
+    return JSONResponse({
+        "agents": [
+            {
+                "id": agent.id,
+                "name": agent.name,
+                "role": agent.role,
+                "color": agent.color,
+                "avatar": agent.avatar,
+            }
+            for agent in AGENTS.values()
+        ]
+    })

server/web.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+NeuralCAD Web Demo Server
+=========================
+FastAPI server that proxies REST requests to the MCP CAD server (SSE transport)
+and serves the web frontend.
+
+Usage:
+    # Start MCP server first:
+    python -m server.mcp --transport sse --port 8000
+
+    # Then start web server:
+    python -m server.web
+
+    # Or auto-launch MCP server:
+    python -m server.web --start-mcp
+
+    # Open http://localhost:5000
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, File, Form, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+
+from server.routes import router
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+# ── Config ───────────────────────────────────────────────────────────────
+
+MCP_SERVER_URL = os.environ.get("MCP_SERVER_URL", "http://localhost:8000/sse")
+OUTPUT_DIR = Path(__file__).parent.parent / "output"
+WEB_DIR = Path(__file__).parent.parent / "web"
+PORT = int(os.environ.get("WEB_PORT", "5000"))
+
+# ── MCP Client Management ───────────────────────────────────────────────
+
+_mcp_process = None
+
+
+async def call_mcp_tool(tool_name: str, arguments: dict) -> dict:
+    """Connect to MCP server, call a tool, return parsed JSON result."""
+    async with sse_client(url=MCP_SERVER_URL) as streams:
+        async with ClientSession(*streams) as session:
+            await session.initialize()
+            result = await session.call_tool(name=tool_name, arguments=arguments)
+            if result.content:
+                return json.loads(result.content[0].text)
+            return {"error": "Empty response from MCP server"}
+
+
+async def read_mcp_resource(uri: str) -> str:
+    """Connect to MCP server and read a resource."""
+    async with sse_client(url=MCP_SERVER_URL) as streams:
+        async with ClientSession(*streams) as session:
+            await session.initialize()
+            result = await session.read_resource(uri=uri)
+            if result.contents:
+                return result.contents[0].text
+            return "{}"
+
+
+def start_mcp_server(port: int = 8000):
+    """Launch mcp.py as a subprocess with SSE transport."""
+    global _mcp_process
+    mcp_script = Path(__file__).parent / "mcp.py"
+    _mcp_process = subprocess.Popen(
+        [sys.executable, str(mcp_script), "--transport", "sse", "--port", str(port)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    # Give it a moment to start
+    time.sleep(2)
+    if _mcp_process.poll() is not None:
+        stderr = _mcp_process.stderr.read().decode() if _mcp_process.stderr else ""
+        raise RuntimeError(f"MCP server failed to start: {stderr}")
+    print(f"  MCP server started (PID {_mcp_process.pid}) on port {port}")
+
+
+# ── FastAPI App ──────────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    OUTPUT_DIR.mkdir(exist_ok=True)
+    yield
+    global _mcp_process
+    if _mcp_process:
+        _mcp_process.terminate()
+        _mcp_process.wait()
+
+
+app = FastAPI(title="NeuralCAD Web Demo", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(router)
+
+
+# ── Routes ───────────────────────────────────────────────────────────────
+
+@app.get("/", response_class=HTMLResponse)
+async def index():
+    index_file = WEB_DIR / "index.html"
+    return HTMLResponse(index_file.read_text())
+
+
+@app.post("/api/generate")
+async def generate(body: dict):
+    result = await call_mcp_tool("generate_cnc_model", {
+        "prompt": body.get("prompt", ""),
+        "part_name": body.get("part_name", ""),
+        "backend": body.get("backend", "mock"),
+        "max_retries": body.get("max_retries", 2),
+    })
+    return JSONResponse(result)
+
+
+@app.post("/api/generate-image")
+async def generate_image(
+    image: UploadFile = File(...),
+    text_hint: str = Form(""),
+    part_name: str = Form(""),
+    backend: str = Form("anthropic"),
+):
+    # Save uploaded image to temp file
+    suffix = Path(image.filename or "upload.png").suffix
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        tmp.write(await image.read())
+        tmp_path = tmp.name
+
+    try:
+        result = await call_mcp_tool("generate_from_image", {
+            "image_path": tmp_path,
+            "text_hint": text_hint,
+            "part_name": part_name,
+            "backend": backend,
+        })
+        return JSONResponse(result)
+    finally:
+        os.unlink(tmp_path)
+
+
+@app.post("/api/validate")
+async def validate(body: dict):
+    result = await call_mcp_tool("validate_cnc_model", {
+        "cadquery_code": body.get("code", ""),
+        "part_name": body.get("part_name", "Part"),
+    })
+    return JSONResponse(result)
+
+
+@app.get("/api/models")
+async def list_models():
+    result = await call_mcp_tool("list_models", {
+        "output_dir": str(OUTPUT_DIR),
+    })
+    return JSONResponse(result)
+
+
+@app.get("/api/models/{name}.stl")
+async def get_stl(name: str):
+    path = OUTPUT_DIR / f"{name}.stl"
+    if not path.exists():
+        return JSONResponse({"error": f"STL not found: {name}"}, status_code=404)
+    return FileResponse(path, media_type="model/stl", filename=f"{name}.stl")
+
+
+@app.get("/api/models/{name}.step")
+async def get_step(name: str):
+    path = OUTPUT_DIR / f"{name}.step"
+    if not path.exists():
+        return JSONResponse({"error": f"STEP not found: {name}"}, status_code=404)
+    return FileResponse(path, media_type="application/step", filename=f"{name}.step")
+
+
+@app.get("/api/capabilities")
+async def capabilities():
+    try:
+        text = await read_mcp_resource("text-to-cnc://capabilities")
+        return JSONResponse(json.loads(text))
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=502)
+
+
+# ── Entry Point ──────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="NeuralCAD Web Demo Server")
+    parser.add_argument("--port", type=int, default=PORT, help="Web server port (default: 5000)")
+    parser.add_argument("--host", default="0.0.0.0", help="Bind host (default: 0.0.0.0)")
+    parser.add_argument(
+        "--start-mcp", action="store_true",
+        help="Auto-launch MCP server as subprocess before starting web server"
+    )
+    parser.add_argument("--mcp-port", type=int, default=8000, help="MCP server port (default: 8000)")
+    args = parser.parse_args()
+
+    if args.start_mcp:
+        MCP_SERVER_URL = f"http://localhost:{args.mcp_port}/sse"
+        print(f"Starting MCP CAD server on port {args.mcp_port}...")
+        start_mcp_server(args.mcp_port)
+
+    print(f"Starting NeuralCAD Web Demo on http://localhost:{args.port}")
+    print(f"MCP server: {MCP_SERVER_URL}")
+    uvicorn.run(app, host=args.host, port=args.port)

tests/conftest.py

@@ -0,0 +1,61 @@
+"""Shared fixtures for NeuralCAD tests."""
+
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def tmp_output_dir(tmp_path):
+    """Temporary output directory for model files."""
+    out = tmp_path / "output"
+    out.mkdir()
+    return out
+
+
+@pytest.fixture
+def sample_history():
+    """A typical multi-turn conversation history."""
+    return [
+        {"role": "user", "content": "I need a servo bracket for an MG996R"},
+        {"role": "agent", "agent_id": "design", "content": "I'd suggest an L-bracket with a servo pocket on the vertical face."},
+        {"role": "agent", "agent_id": "engineering", "content": "3mm wall thickness in aluminum 6061-T6 should handle the load."},
+        {"role": "user", "content": "Make it 60mm wide with M4 base mounting holes"},
+    ]
+
+
+@pytest.fixture
+def empty_design_state():
+    """Empty design state dict."""
+    return {}
+
+
+@pytest.fixture
+def populated_design_state():
+    """Design state with some decisions already made."""
+    return {
+        "part_name": "servo_bracket",
+        "material": "aluminum 6061",
+        "dimensions": {"width": 60.0},
+        "features": ["4x M4 holes"],
+        "decisions": ["L-bracket form factor"],
+    }
+
+
+class FakeLLMBackend:
+    """A controllable fake LLM backend for testing orchestrators."""
+
+    def __init__(self, response: str = '{"agents": []}'):
+        self.response = response
+        self.calls: list[list[dict]] = []
+
+    def generate(self, messages: list[dict]) -> str:
+        self.calls.append(messages)
+        return self.response
+
+
+@pytest.fixture
+def fake_backend():
+    """FakeLLMBackend factory — call with desired JSON response."""
+    def _make(response: str = '{"agents": []}'):
+        return FakeLLMBackend(response)
+    return _make

tests/test_api_routes.py

@@ -0,0 +1,127 @@
+"""Tests for server/routes.py — FastAPI chat API endpoints."""
+
+from fastapi.testclient import TestClient
+from server.web import app
+
+
+client = TestClient(app)
+
+
+class TestChatEndpoint:
+    def test_basic_chat(self):
+        resp = client.post("/api/chat", json={
+            "message": "I need a bracket",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "responses" in data
+        assert len(data["responses"]) > 0
+
+    def test_chat_with_mentions(self):
+        resp = client.post("/api/chat", json={
+            "message": "What do you think?",
+            "history": [],
+            "mentions": ["cnc"],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        agent_ids = [r["agent_id"] for r in data["responses"]]
+        assert "cnc" in agent_ids
+
+    def test_chat_with_history(self):
+        resp = client.post("/api/chat", json={
+            "message": "Make it wider",
+            "history": [
+                {"role": "user", "content": "I need a bracket"},
+                {"role": "agent", "agent_id": "design", "content": "L-bracket suggestion."},
+            ],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "responses" in data
+
+    def test_chat_empty_message_rejected(self):
+        resp = client.post("/api/chat", json={
+            "message": "",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 422
+
+    def test_chat_returns_design_state(self):
+        resp = client.post("/api/chat", json={
+            "message": "60mm wide aluminum bracket",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "design_state" in data
+
+    def test_chat_at_mention_in_message(self):
+        resp = client.post("/api/chat", json={
+            "message": "@engineering what thickness?",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        agent_ids = [r["agent_id"] for r in data["responses"]]
+        assert "engineering" in agent_ids
+
+
+class TestReportEndpoint:
+    def test_basic_report(self):
+        resp = client.post("/api/report", json={
+            "part_name": "test_bracket",
+            "history": [
+                {"role": "agent", "agent_id": "design", "content": "L-bracket design."},
+                {"role": "agent", "agent_id": "engineering", "content": "3mm aluminum."},
+                {"role": "agent", "agent_id": "cnc", "content": "3-axis OK."},
+            ],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "report" in data
+        assert "test_bracket" in data["report"]
+        assert "Design Decisions" in data["report"]
+        assert "Engineering Specifications" in data["report"]
+        assert "Manufacturing Notes" in data["report"]
+
+    def test_empty_history(self):
+        resp = client.post("/api/report", json={
+            "part_name": "empty_part",
+            "history": [],
+            "backend": "mock",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "report" in data
+
+
+class TestAgentsEndpoint:
+    def test_list_agents(self):
+        resp = client.get("/api/agents")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "agents" in data
+        agent_ids = [a["id"] for a in data["agents"]]
+        assert "design" in agent_ids
+        assert "engineering" in agent_ids
+        assert "cnc" in agent_ids
+        assert "cad" in agent_ids
+
+    def test_agent_has_metadata(self):
+        resp = client.get("/api/agents")
+        data = resp.json()
+        agent = data["agents"][0]
+        assert "id" in agent
+        assert "name" in agent
+        assert "role" in agent
+        assert "color" in agent
+        assert "avatar" in agent

tests/test_design_state.py

@@ -0,0 +1,90 @@
+"""Tests for agents/design_state.py — state tracking and decision extraction."""
+
+from agents.design_state import DesignState, extract_decisions
+
+
+class TestDesignState:
+    def test_empty_render(self):
+        state = DesignState()
+        assert state.render() == ""
+
+    def test_render_with_fields(self):
+        state = DesignState(
+            part_name="bracket",
+            material="aluminum 6061",
+            dimensions={"width": 60.0, "height": 40.0},
+        )
+        rendered = state.render()
+        assert "bracket" in rendered
+        assert "aluminum 6061" in rendered
+        assert "width=60.0mm" in rendered
+
+    def test_render_features(self):
+        state = DesignState(features=["4x M6 holes", "fillet"])
+        rendered = state.render()
+        assert "4x M6 holes" in rendered
+
+    def test_render_decisions_capped_at_5(self):
+        state = DesignState(decisions=[f"decision {i}" for i in range(10)])
+        rendered = state.render()
+        assert "decision 9" in rendered
+        assert "decision 4" not in rendered
+
+
+class TestExtractDecisions:
+    def test_extracts_material(self):
+        responses = [
+            {"agent_id": "engineering", "message": "I recommend aluminum 6061 for this application."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert "aluminum" in state.material.lower()
+
+    def test_extracts_dimensions_from_user(self):
+        responses = []
+        state = extract_decisions(responses, DesignState(), user_message="Make it 60mm wide and 40mm high")
+        assert state.dimensions.get("width") == 60.0
+        assert state.dimensions.get("height") == 40.0
+
+    def test_extracts_fastener_features(self):
+        responses = [
+            {"agent_id": "engineering", "message": "I'll add 4x M6 clearance holes for mounting."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert any("M6" in f for f in state.features)
+
+    def test_extracts_axis_recommendation(self):
+        responses = [
+            {"agent_id": "cnc", "message": "This part needs 5-axis machining due to the undercut."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert "5-axis" in state.axis_recommendation
+
+    def test_extracts_part_name(self):
+        responses = []
+        state = extract_decisions(responses, DesignState(), user_message="I need a servo bracket with M4 holes")
+        assert "servo bracket" in state.part_name.lower()
+
+    def test_preserves_existing_state(self):
+        existing = DesignState(material="steel", dimensions={"width": 50.0})
+        responses = [
+            {"agent_id": "engineering", "message": "Height should be 30mm."}
+        ]
+        updated = extract_decisions(responses, existing, user_message="add height")
+        assert updated.material == "steel"
+        assert updated.dimensions.get("width") == 50.0
+
+    def test_extracts_decisions_from_agreement(self):
+        responses = [
+            {"agent_id": "design", "message": "I'd recommend an L-bracket form factor for this."}
+        ]
+        state = extract_decisions(responses, DesignState())
+        assert len(state.decisions) > 0
+
+    def test_no_duplicate_features(self):
+        existing = DesignState(features=["4x M6 holes"])
+        responses = [
+            {"agent_id": "engineering", "message": "The 4x M6 holes are properly specified."}
+        ]
+        updated = extract_decisions(responses, existing)
+        m6_count = sum(1 for f in updated.features if "M6" in f)
+        assert m6_count == 1

tests/test_executor.py

@@ -0,0 +1,104 @@
+"""Tests for core/executor.py — CadQuery code execution and export.
+
+These tests require CadQuery to be installed.
+"""
+
+import pytest
+from pathlib import Path
+from core.executor import sanitize_code, execute_cadquery, export_step, export_stl, export_all
+
+pytestmark = pytest.mark.requires_cadquery
+
+
+class TestSanitizeCode:
+    def test_strips_markdown_fences(self):
+        code = "```python\nresult = 1\n```"
+        assert "```" not in sanitize_code(code)
+
+    def test_strips_plain_fences(self):
+        code = "```\nresult = 1\n```"
+        assert "```" not in sanitize_code(code)
+
+    def test_removes_cadquery_imports(self):
+        code = "import cadquery as cq\nresult = cq.Workplane('XY').box(10,10,10)"
+        cleaned = sanitize_code(code)
+        assert "import cadquery" not in cleaned
+        assert "result" in cleaned
+
+    def test_removes_math_import(self):
+        code = "import math\nresult = cq.Workplane('XY').box(10,10,10)"
+        cleaned = sanitize_code(code)
+        assert "import math" not in cleaned
+
+    def test_preserves_valid_code(self):
+        code = "result = cq.Workplane('XY').box(10, 20, 30)"
+        assert sanitize_code(code) == code
+
+
+class TestExecuteCadquery:
+    def test_simple_box(self):
+        result = execute_cadquery("result = cq.Workplane('XY').box(10, 20, 30)")
+        assert result.success is True
+        assert result.volume > 0
+        assert result.face_count == 6
+        assert result.edge_count == 12
+        assert len(result.bounding_box) == 3
+
+    def test_cylinder(self):
+        result = execute_cadquery("result = cq.Workplane('XY').cylinder(20, 10)")
+        assert result.success is True
+        assert result.volume > 0
+
+    def test_missing_result_variable(self):
+        result = execute_cadquery("x = cq.Workplane('XY').box(10,10,10)")
+        assert result.success is False
+        assert "result" in result.error
+
+    def test_syntax_error(self):
+        result = execute_cadquery("result = cq.Workplane('XY').box(10, 10,")
+        assert result.success is False
+        assert result.error is not None
+
+    def test_wrong_type(self):
+        result = execute_cadquery("result = 42")
+        assert result.success is False
+        assert "Workplane" in result.error
+
+    def test_code_with_markdown_fences(self):
+        code = "```python\nimport cadquery as cq\nresult = cq.Workplane('XY').box(5,5,5)\n```"
+        result = execute_cadquery(code)
+        assert result.success is True
+
+    def test_summary_on_success(self):
+        result = execute_cadquery("result = cq.Workplane('XY').box(10, 20, 30)")
+        summary = result.summary()
+        assert "OK" in summary
+        assert "Volume" in summary
+
+    def test_summary_on_failure(self):
+        result = execute_cadquery("result = bad_code")
+        summary = result.summary()
+        assert "FAILED" in summary
+
+
+class TestExport:
+    def test_export_step(self, tmp_path):
+        exec_result = execute_cadquery("result = cq.Workplane('XY').box(10,10,10)")
+        assert exec_result.success
+        path = export_step(exec_result.result, tmp_path / "test.step")
+        assert path.exists()
+        assert path.suffix == ".step"
+
+    def test_export_stl(self, tmp_path):
+        exec_result = execute_cadquery("result = cq.Workplane('XY').box(10,10,10)")
+        assert exec_result.success
+        path = export_stl(exec_result.result, tmp_path / "test.stl")
+        assert path.exists()
+        assert path.suffix == ".stl"
+
+    def test_export_all(self, tmp_path):
+        exec_result = execute_cadquery("result = cq.Workplane('XY').box(10,10,10)")
+        assert exec_result.success
+        files = export_all(exec_result.result, tmp_path / "part")
+        assert files["step"].exists()
+        assert files["stl"].exists()

tests/test_mock_orchestrator.py

@@ -0,0 +1,87 @@
+"""Tests for agents/orchestrator.py — MockChatBackend and helpers."""
+
+from agents.orchestrator import MockChatBackend, _format_response
+from agents.definitions import AGENTS, AGENT_COLORS, AGENT_NAMES, AGENT_AVATARS
+
+
+class TestFormatResponse:
+    def test_returns_all_fields(self):
+        resp = _format_response("design", "Hello")
+        assert resp["agent_id"] == "design"
+        assert resp["agent_name"] == AGENT_NAMES["design"]
+        assert resp["message"] == "Hello"
+        assert resp["color"] == AGENT_COLORS["design"]
+        assert resp["avatar"] == AGENT_AVATARS["design"]
+        assert resp["code"] is None
+
+    def test_includes_code(self):
+        resp = _format_response("cad", "Done.", code="result = cq.Workplane().box(10,10,10)")
+        assert resp["code"] == "result = cq.Workplane().box(10,10,10)"
+
+
+class TestMockChatBackend:
+    def test_response_shape(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("I need a bracket", history=[])
+        assert "responses" in result
+        assert "preview" in result
+        assert "design_state" in result
+        assert isinstance(result["responses"], list)
+        assert len(result["responses"]) > 0
+
+    def test_bracket_routes_to_design(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Design a mounting bracket", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "design" in agent_ids
+
+    def test_mention_overrides_routing(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn(
+            "What do you think?",
+            history=[],
+            mentions=["cnc"],
+        )
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert agent_ids == ["cnc"]
+
+    def test_cad_mention_generates_code(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn(
+            "Generate a 50mm cube",
+            history=[],
+            mentions=["cad"],
+        )
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "cad" in agent_ids
+        cad_resp = next(r for r in result["responses"] if r["agent_id"] == "cad")
+        assert cad_resp["code"] is not None
+        assert "result" in cad_resp["code"]
+
+    def test_design_state_updated(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn(
+            "Make it 60mm wide in aluminum",
+            history=[],
+        )
+        ds = result["design_state"]
+        assert isinstance(ds, dict)
+
+    def test_engineering_keywords_trigger_engineering(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Use M6 bolts with 3mm wall thickness", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "engineering" in agent_ids
+
+    def test_cnc_keywords_trigger_cnc(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Can this be machined on a CNC mill?", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "cnc" in agent_ids
+
+    def test_generic_message_default_agents(self, tmp_output_dir):
+        mock = MockChatBackend(output_dir=tmp_output_dir)
+        result = mock.chat_turn("Hello there", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "design" in agent_ids
+        assert "engineering" in agent_ids

tests/test_pipeline.py

@@ -0,0 +1,78 @@
+"""Tests for core/pipeline.py — end-to-end text-to-CNC pipeline.
+
+These tests require CadQuery to be installed.
+"""
+
+import pytest
+from pathlib import Path
+from core.pipeline import run_pipeline, PipelineResult
+from core.backends import MockBackend
+
+pytestmark = pytest.mark.requires_cadquery
+
+
+class TestRunPipeline:
+    def test_basic_box(self, tmp_output_dir):
+        result = run_pipeline(
+            "A simple 50mm cube",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+        )
+        assert isinstance(result, PipelineResult)
+        assert result.execution.success is True
+        assert result.execution.volume > 0
+
+    def test_exports_files(self, tmp_output_dir):
+        result = run_pipeline(
+            "A 60x40x5mm mounting plate",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            part_name="test_plate",
+        )
+        assert result.exported_files is not None
+        assert result.exported_files["step"].exists()
+        assert result.exported_files["stl"].exists()
+
+    def test_validation_runs(self, tmp_output_dir):
+        result = run_pipeline(
+            "A 50mm cylinder",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            validate=True,
+        )
+        assert result.validation is not None
+        assert hasattr(result.validation, "machinable")
+
+    def test_skip_validation(self, tmp_output_dir):
+        result = run_pipeline(
+            "A simple box",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            validate=False,
+        )
+        assert result.validation is None
+
+    def test_skip_export(self, tmp_output_dir):
+        result = run_pipeline(
+            "A simple box",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+            export=False,
+        )
+        assert result.exported_files is None or len(result.exported_files) == 0
+
+    def test_summary(self, tmp_output_dir):
+        result = run_pipeline(
+            "A 30mm cube",
+            backend=MockBackend(),
+            output_dir=tmp_output_dir,
+        )
+        summary = result.summary()
+        assert isinstance(summary, str)
+
+    def test_default_backend_is_mock(self, tmp_output_dir):
+        result = run_pipeline(
+            "A basic plate",
+            output_dir=tmp_output_dir,
+        )
+        assert result.execution.success is True

tests/test_prompts.py

@@ -0,0 +1,216 @@
+"""Tests for agents/prompts.py — prompt building, routing, parsing."""
+
+from agents.prompts import (
+    parse_mentions,
+    route_by_keywords,
+    parse_orchestrator_response,
+    build_orchestrator_system_prompt,
+    build_chat_messages,
+    CAD_TRIGGER_KEYWORDS,
+)
+
+
+class TestParseMentions:
+    def test_no_mentions(self):
+        cleaned, mentions = parse_mentions("I need a bracket")
+        assert cleaned == "I need a bracket"
+        assert mentions == []
+
+    def test_single_mention(self):
+        cleaned, mentions = parse_mentions("@design what shape?")
+        assert "design" in mentions
+        assert "@design" not in cleaned
+
+    def test_multiple_mentions(self):
+        cleaned, mentions = parse_mentions("@design @engineering check this")
+        assert "design" in mentions
+        assert "engineering" in mentions
+        assert "@design" not in cleaned
+        assert "@engineering" not in cleaned
+
+    def test_cad_mention(self):
+        cleaned, mentions = parse_mentions("@cad generate a preview")
+        assert "cad" in mentions
+
+    def test_case_insensitive(self):
+        cleaned, mentions = parse_mentions("@Design what do you think?")
+        assert "design" in mentions
+
+    def test_mention_mid_sentence(self):
+        cleaned, mentions = parse_mentions("Can @engineering check the wall thickness?")
+        assert "engineering" in mentions
+        assert "Can" in cleaned
+        assert "check the wall thickness?" in cleaned
+
+
+class TestRouteByKeywords:
+    def test_design_keywords(self):
+        agents = route_by_keywords("I want a sleek design with smooth shape")
+        assert "design" in agents
+
+    def test_engineering_keywords(self):
+        agents = route_by_keywords("Use M6 bolts with 3mm wall thickness in aluminum")
+        assert "engineering" in agents
+
+    def test_cnc_keywords(self):
+        agents = route_by_keywords("Can this be machined on a 3-axis CNC mill?")
+        assert "cnc" in agents
+
+    def test_cad_trigger(self):
+        agents = route_by_keywords("Generate a preview of the part")
+        assert "cad" in agents
+
+    def test_default_when_no_match(self):
+        agents = route_by_keywords("hello there")
+        assert agents == ["design", "engineering"]
+
+    def test_max_three_agents(self):
+        agents = route_by_keywords(
+            "design shape in aluminum for CNC machining, generate preview"
+        )
+        assert len(agents) <= 3
+
+    def test_sorted_by_relevance(self):
+        agents = route_by_keywords("M4 M6 tolerance clearance aluminum steel wall")
+        assert agents[0] == "engineering"
+
+
+class TestParseOrchestratorResponse:
+    def test_valid_json(self):
+        resp = '{"agents": [{"id": "design", "message": "Nice bracket."}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "design"
+        assert parsed[0]["message"] == "Nice bracket."
+        assert parsed[0]["code"] is None
+
+    def test_json_with_code(self):
+        resp = '{"agents": [{"id": "cad", "message": "Done.", "code": "result = cq.Workplane().box(10,10,10)"}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert parsed[0]["code"] == "result = cq.Workplane().box(10,10,10)"
+
+    def test_json_in_markdown_fence(self):
+        resp = '```json\n{"agents": [{"id": "engineering", "message": "Use 3mm walls."}]}\n```'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "engineering"
+
+    def test_multiple_agents(self):
+        resp = '{"agents": [{"id": "design", "message": "A"}, {"id": "cnc", "message": "B"}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 2
+        assert parsed[0]["id"] == "design"
+        assert parsed[1]["id"] == "cnc"
+
+    def test_invalid_json_fallback(self):
+        resp = "I think you should use aluminum."
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "design"
+        assert parsed[0]["message"] == resp
+
+    def test_empty_agents_fallback(self):
+        resp = '{"agents": []}'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "design"
+
+    def test_missing_fields_skipped(self):
+        resp = '{"agents": [{"id": "design"}, {"id": "cnc", "message": "OK"}]}'
+        parsed = parse_orchestrator_response(resp)
+        assert len(parsed) == 1
+        assert parsed[0]["id"] == "cnc"
+
+
+class TestBuildOrchestratorSystemPrompt:
+    def test_default_agents(self):
+        prompt = build_orchestrator_system_prompt()
+        assert "Design Agent" in prompt
+        assert "Engineering Agent" in prompt
+        assert "CNC Agent" in prompt
+        assert '### CAD Coder' not in prompt  # persona block excluded
+
+    def test_specific_agents(self):
+        prompt = build_orchestrator_system_prompt(active_agents=["cad"])
+        assert "CAD Coder" in prompt
+        assert "Design Agent" not in prompt
+
+    def test_includes_json_format(self):
+        prompt = build_orchestrator_system_prompt()
+        assert '"agents"' in prompt
+        assert "JSON" in prompt
+
+    def test_cad_context_included(self):
+        prompt = build_orchestrator_system_prompt(
+            active_agents=["cad"], include_cad_context=True
+        )
+        assert "CadQuery" in prompt
+
+
+class TestBuildChatMessages:
+    def test_returns_system_and_user(self):
+        msgs = build_chat_messages("hello", [], "You are a bot.")
+        assert len(msgs) == 2
+        assert msgs[0]["role"] == "system"
+        assert msgs[0]["content"] == "You are a bot."
+        assert msgs[1]["role"] == "user"
+
+    def test_history_included_in_user_message(self, sample_history):
+        msgs = build_chat_messages("new msg", sample_history, "system prompt")
+        user_content = msgs[1]["content"]
+        assert "servo bracket" in user_content
+        assert "new msg" in user_content
+
+    def test_design_state_included(self):
+        msgs = build_chat_messages(
+            "make it wider", [], "system prompt",
+            design_state_text="Part: bracket\nMaterial: aluminum"
+        )
+        user_content = msgs[1]["content"]
+        assert "bracket" in user_content
+        assert "aluminum" in user_content
+
+    def test_history_truncation(self):
+        long_history = [
+            {"role": "user", "content": f"msg {i}"}
+            for i in range(50)
+        ]
+        msgs = build_chat_messages("latest", long_history, "sys", max_history=5)
+        user_content = msgs[1]["content"]
+        assert "msg 49" in user_content
+        assert "msg 0" not in user_content
+
+
+# ── Improved routing coverage ───────────────────────���─────────────────────
+
+
+class TestRouteByKeywordsImproved:
+    """Tests for expanded keyword routing vocabulary."""
+
+    def test_gear_routes_to_engineering(self):
+        agents = route_by_keywords("I need a spur gear with 20 teeth")
+        assert "engineering" in agents
+
+    def test_bearing_routes_to_engineering(self):
+        agents = route_by_keywords("Design a bearing housing")
+        assert "engineering" in agents
+
+    def test_heatsink_routes_to_engineering(self):
+        agents = route_by_keywords("Create a heatsink with fins")
+        assert "engineering" in agents
+
+    def test_flange_routes_to_engineering(self):
+        agents = route_by_keywords("A pipe flange with bolt holes")
+        assert "engineering" in agents
+
+    def test_servo_bracket_routes_to_design(self):
+        agents = route_by_keywords("Design a servo bracket for a camera gimbal")
+        assert "design" in agents
+
+    def test_cost_routes_to_cnc(self):
+        agents = route_by_keywords("How much would this cost to machine?")
+        assert "cnc" in agents
+
+    def test_surface_finish_routes_to_cnc(self):
+        agents = route_by_keywords("What surface finish can we achieve?")
+        assert "cnc" in agents

tests/test_single_call_orchestrator.py

@@ -0,0 +1,78 @@
+"""Tests for SingleCallOrchestrator using a fake LLM backend."""
+
+import json
+from agents.orchestrator import SingleCallOrchestrator
+from tests.conftest import FakeLLMBackend
+
+
+class TestSingleCallOrchestrator:
+    def _make_orchestrator(self, response_json: str, tmp_output_dir):
+        backend = FakeLLMBackend(response_json)
+        return SingleCallOrchestrator(backend=backend, output_dir=tmp_output_dir), backend
+
+    def test_response_shape(self, tmp_output_dir):
+        resp = json.dumps({"agents": [
+            {"id": "design", "message": "An L-bracket would work."},
+        ]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("I need a bracket", history=[])
+        assert "responses" in result
+        assert "preview" in result
+        assert "design_state" in result
+
+    def test_passes_message_to_backend(self, tmp_output_dir):
+        resp = json.dumps({"agents": [{"id": "design", "message": "OK"}]})
+        orch, backend = self._make_orchestrator(resp, tmp_output_dir)
+        orch.chat_turn("Test message", history=[])
+        assert len(backend.calls) == 1
+        last_user_msg = backend.calls[0][-1]["content"]
+        assert "Test message" in last_user_msg
+
+    def test_mentions_restrict_agents(self, tmp_output_dir):
+        resp = json.dumps({"agents": [{"id": "cnc", "message": "3-axis OK"}]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("check this", history=[], mentions=["cnc"])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "cnc" in agent_ids
+
+    def test_invalid_json_fallback(self, tmp_output_dir):
+        orch, _ = self._make_orchestrator("not json at all", tmp_output_dir)
+        result = orch.chat_turn("help", history=[])
+        assert len(result["responses"]) > 0
+        assert result["responses"][0]["agent_id"] == "design"
+
+    def test_llm_exception_fallback(self, tmp_output_dir):
+        class RaisingBackend:
+            def generate(self, messages):
+                raise RuntimeError("API error")
+
+        orch = SingleCallOrchestrator(backend=RaisingBackend(), output_dir=tmp_output_dir)
+        result = orch.chat_turn("Design a part", history=[])
+        assert len(result["responses"]) > 0
+
+    def test_unknown_agent_id_filtered(self, tmp_output_dir):
+        resp = json.dumps({"agents": [
+            {"id": "nonexistent", "message": "I don't exist"},
+            {"id": "design", "message": "Real agent"},
+        ]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("test", history=[])
+        agent_ids = [r["agent_id"] for r in result["responses"]]
+        assert "nonexistent" not in agent_ids
+        assert "design" in agent_ids
+
+    def test_history_forwarded_to_backend(self, tmp_output_dir, sample_history):
+        resp = json.dumps({"agents": [{"id": "design", "message": "OK"}]})
+        orch, backend = self._make_orchestrator(resp, tmp_output_dir)
+        orch.chat_turn("continue", history=sample_history)
+        user_content = backend.calls[0][-1]["content"]
+        assert "servo bracket" in user_content.lower() or "MG996R" in user_content
+
+    def test_design_state_returned(self, tmp_output_dir):
+        resp = json.dumps({"agents": [
+            {"id": "engineering", "message": "Use aluminum 6061 with 3mm walls."},
+        ]})
+        orch, _ = self._make_orchestrator(resp, tmp_output_dir)
+        result = orch.chat_turn("material?", history=[])
+        assert "design_state" in result
+        assert isinstance(result["design_state"], dict)

tests/test_validator.py

@@ -0,0 +1,76 @@
+"""Tests for core/validator.py — CNC manufacturability validation.
+
+These tests require CadQuery to be installed.
+"""
+
+import pytest
+from core.executor import execute_cadquery
+from core.validator import validate_for_cnc, CNCValidationResult, CNCIssue
+
+pytestmark = pytest.mark.requires_cadquery
+
+
+def _make_solid(code: str):
+    """Helper to create a CadQuery Workplane from code."""
+    result = execute_cadquery(code)
+    assert result.success, f"Code failed: {result.error}"
+    return result.result
+
+
+class TestValidateForCnc:
+    def test_simple_box_is_machinable(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, "test_box")
+        assert val.machinable is True
+        assert val.error_count == 0
+
+    def test_result_has_part_name(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, "my_part")
+        assert val.part_name == "my_part"
+
+    def test_axis_recommendation_default_3axis(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid)
+        assert "3-axis" in val.axis_recommendation or "3" in val.axis_recommendation
+
+    def test_complex_part_gets_higher_axis(self):
+        code = '''
+result = cq.Workplane('XY').box(50, 50, 50)
+for i in range(5):
+    result = result.faces('>Z').workplane().pushPoints([(i*8-16, 0)]).hole(3)
+for i in range(5):
+    result = result.faces('>X').workplane().pushPoints([(i*8-16, 0)]).hole(3)
+'''
+        solid = _make_solid(code)
+        val = validate_for_cnc(solid)
+        assert val.part_name is not None
+
+    def test_oversized_part_flagged(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(600, 600, 600)")
+        val = validate_for_cnc(solid, config={"max_part_size_mm": 500.0})
+        assert any(i.category == "Size" for i in val.issues)
+
+    def test_tiny_part_flagged(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(0.5, 0.5, 0.5)")
+        val = validate_for_cnc(solid, config={"min_part_size_mm": 1.0})
+        assert any(i.category == "Size" for i in val.issues)
+
+    def test_summary_format(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, "test")
+        summary = val.summary()
+        assert isinstance(summary, str)
+        assert "test" in summary
+
+    def test_custom_config(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid, config={"min_wall_thickness_mm": 0.5})
+        assert isinstance(val, CNCValidationResult)
+
+    def test_error_and_warning_counts(self):
+        solid = _make_solid("result = cq.Workplane('XY').box(50, 30, 10)")
+        val = validate_for_cnc(solid)
+        assert val.error_count >= 0
+        assert val.warning_count >= 0
+        assert val.error_count + val.warning_count <= len(val.issues)

web/index.html

@@ -0,0 +1,1983 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>NeuralCAD — Multi-Agent Design</title>
+
+<!-- Three.js -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.128.0/examples/js/loaders/STLLoader.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/three@0.128.0/examples/js/controls/OrbitControls.js"></script>
+
+<!-- Fonts -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600;700&family=DM+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+  :root {
+    --bg-void: #06080c;
+    --bg-panel: #0c1018;
+    --bg-surface: #111822;
+    --bg-input: #0a0f16;
+    --border: #1c2636;
+    --border-active: #2a3a52;
+    --text-primary: #c8d6e5;
+    --text-secondary: #5a7089;
+    --text-muted: #3a4d63;
+    --accent: #00b4d8;
+    --accent-glow: rgba(0, 180, 216, 0.15);
+    --accent-dim: #007a94;
+    --success: #00e676;
+    --success-glow: rgba(0, 230, 118, 0.12);
+    --warning: #ffab40;
+    --error: #ff5252;
+    --machined-steel: #8899aa;
+    --font-mono: 'JetBrains Mono', 'Cascadia Code', monospace;
+    --font-body: 'DM Sans', system-ui, sans-serif;
+    --agent-design: #7c3aed;
+    --agent-engineering: #00b4d8;
+    --agent-cnc: #00e676;
+    --agent-cad: #ffab40;
+    --chat-width: 340px;
+  }
+
+  html, body {
+    height: 100%;
+    overflow: hidden;
+    background: var(--bg-void);
+    color: var(--text-primary);
+    font-family: var(--font-body);
+  }
+
+  /* ---- Scrollbar ---- */
+  ::-webkit-scrollbar { width: 5px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+  ::-webkit-scrollbar-thumb:hover { background: var(--border-active); }
+
+  /* ---- LAYOUT ---- */
+
+  #app {
+    display: flex;
+    flex-direction: column;
+    height: 100vh;
+    width: 100vw;
+    overflow: hidden;
+  }
+
+  /* ---- TOP BAR ---- */
+
+  #topbar {
+    flex: 0 0 44px;
+    background: var(--bg-panel);
+    border-bottom: 1px solid var(--border);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 16px;
+    z-index: 100;
+    position: relative;
+  }
+
+  #topbar::after {
+    content: '';
+    position: absolute;
+    bottom: -1px;
+    left: 0; right: 0;
+    height: 1px;
+    background: linear-gradient(90deg, transparent, var(--accent-dim), transparent);
+    opacity: 0.4;
+  }
+
+  .logo {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+  }
+
+  .logo-diamond {
+    color: var(--accent);
+    font-size: 18px;
+    line-height: 1;
+  }
+
+  .logo-text {
+    font-family: var(--font-mono);
+    font-weight: 600;
+    font-size: 14px;
+    letter-spacing: 2px;
+    color: var(--text-primary);
+    text-transform: uppercase;
+  }
+
+  .logo-sub {
+    font-family: var(--font-mono);
+    font-size: 9px;
+    color: var(--text-muted);
+    letter-spacing: 3px;
+    text-transform: uppercase;
+    margin-left: 8px;
+    padding-left: 8px;
+    border-left: 1px solid var(--border);
+  }
+
+  .topbar-center {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+
+  .topbar-right {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+
+  .backend-toggle {
+    display: flex;
+    align-items: center;
+    gap: 0;
+    background: var(--bg-void);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    overflow: hidden;
+    font-family: var(--font-mono);
+    font-size: 11px;
+  }
+
+  .backend-toggle button {
+    all: unset;
+    padding: 4px 12px;
+    cursor: pointer;
+    color: var(--text-muted);
+    transition: all 0.2s;
+    border-right: 1px solid var(--border);
+  }
+
+  .backend-toggle button:last-child { border-right: none; }
+
+  .backend-toggle button.active {
+    background: var(--accent-glow);
+    color: var(--accent);
+  }
+
+  .backend-toggle button:hover:not(.active) {
+    color: var(--text-secondary);
+  }
+
+  .gallery-btn {
+    all: unset;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 12px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--text-secondary);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    cursor: pointer;
+    transition: all 0.2s;
+  }
+
+  .gallery-btn:hover {
+    border-color: var(--accent-dim);
+    color: var(--accent);
+  }
+
+  .status-dot {
+    width: 7px; height: 7px;
+    border-radius: 50%;
+    background: var(--success);
+    box-shadow: 0 0 6px var(--success);
+    animation: pulse-dot 2s ease-in-out infinite;
+  }
+
+  @keyframes pulse-dot {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.4; }
+  }
+
+  /* ---- MAIN AREA ---- */
+
+  #main {
+    flex: 1;
+    display: flex;
+    position: relative;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  /* ---- 3D VIEWER ---- */
+
+  #viewer-container {
+    flex: 1;
+    position: relative;
+    background: var(--bg-void);
+    overflow: hidden;
+    min-height: 0;
+  }
+
+  #viewer-canvas {
+    width: 100%;
+    height: 100%;
+    display: block;
+  }
+
+  /* Geo stats overlay - top left */
+  #geo-stats {
+    position: absolute;
+    top: 14px;
+    left: 14px;
+    z-index: 10;
+    background: rgba(6, 8, 12, 0.85);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    padding: 10px 14px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    line-height: 1.7;
+    backdrop-filter: blur(8px);
+    display: none;
+  }
+
+  #geo-stats.visible { display: block; }
+
+  .stat-label { color: var(--text-muted); }
+  .stat-value { color: var(--accent); }
+
+  /* CNC badge - top right of viewer (NOT behind chat) */
+  #cnc-badge {
+    position: absolute;
+    top: 14px;
+    right: 14px;
+    z-index: 10;
+    display: none;
+    gap: 6px;
+    transition: right 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  #cnc-badge.visible { display: flex; }
+  body.chat-open #cnc-badge { right: calc(var(--chat-width) + 14px); }
+
+  .badge {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    font-weight: 500;
+    padding: 4px 10px;
+    border-radius: 3px;
+    letter-spacing: 0.5px;
+    backdrop-filter: blur(8px);
+  }
+
+  .badge-success {
+    background: var(--success-glow);
+    border: 1px solid rgba(0, 230, 118, 0.3);
+    color: var(--success);
+  }
+
+  .badge-warning {
+    background: rgba(255, 171, 64, 0.1);
+    border: 1px solid rgba(255, 171, 64, 0.3);
+    color: var(--warning);
+  }
+
+  .badge-error {
+    background: rgba(255, 82, 82, 0.1);
+    border: 1px solid rgba(255, 82, 82, 0.3);
+    color: var(--error);
+  }
+
+  .badge-info {
+    background: var(--accent-glow);
+    border: 1px solid rgba(0, 180, 216, 0.3);
+    color: var(--accent);
+  }
+
+  /* Download buttons - bottom left */
+  #download-btns {
+    position: absolute;
+    bottom: 14px;
+    left: 14px;
+    z-index: 10;
+    display: none;
+    gap: 6px;
+  }
+
+  #download-btns.visible { display: flex; }
+
+  .dl-btn {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    font-weight: 500;
+    padding: 5px 14px;
+    border-radius: 3px;
+    background: rgba(6, 8, 12, 0.85);
+    border: 1px solid var(--border);
+    color: var(--text-secondary);
+    cursor: pointer;
+    text-decoration: none;
+    transition: all 0.2s;
+    backdrop-filter: blur(8px);
+    letter-spacing: 0.5px;
+  }
+
+  .dl-btn:hover {
+    border-color: var(--accent-dim);
+    color: var(--accent);
+  }
+
+  /* Viewer hint */
+  #viewer-hint {
+    position: absolute;
+    bottom: 16px;
+    right: 16px;
+    z-index: 10;
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    letter-spacing: 0.5px;
+    pointer-events: none;
+    transition: right 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  body.chat-open #viewer-hint { right: calc(var(--chat-width) + 16px); }
+
+  /* Loading spinner */
+  #viewer-loading {
+    position: absolute;
+    inset: 0;
+    z-index: 20;
+    display: none;
+    align-items: center;
+    justify-content: center;
+    flex-direction: column;
+    gap: 16px;
+    background: rgba(6, 8, 12, 0.7);
+    backdrop-filter: blur(4px);
+  }
+
+  #viewer-loading.visible { display: flex; }
+
+  .spinner {
+    width: 36px; height: 36px;
+    border: 2px solid var(--border);
+    border-top-color: var(--accent);
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+  }
+
+  @keyframes spin { to { transform: rotate(360deg); } }
+
+  .loading-text {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--text-secondary);
+    letter-spacing: 1px;
+  }
+
+  /* Empty state */
+  #viewer-empty {
+    position: absolute;
+    inset: 0;
+    z-index: 5;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-direction: column;
+    gap: 16px;
+    pointer-events: none;
+  }
+
+  .empty-icon {
+    width: 64px; height: 64px;
+    border: 2px solid var(--border);
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transform: rotate(45deg);
+    opacity: 0.5;
+  }
+
+  .empty-icon-inner {
+    width: 20px; height: 20px;
+    border: 2px solid var(--text-muted);
+    border-radius: 2px;
+    transform: rotate(-45deg);
+    opacity: 0.3;
+  }
+
+  .empty-text {
+    font-family: var(--font-mono);
+    font-size: 12px;
+    color: var(--text-muted);
+    letter-spacing: 1px;
+    text-align: center;
+    line-height: 1.6;
+  }
+
+  /* ---- CHAT PANEL ---- */
+
+  #chat-panel {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: var(--chat-width);
+    height: 100%;
+    background: rgba(10, 14, 20, 0.92);
+    backdrop-filter: blur(16px);
+    border-left: 1px solid var(--border);
+    display: flex;
+    flex-direction: column;
+    z-index: 50;
+    transform: translateX(0);
+    transition: transform 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  #chat-panel.collapsed {
+    transform: translateX(100%);
+  }
+
+  /* Collapse toggle */
+  #chat-toggle {
+    all: unset;
+    position: absolute;
+    top: 50%;
+    left: -28px;
+    transform: translateY(-50%);
+    width: 28px;
+    height: 56px;
+    background: rgba(10, 14, 20, 0.92);
+    backdrop-filter: blur(16px);
+    border: 1px solid var(--border);
+    border-right: none;
+    border-radius: 6px 0 0 6px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    color: var(--text-secondary);
+    font-size: 14px;
+    transition: all 0.2s;
+    z-index: 51;
+  }
+
+  #chat-toggle:hover {
+    color: var(--accent);
+    background: rgba(10, 14, 20, 0.98);
+  }
+
+  /* Floating open pill */
+  #chat-open-pill {
+    position: fixed;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 60;
+    display: none;
+    align-items: center;
+    gap: 10px;
+    padding: 10px 20px;
+    background: rgba(10, 14, 20, 0.95);
+    backdrop-filter: blur(16px);
+    border: 1px solid var(--border);
+    border-radius: 24px;
+    cursor: pointer;
+    font-family: var(--font-mono);
+    font-size: 12px;
+    color: var(--text-primary);
+    letter-spacing: 0.5px;
+    transition: all 0.3s;
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
+  }
+
+  #chat-open-pill:hover {
+    border-color: var(--accent-dim);
+    box-shadow: 0 4px 32px rgba(0, 180, 216, 0.15);
+  }
+
+  #chat-open-pill.visible { display: flex; }
+
+  .pill-dots {
+    display: flex;
+    gap: 4px;
+  }
+
+  .pill-dot {
+    width: 8px; height: 8px;
+    border-radius: 50%;
+  }
+
+  /* Chat header */
+  .chat-header {
+    flex: 0 0 48px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 16px;
+    border-bottom: 1px solid var(--border);
+  }
+
+  .chat-header-left {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+  }
+
+  .chat-header-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 2px;
+    color: var(--text-secondary);
+    text-transform: uppercase;
+  }
+
+  .agent-dots {
+    display: flex;
+    gap: 5px;
+  }
+
+  .agent-dot {
+    width: 8px; height: 8px;
+    border-radius: 50%;
+    opacity: 0.8;
+  }
+
+  /* Messages area */
+  #chat-messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 16px 12px;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    min-height: 0;
+  }
+
+  /* Quick examples */
+  .quick-examples {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 12px;
+    padding: 40px 16px 20px;
+  }
+
+  .quick-examples-label {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    letter-spacing: 2px;
+    text-transform: uppercase;
+  }
+
+  .quick-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+    justify-content: center;
+  }
+
+  .quick-chip {
+    all: unset;
+    padding: 6px 12px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--text-secondary);
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 16px;
+    cursor: pointer;
+    transition: all 0.2s;
+    white-space: nowrap;
+  }
+
+  .quick-chip:hover {
+    border-color: var(--accent-dim);
+    color: var(--accent);
+    background: var(--accent-glow);
+  }
+
+  /* Message bubbles */
+  .msg {
+    display: flex;
+    gap: 8px;
+    max-width: 100%;
+    animation: msg-in 0.25s ease-out both;
+  }
+
+  @keyframes msg-in {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  .msg-user {
+    justify-content: flex-end;
+  }
+
+  .msg-user .msg-bubble {
+    background: #1a2a3a;
+    border: 1px solid rgba(0, 180, 216, 0.15);
+    border-radius: 12px 12px 4px 12px;
+    padding: 8px 12px;
+    font-size: 13px;
+    line-height: 1.5;
+    color: var(--text-primary);
+    max-width: 85%;
+    word-wrap: break-word;
+  }
+
+  .msg-agent {
+    align-items: flex-start;
+  }
+
+  .msg-avatar {
+    flex-shrink: 0;
+    width: 24px; height: 24px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 11px;
+    font-weight: 700;
+    color: rgba(0, 0, 0, 0.7);
+    margin-top: 2px;
+  }
+
+  .msg-agent-body {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .msg-agent-name {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.5px;
+    margin-bottom: 3px;
+    text-transform: uppercase;
+  }
+
+  .msg-agent-bubble {
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 4px 12px 12px 12px;
+    padding: 8px 12px;
+    font-size: 13px;
+    line-height: 1.5;
+    color: var(--text-primary);
+    word-wrap: break-word;
+  }
+
+  /* CAD Coder special styling */
+  .msg-agent-bubble.cad-bubble {
+    background: rgba(255, 171, 64, 0.08);
+    border-color: rgba(255, 171, 64, 0.2);
+  }
+
+  .msg-view-code {
+    display: inline-block;
+    margin-top: 6px;
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--warning);
+    cursor: pointer;
+    text-decoration: none;
+    letter-spacing: 0.5px;
+    transition: opacity 0.2s;
+  }
+
+  .msg-view-code:hover { opacity: 0.7; }
+
+  /* Typing indicator */
+  .typing-indicator {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 12px;
+  }
+
+  .typing-dots {
+    display: flex;
+    gap: 4px;
+  }
+
+  .typing-dots span {
+    width: 6px; height: 6px;
+    border-radius: 50%;
+    background: var(--text-muted);
+    animation: typing-bounce 1.2s ease-in-out infinite;
+  }
+
+  .typing-dots span:nth-child(2) { animation-delay: 0.15s; }
+  .typing-dots span:nth-child(3) { animation-delay: 0.3s; }
+
+  @keyframes typing-bounce {
+    0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
+    30% { transform: translateY(-4px); opacity: 1; }
+  }
+
+  .typing-label {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    letter-spacing: 0.5px;
+  }
+
+  /* Chat input area */
+  .chat-input-area {
+    flex: 0 0 auto;
+    padding: 12px;
+    border-top: 1px solid var(--border);
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+
+  .chat-input-row {
+    display: flex;
+    gap: 6px;
+    align-items: flex-end;
+  }
+
+  #chat-input {
+    flex: 1;
+    min-height: 38px;
+    max-height: 120px;
+    background: var(--bg-input);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 8px 12px;
+    color: var(--text-primary);
+    font-family: var(--font-body);
+    font-size: 13px;
+    line-height: 1.4;
+    resize: none;
+    outline: none;
+    transition: border-color 0.2s;
+  }
+
+  #chat-input::placeholder { color: var(--text-muted); }
+  #chat-input:focus { border-color: var(--accent-dim); }
+
+  .chat-btn {
+    all: unset;
+    flex-shrink: 0;
+    width: 34px; height: 34px;
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    transition: all 0.2s;
+    font-size: 16px;
+  }
+
+  .chat-btn-preview {
+    background: rgba(255, 171, 64, 0.1);
+    border: 1px solid rgba(255, 171, 64, 0.25);
+    color: var(--warning);
+  }
+
+  .chat-btn-preview:hover {
+    background: rgba(255, 171, 64, 0.2);
+    border-color: var(--warning);
+  }
+
+  .chat-btn-send {
+    background: var(--accent-glow);
+    border: 1px solid rgba(0, 180, 216, 0.3);
+    color: var(--accent);
+  }
+
+  .chat-btn-send:hover {
+    background: rgba(0, 180, 216, 0.25);
+    border-color: var(--accent);
+  }
+
+  .chat-shortcut-hint {
+    font-family: var(--font-mono);
+    font-size: 9px;
+    color: var(--text-muted);
+    text-align: right;
+    letter-spacing: 0.3px;
+  }
+
+  /* @mention autocomplete */
+  #mention-dropdown {
+    display: none;
+    position: absolute;
+    bottom: 100%;
+    left: 12px;
+    right: 12px;
+    margin-bottom: 4px;
+    background: var(--bg-panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    overflow: hidden;
+    box-shadow: 0 -8px 24px rgba(0, 0, 0, 0.4);
+    z-index: 55;
+  }
+
+  #mention-dropdown.visible { display: block; }
+
+  .mention-option {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 8px 12px;
+    cursor: pointer;
+    transition: background 0.15s;
+    font-size: 12px;
+  }
+
+  .mention-option:hover,
+  .mention-option.active {
+    background: var(--bg-surface);
+  }
+
+  .mention-dot {
+    width: 10px; height: 10px;
+    border-radius: 50%;
+    flex-shrink: 0;
+  }
+
+  .mention-name {
+    font-family: var(--font-mono);
+    font-weight: 500;
+    color: var(--text-primary);
+    font-size: 12px;
+  }
+
+  .mention-role {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    color: var(--text-muted);
+    margin-left: auto;
+  }
+
+  /* ---- CODE VIEWER MODAL ---- */
+
+  #code-modal {
+    display: none;
+    position: fixed;
+    inset: 0;
+    z-index: 200;
+    align-items: center;
+    justify-content: center;
+    background: rgba(6, 8, 12, 0.85);
+    backdrop-filter: blur(8px);
+  }
+
+  #code-modal.visible { display: flex; }
+
+  .code-modal-inner {
+    width: min(720px, 90vw);
+    max-height: 80vh;
+    background: var(--bg-panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    box-shadow: 0 16px 64px rgba(0, 0, 0, 0.5);
+    animation: modal-in 0.25s ease-out;
+  }
+
+  @keyframes modal-in {
+    from { opacity: 0; transform: scale(0.96) translateY(12px); }
+    to { opacity: 1; transform: scale(1) translateY(0); }
+  }
+
+  .code-modal-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--border);
+  }
+
+  .code-modal-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 600;
+    color: var(--text-secondary);
+    letter-spacing: 1px;
+    text-transform: uppercase;
+  }
+
+  .code-modal-close {
+    all: unset;
+    width: 28px; height: 28px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 4px;
+    cursor: pointer;
+    color: var(--text-muted);
+    font-size: 18px;
+    transition: all 0.15s;
+  }
+
+  .code-modal-close:hover {
+    background: var(--bg-surface);
+    color: var(--text-primary);
+  }
+
+  #code-display {
+    flex: 1;
+    margin: 0;
+    padding: 16px;
+    background: var(--bg-input);
+    color: var(--machined-steel);
+    font-family: var(--font-mono);
+    font-size: 12px;
+    line-height: 1.7;
+    overflow: auto;
+    white-space: pre;
+    tab-size: 4;
+  }
+
+  /* Syntax coloring */
+  .kw { color: #c792ea; }
+  .fn { color: #82aaff; }
+  .cm { color: #546e7a; }
+  .st { color: #c3e88d; }
+  .nu { color: #f78c6c; }
+  .op { color: #89ddff; }
+
+  /* ---- GALLERY MODAL ---- */
+
+  #gallery-modal {
+    display: none;
+    position: fixed;
+    inset: 0;
+    z-index: 200;
+    align-items: center;
+    justify-content: center;
+    background: rgba(6, 8, 12, 0.85);
+    backdrop-filter: blur(8px);
+  }
+
+  #gallery-modal.visible { display: flex; }
+
+  .gallery-modal-inner {
+    width: min(800px, 90vw);
+    max-height: 80vh;
+    background: var(--bg-panel);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    box-shadow: 0 16px 64px rgba(0, 0, 0, 0.5);
+    animation: modal-in 0.25s ease-out;
+  }
+
+  .gallery-modal-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--border);
+  }
+
+  .gallery-modal-title {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 600;
+    color: var(--text-secondary);
+    letter-spacing: 1px;
+    text-transform: uppercase;
+  }
+
+  .gallery-grid {
+    flex: 1;
+    overflow-y: auto;
+    padding: 16px;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+    align-content: flex-start;
+  }
+
+  .gallery-empty {
+    width: 100%;
+    text-align: center;
+    padding: 40px;
+    font-family: var(--font-mono);
+    font-size: 11px;
+    color: var(--text-muted);
+    letter-spacing: 0.5px;
+  }
+
+  .gallery-card {
+    all: unset;
+    flex: 0 0 auto;
+    width: 180px;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 12px;
+    cursor: pointer;
+    transition: all 0.2s;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+
+  .gallery-card:hover {
+    border-color: var(--accent-dim);
+    background: var(--bg-input);
+  }
+
+  .gallery-card-name {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    font-weight: 500;
+    color: var(--text-primary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .gallery-card-meta {
+    font-family: var(--font-mono);
+    font-size: 9px;
+    color: var(--text-muted);
+    display: flex;
+    gap: 8px;
+  }
+
+  /* ---- ANIMATIONS ---- */
+
+  @keyframes fade-in-up {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  .fade-in {
+    animation: fade-in-up 0.3s ease-out both;
+  }
+
+  /* ---- RESPONSIVE ---- */
+
+  @media (max-width: 768px) {
+    .logo-sub { display: none; }
+    :root { --chat-width: 100vw; }
+    #chat-toggle { display: none; }
+    .gallery-btn span { display: none; }
+  }
+</style>
+</head>
+<body class="chat-open">
+<div id="app">
+
+  <!-- ---- TOP BAR ---- -->
+  <div id="topbar">
+    <div class="logo">
+      <span class="logo-diamond">&#9670;</span>
+      <span class="logo-text">NeuralCAD</span>
+      <span class="logo-sub">Multi-Agent Design</span>
+    </div>
+    <div class="topbar-right">
+      <div class="backend-toggle">
+        <button id="btn-mock" class="active" onclick="setBackend('mock')">MOCK</button>
+        <button id="btn-gemini" onclick="setBackend('gemini')">GEMINI</button>
+        <button id="btn-claude" onclick="setBackend('anthropic')">CLAUDE</button>
+      </div>
+      <button class="gallery-btn" onclick="openGallery()">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/></svg>
+        <span>GALLERY</span>
+      </button>
+      <div class="status-dot" id="status-dot" title="Server Connected"></div>
+    </div>
+  </div>
+
+  <!-- ---- MAIN AREA ---- -->
+  <div id="main">
+
+    <!-- 3D Viewer -->
+    <div id="viewer-container">
+      <canvas id="viewer-canvas"></canvas>
+
+      <div id="geo-stats">
+        <div><span class="stat-label">VOL </span><span class="stat-value" id="stat-volume">&mdash;</span></div>
+        <div><span class="stat-label">BBOX </span><span class="stat-value" id="stat-bbox">&mdash;</span></div>
+        <div><span class="stat-label">FACES </span><span class="stat-value" id="stat-faces">&mdash;</span><span class="stat-label"> EDGES </span><span class="stat-value" id="stat-edges">&mdash;</span></div>
+      </div>
+
+      <div id="cnc-badge">
+        <div class="badge badge-success" id="badge-cnc"></div>
+        <div class="badge badge-info" id="badge-axis"></div>
+      </div>
+
+      <div id="download-btns">
+        <a class="dl-btn" id="dl-step" download>STEP</a>
+        <a class="dl-btn" id="dl-stl" download>STL</a>
+        <a class="dl-btn" id="dl-report" download>REPORT</a>
+      </div>
+
+      <div id="viewer-hint">DRAG ROTATE &middot; SCROLL ZOOM &middot; RIGHT-DRAG PAN</div>
+
+      <div id="viewer-loading">
+        <div class="spinner"></div>
+        <div class="loading-text" id="loading-msg">GENERATING MODEL...</div>
+      </div>
+
+      <div id="viewer-empty">
+        <div class="empty-icon"><div class="empty-icon-inner"></div></div>
+        <div class="empty-text">Start a conversation to<br>design your part</div>
+      </div>
+    </div>
+
+    <!-- Chat Panel -->
+    <div id="chat-panel">
+      <button id="chat-toggle" onclick="toggleChat()" title="Toggle chat panel">&#9664;</button>
+
+      <div class="chat-header">
+        <div class="chat-header-left">
+          <span class="chat-header-title">Design Chat</span>
+          <button onclick="newDesign()" title="New Design" style="background:none;border:1px solid var(--border);border-radius:4px;color:var(--text-secondary);padding:2px 8px;font-size:10px;cursor:pointer;margin-left:8px;">NEW</button>
+          <div class="agent-dots">
+            <div class="agent-dot" style="background: var(--agent-design);" title="Design Agent"></div>
+            <div class="agent-dot" style="background: var(--agent-engineering);" title="Engineering Agent"></div>
+            <div class="agent-dot" style="background: var(--agent-cnc);" title="CNC Agent"></div>
+            <div class="agent-dot" style="background: var(--agent-cad);" title="CAD Coder Agent"></div>
+          </div>
+        </div>
+      </div>
+
+      <div id="chat-messages">
+        <div class="quick-examples" id="quick-examples">
+          <div class="quick-examples-label">Quick Start</div>
+          <div class="quick-chips">
+            <button class="quick-chip" onclick="quickSend('Design a servo bracket')">Design a servo bracket</button>
+            <button class="quick-chip" onclick="quickSend('I need a spur gear')">I need a spur gear</button>
+            <button class="quick-chip" onclick="quickSend('Create a heatsink')">Create a heatsink</button>
+            <button class="quick-chip" onclick="quickSend('Design a pipe flange')">Design a pipe flange</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="chat-input-area" style="position: relative;">
+        <div id="mention-dropdown">
+          <div class="mention-option" data-agent="design" onclick="insertMention('design')">
+            <div class="mention-dot" style="background: var(--agent-design);"></div>
+            <span class="mention-name">@design</span>
+            <span class="mention-role">Design Agent</span>
+          </div>
+          <div class="mention-option" data-agent="engineering" onclick="insertMention('engineering')">
+            <div class="mention-dot" style="background: var(--agent-engineering);"></div>
+            <span class="mention-name">@engineering</span>
+            <span class="mention-role">Engineering Agent</span>
+          </div>
+          <div class="mention-option" data-agent="cnc" onclick="insertMention('cnc')">
+            <div class="mention-dot" style="background: var(--agent-cnc);"></div>
+            <span class="mention-name">@cnc</span>
+            <span class="mention-role">CNC Agent</span>
+          </div>
+          <div class="mention-option" data-agent="cad" onclick="insertMention('cad')">
+            <div class="mention-dot" style="background: var(--agent-cad);"></div>
+            <span class="mention-name">@cad</span>
+            <span class="mention-role">CAD Coder</span>
+          </div>
+        </div>
+        <div class="chat-input-row">
+          <textarea id="chat-input" rows="1" placeholder="Type your message..."></textarea>
+          <button class="chat-btn chat-btn-preview" onclick="sendPreview()" title="Generate 3D preview">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg>
+          </button>
+          <button class="chat-btn chat-btn-send" onclick="sendFromInput()" title="Send message">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="5" y1="12" x2="19" y2="12"/><polyline points="12 5 19 12 12 19"/></svg>
+          </button>
+        </div>
+        <div class="chat-shortcut-hint">Ctrl+Enter to send</div>
+      </div>
+    </div>
+
+  </div>
+</div>
+
+<!-- Floating open pill (when chat collapsed) -->
+<div id="chat-open-pill" onclick="toggleChat()">
+  <span>Open Chat</span>
+  <div class="pill-dots">
+    <div class="pill-dot" style="background: var(--agent-design);"></div>
+    <div class="pill-dot" style="background: var(--agent-engineering);"></div>
+    <div class="pill-dot" style="background: var(--agent-cnc);"></div>
+    <div class="pill-dot" style="background: var(--agent-cad);"></div>
+  </div>
+  <span>&#9654;</span>
+</div>
+
+<!-- Code Viewer Modal -->
+<div id="code-modal">
+  <div class="code-modal-inner">
+    <div class="code-modal-header">
+      <span class="code-modal-title">CadQuery Code</span>
+      <button class="code-modal-close" onclick="closeCodeModal()">&times;</button>
+    </div>
+    <pre id="code-display"></pre>
+  </div>
+</div>
+
+<!-- Gallery Modal -->
+<div id="gallery-modal">
+  <div class="gallery-modal-inner">
+    <div class="gallery-modal-header">
+      <span class="gallery-modal-title">Model Gallery</span>
+      <button class="code-modal-close" onclick="closeGallery()">&times;</button>
+    </div>
+    <div class="gallery-grid" id="gallery-grid">
+      <div class="gallery-empty">No models generated yet.</div>
+    </div>
+  </div>
+</div>
+
+<script>
+// ── STATE ─────────────────────────────────────────────
+
+let currentBackend = 'mock';
+let chatHistory = [];
+let designState = {};
+let chatPanelOpen = true;
+let currentPartName = '';
+let currentCode = '';
+let scene, camera, renderer, controls, currentMesh, gridHelper;
+const galleryItems = [];
+let mentionActive = false;
+let mentionIndex = 0;
+
+// Persist/restore from localStorage
+function saveState() {
+  try {
+    localStorage.setItem('neuralcad_history', JSON.stringify(chatHistory));
+    localStorage.setItem('neuralcad_state', JSON.stringify(designState));
+  } catch (e) { /* quota exceeded, ignore */ }
+}
+
+function loadState() {
+  try {
+    const h = localStorage.getItem('neuralcad_history');
+    const s = localStorage.getItem('neuralcad_state');
+    if (h) chatHistory = JSON.parse(h);
+    if (s) designState = JSON.parse(s);
+  } catch (e) { /* corrupted, ignore */ }
+}
+
+function clearState() {
+  chatHistory = [];
+  designState = {};
+  localStorage.removeItem('neuralcad_history');
+  localStorage.removeItem('neuralcad_state');
+}
+
+function newDesign() {
+  if (!confirm('Start a new design? Current conversation will be cleared.')) return;
+  clearState();
+  // Clear chat UI
+  const msgs = document.getElementById('chat-messages');
+  if (msgs) msgs.innerHTML = '';
+  // Show examples again
+  const examples = document.getElementById('quick-examples');
+  if (examples) examples.style.display = '';
+  // Clear 3D viewer
+  if (currentMesh) {
+    scene.remove(currentMesh);
+    currentMesh.geometry.dispose();
+    currentMesh.material.dispose();
+    currentMesh = null;
+  }
+  // Hide overlays
+  const geo = document.getElementById('geo-stats');
+  if (geo) geo.classList.remove('visible');
+  const cnc = document.getElementById('cnc-badge');
+  if (cnc) cnc.classList.remove('visible');
+  const dl = document.getElementById('download-btns');
+  if (dl) dl.classList.remove('visible');
+  // Show empty state
+  const empty = document.getElementById('viewer-empty');
+  if (empty) empty.style.display = '';
+}
+
+const AGENTS = {
+  design:      { name: 'Design',      color: '#7c3aed', avatar: 'D' },
+  engineering: { name: 'Engineering', color: '#00b4d8', avatar: 'E' },
+  cnc:         { name: 'CNC',         color: '#00e676', avatar: 'C' },
+  cad:         { name: 'CAD Coder',   color: '#ffab40', avatar: '{}'  },
+};
+
+// ── THREE.JS SETUP ────────────────────────────────────
+
+function initViewer() {
+  const canvas = document.getElementById('viewer-canvas');
+  const container = document.getElementById('viewer-container');
+
+  scene = new THREE.Scene();
+
+  // Camera
+  camera = new THREE.PerspectiveCamera(45, container.clientWidth / container.clientHeight, 0.1, 10000);
+  camera.position.set(120, 80, 120);
+
+  // Renderer
+  renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
+  renderer.setPixelRatio(window.devicePixelRatio);
+  renderer.setSize(container.clientWidth, container.clientHeight);
+  renderer.setClearColor(0x06080c, 1);
+  renderer.shadowMap.enabled = true;
+
+  // Lights
+  const ambient = new THREE.AmbientLight(0x334466, 0.6);
+  scene.add(ambient);
+
+  const dirLight1 = new THREE.DirectionalLight(0xddeeff, 0.8);
+  dirLight1.position.set(100, 150, 100);
+  dirLight1.castShadow = true;
+  scene.add(dirLight1);
+
+  const dirLight2 = new THREE.DirectionalLight(0x8899bb, 0.4);
+  dirLight2.position.set(-80, 60, -60);
+  scene.add(dirLight2);
+
+  const rimLight = new THREE.DirectionalLight(0x00b4d8, 0.15);
+  rimLight.position.set(0, -50, 100);
+  scene.add(rimLight);
+
+  // Grid helper
+  gridHelper = new THREE.GridHelper(400, 40, 0x1a2636, 0x111822);
+  gridHelper.position.y = -0.5;
+  scene.add(gridHelper);
+
+  // Controls
+  controls = new THREE.OrbitControls(camera, renderer.domElement);
+  controls.enableDamping = true;
+  controls.dampingFactor = 0.08;
+  controls.rotateSpeed = 0.6;
+  controls.minDistance = 10;
+  controls.maxDistance = 2000;
+
+  // Handle resize
+  const ro = new ResizeObserver(() => {
+    const w = container.clientWidth;
+    const h = container.clientHeight;
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h);
+  });
+  ro.observe(container);
+
+  animate();
+}
+
+function animate() {
+  requestAnimationFrame(animate);
+  controls.update();
+  renderer.render(scene, camera);
+}
+
+function loadSTL(url) {
+  return new Promise((resolve, reject) => {
+    const loader = new THREE.STLLoader();
+    loader.load(url, (geometry) => {
+      if (currentMesh) {
+        scene.remove(currentMesh);
+        currentMesh.geometry.dispose();
+        currentMesh.material.dispose();
+      }
+
+      const material = new THREE.MeshPhongMaterial({
+        color: 0x7799aa,
+        specular: 0x445566,
+        shininess: 60,
+        flatShading: false,
+      });
+
+      const mesh = new THREE.Mesh(geometry, material);
+      mesh.castShadow = true;
+      mesh.receiveShadow = true;
+
+      geometry.computeBoundingBox();
+      const center = new THREE.Vector3();
+      geometry.boundingBox.getCenter(center);
+      mesh.position.sub(center);
+
+      scene.add(mesh);
+      currentMesh = mesh;
+
+      // Fit camera
+      const size = new THREE.Vector3();
+      geometry.boundingBox.getSize(size);
+      const maxDim = Math.max(size.x, size.y, size.z);
+      const dist = maxDim * 2.5;
+      camera.position.set(dist * 0.7, dist * 0.5, dist * 0.7);
+      controls.target.set(0, 0, 0);
+      controls.update();
+
+      // Update grid to match model scale
+      if (gridHelper) {
+        gridHelper.position.y = -size.y / 2 - 0.5;
+      }
+
+      document.getElementById('viewer-empty').style.display = 'none';
+      resolve();
+    }, undefined, reject);
+  });
+}
+
+// ── BACKEND TOGGLE ────────────────────────────────────
+
+function setBackend(name) {
+  currentBackend = name;
+  document.getElementById('btn-mock').classList.toggle('active', name === 'mock');
+  document.getElementById('btn-gemini').classList.toggle('active', name === 'gemini');
+  document.getElementById('btn-claude').classList.toggle('active', name === 'anthropic');
+}
+
+// ── CHAT PANEL TOGGLE ─────────────────────────────────
+
+function toggleChat() {
+  chatPanelOpen = !chatPanelOpen;
+  const panel = document.getElementById('chat-panel');
+  const pill = document.getElementById('chat-open-pill');
+  const toggle = document.getElementById('chat-toggle');
+
+  if (chatPanelOpen) {
+    panel.classList.remove('collapsed');
+    pill.classList.remove('visible');
+    toggle.innerHTML = '&#9664;';
+    document.body.classList.add('chat-open');
+  } else {
+    panel.classList.add('collapsed');
+    pill.classList.add('visible');
+    toggle.innerHTML = '&#9654;';
+    document.body.classList.remove('chat-open');
+  }
+}
+
+// ── CHAT MESSAGING ────────────────────────────────────
+
+async function sendMessage(text) {
+  if (!text.trim()) return;
+
+  // Parse @mentions
+  const mentions = [];
+  const mentionRegex = /@(design|engineering|cnc|cad)\b/gi;
+  let match;
+  while ((match = mentionRegex.exec(text)) !== null) {
+    mentions.push(match[1].toLowerCase());
+  }
+  const cleanedText = text.replace(mentionRegex, '').trim();
+
+  // Hide quick examples
+  const examples = document.getElementById('quick-examples');
+  if (examples) examples.style.display = 'none';
+
+  // Add user message to UI
+  addMessage({ role: 'user', content: text });
+
+  // Show typing
+  showTyping();
+
+  try {
+    // Send history WITHOUT the current message (backend appends it)
+    const resp = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        message: cleanedText,
+        history: chatHistory,
+        mentions: mentions,
+        backend: currentBackend,
+        design_state: designState,
+      }),
+    });
+
+    // Add to history AFTER sending (so it's included in future turns)
+    chatHistory.push({ role: 'user', content: text });
+    saveState();
+    const data = await resp.json();
+
+    hideTyping();
+
+    // Add agent responses
+    for (const r of data.responses) {
+      addMessage({
+        role: 'agent',
+        agent_id: r.agent_id,
+        agent_name: r.agent_name,
+        content: r.message,
+        color: r.color,
+        avatar: r.avatar,
+        code: r.code,
+      });
+      chatHistory.push({ role: 'agent', agent_id: r.agent_id, content: r.message });
+    }
+
+    if (data.design_state) {
+      designState = data.design_state;
+    }
+    saveState();
+
+    // If preview available, load 3D model
+    if (data.preview && data.preview.success) {
+      setViewerLoading(true, 'LOADING 3D MODEL...');
+      try {
+        await loadSTL(data.preview.stl_url);
+      } catch (e) {
+        console.warn('STL load failed:', e);
+      }
+      setViewerLoading(false);
+      updateGeoStats(data.preview.execution);
+      updateCNCBadge(data.preview.validation);
+      updateDownloads(data.preview.part_name);
+
+      if (data.preview.part_name) {
+        currentPartName = data.preview.part_name;
+        addToGallery(data.preview);
+      }
+    }
+  } catch (err) {
+    hideTyping();
+    addMessage({
+      role: 'agent',
+      agent_id: 'system',
+      agent_name: 'System',
+      content: 'Error: ' + err.message,
+      color: '#ff5252',
+      avatar: '!',
+    });
+  }
+}
+
+function sendFromInput() {
+  const input = document.getElementById('chat-input');
+  const text = input.value.trim();
+  if (!text) return;
+  input.value = '';
+  input.style.height = 'auto';
+  closeMentionDropdown();
+  sendMessage(text);
+}
+
+function sendPreview() {
+  sendMessage('@cad Generate a 3D preview based on our discussion');
+}
+
+function quickSend(text) {
+  const examples = document.getElementById('quick-examples');
+  if (examples) examples.style.display = 'none';
+  sendMessage(text);
+}
+
+// ── MESSAGE RENDERING ─────────────────────────────────
+
+function addMessage(msg) {
+  const container = document.getElementById('chat-messages');
+
+  const el = document.createElement('div');
+
+  if (msg.role === 'user') {
+    el.className = 'msg msg-user';
+    el.innerHTML = '<div class="msg-bubble">' + escapeHtml(msg.content) + '</div>';
+  } else {
+    const agentId = msg.agent_id || 'system';
+    const agentInfo = AGENTS[agentId] || { name: msg.agent_name || 'Agent', color: msg.color || '#5a7089', avatar: '?' };
+    const color = msg.color || agentInfo.color;
+    const avatar = msg.avatar || agentInfo.avatar;
+    const name = msg.agent_name || agentInfo.name;
+    const isCad = agentId === 'cad';
+
+    el.className = 'msg msg-agent';
+
+    let html = '<div class="msg-avatar" style="background: ' + color + ';">' + avatar + '</div>';
+    html += '<div class="msg-agent-body">';
+    html += '<div class="msg-agent-name" style="color: ' + color + ';">' + escapeHtml(name) + '</div>';
+    html += '<div class="msg-agent-bubble' + (isCad ? ' cad-bubble' : '') + '">' + escapeHtml(msg.content);
+
+    if (msg.code) {
+      currentCode = msg.code;
+      html += '<br><a class="msg-view-code" onclick="openCodeModal()">&#9654; View code</a>';
+    }
+
+    html += '</div></div>';
+    el.innerHTML = html;
+  }
+
+  container.appendChild(el);
+  scrollChatToBottom();
+}
+
+function showTyping() {
+  const container = document.getElementById('chat-messages');
+  const el = document.createElement('div');
+  el.className = 'typing-indicator';
+  el.id = 'typing-indicator';
+  el.innerHTML = '<div class="typing-dots"><span></span><span></span><span></span></div><span class="typing-label">Agents are thinking...</span>';
+  container.appendChild(el);
+  scrollChatToBottom();
+}
+
+function hideTyping() {
+  const el = document.getElementById('typing-indicator');
+  if (el) el.remove();
+}
+
+function scrollChatToBottom() {
+  const container = document.getElementById('chat-messages');
+  requestAnimationFrame(() => {
+    container.scrollTop = container.scrollHeight;
+  });
+}
+
+// ── @MENTION AUTOCOMPLETE ─────────────────────────────
+
+const mentionAgents = ['design', 'engineering', 'cnc', 'cad'];
+
+function handleInputForMention(e) {
+  const input = document.getElementById('chat-input');
+  const val = input.value;
+  const pos = input.selectionStart;
+
+  // Find @ before cursor
+  const before = val.substring(0, pos);
+  const atMatch = before.match(/@(\w*)$/);
+
+  if (atMatch) {
+    const query = atMatch[1].toLowerCase();
+    const filtered = mentionAgents.filter(a => a.startsWith(query));
+
+    if (filtered.length > 0) {
+      showMentionDropdown(filtered);
+      mentionActive = true;
+      return;
+    }
+  }
+
+  closeMentionDropdown();
+}
+
+function showMentionDropdown(filtered) {
+  const dropdown = document.getElementById('mention-dropdown');
+  const options = dropdown.querySelectorAll('.mention-option');
+  let visibleCount = 0;
+
+  options.forEach(opt => {
+    const agent = opt.dataset.agent;
+    if (filtered.includes(agent)) {
+      opt.style.display = 'flex';
+      visibleCount++;
+    } else {
+      opt.style.display = 'none';
+    }
+  });
+
+  if (visibleCount > 0) {
+    dropdown.classList.add('visible');
+    mentionIndex = 0;
+    updateMentionHighlight();
+  }
+}
+
+function closeMentionDropdown() {
+  document.getElementById('mention-dropdown').classList.remove('visible');
+  mentionActive = false;
+}
+
+function updateMentionHighlight() {
+  const options = Array.from(document.querySelectorAll('#mention-dropdown .mention-option'))
+    .filter(o => o.style.display !== 'none');
+  options.forEach((o, i) => o.classList.toggle('active', i === mentionIndex));
+}
+
+function insertMention(agent) {
+  const input = document.getElementById('chat-input');
+  const val = input.value;
+  const pos = input.selectionStart;
+  const before = val.substring(0, pos);
+  const after = val.substring(pos);
+  const atPos = before.lastIndexOf('@');
+
+  input.value = before.substring(0, atPos) + '@' + agent + ' ' + after;
+  input.focus();
+  const newPos = atPos + agent.length + 2;
+  input.setSelectionRange(newPos, newPos);
+  closeMentionDropdown();
+}
+
+// ── UI UPDATES ────────────────────────────────────────
+
+function setViewerLoading(on, msg) {
+  const el = document.getElementById('viewer-loading');
+  if (on) {
+    el.classList.add('visible');
+    document.getElementById('loading-msg').textContent = msg || 'GENERATING...';
+  } else {
+    el.classList.remove('visible');
+  }
+}
+
+function updateGeoStats(exec) {
+  if (!exec || !exec.success) return;
+  const el = document.getElementById('geo-stats');
+  el.classList.add('visible');
+
+  const vol = exec.volume_mm3;
+  document.getElementById('stat-volume').textContent =
+    vol > 1000 ? (vol / 1000).toFixed(1) + ' cm\u00B3' : vol.toFixed(1) + ' mm\u00B3';
+
+  const bbox = exec.bounding_box_mm;
+  if (bbox && bbox.length === 3) {
+    document.getElementById('stat-bbox').textContent =
+      bbox.map(v => v.toFixed(1)).join(' \u00D7 ') + ' mm';
+  }
+
+  document.getElementById('stat-faces').textContent = exec.face_count || '\u2014';
+  document.getElementById('stat-edges').textContent = exec.edge_count || '\u2014';
+}
+
+function updateCNCBadge(validation) {
+  const el = document.getElementById('cnc-badge');
+  if (!validation) { el.classList.remove('visible'); return; }
+  el.classList.add('visible');
+
+  const cncBadge = document.getElementById('badge-cnc');
+  if (validation.machinable) {
+    cncBadge.className = 'badge badge-success';
+    cncBadge.textContent = '\u2713 CNC MACHINABLE';
+  } else {
+    cncBadge.className = 'badge badge-error';
+    cncBadge.textContent = '\u2717 NOT MACHINABLE';
+  }
+
+  const axisBadge = document.getElementById('badge-axis');
+  axisBadge.textContent = (validation.axis_recommendation || '').toUpperCase();
+}
+
+function updateDownloads(partName) {
+  const el = document.getElementById('download-btns');
+  if (!partName) { el.classList.remove('visible'); return; }
+  el.classList.add('visible');
+
+  document.getElementById('dl-step').href = '/api/models/' + partName + '.step';
+  document.getElementById('dl-stl').href = '/api/models/' + partName + '.stl';
+  document.getElementById('dl-report').href = '/api/models/' + partName + '_report.json';
+}
+
+// ── CODE MODAL ────────────────────────────────────────
+
+function openCodeModal() {
+  const modal = document.getElementById('code-modal');
+  const display = document.getElementById('code-display');
+
+  if (currentCode) {
+    display.innerHTML = highlightPython(currentCode);
+  } else {
+    display.textContent = 'No code available.';
+  }
+
+  modal.classList.add('visible');
+}
+
+function closeCodeModal() {
+  document.getElementById('code-modal').classList.remove('visible');
+}
+
+function highlightPython(code) {
+  let escaped = code
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+
+  escaped = escaped.replace(/(#.*$)/gm, '<span class="cm">$1</span>');
+  escaped = escaped.replace(/("""[\s\S]*?"""|'''[\s\S]*?'''|"[^"\n]*"|'[^'\n]*')/g, '<span class="st">$1</span>');
+
+  const kw = /\b(import|from|as|def|class|return|if|else|elif|for|while|in|not|and|or|True|False|None|with|try|except|finally|raise|pass|break|continue|lambda|yield)\b/g;
+  escaped = escaped.replace(kw, '<span class="kw">$1</span>');
+  escaped = escaped.replace(/\b(\d+\.?\d*)\b/g, '<span class="nu">$1</span>');
+  escaped = escaped.replace(/\.([a-zA-Z_]\w*)\(/g, '.<span class="fn">$1</span>(');
+
+  return escaped;
+}
+
+// ── GALLERY ───────────────────────────────────────────
+
+function addToGallery(data) {
+  galleryItems.unshift({
+    name: data.part_name,
+    volume: data.execution?.volume_mm3,
+    faces: data.execution?.face_count,
+    machinable: data.validation?.machinable,
+  });
+}
+
+function openGallery() {
+  renderGallery();
+  document.getElementById('gallery-modal').classList.add('visible');
+}
+
+function closeGallery() {
+  document.getElementById('gallery-modal').classList.remove('visible');
+}
+
+function renderGallery() {
+  const grid = document.getElementById('gallery-grid');
+
+  if (galleryItems.length === 0) {
+    grid.innerHTML = '<div class="gallery-empty">No models generated yet.</div>';
+    return;
+  }
+
+  let html = '';
+  for (const item of galleryItems) {
+    html += '<button class="gallery-card fade-in" onclick="loadGalleryItem(\'' + escapeHtml(item.name) + '\')">';
+    html += '<div class="gallery-card-name">' + escapeHtml(item.name) + '</div>';
+    html += '<div class="gallery-card-meta">';
+    if (item.faces) html += '<span>' + item.faces + ' faces</span>';
+    if (item.machinable !== undefined) {
+      html += '<span style="color:' + (item.machinable ? 'var(--success)' : 'var(--error)') + '">'
+        + (item.machinable ? '\u2713 CNC' : '\u2717 CNC') + '</span>';
+    }
+    html += '</div></button>';
+  }
+
+  grid.innerHTML = html;
+}
+
+async function loadGalleryItem(name) {
+  closeGallery();
+  setViewerLoading(true, 'LOADING MODEL...');
+  try {
+    await loadSTL('/api/models/' + name + '.stl');
+  } catch (e) {
+    console.warn('Failed to load:', e);
+  }
+  setViewerLoading(false);
+}
+
+// ── UTILS ─────────────────────────────────────────────
+
+function escapeHtml(str) {
+  const div = document.createElement('div');
+  div.textContent = str;
+  return div.innerHTML;
+}
+
+// ── SERVER STATUS CHECK ───────────────────────────────
+
+async function checkServer() {
+  try {
+    const resp = await fetch('/api/capabilities');
+    const dot = document.getElementById('status-dot');
+    if (resp.ok) {
+      dot.style.background = 'var(--success)';
+      dot.style.boxShadow = '0 0 6px var(--success)';
+      dot.title = 'Server Connected';
+    } else {
+      dot.style.background = 'var(--warning)';
+      dot.style.boxShadow = '0 0 6px var(--warning)';
+      dot.title = 'Server Error';
+    }
+  } catch {
+    const dot = document.getElementById('status-dot');
+    dot.style.background = 'var(--error)';
+    dot.style.boxShadow = '0 0 6px var(--error)';
+    dot.title = 'Server Offline';
+  }
+}
+
+// ── KEYBOARD / INPUT EVENTS ──────────────────────────
+
+const chatInput = document.getElementById('chat-input');
+
+chatInput.addEventListener('input', (e) => {
+  // Auto-resize
+  chatInput.style.height = 'auto';
+  chatInput.style.height = Math.min(chatInput.scrollHeight, 120) + 'px';
+
+  // Check for @mention
+  handleInputForMention(e);
+});
+
+chatInput.addEventListener('keydown', (e) => {
+  if (mentionActive) {
+    const dropdown = document.getElementById('mention-dropdown');
+    const visibleOptions = Array.from(dropdown.querySelectorAll('.mention-option'))
+      .filter(o => o.style.display !== 'none');
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      mentionIndex = (mentionIndex + 1) % visibleOptions.length;
+      updateMentionHighlight();
+      return;
+    }
+    if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      mentionIndex = (mentionIndex - 1 + visibleOptions.length) % visibleOptions.length;
+      updateMentionHighlight();
+      return;
+    }
+    if (e.key === 'Enter' || e.key === 'Tab') {
+      e.preventDefault();
+      const agent = visibleOptions[mentionIndex]?.dataset.agent;
+      if (agent) insertMention(agent);
+      return;
+    }
+    if (e.key === 'Escape') {
+      closeMentionDropdown();
+      return;
+    }
+  }
+
+  if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
+    e.preventDefault();
+    sendFromInput();
+  }
+
+  // Regular enter sends (without shift)
+  if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.metaKey) {
+    e.preventDefault();
+    sendFromInput();
+  }
+});
+
+// Close modals on backdrop click
+document.getElementById('code-modal').addEventListener('click', (e) => {
+  if (e.target === document.getElementById('code-modal')) closeCodeModal();
+});
+
+document.getElementById('gallery-modal').addEventListener('click', (e) => {
+  if (e.target === document.getElementById('gallery-modal')) closeGallery();
+});
+
+// Escape to close modals
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') {
+    closeCodeModal();
+    closeGallery();
+  }
+});
+
+// ── INIT ──────────────────────────────────────────────
+
+initViewer();
+checkServer();
+setInterval(checkServer, 15000);
+
+loadState();
+// Re-render restored messages
+if (chatHistory.length > 0) {
+  const examples = document.getElementById('quick-examples');
+  if (examples) examples.style.display = 'none';
+  for (const msg of chatHistory) {
+    addMessage(msg);
+  }
+}
+</script>
+</body>
+</html>