# LLM-Orchestrated Atomizer Workflow ## Core Philosophy **Atomizer is LLM-first.** The user talks to Claude Code, describes what they want in natural language, and the LLM orchestrates everything: - Interprets engineering intent - Creates optimized configurations - Sets up study structure - Runs optimizations - Generates reports - Implements custom features **The dashboard is for monitoring, not setup.** --- ## Architecture: Skills + Protocols + Validators ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ USER (Natural Language) │ │ "I want to optimize this drone arm for weight while keeping it stiff" │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ CLAUDE CODE (LLM Orchestrator) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ SKILLS │ │ PROTOCOLS │ │ VALIDATORS │ │ KNOWLEDGE │ │ │ │ (.claude/ │ │ (docs/06_) │ │ (Python) │ │ (docs/) │ │ │ │ commands/) │ │ │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ └─────────────────┴─────────────────┴─────────────────┘ │ │ │ │ │ ORCHESTRATION LOGIC │ │ (Intent → Plan → Execute → Validate) │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ ATOMIZER ENGINE │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Config │ │ Runner │ │ Extractors │ │ Reports │ │ │ │ Generator │ │ (FEA/NN) │ │ (OP2/CAD) │ │ Generator │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ OUTPUTS (User-Visible) │ │ │ │ • study/1_setup/optimization_config.json (config) │ │ • study/2_results/study.db (optimization data) │ │ • reports/ (visualizations) │ │ • Dashboard at localhost:3000 (live monitoring) │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## The Three Pillars ### 1. SKILLS (What LLM Can Do) Location: `.claude/skills/*.md` Skills are **instruction sets** that tell Claude Code how to perform specific tasks with high rigor. They're like recipes that ensure consistency. ``` .claude/skills/ ├── create-study.md # Create new optimization study ├── analyze-model.md # Analyze NX model for optimization ├── configure-surrogate.md # Setup NN surrogate settings ├── generate-report.md # Create performance reports ├── troubleshoot.md # Debug common issues └── extend-feature.md # Add custom functionality ``` ### 2. PROTOCOLS (How To Do It Right) Location: `docs/06_PROTOCOLS_DETAILED/` Protocols are **step-by-step procedures** that define the correct sequence for complex operations. They ensure rigor and reproducibility. ``` docs/06_PROTOCOLS_DETAILED/ ├── PROTOCOL_01_STUDY_SETUP.md ├── PROTOCOL_02_MODEL_VALIDATION.md ├── PROTOCOL_03_OPTIMIZATION_RUN.md ├── PROTOCOL_11_MULTI_OBJECTIVE.md ├── PROTOCOL_12_HYBRID_SURROGATE.md └── LLM_ORCHESTRATED_WORKFLOW.md (this file) ``` ### 3. VALIDATORS (Verify It's Correct) Location: `optimization_engine/validators/` Validators are **Python modules** that check configurations, outputs, and state. They catch errors before they cause problems. ```python # Example: optimization_engine/validators/config_validator.py def validate_optimization_config(config: dict) -> ValidationResult: """Ensure config is valid before running.""" errors = [] warnings = [] # Check required fields if 'design_variables' not in config: errors.append("Missing design_variables") # Check bounds make sense for var in config.get('design_variables', []): if var['bounds'][0] >= var['bounds'][1]: errors.append(f"{var['parameter']}: min >= max") return ValidationResult(errors, warnings) ``` --- ## Master Skill: `/create-study` This is the primary entry point. When user says "I want to optimize X", this skill orchestrates everything. ### Skill File: `.claude/skills/create-study.md` ```markdown # Create Study Skill ## Trigger User wants to create a new optimization study. ## Required Information (Gather via conversation) ### 1. Model Information - [ ] NX model file location (.prt) - [ ] Simulation file (.sim) - [ ] FEM file (.fem) - [ ] Analysis types (static, modal, buckling, etc.) ### 2. Engineering Goals - [ ] What to optimize (minimize mass, maximize stiffness, etc.) - [ ] Target values (if any) - [ ] Constraints (max stress, min frequency, etc.) - [ ] Engineering context (what is this part for?) ### 3. Design Variables - [ ] Which parameters can change - [ ] Bounds for each (min/max) - [ ] Integer vs continuous ### 4. Optimization Settings - [ ] Number of trials - [ ] Single vs multi-objective - [ ] Enable NN surrogate? (recommend for >50 trials) ## Execution Steps ### Step 1: Analyze Model Read the NX model to: - Extract existing expressions (potential design variables) - Identify geometry features - Check simulation setup ### Step 2: Generate Configuration Create optimization_config.json with: - All gathered information - Sensible defaults for missing info - Appropriate protocol selection ### Step 3: Validate Configuration Run config validator to check: - All required fields present - Bounds are reasonable - Extraction methods are correct ### Step 4: Create Study Structure ``` studies/{study_name}/ ├── 1_setup/ │ ├── model/ # Copy of NX files │ ├── optimization_config.json │ └── workflow_config.json ├── 2_results/ └── README.md ``` ### Step 5: Confirm with User Show summary: - Design variables and bounds - Objectives and constraints - Recommended settings - Estimated time ### Step 6: Start Optimization (if confirmed) Run the optimization with appropriate flags. ## Error Handling - If model not found: Ask for correct path - If expressions not found: List available ones - If config invalid: Show errors, suggest fixes ## Output - Valid study folder structure - Validated optimization_config.json - README with study description - Optional: Start optimization run ``` --- ## Conversation Flow Example ``` USER: I want to optimize this bracket for weight. The model is at examples/Models/Bracket/bracket.prt CLAUDE: I'll help you set up an optimization study for the bracket. Let me first analyze your model to understand its structure. [Reads model, extracts expressions] I found these parametric expressions in your model: - wall_thickness (current: 2mm) - fillet_radius (current: 3mm) - hole_diameter (current: 10mm) - rib_count (current: 4) Which of these should be design variables for optimization? USER: All of them. Wall thickness 1-4mm, fillet 2-8mm, hole 5-20mm, ribs 2-6. CLAUDE: Got it. Now for the engineering requirements: 1. What's the loading condition? (I see a static analysis in your sim) 2. Any stress limits? (Material yield strength?) 3. Any displacement limits? 4. Is there a target weight you're trying to achieve? USER: It's holding a 50kg load. Aluminum 6061, so keep stress under 200 MPa. Max deflection 0.5mm. Want it as light as possible. CLAUDE: Perfect. Here's your optimization setup: **Study: bracket_weight_optimization** **Design Variables:** | Parameter | Min | Max | Type | |---------------|-----|-----|---------| | wall_thickness | 1 | 4 | float | | fillet_radius | 2 | 8 | float | | hole_diameter | 5 | 20 | float | | rib_count | 2 | 6 | integer | **Objective:** Minimize mass **Constraints:** - Max von Mises stress < 200 MPa - Max displacement < 0.5 mm **Settings:** - Protocol: Single-objective constrained - Trials: 50 (recommended for 4 variables) - Sampler: TPE (good for constrained problems) Should I create this study? I can also enable neural network acceleration if you want more than 50 trials. USER: Yes, create it. And enable the NN thing, let's do 200 trials. CLAUDE: Creating study with NN surrogate enabled... [Creates folder structure] [Generates optimization_config.json] [Validates configuration] [Copies model files] Study created at: studies/bracket_weight_optimization/ Configuration validated successfully: ✓ All design variables have valid bounds ✓ Extraction methods configured ✓ Surrogate settings enabled Ready to start optimization. The workflow will: 1. Run 30 initial FEA trials 2. Generate 100 space-filling training points 3. Train NN surrogate 4. Run 170 NN-accelerated trials with FEA validation Start now? (You can monitor at localhost:3000) USER: Yes, start it. CLAUDE: Starting optimization... [Runs optimization in background] Optimization running (ID: bracket_weight_optimization) - Monitor: http://localhost:3000 - Optuna Dashboard: http://localhost:8081 I'll notify you when Stage 1 (initial FEA) completes. ``` --- ## Skill Library ### Core Skills (Must Have) | Skill | Trigger | Purpose | |-------|---------|---------| | `/create-study` | "optimize", "new study" | Create optimization from scratch | | `/analyze-model` | "look at model", "what can I optimize" | Extract model info | | `/run-optimization` | "start", "run" | Execute optimization | | `/check-status` | "how's it going", "progress" | Report on running studies | | `/generate-report` | "report", "results" | Create visualizations | ### Advanced Skills (For Power Users) | Skill | Trigger | Purpose | |-------|---------|---------| | `/configure-surrogate` | "neural network", "surrogate" | Setup NN acceleration | | `/add-constraint` | "add constraint" | Modify existing study | | `/compare-studies` | "compare" | Cross-study analysis | | `/export-results` | "export", "pareto" | Export optimal designs | | `/troubleshoot` | "error", "failed" | Debug issues | ### Custom Skills (Project-Specific) Users can create their own skills for recurring tasks: ``` .claude/skills/ ├── my-bracket-setup.md # Pre-configured bracket optimization ├── thermal-analysis.md # Custom thermal workflow └── batch-runner.md # Run multiple studies ``` --- ## Implementation Approach ### Phase 1: Foundation (Current) - [x] Basic skill system (create-study.md exists) - [x] Config validation - [x] Manual protocol following - [ ] **Formalize skill structure** - [ ] **Create skill template** ### Phase 2: Skill Library - [ ] Implement all core skills - [ ] Add protocol references in skills - [ ] Create skill chaining (one skill calls another) - [ ] Add user confirmation checkpoints ### Phase 3: Validators - [ ] Config validator (comprehensive) - [ ] Model validator (check NX setup) - [ ] Results validator (check outputs) - [ ] State validator (check study health) ### Phase 4: Knowledge Integration - [ ] Physics knowledge base queries - [ ] Similar study lookup - [ ] Transfer learning suggestions - [ ] Best practices recommendations --- ## Skill Template Every skill should follow this structure: ```markdown # Skill Name ## Purpose What this skill accomplishes. ## Triggers Keywords/phrases that activate this skill. ## Prerequisites What must be true before running. ## Information Gathering Questions to ask user (with defaults). ## Protocol Reference Link to detailed protocol in docs/06_PROTOCOLS_DETAILED/ ## Execution Steps 1. Step one (with validation) 2. Step two (with validation) 3. ... ## Validation Checkpoints - After step X, verify Y - Before step Z, check W ## Error Handling - Error type 1: Recovery action - Error type 2: Recovery action ## User Confirmations Points where user approval is needed. ## Outputs What gets created/modified. ## Next Steps What to suggest after completion. ``` --- ## Key Principles ### 1. Conversation > Configuration Don't ask user to edit JSON. Have a conversation, then generate the config. ### 2. Validation at Every Step Never proceed with invalid state. Check before, during, and after. ### 3. Sensible Defaults Provide good defaults so user only specifies what they care about. ### 4. Explain Decisions When making choices (sampler, n_trials, etc.), explain why. ### 5. Graceful Degradation If something fails, recover gracefully with clear explanation. ### 6. Progressive Disclosure Start simple, offer complexity only when needed. --- ## Integration with Dashboard The dashboard complements LLM interaction: | LLM Handles | Dashboard Handles | |-------------|-------------------| | Study setup | Live monitoring | | Configuration | Progress visualization | | Troubleshooting | Results exploration | | Reports | Pareto front interaction | | Custom features | Historical comparison | **The LLM creates, the dashboard observes.** --- ## Next Steps 1. **Formalize Skill Structure**: Create template that all skills follow 2. **Implement Core Skills**: Start with create-study, analyze-model 3. **Add Validators**: Python modules for each validation type 4. **Test Conversation Flows**: Verify natural interaction patterns 5. **Build Skill Chaining**: Allow skills to call other skills --- *Document Version: 1.0* *Created: 2025-11-25* *Philosophy: Talk to the LLM, not the dashboard*