PiCAD

A low-code platform for CAD modeling assisted by large language models.

Overview

PiCAD makes CAD modeling accessible through low-code workflows powered by large language models (LLMs). Instead of writing complex scripts or mastering intricate CAD software, users describe what they want to build in natural language and the platform translates intent into parametric models — from single parts to multi-part mated assemblies.

Features

• Natural-language-driven modeling — describe parts and assemblies in plain text, LLMs turn them into CAD geometry
• Low-code workflow — parametric design through declarative, statically-validatable workflow JSON instead of imperative scripting
• Phased assembly pipeline — plan → per-part generation → mate-as-designed assembly → optional vision-model review, each phase gated and auto-repaired
• Native MbD assembly — semantic anchors (TNP-immune), closed-form mates (seat/concentric/coincident), and a JSON diagnostics quality gate (JCS gap, interference, containment, clearance)
• Rich node library — sketches/datums, features (loft, sweep, helix, fillet/chamfer, thread, patterns), booleans, transforms, parametric curves/surfaces including function-expression geometry (curve.parametric, surface.parametric, surface.heightfield, surface.thicken), assembly, and inspect.assert quality gates
• Live FreeCAD integration — XML-RPC addon drives a running FreeCAD GUI: node-by-node execution, screenshots, HD renders, and live measurements
• Agent-ready — a standalone modeling skill (skill/) lets coding agents (Claude Code, ZCode, …) probe, validate, run, and check models from any directory
• LLM-assisted design iteration — validation errors feed back as repair prompts; the assistant understands design intent

Workflow Platform

The core of PiCAD is a workflow harness for LLMs: models emit bounded, statically-validatable workflow JSON instead of free-form CAD code; the engine executes it node-by-node against a live FreeCAD GUI; validation errors feed back as repair prompts. A web canvas lets humans inspect and adjust every step.

 natural language ──► LLM ──► workflow JSON ──► validate ──► engine
                                      ▲            │            │
                                      └──── issues ┘            ▼
                                                     FreeCAD GUI (PiCAD addon)
 web canvas (React Flow) ◄── SSE node status/screenshots ────────┘

• src/flow/ — schema, sandboxed expressions, registry, validator, engine, node library
• src/geom/ — advanced 3D builders: profiles, loft/sweep/helix/thread, parametric & function-expression curves/surfaces, thicken, STEP I/O
• src/assembly/ — anchors, mate-as-designed builder, closed-form mates, diagnostics
• src/server/ — FastAPI backend: /api/nodes, /api/workflow/validate|run (SSE), /api/llm/generate_and_run, /api/llm/design_and_assemble, /api/library, /api/render
• src/liveview/ + src/livetools/ — live RPC client (heartbeat + auto-reconnect) and tools: screenshot, set_view, fit_view, measure
• web/ — React Flow canvas (Vite + TypeScript); zero hardcoded node knowledge
• web/library/ — reusable sub-workflow templates (composite workflow node)
• examples/workflows/ — runnable example JSON (flange, bracket, spring, vase, airplane, helicopter, sports car, turbine blade, …)
• skill/ — agent-facing modeling skill (probe / validate / run / check / card)
• benchmarks/ — LLM-harness benchmark suite with scoring and failure-analysis reports

Quickstart

pip install -r requirements-server.txt
# 1. install the PiCAD addon (addon/install.ps1) and start FreeCAD GUI —
#    its RPC auto-starts on 127.0.0.1:9876
# 2. backend (serves the built frontend too):
uvicorn server.app:app --app-dir src --host 127.0.0.1 --port 8321
# 3. or, for frontend development:
cd web && npm i && npm run dev

Open http://127.0.0.1:8321/ — drag nodes, or press AI Generate.

Headless example runs (no server needed, FreeCAD GUI must be up):

python examples/run_workflow.py examples/workflows/flange.json
python examples/run_workflow.py examples/workflows/flange_pattern.json

LLM configuration

Set these env vars for any OpenAI-compatible endpoint (works with Ollama's /v1):

PICAD_LLM_BASE_URL=http://127.0.0.1:11434/v1
PICAD_LLM_API_KEY=ollama          # any non-empty string for local providers
PICAD_LLM_MODEL=qwen2.5-coder

Or skip env vars entirely: open the web UI → Settings and fill in the same three values. The UI writes .picad-llm.json (gitignored) at the repo root; per field, the file takes precedence over env vars. An optional "vision" section configures a VLM for the assembly-review phase.

Generation and repair share one guarded loop: LLM → extract JSON → static validation → feed issues back (≤3 attempts). The LLM can only ever produce workflow JSON — execution capability stays inside registered nodes.

Docs & tests

• Workflow JSON contract: docs/workflow-format.md
• Tests: python tests/test_flow_engine.py (and siblings), cd web && npx vitest run
• Headless geometry/assembly tests: D:/FreeCAD/bin/freecadcmd.exe tests/test_geom_builders.py

License

TBD