database/README.md

# Base de données de monitoring — Agritech Answers

## Objectif

Cette base PostgreSQL permet de suivre le comportement de l’API en production dans une logique **MLOps**.

Elle centralise :

- les appels API
- les étapes internes du pipeline ML
- les prédictions produites
- le détail des recommandations
- les référentiels métier utilisés par l’API
- les distributions de référence utilisées pour le monitoring du drift

---

# Structure de la base

## Table `api_requests`

Table principale du monitoring.

**1 ligne = 1 appel API**

Cette table contient :

- l’endpoint appelé (`predict` ou `recommend`)
- le statut de la requête
- la latence de traitement
- le modèle utilisé
- les données d’entrée
- la réponse retournée par l’API
- les erreurs éventuelles

---

## Table `inference_steps`

Suivi technique détaillé du pipeline ML.

Cette table permet de tracer :

- la validation métier
- le feature engineering
- la prédiction
- le post-processing
- les erreurs techniques
- la durée de chaque étape

---

## Table `api_predictions`

Résumé métier des prédictions produites.

Cette table contient :

- le pays concerné
- la culture prédite ou recommandée
- le rendement estimé
- le type de prédiction (`predict` ou `recommend`)
- le nombre de candidats évalués

---

## Table `api_recommendation_details`

Détail complet du classement des recommandations.

**1 ligne = 1 culture candidate du Top K**

Cette table permet de conserver :

- le rang de la culture
- la culture recommandée
- le rendement estimé

---

## Table `country_crop_mapping`

Référentiel métier des associations pays / cultures.

Cette table est générée automatiquement depuis le jeu d’entraînement afin de garantir :

- la cohérence des recommandations
- l’absence de fuite de données
- l’utilisation exclusive des cultures réellement observées

Elle est utilisée par l’API pour :

- valider les entrées utilisateur
- limiter les recommandations aux cultures plausibles

---

## Table `reference_distributions`

Référentiel de distributions utilisé pour le monitoring du drift.

Cette table stocke les valeurs de référence issues du jeu d’entraînement pour :

### Variables numériques

- `temp`
- `rainfall_mm`
- `pesticides`
- `trend`

### Variables catégorielles

- `area`
- `item`

Elle permet :

- le calcul du PSI (Population Stability Index)
- le suivi des distributions en production
- la détection de dérive des données
- le monitoring ML avancé

---

# Relations entre les tables

```mermaid
erDiagram

    api_requests ||--o{ inference_steps : "décompose"

    api_requests ||--o{ api_predictions : "produit"

    api_requests ||--o{ api_recommendation_details : "détaille"
```

---

# Schéma de la base

```mermaid
erDiagram

    api_requests ||--o{ inference_steps : "trace"

    api_requests ||--o{ api_predictions : "produit"

    api_requests ||--o{ api_recommendation_details : "detaille"


    api_requests {

        int id PK

        datetime timestamp

        string endpoint

        int status_code

        boolean success

        string error_message

        float latency_ms

        string model_name

        string model_version

        string input_json

        string output_json

    }


    inference_steps {

        int id PK

        int request_id FK

        string step_name

        boolean success

        string error_message

        float duration_ms

        string details_json

    }


    api_predictions {

        int id PK

        int request_id FK

        string area

        string item

        string recommended_crop

        float predicted_yield

        int n_candidates

        string prediction_type

    }


    api_recommendation_details {

        int id PK

        int request_id FK

        int rank

        string item

        float predicted_yield

    }


    country_crop_mapping {

        int id PK

        string area

        string item

        string source

        datetime created_at

    }


    reference_distributions {

        int id PK

        string feature_name

        string feature_value

        string source

        datetime created_at

    }
```

---

# Initialisation

## 1. Créer la base PostgreSQL

```sql
CREATE DATABASE agritech_monitoring;
```

---

## 2. Exécuter le schéma SQL

```sql
\i database/schema.sql
```

---

# Génération des référentiels métier

## Mapping pays / cultures

Le mapping `country_crop_mapping` est généré automatiquement depuis le notebook de recommandation.

Cette étape permet de :

- construire les associations pays / cultures
- exporter le référentiel en JSON
- enregistrer les données en base PostgreSQL

Le référentiel est construit uniquement à partir du jeu d’entraînement afin d’éviter toute fuite de données.

---

## Distributions de référence

Les distributions de référence sont chargées via :

```bash
python -m scripts.load_reference_distributions
```

Ce script :

- lit le jeu d’entraînement
- extrait les variables suivies
- charge les distributions en base PostgreSQL
- prépare les données nécessaires au calcul du drift et du PSI

---

# Monitoring ML

Le système de monitoring permet de suivre :

## Monitoring système

- nombre de requêtes
- latence moyenne
- latence par endpoint
- latence par étape d’inférence
- erreurs récentes
- volume d’appels API

## Monitoring métier

- cultures les plus recommandées
- utilisation des endpoints
- suivi des prédictions

## Monitoring ML

- distributions des variables d’entrée
- dérive des données
- PSI (Population Stability Index)
- comparaison train vs production

---

# Utilisation dans l’API

La base est utilisée par l’API pour :

- tracer les appels utilisateurs
- suivre les performances du modèle
- analyser les erreurs
- monitorer les temps d’inférence
- conserver l’historique des recommandations
- valider les cultures disponibles selon les pays
- suivre la dérive des données en production

---

# Architecture MLOps

Cette base s’intègre dans une architecture MLOps comprenant :

- FastAPI
- PostgreSQL / Neon
- Docker
- Hugging Face Hub
- GitHub Actions
- Streamlit
- Streamlit Monitoring

---

# Objectif du monitoring

Le système de monitoring a pour objectif de :

- superviser les performances techniques
- suivre le comportement du modèle en production
- détecter les anomalies
- analyser les usages métier
- préparer une industrialisation MLOps complète