📦 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
• les contextes futurs ou passés (calendrier, événements planifiés)

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

✨ Principes de conception

• 🔌 Agnostique à la source des données
• 📅 Apprentissage automatique des comportements hebdomadaires et saisonniers
• 🏷️ Gestion des événements via importance et tags
• 🔮 Support du contexte futur (événements planifiés)
• 📉 Stabilisation automatique des prédictions long horizon
• 🔍 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

Version simple

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)

Avec contexte futur (calendrier / événements planifiés)

const predicted = await predict(
  { date: new Date('2026-12-10'), importance: 0 },
  getHistory,
  async (start, end) => {
    return [
      { date: new Date('2026-12-25'), importance: 1, tags: ['christmas'] },
      { date: new Date('2026-12-24'), importance: 1, tags: ['holiday_eve'] }
    ].filter(d => d.date >= start && d.date <= end)
  }
)

🧠 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 (kernels)

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 à partir de l’historique.

3️⃣ Contexte futur et passé

Le moteur peut recevoir un getContext :

• événements futurs planifiés
• calendrier structurel (Noël, fêtes nationales…)
• événements dynamiques (concert, promo, grève…)

Cela permet d’activer les effets appris même lorsque la date prédite est éloignée de l’historique disponible.

4️⃣ Stabilisation long horizon

Pour éviter les divergences lors de prédictions très éloignées :

• shrink exponentiel de l’impact en fonction de la distance temporelle
• plafonnement de l’impact avant application de exp()

Cela garantit stabilité et absence d’explosion.

🖥️ Frontend & Backend

Le moteur dépend uniquement de :

• getHistory
• getContext (optionnel)

Il peut fonctionner :

Backend

• Node.js
• API REST
• Microservice de forecasting

Frontend

• Application React / Vue
• Dashboard analytique
• Simulation locale

📊 Gestion des volumes

nostra-data ne force pas le chargement complet de la base.

Le moteur demande uniquement les périodes nécessaires via getHistory(start, end).

Il est recommandé :

• de limiter l’historique à quelques années pertinentes
• ou d’agréger les données si la granularité est fine (ex: hourly)

Un cache interne évite les appels redondants.

⚠️ Limitations actuelles

• Pas encore de granularité horaire native
• Pas encore de gestion automatique des tendances structurelles longues
• Pas encore de système de score de confiance

🔮 Améliorations prévues

• Support multi-granularité (jour, semaine, mois, heure)
• Score de confiance
• Détection automatique de tendance
• Optimisation performance avancée

🧩 Philosophie

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

Le moteur est :

• explicable
• déterministe
• modulaire
• évolutif
• contrôlable