Graph-CAD: Why Top AI Researchers Abandoned End-to-End CAD Generation

What if I told you that GPT-5, Claude Opus 4.1, and every other massive language model are fundamentally broken for one critical task? Not broken in the flashy, headline-grabbing way. Broken in the silent, expensive way that wastes engineering hours and produces unbuildable 3D models.

I'm talking about Text-to-CAD generation—the holy grail of turning natural language into executable manufacturing instructions. For years, the dominant approach was brutally simple: feed text into a giant LLM, pray it outputs valid Blender Python^{↗ Bright Coding Blog} code, and hope the resulting geometry doesn't collapse into an impossible nightmare of intersecting surfaces and violated constraints.

The results? Catastrophic error propagation. A single misinterpreted spatial relationship in step 3 of a 50-step assembly cascades into complete structural failure by step 47. Syntax error rates exceeding 48% for some proprietary models. Geometric constraint satisfaction scores so low that the generated models are physically unmanufacturable.

But something extraordinary just happened at ICLR 2026. A team of researchers from the EESJ lab didn't just incrementally improve Text-to-CAD—they reinvented the entire architecture. Their secret weapon? A hierarchical, geometry-aware graph that sits between language and code, acting as a semantic shock absorber against error propagation.

Welcome to Graph-CAD (https://github.com/EESJGong/Graph-CAD)—the framework that doesn't just generate CAD code, but thinks in structures before it ever writes a line of Python.

What is Graph-CAD?

Graph-CAD is a graph-mediated Text-to-CAD framework for long-horizon CAD code generation, developed by Shengjie Gong, Wenjie Peng, Hongyuan Chen, and colleagues. Accepted to ICLR 2026, this research project represents a fundamental architectural departure from every existing approach in the field.

Instead of directly decoding natural language into executable bpy (Blender Python) code—a paradigm that has dominated since the first Text-to-CAD experiments—Graph-CAD introduces an intermediate hierarchical representation that explicitly models product structure, geometric constraints, and assembly relationships before any code generation occurs.

The core insight is devastatingly simple once you see it: natural language describes what to build, but manufacturing requires knowing how parts relate to each other spatially and structurally. By forcing the model to first predict a structured graph of decomposition and constraints, Graph-CAD separates "understanding the design intent" from "executing the construction steps"—preventing the catastrophic error cascades that plague end-to-end systems.

The framework is built on Qwen3-8B as its base model, fine-tuned through a sophisticated curriculum learning regime, and trained on the BlendGeo dataset—a 12,000-sample corpus pairing instructions, decomposition graphs, action sequences, and executable Blender code. The model weights are publicly available through ModelScope, making this one of the most accessible high-performance CAD generation systems ever released.

What's particularly striking is Graph-CAD's performance against industrial-strength competition. On geometric constraint satisfaction (GCS)—the metric that truly matters for manufacturability—Graph-CAD (SAPCL) achieves 0.9018 on CADBench-Sim and 0.8943 on CADBench-Wild. GPT-5? 0.3846 and 0.4017 respectively. Claude Opus 4.1? 0.4932 and 0.5062. The gap isn't incremental; it's a different category of capability.

Key Features That Redefine Text-to-CAD

Graph-Mediated Generation: The Secret Sauce

At the heart of Graph-CAD lies its hierarchical geometric decomposition graph. Starting from the whole object, the model performs top-down decomposition until each part can be realized by primitive Blender operators. Parts and subcomponents become nodes; spatial relations like alignment and attachment become explicit geometric constraints on edges.

This graph structure serves three critical functions:

Error containment: Local mistakes in graph prediction don't automatically corrupt the entire assembly
Constraint verification: Geometric relationships are checked at the graph level before code generation
Structural coherence: The hierarchy enforces logical part-whole relationships that pure sequence models ignore

Three-Stage Inference Pipeline

Graph-CAD deliberately fragments generation into three sequential stages, each with reduced complexity compared to monolithic end-to-end decoding:

Geometry Decomposition: Predict hierarchical graph with geometric constraints from user instruction
Action Planning: Convert graph into ordered CAD action sequence respecting assembly structure
Code Generation: Translate planned actions into executable bpy code

This staged design reduces the search space at each step and improves both geometric fidelity and constraint satisfaction. The ablation studies prove both intermediate stages are essential—removing either degrades performance significantly.

Structure-Aware Progressive Curriculum Learning (SAPCL)

Perhaps the most technically sophisticated innovation, SAPCL alternates between Supervised Fine-Tuning (SFT) and Structure-aware Progressive Curriculum Exploration (SAPCE):

SAPCE samples seed instances and uses a problem generator to create graded difficulty variants
A discriminator estimates the model's capability boundary
Boundary data generation synthesizes new training samples near that frontier
Validated samples merge back for the next SFT round

This creates a self-improving training loop that progressively masters more complex decomposition graphs—explaining why Graph-CAD (SAPCL) dramatically outperforms even its own SFT baseline.

Comprehensive Evaluation Beyond Surface Metrics

Unlike projects that optimize for pretty renders alone, Graph-CAD evaluates:

Graph quality: Structural correctness of the intermediate representation
Rendered output quality: Visual fidelity of final 3D models
Geometric constraint satisfaction: Physical manufacturability and spatial relationship accuracy
Syntax executability: Whether generated code actually runs without errors

Use Cases Where Graph-CAD Absolutely Dominates

1. Complex Multi-Part Mechanical Assemblies

Imagine describing "a gear reduction box with input shaft, output shaft, three helical gears, bearing housings, and a split casing with bolted flanges." End-to-end models routinely fail on such descriptions—generating gears that don't mesh, shafts with impossible clearances, or casings that can't physically separate.

Graph-CAD's hierarchical decomposition first establishes the casing as the root node, then attaches bearing housings with constraint edges specifying concentricity and axial positioning, then adds shafts with diameter and length constraints, and finally places gears with meshing relationships. Only after this structural verification does code generation begin.

2. Architectural Elements with Strict Dimensional Constraints

"A bay window with three angled panels, each containing a double-hung sash with specific mullion spacing, integrated seat with storage, and exterior trim matching existing colonial molding profiles."

The geometric constraint graph captures angular relationships between panels, mullion spacing regularity, and trim profile continuity—constraints that pure sequence models violate because they have no mechanism to enforce global consistency across distant code positions.

3. Consumer Product Design with Assembly Sequences

Modern product design requires thinking about manufacturing order, not just final geometry. A wireless earbuds case needs: base shell → battery cavity → hinge boss → lid shell → magnet pockets → charging coil recess → exterior curvature continuity.

Graph-CAD's action planning stage explicitly orders operations based on assembly dependencies—ensuring that features requiring access from specific directions are created before that access is blocked by subsequent geometry.

4. Parametric Design Variations from Natural Language

"Same chair design but with wider seat, taller back, and switched from four legs to pedestal base." Traditional systems often regenerate from scratch, losing design coherence. Graph-CAD can modify the decomposition graph—preserving structural relationships while adjusting parameters—then replan actions and regenerate code with guaranteed consistency.

Step-by-Step Installation & Setup Guide

Ready to run Graph-CAD yourself? The setup is straightforward but requires attention to path dependencies. Follow these exact steps:

Step 1: Clone Repositories

# Clone Graph-CAD main repository
git clone https://github.com/EESJGong/Graph-CAD.git
cd Graph-CAD

# Clone LlamaFactory dependency (required for model serving)
git clone https://github.com/hiyouga/LlamaFactory

Step 2: Create Conda Environment

# Create isolated Python 3.10 environment
conda create -n graphcad python=3.10 -y
conda activate graphcad

Step 3: Install Python Dependencies

cd LlamaFactory
pip install -e .                    # Install LlamaFactory in editable mode
pip install -r requirements/metrics.txt  # Evaluation metrics dependencies
pip install openai                  # API compatibility layer
pip install modelscope              # Model download from Chinese hub
cd ..

Step 4: Install Blender for Execution and Rendering

# Download Blender 4.4.1 (Linux x64)
wget https://download.blender.org/release/Blender4.4/blender-4.4.1-linux-x64.tar.xz
tar -xf blender-4.4.1-linux-x64.tar.xz

Step 5: Download Model Weights

# Create directory for base model
mkdir -p qwen3

# Download Qwen3-8B base model (~15GB)
modelscope download --model Qwen/Qwen3-8B --local_dir ./qwen3

# Create checkpoint directory structure
mkdir -p checkpoints

# Download Graph-CAD stage adapters from ModelScope
modelscope download --model JackeySmile/graph-cad --local_dir ./checkpoints

Critical Path Verification

Before running inference, confirm these paths exist:

# Verify all required directories
ls ./qwen3                          # Base model weights
ls ./checkpoints/stage1             # Geometry decomposition adapter
ls ./checkpoints/stage2             # Action planning adapter
ls ./checkpoints/stage3             # Code generation adapter
ls ./prompt_sft                     # System prompts for each stage
ls ./output                         # Output directory (create if missing)
ls ./blender-4.4.1-linux-x64        # Blender installation

Pro tip: The checkpoints download from ModelScope should automatically create the stage1/, stage2/, and stage3/ subdirectories. If not, manually organize the downloaded files accordingly.

REAL Code Examples from the Repository

Let's examine the actual implementation patterns from Graph-CAD's codebase, with detailed explanations of how each component functions.

Example 1: Running the Complete Inference Pipeline

The simplest entry point is infer_api.py, which orchestrates all three stages with default repository-local paths:

# Execute the full three-stage pipeline
python infer_api.py

This single command performs the complete workflow: loading the base Qwen3-8B model with stage-specific LoRA adapters, reading instructions from ./CADBench.jsonl, predicting decomposition graphs, converting to action sequences, and finally generating executable bpy code in ./output/result_name.

Behind the scenes, the script manages:

Model loading: Qwen3-8B base with three sequentially-applied adapters
Prompt templating: Loading stage-appropriate system prompts from ./prompt_sft/
Chain-of-generation: Stage 1 output feeds Stage 2 input feeds Stage 3 input
Error handling: Graceful degradation if intermediate stages produce invalid structures

The default paths are hardcoded for reproducibility, making this ideal for benchmarking against published results.

Example 2: Automated Rendering of Generated Models

After inference produces bpy.txt files, visualization requires Blender execution:

python render_auto.py \
  --base_dir output/result_name \
  --all \
  --blender_executable ./blender-4.4.1-linux-x64/blender

Parameter breakdown:

--base_dir output/result_name: Root directory containing generated .txt files with embedded bpy code
--all: Batch-process all subfolders under the target—essential for benchmark evaluation
--blender_executable ./blender-4.4.1-linux-x64/blender: Explicit path to Blender binary; modify if you installed differently

Additional flags for advanced usage:

  --recursive              # Search nested subdirectories for .txt files
  --overwrite              # Force re-render even if .png already exists
  --timeout 300            # Kill hung renders after 5 minutes

This rendering step is not merely visualization—it's verification. Many competing Text-to-CAD systems generate code that looks plausible but fails to execute. Graph-CAD's 2.0% syntax error rate (vs. 48.4% for Qwen-Plus) means most renders succeed, but the pipeline still validates executability.

Example 3: Evaluation Against Benchmarks

For rigorous comparison with published results, use the evaluation script:

python evaluate_and_report.py \
  --api-base YOUR_BASE_URL \
  --api-key YOUR_API_KEY \
  --model YOUR_MODEL_NAME

Critical configuration:

--api-base: Your LLM service endpoint (OpenAI-compatible format)
--api-key: Authentication token
--model: Model identifier for judge/evaluator LLM

The evaluation performs two-phase assessment:

Generation-time judging: Uses an external LLM to evaluate semantic correctness of outputs
Metric summarization: Computes aggregate statistics across attribute accuracy, spatial relationship accuracy, instance correctness, CLIP similarity, and geometric constraint satisfaction

Default paths mirror the inference setup:

Input configs: ./CADBench.jsonl
Rendered samples: ./output/result_name
Merged results: ./output/result_name.jsonl
Final metrics: ./output/result_name_metrics.json

Important: The evaluation requires an external LLM API for judging. The authors used this for human-aligned quality assessment in the paper—plan for API costs if running full benchmark evaluation.

Example 4: Repository Structure Navigation

Understanding the layout helps with customization:

Graph-CAD/
|- CADBench.jsonl          # Benchmark: instruction → expected output pairs
|- infer_api.py            # MAIN ENTRY: three-stage inference pipeline
|- render_auto.py          # Visualization: bpy.txt → rendered PNG
|- evaluate_and_report.py  # Assessment: compute all paper metrics
|- prompt_sft/             # Stage-specific system prompts (crucial for behavior)
|- utils/                  # Helper functions for graph parsing, validation
|- LlamaFactory/           # LOCAL CLONE: model serving infrastructure
|- qwen3/                  # LOCAL WEIGHTS: base model (~15GB)
|- checkpoints/            # STAGE ADAPTERS: LoRA weights for each stage
|  |- stage1/              #   Geometry decomposition model
|  |- stage2/              #   Action planning model
|  `- stage3/              #   Code generation model
`- output/                 # GENERATED: results, renders, evaluation files

Key insight: The modular checkpoint structure enables fascinating experiments. You could replace stage3 with a custom code generator while keeping Graph-CAD's graph prediction, or fine-tune stage1 on domain-specific mechanical assemblies.

Advanced Usage & Best Practices

Optimizing for Your Hardware

The default Qwen3-8B base model requires ~16GB VRAM for efficient inference. For constrained GPUs:

Use 4-bit quantization via LlamaFactory's quantization_bit: 4 config
Enable CPU offloading for stage adapters (base stays on GPU, adapters swap)
Consider qwen3-4b experimental finetuning (not officially supported)

Custom Dataset Integration

To train on proprietary CAD data:

Format instructions with explicit hierarchy markers (the graph serialization format)
Include constraint annotations between parts (distance, angle, concentricity)
Use SAPCL's problem generator to create graded difficulty variants automatically

Production Deployment Patterns

For API serving, wrap infer_api.py stages as separate microservices:

Stage 1 service: High-availability graph prediction (caches common structures)
Stage 2 service: Action planning with design rule validation
Stage 3 service: Code generation with sandboxed execution

This enables independent scaling and A/B testing of component improvements.

Debugging Failed Generations

When outputs fail:

Check ./output/result_name/*/graph.txt for structural prediction errors
Verify constraint consistency in the graph before blaming code generation
Use --overwrite in rendering to catch transient Blender issues

Comparison with Alternatives

Capability	Graph-CAD (SAPCL)	GPT-5	Claude Opus 4.1	DeepSeek-R1	BlenderLLM
Architecture	Graph-mediated 3-stage	End-to-end	End-to-end	End-to-end	End-to-end
GCS (CADBench-Sim)	0.9018	0.3846	0.4932	0.5556	0.5513
GCS (CADBench-Wild)	0.8943	0.4017	0.5062	0.4275	0.4983
Syntax Error Rate	2.0%	2.8%	7.4%	19.2%	2.4%
Overall Avg (Sim)	0.6883	0.6203	0.6662	0.3556	0.5832
Overall Avg (Wild)	0.7114	0.6515	0.6687	0.4564	0.5909
Open Weights	✅ Yes	❌ No	❌ No	✅ Yes	✅ Yes
Intermediate Inspection	✅ Graph + Actions	❌ Black box	❌ Black box	❌ Black box	❌ Black box
Constraint Satisfaction	Explicit edges	Implicit only	Implicit only	Implicit only	Implicit only

The verdict: Graph-CAD dominates where it matters most—geometric constraint satisfaction—while maintaining competitive overall quality. The explicit graph representation enables debugging and modification impossible with black-box alternatives. For production CAD workflows where manufacturability is non-negotiable, Graph-CAD isn't just better; it's the only rational choice.

FAQ

What hardware do I need to run Graph-CAD?

Minimum: 16GB VRAM (NVIDIA RTX 3090/4090 or A10G). CPU-only execution is possible via LlamaFactory's CPU offloading but significantly slower. For development, cloud instances with A100 40GB provide comfortable headroom.

Can I use Graph-CAD with my own 3D models?

Currently, the released pipeline generates from text instructions. To adapt existing models, you'd extract their decomposition graph (manual or automated), modify textually, and regenerate. Native "edit this mesh" support is planned for future releases.

Why does Graph-CAD use Blender instead of OpenSCAD or FreeCAD?

Blender's bpy API offers unmatched geometric primitive coverage and rendering quality for evaluation. The graph-mediated architecture is agnostic to the target CAD kernel—future work could target STEP, OpenCASCADE, or manufacturing-specific formats.

How does SAPCL differ from standard curriculum learning?

Standard curricula use fixed difficulty progressions. SAPCL's Structure-aware Progressive Curriculum Exploration dynamically generates boundary-difficulty examples based on the model's current capability frontier, discovered via a learned discriminator. This adapts to each training run's unique failure modes.

Is Graph-CAD suitable for commercial use?

The code and weights are publicly released; check the repository license for specifics. The ICLR paper establishes prior art for the architecture. For commercial deployment, consider the engineering effort to integrate with your existing PLM/PDM systems.

What languages besides English are supported?

The released model was trained primarily on English instructions. Qwen3-8B's multilingual capabilities suggest potential for Chinese and other languages, but this hasn't been validated for CAD-specific vocabulary.

How do I contribute or report issues?

Open GitHub issues for bugs or feature requests. The authors are responsive to community feedback, with dataset release and full evaluation code on the public roadmap.

Conclusion

Graph-CAD represents a paradigm shift in how we think about AI-generated manufacturing instructions. By refusing the seductive simplicity of end-to-end generation and instead embracing structured intermediate representations, it achieves geometric constraint satisfaction scores that make competitors look like toys.

The three-stage pipeline—graph decomposition, action planning, code generation—isn't just academically elegant. It's practically transformative, reducing syntax errors to 2% while hitting 90%+ constraint satisfaction. The SAPCL training mechanism proves that curriculum learning, when structure-aware, can push models past plateaus that defeat standard fine-tuning.

For researchers, Graph-CAD opens entirely new directions: graph-conditioned diffusion for CAD, neural symbolic verification of geometric constraints, and human-in-the-loop design editing. For practitioners, it offers the first Text-to-CAD system trustworthy enough for production workflows.

The field has been waiting for this. End-to-end models had their moment, but the future belongs to architectures that respect the structure of what they're building.

Ready to generate CAD that actually works? Clone the repository, download the weights, and experience the graph-mediated difference:

👉 https://github.com/EESJGong/Graph-CAD

Star the repo, open an issue with your results, and join the community building the next generation of intelligent manufacturing.