pommes-assistant 0.1.0__tar.gz

pommes_assistant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Girard, MINES Paris – PSL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pommes_assistant-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+prune tests
+prune docs
+prune examples
+prune output
+global-exclude *.pyc __pycache__

pommes_assistant-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: pommes-assistant
+Version: 0.1.0
+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 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
+
+```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.

pommes_assistant-0.1.0/README.md

@@ -0,0 +1,101 @@
+# 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 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
+
+```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.

pommes_assistant-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+# setuptools>=77: the [project] table uses the PEP 639 licence form (SPDX string +
+# license-files), which older setuptools rejects.
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pommes-assistant"
+# Single source of truth: `pommes_assistant.__version__`, read by setuptools without import.
+dynamic = ["version"]
+description = "Deterministic backbone of a conversational assistant for pommes energy-system studies: StudySpec with provenance, validator, catalogue, tools"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Robin Girard", email = "robin.girard@minesparis.psl.eu" }]
+keywords = ["energy", "energy system modelling", "pommes", "provenance", "LLM tools", "MCP"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Natural Language :: French",
+]
+# The core (spec + validate) must stay light and import neither pommes nor linopy:
+# the CLI answers in well under 2 s. pommes and pommes_craft are optional extras.
+dependencies = [
+    "pydantic>=2.7,<3",
+    "pyyaml>=6,<7",
+]
+
+[project.optional-dependencies]
+# Regenerate the bundled parameter schema from an installed pommes.
+# Snapshots are bundled for 0.5.0 and 0.6.0 ; a StudySpec is validated against its own.
+pommes = ["pommes>=0.5,<0.7"]
+# Import a pommes_craft model.yaml. pommes_craft 0.3.7 pins linopy<0.8, which conflicts with
+# pommes>=0.5 (install it with `pip install --no-deps pommes_craft`); 0.3.8 lifts the pin
+# (pommes_craft!11, 2026-10-05).
+craft = ["pommes_craft>=0.5.1", "polars>=0.20"]
+# Read data: `validate --tables`, catalogue loaders, audit of a pommes Dataset.
+data = ["polars>=0.20", "xarray>=2024.1", "h5netcdf>=1.3", "numpy>=1.26"]
+# The MCP server (``pommes-assistant mcp``); the tools themselves need no mcp.
+mcp = ["mcp>=2.2,<3"]
+# The views (S7): HTML with plotly, PDF/SVG/PNG with matplotlib; zstd result files need
+# hdf5plugin.
+views = ["plotly>=6", "matplotlib>=3.8", "xarray>=2024.1", "h5netcdf>=1.3", "numpy>=1.26",
+         "hdf5plugin>=4"]
+# Everything a user needs : the assistant (MCP tools in process, Ollama or an OpenAI-compatible
+# server), compilation, sketch, guess, regret, runs, views.
+all = ["pommes>=0.6,<0.7", "pommes_craft>=0.5.1", "linopy>=0.8", "highspy>=1.7", "polars>=0.20",
+       "xarray>=2024.1", "h5netcdf>=1.3", "numpy>=1.26", "mcp>=2.2,<3", "plotly>=6",
+       "matplotlib>=3.8", "hdf5plugin>=4"]
+dev = ["pytest>=8", "anyio>=4"]
+
+[project.scripts]
+pommes-assistant = "pommes_assistant.cli:main"
+
+[project.urls]
+Repository = "https://git.persee.minesparis.psl.eu/energy-alternatives/pommes-assistant"
+
+[tool.setuptools.dynamic]
+version = { attr = "pommes_assistant.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"pommes_assistant.spec" = ["schema_data/*.json", "schema_data/*.yaml"]
+"pommes_assistant.catalogue" = ["cards/*.yaml"]
+"pommes_assistant.audit" = ["thresholds.yaml"]
+"pommes_assistant.sketch" = ["thresholds.yaml"]
+"pommes_assistant.run" = ["llm_data/*"]
+"pommes_assistant.mcp" = ["skill/SKILL.md"]
+"pommes_assistant.guess" = ["settings.yaml", "validation.yaml"]
+"pommes_assistant.views" = ["*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "data: reads the real datasets under ${DATA} (skipped when the root is not configured)",
+]

pommes_assistant-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pommes_assistant-0.1.0/src/pommes_assistant/__init__.py

@@ -0,0 +1,13 @@
+"""pommes-assistant: deterministic backbone for describing, building, running and
+exploiting pommes energy-system studies, with the provenance of every number."""
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    """``from pommes_assistant import Assistant`` without loading the client at import time."""
+    if name in ("Assistant", "Answer"):
+        from pommes_assistant import assistant
+
+        return getattr(assistant, name)
+    raise AttributeError(f"module 'pommes_assistant' has no attribute {name!r}")

pommes_assistant-0.1.0/src/pommes_assistant/assistant.py

@@ -0,0 +1,179 @@
+"""The assistant from Python : a notebook, a script, an IDE console (S35).
+
+.. code-block:: python
+
+    from pommes_assistant import Assistant
+
+    assistant = Assistant(host="slurm")            # gemma4:26b served from a GPU job (run llm)
+    assistant("Mon étude est le fichier etude.study.yaml. Esquisse-la.")
+    assistant("combien de temps prendrait le modèle complet ?")
+    assistant.close()                              # the job it submitted is cancelled
+
+The same tool loop as ``pommes-assistant chat`` and the bench (:class:`~pommes_assistant.
+client.Agent`), with the same policy and the same guards : no number without a source, the
+questions from the validator. A local model by default (Ollama on this machine), or one served
+from a host of the profile (``host=``, :class:`~pommes_assistant.run.llm.Serving` : the job is
+submitted on the first call, held, and cancelled by :meth:`Assistant.close`, by a ``with``
+block, or at the end of the process), or any OpenAI-compatible server (``backend="openai"``,
+``base_url=``). Claude itself is reached through Claude Code (VS Code, PyCharm : the MCP
+server of ``.mcp.json``), not from here : no API key (decision of 2026-09-27).
+
+Each call returns an :class:`Answer`, which a notebook shows as Markdown : the answer, then the
+tools called (refused ones marked), the time and, if any, the wait for an unreachable server.
+"""
+
+from __future__ import annotations
+
+import atexit
+import html
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+#: as each model was measured (``cli.DEFAULT_THINK``) : the 26B thinks, the 12B does not
+DEFAULT_THINK = {"gemma4:26b": True}
+
+
+@dataclass
+class Answer:
+    """One answer of the assistant."""
+
+    text: str
+    tool_uses: list[dict[str, Any]] = field(default_factory=list)
+    error: str | None = None
+    duration_s: float = 0.0
+    waited_s: float = 0.0
+
+    def __str__(self) -> str:
+        return self.text + (f"\n\n[erreur : {self.error}]" if self.error else "")
+
+    def _repr_markdown_(self) -> str:
+        parts = [self.text or "*(pas de réponse)*"]
+        if self.error:
+            parts.append(f"> **Erreur** : {self.error}")
+        if self.tool_uses:
+            rows = []
+            for u in self.tool_uses:
+                args = {k: v for k, v in (u.get("args") or {}).items() if k != "spec_file"} \
+                    if isinstance(u.get("args"), dict) else u.get("args")
+                shown = html.escape(json.dumps(args, ensure_ascii=False, default=str))
+                if len(shown) > 160:
+                    shown = shown[:157] + "…"
+                rows.append(f"<li><code>{u['tool']}</code>{'' if u.get('ok') else ' — refusé'}"
+                            f" <small>{shown}</small></li>")
+            parts.append(f"<details><summary>{len(self.tool_uses)} appel(s) d'outil</summary>"
+                         f"<ul>{''.join(rows)}</ul></details>")
+        tail = f"{self.duration_s:.0f} s"
+        if self.waited_s:
+            tail += f", dont {self.waited_s:.0f} s d'attente du serveur"
+        parts.append(f"<small>{tail}</small>")
+        return "\n\n".join(parts)
+
+
+class Assistant:
+    """A conversation with the assistant (see the module's docstring).
+
+    Args:
+        model: the model's name on the server (``gemma4:26b`` by default, the measured one).
+        host: a host of the profile that serves the model from a GPU job (``run llm``) ; the
+            job is submitted on the first call if none runs, held, and cancelled on close.
+        base_url: the server's address (default : Ollama on this machine, or the tunnel of
+            ``host``).
+        backend: ``ollama`` (native API : context length and thinking per request) or
+            ``openai`` (any OpenAI-compatible server).
+        think: thinking on or off ; default : as the model was measured.
+        workdir: the folder relative paths are read from (default : the current one).
+        wait_minutes: how long a call waits for an unreachable server (VPN, a job starting).
+        verbose: print each tool call as it happens.
+        chat: a chat model already made (tests) ; ``model``, ``backend`` and ``base_url`` are
+            then not used.
+    """
+
+    def __init__(self, model: str = "gemma4:26b", *, host: str | None = None,
+                 base_url: str | None = None, backend: str = "ollama",
+                 think: bool | str | None = None, workdir: str | Path | None = None,
+                 wait_minutes: float = 10.0, max_tokens: int | None = 8192,
+                 num_ctx: int = 65536, job_time: str | None = None, verbose: bool = False,
+                 chat: Any = None) -> None:
+        self.model, self.host, self.base_url, self.backend = model, host, base_url, backend
+        self.think = DEFAULT_THINK.get(model, False) if think is None else think
+        self.workdir = Path(workdir or Path.cwd()).resolve()
+        self.wait_minutes, self.max_tokens, self.num_ctx = wait_minutes, max_tokens, num_ctx
+        self.job_time, self.verbose = job_time, verbose
+        self.answers: list[Answer] = []
+        self._chat, self._agent, self._serving = chat, None, None
+        self._closed = False
+        atexit.register(self.close)
+
+    # -------------------------------------------------------------------- lifecycle
+    def _serve(self) -> str | None:
+        """The base URL of the host's tunnel, the job submitted and held if needed."""
+        if self.host is None:
+            return None
+        if self._serving is None:
+            from pommes_assistant.run.llm import Serving
+            from pommes_assistant.run.profile import host as host_of
+
+            serving = Serving(host_of(self.host), time_limit=self.job_time,
+                              log=lambda m: print(f"[run llm] {m}", flush=True))
+            serving.__enter__()
+            self._serving = serving
+        return self._serving.base_url
+
+    def _make_agent(self) -> Any:
+        from pommes_assistant.client import Agent, ToolBox, chat_model
+
+        chat = self._chat
+        if chat is None:
+            url = self.base_url or self._serve()
+            options: dict[str, Any] = {"max_tokens": self.max_tokens,
+                                       "wait_s": 60.0 * self.wait_minutes,
+                                       "on_wait": lambda m: print(f"[serveur] {m}", flush=True)}
+            if self.backend == "ollama":
+                options.update(num_ctx=self.num_ctx, think=self.think)
+            chat = chat_model(self.backend, self.model, url, **options)
+        elif self.host is not None:
+            self._serve()
+
+        def show(kind: str, data: dict[str, Any]) -> None:
+            if kind == "tool":
+                state = "ok" if data["ok"] else "refusé"
+                print(f"  · {data['name']} → {state}", flush=True)
+
+        return Agent(chat, ToolBox(self.workdir), on_event=show if self.verbose else None)
+
+    def close(self) -> None:
+        """End the conversation ; the job this assistant submitted is cancelled."""
+        if self._closed:
+            return
+        self._closed = True
+        if self._serving is not None:
+            self._serving.__exit__(None, None, None)
+            self._serving = None
+
+    def __enter__(self) -> Assistant:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -------------------------------------------------------------------- conversation
+    def __call__(self, message: str) -> Answer:
+        """Send one message ; the answer comes back when the model has finished its turn."""
+        if self._closed:
+            raise RuntimeError("cet assistant est fermé : en créer un nouveau")
+        if self._agent is None:
+            self._agent = self._make_agent()
+        turn = self._agent.send(message)
+        answer = Answer(turn.text, list(turn.tool_uses), turn.error, turn.duration_s,
+                        getattr(turn, "waited_s", 0.0))
+        self.answers.append(answer)
+        return answer
+
+    ask = __call__
+
+    def __repr__(self) -> str:
+        where = self.host or self.base_url or "Ollama local"
+        return (f"Assistant({self.model}, {where}, {len(self.answers)} réponse(s)"
+                + (", fermé" if self._closed else "") + ")")

pommes_assistant-0.1.0/src/pommes_assistant/audit/__init__.py

@@ -0,0 +1,5 @@
+"""Audit of the inputs (F10): indicators on an assembled pommes Dataset, compared to sourced
+references with sourced thresholds. Never a correction: error / warning / info lines only.
+
+Needs the ``data`` extra (xarray; polars for references read from the catalogue).
+"""