README.md

metadata

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

# 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

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

# 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

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

# 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

# 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

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