📦 nostra-data

nostra-data est une librairie JavaScript/TypeScript de prévision de demande basée sur l’apprentissage des patterns temporels et des impacts d’événements.

Elle ne dépend d’aucune base de données, d’aucun framework, et n’impose aucune source de données.
Elle fonctionne aussi bien côté backend (Node.js) que côté frontend (browser).

🎯 Objectif

Prédire la demande pour une date donnée en se basant sur :

• l’historique passé
• la saisonnalité naturelle (jour de semaine, période de l’année)
• les impacts d’événements (via importance et tags)
• les effets autour des dates marquantes

Le moteur n’utilise pas de réseau de neurones.
Il repose sur un modèle explicable et déterministe.

✨ Principes de conception

• 🔌 Agnostique à la source des données
• 📅 Apprentissage automatique des comportements hebdomadaires et saisonniers
• 🏷️ Gestion des événements via importance et tags
• 🔍 Modèle interprétable
• 🧠 Aucun accès direct à la base de données
• 🌍 Compatible Node.js et navigateur

📥 Installation

npm install nostra-data

yarn add nostra-data

📐 Format des données

export interface DemandDTO {
  date: Date
  demand: number
  importance: number   // entre 0 et 1
  tags?: string[]
}

🚀 Utilisation

import { predict } from 'nostra-data'

const predicted = await predict(
  {
    date: new Date('2026-12-24'),
    importance: 0.9,
    tags: ['holiday_eve']
  },
  async (startDate, endDate) => {
    return prendreDataDepuisLaBase(startDate, endDate)
  }
)

console.log("la valeur prédite est", predicted) // affiche la valeur prédite

🧠 Fonctionnement

1️⃣ Baseline saisonnière

Apprentissage automatique :

• week-ends vs semaine
• jour de la semaine
• saisonnalité annuelle

Aucun poids manuel n’est nécessaire.

2️⃣ Impact d’événements

Les dates marquées (importance > 0 ou tags) influencent :

• le jour concerné
• les jours autour (avant / après)

Le moteur apprend automatiquement la forme de ces impacts.

🖥️ Frontend & Backend

Le moteur dépend uniquement du callback getHistory.

Il peut fonctionner :

Backend

• Node.js
• API REST
• Microservice de forecasting

Frontend

• Application React / Vue
• Dashboard analytique
• Simulation locale

📊 Cas d’usage

• Retail
• Mobilité
• Température
• Livraison
• Gestion de stock
• Planification RH
• Analyse d’affluence

⚠️ Limitations actuelles

• Pas encore de gestion explicite des événements futurs (le moteur ne gère pas encore le fait qu'il y ait des évènements importants postérieurs à la date à laquelle on veut faire la prédiction)
• Pas encore de granularité horaire native
• Pas encore de mécanisme de stabilisation long horizon
• Pas encore de cache interne

🔮 Améliorations prévues

🔹 Ajout d’un système de contexte futur

Permettre d’indiquer à l’avance les dates marquantes à venir.

🔹 Support multi-granularité

• jour
• semaine
• mois
• heure

🔹 Stabilisation long horizon

• shrinkage automatique de l’impact
• plafonnement dynamique
• gestion de l’incertitude

🔹 Optimisation performance

• cache interne intelligent
• indexation automatique
• pré-calcul saisonnier

🧩 Philosophie

nostra-data n’est pas une boîte noire.

Le moteur est :

• explicable
• déterministe
• modulaire
• évolutif