Skip to content

Latest commit

 

History

History
144 lines (102 loc) · 16 KB

commandes.md

File metadata and controls

144 lines (102 loc) · 16 KB

Commandes et développement

Détail des commandes de knitproof, de l’organisation du code et de la contribution. Le README en donne l’essentiel.

Organisation du code

domain et engine portent le modèle de patron, le calcul du bonnet et la vérification des comptes de mailles ; app et cli portent les commandes knitproof calc, knitproof verify et knitproof eval ; llm porte la configuration, la fabrique d’agents et l’appel de sortie structurée (voir « Modèles ») ; les autres paquets de src/knitproof/ sont vides pour l’instant. Ils fixent les contrats de couches, que uv run lint-imports vérifie. Les deux exemples de la section « Ce que ça donne » vivent dans examples/ ; leurs sorties de référence vivent dans examples/sorties/ et un test garde les blocs du README contre elles (balise <!-- sortie : … --> avant chaque bloc). Les patrons synthétiques justes vivent dans examples/synthetiques/, et la CI les vérifie tous.

Données Ravelry

Pour les données Ravelry, copier .env.example en .env et y renseigner ses identifiants d’API. Le fichier .env n’est jamais versionné.

Modèles

La couche llm appelle Anthropic, Mistral, OpenAI, OpenRouter, Kimi (Moonshot AI) et un modèle local (Ollama) par pydanticAI (ADR 0033, ADR 0034). Les variables se lisent dans l’environnement ; .env.example les liste, sans valeur.

Variable Rôle
ANTHROPIC_API_KEY, MISTRAL_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, MOONSHOTAI_API_KEY clé du fournisseur, obligatoire pour lui
KNITPROOF_ANTHROPIC_MODEL, KNITPROOF_MISTRAL_MODEL, KNITPROOF_OPENAI_MODEL, KNITPROOF_OPENROUTER_MODEL, KNITPROOF_MOONSHOTAI_MODEL identifiant figé du modèle, obligatoire ; -latest refusé
KNITPROOF_ANTHROPIC_BASE_URL, KNITPROOF_MISTRAL_BASE_URL, KNITPROOF_OPENAI_BASE_URL adresse de l’API, facultative
KNITPROOF_OPENROUTER_HOST slug OpenRouter de l’hébergeur unique, obligatoire pour OpenRouter (provider[/variant][/region][/tier], par exemple deepinfra), copié sur la page du modèle ; aucun repli ; la trace garde le nom que rend la réponse, qui peut différer du slug ; KNITPROOF_OPENROUTER_BASE_URL est refusée
KNITPROOF_OLLAMA_MODEL, KNITPROOF_OLLAMA_BASE_URL modèle local : nom avec étiquette explicite (qwen3:8b, ni :latest ni nom sans étiquette) et adresse, obligatoires ; aucune clé
KNITPROOF_MOONSHOTAI_BASE_URL adresse de Kimi, facultative ; https://api.moonshot.ai/v1 par défaut, https://api.moonshot.cn/v1 pour une clé de la console chinoise
KNITPROOF_LLM_TEMPERATURE entre 0 et 1, facultative
KNITPROOF_ANTHROPIC_TEMPERATURE, KNITPROOF_MISTRAL_TEMPERATURE, KNITPROOF_OPENAI_TEMPERATURE, KNITPROOF_OPENROUTER_TEMPERATURE, KNITPROOF_MOONSHOTAI_TEMPERATURE, KNITPROOF_OLLAMA_TEMPERATURE température du fournisseur, facultative ; prime sur la globale, même vide ; omit n’envoie aucune température
KNITPROOF_LLM_RETRIES relances de sortie, obligatoire (0 ou plus)
KNITPROOF_LLM_HTTP_RETRIES réessais après une erreur passagère (429, 5xx), obligatoire (0 ou plus)
KNITPROOF_LLM_HTTP_WAIT attente avant le premier réessai, en secondes, obligatoire (de 0 à 60) ; elle double à chaque réessai

La température est facultative parce que certains modèles la refusent : Sonnet 5.5 répond 400 si temperature est posé (doc Anthropic) et pydanticAI la retire pour Opus 4.7, 4.8, 5 et 5.5 (doc pydanticAI). Absente, rien n’est envoyé. Les modèles de raisonnement d’OpenAI peuvent aussi refuser temperature, Kimi en direct aussi (non prouvé, à prouver par l’appel live) ; Kimi K3.1 Pro par OpenRouter a accepté 0 le 17/11/2026.

