# 8ohamed/incubator-llm architecture

> Architecture diagram of the GitHub repository 8ohamed/incubator-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/8ohamed/incubator-llm
- Repository: https://github.com/8ohamed/incubator-llm

## Overview

This is an incubator advisory digital twin for predicting the effect of opening a tempeh incubator lid. The main workflow reads and validates the current incubator state, simulates the temperature trajectory, then assesses batch risk and reports a verdict. A separate heater-boost workflow searches for a setpoint-and-wait plan when the opening is high risk; plotting visualizes simulation output without making a verdict. The graph follows the README and indexed references; some implementation details for CLI and plotting are unsampled.

Main entry points: [`tools/simulate.py`](https://github.com/8ohamed/incubator-llm/blob/main/tools/simulate.py) (Lid simulation), [`tools/heater_boost.py`](https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost.py) (Boost planner), [`tools/cli.py`](https://github.com/8ohamed/incubator-llm/blob/main/tools/cli.py) (Opening CLI), [`tools/analyze.py`](https://github.com/8ohamed/incubator-llm/blob/main/tools/analyze.py) (Risk assessment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Operator interfaces"]
  node_lid_cli["Opening CLI<br/>[cli.py]"]
  node_boost_cli["Boost CLI"]
  node_plotter["Trajectory plot<br/>[plot_simulation.py]"]
  node_plot_result["Simulation plot"]
end

subgraph group_twin["Incubator twin"]
  node_simulator["Lid simulation<br/>[simulate.py]"]
  node_boost_simulator["Boosted simulation"]
  node_controller["Incubator controller"]
  node_controller_sm["Controller state machine"]
  node_four_plant["Four-parameter plant"]
  node_two_plant["Two-parameter plant base"]
end

subgraph group_advisory["Risk and planning"]
  node_risk_assessment["Risk assessment<br/>[analyze.py]"]
  node_boost_search["Boost planner<br/>[heater_boost.py]"]
  node_verdict["Risk verdict and advice"]
  node_boost_plan["Boost plan or limits"]
end

subgraph group_knowledge["State and domain data"]
  node_state_reader["State reader<br/>[state.py]"]
  node_current_state["Current state<br/>[current_state.json]"]
  node_thresholds["Tempeh thresholds"]
  node_domain_rules["Domain knowledge"]
end

node_operator(("Operator"))

node_operator -->|"asks about opening"| node_lid_cli
node_lid_cli -->|"runs simulation"| node_simulator
node_lid_cli -->|"requests assessment"| node_risk_assessment
node_lid_cli -->|"loads state"| node_state_reader
node_state_reader -->|"reads and validates"| node_current_state
node_simulator -->|"loads state"| node_state_reader
node_simulator -->|"wires controller"| node_controller
node_simulator -->|"wires plant"| node_four_plant
node_controller -->|"delegates steps"| node_controller_sm
node_four_plant -->|"inherits equations"| node_two_plant
node_risk_assessment -->|"applies thresholds"| node_domain_rules
node_domain_rules -->|"reads definitions"| node_thresholds
node_risk_assessment -->|"returns verdict"| node_verdict
node_operator -->|"requests boost plan"| node_boost_cli
node_boost_cli -->|"runs search"| node_boost_search
node_boost_search -->|"checks unboosted case"| node_simulator
node_boost_search -->|"judges candidates"| node_risk_assessment
node_boost_search -->|"simulates candidates"| node_boost_simulator
node_boost_simulator -->|"schedules setpoint"| node_controller_sm
node_boost_search -->|"returns plan or limit"| node_boost_plan
node_operator -->|"requests visualization"| node_plotter
node_plotter -->|"plots simulation output"| node_simulator
node_plotter -->|"draws trajectory"| node_plot_result
node_verdict -->|"explains risk"| node_operator
node_boost_plan -->|"returns instructions"| node_operator

click node_lid_cli "https://github.com/8ohamed/incubator-llm/blob/main/tools/cli.py"
click node_boost_cli "https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost_cli.py"
click node_plotter "https://github.com/8ohamed/incubator-llm/blob/main/tools/plot_simulation.py"
click node_state_reader "https://github.com/8ohamed/incubator-llm/blob/main/tools/state.py"
click node_current_state "https://github.com/8ohamed/incubator-llm/blob/main/state/current_state.json"
click node_thresholds "https://github.com/8ohamed/incubator-llm/blob/main/domain_knowledge/tempeh_thresholds.json"
click node_domain_rules "https://github.com/8ohamed/incubator-llm/blob/main/tools/domain_knowledge.py"
click node_simulator "https://github.com/8ohamed/incubator-llm/blob/main/tools/simulate.py"
click node_boost_simulator "https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost_simulate.py"
click node_controller "https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/controller_models/controller_model4.py"
click node_controller_sm "https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/controller_models/controller_model_sm.py"
click node_four_plant "https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/plant_models/four_parameters_model/four_parameter_model.py"
click node_two_plant "https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/plant_models/two_parameters_model/two_parameter_model.py"
click node_risk_assessment "https://github.com/8ohamed/incubator-llm/blob/main/tools/analyze.py"
click node_boost_search "https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lid_cli,node_boost_cli,node_plotter,node_plot_result toneBlue
class node_simulator,node_boost_simulator,node_controller,node_controller_sm,node_four_plant,node_two_plant toneAmber
class node_risk_assessment,node_boost_search,node_verdict,node_boost_plan toneMint
class node_state_reader,node_current_state,node_thresholds,node_domain_rules toneRose
class node_operator toneIndigo
```

## Components

### Operator interfaces

- [Opening CLI](https://github.com/8ohamed/incubator-llm/blob/main/tools/cli.py): `tools/cli.py`
- [Boost CLI](https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost_cli.py): `tools/heater_boost_cli.py`
- [Trajectory plot](https://github.com/8ohamed/incubator-llm/blob/main/tools/plot_simulation.py): `tools/plot_simulation.py`
- **Simulation plot**

### Incubator twin

- [Lid simulation](https://github.com/8ohamed/incubator-llm/blob/main/tools/simulate.py): `tools/simulate.py`
- [Boosted simulation](https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost_simulate.py): `tools/heater_boost_simulate.py`
- [Incubator controller](https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/controller_models/controller_model4.py): `incubator_dt/models/controller_models/controller_model4.py`
- [Controller state machine](https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/controller_models/controller_model_sm.py): `incubator_dt/models/controller_models/controller_model_sm.py`
- [Four-parameter plant](https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/plant_models/four_parameters_model/four_parameter_model.py): `incubator_dt/models/plant_models/four_parameters_model/four_parameter_model.py`
- [Two-parameter plant base](https://github.com/8ohamed/incubator-llm/blob/main/incubator_dt/models/plant_models/two_parameters_model/two_parameter_model.py): `incubator_dt/models/plant_models/two_parameters_model/two_parameter_model.py`

### Risk and planning

- [Risk assessment](https://github.com/8ohamed/incubator-llm/blob/main/tools/analyze.py): `tools/analyze.py`
- [Boost planner](https://github.com/8ohamed/incubator-llm/blob/main/tools/heater_boost.py): `tools/heater_boost.py`
- **Risk verdict and advice**
- **Boost plan or limits**

### State and domain data

- [State reader](https://github.com/8ohamed/incubator-llm/blob/main/tools/state.py): `tools/state.py`
- [Current state](https://github.com/8ohamed/incubator-llm/blob/main/state/current_state.json): `state/current_state.json`
- [Tempeh thresholds](https://github.com/8ohamed/incubator-llm/blob/main/domain_knowledge/tempeh_thresholds.json): `domain_knowledge/tempeh_thresholds.json`
- [Domain knowledge](https://github.com/8ohamed/incubator-llm/blob/main/tools/domain_knowledge.py): `tools/domain_knowledge.py`

### Other components

- **Operator**

## Connections

- Operator → Opening CLI: asks about opening (evidence: `README.md`)
- Opening CLI → Lid simulation: runs simulation (evidence: `tools/cli.py`)
- Opening CLI → Risk assessment: requests assessment (evidence: `tools/cli.py`)
- Opening CLI → State reader: loads state (evidence: `tools/cli.py`)
- State reader → Current state: reads and validates (evidence: `tools/state.py`)
- Lid simulation → State reader: loads state (evidence: `tools/simulate.py`)
- Lid simulation → Incubator controller: wires controller (evidence: `tools/simulate.py`)
- Lid simulation → Four-parameter plant: wires plant (evidence: `tools/simulate.py`)
- Incubator controller → Controller state machine: delegates steps (evidence: `incubator_dt/models/controller_models/controller_model4.py`)
- Four-parameter plant → Two-parameter plant base: inherits equations (evidence: `incubator_dt/models/plant_models/four_parameters_model/four_parameter_model.py`)
- Risk assessment → Domain knowledge: applies thresholds (evidence: `tools/analyze.py`)
- Domain knowledge → Tempeh thresholds: reads definitions (evidence: `tools/domain_knowledge.py`)
- Risk assessment → Risk verdict and advice: returns verdict (evidence: `tools/analyze.py`)
- Operator → Boost CLI: requests boost plan (evidence: `README.md`)
- Boost CLI → Boost planner: runs search (evidence: `tools/heater_boost_cli.py`)
- Boost planner → Lid simulation: checks unboosted case (evidence: `tools/heater_boost.py`)
- Boost planner → Risk assessment: judges candidates (evidence: `tools/heater_boost.py`)
- Boost planner → Boosted simulation: simulates candidates (evidence: `tools/heater_boost.py`)
- Boosted simulation → Controller state machine: schedules setpoint (evidence: `tools/heater_boost_simulate.py`)
- Boost planner → Boost plan or limits: returns plan or limit (evidence: `tools/heater_boost.py`)
- Operator → Trajectory plot: requests visualization (evidence: `README.md`)
- Trajectory plot → Lid simulation: plots simulation output (evidence: `tools/plot_simulation.py`)
- Trajectory plot → Simulation plot: draws trajectory (evidence: `tools/plot_simulation.py`)
- Risk verdict and advice → Operator: explains risk (evidence: `README.md`)
- Boost plan or limits → Operator: returns instructions (evidence: `README.md`)