# yzyazid8-web/maintenance-agent architecture

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

- Interactive diagram: https://gitdiagram.com/yzyazid8-web/maintenance-agent
- Repository: https://github.com/yzyazid8-web/maintenance-agent
- Video tour (about a minute): https://gitdiagram.com/yzyazid8-web/maintenance-agent/video

## Overview

Le produit est un tableau de bord marimo de maintenance prédictive, enrichi d’un agent conversationnel qui interroge le modèle et les outils de diagnostic. Le parcours principal va des relevés machine au risque et à son explication, puis au diagnostic FMEA et aux actions recommandées; le tableau de bord expose aussi la supervision de dérive et le réentraînement. Les liens s’appuient sur les extraits, l’index des sources et le README; certaines implémentations de capacités documentées n’ont pas été échantillonnées.

Main entry points: [`app.py`](https://github.com/yzyazid8-web/maintenance-agent/blob/main/app.py) (Dashboard marimo), [`src/agent/tools.py`](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/tools.py) (Outils métier), [`src/agent/chat.py`](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/chat.py) (Chat UI), [`src/agent/agent.py`](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/agent.py) (Agent à outils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Tableau de bord"]
  node_dashboard["Dashboard marimo<br/>[app.py]"]
  node_chat["Chat UI<br/>[chat.py]"]
end

subgraph group_assistant["Agent conversationnel"]
  node_agent["Agent à outils<br/>[agent.py]"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_tools["Outils métier<br/>[tools.py]"]
  node_trace["Traces agent<br/>[trace.py]"]
  node_llm["Routage LLM<br/>[llm.py]"]
  node_eval["Évaluation agent<br/>[eval.py]"]
end

subgraph group_ml["Données et modèle"]
  node_data["Chargement AI4I<br/>[data.py]"]
  node_dataset[("Relevés AI4I<br/>[ai4i2020.csv]")]
  node_features["Features physiques<br/>[features.py]"]
  node_model["Entraînement XGBoost<br/>[model.py]"]
  node_calibration["Calibration Platt<br/>[calibration.py]"]
  node_explain["Explications SHAP<br/>[explain.py]"]
end

subgraph group_diagnostic["Diagnostic FMEA"]
  node_kg[("Knowledge graph FMEA<br/>[knowledge_graph.py]")]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_memory[("Mémoire épisodique<br/>[memory.py]")]
end

subgraph group_ops["Supervision et MLOps"]
  node_drift["Détection de dérive<br/>[drift.py]"]
  node_retrain["Promotion challenger<br/>[model.py]"]
end

node_user(("Utilisateur"))
node_llm_service{{"Groq / Ollama"}}

node_user -->|"utilise"| node_dashboard
node_dashboard -->|"affiche"| node_chat
node_chat -->|"délègue"| node_agent
node_chat -->|"filtre"| node_guardrails
node_chat -->|"trace"| node_trace
node_agent -->|"enregistre"| node_tools
node_agent -->|"construit modèle"| node_llm
node_llm -->|"route requêtes"| node_llm_service
node_agent -->|"évalué par"| node_eval
node_tools -->|"charge"| node_data
node_data -->|"lit"| node_dataset
node_model -->|"entraîne sur"| node_data
node_model -->|"construit pipeline"| node_features
node_model -->|"calibre scores"| node_calibration
node_tools -->|"calcule SHAP"| node_explain
node_tools -->|"calibre what-if"| node_calibration
node_tools -->|"diagnostique"| node_kg
node_tools -->|"lit et écrit"| node_memory
node_kg -->|"récupère sémantiquement"| node_embeddings
node_memory -->|"vectorise épisodes"| node_embeddings
node_dashboard -->|"analyse dérive"| node_drift
node_dashboard -->|"demande réentraînement"| node_model
node_dashboard -->|"affiche SHAP"| node_explain
node_dashboard -->|"charge relevés"| node_data
node_eval -->|"utilise juge"| node_llm

click node_dashboard "https://github.com/yzyazid8-web/maintenance-agent/blob/main/app.py"
click node_chat "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/chat.py"
click node_agent "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/agent.py"
click node_guardrails "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/guardrails.py"
click node_tools "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/tools.py"
click node_trace "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/trace.py"
click node_llm "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/llm.py"
click node_eval "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/eval.py"
click node_data "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/data.py"
click node_dataset "https://github.com/yzyazid8-web/maintenance-agent/blob/main/data/ai4i2020.csv"
click node_features "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/features.py"
click node_model "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/model.py"
click node_calibration "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/calibration.py"
click node_explain "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/explain.py"
click node_kg "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/knowledge_graph.py"
click node_embeddings "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/embeddings.py"
click node_memory "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/memory.py"
click node_drift "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/drift.py"
click node_retrain "https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/model.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_dashboard,node_chat toneBlue
class node_agent,node_guardrails,node_tools,node_trace,node_llm,node_eval toneAmber
class node_data,node_dataset,node_features,node_model,node_calibration,node_explain toneMint
class node_kg,node_embeddings,node_memory toneRose
class node_drift,node_retrain,node_user,node_llm_service toneIndigo
```

## Components

### Tableau de bord

- [Dashboard marimo](https://github.com/yzyazid8-web/maintenance-agent/blob/main/app.py): `app.py`
- [Chat UI](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/chat.py): `src/agent/chat.py`

### Agent conversationnel

- [Agent à outils](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/agent.py): `src/agent/agent.py`
- [Guardrails](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/guardrails.py): `src/agent/guardrails.py`
- [Outils métier](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/tools.py): `src/agent/tools.py`
- [Traces agent](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/trace.py): `src/agent/trace.py`
- [Routage LLM](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/llm.py): `src/agent/llm.py`
- [Évaluation agent](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/eval.py): `src/agent/eval.py`

### Données et modèle

- [Chargement AI4I](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/data.py): `src/data.py`
- [Relevés AI4I](https://github.com/yzyazid8-web/maintenance-agent/blob/main/data/ai4i2020.csv): `data/ai4i2020.csv`
- [Features physiques](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/features.py): `src/features.py`
- [Entraînement XGBoost](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/model.py): `src/model.py`
- [Calibration Platt](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/calibration.py): `src/calibration.py`
- [Explications SHAP](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/explain.py): `src/explain.py`

### Diagnostic FMEA

- [Knowledge graph FMEA](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/knowledge_graph.py): `src/agent/knowledge_graph.py`
- [Embeddings](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/embeddings.py): `src/agent/embeddings.py`
- [Mémoire épisodique](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/agent/memory.py): `src/agent/memory.py`

### Supervision et MLOps

- [Détection de dérive](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/drift.py): `src/drift.py`
- [Promotion challenger](https://github.com/yzyazid8-web/maintenance-agent/blob/main/src/model.py): `src/model.py`

### Other components

- **Utilisateur**
- **Groq / Ollama**

## Connections

- Utilisateur → Dashboard marimo: utilise (evidence: `README.md`)
- Dashboard marimo → Chat UI: affiche (evidence: `app.py`)
- Chat UI → Agent à outils: délègue (evidence: `src/agent/chat.py`)
- Chat UI → Guardrails: filtre (evidence: `src/agent/chat.py`)
- Chat UI → Traces agent: trace (evidence: `src/agent/chat.py`)
- Agent à outils → Outils métier: enregistre (evidence: `src/agent/agent.py`)
- Agent à outils → Routage LLM: construit modèle (evidence: `src/agent/agent.py`)
- Routage LLM → Groq / Ollama: route requêtes (evidence: `src/agent/llm.py`)
- Agent à outils → Évaluation agent: évalué par (evidence: `src/agent/eval.py`)
- Outils métier → Chargement AI4I: charge (evidence: `src/agent/tools.py`)
- Chargement AI4I → Relevés AI4I: lit (evidence: `src/data.py`)
- Entraînement XGBoost → Chargement AI4I: entraîne sur (evidence: `src/model.py`)
- Entraînement XGBoost → Features physiques: construit pipeline (evidence: `src/model.py`)
- Entraînement XGBoost → Calibration Platt: calibre scores (evidence: `src/model.py`)
- Outils métier → Explications SHAP: calcule SHAP (evidence: `src/agent/tools.py`)
- Outils métier → Calibration Platt: calibre what-if (evidence: `src/agent/tools.py`)
- Outils métier → Knowledge graph FMEA: diagnostique (evidence: `src/agent/tools.py`)
- Outils métier → Mémoire épisodique: lit et écrit (evidence: `src/agent/tools.py`)
- Knowledge graph FMEA → Embeddings: récupère sémantiquement (evidence: `src/agent/knowledge_graph.py`)
- Mémoire épisodique → Embeddings: vectorise épisodes (evidence: `src/agent/memory.py`)
- Dashboard marimo → Détection de dérive: analyse dérive (evidence: `README.md`)
- Dashboard marimo → Entraînement XGBoost: demande réentraînement (evidence: `README.md`)
- Dashboard marimo → Explications SHAP: affiche SHAP (evidence: `app.py`)
- Dashboard marimo → Chargement AI4I: charge relevés (evidence: `app.py`)
- Évaluation agent → Routage LLM: utilise juge (evidence: `src/agent/eval.py`)