# maheshks74/ecotwin_ai architecture

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

- Interactive diagram: https://gitdiagram.com/maheshks74/ecotwin_ai
- Repository: https://github.com/maheshks74/ecotwin_ai

## Overview

EcoTwin’s main workflow is an operator using the dashboard to inspect plant telemetry and compare or direct energy-aware production. The Gymnasium environment combines tariffs, weather, and scenarios with a simulated factory; controllers choose machine and HVAC actions, and evaluation summarizes cost, peak demand, and quota outcomes. Separate branches provide preference-based reward learning and an LLM advisor/directive compiler. The README documents these capabilities; some dashboard and evaluation connections below are documented rather than verified from implementation excerpts.

Main entry points: [`ecotwin/evaluation/run_eval.py`](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/run_eval.py) (Benchmark runner), [`ecotwin/env/ecotwin_env.py`](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/env/ecotwin_env.py) (Gymnasium environment), [`dashboard/app.py`](https://github.com/maheshks74/ecotwin_ai/blob/main/dashboard/app.py) (Streamlit dashboard), [`ecotwin/twin/factory.py`](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/factory.py) (Factory floor simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Operational Inputs"]
  node_tariffs["Tariff manager<br/>[tariff.py]"]
  node_weather["Weather manager<br/>[weather.py]"]
  node_scenarios["Scenario manager<br/>[scenarios.py]"]
end

subgraph group_simulation["Plant Simulation"]
  node_factory["Factory floor simulator<br/>[factory.py]"]
  node_machines["Production machines<br/>[machines.py]"]
  node_hvac["HVAC thermal zones<br/>[hvac.py]"]
  node_jobs["Job queue<br/>[jobs.py]"]
end

subgraph group_control["Control and Learning"]
  node_environment["Gymnasium environment<br/>[ecotwin_env.py]"]
  node_fixed["Fixed controller<br/>[fixed.py]"]
  node_rules["Rule-based controller<br/>[rule_based.py]"]
  node_ppo["Hand-reward PPO<br/>[ppo_train.py]"]
  node_ppo_pref["Preference PPO<br/>[ppo_pref.py]"]
  node_manager["Simulated manager"]
  node_pairs["Trajectory pair generator<br/>[pair_generator.py]"]
  node_reward["Preference reward model<br/>[reward_model.py]"]
end

subgraph group_insight["Evaluation and Advice"]
  node_evaluation["Benchmark runner<br/>[run_eval.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_plots["Evaluation plots<br/>[plots.py]"]
  node_logger["Telemetry logger<br/>[logger.py]"]
  node_advisor["LLM operations advisor<br/>[advisor.py]"]
  node_parser["Directive parser"]
  node_gemini["Gemini client<br/>[client.py]"]
end

subgraph group_interface["Operator Interface"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
end

node_operator(("Plant operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"runs simulations"| node_environment
node_dashboard -->|"shows benchmarks"| node_evaluation
node_dashboard -->|"offers Q&amp;A"| node_advisor
node_dashboard -->|"compiles directives"| node_parser
node_environment -->|"advances simulation"| node_factory
node_environment -->|"reads prices"| node_tariffs
node_environment -->|"reads forecasts"| node_weather
node_environment -->|"builds scenario"| node_scenarios
node_environment -.->|"accepts actions from"| node_fixed
node_environment -.->|"accepts actions from"| node_rules
node_environment -->|"trains policy on"| node_ppo
node_factory -->|"builds"| node_machines
node_factory -->|"builds"| node_hvac
node_factory -->|"creates queue"| node_jobs
node_scenarios -->|"adds scenario jobs"| node_jobs
node_evaluation -->|"runs episodes"| node_environment
node_evaluation -->|"benchmarks"| node_fixed
node_evaluation -->|"benchmarks"| node_rules
node_evaluation -->|"benchmarks"| node_ppo
node_evaluation -->|"benchmarks"| node_ppo_pref
node_evaluation -->|"creates preferences"| node_manager
node_evaluation -->|"generates comparisons"| node_pairs
node_evaluation -->|"trains model"| node_reward
node_evaluation -->|"summarizes results"| node_metrics
node_evaluation -->|"generates figures"| node_plots
node_evaluation -->|"logs telemetry"| node_logger
node_pairs -->|"compares trajectories"| node_manager
node_reward -->|"uses trajectory type"| node_manager
node_ppo_pref -.->|"uses learned reward"| node_reward
node_logger -->|"reads floor state"| node_factory
node_advisor -->|"requests responses"| node_gemini
node_parser -->|"requests parsing"| node_gemini
node_advisor -->|"grounds answers in telemetry"| node_logger
node_dashboard -->|"replays telemetry"| node_logger

click node_dashboard "https://github.com/maheshks74/ecotwin_ai/blob/main/dashboard/app.py"
click node_environment "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/env/ecotwin_env.py"
click node_tariffs "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/data/tariff.py"
click node_weather "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/data/weather.py"
click node_scenarios "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/data/scenarios.py"
click node_factory "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/factory.py"
click node_machines "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/machines.py"
click node_hvac "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/hvac.py"
click node_jobs "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/jobs.py"
click node_fixed "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/fixed.py"
click node_rules "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/rule_based.py"
click node_ppo "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/ppo_train.py"
click node_ppo_pref "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/ppo_pref.py"
click node_manager "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/preference/simulated_manager.py"
click node_pairs "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/preference/pair_generator.py"
click node_reward "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/preference/reward_model.py"
click node_evaluation "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/run_eval.py"
click node_metrics "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/metrics.py"
click node_plots "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/plots.py"
click node_logger "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/logger.py"
click node_advisor "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/advisor.py"
click node_parser "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/instruction_parser.py"
click node_gemini "https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/client.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_tariffs,node_weather,node_scenarios toneBlue
class node_factory,node_machines,node_hvac,node_jobs toneAmber
class node_environment,node_fixed,node_rules,node_ppo,node_ppo_pref,node_manager,node_pairs,node_reward toneMint
class node_evaluation,node_metrics,node_plots,node_logger,node_advisor,node_parser,node_gemini toneRose
class node_dashboard,node_operator toneIndigo
```

## Components

### Operational Inputs

- [Tariff manager](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/data/tariff.py): `ecotwin/data/tariff.py`
- [Weather manager](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/data/weather.py): `ecotwin/data/weather.py`
- [Scenario manager](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/data/scenarios.py): `ecotwin/data/scenarios.py`

### Plant Simulation

- [Factory floor simulator](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/factory.py): `ecotwin/twin/factory.py`
- [Production machines](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/machines.py): `ecotwin/twin/machines.py`
- [HVAC thermal zones](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/hvac.py): `ecotwin/twin/hvac.py`
- [Job queue](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/twin/jobs.py): `ecotwin/twin/jobs.py`

### Control and Learning

- [Gymnasium environment](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/env/ecotwin_env.py): `ecotwin/env/ecotwin_env.py`
- [Fixed controller](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/fixed.py): `ecotwin/controllers/fixed.py`
- [Rule-based controller](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/rule_based.py): `ecotwin/controllers/rule_based.py`
- [Hand-reward PPO](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/ppo_train.py): `ecotwin/controllers/ppo_train.py`
- [Preference PPO](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/controllers/ppo_pref.py): `ecotwin/controllers/ppo_pref.py`
- [Simulated manager](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/preference/simulated_manager.py): `ecotwin/preference/simulated_manager.py`
- [Trajectory pair generator](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/preference/pair_generator.py): `ecotwin/preference/pair_generator.py`
- [Preference reward model](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/preference/reward_model.py): `ecotwin/preference/reward_model.py`

### Evaluation and Advice

- [Benchmark runner](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/run_eval.py): `ecotwin/evaluation/run_eval.py`
- [Evaluation metrics](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/metrics.py): `ecotwin/evaluation/metrics.py`
- [Evaluation plots](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/evaluation/plots.py): `ecotwin/evaluation/plots.py`
- [Telemetry logger](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/logger.py): `ecotwin/llm/logger.py`
- [LLM operations advisor](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/advisor.py): `ecotwin/llm/advisor.py`
- [Directive parser](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/instruction_parser.py): `ecotwin/llm/instruction_parser.py`
- [Gemini client](https://github.com/maheshks74/ecotwin_ai/blob/main/ecotwin/llm/client.py): `ecotwin/llm/client.py`

### Operator Interface

- [Streamlit dashboard](https://github.com/maheshks74/ecotwin_ai/blob/main/dashboard/app.py): `dashboard/app.py`

### Other components

- **Plant operator**

## Connections

- Plant operator → Streamlit dashboard: uses (evidence: `README.md`)
- Streamlit dashboard → Gymnasium environment: runs simulations (evidence: `README.md`)
- Streamlit dashboard → Benchmark runner: shows benchmarks (evidence: `README.md`)
- Streamlit dashboard → LLM operations advisor: offers Q&A (evidence: `README.md`)
- Streamlit dashboard → Directive parser: compiles directives (evidence: `README.md`)
- Gymnasium environment → Factory floor simulator: advances simulation (evidence: `ecotwin/env/ecotwin_env.py`)
- Gymnasium environment → Tariff manager: reads prices (evidence: `ecotwin/env/ecotwin_env.py`)
- Gymnasium environment → Weather manager: reads forecasts (evidence: `ecotwin/env/ecotwin_env.py`)
- Gymnasium environment → Scenario manager: builds scenario (evidence: `ecotwin/env/ecotwin_env.py`)
- Gymnasium environment → Fixed controller: accepts actions from (evidence: `README.md`)
- Gymnasium environment → Rule-based controller: accepts actions from (evidence: `README.md`)
- Gymnasium environment → Hand-reward PPO: trains policy on (evidence: `ecotwin/controllers/ppo_train.py`)
- Factory floor simulator → Production machines: builds (evidence: `ecotwin/twin/factory.py`)
- Factory floor simulator → HVAC thermal zones: builds (evidence: `ecotwin/twin/factory.py`)
- Factory floor simulator → Job queue: creates queue (evidence: `ecotwin/twin/factory.py`)
- Scenario manager → Job queue: adds scenario jobs (evidence: `ecotwin/data/scenarios.py`)
- Benchmark runner → Gymnasium environment: runs episodes (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Fixed controller: benchmarks (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Rule-based controller: benchmarks (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Hand-reward PPO: benchmarks (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Preference PPO: benchmarks (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Simulated manager: creates preferences (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Trajectory pair generator: generates comparisons (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Preference reward model: trains model (evidence: `ecotwin/evaluation/run_eval.py`)
- Benchmark runner → Evaluation metrics: summarizes results (evidence: `README.md`)
- Benchmark runner → Evaluation plots: generates figures (evidence: `README.md`)
- Benchmark runner → Telemetry logger: logs telemetry (evidence: `ecotwin/evaluation/run_eval.py`)
- Trajectory pair generator → Simulated manager: compares trajectories (evidence: `ecotwin/preference/pair_generator.py`)
- Preference reward model → Simulated manager: uses trajectory type (evidence: `ecotwin/preference/reward_model.py`)
- Preference PPO → Preference reward model: uses learned reward (evidence: `README.md`)
- Telemetry logger → Factory floor simulator: reads floor state (evidence: `ecotwin/llm/logger.py`)
- LLM operations advisor → Gemini client: requests responses (evidence: `ecotwin/llm/advisor.py`)
- Directive parser → Gemini client: requests parsing (evidence: `ecotwin/llm/instruction_parser.py`)
- LLM operations advisor → Telemetry logger: grounds answers in telemetry (evidence: `README.md`)
- Streamlit dashboard → Telemetry logger: replays telemetry (evidence: `README.md`)
