Text-to-CAD: parametric source, geometry evidence and responsible handoff
Text-to-CAD architecture: source freshness and document compilation answer different questions
Trace model calls, derived outputs and viewer state, including pull-based assembly updates and inputs the freshness contract does not observe.
What you will learn
- Follow the source build path
- A document can render while its source has moved on
- Make geometry inputs explicit
Before you start
- Basic Python functions, modules and file paths
- Understanding of units and the difference between a design and a physical part
Plan a bounded CAD exercise and distinguish source freshness, document inspection, visual review and manufacturing decisions.
Key takeaways
- Parent assemblies consume child updates when rebuilt.
- Document rendering does not establish source freshness.
- Geometry-changing inputs should be explicit and tracked.
Follow the source build path
The CAD guide describes model identity through a file and function, geometry returned from the body and outputs declared by decorators. Parent models call child models and place their geometry. A child change is not pushed automatically into every parent artifact; the parent must be rebuilt to consume changed child results.
The documented store holds derived, content-addressed geometry and model records. Freshness checks consider source, imported constants, child results and declared outputs. This is a documented contract, not a concurrency or cache implementation we fully tested in this series.
A document can render while its source has moved on
Inspection and viewing start from a STEP or mesh document, not its Python generator. If the store lacks the document’s representation, a document operation can compile it from existing bytes. That says what the file contains now, not whether a later source edit should have produced different bytes.
The viewer’s states describe document compilation and rendering, including failure. For source freshness, use the model-oriented store why diagnostic and rebuild the relevant source target. Reopening the same old STEP in a viewer does not apply an edited dimension from Python.
Make geometry inputs explicit
The guide warns that environment variables, current time, working directory and randomness are not tracked geometry inputs. Put configuration into explicit constants or factory arguments instead of hiding it in ambient process state. Otherwise a changing external value may leave the freshness result misleadingly current.
One source file per model is the recommended organization because models sharing a file also share its source closure. Choose boundaries around meaningful parts and dependencies. We did not test daemon races, cache invalidation across runtime upgrades or full assembly rebuilds; do not infer those guarantees from the diagram.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Identify source model, child dependencies and declared outputs.
- 2
Ask whether the problem concerns source or document bytes.
- 3
Use source freshness diagnostics before rebuilding.
- 4
Remove hidden time, environment or random geometry inputs.
Copy-ready example
{
"diagnostic": true,
"sourceEdited": true,
"documentRendered": true,
"sourceFreshnessKnown": false,
"nextCheck": "cadgen store why sample.py",
"rebuildTarget": "sample.py"
}Frequently asked questions
Will rebuilding a child automatically update every assembly file?
The documented dependency model is pull-based; rebuild the parent to consume its changed child.
Does Rendered mean the source is current?
No. It is a document-side viewer state.
Sources
- Text-to-CAD / skills/cad/SKILL.mdSource checked 2026-09-14
- Text-to-CAD / skills/cad-viewer/SKILL.mdSource checked 2026-09-14