# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Purpose

This repository generates runnable Curtin ICS-SimLab scenarios from textual descriptions. It produces:
- `configuration.json` compatible with Curtin ICS-SimLab
- `logic/*.py` files implementing PLC control logic and HIL process physics

**Hard boundary**: Do NOT modify the Curtin ICS-SimLab repository. Only change files inside this repository.

## Common Commands

```bash
# Activate virtual environment
source .venv/bin/activate

# Generate configuration.json from text input (requires OPENAI_API_KEY in .env)
python3 main.py --input-file prompts/input_testuale.txt

# Build complete scenario (config -> IR -> logic)
python3 build_scenario.py --out outputs/scenario_run --overwrite

# Validate PLC callback retry fix is present
python3 validate_fix.py

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

# Run scenario in ICS-SimLab (use ABSOLUTE paths with sudo)
cd /home/stefano/projects/ICS-SimLab-main/curtin-ics-simlab
sudo ./start.sh /home/stefano/projects/ics-simlab-config-gen_claude/outputs/scenario_run
```

## Architecture

The pipeline follows a deterministic approach:

```
text input -> LLM -> configuration.json -> IR (ir_v1.json) -> logic/*.py
```

### Key Components

**Entry Points:**
- `main.py` - LLM-based generation: text -> configuration.json
- `build_scenario.py` - Orchestrates full build: config -> IR -> logic (calls tools/*.py)

**IR Pipeline (tools/):**
- `make_ir_from_config.py` - Extracts IR from configuration.json using keyword-based heuristics
- `compile_ir.py` - Deterministic compiler: IR -> Python logic files (includes `_safe_callback` fix)
- `validate_logic.py` - Validates generated logic against config

**Models (models/):**
- `ics_simlab_config.py` - Pydantic models for configuration.json (PLC, HIL, registers)
- `ir_v1.py` - Intermediate Representation: `IRSpec` contains `IRPLC` (rules) and `IRHIL` (blocks)

**LLM Pipeline (services/):**
- `pipeline.py` - Generate -> validate -> repair loop
- `generation.py` - OpenAI API calls
- `patches.py` - Auto-fix common config issues
- `validation/` - Validators for config, PLC callbacks, HIL initialization

## ICS-SimLab Contract

### PLC Logic

File referenced by `plcs[].logic` becomes `src/logic.py` in container.

Required signature:
```python
def logic(input_registers, output_registers, state_update_callbacks):
```

Rules:
- Read only registers with `io: "input"` (from `input_registers`)
- Write only registers with `io: "output"` (to `output_registers`)
- After EVERY write to an output register, call `state_update_callbacks[id]()`
- Access by logical `id`/`name`, never by Modbus address

### HIL Logic

File referenced by `hils[].logic` becomes `src/logic.py` in container.

Required signature:
```python
def logic(physical_values):
```

Rules:
- Initialize ALL keys declared in `hils[].physical_values`
- Update only keys marked as `io: "output"`

## Known Runtime Pitfall

PLC startup race condition: PLC2 can crash when writing to PLC1 before it's ready (`ConnectionRefusedError`).

**Solution implemented in `tools/compile_ir.py`**: The `_safe_callback()` wrapper retries failed callbacks with exponential backoff (30 attempts x 0.2s).

Always validate after rebuilding:
```bash
python3 validate_fix.py
```

## IR System

The IR (Intermediate Representation) enables deterministic code generation.

**PLC Rules** (`models/ir_v1.py`):
- `HysteresisFillRule` - Tank level control with low/high thresholds
- `ThresholdOutputRule` - Simple threshold-based output

**HIL Blocks** (`models/ir_v1.py`):
- `TankLevelBlock` - Water tank dynamics (level, inlet, outlet)
- `BottleLineBlock` - Conveyor + bottle fill simulation

To add new process physics: create a structured spec (not free-form Python via LLM), then add a deterministic compiler.

## Project Notes (appunti.txt)

Maintain `appunti.txt` in the repo root with bullet points (in Italian) documenting:
- Important discoveries about the repo or runtime
- Code changes, validations, generation behavior modifications
- Root causes of bugs
- Verification commands used

Include `appunti.txt` in diffs when updated.

## Validation Rules

Validators catch:
- PLC callback invoked after each output write
- HIL initializes all declared physical_values keys
- HIL updates only `io: "output"` keys
- No reads from output-only registers, no writes to input-only registers
- No missing IDs referenced by generated code

Prefer adding a validator over adding generation complexity when a runtime crash is possible.

## Research-Plan-Implement Framework

This repository uses the Research-Plan-Implement framework with the following workflow commands:

1. `/1_research_codebase` - Deep codebase exploration with parallel AI agents
2. `/2_create_plan` - Create detailed, phased implementation plans
3. `/3_validate_plan` - Verify implementation matches plan
4. `/4_implement_plan` - Execute plan systematically
5. `/5_save_progress` - Save work session state
6. `/6_resume_work` - Resume from saved session
7. `/7_research_cloud` - Analyze cloud infrastructure (READ-ONLY)

Research findings are saved in `thoughts/shared/research/`
Implementation plans are saved in `thoughts/shared/plans/`
Session summaries are saved in `thoughts/shared/sessions/`
Cloud analyses are saved in `thoughts/shared/cloud/`