ganjihong
6fa4501f16
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/.
98 lines
4.8 KiB
Markdown
98 lines
4.8 KiB
Markdown
# Local CDSL Engine
|
|
|
|
This package rebuilds `cad.cdsl.llm.v1` models through the CDSL-only path:
|
|
|
|
`semantic validation -> capability analysis -> sketch resolution -> session runtime -> STEP`
|
|
|
|
## 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` (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`.
|
|
|
|
## Engine schema maintenance
|
|
|
|
`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`, `executors/`, or the build adapter must update both files
|
|
in the same change.
|
|
`backend/tests/test_profile_schema.py` fails when the registered profiles,
|
|
supported atomic operations, or `runtime_capability` flags diverge from the
|
|
document.
|
|
|
|
## Batch baseline
|
|
|
|
Use the resumable batch entry point to produce feature-level eligibility and
|
|
rebuild reports. `--build` invokes only the session-based CDSL runtime; it
|
|
never falls back to `compiler_context` or the legacy translator.
|
|
|
|
```bash
|
|
PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
|
|
json_to_cdsl/output --out /tmp/cdsl-batch --build --build-timeout 15
|
|
```
|
|
|
|
The output directory contains `manifest.json`, one report per part under
|
|
`parts/`, `summary-by-atomic.json`, and `summary-by-blocker.json`. Re-run the
|
|
same command to resume completed work; use `--max-parts` to run a bounded CI
|
|
shard.
|
|
|
|
Use `--part-ids 046112,053393` to run an exact, comma-separated regression
|
|
subset. Unknown ids are rejected so a phase baseline cannot silently omit a
|
|
requested part.
|
|
|
|
Use `--phase p3`, `--phase p4`, or `--phase p6` to run a documented
|
|
strict-closed static pool. The
|
|
selector lives in `phase_pools.py`; its membership is regression-tested
|
|
against the committed exports rather than copied into a shell command.
|
|
|
|
The runtime foundation test suite also analyzes every committed export without
|
|
building STEP, so CI verifies that the full corpus always yields one
|
|
machine-readable capability result per input. Use the batch command above for
|
|
the slower, resumable truth-build layer.
|