ics-simlab-config-gen-claude/README.md

# ICS-SimLab Configuration Generator (Claude)

Generatore di configurazioni e logica PLC/HIL per ICS-SimLab usando LLM.

## 🚀 Quick Start

### 1. Genera configurazione da testo (LLM)
```bash
source .venv/bin/activate
python3 main.py --input-file prompts/input_testuale.txt
```

### 2. Build scenario completo
```bash
python3 build_scenario.py --out outputs/scenario_run --overwrite
```

### 3. Valida fix PLC
```bash
python3 validate_fix.py
```

### 4. Esegui ICS-SimLab
```bash
./scripts/run_simlab.sh
```

## 📁 Struttura Progetto

```
ics-simlab-config-gen_claude/
├── main.py                    # Script principale (LLM -> configuration.json)
├── build_scenario.py          # Builder scenario (config -> IR -> logic)
├── validate_fix.py            # Validazione fix PLC startup race
├── README.md                  # Questo file
│
├── docs/                      # 📚 Documentazione completa
│   ├── README_FIX.md         # Main doc per fix PLC startup race
│   ├── QUICKSTART.txt        # Guida rapida
│   ├── RUNTIME_FIX.md        # Fix completo con troubleshooting
│   ├── CHANGES.md            # Dettaglio modifiche con diff
│   ├── DELIVERABLES.md       # Summary completo
│   └── ...
│
├── scripts/                   # 🔧 Script utility
│   ├── run_simlab.sh         # Avvia ICS-SimLab (path assoluti)
│   ├── test_simlab.sh        # Test interattivo
│   └── diagnose_runtime.sh   # Diagnostica
│
├── tools/                     # ⚙️ Generatori
│   ├── compile_ir.py         # IR -> logic/*.py (CON FIX!)
│   ├── make_ir_from_config.py # config.json -> IR
│   ├── generate_logic.py     # Generatore alternativo
│   ├── validate_logic.py     # Validatore
│   └── pipeline.py           # Pipeline end-to-end
│
├── services/                  # 🔄 Pipeline LLM
│   ├── pipeline.py           # Pipeline principale
│   ├── generation.py         # Chiamate LLM
│   ├── patches.py            # Patch automatiche config
│   └── validation/           # Validatori
│
├── models/                    # 📋 Schemi dati
│   ├── ics_simlab_config.py  # Config ICS-SimLab
│   ├── ir_v1.py              # IR (Intermediate Representation)
│   └── schemas/              # JSON Schema
│
├── templates/                 # 📝 Template codice
│   └── tank.py               # Template water tank
│
├── helpers/                   # 🛠️ Utility
│   └── helper.py
│
├── prompts/                   # 💬 Prompt LLM
│   ├── input_testuale.txt    # Input esempio
│   ├── prompt_json_generation.txt
│   └── prompt_repair.txt
│
├── examples/                  # 📦 Esempi riferimento
│   ├── water_tank/
│   ├── smart_grid/
│   └── ied/
│
├── spec/                      # 📖 Specifiche
│   └── ics_simlab_contract.json
│
└── outputs/                   # 🎯 Output generati
    ├── configuration.json    # Config base generata
    ├── ir/                   # IR intermedio
    │   └── ir_v1.json
    └── scenario_run/         # 🚀 SCENARIO FINALE PER ICS-SIMLAB
        ├── configuration.json
        └── logic/
            ├── plc1.py       # ✅ Con _safe_callback
            ├── plc2.py       # ✅ Con _safe_callback
            └── hil_1.py
```

## 🔧 Workflow Completo

### Opzione A: Solo generazione logica (da config esistente)
```bash
# Da configuration.json esistente -> scenario completo
python3 build_scenario.py --config outputs/configuration.json --overwrite
```

### Opzione B: Pipeline completa (da testo)
```bash
# 1. Testo -> configuration.json (LLM)
python3 main.py --input-file prompts/input_testuale.txt

# 2. Config -> scenario completo
python3 build_scenario.py --overwrite

# 3. Valida
python3 validate_fix.py

# 4. Esegui
./scripts/run_simlab.sh
```

