Préparer ses données

Ce qu'attend Spavik, et ce qu'il refuse.

Le minimum

Contrainte	Valeur
Lignes pour entraîner	10 au minimum
Valeurs distinctes dans la cible	2 au minimum
Colonnes	pas de minimum, mais une seule colonne prédit mal

Les bibliothèques vérifient ces trois points sur votre machine, avant tout appel réseau. Un fichier trop court ne consomme donc ni crédit ni aller-retour.

Les formats acceptés

Vous n'avez rien à convertir.

spavik.train(df, target="churn")                   # DataFrame pandas
spavik.train("data/churn.csv", target="churn")     # fichier CSV
spavik.train("data/churn.json", target="churn")    # fichier JSON
spavik.train([{"plan": "pro", "churn": 0}], ...)   # liste de dictionnaires
spavik.train("plan,churn\npro,0\n...", ...)        # CSV en mémoire

Le séparateur est détecté (virgule, point-virgule, tabulation, barre verticale), les guillemets sont gérés, et les nombres retrouvent leur type au passage : un "12" lu dans un CSV devient un entier.

En appel direct, l'API accepte le JSON dans data, ou un fichier en multipart/form-data sur POST /v1/models, POST /v1/forecast et POST /v1/models/{id}/predict. Le second évite de sérialiser un gros jeu de données dans un corps JSON.

Vérifier avant d'entraîner

POST /v1/datasets/validate rend le même rapport que l'entraînement, plus un essai du moteur : un verdict et la première chose à corriger. Il ne crée rien et ne facture rien, donc itérez sur le fichier jusqu'à ce qu'il tienne.

rapport = spavik.validate("churn.csv", target="churn")
rapport["hint"]                       # 'Add more rows if you can: quality will be limited below fifty examples.'
rapport["trial"]["verdict"]["level"]  # 'usable', 'weak' ou 'no_signal'

weak veut dire que la note est trop belle : une colonne est probablement remplie après l'événement que vous prédisez, et le modèle serait inutile en production. no_signal veut dire que les colonnes ne portent rien pour cette cible. L'essai découpe les lignes au hasard, pas dans l'ordre du temps : pour une série, utilisez le backtest ci-dessous.

Les valeurs manquantes

Une cellule vide devient null, et le moteur sait faire avec. En revanche, une ligne dont la cible est vide ne sert à rien pour apprendre : si trop de vos lignes sont dans ce cas, la bibliothèque vous le dit plutôt que de laisser l'entraînement se faire sur presque rien.

Les NaN d'un DataFrame pandas sont convertis en null automatiquement.

Le nom des colonnes

Les colonnes que vous envoyez à predict doivent porter les mêmes noms qu'à l'entraînement, la cible en moins. Un écart donne COLUMN_MISMATCH ou SCHEMA_MISMATCH. Un modèle s'en souvient : feature_columns sur GET /v1/models/{id}, model.features dans les bibliothèques.

Si vous vous trompez sur le nom de la cible, la bibliothèque vous propose la colonne la plus proche :

SpavikDataError: the target column 'churn_90d' is missing from the data.
                 Columns found: plan, seats, tickets_90d, churn. Did you mean 'churn'?

Les limites de taille

L'API refuse au-delà de certains seuils, avec un code explicite :

Code	Ce qui s'est passé
TOO_MANY_ROWS	trop de lignes dans un seul appel
DATASET_TOO_LARGE	jeu de données trop volumineux
FILE_TOO_LARGE	fichier téléversé trop lourd
CSV_UNREADABLE	le CSV n'a pas pu être lu

Ces seuils dépendent du plan et du déploiement. Plutôt que de les deviner, envoyez et lisez le code : le message précise la limite atteinte.

Pour une série temporelle

forecast demande en plus :

• une colonne de valeurs (target), numérique ;
• une colonne d'horodatage (timestamp), facultative mais recommandée ;
• une colonne d'identifiant de série (item_id) si votre fichier contient plusieurs séries, une par boutique ou par produit par exemple.

Votre série doit compter au moins autant de points que l'horizon demandé, et de préférence plusieurs fois plus. Trois points pour un horizon de quatorze ne produit rien d'exploitable, et la bibliothèque le refuse avant l'appel.

Le coût dépend de l'horizon et du nombre de séries, jamais de la longueur de l'historique : 56 points avec un horizon de 7 coûtent 7 crédits.

Avant de payer, POST /v1/forecast/backtest vérifie la série (longueur, pas régulier, horodatages en double) et rejoue son historique pour comparer le moteur à la simple répétition de la dernière période. Il rend un verdict, une note par période rejouée, et jamais la prévision elle-même. Une série au pas régulier mais sans motif exploitable revient no_signal : la réponse est alors de ne pas payer. Un historique plus long n'aide pas par lui-même ; mesurez chaque série.