Librairie StatsComputer

Cette librairie centralise le calcul de diverses statistiques pour le tableau de bord d’administration de Clea-API, en s’appuyant sur :

  • Les schémas Pydantic définis dans stats_src_schemas.py
  • La classe StatsComputer implémentée dans stats_src_compute.py

1. Installation

Assurez-vous que le paquet stats est installé dans votre environnement Clea-API, et que vectordb est configuré (PG + SQLAlchemy).

pip install -e stats/

2. Schémas de sortie

Tous les modèles Pydantic utilisent la configuration alias_generator pour produire des clés camelCase à la sortie JSON.

# config globale
def _to_camel(s: str) -> str:
    head, *tail = s.split("_")
    return head + "".join(word.capitalize() for word in tail)
CamelConfig = {
    "alias_generator": _to_camel,
    "populate_by_name": True,
}

2.1. DocumentStats

Statistiques sur les documents stockés.

Attribut Type Description
totalCount int Nombre total de documents analysés
byTheme Record<string,int> Répartition par thème
byType Record<string,int> Répartition par type de document
recentlyAdded int Documents publiés au cours des 30 derniers jours
percentChange float % de documents récents par rapport au total

2.2. SearchStats

Statistiques sur l’historique des recherches des utilisateurs.

Attribut Type Description
totalCount int Nombre total de requêtes enregistrées
lastMonthCount int Requêtes effectuées au cours des 30 derniers jours
percentChange float % d’évolution par rapport au mois précédent
topQueries Array<{query:string, count:number}> Top 10 des requêtes les plus populaires

2.3. SystemStats

Indicateurs globaux de performance et d’état.

Attribut Type Description
satisfaction float % de recherches jugées satisfaisantes (confiance ≥ 0.7)
avgConfidence float Confiance moyenne des recherches du dernier mois
percentChange float % d’évolution de la confiance par rapport au mois précédent
indexedCorpora int Nombre de corpus/documents déjà indexés
totalCorpora int Nombre total de corpus/documents dans la base

2.4. DashboardStats

Regroupe l’ensemble des stats en un seul objet :

interface DashboardStats {
  documentStats: DocumentStats;
  searchStats:   SearchStats;
  systemStats:   SystemStats;
}

3. Classe StatsComputer

La classe principale pour générer ces statistiques :

from stats.src.stats_src_compute import StatsComputer

stats = StatsComputer()

3.1. compute_document_stats(skip=0, limit=100) → DocumentStats

  • Description : Récupère jusqu’à limit documents (après avoir ignoré skip), puis calcule :

  • totalCount, byTheme, byType

  • recentlyAdded (← 30 derniers jours)

  • percentChange

  • Usage :

doc_stats = stats.compute_document_stats(skip=0, limit=500)
print(doc_stats.json())

3.2. compute_search_stats(skip=0, limit=100) → SearchStats

  • Description : Analyse la table SearchQuery pour :

  • totalCount, lastMonthCount

  • percentChange (mois vs mois)

  • topQueries (top 10 requêtes)

  • Usage :

search_stats = stats.compute_search_stats()
print(search_stats.json())

3.3. compute_system_stats() → SystemStats

  • Description : Calcul des indicateurs système :

  • Confiance moyenne (avgConfidence) et évolution (percentChange)

  • Taux de satisfaction (satisfaction)

  • indexedCorpora vs totalCorpora

  • Usage :

sys_stats = stats.compute_system_stats()
print(sys_stats.json())

3.4. compute_all_stats() → DashboardStats

  • Description : Agrège les trois méthodes précédentes et retourne un DashboardStats.

  • Usage :

dashboard = stats.compute_all_stats()
# affiche un rapport JSON complet
print(dashboard.json(indent=2))

4. Bonnes pratiques

  • Pagination : ajustez skip/limit pour ne pas surcharger la mémoire.
  • Logging : la classe utilise le logger "clea-api.stats" pour tracer les erreurs.
  • Sécurité : si les calculs sont lourds, envisagez de les déporter en tâche asynchrone.

Fichiers source : – stats/src/stats_src_schemas.py – stats/src/stats_src_compute.py Dernière mise à jour : 05 mai 2025