Files
Support-AI/agents/support/outils.py
T
2026-11-09 08:35:00 +01:00

297 lines
17 KiB
Python

"""Les outils des deux agents : leurs schémas pour l'API, et la Boite qui les exécute sur le poste.
Tout outil lance une copie de `API/tools/` par `subprocess`, n'écrit que dans le dossier de la séance (et dans la fabrique
Typst `tools/typst/{documents,build}/`), et lève ErreurOutil sur une erreur : l'agent la rend au modèle en `is_error`.
"""
import base64
import io
import json
import os
import re
import shutil
import subprocess
from datetime import datetime
from pathlib import Path
from typing import Callable
from PIL import Image
API = Path(__file__).resolve().parents[1]
PY = str(API / ".venv" / "bin" / "python")
TOOLS = API / "tools"
TYPST = TOOLS / "typst"
KNOWLEDGE = API / "knowledge"
LECTURE = {"inventaire", "resume", "plages", "jours", "vignettes", "qualite", "ensemble", "graphique", "metriques",
"stations"}
AVEC_SORTIE = {"graphique", "ensemble", "jours", "metriques", "vignettes", "qualite", "stations"} # ceux qui écrivent des PNG
DELAI = 600 # s
VOIR = 1000 # px : les images regardées restent dans l'historique et repartent à chaque appel
NOM = re.compile(r"^[A-Za-z0-9_-]+$")
INSTANT = re.compile(r"^\d{8}T\d{4}Z$") # AAAAMMJJTHHMMZ, comme le début du nom des images
PROCHE = 90 # min : au-delà, pas d'image « à cette heure »
class ErreurOutil(Exception):
pass
def plafonner(texte: str, n: int = 40_000) -> str:
return texte if len(texte) <= n else texte[:n] + f"\n[… tronqué : {len(texte)} caractères]"
def section(texte: str, titre: str) -> str:
"""La section d'un markdown dont le titre contient `titre` (sans la casse), jusqu'au titre suivant de même niveau ou
plus haut ; lève ErreurOutil avec la liste des titres si aucun ne convient."""
lignes = texte.splitlines()
titres = [(i, len(l) - len(l.lstrip("#"))) for i, l in enumerate(lignes) if l.startswith("#")]
for k, (i, niveau) in enumerate(titres):
if titre.lower() in lignes[i].lstrip("#").strip().lower():
fin = next((j for j, n in titres[k + 1:] if n <= niveau), len(lignes))
return "\n".join(lignes[i:fin]).strip()
raise ErreurOutil(f"pas de section « {titre} » ; sections : " + " | ".join(lignes[i].strip() for i, _ in titres))
def bloc_image(chemin: Path, cote: int = 1568) -> dict:
"""Image -> bloc image de l'API, plus grand côté ≤ cote px (au-delà de 1568, l'API la réduirait de toute façon)."""
im = Image.open(chemin)
im.thumbnail((cote, cote))
jpeg = Path(chemin).suffix.lower() in (".jpg", ".jpeg")
if im.mode not in ("RGB", "L"):
im = im.convert("RGB")
tampon = io.BytesIO()
im.save(tampon, "JPEG" if jpeg else "PNG")
return {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg" if jpeg else "image/png",
"data": base64.b64encode(tampon.getvalue()).decode()}}
def _schema(nom: str, description: str, props: dict) -> dict:
return {"name": nom, "description": description, "strict": True,
"input_schema": {"type": "object", "properties": props, "required": list(props),
"additionalProperties": False}}
S, I = {"type": "string"}, {"type": "integer"}
LISTE = {"type": "array", "items": {"type": "string"}}
OUTILS_ANALYSTE = [
_schema("detecteurs", "Les événements des détecteurs du journal sur une plage : famille, sorte, capteurs, phrase. "
"du et au : AAAA-MM-JJ, UTC, au exclu.", {"station": S, "du": S, "au": S}),
_schema("stabilite", "La stabilité verticale chiffrée : pour chaque cible, la médiane de corr_y jour par jour et "
"l'étendue de ces médianes (de combien elle a varié d'un jour à l'autre), mesures rejetées écartées ; hors : "
"plages à écarter, AAAA-MM-JJTHH:MMZ/AAAA-MM-JJTHH:MMZ (les nuits de visibilité réduite). du, au : AAAA-MM-JJ, "
"au exclu.", {"station": S, "du": S, "au": S, "hors": LISTE}),
_schema("lire_document", "Lit un document de ton savoir (l'index de ton prompt), entier (section vide) ou une seule "
"section par son titre (ex. une fiche de la carte des étiquettes : « La pluie »).", {"nom": S, "section": S}),
_schema("outil_de_lecture", "Lance un outil de lecture (lire-les-donnees.md) : nom parmi " + ", ".join(sorted(LECTURE))
+ ". arguments : la ligne de commande après le nom du script, data/<STATION> pour le dossier.",
{"nom": S, "arguments": LISTE}),
_schema("figure_courbes", "Figure corr_y à plage grisée (figure-y.py) dans le dossier de la séance, <nom>.png. "
"debut, fin : AAAA-MM-JJTHH:MMZ. options : --cam tilt,pan, --temp, --zone D/F, --ligne T, --hauteur 5…",
{"nom": S, "debut": S, "fin": S, "cibles": LISTE, "options": LISTE}),
_schema("image_de_la_cause", "Recadrages éclaircis côte à côte autour d'une cible (x, y : pixel dans l'image entière), "
"<nom>.png. instants : AAAAMMJJTHHMMZ=légende (l'image la plus proche de chaque heure), d'abord un instant "
"sans la cause. cibles : les seules cibles dont le nom est écrit, celles dont parle la diapositive.",
{"nom": S, "x": I, "y": I, "instants": LISTE, "cibles": LISTE}),
_schema("voir_image", "Regarder une image : un fichier du dossier de la séance (ex. bosse.png), ou une image de la "
"caméra, images/AAAAMMJJTHHMMZ (la plus proche de cette heure UTC) ou images/<fichier>.", {"chemin": S}),
]
OUTILS_SUPPORT = [
_schema("poser_station", "Fixe la station de la séance (un dossier de données) et le sujet en 2-3 mots "
"(ex. courbes-bruitees) ; rend ce que la station a comme données.", {"station": S, "sujet": S}),
_schema("demander_analyste", "Envoie un message à l'analyste (station, plage UTC, question ; ou un retour de fond) "
"et rend sa réponse.", {"message": S}),
_schema("ecrire_presentation", "Écrit le source Typst complet de la présentation dans le dossier de la séance.",
{"source_typ": S}),
_schema("compiler", "Compile la présentation : rend la version (v1.pdf, v2.pdf…), le nombre de diapositives qui "
"débordent et les remarques du lint, ou l'erreur de Typst.", {}),
_schema("voir_page", "Regarder la page n (à partir de 1) de la dernière version du PDF.", {"n": I}),
]
PIECES = (".png", ".jpg", ".jpeg", ".gif") # ce qu'un mail peut joindre, du dossier de la séance
# La sortie mail : sans les outils de la présentation, avec ecrire_mail
OUTILS_SUPPORT_MAIL = [o for o in OUTILS_SUPPORT if o["name"] in ("poser_station", "demander_analyste")] + [
_schema("ecrire_mail", "Écrit une version du mail de réponse (mail-v1.json, mail-v2.json…) : le corps, et les "
"fichiers du dossier de la séance à joindre (.png, .jpg, .gif ; liste vide : aucun).",
{"texte": S, "pieces_jointes": {"type": "array", "items": S}}),
]
class Boite:
def __init__(self, dossier_seance: Callable[[], Path], station: Callable[[], str | None], donnees: Path,
demander_analyste: Callable[[str], str], poser: Callable[[str, str], Path]):
self.dossier, self.station, self.donnees = dossier_seance, station, Path(donnees)
self.demander_analyste, self.poser = demander_analyste, poser
# --- aides
def _lancer(self, args: list[str], env: dict | None = None) -> str:
try:
r = subprocess.run(args, cwd=self.dossier(), capture_output=True, text=True, timeout=DELAI,
env={**os.environ, **(env or {})})
except subprocess.TimeoutExpired:
raise ErreurOutil(f"délai de {DELAI} s dépassé : {' '.join(args[1:3])}")
sortie = (r.stdout + ("\n" + r.stderr if r.stderr.strip() else "")).strip()
if r.returncode:
raise ErreurOutil(plafonner(sortie or f"code de sortie {r.returncode}"))
return plafonner(sortie or "(rien)")
def _station(self, station: str | None = None) -> Path:
station = station or self.station()
if not station:
raise ErreurOutil("pas encore de station : le support doit d'abord appeler poser_station")
if not NOM.match(station) or not (self.donnees / station).is_dir():
raise ErreurOutil(f"station inconnue : {station} (pas de dossier dans les données)")
return self.donnees / station
def _nom(self, nom: str) -> str:
if not NOM.match(nom):
raise ErreurOutil(f"nom de fichier refusé : {nom} (lettres, chiffres, - et _)")
return nom
def _data(self, a: str) -> str:
return str(self.donnees) + a[4:] if a == "data" or a.startswith("data/") else a
def _image_proche(self, instant: str) -> Path:
"""L'image de la station la plus proche de l'instant (les images tombent à :00 ou :01, à un nom près)."""
t = datetime.strptime(instant, "%Y%m%dT%H%MZ")
ecart = lambda p: abs((datetime.strptime(p.name[:14], "%Y%m%dT%H%MZ") - t).total_seconds()) # noqa: E731
images = [p for p in (self._station() / "images").glob("*.jpg") if INSTANT.match(p.name[:14])]
proche = min(images, key=ecart, default=None)
if not proche or ecart(proche) > PROCHE * 60:
raise ErreurOutil(f"pas d'image à moins de {PROCHE} min de {instant}")
return proche
def _image(self, chemin: str) -> Path:
if chemin.startswith("images/") and INSTANT.match(chemin[7:21]) and not (self._station() / chemin).is_file():
return self._image_proche(chemin[7:21])
if chemin.startswith("images/"):
base = self._station() / "images"
p = (base / chemin[7:]).resolve()
else:
base = self.dossier()
p = (base / chemin).resolve()
if Path(chemin).is_absolute() or not p.is_relative_to(base.resolve()) or not p.is_file():
raise ErreurOutil(f"image refusée ou absente : {chemin}")
return p
def _versions(self) -> list[Path]:
return sorted(self.dossier().glob("v*.pdf"), key=lambda p: int(p.stem[1:]))
# --- l'analyste
def executer_analyste(self, nom: str, e: dict):
if nom == "detecteurs":
return self._lancer([PY, str(TOOLS / "journal.py"), str(self._station(e["station"])), "--du", e["du"],
"--au", e["au"]])
if nom == "lire_document":
p = KNOWLEDGE / "analyste" / e["nom"]
if "/" in e["nom"] or not p.is_file():
raise ErreurOutil(f"document inconnu : {e['nom']} ; documents : "
+ ", ".join(sorted(f.name for f in (KNOWLEDGE / "analyste").iterdir())))
texte = p.read_text()
return plafonner(section(texte, e["section"]) if e["section"].strip() else texte)
if nom == "stabilite":
return self._lancer([PY, str(TOOLS / "stabilite.py"), str(self._station(e["station"])), "--du", e["du"],
"--au", e["au"], *(["--hors", *e["hors"]] if e["hors"] else [])])
if nom == "outil_de_lecture":
if e["nom"] not in LECTURE:
raise ErreurOutil(f"outil inconnu : {e['nom']} (permis : {', '.join(sorted(LECTURE))})")
args = [self._data(a) for a in e["arguments"]]
if e["nom"] in AVEC_SORTIE:
args += ["--sortie", str(self.dossier())]
return self._lancer([PY, str(TOOLS / "agent-tools" / f"{e['nom']}.py"), *args])
if nom == "figure_courbes":
sortie = self.dossier() / f"{self._nom(e['nom'])}.png"
self._lancer([PY, str(TOOLS / "figures" / "figure-y.py"), str(self._station()), str(sortie), e["debut"],
e["fin"], "--cibles", ",".join(e["cibles"]), *e["options"]])
return f"{sortie.name} écrite ; la regarder avec voir_image avant de la garder"
if nom == "image_de_la_cause":
sortie = self.dossier() / f"{self._nom(e['nom'])}.png"
instants = [] # chaque instant ramené à l'image la plus proche, sa légende gardée
for i in e["instants"]:
k, egal, legende = i.partition("=")
instants.append(self._image_proche(k).name[:14] + egal + legende)
self._lancer([PY, str(TOOLS / "figures" / "image-de-la-cause.py"), str(self._station()), str(e["x"]),
str(e["y"]), str(sortie), *instants, *(["--cibles", ",".join(e["cibles"])] if e["cibles"] else [])])
return (f"{sortie.name} écrite, images : {', '.join(i.partition('=')[0] for i in instants)} ; "
"la regarder avec voir_image avant de la garder")
if nom == "voir_image":
return [bloc_image(self._image(e["chemin"]), VOIR)]
raise ErreurOutil(f"outil inconnu : {nom}")
# --- le support
def executer_support(self, nom: str, e: dict):
if nom == "poser_station":
dossier = self._station(e["station"])
self.poser(e["station"], self._nom(e["sujet"]))
sous = ", ".join(f"{d.name} ({sum(1 for _ in d.iterdir())} fichiers)" for d in sorted(dossier.iterdir())
if d.is_dir())
return f"station {e['station']} posée ; données : {sous}"
if nom == "demander_analyste":
return self.demander_analyste(e["message"])
if nom == "ecrire_presentation":
p = self.dossier() / f"{self._station().name.lower()}.typ"
p.write_text(e["source_typ"])
return f"{p.name} écrit ({len(e['source_typ'])} caractères)"
if nom == "compiler":
return self._compiler()
if nom == "voir_page":
return self._voir_page(int(e["n"]))
if nom == "ecrire_mail":
return self._ecrire_mail(e["texte"], e["pieces_jointes"])
raise ErreurOutil(f"outil inconnu : {nom}")
def _ecrire_mail(self, texte: str, pieces: list[str]) -> str:
absentes = [p for p in pieces if "/" in p or not p.lower().endswith(PIECES) or not (self.dossier() / p).is_file()]
if absentes:
raise ErreurOutil(f"pièces refusées ou absentes du dossier de la séance : {', '.join(absentes)}")
version = self.dossier() / f"mail-v{len(list(self.dossier().glob('mail-v*.json'))) + 1}.json"
version.write_text(json.dumps({"texte": texte, "pieces_jointes": pieces}, ensure_ascii=False, indent=1))
return f"{version.name} écrit ({len(texte)} caractères, {len(pieces)} pièce(s) jointe(s))"
def _compiler(self) -> str:
station = self._station().name.lower()
source = self.dossier() / f"{station}.typ"
if not source.exists():
raise ErreurOutil("pas de source : appeler ecrire_presentation d'abord")
slug = f"{station}-support"
doc = TYPST / "documents" / slug
shutil.rmtree(doc, ignore_errors=True)
doc.mkdir(parents=True)
shutil.copy(source, doc / "main.typ")
for png in self.dossier().glob("*.png"):
shutil.copy(png, doc)
env = {"PATH": f"{Path.home() / '.local' / 'bin'}:{os.environ.get('PATH', '')}"}
try:
r = subprocess.run([PY, "brand/tools/build.py", slug], cwd=TYPST, capture_output=True, text=True,
timeout=DELAI, env={**os.environ, **env})
except subprocess.TimeoutExpired:
raise ErreurOutil(f"compilation : délai de {DELAI} s dépassé")
sortie = (r.stdout + "\n" + r.stderr).strip()
pdf = TYPST / "build" / f"{slug}-draft.pdf"
if r.returncode or not pdf.exists():
raise ErreurOutil(plafonner(sortie))
version = self.dossier() / f"v{len(self._versions()) + 1}.pdf"
shutil.copy(pdf, version)
pdf.unlink() # la prochaine compilation ratée ne doit pas trouver l'ancien PDF
texte = subprocess.run(["pdftotext", str(version), "-"], capture_output=True, text=True).stdout
remarques = "\n".join(l for l in sortie.splitlines() if "warning" in l and "bare-image" not in l)
return f"{version.name} : {texte.count('Overflow')} diapositive(s) qui débordent" + (
f"\nremarques du lint :\n{plafonner(remarques, 4000)}" if remarques else "")
def _voir_page(self, n: int) -> list[dict]:
versions = self._versions()
if not versions:
raise ErreurOutil("pas encore de PDF : compiler d'abord")
prefixe = self.dossier() / f".page-{n}"
r = subprocess.run(["pdftoppm", "-f", str(n), "-l", str(n), "-png", "-r", "80", str(versions[-1]),
str(prefixe)], capture_output=True, text=True)
pages = sorted(self.dossier().glob(f".page-{n}-*.png"))
if r.returncode or not pages:
raise ErreurOutil(f"page {n} introuvable dans {versions[-1].name}")
bloc = bloc_image(pages[0])
for p in pages:
p.unlink()
return [bloc]