uv run pytest n’appelle jamais un fournisseur : les requêtes réelles sont interdites en test. L’appel de contrôle, un par fournisseur, se lance à la main :

uv run --env-file .env pytest -m live -k anthropic
uv run --env-file .env pytest -m live -k mistral
uv run --env-file .env pytest -m live -k openai
uv run --env-file .env pytest -m live -k openrouter
uv run --env-file .env pytest -m live -k moonshotai
uv run --env-file .env pytest -m live -k ollama

Kimi : créer un compte sur platform.kimi.ai ; la recharge minimale est de 1 $.

Modèle local : installer Ollama, puis ollama pull avec un nom à étiquette explicite (par exemple ollama pull qwen3:8b), et renseigner KNITPROOF_OLLAMA_BASE_URL=http://localhost:11434/v1.

Mesurer la ligne de base « LLM seul »

knitproof eval interroge chaque entrée de --models, 3 fois par cas, avec le prompt figé baseline-cast-on-v1, et juge chaque réponse par le moteur : le tour fini du montage rendu doit tomber à ±1 cm du tour visé (ADR 0035). Une réponse null ou refusée est une abstention, juste seulement sur un cas qui attend l’abstention (aucune jauge).

uv run --env-file .env knitproof eval --split dev --models anthropic,openrouter,ollama
  • --split : dev (5 cas et l’exemple, N = 18) ou test (15 cas, N = 45) ; ne lancer test qu’après le gel du prompt.
  • --models : des entrées fournisseur[:modèle][@hébergeur] séparées par des virgules. Fournisseurs : anthropic, mistral, openai, openrouter, moonshotai, ollama. On coupe au dernier @ (l’hébergeur, OpenRouter seulement), puis au premier : : le reste est le modèle, étiquette Ollama ou suffixe OpenRouter compris (ollama:qwen3:8b, openrouter:x:free). Sans modèle, c’est KNITPROOF_<P>_MODEL ; sans hébergeur, KNITPROOF_OPENROUTER_HOST. Une entrée se définit par son fournisseur, son modèle et son hébergeur résolus : openrouter et openrouter:<modèle de .env> sont le même doublon, refusé. Un modèle vide après :, un hébergeur vide après @, un @ hors OpenRouter ou un fournisseur inconnu sont refusés, avec l’entrée tapée dans le message. La température reste une par fournisseur : deux modèles OpenRouter partagent KNITPROOF_OPENROUTER_TEMPERATURE. Les variantes :nitro et :floor changent le routage ; leur effet avec @hébergeur n’est pas documenté (variantes OpenRouter). Exemple : --models openrouter:mistralai/mistral-small-3.2-24b-instruct@mistral/eu,openrouter:moonshotai/kimi-k3.1-pro@moonshotai,ollama:qwen3:8b.
  • --results : dossier du résultat, evals/results par défaut. Le YAML AAAA-MM-JJTHHMM-<split>.yaml n’écrase jamais un fichier.
  • Chaque entrée demande une température explicite, KNITPROOF_<P>_TEMPERATURE ou, à défaut, KNITPROOF_LLM_TEMPERATURE, à 0 ou omit (modèle qui la refuse : Sonnet 5.5 ; Kimi en direct, non prouvé ; Kimi K3.1 Pro par OpenRouter a accepté 0 le 17/11/2026) ; toute autre valeur est refusée.
  • Sortie : une ligne par entrée, nommée fournisseur:modèle[@hébergeur], k/N [bas ; haut] (intervalle de Wilson à 95 %) et les abstentions. Code 0 si la mesure est faite, 3 si la configuration est invalide ou si le fournisseur répond par une erreur : aucun YAML partiel n’est écrit (règle d’arrêt de CLA-188).
  • Reprise (CLA-203, ADR 0037) : chaque passage est écrit, avec sa lecture, dans <horodatage>-<split>.partial.jsonl du dossier des résultats avant l’appel suivant ; le journal naît au premier passage. Après un arrêt (429 épuisé, 400, 401…), le message nomme le journal : --resume <journal> n’appelle que les passages absents, garde measured_on, le nom du YAML et le at de chaque passage du premier lancement, puis écrit le YAML daté et supprime le journal. Un journal dont le prompt, les passages, le split, les cas ou les entrées --models diffèrent est refusé avant tout appel, en nommant le champ (code 3) ; l’ordre des entrées de --models doit être le même que celui du premier lancement. Un YAML daté déjà présent est refusé avant tout appel. Une ligne finale coupée est ignorée. --resume : chemin du journal ; il n’est pas versionné (*.partial.jsonl).
  • Réessai (CLA-197, ADR 0036) : une réponse 429 ou 5xx est réessayée, au plus KNITPROOF_LLM_HTTP_RETRIES fois ; les réessais propres aux SDK sont coupés. L’attente est KNITPROOF_LLM_HTTP_WAIT × 2^(essai − 1), portée au Retry-After du fournisseur s’il est plus long, et plafonnée à 60 s : avec 3 réessais et 2 s, 2 + 4 + 8 = 14 s au pire par appel. Les essais épuisés arrêtent la mesure (code 3, fournisseur et nombre d’essais nommés) ; tout autre statut (400, 401, 404…) n’est appelé qu’une fois. Chaque passage consigne ses attempts, et sa latence ne compte que l’essai qui répond.

