docs/engine-assembly-milestone.md

Engine-Assembly Milestone (Concept)

Goal

Support high-detail assemblies (example: engine block + major subsystems) without relying on a single one-shot prompt-to-code pass.

Why

Single-pass generation is strong for parts and simple assemblies, but detailed mechanical assemblies need decomposition, validation, and staged execution.

Proposed architecture (multi-stage)

1. Intent + Scope Pass

   • Parse user request into complexity level and target detail level (L1/L2/L3).
   • Confirm assumptions if needed (internal channels, bolt patterns, tolerances, etc.).

2. Assembly Plan JSON

   • Generate a strict JSON plan:
     • parts list
     • param schema per part
     • mating/constraint relationships
     • units + coordinate conventions
   • Validate against a JSON schema before any CAD execution.

3. Per-Part CAD Generation

   • Generate build123d code per part (isolated runs).
   • Validate and export each part independently.
   • Retry/fix only failed parts, not the whole assembly.

4. Assembly Build Pass

   • Compose validated parts into final assembly.
   • Run constraint checks and collision checks where possible.

5. Output Profiles

   • L1: concept massing
   • L2: manufacturing-relevant external features
   • L3: high-detail subsystem geometry
   • Export: STEP/STL (+ optional linework outputs later)

Guardrails

• Per-part complexity cap and timeout.
• Max part count per run (configurable).
• Graceful degrade path (drop to L2 if L3 is too heavy).
• User-facing messages should explain what detail was delivered.

Success criteria

• Higher success rate for detailed prompts.
• Better partial recovery (single part fail does not kill full job).
• More predictable latency and compute cost.
• Clear user control over detail level.

Suggested implementation order

1. Define JSON schema + validator.
2. Add planner stage (returns plan only).
3. Add per-part execution loop with retries.
4. Add assembly compose stage.
5. Add detail profile controls in UI.