# 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) [![Paper PDF](https://img.shields.io/badge/Paper-PDF-b31b1b.svg)](https://562590763.github.io/CADDesigner/files/CADDesigner.pdf) [![Elsevier](https://img.shields.io/badge/Elsevier-Published-f36c21.svg)](https://www.sciencedirect.com/science/article/pii/S0010448526000576) [![Project Page](https://img.shields.io/badge/Project%20Page-Website-blue.svg)](https://562590763.github.io/CADDesigner/) [![Code](https://img.shields.io/badge/Code-GitHub-black.svg)](https://github.com/562590763/CADDesigner-Code) CADDesigner framework
## 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](https://github.com/astral-sh/uv) for fast and reliable dependency management. Install all dependencies with: ```bash 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: ```bash 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: ```bash cp config/provider_template.json config/provider.json ``` Edit `config/provider.json` with your own provider settings and API keys: ```json { "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: ```bash git clone https://github.com/562590763/CADDesigner-Code.git cd CADDesigner ``` 2. Install dependencies: ```bash uv sync ``` 3. Install the repository Git hook, optional for development: ```bash ./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: ```bash # 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: ```bash 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: ```bash 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** ```bash # Start both the API server and the React Web UI uv run python start_caddesigner_full.py ``` **Option B: start services separately** ```bash # 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**: - **Local API docs**: - **Local health check**: 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://:7860` - **Remote API docs**: `http://: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. ```bash # 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**: - **Backend API**: #### Advanced Configuration **Custom ports and hosts** ```bash # 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** ```bash # 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](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: ```bash 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: ```bash cp docker/env.example docker/.env ``` Edit `docker/.env` if needed. Common values include: ```bash # 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** ```bash 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**: - **Local API service**: - **Local API docs**: If accessing from another machine, replace `127.0.0.1` with the host IP or domain: - **Remote React Web UI**: `http://:7860` - **Remote API service**: `http://:8000` - **Remote API docs**: `http://:8000/docs` **Manage services** ```bash # 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: ```yaml # 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: ```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** ```text Create a cube with side length 50 mm. ``` 2. **Complex mechanical part** ```text Create a DN100 PN16 welding flange according to the ASME B16.5 standard. ``` 3. **Parametric model** ```text Design a gear with 18 teeth, module 2.0, and pressure angle 20 degrees. ``` 4. **Sketch-conditioned design** ```text 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: ```bash ./scripts/export_requirements.sh ``` ### Project Structure ```text 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/`: ```python @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: ```python 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 ```bash uv run python main.py ``` Example prompt: ```text Create a simple cylinder with radius 10 mm and height 20 mm. ``` ### Automated Testing Run tests with: ```bash 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: ```text 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](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](https://doi.org/10.1016/j.cad.2026.104087) ```bibtex @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.