likang/cdsl-cad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(cdsl_engine): document package layout and the add-atomic-operation workflow

Browse Source 
Phase 8: README now maps every module of the split package, documents
the executor registration + schema-contract workflow for new atomic
operations, and restates the schema maintenance rule for executors/.
This commit is contained in:
ganjihong
2026-09-09 14:34:14 +08:00
parent 95cae203f4
commit 6fa4501f16
1 changed files with 49 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/engine/cdsl_engine/README.md
+49 -12
View File
@@ -4,17 +4,53 @@ This package rebuilds `cad.cdsl.llm.v1` models through the CDSL-only path:
`semantic validation -> capability analysis -> sketch resolution -> session runtime -> STEP`
`runtime.py` owns the executor registry, an `ExecutionSession`, and the
feature/topology lifecycle. `build123d_adapter.py` is the only layer that
creates or mutates B-rep objects. `runtime_types.py` owns runtime-neutral
feature, context, selector, and topology contracts. `llm_compiler.py` and
`llm_engine.py` remain available for legacy engine-plan compatibility but are
not used by `run_cdsl_only`.
## Package layout
| Module | Responsibility |
|---|---|
| `specs.py` | Vector math, plane/axis helpers, parametric feature specs (no kernel deps) |
| `topology.py` | Diagnostics, planning contracts, `TopologyRegistry`, selector resolution |
| `capabilities.py` | `CapabilityAnalyzer`: preflight blockers before any geometry runs |
| `sketch_solver.py` | Profile expansion (circle / polygon / analytic contours) |
| `session.py` | `ExecutionSession` and the kernel-facing `GeometryAdapter` protocol |
| `runtime_base.py` | Shared error types and the `ExtentVector` value |
| `extents.py` | End-condition planning (blind / through / up-to-surface / ...) |
| `pattern_transform.py` | Translate/mirror/rotate parameter algebra for pattern replay |
| `registry.py` | `EXECUTORS`, the `atomic_executor` decorator, and `execute_node` dispatch |
| `executors/` | One module per executor family; importing the package registers all |
| `build123d_adapter.py` | The only layer that creates or mutates B-rep objects |
| `topology.py` / `runtime_types.py` | Historical re-export shim (`runtime_types`) |
| `translator/` | Frozen SolidWorks-exact code generation (`ir` / `codegen` / `runtime_lib`) |
| `legacy/` | Frozen legacy engine paths (`llm_compiler`, `llm_engine`, exact rebuilds) |
| `rebuild.py` | Legacy three-way facade plus `compare_with_gold` acceptance |
`runtime.py` keeps the `analyze_cdsl` / `rebuild_cdsl` entry points and
re-exports the historical names. `llm_compiler.py` and `llm_engine.py` are
compatibility shims for the frozen `legacy/` implementations and are not used
by `run_cdsl_only`.
## Adding an atomic operation
1. Add the operation contract to `profile_schema.json` (`operation_contracts`),
including its `runtime_capability` flags — this is the single source of
truth for preflight classification.
2. Add a decorated executor function in exactly one `executors/<family>.py`
module (`@atomic_executor("...")`); the shared registry never changes.
3. Add the atomic id to `ALL_ATOMIC_IDS` in `registry.py` (registration fails
fast on unknown or duplicate ids, and `executors/__init__` fails if any
declared id has no registered executor).
4. Update `cdsl_schema.json` in the same change.
5. Extend `backend/tests/test_profile_schema.py` fixtures if the contract
shape changed.
Multiple people can add different operations in parallel without touching a
shared registry file: the only shared edits are the two schema documents.
Supported profiles are defined by `SHAPE_GENERATORS` in `sketch_solver.py`.
Supported feature atomic operations are defined by `EXECUTORS` in `runtime.py`.
Their human-readable contract is in `profile_schema.json`; the complete,
machine-enforced CDSL object contract is in `cdsl_schema.json`.
Supported feature atomic operations are defined by `EXECUTORS` (populated from
`executors/` at import time). Their human-readable contract is in
`profile_schema.json`; the complete, machine-enforced CDSL object contract is
in `cdsl_schema.json`.
The Studio only accepts self-contained profile data and requires successful
`engine=cdsl_only` output. It never uses the legacy translator fallback or
`compiler_context`.
@@ -24,10 +60,11 @@ The Studio only accepts self-contained profile data and requires successful
`profile_schema.json` and `cdsl_schema.json` together are the source of truth
for the engine contract exposed to the CAD Agent and the backend validator.
Any addition, removal, rename, or parameter-contract change in
`sketch_solver.py`, `runtime.py`, or the build adapter must update both files
`sketch_solver.py`, `executors/`, or the build adapter must update both files
in the same change.
`backend/tests/test_profile_schema.py` fails when the registered profiles or
supported atomic operations diverge from the document.
`backend/tests/test_profile_schema.py` fails when the registered profiles,
supported atomic operations, or `runtime_capability` flags diverge from the
document.
## Batch baseline