cadSet/CADDesigner-Code/README.md

CADDesigner: Conceptual CAD Model Generation with a General-Purpose Agent

Fengxiao Fan* · Jingzhe Ni* · Xiaolong Yin · Sirui Wang · Xingyu Lu · Qiang Zou · Ruofeng Tong · Min Tang · Peng Du†

Zhejiang University, China

(* equal contribution, † corresponding author)

News

• 2026.05: CADDesigner is published in Computer-Aided Design.
• Code release: This repository contains the public implementation and setup instructions.

Abstract

Computer-Aided Design (CAD) plays a pivotal role in industrial manufacturing but typically requires a high level of expertise from designers. To lower the entry barrier and improve design efficiency, CADDesigner presents an LLM-powered general-purpose agent for conceptual CAD design. The agent accepts textual descriptions and sketches as input, interacts with users to refine and clarify design requirements, and generates executable CAD modeling code.

CADDesigner is built around the Explicit Context Imperative Paradigm (ECIP), which makes modeling context, intermediate state, and operation intent explicit during code generation. During generation, the agent uses execution feedback and rendered visual feedback to repair the CAD program iteratively. Generated design cases can be stored in a structured knowledge base, providing a path for continual improvement of CAD code generation.

Highlights

• Natural-language CAD modeling: describe a CAD model in text and let the agent generate executable modeling code.
• Sketch-aware conceptual design: use sketch or image references together with text prompts.
• Requirement refinement: expand vague user requests into structured modeling specifications before code generation.
• ECIP-based CAD code generation: represent modeling context and operation state explicitly for more reliable code synthesis.
• Execution and automatic repair: run generated code, inspect errors, and repair common CAD modeling failures.
• Visual feedback loop: compare rendered model views with the design requirement and revise the model when needed.
• Interactive development: support command-line use, API service mode, and a React Web UI.
• File and artifact management: save generated scripts, STEP/STL files, rendered images, and conversation context.

Method Overview

CADDesigner follows a ReAct-style agent workflow for conceptual CAD generation:

1. Receive Requirement: the user provides a text prompt and optionally a sketch or reference image.
2. Requirement Expansion: a specialist subagent expands the request into dimensions, constraints, assumptions, APIs, and an ordered modeling process.
3. Code Generation: CADDesigner produces executable CAD modeling code with explicit context and operation intent.
4. Execution and Export: the generated script is executed and exports STEP/STL artifacts.
5. Error Handling: tracebacks and missing artifacts trigger automatic repair.
6. Visual Feedback: rendered views are checked against the user intent.
7. Task Completion: final scripts and exported model artifacts are returned to the user.

🚀 Features

• Natural-language CAD modeling: describe a 3D model in plain language and let the agent generate accurate CAD code.
• Multi-framework support: supports CADQuery, SimpleCADAPI, PythonOCC-related workflows, and extensible CAD tooling.
• Interactive development: generate, execute, inspect, and debug CAD code in an iterative loop.
• Intelligent query expansion: automatically expands ambiguous requirements into detailed modeling specifications.
• File management: built-in file tools help save, inspect, and organize generated models.
• Error handling and automatic repair: detects common CAD modeling failures and attempts to repair them.
• Web interface: provides a FastAPI backend and React frontend for multi-session interaction.

Core Components

1. BaseAgent: the main AI agent that coordinates the full workflow.
2. Tools: specialized tools for CAD code generation, file operations, command execution, rendering, and feedback.
3. Config: manages LLM provider configuration, API keys, and model routing.
4. CLI Interface: rich terminal-based interaction for local modeling.
5. Web Interface: FastAPI service and React UI for browser-based use.
6. Skill References: CAD API and workflow references used by specialist subagents under workspace/skills/.

📋 Prerequisites

System Requirements

• Python 3.12, as specified in pyproject.toml
• Docker, if you want to use the bundled Redis service or full Docker deployment
• Node.js and pnpm, if you want to run the React frontend in development mode

Required Python Packages

This project uses uv for fast and reliable dependency management.

Install all dependencies with:

uv sync

In the development environment, pyproject.toml and uv.lock are the source of truth for dependencies. The committed requirements.txt is exported from uv.lock for Docker and deployment environments.

⚙️ Configuration

1. Environment Variables

The project reads environment variables from a .env file in the repository root. Create one from the provided template:

cp docker/env.example .env

Configurable variables include:

• Redis configuration

  • REDIS_DB: Redis database index
  • REDIS_PASSWORD: Redis password
  • REDIS_HOST: Redis host
  • REDIS_PORT: Redis port

