Gérer sa base de données d'ingrédients

Gram utilise un fichier local ingredients.yaml pour stocker les données physiques et nutritionnelles des ingrédients que vous utilisez dans vos recettes. Le maintien de cette base de données permet aux fonctionnalités telles que la Standardisation des Masses, le Calcul des Rendements et l’Estimation Nutritionnelle de fonctionner parfaitement.

Ce guide détaille le workflow standard pour entretenir votre base de données à l’aide du CLI Gram.

Le workflow recommandé

Le workflow recommandé se compose de trois étapes, à exécuter dans cet ordre précis :

1. Synchroniser les nouveaux ingrédients

   En rédigeant de nouvelles recettes, vous utiliserez inévitablement des ingrédients qui manquent à l’appel dans votre base. Au lieu de les ajouter à la main, laissez le CLI s’en charger.

   gram db sync

   Cette commande scanne tous les fichiers .gram de votre projet. Si elle trouve un ingrédient (ex : @lait de coco{200 ml}) qui n’existe pas dans ingredients.yaml, elle lui ajoutera une entrée vierge.

   Astuce

   Le CLI utilise une recherche approximative (fuzzy matching) pour détecter les fautes de frappe et vous éviter de créer des doublons !

2. Nettoyage et déduplication (Linting)

   Parfois, vous pourriez écrire @œuf dans une recette et @œufs dans une autre. Ou bien @sugar et @sucre si vous écrivez dans plusieurs langues.

   gram db lint

   Cette commande s’appuie sur l’IA (voir Configurer l’IA) pour détecter les doublons sémantiques au sein de votre base de données. Si elle trouve œuf et œufs, elle vous demandera lequel conserver comme clé principale. Elle fusionnera ensuite l’autre dans la liste des aliases (alias) de la clé principale.

   Astuce

   L’IA respecte la langue par défaut définie dans config.yaml. Si elle fusionne des termes anglais et français, elle proposera intelligemment le terme dans votre langue de prédilection comme clé principale !

   Désormais, écrire @œufs pointera automatiquement vers l’entrée de base de données œuf.

   Rien à voir avec la syntaxe d’alias : dans la recette

   La liste aliases sert exclusivement à l’agrégation de la liste de courses pour regrouper les ingrédients entre différentes recettes. Elle n’a aucun rapport avec le renommage ponctuel @Vrai Nom:Nom d'Affichage (voir Syntaxe des ingrédients), qui modifie uniquement l’affichage d’un ingrédient dans le texte des étapes, sans jamais affecter le regroupement ou la liste de courses.

3. Enrichir les données

   v1.1.0

   Maintenant que votre base de données contient des entrées propres et dédupliquées, vous devez renseigner leurs données physiques (densité, poids unitaire, rendement) et nutritionnelles (calories, macros).

   Faire cela manuellement est fastidieux. Gram peut faire appel à l’IA pour proposer ces valeurs à votre place, par lots (voir Configurer l’IA) :

   gram db enrich

   Le CLI récupère les données nutritionnelles standards et les densités pour toutes les entrées incomplètes, puis vous les fait passer en revue une par une pour que vous puissiez accepter, modifier ou passer chaque proposition — la densité et la nutrition sont des données propres à un produit précis (un beurre AOP français n’a pas la même densité qu’un beurre américain), donc seul vous pouvez réellement les valider. category/tags sont peu risqués et s’écrivent automatiquement.

   Cette commande ne comble que les champs manquants, n’écrase jamais les données saisies manuellement, et peut être relancée sans crainte. Une valeur acceptée telle quelle est taguée # [LLM] dans ingredients.yaml, pour repérer les estimations IA jamais relues par un humain.

   Astuce

   Pressé, ou dans un script CI ? gram db enrich --yes ignore la revue et accepte automatiquement toutes les estimations de l’IA. Utilisez gram db enrich --report pour un aperçu de ce qui a besoin d’être revu, sans rien écrire.

Valider la base de données

v1.1.0

Avant de commit votre fichier ingredients.yaml dans votre gestionnaire de versions, il est recommandé de le valider (validate) par rapport au schéma Gram pour s’assurer de l’absence d’erreurs de formatage (comme des alias qui se chevauchent).

gram db validate --strict

Partager et fusionner des bases de données

Si vous travaillez en équipe, ou si vous souhaitez importer une base de données communautaire, vous pouvez fusionner un fichier YAML externe dans votre fichier local :

gram db merge ~/Downloads/community-db.yaml

En cas de conflit (par exemple, la base communautaire indique que le beurre contient 717 kcal, contre 740 kcal dans la vôtre), le CLI vous demandera de manière interactive comment trancher.