Réglages mesurés

Chaque valeur est relue dans le YAML du résultat, sauf l’hébergeur demandé, noté par la session : les mesures d’avant CLA-199 ne le consignent pas.

Date Fournisseur : modèle Hébergeur demandé Hôte rendu T k/N Résultat
17/11/2026 ollama : qwen3:8b — — 0 18/18 evals/results/2026-11-17T1409-dev.yaml
17/11/2026 openrouter : mistralai/mistral-small-3.2-24b-instruct mistral/eu (.env, lu par la session) Mistral 0 10/18 evals/results/2026-11-17T1428-dev.yaml
17/11/2026 anthropic : claude-opus-5-5 — — non envoyée 18/18 evals/results/2026-11-17T1428-dev.yaml
17/11/2026 openrouter : mistralai/mistral-large-2512 mistral/eu Mistral 0 15/18 evals/results/2026-11-17T1435-dev.yaml
17/11/2026 openrouter : moonshotai/kimi-k3.1-pro moonshotai Moonshot AI 0 18/18 evals/results/2026-11-17T1528-dev.yaml
17/11/2026 openrouter : mistralai/mistral-small-3.2-24b-instruct mistral/eu (.env, lu par la session) Mistral 0 9/18 evals/results/2026-11-17T1443-dev.yaml
17/11/2026 ollama : qwen3:8b — — 0 18/18 evals/results/2026-11-17T1443-dev.yaml
17/11/2026 anthropic : claude-opus-5-5 — — non envoyée 18/18 evals/results/2026-11-17T1443-dev.yaml
17/11/2026 openrouter : mistralai/mistral-small-3.2-24b-instruct mistral/eu (.env, lu par la session) Mistral 0 10/18 evals/results/2026-11-17T1458-dev.yaml
17/11/2026 ollama : qwen3:8b — — 0 18/18 evals/results/2026-11-17T1458-dev.yaml

Calculer un bonnet

La commande knitproof calc lit une demande YAML (format décrit dans docs/architecture.md, section 9), applique l’aisance, calcule le plan du bonnet, contrôle le montage proposé et les aiguilles, puis rend un rapport unique sur stdout.

uv run knitproof calc examples/bonnet-3-ans.yaml

Le code de sortie dit le résultat, et ne se lit pas comme celui de verify :

  • 0 : un plan est calculé, avec ou sans alerte ou rejet dans le rapport ;
  • 1 : des questions restent en attente (par exemple, pas de jauge en rangs, ou un échantillon d’état de blocage inconnu), pas de plan ; les questions sortent sur stdout ;
  • 2 : erreur d’usage (fichier non précisé), message sur stderr ;
  • 3 : fichier absent, illisible ou invalide (clé inconnue, nombre trop grand), message sur stderr, sans trace Python.

Pour verify, 1 veut dire « au moins un constat ».

Les tailles d’aiguilles s’écrivent « 4 mm », « US 6 » ou « US 6 (4 mm) » ; le texte rendu garde la notation saisie et donne les mm de la table, « À VÉRIFIER » sur l’emballage. L’âge, le fil et la fibre ne sont pas lus : leur résolution revient à un ticket de suite et à CLA-121. La jauge se résout : échantillon bloqué, puis non bloqué (« À VÉRIFIER »), puis étiquette (label_gauge, « À VÉRIFIER ») ; un échantillon d’état de blocage inconnu (unknown_blocking) pose la question « l’as-tu bloqué ? » et la réponse se donne en renommant la clé.

