Calculateur de KPI

Que fait Calculateur de KPI ?

Transforme un ou plusieurs fichiers CSV/TSV ainsi qu'une instruction courte en un ensemble vérifié de KPI, chacun avec sa valeur, son unité, son équation, sa signification et une étiquette de base. Il n'y a pas de liste fixe de champs : les KPI sont conçus pour ce que les données et l'instruction décrivent. Les articles, rapports ou résultats antérieurs joints à côté des données contribuent à leurs KPI, appliqués aux données de l'utilisateur avec leur provenance.

<skill_dir> ci-dessous signifie le dossier contenant ce fichier. Exécutez les scripts comme python <skill_dir>/scripts/<nom>.py depuis le dossier de travail (voir « Où vont les sorties »), en passant les fichiers de données par chemin absolu.

Si python n'est pas trouvé (ou ouvre le Microsoft Store), utilisez py -3 sur Windows ou python3 ailleurs dans chaque commande ci-dessous. Vérifiez une fois au début avec python --version.

Règles strictes

1. Chaque nombre provient du code exécuté sur les fichiers. N'estimez jamais, n'arrondissez pas à vue d'œil et ne déclarez aucune valeur en prose qui ne se trouve pas dans results.json.
2. Les KPI exclus ne sont jamais calculés et n'apparaissent jamais ailleurs que sur la ligne unique « Exclu à votre demande ».
3. Chaque hypothèse est énoncée dans « Ce que j'ai compris » (modèle, rôles, unités, interpolation, fuseau horaire, ordre jour/mois, valeurs par défaut utilisées).
4. Au plus une question par exécution, et seulement lorsqu'une mauvaise estimation modifierait les résultats (voir references/role-mapping.md, « Quand demander »). Sinon, indiquez la lecture effectuée et poursuivez.
5. Chaque KPI est une spécification dans kpi_specs.json construite à partir de primitives. Chacun est étiqueté basis: established (standard dans le domaine) ou derived (construit à partir des premiers principes).
6. Les ratios sur des périodes sont des ratios de sommes, pas des moyennes de ratios, sauf si le KPI est défini autrement.
7. Le temps irrégulier est le temps réel. Ne comptez jamais les lignes comme des pas de temps ; intégrez et moyennez sur les horodatages avec l'interpolation de chaque colonne.
8. Les échecs de validation sont revérifiés une fois (notes d'analyse → cartographie → spécification), puis signalés avec l'avertissement, jamais cachés.
9. Les connaissances du domaine vivent uniquement en Markdown. N'ajoutez jamais de logique spécifique au domaine dans les scripts.
10. Les valeurs provenant de références sont des citations. Les nombres rapportés dans des articles ou résultats antérieurs vont uniquement dans reference.reported d'une spécification ; ils ne sont jamais des entrées pour un calcul et ne sont jamais présentés comme le résultat de l'utilisateur.

Où vont les sorties

Décidez cela à l'étape 1 et enregistrez-le dans request.json → output_dir.

Situation	Dossier de travail (tous les fichiers JSON, répertoire de travail des scripts)	Livrables
L'utilisateur nomme un dossier (« enregistre les résultats dans D:/reports/line3 »)	ce dossier (créez-le)	même dossier
Applications Claude (claude.ai / chat desktop, /mnt/user-data/outputs/ existe)	le répertoire courant	copie dans /mnt/user-data/outputs/ : ils apparaissent comme des fichiers téléchargeables
Claude Code, aucun dossier nommé	kpi_output/ dans le répertoire courant	même dossier

Les livrables sont report.md, kpi_results.csv, kpi_run.py, et lorsqu'ils sont produits kpi_chart.png, kpi_adhoc.py et un pack de domaine proposé. Les fichiers de travail (request.json, profile.json, mapping.json, kpi_specs.json, results.json) restent dans le dossier de travail pour audit et ne sont partagés que sur demande.

Remettez les livrables à l'utilisateur pour qu'il puisse les enregistrer n'importe où :

• Applications Claude : en plus des fichiers téléchargeables, montrez le rapport terminé comme un artefact de document Markdown, afin qu'il puisse être lu, copié ou téléchargé indépendamment.
• Claude Code : listez chaque livrable comme un lien vers son chemin. Lorsque l'hôte propose un outil pour envoyer des fichiers à l'utilisateur (par exemple des fiches de fichiers dans l'application desktop), envoyez également les livrables via celui-ci.
• N'écrivez jamais en dehors du dossier de travail et de l'emplacement des livrables sauf si l'utilisateur le demande.

Pour réexécuter kpi_run.py plus tard, placez-le dans un dossier avec les fichiers d'entrée.

Scripts d'abord, ad hoc seulement comme solution de repli

Exécutez toujours les scripts ci-dessous. Écrivez votre propre code pandas uniquement lorsque :

• un script se termine par une erreur que vous ne pouvez pas corriger en modifiant profile.json, mapping.json ou les spécifications (par exemple, un fichier profile_csv.py ne peut pas analyser), ou
• un KPI nécessite une opération qu'aucune primitive ou expression ne couvre (check_spec.py signale unknown_op).

Ensuite :

1. Placez le code dans kpi_adhoc.py dans le répertoire de travail, chargez les données avec les paramètres d'analyse dans profile.json (ou scripts/lib/io.py load) et gardez-le exécutable de manière autonome.
2. Ajoutez chaque KPI ad hoc à results.json → kpis avec chaque champ de schemas/results.schema.json et "computed_by": "ad_hoc", après que run_specs.py a écrit le fichier. Ne modifiez jamais les valeurs calculées par le moteur.
3. Le rapport marque ces KPI avec † et pointe vers kpi_adhoc.py.

N'utilisez jamais eval/exec sur des chaînes dérivées de l'utilisateur ou des données, même ad hoc.

Workflow

Exécutez les huit étapes dans l'ordre. Ne lisez un fichier de référence que lorsque son étape en a besoin.

Étape 1 [Claude] Analyser la requête → request.json

Lisez references/request-parsing.md. Extrayez les champs field, mode, focus, include, exclude, custom, params, max_kpis, output_dir.

• Références (articles, rapports, normes, résultats antérieurs) jointes ou nommées dans l'invite : lisez references/reference-documents.md, distinguez-les des fichiers de données, lisez chacun en entier et enregistrez ses KPI dans request.json → references (id, nom, définition, équation, emplacement, valeurs rapportées). Seuls les fichiers de données vont à l'étape 2.

• Entrée Excel : convertissez chaque feuille en son propre CSV d'abord (pandas.read_excel(sheet_name=None)), nommez-les <livre>__<feuille>.csv.

• Un KPI à la fois inclus et exclu → c'est la seule question de cette exécution. Ne calculez rien pour ce KPI jusqu'à ce qu'il soit répondu.

Étape 2 [script] Charger et profiler → profile.json

python <skill_dir>/scripts/profile_csv.py FICHIER [FICHIER ...] --out profile.json

Vérifiez le type de chaque colonne, l'indice d'unité et les notes d'analyse. Si une colonne qui devrait être numérique s'avère être du text, regardez ses échantillons et corrigez l'analyse avant de continuer.

Étape 3 [script] Détecter le modèle temporel et de collecte → profile.json (section temps)

python <skill_dir>/scripts/detect_time.py --profile profile.json [--tz <fuseau IANA>] --out profile.json

Lisez references/collection-patterns.md. Le script propose un modèle avec evidence et d'autres candidates plausibles, plus entity_column (lorsque les horodatages se répètent sur une colonne de regroupement), frequency (alias pandas tel que D, B, h, MS), gaps, duplicates et tz. Confirmez ou remplacez le modèle et l'entité en utilisant la description de l'utilisateur. Si ambiguous_dayfirst est vrai, indiquez l'hypothèse (ou demandez, si les deux lectures modifient les valeurs des KPI et qu'aucune autre question n'est en attente). Passez --tz lorsque l'utilisateur nomme le fuseau horaire des horodatages locaux naïfs.

Étape 4 [Claude] Cartographier les rôles des colonnes → mapping.json

Lisez references/role-mapping.md. Attribuez à chaque colonne un rôle, une quantité physique, une unité et une interpolation ; enregistrez l'entité, les paires, les jointures, le remodelage, le rééchantillonnage et les paramètres. Les en-têtes dans n'importe quelle langue sont lus par leur signification ; conservez les noms originaux.

Ensuite, écrivez mapping.json → sensitivity : une variante pour chaque jugement qui aurait pu raisonnablement être différent (interpolation, une classe d'état ambiguë, ordre jour/mois, temps d'arrêt planifié, une unité ou un paramètre supposé). Le moteur réexécute chaque KPI sous chaque variante et rapporte une plage basse-haute, afin que l'utilisateur voie quels nombres dépendent de quelles hypothèses. Les règles et le format des correctifs se trouvent dans references/role-mapping.md, « Variantes de sensibilité ».

Étape 5 [Claude] Concevoir et sélectionner les KPI → kpi_specs.json

Lisez references/kpi-discovery.md (méthode) et references/kpi-spec.md (format, primitives, grammaire). Si references/fields/ contient un pack correspondant au domaine, lisez-le également ; il informe mais ne limite jamais.

Ordre de sélection : ceux requis (include) et custom d'abord → KPI provenant de references (spécification source: reference avec un bloc reference, voir references/reference-documents.md) → jamais exclude → par pertinence pour focus, établis avant dérivés, pas de quasi-doublons → limitez les choix de Claude à max_kpis (par défaut 12). Les KPI requis, personnalisés et de référence ne sont jamais supprimés ; un KPI de référence que les données ne peuvent pas prendre en charge n'obtient pas de spécification et est listé sous « Non calculé automatiquement ».

Ensuite, vérifiez les spécifications :

python <skill_dir>/scripts/check_spec.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json

Exit 0 = ok. Exit 1 = erreurs au format JSON sur stdout : corrigez la spécification ou la cartographie et réexécutez. Les unités inconnues reviennent sous forme d'avertissements : si l'une d'elles modifie les résultats, cela peut être la question de l'exécution.

Étape 6–7 [script] Calculer et valider → results.json, kpi_run.py

python <skill_dir>/scripts/run_specs.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json --out results.json --script-out kpi_run.py

Chaque spécification s'exécute par groupe (entité) plus une valeur globale selon sa règle overall. Une spécification ou groupe défaillant devient not_computed avec sa raison ; l'exécution continue. Le résumé stdout liste chaque avertissement de validation:.

La même exécution aussi :

• réexécute tous les KPI une fois par variante de sensibilité et stocke sensitivity: {low, high, variants} sur chaque KPI ;
• compare chaque KPI avec les valeurs rapportées par ses références, converties dans l'unité du KPI (comparison : différence, différence relative, meilleur/pire par direction, si la valeur rapportée se situe dans la plage de sensibilité) ;
• écrit data_health : par colonne numérique cartographiée, part manquante, plus longue séquence constante, valeurs aberrantes robustes et valeurs impossibles (comptes négatifs, % supérieur à 100, en dessous du zéro absolu), plus couverture temporelle pour les séries régulières.

Si un KPI porte un avertissement de validation : revérifiez les notes d'analyse (étape 2), la cartographie (étape 4) et la spécification (étape 5) une fois, réexécutez à partir de la première étape que vous avez modifiée, puis rapportez avec l'avertissement si cela échoue toujours.

Après l'exécution, vous pouvez modifier results.json uniquement pour ajouter un texte enable aux entrées not_computed (toujours pour les KPI provenant de références et include) (quelles données ou paramètres rendraient le KPI calculable) et, selon le repli ci-dessus, des enregistrements de KPI ad hoc. kpi_run.py intègre les hachages des entrées, le profil, la cartographie, les spécifications et le code de la compétence ; il reproduit results.json (sous le nom results_rerun.json) sans la compétence.

Étape 8 [script + Claude] Rapport → report.md, kpi_results.csv, graphique optionnel

python <skill_dir>/scripts/report.py --results results.json --request request.json \
       --mapping mapping.json --profile profile.json \
       --out-md report.md --out-csv kpi_results.csv [--chart kpi_chart.png]

Passez --chart uniquement lorsque le focus implique un changement dans le temps et qu'une colonne temporelle existe ; cela trace jusqu'à deux KPI avec des valeurs per_period (donnez à ces KPI une portée per_period). Le script refuse de s'exécuter si un KPI exclu se trouve dans results.json.

Lisez references/report-format.md, puis remplacez les espaces réservés que le script liste sur stdout, en éditant report.md sur place :

• {{FINDINGS}} : 2 à 5 phrases répondant au focus, citant les valeurs des KPI avec les unités de results.json. Aucun nouveau nombre. Nommez les KPI dont la plage de sensibilité est large (et la lecture qui les modifie), la comparaison avec les références lorsqu'il y en a une (en utilisant la différence calculée et le verdict, avec les limites de comparabilité), et tout indicateur de santé des données sur une colonne utilisée par un KPI clé.
• {{READING:<id_kpi>}} : une phrase par KPI : bon ou mauvais par rapport à sa direction et à sa plage typique si connue.

Tout le reste dans le rapport (noms, équations, significations, nombres) provient de results.json et n'est pas réécrit. Montrez le report.md terminé dans le chat et livrez les fichiers comme décrit dans « Où vont les sorties ».

Liste de vérification des sorties

Avant de répondre, confirmez tout ce qui suit :

• Rapport de chat avec les huit sections dans l'ordre : Ce que j'ai compris · Aperçu des KPI · Détails des KPI · Résultats · Non calculé · Exclu à votre demande · Problèmes de données · Reproduire.
• Chaque KPI montre la valeur, l'unité, la direction, l'étiquette de base, la source, l'équation LaTeX et l'équation en texte brut, les symboles mappés aux noms de colonnes d'origine avec n, la signification, la lecture, les avertissements.
• Chaque KPI requis est soit calculé, soit listé sous « Non calculé » avec les données ou paramètres qui le permettraient.
• Aucun KPI exclu n'apparaît nulle part sauf sur la ligne unique « Exclu » (vérifiez aussi le CSV).
• Le modèle de collecte et chaque hypothèse sont énoncés ; chaque jugement est soit demandé, soit énoncé et testé comme une variante de sensibilité.
• Tableau de santé des données présent ; les indicateurs sur les entrées des KPI clés mentionnés dans les résultats.
• Chaque KPI trouvé dans une référence est soit calculé (avec citation, emplacement, définition et adaptation montrés) soit listé sous « Non calculé » avec ce qui le permettrait ; les valeurs rapportées sont étiquetées comme citées.
• kpi_results.csv (UTF-8 avec BOM) et kpi_run.py écrits, et chaque livrable remis à l'utilisateur selon « Où vont les sorties » (téléchargements + artefact de rapport dans les applications Claude ; chemins et fiches de fichiers dans Claude Code).
• Graphique uniquement si le focus concerne un changement dans le temps.
• Domaine sans pack dans references/fields/ : proposez un pack de domaine construit à partir des KPI utilisés dans cette exécution, sous forme de fichier Markdown séparé suivant references/fields/_template.md, pour que l'utilisateur le révise et l'ajoute. Ne l'écrivez pas dans le dossier de la compétence.

Non-objectifs

Pas de prévisions ou de construction de modèles (la compétence évalue les prédictions qui lui sont données). Pas de flux en direct ou de bases de données. Pas de conseils en investissement, médical ou d'ingénierie : rapportez les métriques et ce qu'elles indiquent. Pas de conversion de devises : les devises mixtes sont signalées et calculées par devise.

Valeurs par défaut (utiliser sans demander, indiquer lorsqu'elles sont utilisées)

Paramètre	Par défaut
Taux sans risque	0
Facteur d'annualisation	jours ouvrés quotidiens 252, calendaire quotidien 365, hebdomadaire 52, mensuel 12, trimestriel 4, horaire 8760
Période saisonnière MASE	horaire 24, quotidien 7, hebdomadaire 52, mensuel 12, trimestriel 4, sinon 1
Seuil d'irrégularité	CV de l'intervalle > 0,5
Seuil d'écart	3 × intervalle médian
Taux d'analyse des colonnes temporelles	≥ 95 %
Échantillonnage du profil	> 1 000 000 lignes → échantillon de 200 000 lignes (colonne temporelle toujours lue en entier)
max_kpis	12 (uniquement les choix de Claude)
Gestion des pourcentages	valeurs 0–100 dans une colonne dont les heuristiques...