Skip to content
Back to search

cad-cae-copilot

CAD/CAE Copilot — an AI-native CAD/CAE/CAX workbench for AI agents. Text-to-CAD, text-to-CAE, real build123d/OpenCASCADE geometry, editable parameters, stable topology pointers, deterministic critique, and MCP server tools.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/armpro24-blip--cad-cae-copilot/badge.svg)](/listings/armpro24-blip--cad-cae-copilot)

HTML

<a href="/listings/armpro24-blip--cad-cae-copilot"><img src="/api/listings/armpro24-blip--cad-cae-copilot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Three ways in — pick one and you're modeling in minutes.

> **Before you start:** you need your own MCP client (Claude Code, OpenAI > Codex, GitHub Copilot, Cursor, …) with its own model access. The aieng > backend itself needs no API key — your agent connects to it over MCP and > drives the workbench through its own harness.

For a first try, **Docker (Option 2) is the most reliable** — it pins the build123d / OpenCASCADE / CalculiX stack so nothing has to compile on your machine. The local dev install is best once you intend to hack on the code.

Option 1: GitHub Codespaces (fastest, zero install)

Click **"Open in GitHub Codespaces"** above. The environment sets itself up; when it finishes loading, run `make dev` (or `python3 scripts/dev.py` if `make` is unavailable). Then connect an agent and paste the [motor mounting fixture prompt](#from-specification-to-verified-cad), or the shorter bracket prompt:

Create a 120 × 80 × 12 mm machined bearing support bracket with a centered
Ø42 mm horizontal bearing bore, four Ø10 mm base mounting holes, and two
mirrored gussets. Preserve the exact dimensions, expose editable parameters,
verify the final geometry, and run the deterministic engineering critique.

Inspect the generated model, named parts, verification results, and stable `@face:*` references in the workbench.

Option 2: Docker all-in-one (recommended local package)

Packages the backend, built viewer, MCP HTTP server, build123d / OpenCASCADE dependencies, and CalculiX into one container.

**Quick start — pull the published image (no local build):**

docker pull ghcr.io/armpro24-blip/aieng-workbench:latest
docker run --rm -it -p 8000:8000 -p 8765:8765 -v aieng-data:/data ghcr.io/armpro24-blip/aieng-workbench:latest

For an agent-guided first run, paste the [one-prompt setup](docs/one-prompt-agent-setup.md) into your MCP-capable client. It checks Docker, backend health, MCP endpoint visibility, onboarding calls, and approval-surface readiness before any optional CAD smoke.

The alpha image is published to GHCR from `main` after the Docker smoke passes (`latest` + an immutable `sha-<commit>` tag). Alpha-scoped, not production-certified.

**Releases:** the current pre-release is [`v0.1.0-alpha.4`](https://github.com/armpro24-blip/cad-cae-copilot/releases/tag/v0.1.0-alpha.4). Distribution is the Git tag plus the GHCR image — **PyPI publication is not planned**, so the Git form below is the install path, not a stopgap. To run just the MCP server without cloning (Python 3.11+, pinned to the release tag):

uvx \
  --from "aieng-workbench-mcp[full] @ git+https://github.com/armpro24-blip/cad-cae-copilot.git@v0.1.0-alpha.4#subdirectory=aieng-ui/backend" \
  --with "aieng-format @ git+https://github.com/armpro24-blip/cad-cae-copilot.git@v0.1.0-alpha.4#subdirectory=aieng" \
  aieng-workbench-mcp --approval-mode client --data-dir ~/.aieng-workbench

What a successful first run looks like

After the first successful CAD smoke, you should be able to verify:

- the workbench viewer shows a generated model, - STEP/STL/GLB or preview artifacts were written, - generated source and metadata are preserved in the project package, - named parts and editable parameters are present when the model exposes them, - stable topology references such as `@face:*` are available when topology mapping succeeds, - deterministic critique or geometry checks report findings honestly, - and the `.aieng` package contains reproducible artifacts and provenance.

CAE setup, mesh generation, and solver execution are separate approval-gated steps. A readiness or preflight report does not mean the solver has run.

**Contributor path — build locally from source** (Docker Compose or manual, for developing the image or running an unmerged branch):

docker compose up -d
# or:
docker build -t aieng/workbench:local .
docker run --rm -it -p 8000:8000 -p 8765:8765 -v aieng-data:/data aieng/workbench:local

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 694 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- SEO Keywords: AI CAD, AI CAE, AI CAX, Text-to-CAD, Text-to-CAE, Text-to-CAX, Generative CAD, AI Engineering Workbench, MCP CAD, build123d, OpenCASCADE, CalculiX -->
  2. <div align="center">
  3. # CAD/CAE Copilot
  4. ### Most AI CAD tools stop when a picture appears. CAD/CAE Copilot turns an engineering spec into real, editable, verifiable CAD — and keeps every artifact reproducible.
  5. An AI-native CAD/CAE/CAX workbench. An MCP-capable agent writes real
  6. build123d / OpenCASCADE geometry, exports STEP/STL/GLB, names the parts,
  7. exposes stable topology pointers, runs a deterministic critique, and can
  8. continue into CAE — all preserved in one reproducible `.aieng` package.
  9. **You bring your own MCP client** (e.g. Claude Code, Codex, Copilot, Cursor),
  10. which carries its own model access. The aieng backend itself needs no API key.
  11. <a href="docs/assets/images/hero.webp">
  12. <img src="docs/assets/images/hero.webp" width="100%" alt="A fully specified industrial motor mounting fixture modeled and inspected with aieng"/>
  13. </a>
  14. [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/armpro24-blip/cad-cae-copilot)
  15. ![CAD](https://img.shields.io/badge/CAD-build123d%20%2F%20OpenCASCADE-1f6feb)
  16. ![FEA](https://img.shields.io/badge/FEA-CalculiX-e36209)
  17. ![Agent](https://img.shields.io/badge/agent-MCP%20server-8957e5)
  18. ![Python](https://img.shields.io/badge/python-3.11%2B-3776ab)
  19. [What is this?](#what-is-this--architecture--information-flow) ·
  20. [Quick Start](#quick-start) ·
  21. [CAD Examples](#industrial-cad-examples) ·
  22. [Benchmarks](#quantitative-benchmarking) ·
  23. [Why aieng](#why-aieng--beyond-text-to-cad) ·
  24. [One-prompt setup](docs/one-prompt-agent-setup.md) ·
  25. [MCP Setup](aieng-ui/backend/MCP_SETUP.md) ·
  26. [Agent Guide](AGENTS.md)
  27. <sub>English | <a href="README.zh.md">中文</a></sub>
  28. <sub>Real STEP/STL/GLB · Editable parameters · Named parts · Stable topology pointers · Deterministic critique · CAD → CAE artifacts · Approval-gated actions</sub>
  29. </div>
  30. ## At a glance
  31. CAD/CAE Copilot lets an MCP-capable agent turn an engineering specification into
  32. a reproducible CAD/CAE package.
  33. - **Input:** explicit mechanical specs, dimensions, constraints, and follow-up
  34. edits.
  35. - **CAD kernel:** real build123d / OpenCASCADE geometry, not a mock renderer.
  36. - **Outputs:** STEP, STL, GLB, generated source, thumbnails, topology maps, and
  37. `.aieng` packages.
  38. - **Editability:** named parts, editable parameters, and stable `@face:*`
  39. pointers when topology mapping succeeds.
  40. - **Verification:** deterministic critique, geometry checks, design-rule
  41. assertions, and diff-aware edits.
  42. - **CAE path:** material, loads, constraints, mesh, solver artifacts, and
  43. evidence are kept beside the CAD model.
  44. - **Agent model:** bring your own MCP client and model access; the backend
  45. itself does not require an API key.
  46. ```text
  47. engineering spec
  48. -> MCP agent
  49. -> build123d / OpenCASCADE CAD
  50. -> named parts + topology pointers
  51. -> critique / CAE setup / solver evidence
  52. -> reproducible .aieng package
  53. ```
  54. ## What is this? — architecture & information flow
  55. In one picture: a natural-language engineering spec becomes optimized, verified
  56. CAD/CAE, driven end-to-end by **your own MCP agent** and preserved in one
  57. reproducible `.aieng` package.
  58. <a href="docs/cad_cae_copilot_architecture_information_flow.png">
  59. <img src="docs/cad_cae_copilot_architecture_information_flow.png" width="100%" alt="CAD/CAE Copilot system architecture and information flow: user requirement → agent (plan/reason) → MCP tool layer → CAD modeling → CAE setup & simulation → result evaluation → closed-loop optimization, with a human-in-the-loop trust/approval layer and an .aieng engineering package"/>
  60. </a>
  61. **User requirement → agent (plan & reason) → MCP tool layer → CAD modeling &
  62. editing → CAE setup & simulation → result evaluation → closed-loop
  63. optimization.** A human-in-the-loop **trust & approval** layer gates every
  64. mutation, a **credibility tier** is stamped on every result, and all artifacts
  65. land in a self-describing `.aieng` package — so any MCP-capable agent can design,
  66. analyze, optimize, and deliver verified, reproducible CAD/CAE solutions.
  67. ## Quantitative benchmarking
  68. The project includes a machine-readable analytical FEA benchmark corpus at
  69. [`aieng/benchmarks/datasets/analytical_fea`](aieng/benchmarks/datasets/analytical_fea).
  70. It builds runnable `.aieng` cases, compares solver metrics against documented
  71. closed-form references, and emits an
  72. `aieng.benchmark.analytical_fea.scorecard` JSON artifact. The harness reports
  73. "agreement within tolerance"; it is not certification or a production-safety
  74. claim.
  75. ```bash
  76. cd aieng
  77. python -m aieng.benchmarks.analytical_fea --out analytical_fea_scorecard.json
  78. ```
  79. CI runs the analytical benchmark corpus tests so corpus/reference drift and
  80. scorecard regressions fail fast.
  81. ## Quick start
  82. Three ways in — pick one and you're modeling in minutes.
  83. > **Before you start:** you need your own MCP client (Claude Code, OpenAI
  84. > Codex, GitHub Copilot, Cursor, …) with its own model access. The aieng
  85. > backend itself needs no API key — your agent connects to it over MCP and
  86. > drives the workbench through its own harness.
  87. For a first try, **Docker (Option 2) is the most reliable** — it pins the
  88. build123d / OpenCASCADE / CalculiX stack so nothing has to compile on your
  89. machine. The local dev install is best once you intend to hack on the code.
  90. ### Option 1: GitHub Codespaces (fastest, zero install)
  91. Click **"Open in GitHub Codespaces"** above. The environment sets itself up;
  92. when it finishes loading, run `make dev` (or `python3 scripts/dev.py` if `make`
  93. is unavailable). Then connect an agent and paste the
  94. [motor mounting fixture prompt](#from-specification-to-verified-cad), or the
  95. shorter bracket prompt:
  96. ```text
  97. Create a 120 × 80 × 12 mm machined bearing support bracket with a centered
  98. Ø42 mm horizontal bearing bore, four Ø10 mm base mounting holes, and two
  99. mirrored gussets. Preserve the exact dimensions, expose editable parameters,
  100. verify the final geometry, and run the deterministic engineering critique.
  101. ```
  102. Inspect the generated model, named parts, verification results, and stable
  103. `@face:*` references in the workbench.
  104. ### Option 2: Docker all-in-one (recommended local package)
  105. Packages the backend, built viewer, MCP HTTP server, build123d / OpenCASCADE
  106. dependencies, and CalculiX into one container.
  107. **Quick start — pull the published image (no local build):**
  108. ```bash
  109. docker pull ghcr.io/armpro24-blip/aieng-workbench:latest
  110. docker run --rm -it -p 8000:8000 -p 8765:8765 -v aieng-data:/data ghcr.io/armpro24-blip/aieng-workbench:latest
  111. ```
  112. For an agent-guided first run, paste the
  113. [one-prompt setup](docs/one-prompt-agent-setup.md) into your MCP-capable client.
  114. It checks Docker, backend health, MCP endpoint visibility, onboarding calls, and
  115. approval-surface readiness before any optional CAD smoke.
  116. The alpha image is published to GHCR from `main` after the Docker smoke passes
  117. (`latest` + an immutable `sha-<commit>` tag). Alpha-scoped, not
  118. production-certified.
  119. **Releases:** the current pre-release is
  120. [`v0.1.0-alpha.4`](https://github.com/armpro24-blip/cad-cae-copilot/releases/tag/v0.1.0-alpha.4).
  121. Distribution is the Git tag plus the GHCR image — **PyPI publication is not
  122. planned**, so the Git form below is the install path, not a stopgap. To run just
  123. the MCP server without cloning (Python 3.11+, pinned to the release tag):
  124. ```bash
  125. uvx \
  126. --from "aieng-workbench-mcp[full] @ git+https://github.com/armpro24-blip/cad-cae-copilot.git@v0.1.0-alpha.4#subdirectory=aieng-ui/backend" \
  127. --with "aieng-format @ git+https://github.com/armpro24-blip/cad-cae-copilot.git@v0.1.0-alpha.4#subdirectory=aieng" \
  128. aieng-workbench-mcp --approval-mode client --data-dir ~/.aieng-workbench
  129. ```
  130. ### What a successful first run looks like
  131. After the first successful CAD smoke, you should be able to verify:
  132. - the workbench viewer shows a generated model,
  133. - STEP/STL/GLB or preview artifacts were written,
  134. - generated source and metadata are preserved in the project package,
  135. - named parts and editable parameters are present when the model exposes them,
  136. - stable topology references such as `@face:*` are available when topology
  137. mapping succeeds,
  138. - deterministic critique or geometry checks report findings honestly,
  139. - and the `.aieng` package contains reproducible artifacts and provenance.
  140. CAE setup, mesh generation, and solver execution are separate approval-gated
  141. steps. A readiness or preflight report does not mean the solver has run.
  142. **Contributor path — build locally from source** (Docker Compose or manual,
  143. for developing the image or running an unmerged branch):
  144. ```bash
  145. docker compose up -d
  146. # or:
  147. docker build -t aieng/workbench:local .
  148. docker run --rm -it -p 8000:8000 -p 8765:8765 -v aieng-data:/data aieng/workbench:local
  149. ```
  150. Open the viewer at http://localhost:8000/app/ and point an MCP-over-HTTP client
  151. at `http://localhost:8765/sse`. Projects and `.aieng` packages persist in the
  152. `aieng-data` volume. The container enables `AIENG_MCP_MANAGED_APPROVAL=1` by
  153. default, so approval-gated CAD/CAE tools surface through the workbench UI.
  154. ### Option 3: Local developer install
  155. Best when you intend to modify the code. Prerequisite: a conda env named
  156. **exactly `aieng311`** (Python ≥ 3.11) with **build123d** — the MCP configs
  157. and run scripts assume this name. The `build123d` / OpenCASCADE (OCP) install
  158. can be slow or fail on some platforms; if it does, prefer the Docker path
  159. above.
  160. ```bash
  161. conda create -n aieng311 python=3.11 -y
  162. conda activate aieng311
  163. pip install build123d
  164. cd aieng-ui/backend && pip install -e .
  165. ```
  166. Then start both services in one terminal (Ctrl+C stops both):
  167. ```bash
  168. make dev # macOS / Linux / WSL
  169. .\dev.ps1 # Windows PowerShell
  170. python scripts/dev.py # cross-platform fallback
  171. ```
  172. Backend → FastAPI on `http://127.0.0.1:8000`; frontend → Vite on
  173. `http://localhost:5173`. Custom ports: `BACKEND_PORT=8080 FRONTEND_PORT=3000 make dev`.
  174. <details>
  175. <summary>Start services individually / run tests</summary>
  176. ```bash
  177. make backend # or: cd aieng-ui/backend && uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
  178. make frontend # or: cd aieng-ui/frontend && npm install && npm run dev
  179. cd aieng-ui/backend && python -m pytest # backend test suite
  180. ```
  181. </details>
  182. ## From specification to verified CAD
  183. The hero model above was built from an explicit industrial fixture
  184. specification — fixed dimensions, named parts, exact hole and slot locations,
  185. required symmetry, and no permission to invent extra geometry. The agent
  186. executes and verifies the spec; it does not silently fill in the engineering.
  187. <details>
  188. <summary><strong>Copy the motor mounting fixture prompt</strong></summary>
  189. ```text
  190. Create a fully specified industrial motor mounting fixture using millimeters.
  191. Coordinate system:
  192. - X is the fixture width, Y is the fixture depth, and Z is vertical.
  193. - Center the complete fixture on X=0.
  194. - Place the bottom face of the base plate at Z=0.
  195. Base plate:
  196. - Create a 180 × 140 × 14 mm base plate.
  197. - Add four Ø11 mm vertical through-holes at X=±70 mm and Y=±50 mm.
  198. - Add an Ø18 mm, 5 mm deep counterbore to the top of every mounting hole.
  199. - Add a 3 mm fillet to the four outside vertical corners.
  200. Motor support:
  201. - Add a centered rear vertical support plate, 130 mm wide, 14 mm thick,
  202. and 120 mm tall above the base.
  203. - Add a Ø72 mm horizontal locating bore through the plate along Y.
  204. - Position its center at X=0 and Z=78 mm.
  205. - Add four Ø8.5 mm horizontal mounting holes on a Ø100 mm bolt circle.
  206. Reinforcement and rails:
  207. - Add two mirrored 12 mm thick triangular gussets extending 45 mm forward
  208. and rising 65 mm above the base.
  209. - Add two separate 110 × 12 × 8 mm guide rails centered at X=±38 mm, Y=-12 mm.
  210. - Add one centered 70 × 6 mm longitudinal slot to each rail.
  211. Modeling requirements:
  212. - Create named parts "fixture_body", "guide_rail_left", and "guide_rail_right".
  213. - Color the fixture body dark blue-gray and both guide rails orange.
  214. - Declare all major dimensions as editable UPPER_SNAKE_CASE constants.
  215. - Preserve exact left/right symmetry.
  216. - Verify overall dimensions, named parts, and stable topology pointers.
  217. - Run the deterministic engineering critique after modeling.
  218. - Do not add a motor, fasteners, logos, decorative features, or unspecified geometry.
  219. ```
  220. </details>
  221. ## Industrial CAD examples
  222. Each example starts from explicit dimensions, feature locations, and modeling
  223. constraints — the agent executes and verifies the specification rather than
  224. inventing the requirements.
  225. <table>
  226. <tr>
  227. <td width="33%" align="center">
  228. <a href="docs/assets/images/example1.webp">
  229. <img src="docs/assets/images/example1.webp" width="100%" alt="aieng generating and verifying a fully specified machined bearing support bracket"/>
  230. </a>
  231. <br>
  232. <strong>Machined Bearing Bracket</strong>
  233. <br>
  234. <sub>Datums, bore, mounting pattern, gussets, fillets, and critique</sub>
  235. </td>
  236. <td width="33%" align="center">
  237. <a href="docs/assets/images/example2.webp">
  238. <img src="docs/assets/images/example2.webp" width="100%" alt="aieng generating and auditing a fully specified six-port pneumatic manifold"/>
  239. </a>
  240. <br>
  241. <strong>Six-Port Pneumatic Manifold</strong>
  242. <br>
  243. <sub>Exact envelope, port spacing, counterbores, and editable dimensions</sub>
  244. </td>
  245. <td width="33%" align="center">
  246. <a href="docs/assets/images/example3.webp">
  247. <img src="docs/assets/images/example3.webp" width="100%" alt="aieng generating a named-part industrial junction-box assembly with stable face pointers"/>
  248. </a>
  249. <br>
  250. <strong>Industrial Junction Box</strong>
  251. <br>
  252. <sub>Named assembly parts, exported artifacts, and stable face pointers</sub>
  253. </td>
  254. </tr>
  255. </table>
  256. <details>
  257. <summary><strong>What these examples verify</strong></summary>
  258. - **Machined bearing support bracket** — one manufacturable solid with a
  259. specified base envelope, horizontal bearing bore, symmetric mounting pattern,
  260. mirrored gussets, fillets, and chamfers. The workbench caught and corrected
  261. construction errors, then verified the final datums, topology, editable
  262. parameters, and engineering critique.
  263. - **Six-port pneumatic manifold** — a specification-driven manifold with an
  264. exact `160 × 50 × 40 mm` envelope, six equally spaced outlets, axial inlet
  265. ports, counterbored mounting holes, edge fillets, opening chamfers, and
  266. editable dimensions.
  267. - **Industrial junction-box assembly** — a two-part enclosure assembly with
  268. named base and lid solids, internal mounting bosses, cable-gland openings,
  269. separated lid placement, generated STEP/STL/GLB artifacts, and a selectable
  270. stable face pointer for precise follow-up work.
  271. </details>
  272. ## Why aieng — beyond text-to-CAD
  273. Most AI CAD and text-to-CAD demos stop when a model appears. aieng treats
  274. geometry generation as one step in a **reviewable engineering workflow** built
  275. around self-describing `.aieng` packages: editable parameters, stable topology,
  276. provenance, and a full CAD → CAE path all survive after the picture.
  277. Think of `.aieng` as a portable engineering evidence passport. It is not a CAD
  278. kernel, solver, PLM database, or certification stamp; it is the shared package
  279. where humans and MCP-capable agents can inspect what geometry exists, what CAE
  280. setup is present, what result evidence was written, which claims cite evidence,
  281. and what provenance explains how the package got there. A package can be handed
  282. to another engineer or agent without losing the CAD/CAE context that matters for
  283. review; see the [package handoff runbook](docs/aieng-package-handoff.md) for the
  284. safe send/receive flow.
  285. | Capability | Typical text-to-CAD demo | aieng |
  286. |------------|:------------------------:|:-----:|
  287. | Generate real CAD exports (STEP/STL/GLB) | Yes | Yes |
  288. | Execute explicit dimensions and datums | Partial | Yes |
  289. | Preserve editable source and parameters | Partial | Yes |
  290. | Name parts and expose stable topology references | Rarely | Yes |
  291. | Verify geometry and run deterministic critique | Rarely | Yes |
  292. | Diff every edit (topology drift + manufacturability) | No | Yes |
  293. | Design-rule assertions that fail the build (`require`) | No | Yes |
  294. | Stamp a credibility tier on every result (V&V-40) | No | Yes |
  295. | Preserve artifacts and provenance in one package | Rarely | Yes |
  296. | Continue from CAD into CAE workflows | Rarely | Yes |
  297. | Require approval for gated engineering actions | Rarely | Yes |
  298. | Standard parts library | No | Yes |
  299. | Extended material database (51 materials) | No | Yes |
  300. | BOM generation | No | Yes |
  301. What that buys you:
  302. - **Real, exportable CAD** — agent-written build123d / OpenCASCADE geometry
  303. produces STEP, STL, GLB, topology maps, feature graphs, and 4-view thumbnails.
  304. Not a stub.
  305. - **Specification-driven execution** — agents follow explicit dimensions,
  306. datums, feature positions, symmetry, and manufacturing constraints instead of
  307. freely inventing a design.
  308. - **Inspect and correct** — geometry reports, deterministic critiques, named
  309. parts, and stable `@face:*` pointers support precise verification and
  310. follow-up edits.
  311. - **Reproducible engineering packages** — `.aieng` packages preserve geometry,
  312. generated source, analysis state, artifacts, metadata, and provenance, so a
  313. result is reviewable instead of opaque.
  314. - **Agent-independent MCP tools** — Claude Code, GitHub Copilot, OpenAI Codex,
  315. Cursor, and other MCP-capable agents drive the same backend.
  316. - **CAD → CAE path** — material, boundary conditions, mesh, solver runs, result
  317. mappings, and evidence live beside the CAD model.
  318. **Who it's for:** AI agent / MCP developers wanting engineering tools beyond
  319. text and code; mechanical engineers exploring AI-assisted CAD/CAE with real
  320. geometry; and makers, researchers, and open-source contributors interested in
  321. CAD, CAE, MCP, VS Code extensions, or build123d / OpenCASCADE.
  322. ## Proof, not just screenshots
  323. Each successful CAD run can preserve inspectable artifacts, not just a rendered
  324. image:
  325. - generated build123d source,
  326. - STEP/STL/GLB exports,
  327. - named parts and editable parameters,
  328. - topology maps and stable `@face:*` pointers when mapping succeeds,
  329. - preview thumbnails,
  330. - critique and geometry-check results,
  331. - provenance and package metadata inside the `.aieng` evidence package.
  332. That means another engineer or MCP-capable agent can inspect, modify, rerun, and
  333. review the result instead of trusting a static render.
  334. ## Trust layer — verified & explainable by construction
  335. The crowded field is *generation*; the empty field is *trust*. Every
  336. AI-suggested change here is checked and explainable, not just rendered:
  337. - **Diff on every edit** — each parametric edit / part swap / append returns a
  338. `regression_diff` (did unintended parts move?) and a `critique_diff` (did the
  339. edit worsen min-wall / hole-spacing / floating-part / symmetry rules?),
  340. re-surfaced as a first-class before→after diff in the viewer.
  341. - **Design-rule assertions** — author `require(WALL >= 3, "wall below 3mm")` (or a
  342. bare `assert`) in build123d code; a violation fails the build deterministically
  343. with a structured `design_rule_violation`, so constraints are verified by
  344. construction instead of hoped for.
  345. - **V&V-40 credibility tiering** — every result-bearing output carries one ordered
  346. tier (`critique_finding` < `surrogate_prediction` < `proxy_assembly_result` <
  347. `executed_solver_result`); a claim is never presented as more credible than its
  348. evidence, and `production_ready` is never assumed. Running the solver is not
  349. enough: a completed run on a mesh whose measured accuracy band is `unreliable`
  350. is stamped `unreliable_mesh`, not `executed_solver_result`.
  351. - **Mesh accuracy by measurement, not hope** — FE meshes default to quadratic
  352. tetrahedra (C3D10; linear tets under-predicted bending stress ~2× in
  353. calibration), and every mesh carries a measured `accuracy` verdict
  354. (reliable / marginal / unreliable) plus an optional GCI/Richardson
  355. convergence study (`cae.mesh_convergence`).
  356. - **Surrogate error-band discipline** — a surrogate-predicted number is never shown
  357. without its uncertainty band + a leave-one-out validation error.
  358. - **Consistency-gated agency** — low cross-sample agreement on an LLM-judged step
  359. routes to *ask the user* instead of acting on a guess.
  360. - **NAFEMS-style V&V suite** — analytically-backed linear-static benchmarks guard
  361. the solver path in CI (results are *verified against reference within tolerance*,
  362. never "certified").
  363. ## How it works
  364. 1. Provide a mechanical specification with explicit dimensions and constraints.
  365. 2. An MCP-capable agent uses aieng tools to create real CAD geometry.
  366. 3. aieng exports the model and records named parts, topology, editable
  367. parameters, source, and provenance.
  368. 4. Inspect the result visually and numerically, then reference exact parts,
  369. features, or faces (`@face:*`) for follow-up changes.
  370. 5. Query the extended material database (51 engineering materials) to assign
  371. accurate mechanical and thermal properties to parts.
  372. 6. Insert standard parts — fasteners, bearings, shafts, structural profiles,
  373. and standard holes — directly from the library into the model.
  374. 7. Generate a Bill of Materials (BOM) from the assembled parts for review
  375. and procurement.
  376. 8. Continue into CAE setup and solver workflows once the required engineering
  377. inputs are available.
  378. **Materials & standard parts workflow:**
  379. ```
  380. aieng.list_materials { category: "Aluminum Alloy" }
  381. aieng.get_material_details { material_name: "Al6061-T6" }
  382. aieng.compare_materials { material_names: ["Al6061-T6", "Steel-316L"] }
  383. aieng.list_standard_parts { category: "fastener" }
  384. aieng.get_standard_part_specs { part_type: "hex_bolt", preset_name: "M8" }
  385. aieng.insert_standard_part { part_type: "hex_bolt", preset_name: "M8", position: [0,0,0] }
  386. aieng.generate_bom { format: "markdown" }
  387. ```
  388. The workbench UI and the
  389. [`aieng-vscode-extension`](aieng-vscode-extension) provide visual inspection for
  390. live backend projects and `.aieng` packages.
  391. ## Visual inspection in VS Code
  392. The VS Code extension is the most visual way to experience aieng — a front-end
  393. for the `.aieng` package format, MCP tools, and CAD/CAE backend that brings the
  394. AI-CAD design loop directly into your editor. It can:
  395. - open a local `.aieng` package as a read-only custom editor,
  396. - connect to a live backend project preview,
  397. - visualize generated GLB/STL CAD outputs,
  398. - and copy stable `@face:id` pointers back into your chat with an agent.
  399. The extension is one layer of the system, not the whole thing — the core is the
  400. package format and engineering backend that let agents and humans share
  401. reproducible CAD/CAE project state. Setup and development notes live in
  402. [`aieng-vscode-extension/README.md`](aieng-vscode-extension/README.md). For the
  403. current editor-first path, see
  404. [`docs/mcp-first-vscode-workflow.md`](docs/mcp-first-vscode-workflow.md).
  405. ## Drive aieng from AI agents via MCP
  406. The backend exposes its tool registry as an **MCP server** (`aieng-workbench`),
  407. so agents drive the workbench through their own harnesses — no API key needed on
  408. our side. Connection configs are committed and load automatically for a fresh
  409. clone, assuming the `aieng311` env exists:
  410. | Agent | Config file |
  411. |-------|-------------|
  412. | Claude Code | `.mcp.json` |
  413. | VS Code / GitHub Copilot | `.vscode/mcp.json` |
  414. | Cursor | `.cursor/mcp.json` |
  415. | Cline | its own `cline_mcp_settings.json` (copy the block from MCP_SETUP) |
  416. | OpenAI Codex | add `[mcp_servers.*]` to `~/.codex/config.toml` (see MCP_SETUP) |
  417. **Approval works three ways** (`--approval-mode`): your client's own prompt
  418. (`client`), the workbench viewer / VS Code extension card (`managed`), or
  419. **headless MCP elicitation** (`elicit`) for agents with no UI — with a fail-safe
  420. deny when no surface can answer. Run `aieng-workbench-mcp --doctor` to check that
  421. your MCP config, backend, and tool set are wired before you start. Full matrix
  422. of tested-vs-documented clients:
  423. [MCP client compatibility](aieng-ui/backend/docs/mcp_client_compatibility.md).
  424. **First three calls every session:**
  425. ```
  426. 1. aieng.agent_readme -> compact operational onboarding
  427. 2. aieng.list_projects -> discover project IDs
  428. 3. aieng.agent_context { project_id } -> geometry state, pointers, next steps
  429. ```
  430. Use `aieng.guide { topic }` for task-specific detail, or
  431. `aieng.agent_readme { detail: "full" }` (returned in parts) when the complete
  432. canonical [`AGENTS.md`](AGENTS.md) is genuinely required.
  433. **The sustainable modeling loop:**
  434. ```
  435. cad.get_source -> see accumulated source, named parts, has_base
  436. cad.execute_build123d -> build/extend geometry (mode=replace|append)
  437. - set .label on parts -> semantic names you can reference
  438. - mode=append builds onto `previous_result`
  439. - returns a thumbnail + named_parts / parts_added
  440. (inspect the result, repeat)
  441. ```
  442. Full tool details, pointer syntax, and approval-gated operations live in
  443. [AGENTS.md](AGENTS.md); MCP wiring by client in
  444. [aieng-ui/backend/MCP_SETUP.md](aieng-ui/backend/MCP_SETUP.md).
  445. ## Showcase demos
  446. Canonical backend demos, each runnable as a single test:
  447. ### 1. CAD Generation → Structural FEA → Topology Optimization
  448. Runs the CAD → FEA → topology optimization loop and writes back editable
  449. optimized geometry.
  450. <img src="docs/assets/showcase/geometry_cae_flow.svg" width="800" alt="CAD Generation to Structural FEA to Topology Optimization"/>
  451. ```bash
  452. pytest aieng/tests/test_topology_optimization.py -q
  453. ```
  454. **Key artifacts:** `analysis/topology_optimization.json`, `geometry/shape_ir.json`
  455. **Boundary:** 2D plane-stress; 3D SIMP is experimental/reference only.
  456. [Details →](aieng/docs/showcase_gallery.md)
  457. ### 2. Rebuild CAD from Mesh → Export STEP
  458. Reconstructs analytic CAD from a mesh and exports STEP when the shell validates.
  459. <img src="docs/assets/showcase/mesh_to_cad_flow.svg" width="880" alt="Mesh to Region Segmentation to Surface Fitting to Face Generation to Sew Shell to Export STEP"/>
  460. ```bash
  461. pytest aieng/tests/test_mesh_brep_solidification.py -q
  462. ```
  463. **Key artifacts:** `geometry/reconstructed.step` (when valid),
  464. `graph/mesh_brep_stitching_plan.json`
  465. **Boundary:** Mesh-derived/lossy; plane/cylinder dominant; freeform/NURBS
  466. future work; partial shells do not produce STEP.
  467. [Details →](aieng/docs/showcase_gallery.md)
  468. ### 3. Assembly Model → Selected-Part Optimization
  469. Builds a proxy assembly analysis model and optimizes one selected design part.
  470. <img src="docs/assets/showcase/assembly_optimization_flow.svg" width="880" alt="Assembly Model to Resolve Interfaces to Simplified Analysis to Topopt Problem to Optimized Part"/>
  471. ```bash
  472. pytest aieng-ui/backend/tests/test_assembly_topopt_demo.py -q
  473. ```
  474. **Key artifacts:** `analysis/assembly_topology_optimization.json`,
  475. `parts/bracket/geometry/optimized_shape_ir.json`
  476. **Boundary:** Proxy connections only; no real contact/friction/bolt preload;
  477. one design part only; not production-certified.
  478. [Details →](aieng/docs/showcase_gallery.md)
  479. ### 4. Design Study: Adjustable Dimensions → Compare → Adopt
  480. Validates, executes, compares, and optionally adopts parameterized design
  481. candidates without overwriting the baseline.
  482. <img src="docs/assets/showcase/design_study_flow.svg" width="960" alt="Setup Problem to Propose Candidate to Safety Checks to Build Design Copy to Compare Options to Adopt Best"/>
  483. ```bash
  484. pytest aieng-ui/backend/tests/test_design_study_demo.py -q
  485. ```
  486. **Key artifacts:** `analysis/design_study_candidate_ranking.json`,
  487. `analysis/design_study_acceptance.json`,
  488. `accepted/candidate_good/geometry/shape_ir.json`
  489. **Boundary:** Static metrics in demo; no autonomous optimization; no baseline
  490. overwrite; ranking is advisory.
  491. [Details →](aieng/docs/showcase_gallery.md)
  492. ### 5. Real CAD->CAE Value Demo
  493. Runs one canonical single-solid cantilever through CAD creation, face-pointer
  494. selection, approval-gated CalculiX execution, a GCI/Richardson mesh-convergence
  495. study, FRD-derived viewer fields, and a shareable engineering report.
  496. ```bash
  497. python aieng-ui/backend/scripts/value_demo_packet.py --format markdown
  498. ```
  499. **Key artifacts:** `simulation/runs/value_demo_run_001/outputs/result.frd`,
  500. `results/computed_metrics.json`, `analysis/mesh_convergence_report.json`,
  501. engineering report HTML.
  502. **Boundary:** Requires real Gmsh/CalculiX; linear static — discretization
  503. uncertainty is bounded by the GCI study (measured 1.31% on the reference
  504. cantilever), not assumed away; no synthetic fallback counts as a successful demo.
  505. [Runbook ->](docs/cad-cae-value-demo.md)
  506. ## Current limitations
  507. Honesty boundaries — outputs are review material, not production sign-off:
  508. - Not production-certified CAD/CAE. Outputs still require human engineering judgment.
  509. - **No fatigue or durability analysis.** Supported: linear static, modal, linear buckling, steady-state thermal, one-way thermal-stress. A cyclic load, a cycle count and a required life have nowhere to be entered, and the material library carries no endurance or S-N data. A cold-start agent trial found this boundary stated in exactly one document, so it is stated here too.
  510. - Assembly contact and bolt preload are proxy-only; real nonlinear contact is future work.
  511. - 3D SIMP is experimental/reference, not production-certified.
  512. - Mesh-to-CAD works best for plane/cylinder-dominant geometry; broader freeform
  513. and NURBS fitting is future work.
  514. - Design study is agent-guided explicit execution, not autonomous global optimization.
  515. ## Repository layout
  516. | Path | Status | What it is |
  517. |------|--------|------------|
  518. | **`aieng-ui/`** | **Active** | FastAPI backend, React workbench, and MCP server — the active CAD/CAE engine (build123d) |
  519. | `aieng/` | Core library | `.aieng` semantic package format engine, schemas, validation, CLI, Shape IR, and evidence model |
  520. | `aieng-vscode-extension/` | Active | VS Code visualization front-end for `.aieng` packages and live project previews |
  521. | `aieng-agent-skills/` | Active | `SKILL.md` contracts teaching agents how to use the ecosystem |
  522. | `legacy/aieng-freecad-mcp/` | Legacy | Old FreeCAD execution adapter — not used by the active path |
  523. | `archive/CAD-Agent-main/` | Archived | Historical and experimental auxiliary CAD-agent material |
  524. ## Documentation
  525. | Doc | Purpose |
  526. |-----|---------|
  527. | [AGENTS.md](AGENTS.md) | Canonical agent guide — tools, workflows, and conventions |
  528. | [docs/prompt-guide.md](docs/prompt-guide.md) | Plain sentences to type at your connected agent — the user-facing phrasing guide |
  529. | [aieng-ui/backend/MCP_SETUP.md](aieng-ui/backend/MCP_SETUP.md) | Per-agent MCP wiring for Claude Code, Copilot, Cursor, and Codex |
  530. | [docs/cad_execution_boundary.md](docs/cad_execution_boundary.md) | Local-first execution boundary, privacy posture, approval gates, and sandbox limits |
  531. | [docs/parametric-edit-governance.md](docs/parametric-edit-governance.md) | Reviewable, reversible CAD parameter edit workflow and honesty boundaries |
  532. | [docs/cae-credibility-ladder.md](docs/cae-credibility-ladder.md) | CAE evidence tiers from artifact presence to benchmark calibration and review support |
  533. | [docs/canonical_engineering_scenarios.md](docs/canonical_engineering_scenarios.md) | Canonical engineering scenarios - reproducible packs, verification commands, artifacts, and honesty boundaries |
  534. | [aieng-vscode-extension/README.md](aieng-vscode-extension/README.md) | VS Code extension usage and development notes |
  535. | [aieng/docs/showcase_gallery.md](aieng/docs/showcase_gallery.md) | Showcase gallery — demo talking points, visual guidance, and honesty boundaries |
  536. | [aieng/docs/demo_catalog.md](aieng/docs/demo_catalog.md) | Backend demo catalog — run commands, expected artifacts, and maturity levels |
  537. | [aieng/docs/backend_capability_matrix.md](aieng/docs/backend_capability_matrix.md) | Capability status snapshot |
  538. | [aieng/docs/roadmap.md](aieng/docs/roadmap.md) | Phase-by-phase development roadmap |
  539. | [CLAUDE.md](CLAUDE.md) | Claude Code entry pointer |
  540. | [.github/copilot-instructions.md](.github/copilot-instructions.md) | GitHub Copilot entry pointer |
  541. ## Contributing
  542. Contributions are welcome across the package format, backend workflows, MCP
  543. tooling, and VS Code front-end. Work that improves reproducibility, visual
  544. inspection, engineering honesty boundaries, or agent usability is especially in
  545. scope.
  546. ## Notes
  547. - Public repo. No secrets are committed; runtime data (`data/projects/`),
  548. virtual environments, `node_modules`, and embedded conda envs are gitignored.
  549. - If your CAD env is not named `aieng311`, edit the `-n aieng311` argument in
  550. the MCP configs or point `command` directly at your interpreter — see
  551. [aieng-ui/backend/MCP_SETUP.md](aieng-ui/backend/MCP_SETUP.md).
  552. - A running backend at `http://127.0.0.1:8000` enables live UI updates when an
  553. agent drives a build; if it is down, the MCP server falls back to in-process
  554. execution.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.