• Storage configuration

  • CONTEXT_DIR: context storage directory
  • CONTEXT_AUTO_SUMMARIZE_TRIGGER: automatic summarization threshold, defaulting to 1000000, which effectively disables automatic summarization
  • SKETCH_DIR: SketchPad storage directory

• Observability configuration, optional

  • LANGFUSE_SECRET_KEY: Langfuse secret key
  • LANGFUSE_PUBLIC_KEY: Langfuse public key
  • LANGFUSE_BASE_URL: Langfuse service URL

2. LLM Provider Configuration

Generate the provider configuration file from the template and then edit it:

cp config/provider_template.json config/provider.json

Edit config/provider.json with your own provider settings and API keys:

{
  "volc_engine": [
    {
      "model_name": "deepseek-v3-250324",
      "api_keys": ["your_api_key_here"],
      "base_url": "https://ark.cn-beijing.volces.com/api/v3/",
      "max_retries": 3,
      "retry_delay": 1
    }
  ],
  "openrouter": [
    {
      "model_name": "anthropic/claude-sonnet-4.6",
      "api_keys": ["your_api_key_here"],
      "base_url": "https://openrouter.ai/api/v1"
    },
    {
      "model_name": "google/gemini-3.1-pro-preview",
      "api_keys": ["your_api_key_here"],
      "base_url": "https://openrouter.ai/api/v1"
    },
    {
      "model_name": "google/gemini-3-flash-preview",
      "api_keys": ["your_api_key_here"],
      "base_url": "https://openrouter.ai/api/v1"
    }
  ]
}

Do not commit real API keys.

3. LLM Interface Configuration

The agent uses different LLM interfaces for different tasks:

• BASIC_INTERFACE: general conversation and coordination
• CODE_INTERFACE: CAD code generation and repair, usually requiring a stronger model
• QUICK_INTERFACE: query expansion and lightweight tasks

These routes are configured in config/config.py and config/provider.json.

🚀 Quick Start

Installation

1. Clone the repository:

git clone https://github.com/562590763/CADDesigner-Code.git
cd CADDesigner

2. Install dependencies:

uv sync

3. Install the repository Git hook, optional for development:

./scripts/install_git_hooks.sh

The hook automatically runs uv export before commits, refreshing and staging requirements.txt.

4. Configure your LLM provider as described above.

5. Start Redis, required by the backend.

The backend uses Redis in CLI, API, and Web modes. By default, the configuration reads REDIS_HOST=localhost and REDIS_PORT=9736 from .env. If you do not already have a local Redis instance, use the bundled Docker Compose file:

# Start local development Redis
docker compose -f docker/docker-compose.redis.yml up -d

# Check Redis status
docker compose -f docker/docker-compose.redis.yml ps

# Stop and remove the Redis container
docker compose -f docker/docker-compose.redis.yml down

You can also verify Redis manually:

docker compose -f docker/docker-compose.redis.yml ps
redis-cli -p 9736 ping

Run the Agent

Method 1: Command-Line Interface

Start interactive CADDesigner:

LOG_LEVEL=WARNING uv run python main.py
# Press Ctrl+D after finishing multi-line input

Method 2: Web Interface, Recommended

The current Web stack uses a FastAPI backend and a React frontend.

Option A: one-command startup, recommended

# Start both the API server and the React Web UI
uv run python start_caddesigner_full.py

Option B: start services separately

# Terminal 1: start the API server
uv run python start_caddesigner_api.py

# Terminal 2: start the Web UI
uv run python start_caddesigner_ui.py

Access the Web interface:

• Local React Web UI: http://127.0.0.1:7860
• Local API docs: http://127.0.0.1:8000/docs
• Local health check: http://127.0.0.1:8000/health

If you start with --api-host 0.0.0.0 or --ui-host 0.0.0.0 and want to access from another machine, replace 127.0.0.1 with the server IP or domain:

• Remote React Web UI: http://<server-ip>:7860
• Remote API docs: http://<server-ip>:8000/docs

Method 3: Start the Frontend Directly Under frontend/

The repository also provides a TypeScript + React frontend under frontend/, suitable for frontend development and richer multi-session agent chat.

# Terminal 1: start API
uv run python start_caddesigner_api.py

# Terminal 2: start React UI
cd frontend
pnpm install
pnpm dev

Access addresses:

• React UI: http://localhost:4173
• Backend API: http://localhost:8000

Advanced Configuration

Custom ports and hosts

# Custom configuration
uv run python start_caddesigner_full.py \
  --api-port 8001 \
  --ui-port 7861 \
  --api-host 0.0.0.0 \
  --ui-host 0.0.0.0

# Development mode with reload
uv run python start_caddesigner_full.py --reload --debug

# By default, generated runtime artifacts are written under ./workspace.

