Atomizer/docs/06_PROTOCOLS_DETAILED/LLM_ORCHESTRATED_WORKFLOW.md

# 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*