Metadata-Version: 2.4
Name: pommes-assistant
Version: 0.1.1
Summary: Deterministic backbone of a conversational assistant for pommes energy-system studies: StudySpec with provenance, validator, catalogue, tools
Author-email: Robin Girard <robin.girard@minesparis.psl.eu>
License-Expression: MIT
Project-URL: Repository, https://git.persee.minesparis.psl.eu/energy-alternatives/pommes-assistant
Keywords: energy,energy system modelling,pommes,provenance,LLM tools,MCP
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Natural Language :: French
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pyyaml<7,>=6
Provides-Extra: pommes
Requires-Dist: pommes<0.7,>=0.5; extra == "pommes"
Provides-Extra: craft
Requires-Dist: pommes_craft>=0.5.1; extra == "craft"
Requires-Dist: polars>=0.20; extra == "craft"
Provides-Extra: data
Requires-Dist: polars>=0.20; extra == "data"
Requires-Dist: xarray>=2024.1; extra == "data"
Requires-Dist: h5netcdf>=1.3; extra == "data"
Requires-Dist: numpy>=1.26; extra == "data"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.2; extra == "mcp"
Provides-Extra: views
Requires-Dist: plotly>=6; extra == "views"
Requires-Dist: matplotlib>=3.8; extra == "views"
Requires-Dist: xarray>=2024.1; extra == "views"
Requires-Dist: h5netcdf>=1.3; extra == "views"
Requires-Dist: numpy>=1.26; extra == "views"
Requires-Dist: hdf5plugin>=4; extra == "views"
Provides-Extra: all
Requires-Dist: pommes<0.7,>=0.6; extra == "all"
Requires-Dist: pommes_craft>=0.5.1; extra == "all"
Requires-Dist: linopy>=0.8; extra == "all"
Requires-Dist: highspy>=1.7; extra == "all"
Requires-Dist: polars>=0.20; extra == "all"
Requires-Dist: xarray>=2024.1; extra == "all"
Requires-Dist: h5netcdf>=1.3; extra == "all"
Requires-Dist: numpy>=1.26; extra == "all"
Requires-Dist: mcp<3,>=2.2; extra == "all"
Requires-Dist: plotly>=6; extra == "all"
Requires-Dist: matplotlib>=3.8; extra == "all"
Requires-Dist: hdf5plugin>=4; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: anyio>=4; extra == "dev"
Dynamic: license-file

# pommes-assistant

Ossature déterministe d'un assistant conversationnel pour les études
[pommes](https://git.persee.minesparis.psl.eu/energy-alternatives/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

```bash
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](https://ollama.com), 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) :

  ```bash
  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) :

  ```python
  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 passage n'a écrit de nombre inventé depuis le 5 octobre 2026 (session S19), quel que
soit le modèle. Les trois inventions vues avant (Claude au premier passage, une version de travail du
26B, le 12B une fois) ont chacune fermé un trou de l'ossature : c'est elle qui 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

```bash
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

```bash
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.
