@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.
Files changed (34) hide show
  1. package/README.md +133 -99
  2. package/README.zh-CN.md +145 -79
  3. package/docs/README.md +7 -4
  4. package/docs/README.zh-CN.md +9 -3
  5. package/docs/agent-modeling-handbook.md +68 -0
  6. package/docs/agent-modeling-handbook.zh-CN.md +222 -0
  7. package/docs/agent-modeling-research.md +22 -0
  8. package/docs/api.md +95 -0
  9. package/docs/best-practices.md +45 -0
  10. package/docs/concepts.md +37 -0
  11. package/docs/getting-started.md +53 -0
  12. package/docs/integrations/claude-code.md +52 -0
  13. package/docs/integrations/codex.md +55 -0
  14. package/docs/integrations/overview.md +53 -0
  15. package/docs/integrations/pi.md +73 -0
  16. package/docs/integrations/verification.md +30 -0
  17. package/docs/modeling-workflow.zh-CN.md +77 -0
  18. package/docs/native-solidworks.md +12 -0
  19. package/docs/performance.md +62 -0
  20. package/docs/troubleshooting.md +25 -0
  21. package/docs/validation.md +23 -0
  22. package/examples/hiwin-kk60/README.md +1 -1
  23. package/examples/integrations/README.md +47 -0
  24. package/examples/integrations/compact-tools.mjs +27 -0
  25. package/examples/integrations/guided-workflow.mjs +31 -0
  26. package/kernel/release.json +1 -1
  27. package/package.json +5 -2
  28. package/skills/colocad/SKILL.md +17 -9
  29. package/skills/colocad/assets/product-brief.example.json +20 -0
  30. package/skills/colocad/references/materials.md +37 -0
  31. package/skills/colocad/references/modeling-loop.md +33 -0
  32. package/skills/colocad/references/prompt-patterns.md +70 -0
  33. package/skills/colocad/references/tool-contracts.md +33 -0
  34. package/skills/colocad/references/tuning.md +30 -0
@@ -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.