README.md

---
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 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 |

## 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