pommes-assistant

Ossature déterministe d'un assistant conversationnel pour les études pommes (planification de systèmes multi-énergies, MINES Paris – PSL / PERSEE). Le LLM n'est qu'une interface remplaçable ; la valeur est dans les outils typés, utilisables sans lui.

Vous décrivez votre étude en français ; l'assistant remplit le fichier d'étude (le StudySpec), pose les questions qui manquent, esquisse le modèle, estime son coût de calcul, le résout et lit les résultats. Aucun nombre n'est inventé : toute valeur vient de vos mots (cités), d'un jeu de données du catalogue, d'un document cité ou d'un défaut de pommes marqué comme tel. L'outil refuse toute écriture qui ne cite pas sa source.

Mode d'emploi complet : docs/guide.md (dans le dépôt).

Installation

pip install "pommes-assistant[all]"     # l'assistant, pommes, pommes_craft, HiGHS, les vues
pip install pommes-assistant            # le cœur seul : lire et valider un StudySpec

Python 3.12 au moins. Pour un modèle local : Ollama, puis ollama pull gemma4:26b (≈ 20 Go de mémoire).

Trois façons de s'en servir

• Claude Code (VS Code, PyCharm, terminal ; abonnement Claude), la voie la plus sûre (29 dialogues de test sur 30) :

  claude mcp add pommes-assistant -- pommes-assistant mcp     # dans votre projet
  pommes-assistant skill --install .                          # la marche de l'assistant
  

• Python ou un notebook, avec un modèle ouvert servi par Ollama (gemma4:26b : 28 à 30 sur 30) :

  from pommes_assistant import Assistant
  
  assistant = Assistant()
  assistant("Mon étude est le fichier mon_etude.study.yaml. Dis-moi ce qui manque.")
  assistant("esquisse-la")
  

• Le terminal : pommes-assistant chat --spec mon_etude.study.yaml.

Au banc, aucun modèle n'a jamais écrit de nombre inventé : c'est l'ossature qui le refuse, pas le modèle qui s'en abstient.

Ce que fait l'ossature

• le StudySpec porte une source par valeur numérique ; le validateur rend des écarts typés, et les questions de l'assistant viennent de lui ;
• le catalogue de jeux certifiés (SL-TYNDP 2024 et PECD) et l'audit d'ordres de grandeur ;
• le compilateur produit une étude pommes ordinaire (le cas TYNDP 8 nœuds à l'identique) ;
• l'esquisse (une heure ou quelques semaines représentatives, en secondes), l'estimation par règle (électrolyseur, cavité d'hydrogène, batterie, demande déplaçable, pilotable) et le regret d'une règle dans son monde, sous le bandeau « pas un résultat » ;
• l'estimateur de taille, de temps et de mémoire ; l'exécution locale ou sur un serveur (soumettre, suivre, rapatrier, sans shell libre) ; le modèle de langage servi par un job GPU Slurm (run llm) ;
• les vues (neuf, en HTML ou PDF) et le rapport Quarto ;
• le serveur MCP, une fonction par action ; le client local (Ollama ou compatible OpenAI) ; le banc de 30 dialogues, qui mesure les inventions et les questions superflues.

Développement

git clone https://git.persee.minesparis.psl.eu/energy-alternatives/pommes-assistant.git
pip install -e ".[all,dev]"
pytest -q                      # sans données ni LLM ; les tests « data » lisent la racine DATA

Commandes

pommes-assistant validate mon_etude.study.yaml           # écarts typés (--json)
pommes-assistant questions mon_etude.study.yaml          # les questions du prochain tour
pommes-assistant spec set-user mon_etude.study.yaml "components[Carbon/carbon].tax" 100 \
    --who "Camille Martin" --quote "une taxe carbone de 100 €/t"
pommes-assistant sketch mon_etude.study.yaml             # esquisse L0 (ou --level L1)
pommes-assistant guess mon_etude.study.yaml              # estimation par règle, sans résolution
pommes-assistant regret mon_etude.study.yaml             # regret d'une règle dans son monde
pommes-assistant estimate mon_etude.study.yaml           # taille, temps et RAM
pommes-assistant build mon_etude.study.yaml -o etude     # une étude pommes ordinaire
pommes-assistant run local etude --dry-run               # ou run submit etude --host …
pommes-assistant results etude/output/<run> --checks --view all --format html,pdf
pommes-assistant import-craft modele_sauve -o mon_etude.study.yaml
pommes-assistant chat --spec mon_etude.study.yaml        # l'assistant au terminal (Ollama)
pommes-assistant mcp                                     # le serveur MCP sur stdio

Documentation dans le dépôt : docs/guide.md (mode d'emploi), docs/studyspec.md (format), docs/compile.md, docs/sketch.md, docs/run.md, docs/views.md, docs/mcp.md, docs/client.md, docs/bench.md ; exemples dans examples/ (TYNDP 8 nœuds, heat_electrification, hub H2 de Fos, dorsale H2, notebook assistant.ipynb).

Licence

MIT — Robin Girard, MINES Paris – PSL.