@coloopx/colocad 0.1.0-alpha.5 → 0.1.0-alpha.7
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/CHANGELOG.md +44 -0
- package/README.md +115 -172
- package/README.zh-CN.md +118 -125
- package/bin/colocad.mjs +17 -9
- package/docs/README.md +10 -3
- package/docs/README.zh-CN.md +11 -2
- package/docs/agent-modeling-handbook.md +1 -1
- package/docs/agent-modeling-handbook.zh-CN.md +2 -2
- package/docs/api.md +9 -6
- package/docs/engineering-queries.md +122 -0
- package/docs/engineering-queries.zh-CN.md +74 -0
- package/docs/getting-started.md +1 -1
- package/docs/integrations/claude-code.md +1 -1
- package/docs/integrations/codex.md +1 -1
- package/docs/integrations/pi.md +17 -4
- package/docs/integrations/verification.md +7 -1
- package/docs/native-solidworks.md +12 -0
- package/docs/performance.md +62 -0
- package/examples/integrations/README.md +11 -2
- package/examples/integrations/compact-tools.mjs +1 -1
- package/kernel/dist/client.d.ts +5 -2
- package/kernel/dist/client.js +35 -7
- package/kernel/dist/generated.d.ts +297 -4
- package/kernel/dist/process.d.ts +1 -1
- package/kernel/dist/process.js +3 -3
- package/kernel/dist/query-generated.d.ts +181 -0
- package/kernel/dist/query-generated.js +1 -0
- package/kernel/dist/tools.d.ts +35 -0
- package/kernel/dist/tools.js +11 -2
- package/kernel/dist/types.d.ts +9 -0
- package/kernel/native/darwin-arm64/agent-cad +2 -2
- package/kernel/native/darwin-arm64/manifest.json +2 -2
- package/kernel/native/linux-arm64/agent-cad +2 -2
- package/kernel/native/linux-arm64/manifest.json +2 -2
- package/kernel/native/linux-x64/agent-cad +2 -2
- package/kernel/native/linux-x64/manifest.json +2 -2
- package/kernel/release.json +4 -4
- package/kernel/schemas/model.schema.json +1752 -135
- package/kernel/schemas/query.schema.json +1150 -0
- package/package.json +5 -2
- package/skills/colocad/references/tool-contracts.md +14 -2
- package/src/build.mjs +3 -2
- package/src/index.d.mts +2 -1
- package/src/session.d.mts +5 -3
- package/src/session.mjs +26 -10
- package/viewer/dist/index.js +179 -179
- package/viewer/dist/standalone.js +179 -179
- package/viewer/index.d.ts +2 -1
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.7",
|
|
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",
|
|
@@ -66,9 +66,12 @@
|
|
|
66
66
|
"examples/integrations/compact-tools.mjs",
|
|
67
67
|
"examples/integrations/guided-workflow.mjs",
|
|
68
68
|
"docs/*.md",
|
|
69
|
-
"docs/integrations/*.md"
|
|
69
|
+
"docs/integrations/*.md",
|
|
70
|
+
"CHANGELOG.md"
|
|
70
71
|
],
|
|
71
72
|
"scripts": {
|
|
73
|
+
"schema": "node scripts/schema.mjs",
|
|
74
|
+
"schema:check": "node scripts/schema.mjs --check",
|
|
72
75
|
"test": "node --test test/*.test.mjs",
|
|
73
76
|
"build:kernel": "node scripts/build-kernel.mjs",
|
|
74
77
|
"prepack": "node scripts/check-release.mjs",
|
|
@@ -4,7 +4,7 @@ The existing harness owns inference, permissions, output locations and artifact
|
|
|
4
4
|
|
|
5
5
|
## Expose tools at the useful level
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The executable Pi adapter exposes five core tools and capability-gates `cad_query` as a sixth. 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
8
|
|
|
9
9
|
| Existing tool | Meaning | Important boundary |
|
|
10
10
|
| --- | --- | --- |
|
|
@@ -13,10 +13,11 @@ Start with the five tools used by the executable Pi adapter; enable sketch solvi
|
|
|
13
13
|
| `cad_build` | Execute an explicit model and return exact artifacts | Creates a new revision; inspect errors/degradations |
|
|
14
14
|
| `cad_preview` | Produce a view, reusing eligible saved mesh | Geometry, pose or precision changes can require work |
|
|
15
15
|
| `cad_edit` | Rebuild changed named parameters | Plain tools take `{model,parameters}`; recorded tools take `{parameters}` |
|
|
16
|
+
| `cad_query` | Observe an accepted exact snapshot: topology, datums, holes/groups/interfaces and explicit part-pair measurements | Requires the latest `query_revision_id`; preserve partial coverage and ambiguity |
|
|
16
17
|
| `cad_solve_sketch` | Local sketch constraints/residuals/DOF | Local solution/rank is not proof of global uniqueness |
|
|
17
18
|
| `cad_inspect_step` | Inspect a registered STEP asset and its instances | Import budgets and supported representations apply |
|
|
18
19
|
|
|
19
|
-
The current API does not provide `image_to_cad`, an automatic drawing-dimension extractor, or
|
|
20
|
+
The current API does not provide `image_to_cad`, an automatic drawing-dimension extractor, or universal geometry recognition. Use the harness's file/image tools for evidence and an appropriate independent geometry verifier for checks. The SDK's `inspect` reads a report; `query` is the capability-gated exact-geometry API. It ships in alpha.7; alpha.6 predates it. Inspect installed capabilities before selecting tools.
|
|
20
21
|
|
|
21
22
|
## Keep feedback focused and inspectable
|
|
22
23
|
|
|
@@ -31,3 +32,14 @@ For a provider that expects an error flag or thrown error, map `ok:false` into t
|
|
|
31
32
|
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
|
|
|
33
34
|
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.
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
## Query and repair loop
|
|
38
|
+
|
|
39
|
+
Enable `queryable` when building, or declare persistent datums/interfaces, which require exact snapshots. Keep `query_revision_id` in compact build/edit feedback: the next query needs it. Session-bound `cad_query` uses the latest accepted artifact; after an edit, obtain new refs by rerunning semantic recipes. A failed build/query must not replace accepted source.
|
|
40
|
+
|
|
41
|
+
For installation, select the support plane, then its loops/openings, rather than all circles on the body. A normal test alone can also match a blind-hole bottom: use an earlier named plane with `planar_coplanar_with` when position matters. Symmetric groups do not establish a unique orientation; choose geometry-derived key direction or explicit design intent. A partial result is incomplete evidence, not proof that no hole/collision exists.
|
|
42
|
+
|
|
43
|
+
For clearance, query explicit occurrence pairs in assembly space. Boundary distance is unsigned; inspect the separate relationship/overlap result so a contained part with positive boundary gap cannot pass as clear. Allowed contact has a bounded supported domain, and discrete pose samples do not certify continuous travel. An ineffective required cut returns `NO_MATERIAL_REMOVED`; inspect its placement/axis instead of assuming the machining feature succeeded.
|
|
44
|
+
|
|
45
|
+
On process interruption, reopen the persisted session and resume from its accepted source. Let the SDK invalidate checkpoints whose execution-policy fingerprint differs; do not copy a cache from another build and force its metadata to match.
|
package/src/build.mjs
CHANGED
|
@@ -15,7 +15,7 @@ import { CadClient } from "../kernel/dist/index.js";
|
|
|
15
15
|
export async function build(
|
|
16
16
|
tree,
|
|
17
17
|
destination,
|
|
18
|
-
{ preview = false, binary } = {},
|
|
18
|
+
{ preview = false, queryable = false, binary } = {},
|
|
19
19
|
) {
|
|
20
20
|
const plan = compileTree(tree);
|
|
21
21
|
const model = kernelModel(tree);
|
|
@@ -26,7 +26,7 @@ export async function build(
|
|
|
26
26
|
let owned = false;
|
|
27
27
|
try {
|
|
28
28
|
const client = new CadClient({ outputRoot: stage, binary, wallMs: 120000 });
|
|
29
|
-
const result = await client.build(model);
|
|
29
|
+
const result = await client.build(model,{queryable});
|
|
30
30
|
if (!result.ok)
|
|
31
31
|
throw Error(result.error.code + ": " + result.error.message);
|
|
32
32
|
const folder = result.data.artifact_directory;
|
|
@@ -59,6 +59,7 @@ export async function build(
|
|
|
59
59
|
step: join(out, "part", "model.step"),
|
|
60
60
|
nativeJob: join(out, "part", "native-job.json"),
|
|
61
61
|
geometry: receipt.geometry,
|
|
62
|
+
...(receipt.query_revision_id?{query_revision_id:receipt.query_revision_id}:{}),
|
|
62
63
|
};
|
|
63
64
|
} catch (error) {
|
|
64
65
|
if (owned) await rm(out, { recursive: true, force: true });
|
package/src/index.d.mts
CHANGED
|
@@ -42,11 +42,12 @@ export function kernelModel(
|
|
|
42
42
|
export function build(
|
|
43
43
|
tree: FeatureTree,
|
|
44
44
|
destination: string,
|
|
45
|
-
options?: { preview?: boolean; binary?: string },
|
|
45
|
+
options?: { preview?: boolean; queryable?: boolean; binary?: string },
|
|
46
46
|
): Promise<{
|
|
47
47
|
directory: string;
|
|
48
48
|
step: string;
|
|
49
49
|
nativeJob: string;
|
|
50
|
+
query_revision_id?: string;
|
|
50
51
|
geometry: Geometry;
|
|
51
52
|
}>;
|
|
52
53
|
export function writeSolidWorks(
|
package/src/session.d.mts
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
|
-
import type { Config, Model, Receipt, PreviewOptions, Sketch } from '../kernel/dist/types.js';
|
|
2
|
-
export interface StepMetadata { label?: string; kind?: string; }
|
|
1
|
+
import type { Config, Model, Receipt, PreviewOptions, Sketch, QueryRequest } from '../kernel/dist/types.js';
|
|
2
|
+
export interface StepMetadata { label?: string; kind?: string; queryable?: boolean; }
|
|
3
3
|
export interface SessionStep {
|
|
4
|
-
id: string; label: string; kind: string; operation: 'build'|'edit'|'observe';
|
|
4
|
+
id: string; label: string; kind: string; operation: 'build'|'edit'|'observe'|'query';
|
|
5
5
|
status: 'running'|'succeeded'|'failed'|'interrupted'; startedAt: string;
|
|
6
6
|
finishedAt?: string; durationMs?: number; inputFile: string; inputSha256: string;
|
|
7
7
|
receiptFile?: string; receiptSha256?: string; artifactDirectory?: string;
|
|
8
8
|
geometry?: Record<string, unknown>; error?: { code: string; message: string };
|
|
9
9
|
nativeTimingMs?: Record<string, unknown>; degradations?: Record<string, unknown>[];
|
|
10
10
|
requestedParameters?: Record<string, number>;
|
|
11
|
+
queryable?: boolean; queryRequestFile?: string; queryRequestSha256?: string;
|
|
11
12
|
}
|
|
12
13
|
export interface SessionLedger { format: 'colocad/session/1'; id: string; title: string; createdAt: string; steps: SessionStep[]; }
|
|
13
14
|
export type SessionConfig = Omit<Config, 'outputRoot'>;
|
|
@@ -22,6 +23,7 @@ export class ModelingSession {
|
|
|
22
23
|
edit(parameters: Record<string, number>, metadata?: StepMetadata): Promise<RecordedReceipt>;
|
|
23
24
|
preview(model: Model, options?: Partial<PreviewOptions>, metadata?: StepMetadata): Promise<RecordedReceipt>;
|
|
24
25
|
observe(options?: Partial<PreviewOptions>, metadata?: StepMetadata): Promise<RecordedReceipt>;
|
|
26
|
+
query(request: QueryRequest, metadata?: StepMetadata): Promise<RecordedReceipt>;
|
|
25
27
|
capabilities(): Promise<Receipt>; schema(): Promise<Receipt>; validate(model: Model): Promise<Receipt>;
|
|
26
28
|
solveSketch(sketch: Sketch, parameters?: Record<string,number>): Promise<Receipt>;
|
|
27
29
|
inspectStep(model: Model, asset: string): Promise<Receipt>;
|
package/src/session.mjs
CHANGED
|
@@ -40,8 +40,8 @@ export class ModelingSession {
|
|
|
40
40
|
try{await writeFile(file,json({pid:process.pid}),{flag:'wx'});}catch(e){if(e.code==='EEXIST')throw Error('SESSION_BUSY: another local writer owns this session');throw e;}
|
|
41
41
|
try{return await fn();}finally{await rm(file,{force:true});}
|
|
42
42
|
}
|
|
43
|
-
async source(){const l=await this.read(),s=l.steps.findLast(x=>x.status==='succeeded'
|
|
44
|
-
async latestGeometry(){return (await this.read()).steps.findLast(x=>x.status==='succeeded'
|
|
43
|
+
async source(){const l=await this.read(),s=l.steps.findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));if(!s)throw Error('SESSION_EMPTY: build a model first');return JSON.parse(await checked(this.root,s.inputFile,s.inputSha256));}
|
|
44
|
+
async latestGeometry(){return (await this.read()).steps.findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));}
|
|
45
45
|
async build(model,metadata={}){const input=structuredClone(model);return this.lock(()=>this.run(input,'build',metadata));}
|
|
46
46
|
async edit(parameters,metadata={}){return this.lock(async()=>{
|
|
47
47
|
const model=await this.source();
|
|
@@ -56,20 +56,28 @@ export class ModelingSession {
|
|
|
56
56
|
}return this.run(next,'build',metadata);
|
|
57
57
|
});}
|
|
58
58
|
async observe(options={},metadata={}){return this.lock(async()=>{const model=await this.source();model.preview={...model.preview,...options};return this.run(model,'observe',metadata);});}
|
|
59
|
-
async
|
|
59
|
+
async query(request,metadata={}){const input=structuredClone(request);return this.lock(async()=>this.run(await this.source(),'query',metadata,undefined,undefined,input));}
|
|
60
|
+
async run(model,operation,{label=operation,kind=['observe','query'].includes(operation)?'inspection':'geometry',queryable}={},preset,requestedParameters,queryRequest){
|
|
60
61
|
const ledger=await this.read(),id='s'+String(ledger.steps.length+1).padStart(4,'0'),dir=join('steps',id);
|
|
61
62
|
await mkdir(join(this.root,dir),{recursive:true});
|
|
62
|
-
if(
|
|
63
|
+
if(!['observe','query'].includes(operation))model.preview={view:'iso',chord_mm:.6,width:960,height:640,...model.preview};
|
|
63
64
|
const bytes=json(model);await writeFile(join(this.root,dir,'input.json'),bytes);
|
|
64
65
|
const step={id,label:String(label),kind:String(kind),operation,status:'running',startedAt:new Date().toISOString(),inputFile:dir+'/input.json',inputSha256:sha(bytes),receiptFile:dir+'/receipt.json'};
|
|
65
66
|
if(requestedParameters)step.requestedParameters=requestedParameters;
|
|
67
|
+
if(queryRequest){const requestBytes=json(queryRequest);step.queryRequestFile=dir+'/query.json';step.queryRequestSha256=sha(requestBytes);await writeFile(join(this.root,step.queryRequestFile),requestBytes);}
|
|
66
68
|
ledger.steps.push(step);await atomic(join(this.root,'session.json'),ledger);
|
|
67
69
|
const start=performance.now();let result;
|
|
68
70
|
try{
|
|
69
|
-
const previous=ledger.steps.slice(0,-1).findLast(x=>x.status==='succeeded'
|
|
70
|
-
|
|
71
|
+
const previous=ledger.steps.slice(0,-1).findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));
|
|
72
|
+
step.queryable=queryable??((model.datums?.length||model.interfaces?.length)?true:previous?.queryable??false);
|
|
73
|
+
const accepted=operation==='query'?JSON.parse(await checked(this.root,previous.receiptFile,previous.receiptSha256)):undefined;
|
|
74
|
+
if(accepted&&queryRequest.query_revision_id!==accepted.data.query_revision_id)preset={ok:false,error:{code:'QUERY_REVISION_MISMATCH',message:'Query must target the accepted geometry revision'}};
|
|
75
|
+
result=preset??await (operation==='query'
|
|
76
|
+
?this.cad.query(inside(this.root,previous.artifactDirectory),queryRequest)
|
|
77
|
+
:operation==='observe'
|
|
71
78
|
?this.cad.observeArtifact(inside(this.root,previous.artifactDirectory),model.preview)
|
|
72
|
-
:this.cad.build(model,previous?inside(this.root,previous.artifactDirectory):undefined));
|
|
79
|
+
:this.cad.build(model,{previousRevision:previous?inside(this.root,previous.artifactDirectory):undefined,queryable:step.queryable}));
|
|
80
|
+
if(operation==='query'&&result.ok){result.data.artifact_directory=inside(this.root,previous.artifactDirectory);result.data.source_artifact_directory=result.data.artifact_directory;result.data.source_artifact_sha256=accepted.data.artifact_sha256;}
|
|
73
81
|
}catch(e){result={ok:false,error:{code:'SESSION_EXECUTION_FAILED',message:String(e.message)}};}
|
|
74
82
|
step.durationMs=performance.now()-start;step.finishedAt=new Date().toISOString();step.status=result.ok?'succeeded':'failed';
|
|
75
83
|
const saved=structuredClone(result);
|
|
@@ -91,7 +99,12 @@ export class ModelingSession {
|
|
|
91
99
|
export async function createSessionTools(session) {
|
|
92
100
|
const tools=await createCadTools(session.cad);
|
|
93
101
|
for(const tool of tools){
|
|
94
|
-
if(tool.name==='cad_build')tool.execute=({model})=>session.build(model,{label:'Agent build'});
|
|
102
|
+
if(tool.name==='cad_build')tool.execute=({model,options})=>session.build(model,{label:'Agent build',queryable:options?.queryable});
|
|
103
|
+
if(tool.name==='cad_query'){
|
|
104
|
+
delete tool.inputSchema.properties.artifact_directory;tool.inputSchema.required=['request'];
|
|
105
|
+
tool.description='Query the latest accepted exact snapshot, persist request/result, and reject stale revisions without changing accepted source.';
|
|
106
|
+
tool.execute=({request})=>session.query(request,{label:'Agent geometry query'});
|
|
107
|
+
}
|
|
95
108
|
if(tool.name==='cad_preview')tool.execute=({model,options})=>session.preview(model,options,{label:'Agent preview'});
|
|
96
109
|
if(tool.name==='cad_edit'){
|
|
97
110
|
delete tool.inputSchema.properties.model;
|
|
@@ -107,16 +120,19 @@ export async function readSessionBundle(directory,{cutaway=false,view='iso'}={})
|
|
|
107
120
|
const root=resolve(directory),ledger=await load(join(root,'session.json'));
|
|
108
121
|
if(ledger.format!==format)throw Error('SESSION_FORMAT');
|
|
109
122
|
const bundle={format:'colocad/viewer/1',title:ledger.title,id:ledger.id,createdAt:ledger.createdAt,display:{cutaway,view},steps:[],meshes:{}};
|
|
110
|
-
const last=ledger.steps.findLast(x=>x.status==='succeeded'
|
|
123
|
+
const last=ledger.steps.findLast(x=>x.status==='succeeded'&&!['observe','query'].includes(x.operation));
|
|
111
124
|
for(const entry of ledger.steps){
|
|
112
125
|
const step={...entry};
|
|
113
126
|
if(entry.inputFile)step.model=JSON.parse(await checked(root,entry.inputFile,entry.inputSha256));
|
|
114
127
|
if(entry.receiptFile&&entry.receiptSha256)step.receipt=JSON.parse(await checked(root,entry.receiptFile,entry.receiptSha256));
|
|
128
|
+
if(entry.queryRequestFile)step.queryRequest=JSON.parse(await checked(root,entry.queryRequestFile,entry.queryRequestSha256));
|
|
115
129
|
if(entry.status==='succeeded'){
|
|
116
130
|
const data=step.receipt.data,artifact=entry.artifactDirectory;inside(root,artifact);
|
|
117
131
|
// Observation results keep their original exact-geometry source for later lookup.
|
|
118
132
|
const source=data.source_artifact_directory??artifact;
|
|
119
|
-
const sourceReport=source===artifact?data:await load(inside(root,source+'/report.json'));
|
|
133
|
+
const sourceReport=entry.operation==='query'?{artifact_sha256:data.source_artifact_sha256}:source===artifact?data:await load(inside(root,source+'/report.json'));
|
|
134
|
+
const guideHash=sourceReport.artifact_sha256?.['query-display.json'];
|
|
135
|
+
if(guideHash)step.queryDisplay=JSON.parse(await checked(root,source+'/query-display.json',guideHash));
|
|
120
136
|
const hash=sourceReport.artifact_sha256?.['preview.mesh.json'];
|
|
121
137
|
if(!hash)throw Error('SESSION_INTEGRITY: missing native preview mesh hash');
|
|
122
138
|
const scene=JSON.parse(await checked(root,source+'/preview.mesh.json',hash));
|