OpenCAD

A modular CAD system for parametric, programmable, and AI-assisted design

Components

• opencad_kernel — geometry kernel and typed operation registry
• opencad_solver — 2D sketch constraint solving (SolveSpace + Python fallback)
• opencad_tree — parametric feature-tree DAG (CRUD + rebuild + stale propagation)
• opencad_agent — AI agent that plans and executes operations
• opencad_viewport — React + Three.js viewport UI (mock mode by default)

Layout

opencad_kernel/      # 1 – Geometry Kernel
opencad_solver/      # 2 – Constraint Solver
opencad_tree/        # 3 – Feature Tree
opencad_viewport/    # 4 – 3D Viewport (frontend)
opencad_agent/       # 5 – AI Chat Agent
scripts/             # Backend smoke tests

Quickstart

Prereqs: Python 3.11+ and Node.js 18+

1. Install

For a packaged install (for example from a wheel or a PyPI release), use:

uv pip install opencad

For local development from this repository:

uv sync --extra test --extra server
cp .env.example .env

Install optional integrations as needed, for example:

uv sync --extra occt
uv sync --extra llm
uv sync --extra full

2. Start backend services

Each service runs on its own port:

cd backend
uv run --no-sync python -m uvicorn api:app --reload --port 8000

Run the dev script

To start the backend and frontend together from the repository root:

cd opencad_viewport
pnpm install
cd ..
./scripts/run_dev.sh

This starts:

• backend: http://127.0.0.1:8000
• frontend: http://127.0.0.1:5173

Press Ctrl+C to stop both services.

Optional environment overrides:

BACKENDHOST=0.0.0.0 BACKENDPORT=8000 FRONTENDHOST=0.0.0.0 FRONTENDPORT=5173 ./scripts/run_dev.sh

3. Check health

curl -s http://127.0.0.1:8000/kernel/healthz   # → {"status":"ok"}
curl -s http://127.0.0.1:8000/agent/healthz
curl -s http://127.0.0.1:8000/solver/healthz
curl -s http://127.0.0.1:8000/tree/healthz

4. Start the frontend

cd opencad_viewport
pnpm install
pnpm dev                                 # → http://localhost:5173

The viewport uses mock geometry/solver data by default (no backend required for those flows). Chat targets the live agent service by default; set VITEUSECHAT_MOCK=true if you explicitly want mocked chat output. Set VITEUSEMOCK=false to connect the rest of the viewport to the live services above.

5. Run with Docker

Build the backend image from the repository root so Docker can see the Python project metadata and backend package files:

docker build -f backend/Dockerfile -t opencad-backend .

Build the frontend image from the viewport directory:

docker build -f opencadviewport/Dockerfile -t opencad-frontend opencadviewport

Run the backend API on port 8000:

docker run --rm -p 8000:8000 opencad-backend

Run the frontend on port 5173:

docker run --rm -p 5173:80 opencad-frontend

By default, the frontend image is built with VITEBASEURL=http://localhost:8000 and live API calls enabled. To point the frontend at another API URL or enable mock mode, pass build args:

docker build \
  -f opencad_viewport/Dockerfile \
  -t opencad-frontend \
  --build-arg VITEBASEURL=http://localhost:8000 \
  --build-arg VITEUSEMOCK=false \
  --build-arg VITEUSECHAT_MOCK=false \
  opencad_viewport

Configuration

Runtime defaults are documented in .env.example.

• OPENCADENABLEDOCS=true|false toggles OpenAPI/docs route exposure.
• OPENCADCORSALLOW_ORIGINS sets a comma-separated browser origin allowlist.
• OPENCADKERNELBACKEND=analytic|occt selects the kernel backend.
• OPENCADSOLVERBACKEND=auto|solvespace|python selects the solver backend.

For production, disable docs and set a strict CORS origin list.

Security

Use TLS + authentication at your reverse proxy/API gateway. Do not commit .env files, tokens, or private datasets. See SECURITY.md for coordinated vulnerability reporting.

Testing

uv run --no-sync python -m pytest

Headless Scripting

OpenCAD now includes a first-class in-process API for scripting workflows with automatic feature-tree logging.

from opencad import Part, Sketch
part = Part() sketch = Sketch().rect(10, 20).circle(3, subtract=True) part.extrude(sketch, depth=5).fillet(edges="top", radius=0.5) part.export("output.step")

Every fluent call appends a built FeatureNode to the in-memory DAG, so headless runs are recoverable. Fluent sketches also persist entities + profile_order metadata in the sketch node, matching agent-path ordering semantics for deterministic profile reconstruction.

CAID Design Artifact

OpenCAD can export a versioned JSON artifact for SimCorrect. The artifact carries the feature tree, named parameters, and simulation tags; SimCorrect returns structured parameter patches against those names.

from opencad import Part, Sketch
part = Part(name="forearm").extrude(Sketch().rect(30, 4), depth=4) part.exportdesignartifact(     "caid-design.json",     artifact_id="forearm-demo",     parameters={"forearm_length": {"value": 0.30, "unit": "m", "role": "geometry"}},     simulation_tags=[         {"name": "rightforearm", "kind": "body", "target": "rforearm"},         {"name": "forearmlength", "kind": "parameter", "target": "link2length"},     ], )

CLI

opencad build model.json --output model.built.json
opencad run model.py --export output.step --tree-output output-tree.json

Examples

The examples/ directory contains end-to-end scripts for common device-development workflows:

• hardwaremountingbracket.py — bracket with fastener and cable pass-through holes
• hardwarepcbcarrier.py — PCB carrier plate with mounting holes and clearance slot
• softwarehmipanel.py — front panel for an operator interface with button and encoder cutouts
• firmwareprogrammerfixture.py — pogo-pin fixture plate for programming/debug access
• fulldevicecable_grommet.py — concentric cable grommet built from primitive booleans
• examples/agents/generatemountingbracket_code.py — agent code-generation usage example

Run an example from the repository root with:

python -m opencad.cli run examples/hardwaremountingbracket.py \
  --export bracket.step \
  --tree-output bracket-tree.json

The agent service can also generate example-style Python scripts for different LLM providers through LiteLLM by posting llmprovider, llmmodel, and generate_code=true to /chat. When generatecode is enabled, the response includes generatedcode and leaves the feature tree unchanged.

For a runnable script example, see examples/agents/README.md.

Documentation

• CHANGELOG.md - release notes
• CONTRIBUTING.md - development and contract workflow
• docs/CAIDARTIFACT_CONTRACT.md - artifact and patch semantics
• docs/RECONSTRUCTIONANDUPGRADE_PLAN.md - local reconstruction status and CAID upgrade plan

• PRODUCTION.md — deployment, routes, and verification
• ARCHITECTURE.md — component design and API contracts
• TOPOLOGY.md — topology reference stability (open research question)
• SECURITY.md — vulnerability reporting and hardening baseline