# Production-style deployment
uv run python start_caddesigner_full.py \
  --workers 4 \
  --working-dir /var/lib/caddesigner

Remote deployment

# Server A: API service
uv run python start_caddesigner_api.py --host 0.0.0.0 --port 8000

# Server B: Web UI pointing to Server A
uv run python start_caddesigner_ui.py \
  --host 0.0.0.0 \
  --port 7860 \
  --api-url http://server-a:8000

For detailed startup options, see STARTUP_GUIDE.md.

Method 4: Docker Deployment, Recommended for Production

Docker can quickly deploy the full CADDesigner system, including Redis, the FastAPI API service, and the React Web UI.

Notes:

• docker/docker-compose.yml starts Redis + API + React Web UI together.
• docker/docker-compose.redis.yml starts only Redis, useful for local non-Docker backend development.
• The React Web UI is exposed on port 7860 in Docker.

Preparation

1. Configure model providers:

cp docker/provider_template.json docker/provider.json

Edit docker/provider.json with your model provider and API key settings.

2. Configure Docker Compose environment variables:

cp docker/env.example docker/.env

Edit docker/.env if needed. Common values include:

# Storage directories
CONTEXT_DIR=workspace/data/contexts
CONTEXT_AUTO_SUMMARIZE_TRIGGER=1000000
SKETCH_DIR=workspace/data/sketches

# Logging
LOG_DIR=workspace/agent_logs
LOG_LEVEL=WARNING

Start services

docker compose -f docker/docker-compose.yml up -d --build

The image build uses requirements.txt, which is exported from uv.lock. When dependency changes are committed, make sure the Git hook has refreshed requirements.txt.

The Compose file starts three services:

• simplecad_redis: Redis
• simplecad_api: FastAPI API service
• simplecad_webui: React Web UI, with Vite proxying to the API

Access services

• Local React Web UI: http://127.0.0.1:7860
• Local API service: http://127.0.0.1:8000
• Local API docs: http://127.0.0.1:8000/docs

If accessing from another machine, replace 127.0.0.1 with the host IP or domain:

• Remote React Web UI: http://<your-host-or-ip>:7860
• Remote API service: http://<your-host-or-ip>:8000
• Remote API docs: http://<your-host-or-ip>:8000/docs

Manage services

# Show service status
docker compose -f docker/docker-compose.yml ps

# Follow logs
docker compose -f docker/docker-compose.yml logs -f

# Stop services
docker compose -f docker/docker-compose.yml down

# Restart services
docker compose -f docker/docker-compose.yml restart

# Remove all volumes, use with care
docker compose -f docker/docker-compose.yml down -v

Production deployment suggestions

1. Change default ports if needed:

# Edit docker/docker-compose.yml
ports:
  - "your_port:7860"  # React UI port
  - "your_port:8000"  # API port