Vérifier un patron YAML

La commande knitproof verify vérifie les comptes de mailles d’un fichier au format décrit dans docs/architecture.md, section 9. Un patron réel se range dans local-patterns/, que git ignore : il ne quitte pas votre machine et aucun test de la CI ne le lit.

uv run knitproof verify local-patterns/mon-bonnet.yaml

Le rapport sort sur stdout. Le code de sortie dit le résultat :

  • 0 : aucun constat ;
  • 1 : au moins un constat, rapporté sur stdout ;
  • 2 : erreur d’usage (par exemple, fichier non précisé), message sur stderr ;
  • 3 : fichier absent, illisible ou invalide, message sur stderr, sans trace Python.

Les comptes (cast_on, work, times, start, end, stated_count) sont des entiers nus : une chaîne, un nombre à virgule ou un booléen rend le patron invalide (code 3).

Pour vérifier plusieurs fichiers d’un coup, un test à la demande lit ceux que désigne KNITPROOF_PATTERNS. Depuis la racine du dépôt, un fichier, puis tous ceux d’un dossier (motif glob, entre apostrophes pour que le shell ne le développe pas) :

KNITPROOF_PATTERNS=local-patterns/mon-bonnet.yaml uv run pytest tests/test_pattern_files.py
KNITPROOF_PATTERNS='local-patterns/*.yaml' uv run pytest tests/test_pattern_files.py

Lire le résultat :

  • 1 passed : aucun constat, chaque compte annoncé est celui que calcule le moteur.
  • 1 failed : une ligne par constat, le fichier, puis le même bloc que knitproof verify, avec le rang. Par exemple, sur examples/bonnet-erreur-rang-33.yaml : Rang 33 — nombre de mailles incohérent, puis Annoncé : 89 m · Calculé : 90 m. Pour un repeat_not_fitting, le bloc donne les mailles laissées par le rang précédent et celles que consomment les opérations ; la simulation s’arrête à ce rang.
  • Un motif qui ne trouve aucun fichier, ou un fichier invalide (opération inconnue, clé en trop), échoue avec la raison.
  • Sans la variable, le test est sauté (1 skipped) : uv run pytest ne lit jamais local-patterns/. Préfixer la commande, ne pas exporter la variable.

Limites :

  • Seules work, k2tog, m1 et repeat sont prises en charge ; les diminutions des patrons synthétiques sont toutes écrites en k2tog. Un fichier qui emploie une autre opération est rejeté, et ce rejet ne prouve pas une erreur de calcul.
  • Le multiple du point (côtes 2/2…) n’est pas vérifié : la commande et le test comptent les mailles, ils ne contrôlent pas le montage. knitproof calc calcule et contrôle le montage d’un seul point (multiple et reste saisi), au plus proche, en dessous en cas d’égalité ; knitproof verify ne le vérifie pas. Le rang d’ajustement entre bord et corps (ADR 0025) n’est exposé par aucune commande.
  • Les tailles d’aiguilles de deux systèmes (US, UK, japonais, mm) ne sont pas converties : le moteur avertit qu’il ne peut pas les comparer, sauf si leur taille en mm est connue des deux côtés (écrite en mm, ou saisie à côté d’une autre notation). knitproof calc signale la différence entre l’échantillon et le projet (swatch_needle_mismatch) ; verify ne compare pas les aiguilles.
  • Après un repeat_not_fitting, les comptes annoncés suivants ne sont pas comparés (ADR 0013).
  • Seuls les comptes de mailles sont vérifiés : ni mesures, ni échantillon.

Les patrons synthétiques justes de examples/synthetiques/ sont vérifiés par la CI à chaque uv run pytest, sans variable.

Contribuer

  • GitHub supprime la branche distante au merge ; en local, git fetch -p puis git branch -d <branche> (sans worktree ouvert : git fetch -p déplace les références distantes partagées et annule le lease des worktrees).
  • ruff vérifie aussi le nommage (N), le style pytest (PT), ses propres règles (RUF) et les nombres magiques dans src/ (PLR2004) ; l’apostrophe typographique et les espaces insécables sont permis. mypy refuse Any (ADR 0012). Les conventions que les outils ne vérifient pas sont dans AGENTS.md.