# shalikadulaj/multi-agent-ai-hybrid-truck architecture

> Architecture diagram of the GitHub repository shalikadulaj/multi-agent-ai-hybrid-truck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shalikadulaj/multi-agent-ai-hybrid-truck
- Repository: https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck

## Overview

This is a research prototype for energy management of an assumed P4 heavy-duty hybrid truck. Its primary workflow is CLI invocation → tabular Q-learning training or saved-policy evaluation → held-out mission benchmarking and CSV/model artifacts. A separate, hand-coded multi-agent simulation provides supervisory, powertrain, battery, driver-assistance, and performance layers; README distinguishes its legacy heuristic from the learned Q policy. The sampled excerpts support only selected internal calls, so documented but unsampled capabilities are included with README-backed relationships.

Main entry points: [`src/multi_agent_ai/rl_training.py`](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py) (Training workflow), [`src/multi_agent_ai/agents.py`](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py) (Agent orchestrator), [`src/multi_agent_ai/main.py`](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/main.py) (CLI entry), [`artifacts`](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/tree/main/artifacts) (Policy and results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment entry"]
  node_cli["CLI entry<br/>[main.py]"]
end

subgraph group_learning["RL experiment"]
  node_trainer["Training workflow<br/>[rl_training.py]"]
  node_route["Duty-cycle generation<br/>[rl_training.py]"]
  node_plant["P4 plant transition<br/>[rl_training.py]"]
  node_qlearn["Q-table learning<br/>[rl_training.py]"]
  node_qpolicy["Learned EMS policy<br/>[rl_training.py]"]
  node_rule["Rule baseline<br/>[rl_training.py]"]
  node_engineonly["Engine-only baseline<br/>[rl_training.py]"]
end

subgraph group_control["Multi-agent control"]
  node_orchestrator["Agent orchestrator<br/>[agents.py]"]
  node_mission["Mission supervisor<br/>[agents.py]"]
  node_powertrain["Powertrain policy<br/>[agents.py]"]
  node_pedals["Pedal demand model<br/>[agents.py]"]
  node_battery["Battery health limits<br/>[agents.py]"]
  node_driver["Driver assistance<br/>[agents.py]"]
  node_performance["Performance layer<br/>[agents.py]"]
  node_reward["Sustainability reward<br/>[agents.py]"]
end

subgraph group_reporting["Evaluation and outputs"]
  node_evaluation["Held-out evaluation<br/>[rl_training.py]"]
  node_metrics["Benchmark metrics<br/>[rl_training.py]"]
  node_artifacts[("Policy and results")]
end

node_operator(("Researcher"))

node_operator -->|"invokes"| node_cli
node_cli -->|"delegates"| node_trainer
node_trainer -->|"generates routes"| node_route
node_trainer -->|"trains"| node_qlearn
node_qlearn -->|"steps environment"| node_plant
node_qlearn -->|"uses cycles"| node_route
node_qpolicy -.->|"selects actions"| node_plant
node_evaluation -.->|"evaluates"| node_qpolicy
node_evaluation -->|"compares"| node_rule
node_evaluation -->|"compares"| node_engineonly
node_evaluation -->|"reports metrics"| node_metrics
node_trainer -->|"benchmarks"| node_evaluation
node_trainer -->|"writes outputs"| node_artifacts
node_orchestrator -->|"coordinates"| node_mission
node_powertrain -->|"computes demand"| node_pedals
node_powertrain -->|"requests limits"| node_battery
node_orchestrator -.->|"coordinates"| node_powertrain
node_orchestrator -->|"coordinates"| node_driver
node_orchestrator -.->|"coordinates"| node_performance
node_performance -.->|"evaluates reward"| node_reward
node_mission -->|"sets safety objectives"| node_battery
node_mission -->|"sets mission objectives"| node_powertrain

click node_cli "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/main.py"
click node_trainer "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_route "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_plant "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_qlearn "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_qpolicy "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_rule "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_engineonly "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_evaluation "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_metrics "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py"
click node_artifacts "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/tree/main/artifacts"
click node_orchestrator "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_mission "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_powertrain "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_pedals "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_battery "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_driver "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_performance "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py"
click node_reward "https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.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_cli toneBlue
class node_trainer,node_route,node_plant,node_qlearn,node_qpolicy,node_rule,node_engineonly toneAmber
class node_orchestrator,node_mission,node_powertrain,node_pedals,node_battery,node_driver,node_performance,node_reward toneMint
class node_evaluation,node_metrics,node_artifacts toneRose
class node_operator toneIndigo
```

## Components

### Experiment entry

- [CLI entry](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/main.py): `src/multi_agent_ai/main.py`

### RL experiment

- [Training workflow](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Duty-cycle generation](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [P4 plant transition](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Q-table learning](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Learned EMS policy](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Rule baseline](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Engine-only baseline](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`

### Multi-agent control

- [Agent orchestrator](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Mission supervisor](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Powertrain policy](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Pedal demand model](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Battery health limits](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Driver assistance](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Performance layer](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`
- [Sustainability reward](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/agents.py): `src/multi_agent_ai/agents.py`

### Evaluation and outputs

- [Held-out evaluation](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Benchmark metrics](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/blob/main/src/multi_agent_ai/rl_training.py): `src/multi_agent_ai/rl_training.py`
- [Policy and results](https://github.com/shalikadulaj/multi-agent-ai-hybrid-truck/tree/main/artifacts): `artifacts`

### Other components

- **Researcher**

## Connections

- Researcher → CLI entry: invokes (evidence: `README.md`)
- CLI entry → Training workflow: delegates (evidence: `src/multi_agent_ai/main.py`)
- Training workflow → Duty-cycle generation: generates routes (evidence: `src/multi_agent_ai/rl_training.py`)
- Training workflow → Q-table learning: trains (evidence: `src/multi_agent_ai/rl_training.py`)
- Q-table learning → P4 plant transition: steps environment (evidence: `src/multi_agent_ai/rl_training.py`)
- Q-table learning → Duty-cycle generation: uses cycles (evidence: `src/multi_agent_ai/rl_training.py`)
- Learned EMS policy → P4 plant transition: selects actions (evidence: `src/multi_agent_ai/rl_training.py`)
- Held-out evaluation → Learned EMS policy: evaluates (evidence: `src/multi_agent_ai/rl_training.py`)
- Held-out evaluation → Rule baseline: compares (evidence: `README.md`)
- Held-out evaluation → Engine-only baseline: compares (evidence: `README.md`)
- Held-out evaluation → Benchmark metrics: reports metrics (evidence: `README.md`)
- Training workflow → Held-out evaluation: benchmarks (evidence: `README.md`)
- Training workflow → Policy and results: writes outputs (evidence: `README.md`)
- Agent orchestrator → Mission supervisor: coordinates (evidence: `src/multi_agent_ai/agents.py`)
- Powertrain policy → Pedal demand model: computes demand (evidence: `src/multi_agent_ai/agents.py`)
- Powertrain policy → Battery health limits: requests limits (evidence: `src/multi_agent_ai/agents.py`)
- Agent orchestrator → Powertrain policy: coordinates (evidence: `src/multi_agent_ai/agents.py`)
- Agent orchestrator → Driver assistance: coordinates (evidence: `README.md`)
- Agent orchestrator → Performance layer: coordinates (evidence: `src/multi_agent_ai/agents.py`)
- Performance layer → Sustainability reward: evaluates reward (evidence: `src/multi_agent_ai/agents.py`)
- Mission supervisor → Battery health limits: sets safety objectives (evidence: `README.md`)
- Mission supervisor → Powertrain policy: sets mission objectives (evidence: `README.md`)
