@coloopx/colocad 0.1.0-alpha.4 → 0.1.0-alpha.5
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 +101 -4
- package/README.zh-CN.md +82 -4
- package/docs/README.md +4 -3
- package/docs/README.zh-CN.md +7 -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/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
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
| Symptom | Check and action |
|
|
4
|
+
| --- | --- |
|
|
5
|
+
| Skill cannot be found | Check `.agents/skills/colocad/SKILL.md` for Codex/Pi or `.claude/skills/colocad/SKILL.md` for Claude Code; start in that project and refresh/restart discovery. |
|
|
6
|
+
| Skill helper cannot import colocad | Install the pinned package in the current project and run the helper from there. Copy the complete skill folder. |
|
|
7
|
+
| `colocad build` rejects `version: 1` | That CLI expects `format: "colocad/1"`. Use `CadClient` or the skill helper for a kernel model. |
|
|
8
|
+
| Output directory already exists | Pick a new revision destination for the CLI/helper. Keep earlier accepted output. `CadClient.outputRoot` can contain multiple revisions. |
|
|
9
|
+
| Unsupported platform / missing executable | Alpha.3 bundles Linux x64/arm64 and macOS arm64. Check `process.platform`, `process.arch` and the installed `kernel/native` directory. Source builds require a Rust toolchain and the pinned dependency. |
|
|
10
|
+
| Native launch fails | Check `LOCAL_EXECUTION_FAILED`, executable permissions, mount policy and `binary`/`AGENT_CAD_BINARY` overrides. Run the local CLI to isolate harness wiring. |
|
|
11
|
+
| `TIMEOUT` | Inspect the failing feature and workload. Simplify or split unnecessary work; adjust `wallMs` within 1–120,000 only when appropriate. Sandbox memory failures need sandbox diagnostics too. |
|
|
12
|
+
| `RESOURCE_LIMIT` / `OUTPUT_LIMIT` | Inspect capabilities and reduce model/mesh payload. SDK stdin is limited to 32 MiB; the feature-tree CLI accepts 2 MiB. |
|
|
13
|
+
| Unknown/missing parameter | Use an existing finite numeric parameter. `edit()` does not create parameters; update the owned source to add one. |
|
|
14
|
+
| An edit undoes a prior change | You reused stale source. Load the last accepted `model.json` or persist the merged parameters after each successful edit. |
|
|
15
|
+
| Preview succeeds but no STEP in its directory | A cached observation points to `source_artifact_directory`. Retrieve STEP from the source geometry revision. |
|
|
16
|
+
| Cached preview cannot be read | Retain its source directory and files; do not modify cache bytes. Rebuild from the saved model if the cache was pruned or is invalid. |
|
|
17
|
+
| Agent cannot see the rendered image | Attach PNG as image content or invoke the harness's image-reading tool. Printing the local filename alone is insufficient. |
|
|
18
|
+
| Provider rejects tool schema | Preserve root `$defs`; check the provider's schema restrictions. Use skill + shell tools if the provider cannot accept the complete schema. |
|
|
19
|
+
| No editable native SOLIDWORKS tree | STEP is not a feature-history file. The Windows author is experimental; generic Linux native authoring is not complete. |
|
|
20
|
+
|
|
21
|
+
Some low-level failures retain the legacy error code `WORKER_FAILED`. It is an error label in alpha.3, not a requirement to deploy a separate service. Native execution is local.
|
|
22
|
+
|
|
23
|
+
For a useful bug report, include package/platform/Node versions, minimal model JSON, the failed receipt, expected geometry and reproduction command. Remove credentials and private design data. Attach a small STEP and screenshot when shareable. Keep the original file if the failure depends on STEP import; otherwise reduce the model to the failing dependency chain.
|
|
24
|
+
|
|
25
|
+
See [Contributing](../CONTRIBUTING.md) for the test commands and [validation](validation.md) for known limitations.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Release validation
|
|
2
|
+
|
|
3
|
+
The same public build API compiled the two different feature trees in `examples/`. The manifold has one solid with 27 faces and 54 edges. OCCT read its STEP as a valid solid with volume 45,490.923866 mm³. Reducing the blind-port count from four to three restored 226.194671 mm³, matching π × 3² × 8. The rail has rectangular through-slots patterned along Y. Removing one slot restored 405 mm³. The validation script also probes points within and outside the blind ends, the pocket, and the fillet.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
The native Windows author compiled against SOLIDWORKS 2024 interop 32.1.0. Runtime creation, feature edit, force rebuild and reopen in the vendor application remain unverified.
|
|
8
|
+
|
|
9
|
+
The Linux file-format experiment started with a synthesized envelope containing no part geometry or feature tree. On an empty source the pinned Rust encoder refuses synthesis without retained signature tokens. Providing a minimal envelope allowed a cube to round-trip as one solid with six faces. For the actual manifold, its exported STEP contains 54 explicit trim ranges. Of these, 32 are lines delimited by their vertices, 8 are closed full circles and 14 are clamped full-domain NURBS. Checking that the endpoints and natural domains agree permits equivalent vertex-delimited geometry. The experimental re-read then recovered one solid, 27 faces, 54 edges and zero neutral validation findings. This result contains a geometry partition only. Editable fillet selection ownership and native feature-pattern seed references still need to be serialized and independently proven. The CLI intentionally does not release these experimental bytes as an editable part.
|
|
10
|
+
|
|
11
|
+
The packaged npm archive was installed offline and invoked through the sandbox-local Pi bash tool in an Abelien Linux arm64 runner limited to 1 vCPU and 512 MiB. In the [scoped 0.1.0-alpha.2 run](evidence/scoped-runner.json) the manifold build with preview took 272 ms, the rail 84 ms and the pattern-count edit 181 ms. These are single tool-call wall times. The full cgroup peak includes the offline npm install, cache and files staged on tmpfs. See the JSON receipts in [evidence](evidence/).
|
|
12
|
+
|
|
13
|
+
We also tested the first two manifold operations with a freshly generated, matching B-rep and a sketch graph compiled directly from the same job. The independent decode of the experimental bytes recovered seven sketch entities across two sketches, one extrusion and one cut. The native operation-class and driving-scalar counts were both zero. Adding the rim fillet to the full graph produced a native encoder refusal at the edge-selection group. The records are in [native-prefix.json](evidence/native-prefix.json) and [native-full-refusal.txt](evidence/native-full-refusal.txt). These are file-format diagnostics, with no claim of successful rebuild in SOLIDWORKS.
|
|
14
|
+
|
|
15
|
+
The fillet selector separately found all six intended edges in the B-rep recovered for the state immediately preceding the fillet. Both adjacent faces and both endpoints are recorded for each edge. Mapping those input-state identities to persistent SOLIDWORKS operands remains open. In a second diagnostic without the fillet, file readback recovered the linear pattern (four instances along X at 18 mm pitch) and its link to the port-cut seed. Its native operation-class and driving-scalar counts were still zero. See [input-state edges](evidence/historical-selection.json) and [pattern diagnostic](evidence/native-pattern.json).
|
|
16
|
+
|
|
17
|
+