2. Configure a reverse proxy, for example with Nginx:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:7860;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /v1/ {
        proxy_pass http://localhost:8000/v1/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /health {
        proxy_pass http://localhost:8000/health;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Basic Usage Examples

1. Simple object creation

Create a cube with side length 50 mm.

2. Complex mechanical part

Create a DN100 PN16 welding flange according to the ASME B16.5 standard.

3. Parametric model

Design a gear with 18 teeth, module 2.0, and pressure angle 20 degrees.

4. Sketch-conditioned design

Use the attached sketch as reference and generate the corresponding CAD model.

Workflow

1. Query input: describe the CAD model in natural language and optionally provide a sketch.
2. Requirement expansion: the agent asks clarification questions and expands the requirement.
3. Code generation: CADDesigner generates CAD modeling code.
4. Execution and export: the code is executed and exports STEP/STL artifacts.
5. Error handling: the agent automatically repairs issues when possible.
6. Visual feedback: rendered model views are checked against the design intent.
7. Task completion: final code and generated model artifacts are returned.

🛠️ Development Guide

Dependency Workflow

• Development and lock file: use pyproject.toml + uv.lock.
• Local installation: run uv sync.
• Docker export: the pre-commit hook installed by ./scripts/install_git_hooks.sh automatically generates and stages requirements.txt before commits.
• Manual export:

./scripts/export_requirements.sh

Project Structure

agent/                    Core agent implementation
config/                   LLM provider and routing configuration
context/                  Conversation, context, and SketchPad management
docker/                   Dockerfiles and Compose templates
frontend/                 React Web UI
observability/            Langfuse tracing integration
scripts/                  Development helper scripts
tools/                    CAD generation, command, file, rendering, and repair tools
web_interface/            FastAPI server and routers
workspace/skills/         CAD skill and API references used by subagents

agent/BaseAgent.py

The core agent is responsible for:

• managing conversation history and memory
• coordinating tool use
• handling streaming responses
• implementing memory-management strategies

Key methods:

• run(): main execution method
• memory_manage(): summarizes and manages conversation history
• chat_impl(): core chat logic and detailed agent instructions

tools/

The tools package contains specialized tools:

• make_user_query_more_detailed: expands user requirements into detailed modeling specifications.
• cad_code_generator: a single-call specialist subagent that creates, modifies, and debugs model.py with built-in file tools and command execution.
• execute_command: runs system commands and modeling scripts.
• sketch_pad_operations: stores, retrieves, searches, and manages SketchPad data.
• get_visual_feedback: renders and evaluates generated models with visual feedback.
• SimpleLLMFunc built-in file tools: read_file, grep, sed, and echo_into.

config/config.py

This module manages:

• LLM provider configuration
• API key loading
• model-selection strategy
• routing between basic, code, and quick interfaces

Adding New Tools

Add a new CAD tool:

1. Create the new function in the appropriate split module, such as tools/code_tools.py, tools/command_tools.py, tools/requirements_tools.py, or a new module under tools/:

@tool(
    name="your_tool_name",
    description="What your tool does"
)
def your_tool_function(param1: str, param2: int) -> str:
    """
    Your tool implementation.
    """
    # Tool logic goes here.
    return result

2. Export and register the tool in the toolkit. For example, expose it from tools/__init__.py and add it to the agent toolkit where the tool list is assembled:

toolkit = [
    make_user_query_more_detailed,
    cad_code_generator,
    execute_command,
    sketch_pad_operations,
    get_visual_feedback,
    # SimpleLLMFunc built-in file tools are created from create_builtin_file_tools(...)
    your_tool_function,  # Add your new tool here.
]

Extending LLM Support

To add a new LLM provider:

1. Add the provider configuration to config/provider.json.
2. Update config/config.py if additional routing logic is needed.
3. Test the provider on requirement refinement, code generation, and repair tasks.

Customizing Agent Behavior

Agent behavior is defined by the orchestration logic and prompts in agent/ and tools/. You can customize:

• response format
• tool-use strategy
• error-handling strategy
• visual-feedback policy
• memory-management strategy

🧪 Testing

Manual Testing

uv run python main.py

Example prompt:

Create a simple cylinder with radius 10 mm and height 20 mm.

Automated Testing

Run tests with:

uv run pytest

Recommended test coverage includes:

• code generation quality
• error handling
• file operations
• tool integration
• Web event streaming

📁 Output Management

Generated models are usually saved under task-specific directories. We recommend using workspace/ as the unified output root:

workspace/
|-- DN100_PN16_welding_flange/
|   |-- model.py
|   |-- model.step
|   |-- model.stl
|   `-- model_multi_view_render.png
`-- gear_18_teeth/
    |-- model.py
    |-- model.step
    |-- model.stl
    `-- model_multi_view_render.png

Generated artifacts and local workspaces should not be committed to the public repository.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature-name.
3. Make changes and test them thoroughly.
4. Submit a pull request with a clear description.

Code Style

• Follow PEP 8 for Python code.
• Use type hints where possible.
• Add docstrings for public functions.
• Test new functionality before committing.

📝 License

This repository is released under the GPL-2.0 license. See LICENSE for details.

🆘 Support

If you have questions or need support:

1. Check the troubleshooting and startup documentation.
2. Search existing issues.
3. Create a new issue with detailed error information.

🔮 Roadmap

• Browser-based Web interface improvements
• Integration with more CAD formats, such as IGES and STL
• Advanced parametric modeling
• Integration with simulation tools
• Multilingual support
• CAD model optimization suggestions
• Manufacturing database integration

Citation

If you find this work useful, please cite:

DOI: 10.1016/j.cad.2026.104087

@article{fan2026caddesigner,
  author    = {Fengxiao Fan and Jingzhe Ni and Xiaolong Yin and Sirui Wang and Xingyu Lu and Qiang Zou and Ruofeng Tong and Min Tang and Peng Du},
  title     = {{CADDesigner}: Conceptual CAD Model Generation with a General-Purpose Agent},
  journal   = {Computer-Aided Design},
  volume    = {198},
  pages     = {104087},
  year      = {2026},
  doi       = {10.1016/j.cad.2026.104087}
}

Acknowledgements

This work was supported by the Leading Goose R&D Program of Zhejiang under Grant No. 2024C01103.

CADDesigner builds on open-source CAD and agent tooling, including CADQuery, PythonOCC, FastAPI, React, uv, and the broader Python CAD ecosystem. We thank the maintainers and contributors of these projects.

---

Note: This project is designed for research, education, and professional CAD modeling assistance. Always verify that generated models satisfy your specific design, manufacturing, and safety requirements.