Détail des commandes de knitproof, de l’organisation du code et de la contribution. Le README en donne l’essentiel.
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.
Pour les données Ravelry, copier .env.example en .env et y renseigner ses identifiants d’API. Le fichier .env n’est jamais versionné.
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 ollamaKimi : 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.
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) outest(15 cas, N = 45) ; ne lancertestqu’après le gel du prompt.--models: des entréesfournisseur[: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’estKNITPROOF_<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 :openrouteretopenrouter:<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 partagentKNITPROOF_OPENROUTER_TEMPERATURE. Les variantes:nitroet:floorchangent le routage ; leur effet avec@hébergeurn’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/resultspar défaut. Le YAMLAAAA-MM-JJTHHMM-<split>.yamln’écrase jamais un fichier.- Chaque entrée demande une température explicite,
KNITPROOF_<P>_TEMPERATUREou, à défaut,KNITPROOF_LLM_TEMPERATURE, à0ouomit(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.jsonldu 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, gardemeasured_on, le nom du YAML et leatde 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--modelsdiffèrent est refusé avant tout appel, en nommant le champ (code 3) ; l’ordre des entrées de--modelsdoit ê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_RETRIESfois ; les réessais propres aux SDK sont coupés. L’attente estKNITPROOF_LLM_HTTP_WAIT× 2^(essai − 1), portée auRetry-Afterdu 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 sesattempts, et sa latence ne compte que l’essai qui répond.
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 |
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.yamlLe 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é.
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.yamlLe 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.pyLire 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 queknitproof verify, avec le rang. Par exemple, surexamples/bonnet-erreur-rang-33.yaml:Rang 33 — nombre de mailles incohérent, puisAnnoncé : 89 m · Calculé : 90 m. Pour unrepeat_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 pytestne lit jamaislocal-patterns/. Préfixer la commande, ne pas exporter la variable.
Limites :
- Seules
work,k2tog,m1etrepeatsont prises en charge ; les diminutions des patrons synthétiques sont toutes écrites enk2tog. 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 calccalcule et contrôle le montage d’un seul point (multiple et reste saisi), au plus proche, en dessous en cas d’égalité ;knitproof verifyne 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 calcsignale la différence entre l’échantillon et le projet (swatch_needle_mismatch) ;verifyne 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.
- GitHub supprime la branche distante au merge ; en local,
git fetch -ppuisgit branch -d <branche>(sans worktree ouvert :git fetch -pdé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 danssrc/(PLR2004) ; l’apostrophe typographique et les espaces insécables sont permis. mypy refuseAny(ADR 0012). Les conventions que les outils ne vérifient pas sont dansAGENTS.md.