c0bfabb3a3
Replaces the AGPL-3.0 license text with the canonical Apache License 2.0 and updates every reference: pyproject trove classifier, both README license sections, and the skill frontmatter. The article drafts under docs/ are untracked and were updated separately.
8.8 KiB
8.8 KiB
name, description, license, metadata
| name | description | license | metadata | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| simplecadapi | Build, assemble, inspect, reconstruct, and export parametric CAD models with the SimpleCADAPI Python SDK. Use for SimpleCAD geometry modeling, constrained sketches, parts and assemblies, standard gears and bearings, STEP/BREP inspection and reconstruction, durable product packages, model JSON replay, and CAD backend translation. | Apache-2.0 |
|
SimpleCAD SDK Skill
This file is the router: it owns load order, route selection, and execution discipline only. Each selected workflow owns its procedure. Classify the request, load exactly one workflow, follow its domain and discipline references, and read exact API pages for the APIs its steps use.
Mandatory load order
Paths are relative to this file's directory.
- Read this file.
- Select exactly one workflow from Task routing. If two rows plausibly match, ask one discriminator question that names the candidate outcomes; never pick silently between routes with different deliverables.
- Read the selected workflow in full. From selection on, it owns the procedure; do not load another workflow's procedure.
- Load each required domain/discipline file the workflow names before the step that uses it; optional ones only when their trigger fires.
- Before the first call of any API, read its exact page
(
references/docs/api/<name>.md,references/docs/stdlib/<name>.md,references/docs/core/<type>.md). A method absent from its page does not exist, however plausible it looks.
- You MUST NOT read the full API or stdlib index up front; the workflow names every page its steps need.
- Routing questions are decided here; after selection the workflow owns execution. You MUST always follow the global rules and execution discipline below.
- Questions about an existing STEP file that change nothing enter no
workflow; you MUST use
references/domains/step-inspection.mdfor them directly.
Task routing
Read exactly one workflow first, per the user's goal:
| User goal | Workflow |
|---|---|
| Model one physical part | references/workflows/single-part-modeling.md |
| Multi-part product or mechanism (custom parts, stdlib gears/bearings, connectors, constraints, package) | references/workflows/assembly-product-build.md |
| Rebuild an editable model from a STEP file | references/workflows/step-reconstruction.md |
| Export/translate a validated package | references/workflows/export-and-translation.md |
| Produce a GB engineering drawing (DXF) from validated geometry | references/workflows/engineering-drawing.md |
Do not present route-choice menus when a row already matches: profile, strategy, and tool choices inside a route belong to that workflow's own gates, not to an up-front question. A missing prerequisite — state it and stop that route; never invent an alternative route.
Routing discipline
| Rule | Behavior |
|---|---|
| One lifecycle per request | Every task enters exactly one workflow; domains, disciplines, and guides refine it and are never competing routes |
| Deterministic selection | When the matrix matches, proceed without asking a route question |
| Ambiguous request | Ask one discriminator question naming the candidate deliverables (editable model vs inspection evidence vs export package), then route |
| Missing prerequisite | Name what is missing and stop that route |
| Explicit user override | Honor it only when the target route's scope actually covers the request |
Global rules (every task)
- Refine the requirement into a brief before modeling
(
references/domains/requirement-refinement.md). - Use keyword arguments for every documented public API and
stdlib function, except the canonical durable export call
capture(result, path), whose two required arguments are positional. - One part per file; one assembly file per product; parameters
live in the file that consumes them; exposed tunable parameters
are
var()/Vardeclarations (optionally withunit,tolerance). Part sources follow the Feature Tree Convention (references/discipline/feature-tree-convention.md): block structuresketch → basic body op → bool → modifier, one feature per block with a mandatory boundary comment# ---- feature: <slug> (<role>) ----; 2D profiles and planar paths go through the sketch API, primitives only when the shape is completely contained in the basic form. - Booleans (
union_rsolid,cut_rsolid,intersect_rsolid) accept mixed inputs and return exactly oneSolid; union defaults toglue=Falsewith a conservative scale-relative tolerance and fails explicitly when it cannot produce one merged solid. - Build and validate incrementally: each major step prints small QL-derived facts; grounding uses QL wherever possible; never print whole solids or full model objects.
- Topology enumeration is QL-only and strictly enforced: plural
getters (
get_edges,get_faces,get_wires,get_vertices,get_solids,get_inner_wires) accept ONLY an index — the no-argument list form raises. Enumerate, count, and measure viaql.<kind>().resolve(shape); filter with QL predicates plustake/exactlycardinality; never build selections by looping over an enumerated list and indexing it. Indexed picks (get_edges(index)) are reserved for intentional, named choices and are recorded as graph selection nodes. - Tags: attach with
apply_tag(shape=..., tag=...)(LOCAL scope — it never propagates downward); inspect withlist_tags(shape=...); keep numeric facts in metadata, never in tags. @scad.partfor one physical single-solid product;@scad.assemblefor assemblies with explicit definitions. Neither nests inside an activeGraphSession. Durable delivery iscapture(result, "out/product.scadpkg")in one call.simplecadapi.inspect.brepis diagnostic-only and rejected insideGraphSession; obtain/export geometry first, inspect outside.- Standard parts first: before hand-modeling a gear, ring gear,
rack, cycloidal disc, or bearing, check
scad.std.gear/scad.std.bearing. - Read
references/docs/guides/cache-build-workflow.mdin full before configuring persistent cache, durable builds, or cache maintenance; cache mutation requires explicit confirmation.
Boundaries
.scadpkgis the canonical durable product; STL/OBJ/MJCF are point-in-time exports, never editable sources.- Model JSON is the replay/interchange contract for explicit
GraphSessionflows; never hand-author payloads. - No claims of strength, fatigue, thermal, vibration, tolerance compliance, or regulatory fitness without the corresponding analysis actually run.
Execution discipline (every task)
- Gates bind artifacts: a validation gate passes only when its named artifact exists — printed QL facts, targeted measurements, named rendered views, completed brief fields. A stated feeling of success is not a gate result.
- Blocking waits: an Ask-or-Record blocking item resolves before any geometry — asked once (batched into one question set) or recorded as an explicit assumption. Proceeding with neither is the failure, not the asking.
- Serial phases: do not preload later-phase pages or build later-phase artifacts early. After an interruption, re-ground from the owning artifact (source file, brief), not from conversation memory.
- Repair the owning source: the named parameter, the brief field, or
the upstream selection — never the downstream symptom.
Candidate x parameter enumeration loops are diagnosis debt, not
repair (
references/discipline/failure-and-repair.md). - A failed check closes by changing the design or by redefining the check with the user — never by weakening or deleting the check.
Example SDK usage
import simplecadapi as scad
from simplecadapi import GraphSession, export_model_json, replay_model_json
with GraphSession(graph_id="box") as session:
shape = scad.make_box_rsolid(width=10.0, height=20.0, depth=30.0)
session.capture_result(value=shape)
payload = export_model_json(session=session)
rebuilt = replay_model_json(json_str=payload)
print(len(rebuilt))
References
references/README.md— skill layer structurereferences/workflows/— six goal-oriented workflowsreferences/domains/— eight capability domainsreferences/discipline/— modeling knowledge and invariantsreferences/SDK_OVERVIEW.md— package-level mapreferences/inspect/brep-reverse-engineering.mdreferences/docs/guides/reconstruction-agent-test-prompt.mdreferences/docs/guides/reconstruction-agent-strategy.mdreferences/docs/guides/cache-build-workflow.mdreferences/docs/guides/ql-selection-playbook.mdreferences/docs/api/,references/docs/stdlib/,references/docs/core/