### Opzione C: Pipeline manuale step-by-step
```bash
# 1. Config -> IR
python3 -m tools.make_ir_from_config \
    --config outputs/configuration.json \
    --out outputs/ir/ir_v1.json \
    --overwrite

# 2. IR -> logic/*.py
python3 -m tools.compile_ir \
    --ir outputs/ir/ir_v1.json \
    --out-dir outputs/scenario_run/logic \
    --overwrite

# 3. Copia config
cp outputs/configuration.json outputs/scenario_run/

# 4. Valida
python3 -m tools.validate_logic \
    --config outputs/configuration.json \
    --logic-dir outputs/scenario_run/logic \
    --check-callbacks \
    --check-hil-init
```

## 🐛 Fix PLC Startup Race Condition

Il generatore include un fix per il crash di PLC2 all'avvio:

- **Problema**: PLC2 crashava quando scriveva a PLC1 prima che fosse pronto
- **Soluzione**: Retry wrapper `_safe_callback()` in `tools/compile_ir.py`
- **Dettagli**: Vedi `docs/README_FIX.md`

### Verifica Fix
```bash
python3 validate_fix.py
# Output atteso: ✅ SUCCESS: All PLC files have the callback retry fix
```

## 🚀 Esecuzione ICS-SimLab

**IMPORTANTE**: Usa percorsi ASSOLUTI con sudo, non `~`!

```bash
# ✅ CORRETTO
cd /home/stefano/projects/ICS-SimLab-main/curtin-ics-simlab
sudo ./start.sh /home/stefano/projects/ics-simlab-config-gen_claude/outputs/scenario_run

# ❌ SBAGLIATO (sudo non espande ~)
sudo ./start.sh ~/projects/ics-simlab-config-gen_claude/outputs/scenario_run
```

**Oppure usa lo script** (gestisce automaticamente i path):
```bash
./scripts/run_simlab.sh
```

### Monitoraggio
```bash
# Log PLC2 (cercare: NO "Exception in thread" errors)
sudo docker logs $(sudo docker ps --format '{{.Names}}' | grep plc2) -f

# Stop
cd /home/stefano/projects/ICS-SimLab-main/curtin-ics-simlab
sudo ./stop.sh
```

## 📚 Documentazione

- **Quick Start**: `docs/QUICKSTART.txt`
- **Fix Completo**: `docs/README_FIX.md`
- **Troubleshooting**: `docs/RUNTIME_FIX.md`
- **Modifiche**: `docs/CHANGES.md`
- **Comandi Corretti**: `docs/CORRECT_COMMANDS.txt`

## 🔑 Setup Iniziale

```bash
# Crea venv
python3 -m venv .venv
source .venv/bin/activate

# Installa dipendenze (se necessario)
pip install openai python-dotenv pydantic

# Configura API key
echo "OPENAI_API_KEY=sk-..." > .env
```

## 🎯 File Chiave

- `tools/compile_ir.py` - **Generatore PLC logic (CON FIX)**
- `build_scenario.py` - **Builder scenario deterministico**
- `validate_fix.py` - **Validatore fix**
- `outputs/scenario_run/` - **Scenario finale per ICS-SimLab**

## ⚠️ Note Importanti

1. **Sempre usare `.venv/bin/python3`** per assicurare venv corretto
2. **Percorsi assoluti con sudo** (no `~`)
3. **Rebuild scenario** dopo modifiche a config: `python3 build_scenario.py --overwrite`
4. **Validare sempre** dopo rebuild: `python3 validate_fix.py`

## 📝 TODO / Roadmap

- [ ] Supporto per più modelli (oltre "tank")
- [ ] Generazione automatica HMI
- [ ] Parametri retry configurabili
- [ ] Test automatizzati end-to-end

## 📄 Licenza

Tesi Stefano D'Orazio - OT Security

---

**Status**: ✅ Production Ready
**Last Update**: 2026-01-27