# throddy/diesel-mas architecture

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

- Interactive diagram: https://gitdiagram.com/throddy/diesel-mas
- Repository: https://github.com/throddy/diesel-mas

## Overview

diesel-mas is an advisory decision-support system for forecasting hydrotreated diesel sulfur and recommending operating adjustments; it does not write to process control. The operator-facing workflow assembles plant and laboratory data, assesses data quality and product quality, evaluates feasible actions, applies safety and reliability checks, and presents an explanation for the technologist. The graph reflects the README and indexed source references; where implementation excerpts were unavailable, relationships are included only when documented or visible in the index.

Main entry points: [`src/pipeline.py`](https://github.com/throddy/diesel-mas/blob/main/src/pipeline.py) (System assembly), [`src/agents/orchestrator.py`](https://github.com/throddy/diesel-mas/blob/main/src/agents/orchestrator.py) (Decision orchestration), [`src/agents/quality_agent.py`](https://github.com/throddy/diesel-mas/blob/main/src/agents/quality_agent.py) (Quality assessment), [`src/agents/optimization_agent.py`](https://github.com/throddy/diesel-mas/blob/main/src/agents/optimization_agent.py) (Action generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and features"]
  node_rawdata[("Plant data sources")]
  node_loaders["Data loading<br/>[loaders.py]"]
  node_datastore[("Prepared data store<br/>[store.py]")]
  node_alignment["Time alignment<br/>[alignment.py]"]
  node_dataset["Feature dataset<br/>[dataset.py]"]
  node_processfeatures["Process features"]
  node_qualityfeatures["Quality features"]
end

subgraph group_forecast["Quality forecasting"]
  node_qualitymodel["Sulfur forecast<br/>[quality.py]"]
  node_horizons["Horizon forecasts<br/>[horizons.py]"]
  node_softsensors["Soft sensors<br/>[soft_sensors.py]"]
end

subgraph group_agents["Decision agents"]
  node_schemas["Agent contracts<br/>[schemas.py]"]
  node_dataquality["Data quality checks"]
  node_qualityagent["Quality assessment<br/>[quality_agent.py]"]
  node_reliability["Reliability assessment"]
  node_optimization["Action generation"]
  node_safety["Safety review<br/>[safety_agent.py]"]
  node_whatif["What-if assessment<br/>[whatif_agent.py]"]
  node_orchestrator["Decision orchestration<br/>[orchestrator.py]"]
  node_bus["Agent message bus<br/>[bus.py]"]
  node_explainer["Recommendation explanation<br/>[explainer_agent.py]"]
end

subgraph group_decision["Action evaluation"]
  node_candidates["Action candidates<br/>[candidates.py]"]
  node_constraints["Feasibility constraints<br/>[constraints.py]"]
  node_expectedloss["Expected loss<br/>[expected_loss.py]"]
end

subgraph group_interface["Operator interface"]
  node_app["Decision UI<br/>[app.py]"]
  node_pipeline["System assembly<br/>[pipeline.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_operator(("Operator"))

node_operator -->|"requests decision"| node_app
node_app -->|"builds system"| node_pipeline
node_pipeline -->|"loads settings"| node_config
node_rawdata -->|"provides measurements"| node_loaders
node_pipeline -->|"loads prepared data"| node_datastore
node_loaders -->|"reads prepared data"| node_datastore
node_pipeline -->|"loads data"| node_loaders
node_pipeline -->|"assembles agent"| node_dataquality
node_pipeline -->|"assembles agent"| node_qualityagent
node_pipeline -->|"assembles agent"| node_reliability
node_pipeline -->|"assembles agent"| node_optimization
node_pipeline -->|"assembles agent"| node_safety
node_pipeline -->|"assembles agent"| node_whatif
node_pipeline -->|"assembles orchestrator"| node_orchestrator
node_pipeline -->|"loads model"| node_qualitymodel
node_pipeline -.->|"uses data preparation"| node_dataset
node_dataset -->|"aligns availability"| node_alignment
node_dataset -->|"builds features"| node_processfeatures
node_dataset -->|"builds features"| node_qualityfeatures
node_qualityagent -->|"uses features"| node_processfeatures
node_qualityagent -->|"uses features"| node_qualityfeatures
node_qualityagent -->|"forecasts sulfur"| node_qualitymodel
node_qualityagent -->|"requests horizons"| node_horizons
node_qualityagent -->|"requests estimates"| node_softsensors
node_orchestrator -->|"requests state"| node_dataquality
node_orchestrator -->|"requests assessment"| node_qualityagent
node_orchestrator -->|"requests assessment"| node_reliability
node_orchestrator -->|"requests candidates"| node_optimization
node_orchestrator -->|"checks candidates"| node_safety
node_optimization -->|"generates actions"| node_candidates
node_optimization -->|"ranks by loss"| node_expectedloss
node_optimization -->|"sends scenarios"| node_whatif
node_orchestrator -->|"builds explanation"| node_explainer
node_orchestrator -->|"publishes messages"| node_bus
node_orchestrator -->|"presents recommendation"| node_operator
node_optimization -.->|"checks feasibility"| node_constraints
node_schemas -.->|"defines contracts"| node_orchestrator

click node_app "https://github.com/throddy/diesel-mas/blob/main/app.py"
click node_pipeline "https://github.com/throddy/diesel-mas/blob/main/src/pipeline.py"
click node_config "https://github.com/throddy/diesel-mas/blob/main/src/config.py"
click node_schemas "https://github.com/throddy/diesel-mas/blob/main/src/schemas.py"
click node_loaders "https://github.com/throddy/diesel-mas/blob/main/src/data/loaders.py"
click node_datastore "https://github.com/throddy/diesel-mas/blob/main/src/data/store.py"
click node_dataquality "https://github.com/throddy/diesel-mas/blob/main/src/agents/data_quality_agent.py"
click node_alignment "https://github.com/throddy/diesel-mas/blob/main/src/data/alignment.py"
click node_dataset "https://github.com/throddy/diesel-mas/blob/main/src/features/dataset.py"
click node_processfeatures "https://github.com/throddy/diesel-mas/blob/main/src/features/process_features.py"
click node_qualityfeatures "https://github.com/throddy/diesel-mas/blob/main/src/features/quality_features.py"
click node_qualityagent "https://github.com/throddy/diesel-mas/blob/main/src/agents/quality_agent.py"
click node_qualitymodel "https://github.com/throddy/diesel-mas/blob/main/src/models/quality.py"
click node_horizons "https://github.com/throddy/diesel-mas/blob/main/src/models/horizons.py"
click node_softsensors "https://github.com/throddy/diesel-mas/blob/main/src/models/soft_sensors.py"
click node_reliability "https://github.com/throddy/diesel-mas/blob/main/src/agents/reliability_agent.py"
click node_optimization "https://github.com/throddy/diesel-mas/blob/main/src/agents/optimization_agent.py"
click node_candidates "https://github.com/throddy/diesel-mas/blob/main/src/optimization/candidates.py"
click node_constraints "https://github.com/throddy/diesel-mas/blob/main/src/optimization/constraints.py"
click node_expectedloss "https://github.com/throddy/diesel-mas/blob/main/src/decision/expected_loss.py"
click node_safety "https://github.com/throddy/diesel-mas/blob/main/src/agents/safety_agent.py"
click node_whatif "https://github.com/throddy/diesel-mas/blob/main/src/agents/whatif_agent.py"
click node_orchestrator "https://github.com/throddy/diesel-mas/blob/main/src/agents/orchestrator.py"
click node_bus "https://github.com/throddy/diesel-mas/blob/main/src/mas/bus.py"
click node_explainer "https://github.com/throddy/diesel-mas/blob/main/src/agents/explainer_agent.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_rawdata,node_loaders,node_datastore,node_alignment,node_dataset,node_processfeatures,node_qualityfeatures toneBlue
class node_qualitymodel,node_horizons,node_softsensors toneAmber
class node_schemas,node_dataquality,node_qualityagent,node_reliability,node_optimization,node_safety,node_whatif,node_orchestrator,node_bus,node_explainer toneMint
class node_candidates,node_constraints,node_expectedloss toneRose
class node_app,node_pipeline,node_config,node_operator toneIndigo
```

## Components

### Data and features

- **Plant data sources**
- [Data loading](https://github.com/throddy/diesel-mas/blob/main/src/data/loaders.py): `src/data/loaders.py`
- [Prepared data store](https://github.com/throddy/diesel-mas/blob/main/src/data/store.py): `src/data/store.py`
- [Time alignment](https://github.com/throddy/diesel-mas/blob/main/src/data/alignment.py): `src/data/alignment.py`
- [Feature dataset](https://github.com/throddy/diesel-mas/blob/main/src/features/dataset.py): `src/features/dataset.py`
- [Process features](https://github.com/throddy/diesel-mas/blob/main/src/features/process_features.py): `src/features/process_features.py`
- [Quality features](https://github.com/throddy/diesel-mas/blob/main/src/features/quality_features.py): `src/features/quality_features.py`

### Quality forecasting

- [Sulfur forecast](https://github.com/throddy/diesel-mas/blob/main/src/models/quality.py): `src/models/quality.py`
- [Horizon forecasts](https://github.com/throddy/diesel-mas/blob/main/src/models/horizons.py): `src/models/horizons.py`
- [Soft sensors](https://github.com/throddy/diesel-mas/blob/main/src/models/soft_sensors.py): `src/models/soft_sensors.py`

### Decision agents

- [Agent contracts](https://github.com/throddy/diesel-mas/blob/main/src/schemas.py): `src/schemas.py`
- [Data quality checks](https://github.com/throddy/diesel-mas/blob/main/src/agents/data_quality_agent.py): `src/agents/data_quality_agent.py`
- [Quality assessment](https://github.com/throddy/diesel-mas/blob/main/src/agents/quality_agent.py): `src/agents/quality_agent.py`
- [Reliability assessment](https://github.com/throddy/diesel-mas/blob/main/src/agents/reliability_agent.py): `src/agents/reliability_agent.py`
- [Action generation](https://github.com/throddy/diesel-mas/blob/main/src/agents/optimization_agent.py): `src/agents/optimization_agent.py`
- [Safety review](https://github.com/throddy/diesel-mas/blob/main/src/agents/safety_agent.py): `src/agents/safety_agent.py`
- [What-if assessment](https://github.com/throddy/diesel-mas/blob/main/src/agents/whatif_agent.py): `src/agents/whatif_agent.py`
- [Decision orchestration](https://github.com/throddy/diesel-mas/blob/main/src/agents/orchestrator.py): `src/agents/orchestrator.py`
- [Agent message bus](https://github.com/throddy/diesel-mas/blob/main/src/mas/bus.py): `src/mas/bus.py`
- [Recommendation explanation](https://github.com/throddy/diesel-mas/blob/main/src/agents/explainer_agent.py): `src/agents/explainer_agent.py`

### Action evaluation

- [Action candidates](https://github.com/throddy/diesel-mas/blob/main/src/optimization/candidates.py): `src/optimization/candidates.py`
- [Feasibility constraints](https://github.com/throddy/diesel-mas/blob/main/src/optimization/constraints.py): `src/optimization/constraints.py`
- [Expected loss](https://github.com/throddy/diesel-mas/blob/main/src/decision/expected_loss.py): `src/decision/expected_loss.py`

### Operator interface

- [Decision UI](https://github.com/throddy/diesel-mas/blob/main/app.py): `app.py`
- [System assembly](https://github.com/throddy/diesel-mas/blob/main/src/pipeline.py): `src/pipeline.py`
- [Configuration](https://github.com/throddy/diesel-mas/blob/main/src/config.py): `src/config.py`

### Other components

- **Operator**

## Connections

- Operator → Decision UI: requests decision (evidence: `README.md`)
- Decision UI → System assembly: builds system (evidence: `app.py`)
- System assembly → Configuration: loads settings (evidence: `src/pipeline.py`)
- Plant data sources → Data loading: provides measurements (evidence: `README.md`)
- System assembly → Prepared data store: loads prepared data (evidence: `src/pipeline.py`)
- Data loading → Prepared data store: reads prepared data (evidence: `src/data/loaders.py`)
- System assembly → Data loading: loads data (evidence: `src/pipeline.py`)
- System assembly → Data quality checks: assembles agent (evidence: `src/pipeline.py`)
- System assembly → Quality assessment: assembles agent (evidence: `src/pipeline.py`)
- System assembly → Reliability assessment: assembles agent (evidence: `src/pipeline.py`)
- System assembly → Action generation: assembles agent (evidence: `src/pipeline.py`)
- System assembly → Safety review: assembles agent (evidence: `src/pipeline.py`)
- System assembly → What-if assessment: assembles agent (evidence: `src/pipeline.py`)
- System assembly → Decision orchestration: assembles orchestrator (evidence: `src/pipeline.py`)
- System assembly → Sulfur forecast: loads model (evidence: `src/pipeline.py`)
- System assembly → Feature dataset: uses data preparation
- Feature dataset → Time alignment: aligns availability (evidence: `src/features/dataset.py`)
- Feature dataset → Process features: builds features (evidence: `src/features/dataset.py`)
- Feature dataset → Quality features: builds features (evidence: `src/features/dataset.py`)
- Quality assessment → Process features: uses features (evidence: `src/agents/quality_agent.py`)
- Quality assessment → Quality features: uses features (evidence: `src/agents/quality_agent.py`)
- Quality assessment → Sulfur forecast: forecasts sulfur (evidence: `src/agents/quality_agent.py`)
- Quality assessment → Horizon forecasts: requests horizons (evidence: `src/agents/quality_agent.py`)
- Quality assessment → Soft sensors: requests estimates (evidence: `src/agents/quality_agent.py`)
- Decision orchestration → Data quality checks: requests state (evidence: `src/agents/orchestrator.py`)
- Decision orchestration → Quality assessment: requests assessment (evidence: `src/agents/orchestrator.py`)
- Decision orchestration → Reliability assessment: requests assessment (evidence: `src/agents/orchestrator.py`)
- Decision orchestration → Action generation: requests candidates (evidence: `src/agents/orchestrator.py`)
- Decision orchestration → Safety review: checks candidates (evidence: `src/agents/orchestrator.py`)
- Action generation → Action candidates: generates actions (evidence: `src/agents/optimization_agent.py`)
- Action generation → Expected loss: ranks by loss (evidence: `src/agents/optimization_agent.py`)
- Action generation → What-if assessment: sends scenarios (evidence: `src/agents/optimization_agent.py`)
- Decision orchestration → Recommendation explanation: builds explanation (evidence: `src/agents/orchestrator.py`)
- Decision orchestration → Agent message bus: publishes messages (evidence: `src/agents/orchestrator.py`)
- Decision orchestration → Operator: presents recommendation (evidence: `src/agents/orchestrator.py`)
- Action generation → Feasibility constraints: checks feasibility
- Agent contracts → Decision orchestration: defines contracts (evidence: `src/agents/orchestrator.py`)
