@coloopx/colocad 0.1.0-alpha.4 → 0.1.0-alpha.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +133 -99
- package/README.zh-CN.md +145 -79
- package/docs/README.md +7 -4
- package/docs/README.zh-CN.md +9 -3
- package/docs/agent-modeling-handbook.md +68 -0
- package/docs/agent-modeling-handbook.zh-CN.md +222 -0
- package/docs/agent-modeling-research.md +22 -0
- package/docs/api.md +95 -0
- package/docs/best-practices.md +45 -0
- package/docs/concepts.md +37 -0
- package/docs/getting-started.md +53 -0
- package/docs/integrations/claude-code.md +52 -0
- package/docs/integrations/codex.md +55 -0
- package/docs/integrations/overview.md +53 -0
- package/docs/integrations/pi.md +73 -0
- package/docs/integrations/verification.md +30 -0
- package/docs/modeling-workflow.zh-CN.md +77 -0
- package/docs/native-solidworks.md +12 -0
- package/docs/performance.md +62 -0
- package/docs/troubleshooting.md +25 -0
- package/docs/validation.md +23 -0
- package/examples/hiwin-kk60/README.md +1 -1
- package/examples/integrations/README.md +47 -0
- package/examples/integrations/compact-tools.mjs +27 -0
- package/examples/integrations/guided-workflow.mjs +31 -0
- package/kernel/release.json +1 -1
- package/package.json +5 -2
- package/skills/colocad/SKILL.md +17 -9
- package/skills/colocad/assets/product-brief.example.json +20 -0
- package/skills/colocad/references/materials.md +37 -0
- package/skills/colocad/references/modeling-loop.md +33 -0
- package/skills/colocad/references/prompt-patterns.md +70 -0
- package/skills/colocad/references/tool-contracts.md +33 -0
- package/skills/colocad/references/tuning.md +30 -0
package/README.md
CHANGED
|
@@ -1,161 +1,195 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Colocad
|
|
2
2
|
|
|
3
|
-
[
|
|
3
|
+

|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Parametric CAD for agents. Local Rust geometry, a TypeScript SDK, a CLI, and an inspectable modeling history.**
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[中文](README.zh-CN.md) · [Documentation](docs/README.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Releases](https://github.com/Coloopx/colocad/releases) · [Model behind the cover](examples/hiwin-kk60/README.md)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Colocad turns explicit modeling instructions into editable source, exact STEP geometry and visual review artifacts. It runs alongside the agent and its harness **inside the same sandbox**. The npm package includes the compiled Rust kernel; installed modeling needs no Python, Rust toolchain, network or separate CAD service.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
**Alpha software:** useful for supported mechanical parts and assemblies, with measured performance and reproducible examples. It is not a complete replacement for build123d or a manufacturing-certified CAD system. See [support and limits](#support-and-limits).
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## What you can build
|
|
14
|
+
|
|
15
|
+
- **Parts and assemblies:** parametric features, repeated part definitions, exact STEP and PNG/GLB/STL previews.
|
|
16
|
+
- **Agent workflows:** SDK tools and a bundled skill for interpreting dimensions, planning features, editing and checking results.
|
|
17
|
+
- **Human review:** persistent build attempts, source/receipt inspection, offline single-file HTML and four-view MP4/GIF replay.
|
|
18
|
+
|
|
19
|
+
The SDK is the foundation; the CLI and tool adapters expose it to your harness; the skill guides modeling decisions. Images and drawings are evidence the agent interprets. Colocad executes explicit geometry instructions.
|
|
20
|
+
|
|
21
|
+
```mermaid
|
|
22
|
+
flowchart LR
|
|
23
|
+
A[Agent + skill] --> H[Existing harness]
|
|
24
|
+
H --> C[CLI / SDK tools]
|
|
25
|
+
C --> K[Local Rust kernel]
|
|
26
|
+
K --> F[STEP + source + receipts + meshes]
|
|
27
|
+
F --> V[CLI viewer / HTML / animation]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
Requires **Node.js 22+** on **Linux x64, Linux arm64 or macOS arm64**.
|
|
14
33
|
|
|
15
34
|
```sh
|
|
16
|
-
|
|
17
|
-
npx colocad view ./actuator/session
|
|
18
|
-
npx colocad replay ./actuator/session ./actuator.html
|
|
19
|
-
# Optional: Playwright/Chromium + FFmpeg are required for video encoding.
|
|
20
|
-
npx colocad render ./actuator/session ./modeling.mp4
|
|
35
|
+
npm install @coloopx/colocad@0.1.0-alpha.6
|
|
21
36
|
```
|
|
22
37
|
|
|
23
|
-
|
|
38
|
+
The package ships JS/TS APIs, the CLI, native executables, viewer and complete skill. Rust source is in [crates/agent-cad](crates/agent-cad); the npm tarball contains compiled binaries. [Package and model formats](docs/concepts.md).
|
|
24
39
|
|
|
25
|
-
##
|
|
40
|
+
## Quick start
|
|
26
41
|
|
|
27
|
-
|
|
42
|
+
Run these commands from your Node project:
|
|
28
43
|
|
|
29
|
-
|
|
44
|
+
```sh
|
|
45
|
+
# Build the packaged manifold and save its source, receipt and geometry.
|
|
46
|
+
npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
|
|
47
|
+
--label "Build the manifold"
|
|
30
48
|
|
|
31
|
-
|
|
49
|
+
# Launch the interactive viewer.
|
|
50
|
+
npx colocad view ./history
|
|
32
51
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
| First STEP | **2.223 s** | 3.010 s |
|
|
37
|
-
| Median job time on the same first 33 inputs | **2.234 s** | 2.855 s |
|
|
38
|
-
| Highest sampled cgroup memory over the 100 s window | **130.9 MiB** | 304.9 MiB |
|
|
52
|
+
# Export one offline HTML file, including a final STEP download.
|
|
53
|
+
npx colocad replay ./history ./review.html
|
|
54
|
+
```
|
|
39
55
|
|
|
40
|
-
|
|
56
|
+
The manifold includes an extrusion, blind cut, fillet, linear pattern and pocket. Record an edited JSON into the same history directory to append a revision; failed attempts remain visible. `view` serves a snapshot, so reopen it after adding revisions. [First part and parameter edit](docs/getting-started.md).
|
|
41
57
|
|
|
42
|
-
|
|
58
|
+
Prefer an API? Use the same kernel through a persistent session:
|
|
43
59
|
|
|
44
|
-
|
|
45
|
-
|
|
60
|
+
```js
|
|
61
|
+
import { ModelingSession } from '@coloopx/colocad/session';
|
|
62
|
+
|
|
63
|
+
const session = await ModelingSession.create('./sdk-history');
|
|
64
|
+
const result = await session.build({
|
|
65
|
+
version: 1, units: 'mm', parameters: { length: 60 },
|
|
66
|
+
features: [{ id: 'stock', op: 'box', origin: [0, 0, 0],
|
|
67
|
+
size: [{ param: 'length' }, 30, 8] }],
|
|
68
|
+
output: 'stock',
|
|
69
|
+
});
|
|
70
|
+
if (!result.ok) throw new Error(JSON.stringify(result.error));
|
|
71
|
+
await session.edit({ length: 80 });
|
|
72
|
+
```
|
|
46
73
|
|
|
47
|
-
|
|
74
|
+
Use `CadClient` for direct builds without session recording. [SDK, CLI and tool API](docs/api.md).
|
|
48
75
|
|
|
49
|
-
|
|
76
|
+
## Visualize and export from the CLI
|
|
50
77
|
|
|
51
|
-
|
|
52
|
-
| :--- | ---: | ---: | ---: | ---: |
|
|
53
|
-
| Sensor rail | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
|
|
54
|
-
| Port manifold | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
|
|
55
|
-
| Tendon-hand proximal link | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
|
|
56
|
-
| Complete 43-solid hand | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
|
|
78
|
+

|
|
57
79
|
|
|
58
|
-
|
|
80
|
+
Inspect the timeline, source, features, receipts and selected parts. Switch cameras, show display sections or explosion, and download artifacts. The offline HTML embeds its rendering code and geometry. Hosts can also embed `@coloopx/colocad/viewer`.
|
|
59
81
|
|
|
60
|
-
|
|
82
|
+
| Command | Input | Result |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| `colocad plan TREE.json` | `colocad/1` feature tree | Compile and inspect a native job |
|
|
85
|
+
| `colocad build TREE.json NEW_DIR --preview` | Feature tree | STEP, editable source and previews |
|
|
86
|
+
| `colocad record MODEL.json SESSION` | Feature tree or kernel JSON | Build and persist a milestone |
|
|
87
|
+
| `colocad view SESSION` | Saved session | Interactive local viewer |
|
|
88
|
+
| `colocad replay SESSION review.html` | Saved session | Self-contained offline HTML |
|
|
89
|
+
| `colocad render SESSION modeling.mp4` | Saved session | Four-view animation; `.gif` also supported |
|
|
61
90
|
|
|
62
|
-
|
|
91
|
+
In a headless sandbox, use `colocad view ./history --no-open --port 8787` with the harness's port forwarding; the listener binds to `127.0.0.1`.
|
|
63
92
|
|
|
64
|
-
|
|
93
|
+
```sh
|
|
94
|
+
# Optional movie dependencies; install FFmpeg on the host as well.
|
|
95
|
+
npm install -D playwright
|
|
96
|
+
npx playwright install chromium
|
|
97
|
+
npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
|
|
98
|
+
```
|
|
65
99
|
|
|
66
|
-
**
|
|
100
|
+
Movies replay **actual saved revisions**. Recorded call times and edited playback duration are separate. Building geometry and exporting HTML do not need Chromium or FFmpeg. [History, viewer and rendering guide](docs/modeling-history.md).
|
|
67
101
|
|
|
68
|
-
|
|
69
|
-
| --- | --- |
|
|
70
|
-
| Pi agent core / Pi coding agent | [Typed tool adapter, extension and skill](docs/integrations/pi.md) |
|
|
71
|
-
| Claude Code | [Project skill and local CLI](docs/integrations/claude-code.md) |
|
|
72
|
-
| Codex | [Project skill, invocation and artifact inspection](docs/integrations/codex.md) |
|
|
73
|
-
| Other harnesses | [Sandbox architecture, revision state and artifact lifecycle](docs/integrations/overview.md) |
|
|
102
|
+
## Use with your agent
|
|
74
103
|
|
|
75
|
-
|
|
104
|
+
Copy the whole skill, including its references, scripts and editable shape assets:
|
|
76
105
|
|
|
77
|
-
|
|
106
|
+
```sh
|
|
107
|
+
# Codex project skill; use .claude/skills for Claude Code.
|
|
108
|
+
mkdir -p .agents/skills
|
|
109
|
+
cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
|
|
110
|
+
```
|
|
78
111
|
|
|
79
|
-
|
|
112
|
+
If that skill already exists, preserve local customizations before updating it. Then ask:
|
|
80
113
|
|
|
81
|
-
-
|
|
82
|
-
- **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.3`. Run `./node_modules/.bin/colocad plan tree.json`, then `./node_modules/.bin/colocad build tree.json ./new-part --preview`. Open `new-part/part/model.step`.
|
|
83
|
-
- **From drawings with an agent:** install the [colocad skill](skills/colocad/SKILL.md). Start the next turn with “Use `$colocad` to reconstruct these four views, export STEP, and flag any internal details you inferred.” [Installation and assembly replay](showcase/tendon-hand/README.md#try-it-with-your-agent).
|
|
114
|
+
> Use the colocad skill to build a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches. Keep editable source and modeling history, verify the dimensions, and export STEP and an offline HTML review through the CLI.
|
|
84
115
|
|
|
85
|
-
|
|
116
|
+
| Harness | Integration |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| Codex | [Project skill and CLI](docs/integrations/codex.md) |
|
|
119
|
+
| Claude Code | [Project skill and local tools](docs/integrations/claude-code.md) |
|
|
120
|
+
| Pi core / coding agent | [Typed tool adapter and extension](docs/integrations/pi.md) |
|
|
121
|
+
| Your own harness | [SDK schemas, state and artifact lifecycle](docs/integrations/overview.md) |
|
|
86
122
|
|
|
87
|
-
|
|
123
|
+
The [end-to-end handbook](docs/agent-modeling-handbook.md) covers source preparation, dimension uncertainty, tool abstraction, prompts, modeling loops, validation and tuning. A [runnable guided workflow](examples/integrations/README.md) demonstrates real builds, quantitative edits and recovery; its decisions are scripted, not a live-LLM benchmark.
|
|
88
124
|
|
|
89
|
-
|
|
125
|
+
## Example: a complete linear actuator
|
|
90
126
|
|
|
91
|
-
|
|
127
|
+
The cover reconstructs a **HIWIN KK60, 300 mm rail, 5 mm lead, 210 mm travel** from manufacturer drawings: **52 final features, 81 named solid occurrences and 16 modeling milestones**. It includes a physically cut helical screw groove, rail tracks, mounting holes, carriage, bearings and coupling.
|
|
92
128
|
|
|
93
|
-
|
|
129
|
+
```sh
|
|
130
|
+
node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
|
|
131
|
+
npx colocad view ./actuator/session
|
|
132
|
+
npx colocad render ./actuator/session ./modeling.mp4
|
|
133
|
+
```
|
|
94
134
|
|
|
95
|
-
|
|
135
|
+
Independent OCCT checks cover all 16 STEP revisions, 64 material probes and selected rail/carriage clearances. Proprietary internals are explicitly approximated or omitted; this is a catalog reconstruction, not a production drawing package. The animation is not a speed benchmark.
|
|
96
136
|
|
|
97
|
-
|
|
98
|
-
| :--- | ---: | ---: | ---: |
|
|
99
|
-
| Sensor rail | 108.8 ms | 19.4 ms | **5.6×** |
|
|
100
|
-
| Port manifold | 223.8 ms | 13.3 ms | **16.8×** |
|
|
137
|
+
[MP4](showcase/hiwin-kk60/modeling.mp4) · [Editable model](showcase/hiwin-kk60/model.json) · [Checks](showcase/hiwin-kk60/verification.json) · [Dimensions and assumptions](examples/hiwin-kk60/sources.json) · [Full offline delivery](https://github.com/Coloopx/colocad/releases/download/v0.1.0-alpha.4/hiwin-kk60-delivery.zip)
|
|
101
138
|
|
|
102
|
-
|
|
139
|
+
## Performance
|
|
103
140
|
|
|
104
|
-
|
|
141
|
+
Performance depends on geometry and execution mode. In a measured 100-second queue of the same **43-solid tendon hand**, Colocad delivered **44 complete STEP revisions versus build123d's 33**, with **57.1% lower highest sampled sandbox memory**.
|
|
105
142
|
|
|
106
|
-
|
|
107
|
-
| :--- | :--- |
|
|
108
|
-
| Agent skill, CLI, JavaScript API, TypeScript declarations and precompiled Rust executables for **Linux x64, Linux arm64 and macOS arm64**. Node.js 22+. | [Rust CAD source](crates/agent-cad/src), [TypeScript kernel SDK](kernel/src), [feature compiler](src/tree.mjs), tests and [pinned SolidCore dependency](third_party/solidcore.lock.json). |
|
|
143
|
+

|
|
109
144
|
|
|
110
|
-
|
|
145
|
+
| Same revision queue, 1 vCPU / 512 MiB | Colocad | build123d |
|
|
146
|
+
| --- | ---: | ---: |
|
|
147
|
+
| Complete STEP deliveries in 100 s | **44** | 33 |
|
|
148
|
+
| First STEP | **2.223 s** | 3.010 s |
|
|
149
|
+
| Median job, same first 33 inputs | **2.234 s** | 2.855 s |
|
|
150
|
+
| Highest sampled cgroup memory | **130.9 MiB** | 304.9 MiB |
|
|
111
151
|
|
|
112
|
-
|
|
152
|
+
One window per backend; a fresh CAD process per revision; approximately 25 ms memory sampling includes subprocesses, temporary files and charged file cache. Every counted STEP reopened successfully. This run used the alpha.2 SDK and the optimized kernel first bundled in alpha.3; it is not a new alpha.6 measurement. The GIF plots the highest sample so far, not instantaneous usage. [Method and samples](showcase/tendon-hand/window/README.md).
|
|
113
153
|
|
|
114
|
-
|
|
154
|
+
<details>
|
|
155
|
+
<summary>Cold-start parts and cached previews</summary>
|
|
115
156
|
|
|
116
|
-
|
|
117
|
-
npm install @coloopx/colocad@alpha
|
|
118
|
-
npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
|
|
119
|
-
npx colocad build node_modules/@coloopx/colocad/examples/sensor-rail.json ./rail
|
|
120
|
-
```
|
|
157
|
+

|
|
121
158
|
|
|
122
|
-
The
|
|
159
|
+
The published alpha.2 kernel reached STEP **22.0× faster** for a sensor rail and **12.9× faster** for a manifold, using **7.7% and 8.0%** of build123d's peak memory. Five fresh processes/cgroups per part and backend after warm-up; Linux arm64, 1 vCPU / 512 MiB. Startup/imports, modeling, checks and export count; installation, previews, inference and a resident agent do not. These gains do not apply to every operation: manifold geometry alone took 53.7 ms versus build123d's 43.8 ms, and the old complete-hand result was slower.
|
|
123
160
|
|
|
124
|
-
|
|
161
|
+
For unchanged geometry, saved-mesh observation was 5.6×–16.8× faster than Colocad's own rebuild-and-render path on two parts. This is an internal cache comparison, not a build123d result.
|
|
125
162
|
|
|
126
|
-
|
|
127
|
-
import { readFile } from 'node:fs/promises';
|
|
128
|
-
import { build } from '@coloopx/colocad';
|
|
129
|
-
|
|
130
|
-
const tree = JSON.parse(await readFile('./node_modules/@coloopx/colocad/examples/manifold.json', 'utf8'));
|
|
131
|
-
await build(tree, './original');
|
|
132
|
-
tree.parameters.instances = 3;
|
|
133
|
-
const edited = await build(tree, './edited');
|
|
134
|
-
console.log(edited.geometry.volume_mm3);
|
|
135
|
-
```
|
|
163
|
+
</details>
|
|
136
164
|
|
|
137
|
-
|
|
165
|
+
[Full performance evidence and limitations](docs/performance.md) · [Offline comparison with STEP downloads](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html).
|
|
138
166
|
|
|
139
|
-
|
|
167
|
+
## Support and limits
|
|
140
168
|
|
|
141
|
-
|
|
169
|
+
- Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.6.json).
|
|
170
|
+
- Editable JSON/programs and exact STEP are supported; STEP does not preserve a commercial CAD application's native feature tree.
|
|
171
|
+
- General editable SOLIDWORKS output on Linux remains incomplete. The experimental Windows author requires licensed SOLIDWORKS, and a native rebuild pass is still unverified. [Native author status](docs/native-solidworks.md).
|
|
172
|
+
- CAD checks, drawing interpretation, edit preservation, fit and manufacturing readiness are separate claims. [Validation scope](docs/validation.md).
|
|
173
|
+
- A 512 MiB CAD test is not a memory guarantee for an entire resident agent, browser or video encoder.
|
|
142
174
|
|
|
143
|
-
|
|
175
|
+
## Documentation and help
|
|
144
176
|
|
|
145
|
-
|
|
146
|
-
colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
|
|
147
|
-
```
|
|
177
|
+
[Getting started](docs/getting-started.md) · [API](docs/api.md) · [Agent handbook](docs/agent-modeling-handbook.md) · [Skill](skills/colocad/SKILL.md) · [Troubleshooting](docs/troubleshooting.md) · [All documentation](docs/README.md)
|
|
148
178
|
|
|
149
|
-
|
|
179
|
+
For a bug or feature request, [open an issue](https://github.com/Coloopx/colocad/issues) with the package version, platform, minimal model and relevant receipt. Remove credentials and private source material.
|
|
150
180
|
|
|
151
|
-
##
|
|
181
|
+
## Develop and contribute
|
|
152
182
|
|
|
153
183
|
```sh
|
|
184
|
+
git clone https://github.com/Coloopx/colocad.git
|
|
185
|
+
cd colocad
|
|
186
|
+
npm ci
|
|
154
187
|
npm run build:kernel
|
|
155
188
|
npm test
|
|
156
|
-
node bin/colocad.mjs build examples/manifold.json ./out/manifold --preview
|
|
157
189
|
```
|
|
158
190
|
|
|
159
|
-
|
|
191
|
+
Building from source requires the Rust toolchain and fetches the pinned SolidCore dependency. Viewer/render and Pi integration checks have additional dependencies; see [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests and release instructions. Contributions are welcome as issues and pull requests.
|
|
192
|
+
|
|
193
|
+
## License and acknowledgments
|
|
160
194
|
|
|
161
|
-
|
|
195
|
+
Colocad application code is [MIT licensed](LICENSE). The kernel builds on [SolidCore](https://github.com/tangency-labs/solidcore), including work derived from NVIDIA USD BRep / SMLib; the viewer uses Three.js. Dependency licenses and attribution are in [NOTICE.md](NOTICE.md) and [kernel/licenses](kernel/licenses). The industrial example is not affiliated with or endorsed by HIWIN.
|