161 lines
5.4 KiB
Markdown
161 lines
5.4 KiB
Markdown
# 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/`
|