|
|
18
|
+
|
|
19
|
+
## npm release 0.1.0-alpha.3
|
|
20
|
+
|
|
21
|
+
The [archive checks and independent STEP measurements](evidence/release-alpha.3.json) cover macOS arm64, Linux arm64 and Linux x64. Both Linux installations ran offline with 1 vCPU and 512 MiB. The x64 check used an emulated x64 environment and exercised the x64 Node executable and native kernel. Each installation used the packaged CLI to build a manifold and the bundled skill to build a six-hole plate, a sleeve pair and a complete 43-solid hand. OCCT reopened all twelve STEP files. The hand report counted 21 measured instances and 22 translated reuses on each platform.
|
|
22
|
+
|
|
23
|
+
For a release, stage the three tested executables and their manifests under `kernel/native/<platform>/`. Record the corresponding SHA-256 values and npm version in `kernel/release.json`. The `prepack` check rejects missing executables and hashes that differ from the recorded build. Run `npm pack`, install that tarball in an empty consumer project on each platform, and run `node /path/to/checkout/test/validation/packed.mjs` from that project. Provide the hand model JSON as an optional argument to exercise all 43 occurrences. Publish that tested tarball directly.
|
|
@@ -4,7 +4,7 @@ This example models one complete configuration of a real product: **HIWIN KK60 s
|
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
7
|
-
[MP4](../../showcase/hiwin-kk60/modeling.mp4) · [Editable generated model](../../showcase/hiwin-kk60/model.json) · [Independent verification](../../showcase/hiwin-kk60/verification.json) · [Source dimensions and assumptions](sources.json)
|
|
7
|
+
[Complete offline delivery: HTML, STEP and session ZIP](https://github.com/Coloopx/colocad/releases/download/v0.1.0-alpha.4/hiwin-kk60-delivery.zip) · [MP4](../../showcase/hiwin-kk60/modeling.mp4) · [Editable generated model](../../showcase/hiwin-kk60/model.json) · [Independent verification](../../showcase/hiwin-kk60/verification.json) · [Source dimensions and assumptions](sources.json)
|
|
8
8
|
|
|
9
9
|
## Build, view and export through the CLI
|
|
10
10
|
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Runnable integration examples
|
|
2
|
+
|
|
3
|
+
This example project installs published `@coloopx/colocad@0.1.0-alpha.3`. It does not depend on a locally compiled kernel. Node.js 22+ and one of the package's supported platforms are required.
|
|
4
|
+
|
|
5
|
+
From the repository root:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm ci --prefix examples/integrations --ignore-scripts
|
|
9
|
+
npm test --prefix examples/integrations
|
|
10
|
+
node examples/integrations/sdk.mjs ./out/sdk-example
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`sdk.mjs` validates a four-hole plate, renders it, changes the camera using its cached mesh, changes the bore diameter and saves the current source. It prints the artifact paths. Its output root can be reused because the SDK creates new revision subdirectories.
|
|
14
|
+
|
|
15
|
+
| File | Purpose |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| [sdk.mjs](sdk.mjs) | Actual SDK modeling/edit/observation cycle |
|
|
18
|
+
| [pi-tools.mjs](pi-tools.mjs) | Five Pi tools, schema preservation, error mapping and PNG attachment |
|
|
19
|
+
| [pi-core.mjs](pi-core.mjs) | Construct a Pi core agent with a caller-supplied model and stream function |
|
|
20
|
+
| [pi-extension.mjs](pi-extension.mjs) | Register the same tools in Pi coding agent |
|
|
21
|
+
| [integration.test.mjs](integration.test.mjs) | Real native calls and Pi loop/extension/skill discovery regression tests |
|
|
22
|
+
|
|
23
|
+
The test model stream is scripted; no LLM provider or credentials are needed. The test asserts a failed edit reaches the agent as an error and the subsequent corrected call exports STEP. It measures integration correctness, not model intelligence or drawing reconstruction success.
|
|
24
|
+
|
|
25
|
+
Use the [Pi guide](../../docs/integrations/pi.md) to connect real inference. [Codex](../../docs/integrations/codex.md) and [Claude Code](../../docs/integrations/claude-code.md) use the bundled skill and local CLI. These example files live in GitHub and are not part of the existing alpha.3 tarball.
|
|
26
|
+
|
|
27
|
+
## Record history in the source checkout
|
|
28
|
+
|
|
29
|
+
The original SDK tests still pin the published alpha.3 package as a compatibility baseline. The new recorded paths import this checkout's `/session` module and use its native executable.
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
node examples/integrations/recorded-pi.mjs ./out/recorded-pi
|
|
33
|
+
node examples/integrations/shell-harness.mjs codex ./out/codex-project
|
|
34
|
+
node examples/integrations/shell-harness.mjs claude-code ./out/claude-project
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`recorded-pi.mjs` runs an actual Pi tool loop with a scripted stream: build, failed edit, correction, then offline replay. `shell-harness.mjs` installs the complete skill into the corresponding project skill directory and executes its helper and the record/replay CLI. These validate local tool integration, not live Codex/Claude inference. The Pi extension opts into recording when `COLOCAD_SESSION_DIR` is set. SDK callers pass `cadSession` to `createCadAgent`. All code runs in the same sandbox.
|
|
38
|
+
|
|
39
|
+
## Compact feedback and a complete guided workflow (alpha.5)
|
|
40
|
+
|
|
41
|
+
`compact-tools.mjs` preserves the existing schemas and error/degradation semantics while returning measurements, timing and references to full receipts. It is transport-neutral. `guided-workflow.mjs` executes real native modeling, analytic edit checks, failure recovery, cached observation and CLI HTML export. Both files are included in the alpha.5 package.
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
node examples/integrations/guided-workflow.mjs ./out/guided-workflow
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Read the [handbook](../../docs/agent-modeling-handbook.md) for materials, tool abstractions, skill structure, prompt examples and tuning. The walkthrough's decisions are scripted; no live-model reconstruction score is claimed.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// Transport-neutral adapter: keep full receipts on disk and send a focused result
|
|
2
|
+
// to the model. Host adapters still decide how to attach a PNG and flag errors.
|
|
3
|
+
import {join} from 'node:path';
|
|
4
|
+
import {createSessionTools} from '../../src/session.mjs';
|
|
5
|
+
export function compactReceipt(receipt){
|
|
6
|
+
if(!receipt.ok||!Array.isArray(receipt.data?.features))return structuredClone(receipt);
|
|
7
|
+
const d=receipt.data,features=d.features;
|
|
8
|
+
const artifacts=Object.fromEntries(Object.entries(d.artifact_sha256??{})
|
|
9
|
+
.filter(([name])=>/^(model|preview)\.(json|step|png|mesh\.json|glb|stl)$/.test(name))
|
|
10
|
+
.map(([name,sha256])=>[name,{path:join(d.artifact_directory,name),sha256}]));
|
|
11
|
+
return {ok:true,...(receipt.session_step?{session_step:receipt.session_step}:{}),data:{
|
|
12
|
+
artifact_directory:d.artifact_directory,source_artifact_directory:d.source_artifact_directory,
|
|
13
|
+
model_hash:d.model_hash,source_hash:d.source_hash,geometry:structuredClone(d.geometry),
|
|
14
|
+
timing_ms:structuredClone(d.timing_ms),validation:structuredClone(d.validation),artifacts,
|
|
15
|
+
feature_summary:{count:features.length,reused:features.filter(f=>f.cache_hit).length,
|
|
16
|
+
slowest:[...features].sort((a,b)=>(b.elapsed_ms??0)-(a.elapsed_ms??0)).slice(0,3).map(f=>({id:f.id,elapsed_ms:f.elapsed_ms,cache_hit:f.cache_hit})),
|
|
17
|
+
degradations:features.filter(f=>f.degradation).map(f=>({id:f.id,...structuredClone(f.degradation)}))},
|
|
18
|
+
}};
|
|
19
|
+
}
|
|
20
|
+
export async function createCompactSessionTools(session,{include=['cad_capabilities','cad_validate','cad_build','cad_preview','cad_edit']}={}){
|
|
21
|
+
const tools=await createSessionTools(session),enabled=new Set(include);
|
|
22
|
+
for(const name of enabled)if(!tools.some(t=>t.name===name))throw Error('Unknown CAD tool: '+name);
|
|
23
|
+
return tools.filter(t=>enabled.has(t.name)).map(tool=>({...tool,
|
|
24
|
+
description:tool.description+' Results summarize measurements and timing; full receipts remain in the recorded session. Report every listed degradation.',
|
|
25
|
+
async execute(args){const result=compactReceipt(await tool.execute(args));if(result.session_step)result.receipt_file=join(session.root,'steps',result.session_step,'receipt.json');return result;},
|
|
26
|
+
}));
|
|
27
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
// Executable tool-contract walkthrough; the decision sequence is scripted, not LLM inference.
|
|
2
|
+
import {readFile,writeFile} from 'node:fs/promises';
|
|
3
|
+
import {join,resolve} from 'node:path';
|
|
4
|
+
import {fileURLToPath,pathToFileURL} from 'node:url';
|
|
5
|
+
import {execFile} from 'node:child_process';
|
|
6
|
+
import {promisify} from 'node:util';
|
|
7
|
+
import {ModelingSession} from '../../src/session.mjs';
|
|
8
|
+
import {createCompactSessionTools} from './compact-tools.mjs';
|
|
9
|
+
const exec=promisify(execFile);
|
|
10
|
+
export async function runGuidedWorkflow(directory){
|
|
11
|
+
const root=resolve(directory),session=await ModelingSession.create(join(root,'session'),{title:'Guided workflow: build, check, edit, recover, inspect'});
|
|
12
|
+
const tools=await createCompactSessionTools(session);const calls=[];
|
|
13
|
+
const call=async(name,args)=>{const result=await tools.find(t=>t.name===name).execute(args);calls.push({tool:name,result});return result;};
|
|
14
|
+
const model=JSON.parse(await readFile(new URL('../../skills/colocad/assets/plate-grid.json',import.meta.url)));
|
|
15
|
+
const caps=await call('cad_capabilities',{});if(!caps.ok||!caps.data.operations.includes('face_hole_grid'))throw Error('Required operation unavailable');
|
|
16
|
+
const validation=await call('cad_validate',{model});if(!validation.ok)throw Error(JSON.stringify(validation.error));
|
|
17
|
+
const first=await call('cad_build',{model});if(!first.ok)throw Error(JSON.stringify(first.error));
|
|
18
|
+
const bored=await call('cad_edit',{parameters:{holeDiameter:8}});if(!bored.ok)throw Error(JSON.stringify(bored.error));
|
|
19
|
+
// Quantitative feedback comes from the analytic feature intent, not just the renderer.
|
|
20
|
+
const expectedRemoved=4*Math.PI*(4**2-3**2)*6;
|
|
21
|
+
if(Math.abs(first.data.geometry.volume_mm3-bored.data.geometry.volume_mm3-expectedRemoved)>.01)throw Error('Hole-size edit failed volume check');
|
|
22
|
+
const invalid=await call('cad_edit',{parameters:{nonexistent:1}});if(invalid.ok||invalid.error.code!=='UNKNOWN_PARAMETER')throw Error('Expected visible failed edit');
|
|
23
|
+
const accepted=await session.source();if(accepted.parameters.holeDiameter!==8)throw Error('Failure replaced accepted source');
|
|
24
|
+
const preview=await call('cad_preview',{model:accepted,options:{view:'top'}});if(!preview.ok)throw Error(JSON.stringify(preview.error));
|
|
25
|
+
const longer=await call('cad_edit',{parameters:{length:100}});if(!longer.ok)throw Error(JSON.stringify(longer.error));
|
|
26
|
+
const [lo,hi]=longer.data.geometry.bbox_mm;if(Math.abs(hi[0]-lo[0]-100)>1e-6)throw Error('Length edit did not update the envelope');
|
|
27
|
+
const html=join(root,'review.html');await exec(process.execPath,[fileURLToPath(new URL('../../bin/colocad.mjs',import.meta.url)),'replay',session.root,html]);
|
|
28
|
+
const result={scope:'Scripted tool-contract workflow, not a live model evaluation',passed:true,html,steps:(await session.read()).steps.length,calls,measurements:{holeEditRemovedMm3:expectedRemoved,finalLengthMm:hi[0]-lo[0]}};
|
|
29
|
+
await writeFile(join(root,'workflow.json'),JSON.stringify(result,null,2)+'\n');return result;
|
|
30
|
+
}
|
|
31
|
+
if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){const r=await runGuidedWorkflow(process.argv[2]??'./out/guided-workflow');console.log(JSON.stringify({passed:r.passed,scope:r.scope,steps:r.steps,html:r.html,measurements:r.measurements}));}
|
package/kernel/release.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@coloopx/colocad",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.5",
|
|
4
4
|
"description": "Parametric feature instructions, a local Rust B-rep kernel and an experimental SolidWorks author",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -63,7 +63,10 @@
|
|
|
63
63
|
"examples/hiwin-kk60/run.mjs",
|
|
64
64
|
"examples/hiwin-kk60/README.md",
|
|
65
65
|
"examples/hiwin-kk60/sources.json",
|
|
66
|
-
"
|
|
66
|
+
"examples/integrations/compact-tools.mjs",
|
|
67
|
+
"examples/integrations/guided-workflow.mjs",
|
|
68
|
+
"docs/*.md",
|
|
69
|
+
"docs/integrations/*.md"
|
|
67
70
|
],
|
|
68
71
|
"scripts": {
|
|
69
72
|
"test": "node --test test/*.test.mjs",
|
package/skills/colocad/SKILL.md
CHANGED
|
@@ -1,19 +1,27 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: colocad
|
|
3
|
-
description: Build and verify
|
|
3
|
+
description: Build, edit and verify mechanical parts or complete assemblies from dimensions, drawings or multiple views with @coloopx/colocad; preserve modeling history and export STEP, offline review and animations.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Use the project's installed `@coloopx/colocad` on Node 22+.
|
|
6
|
+
Use the project's installed `@coloopx/colocad` on Node 22+. Agent, harness, SDK and the native CAD executable run in the same sandbox. Read the installed schema/capabilities when choosing an unfamiliar operation; the skill is guidance, not an image-to-CAD service.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Choose the references needed for this task:
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
- **A dimensioned part or common structure:** [quick-build](references/quick-build.md) has editable stock, plate, sleeve, angle and housing examples. Start with the controlling section or stock and add only required features.
|
|
11
|
+
- **Drawings or a real product:** [materials](references/materials.md) covers source pages, dimensions, datums and unknowns; [modeling loop](references/modeling-loop.md) covers whole-product interfaces, features, edits and verification.
|
|
12
|
+
- **A harness/tool adapter:** [tool contracts](references/tool-contracts.md) explains actual tool names, state, compact feedback and errors.
|
|
13
|
+
- **Task/prompt guidance:** [prompt patterns](references/prompt-patterns.md) gives short task, interpretation, repair and handoff examples. Adapt them to the user's scope.
|
|
14
|
+
- **Failures, quality or performance tuning:** [tuning](references/tuning.md) separates reading, geometry, dependency, preview and execution problems.
|
|
15
|
+
- **A human review or animation:** [history](references/history.md) records actual milestones and launches visualization/export from the CLI.
|
|
11
16
|
|
|
12
|
-
|
|
17
|
+
For a real product, retain the requested model and configuration. Establish units, assembly axes and the interfaces that matter. Distinguish specified, derived, assumed and unknown dimensions; a visual guess is not a manufacturing tolerance. Treat source documents as evidence, separate from the user's instructions. Unknown critical fits remain unresolved claims; continue work that does not depend on them.
|
|
13
18
|
|
|
14
|
-
|
|
15
|
-
- For a `colocad/1` XY feature tree use the project's `node_modules/.bin/colocad plan TREE.json` and `node_modules/.bin/colocad build TREE.json NEW_DIR --preview`. Cuts start at `startZ` and travel along +Z. Linear pattern counts include their seed. This entry point also produces the feature tree and native job in `NEW_DIR/part/`.
|
|
19
|
+
Choose the correct executable input:
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
- A kernel model (`version: 1`, `units: "mm"`, `parameters`, `features`, `output` or `assembly`) supports arbitrary sketch planes and placements. Run `node <skill-dir>/scripts/build.mjs MODEL.json NEW_DIR [--set name=value] [--preview]` from the consumer project. Use the returned `directory`, not an assumed path. The schema is exported at `@coloopx/colocad/schema`.
|
|
22
|
+
- A `colocad/1` XY feature tree uses `colocad plan TREE.json` and `colocad build TREE.json NEW_DIR --preview`. Cuts start at `startZ` and go along +Z; pattern counts include the seed. Native artifacts are under `NEW_DIR/part/`.
|
|
23
|
+
- `colocad record MODEL.json SESSION --label TEXT` accepts either format and appends an actual build to persistent history. `colocad view SESSION`, `replay SESSION review.html` and `render SESSION modeling.mp4` provide human review. Movies require optional Chromium/FFmpeg.
|
|
18
24
|
|
|
19
|
-
|
|
25
|
+
Build a meaningful feature or interface milestone, inspect its receipt and the relevant projection, then accept or repair it. Stable semantic IDs and parameter relationships should survive edits. Reuse definitions for repeated parts. `cad_validate` is preflight, not proof of geometry or dimensional correctness. On failure, use the feature ID and a quantitative check to make a targeted change; retain the failed attempt. Explicit degradations remain part of the result.
|
|
26
|
+
|
|
27
|
+
Deliver editable source and exact STEP with the requested review artifacts. Check the dimensions/holes/clearances that distinguish success, and independently reopen significant STEP deliveries when a verifier is available. Say which checks ran. Rendering establishes appearance; fit, motion, editability and manufacturing claims require their own evidence.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
{
|
|
2
|
+
"purpose": "Evidence handoff example; this is not executable kernel model JSON",
|
|
3
|
+
"product": {"manufacturer":"HIWIN","series":"KK60 standard","configuration":"5 mm lead / 300 mm rail / one A block / open / no motor or switches"},
|
|
4
|
+
"units":"mm",
|
|
5
|
+
"frame":{"x":"width","y":"vertical","z":"travel","overallZ":[0,370]},
|
|
6
|
+
"sources":[{"id":"hiwin-catalog","url":"https://hiwin.com/wp-content/uploads/2026/08/HIWIN-Ballscrew-Driven-Stages-Catalog-1.pdf","revision":"K99TE16-1906","pdfPage":25,"printedPage":22,"views":["SECTION A-A","VIEW B","top","side"]}],
|
|
7
|
+
"dimensions":[
|
|
8
|
+
{"id":"railLength","value":300,"state":"specified","source":"hiwin-catalog","locator":"length table, 300 mm row"},
|
|
9
|
+
{"id":"screwAxisHeight","value":23,"state":"specified","source":"hiwin-catalog","locator":"SECTION A-A"},
|
|
10
|
+
{"id":"carriageHeight","value":33,"state":"specified","source":"hiwin-catalog","locator":"SECTION A-A"},
|
|
11
|
+
{"id":"stroke","value":210,"state":"specified","source":"hiwin-catalog","locator":"length table, A1 column"},
|
|
12
|
+
{"id":"midStrokeZ","value":157,"state":"derived","relation":"rail origin 7 + railLength / 2"},
|
|
13
|
+
{"id":"guideBallRadius","value":1.5,"state":"assumed","reason":"Catalog does not dimension rolling elements; reconstruction only"},
|
|
14
|
+
{"id":"nutRecirculationPath","value":null,"state":"unknown","affects":["OEM internal geometry","functional ball circulation"]}
|
|
15
|
+
],
|
|
16
|
+
"interfaces":[{"id":"carriage-to-rail","datums":["travel axis Z","rail bottom Y=0"],"checks":["carriage height 33","rail/carriage overlap at travel -105,0,105"]}],
|
|
17
|
+
"acceptance":[{"quantity":"screwAxisHeight","expected":23,"numericCheckTolerance":0.01,"note":"Reconstruction check threshold, not a manufacturer tolerance"}],
|
|
18
|
+
"delivery":["editable model","whole-product STEP","recorded session","CLI-exported offline HTML","requested animation"],
|
|
19
|
+
"claimScope":"Catalog interfaces and documented reconstruction; no manufacturing or recirculation certification"
|
|
20
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Prepare evidence for a mechanical model
|
|
2
|
+
|
|
3
|
+
Use for a drawing-based part or a specific product. A small dimensioned stock part does not need a large evidence bundle.
|
|
4
|
+
|
|
5
|
+
## Identify the target and the source
|
|
6
|
+
|
|
7
|
+
Record the manufacturer/model, variant, optional equipment, units and requested fidelity. An entire actuator is the target; its drawings and BOM describe that target. Do not silently replace it with a generic assembly or a simpler test piece.
|
|
8
|
+
|
|
9
|
+
Keep an original source URL/file, revision/date, PDF page and checksum when reproducibility matters. Preserve the full page as context, then provide readable detail crops with the view name and crop location. Text extraction helps find dimensions; the rendered page establishes which extension lines, section or component a number belongs to. Do not crop away the datum or section identifier needed to interpret it.
|
|
10
|
+
|
|
11
|
+
A useful source order is: explicit drawing dimensions and notes, tables for the exact variant, dimensioned sections, then calibrated geometry measurements. A photograph or uncalibrated render supports shape interpretation, not exact dimensions. More views can resolve correspondence but cannot expose every hidden passage or tolerance.
|
|
12
|
+
|
|
13
|
+
For a PDF, existing Poppler tools can prepare the evidence:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pdftotext -layout catalog.pdf catalog.txt
|
|
17
|
+
pdftoppm -f 25 -singlefile -scale-to 2400 -png catalog.pdf page-25
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
These are material-preparation tools, not requirements of the CAD runtime. Do not add Python/PDF tooling to the modeling sandbox unless the task needs it.
|
|
21
|
+
|
|
22
|
+
## Separate evidence states
|
|
23
|
+
|
|
24
|
+
| State | Record | Example |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| Specified | Value, unit, source/page/view/annotation | KK60 screw axis height 23 mm, SECTION A-A |
|
|
27
|
+
| Derived | Formula and referenced dimensions | Hole stations from rail end and G/pitch |
|
|
28
|
+
| Assumed | Value/range, reason and affected claims | Unpublished bearing race dimensions |
|
|
29
|
+
| Unknown | Missing quantity and what it prevents checking | Proprietary ball-recirculation path |
|
|
30
|
+
|
|
31
|
+
Write one shared coordinate convention and the local frame of each part. Name which view corresponds to +/−X, Y or Z; orthographic, perspective and section views are different evidence. Check diameter vs radius, through vs blind, depth origin, units, and normal vs special-order blocks before generating cutters.
|
|
32
|
+
|
|
33
|
+
Keep manufacturing tolerance and reconstruction acceptance tolerance separate. A 0.01 mm numerical check chosen for your model is not a 0.01 mm manufacturer tolerance. For image-derived dimensions, record calibration and uncertainty. If uncertainty prevents a required interface from being checked, request that specific missing fact while continuing independent parts.
|
|
34
|
+
|
|
35
|
+
## Minimal handoff to the modeling stage
|
|
36
|
+
|
|
37
|
+
Provide the selected source pages/crops, dimension table, coordinate frame, interface list, assumptions and acceptance checks. [The product brief](../assets/product-brief.example.json) is a filled example of this evidence convention, not a new executable kernel schema. Do not put its provenance fields into a kernel model with `additionalProperties: false`.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Whole-product modeling loop
|
|
2
|
+
|
|
3
|
+
Read for assemblies, drawing reconstruction or edits whose dependencies matter.
|
|
4
|
+
|
|
5
|
+
## From product evidence to an executable model
|
|
6
|
+
|
|
7
|
+
1. Establish the assembly envelope, primary axes and interface datums. Identify unique part definitions and repeated occurrences. Attach an acceptance check to the interfaces that matter to the request.
|
|
8
|
+
2. Select the controlling cross-section or stock for each unique part. Use extrude/revolve for prismatic/turned structure; cut real bores and cavities; use loft/sweep when geometry requires it. A rotated or copied solid is an assembly occurrence, not a new manufactured part definition.
|
|
9
|
+
3. Preserve relationships in parameters/expressions. Examples: a centered hole pattern follows width edits; the nut's translation and screw rotation share the lead relation. Assign meaningful, stable feature/part IDs. Do not rely on an incidental edge number surviving a Boolean or parameter edit.
|
|
10
|
+
4. Validate the JSON and declared budgets, then build a meaningful milestone. Read `ok`, geometry, timings and degradations; inspect a projection or section aimed at the changed feature. A small subassembly can resolve an interface before an expensive complete build.
|
|
11
|
+
5. Compare a quantitative result with the target. Correct the interpretation, feature or parameter that caused the error. Preserve the last accepted model and the failed attempt; changing unrelated dimensions obscures the cause.
|
|
12
|
+
6. Assemble and check the whole selected configuration. Reopen STEP independently for significant delivery. Test at least the edits or poses required by the request, keeping paired interfaces consistent. Persist the session and launch `view/replay/render` from the CLI for human review.
|
|
13
|
+
|
|
14
|
+
This is an adaptive loop, not a mandatory approval gate between every feature. Use fewer milestones for a simple part. For a long product, keep checkpoints that explain both shape construction and assembly.
|
|
15
|
+
|
|
16
|
+
## Match evidence to the claim
|
|
17
|
+
|
|
18
|
+
| Claim | A useful check |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| Outer size | Exact STEP/B-rep bounding dimensions against the drawing |
|
|
21
|
+
| Hole/cavity | Axis, radius/depth and material probes inside/outside; a rendered circle is insufficient |
|
|
22
|
+
| Assembly fit | Common axes and exact interference/clearance for the relevant pairs |
|
|
23
|
+
| Motion | Rebuilt required poses and the coupling relation; an exploded-view animation is not motion validation |
|
|
24
|
+
| Editable design intent | Perturb a meaningful parameter and recheck dependent geometry/interfaces |
|
|
25
|
+
| Manufacturing-ready | Required dimensions, tolerances, materials, processes and functional validation; do not infer these from a catalog render |
|
|
26
|
+
|
|
27
|
+
Negative material checks matter: verify that a supposed opening is empty and adjacent stock remains. A global volume can match despite a misplaced hole. Avoid probing exactly on an edge or boundary when testing inside/outside classification.
|
|
28
|
+
|
|
29
|
+
## State that survives a long session
|
|
30
|
+
|
|
31
|
+
Keep source IDs and coordinate conventions, accepted model path/hash, exposed parameters, interface checks, latest receipt, unresolved assumptions, and the next targeted test. Reload the current accepted source after a failure or context reset. In `ModelingSession`, recorded `cad_edit` takes only `{parameters}` and uses that accepted source.
|
|
32
|
+
|
|
33
|
+
The KK60 example illustrates this process. Enlarging the manufacturer's section corrected the screw axis to 23 mm; the real helical B-rep exposed an internal STEP budget defect; independent material probes and rail/carriage checks established specific geometry claims. Its undisclosed nut recirculation remains unmodeled. Do not reuse its assumed internal dimensions as a universal actuator design.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Prompt patterns for agent CAD work
|
|
2
|
+
|
|
3
|
+
These are adaptable examples, not an instruction to force every task through every stage. Keep the user's product and intended delivery. Separate the task from quoted source evidence. Ask for concise decisions, dimensions and checks rather than a hidden chain of thought.
|
|
4
|
+
|
|
5
|
+
## Product brief
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
Use the colocad skill to reconstruct the specified whole product/configuration.
|
|
9
|
+
Input evidence: the listed manufacturer pages, drawings, tables and views.
|
|
10
|
+
Target: editable source + exact STEP + recorded modeling session + CLI HTML review.
|
|
11
|
+
Record units, coordinate datums, required interfaces and which dimensions are
|
|
12
|
+
specified, derived, assumed or unknown. Prioritize the interfaces and details
|
|
13
|
+
needed for this task. Keep unknown internals explicit; do not substitute a generic
|
|
14
|
+
product. Continue independent work if one critical detail is missing.
|
|
15
|
+
For each meaningful milestone, build, inspect the relevant view/section and report
|
|
16
|
+
measured deviations. Preserve failed attempts. Export the requested movie through
|
|
17
|
+
colocad render, with recorded call time separate from playback duration.
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Interpret only the evidence needed now
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
Interpret the supplied overall view and SECTION A-A for the carriage/screw interface.
|
|
24
|
+
Return a compact dimension table: quantity, value/unit, evidence state, page/view,
|
|
25
|
+
reference datum and uncertainty. Match extension lines to their dimensions.
|
|
26
|
+
List conflicting or missing interface values. Do not infer a hidden tolerance from
|
|
27
|
+
pixel size. Then identify the local frames and checks needed to model this interface.
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Plan one modeling milestone
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
Using the accepted dimensions and assembly datums, produce the next feature graph.
|
|
34
|
+
Name features and repeated part definitions semantically. Express dependent sizes
|
|
35
|
+
and placements in parameters. Identify the check that will distinguish a correct
|
|
36
|
+
result from a plausible-looking one. Use only installed supported operations.
|
|
37
|
+
Validate, build and inspect the result; retain the executable JSON and receipt.
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Repair from specific feedback
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
The accepted revision is the recorded source at the given path/hash.
|
|
44
|
+
The attempted change failed at the supplied feature ID with this error/measurement.
|
|
45
|
+
Inspect that feature, its operands and local frame. Make a targeted correction;
|
|
46
|
+
keep required geometry and dimensional intent. Re-run the affected check before
|
|
47
|
+
accepting. If an optional treatment is explicitly omitted, retain its degradation
|
|
48
|
+
record and say which claim is weakened.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Check editability or product fit
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
Test the requested dimension change/pose in the actual CAD model. Recheck the
|
|
55
|
+
specified dependent interfaces, hole placement and envelope. Report numerical
|
|
56
|
+
results and the source of each target. Render comparison views, then independently
|
|
57
|
+
read back STEP when available. Distinguish untested pairs and unknown internals
|
|
58
|
+
from passed checks; do not use appearance alone as evidence of fit.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Handoff after a long run
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
Persist: product/configuration; source identifiers; units and datums; accepted
|
|
65
|
+
model path/hash; session path/latest step; parameters and dependency decisions;
|
|
66
|
+
passed checks with values; failed attempts; unresolved assumptions; next targeted
|
|
67
|
+
check. Keep large meshes and receipts as file references rather than inline text.
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
For performance requests, additionally specify the same input/geometry, output requirements, cold or warm start, preview precision, hardware/container limits and measurement window. Never reuse a construction movie's edited duration as a benchmark.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Tool contracts for a local CAD harness
|
|
2
|
+
|
|
3
|
+
The existing harness owns inference, permissions, output locations and artifact retention. Bind SDK functions to that harness; do not introduce a CAD service or remote scheduling layer for this package. The agent supplies geometry inputs, not arbitrary executable paths or process flags.
|
|
4
|
+
|
|
5
|
+
## Expose tools at the useful level
|
|
6
|
+
|
|
7
|
+
Start with the five tools used by the executable Pi adapter; enable sketch solving or STEP inspection when that workflow needs them. Keep the SDK's schema and `$defs` intact instead of rewriting an approximate subset.
|
|
8
|
+
|
|
9
|
+
| Existing tool | Meaning | Important boundary |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `cad_capabilities` | Read operations, limits and unsupported cases | Installed version is authoritative |
|
|
12
|
+
| `cad_validate` | Check input/parameters/dependencies/budgets | Does not build or validate the resulting shape |
|
|
13
|
+
| `cad_build` | Execute an explicit model and return exact artifacts | Creates a new revision; inspect errors/degradations |
|
|
14
|
+
| `cad_preview` | Produce a view, reusing eligible saved mesh | Geometry, pose or precision changes can require work |
|
|
15
|
+
| `cad_edit` | Rebuild changed named parameters | Plain tools take `{model,parameters}`; recorded tools take `{parameters}` |
|
|
16
|
+
| `cad_solve_sketch` | Local sketch constraints/residuals/DOF | Local solution/rank is not proof of global uniqueness |
|
|
17
|
+
| `cad_inspect_step` | Inspect a registered STEP asset and its instances | Import budgets and supported representations apply |
|
|
18
|
+
|
|
19
|
+
The current API does not provide `image_to_cad`, an automatic drawing-dimension extractor, or a universal exact measurement tool in this tool set. Use the harness's file/image tools for evidence and an appropriate independent geometry verifier for checks. The SDK's `inspect` reads a report; it is not an arbitrary geometric query engine.
|
|
20
|
+
|
|
21
|
+
## Keep feedback focused and inspectable
|
|
22
|
+
|
|
23
|
+
A useful response includes `ok`, the failing feature/code/message, revision and artifact paths/hashes, solid count, bounds/volume, relevant measurements, timings, cache reuse and every degradation. Keep full feature traces and source files on disk. Return relevant details or a PNG when they change the next decision; do not send STEP text, complete meshes or every intermediate image back to the model.
|
|
24
|
+
|
|
25
|
+
The repository's `examples/integrations/compact-tools.mjs` wraps `createSessionTools` without changing tool schemas or error meaning. It retains full receipts, returns a compact feature summary and points to the original receipt. `guided-workflow.mjs` exercises real builds, dimension edits, an invalid edit, recovery, cached observation and CLI HTML export. The sequence is scripted; it is not an LLM success-rate evaluation.
|
|
26
|
+
|
|
27
|
+
For a provider that expects an error flag or thrown error, map `ok:false` into that provider's tool-error convention. Preserve the structured detail so the agent can repair the exact cause. A successful transport call is not automatically a successful CAD operation. An `on_fail:record` result still contains omissions and cannot satisfy a required omitted feature.
|
|
28
|
+
|
|
29
|
+
## Reuse and persistence
|
|
30
|
+
|
|
31
|
+
Use one client/session for sequential revisions of one modeling task. Separate independent tasks' output roots. A session stores accepted inputs and failed attempts; archive its directory before the sandbox expires. `preview` can reuse a checked mesh; observation-only artifacts may point to `source_artifact_directory` for the exact STEP. Avoid overlapping writes to one session.
|
|
32
|
+
|
|
33
|
+
Prefer a small semantic set of SDK tools over an RPC endpoint per primitive. Repeated geometry can be generated in a program/feature graph and sent in a meaningful build. Keep enough milestones to inspect geometry creation, not just the final assembly.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Diagnose and tune the actual failure
|
|
2
|
+
|
|
3
|
+
Change one cause at a time and retain the original acceptance target. These are starting heuristics to evaluate on your workload, not a proven universal optimum.
|
|
4
|
+
|
|
5
|
+
| Symptom | Check first | Useful change / proof |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| Looks plausible, dimensions wrong | Source annotation, scale, radius/diameter, frame | Reinspect crop; update dimension evidence; measure the interface |
|
|
8
|
+
| Wrong hidden geometry | Missing section/reference | Mark uncertainty; obtain a source or constrain the claim instead of inventing precision |
|
|
9
|
+
| A dimension edit breaks mating | Constants duplicated across parts, unstable references | Link parameter expressions/datums; rebuild an edit stress case |
|
|
10
|
+
| Boolean/fillet fails | Feature ID, operand overlap, tangent/degenerate regions, selector count | Reduce to a small reproducer; fix geometry/selection; keep required detail |
|
|
11
|
+
| Native success but omitted detail | `degradation` records | Restore required feature or report explicitly allowed omission |
|
|
12
|
+
| Large context and tool confusion | Redundant tools, full schema/traces/images every turn | Load the needed reference/operation; return compact receipts and targeted views |
|
|
13
|
+
| Slow repeated observation | Whether geometry actually changed | Reuse persisted meshes for camera-only changes; measure cache hits |
|
|
14
|
+
| Slow complete rebuild | Per-feature and validation/export timing | Reuse one client/checkpoints and instance definitions; optimize the measured bottleneck |
|
|
15
|
+
| Memory grows with repeated parts | Duplicated geometry/meshes, unnecessary copies | Shared definitions and bounded previews; sample the whole relevant cgroup/process set |
|
|
16
|
+
| Movie clips the product | Perspective framing, aspect ratio, section plane | Orthographic bounds-based fit; inspect all cameras; do not alter exact geometry to fix framing |
|
|
17
|
+
|
|
18
|
+
## Measure separate stages
|
|
19
|
+
|
|
20
|
+
Keep source interpretation/inference, CAD startup, geometry, validation, STEP export, tessellation, view rendering and video encoding separate. Time-to-STEP and time-to-preview answer different questions. A cached view cannot be compared with another tool's fresh geometry build as if they were the same task.
|
|
21
|
+
|
|
22
|
+
For a fair build123d comparison, use the same dimensions, features, instances, precision and required artifacts. Verify both geometries independently, pin environments and define cold/warm behavior. Report repeat counts, median/tails, failures and the accounting boundary. For memory, state sampled RSS/process sum/cgroup, sampling interval and whether the plot is instantaneous or the peak-so-far; retaining a peak is a presentation choice, not the original trace.
|
|
23
|
+
|
|
24
|
+
A 1 vCPU / 512 MiB CAD run establishes only that scoped run. It does not establish the memory budget of the resident agent/harness, an in-process LLM, Chromium or FFmpeg. Do not extrapolate a plate's speedup to a threaded multi-part product.
|
|
25
|
+
|
|
26
|
+
## Evaluate the skill/prompt, not just the executor
|
|
27
|
+
|
|
28
|
+
Hold product tasks, source packs, model/provider version, tools and budget fixed. Compare the existing skill with one changed instruction/tool response policy. Include a dimensioned part, a part needing section interpretation, an editable assembly and an ambiguous source case. Keep some tasks unseen during tuning. Measure required dimensions/features, edit preservation, fit checks, unsupported claims, correction count, inference cost and end-to-end duration.
|
|
29
|
+
|
|
30
|
+
Use numerical checks and inspectable artifacts for acceptance. Scripted tool tests establish transport and geometry contracts; they do not establish that a model understood an unseen drawing. Report failed tasks and unknown evidence, and do not describe an unrun prompt ablation as an improvement result.
|