mm init : d'où viennent les réglages d'un agent généré — explication

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# `mm init` : d'où viennent les réglages d'un agent généré — explication

## De quoi s'agit-il ?

`mm init` (ou `mm --init`) écrit un `agent.yaml` commenté à partir de quelques réponses : le serveur de modèles, le modèle, l'usage (développeur, traducteur, docs…), la machine, et s'il faut demander avant chaque modification. Aucun modèle ne tourne pendant l'assistant. Chaque valeur du fichier vient de l'une de quatre sources, et son commentaire dit laquelle. Cette page explique ces sources, comment elles ont été réunies et pourquoi l'assistant leur fait confiance dans cet ordre. Les étapes sont dans [Créer un agent avec `mm init`](../how-to/create-an-agent.md) et les options dans la [référence de la ligne de commande](../reference/cli.md#mm-init--lassistant-agentyaml).

## Les quatre sources, de la plus précise à la plus générale

Le code est dans `internal/agentinit`. `Decide` (`decide.go`) applique les sources dans un ordre de confiance fixe : **ce que dit le serveur de ce modèle, puis la table des familles, puis le profil d'usage, puis la ligne de la machine.** Chaque source ne complète que ce que les précédentes ne savent pas.

### 1. Ce que dit le serveur du modèle (`facts.go`)

Le serveur connaît le modèle exact qui est chargé : c'est la source la plus précise qui existe. L'assistant l'interroge avant de choisir quoi que ce soit :

| Fournisseur | Interrogé | Ce qu'il donne |
|---|---|---|
| `llmman`, `ollama` | `/api/tags`, puis `/api/show` | la liste des modèles, la famille annoncée par le serveur (`details.family`), la fenêtre de contexte native, l'échantillonnage écrit dans le GGUF (`temperature`, `top_p`, `top_k`, `min_p`), le template de chat |
| `llamacpp` | `/props` | la fenêtre et le template de chat |
| `dmr` | `/models` | la liste des modèles seulement |
| `openai` | `/models` (avec la clé) | la liste des modèles seulement |

Dans le template de chat, `templateThinking` lit comment le raisonnement du modèle s'active et se désactive. Il trouve `enable_thinking` et sa valeur par défaut (activé ou non), ou `reasoning_effort` et les valeurs que le template accepte. Un modèle dont le template ne connaît ni l'un ni l'autre n'a pas d'interrupteur de raisonnement.

Ces règles n'ont pas été écrites pour `mm init`. Ce sont celles de `skills/create-agent/model_facts.py`, portées en Go. Ce script servait déjà à l'agent qui crée des agents (`agent.creator.yaml`) pour lire un modèle dans llmman : mêmes points d'accès, même lecture du template.

Quand le serveur donne l'échantillonnage propre au GGUF, ces valeurs **remplacent** celles de la table des familles. Le GGUF est la source la plus précise, puisqu'il a été écrit pour ce fichier-là. Quand le serveur ne dit rien de plus que le nom du modèle (DMR, le fournisseur générique `openai`, un modèle inconnu), le fichier le signale dans ses notes de fin, et c'est la table des familles qui décide.

### 2. La table des familles (`presets.yaml`)

La famille est déduite de l'identifiant du modèle : la première famille dont tous les mots de `match` apparaissent dans le nom en minuscules l'emporte. `qwen-coder` (`qwen` + `coder`) passe donc avant `qwen`, et `other` correspond à tout. La famille annoncée par le serveur sert quand le nom ne dit rien. Une famille donne :

- l'échantillonnage pour un usage normal (`general`) et raisonnement activé (`thinking`) ;
- une température `precise`, pour les agents qui utilisent des outils sans raisonner ;
- l'interrupteur de raisonnement ;
- parfois une note, par exemple « un modèle de garde, pas un agent généraliste ».

Chaque valeur a une ligne `source`, et la table n'a été remplie qu'à partir de deux sortes de sources :

- **Les fiches de modèles et les fichiers publiés.** Les fiches Qwen (avec raisonnement 0.6 / 0.95 / 20, sans raisonnement 0.7 / 0.8 / 20), l'échantillonnage du GGUF de Gemma 4, le `generation_config.json` de Llama 3.1 8B Instruct (0.6 / 0.9, lu sur un miroir parce que le dépôt de Meta demande une connexion), la fiche de Mistral Small 3.1 (« a relatively low temperature, such as temperature=0.15 »), et la référence de l'API OpenAI pour les modèles hébergés.
- **Les démos mesurées de ce dépôt.** Pour chaque famille, on a cherché dans les démos qui font tourner le modèle l'échantillonnage qu'elles utilisent (`demos/*/agent*.yaml`). Par exemple `demos/qwen-style` (Qwen3-Coder-Next), `demos/coding-helpers` (Mellum2 12B Thinking, MiniCPM5 2B), `demos/team` (Ornith 1.5 9B), `demos/guard` (Granite Guardian), `demos/codex-style` (gpt-oss 20B) et `demos/llmman` (Jan-nano, Lucy). Le `precise` à 0.0 de Qwen vient d'exécutions avec Qwen3.5 4B sans raisonnement (`demos/docs-search`, `memory-search`, `plans`).

Quand rien n'est publié, `other` applique la règle du skill `skills/create-agent` : 0.7 / 0.9, et 0.2 pour un agent de code qui ne raisonne pas.

### 3. Le profil d'usage (`presets.yaml`, `usages`)

L'usage dit à quoi sert l'agent, ce que le modèle ne peut pas savoir. Un profil fixe :

- les outils activés (un traducteur n'a aucun outil, un développeur a bash, les outils de fichiers et l'outil de plan) ;
- s'il faut raisonner quand le modèle le peut ;
- s'il faut utiliser la température précise de la famille ;
- `maxTurns` ;
- la valeur par défaut de la demande avant chaque modification (`yolo`) ;
- un prompt système de départ.

Certains usages activent chacun une fonction : `docs` active la recherche dans la documentation, `json` écrit un exemple de `structuredOutput` (qui interdit tout outil), et `coordinator` confie les questions à d'autres agents. Les prompts sont en anglais, selon le choix de l'utilisateur dans le ticket 97. Ils reprennent des règles communes aux prompts des démos, par exemple « Never state the output of a command you did not run in this answer ».

### 4. La ligne de la machine (`presets.yaml`, `machines`)

Les délais et la taille des sorties d'outils dépendent de la machine, pas du modèle. Les trois lignes `small`, `medium` et `large` (`firstTokenTimeout`, `watchdogTimeout`, `bashTimeout`, `maxOutput`) sont copiées du tableau « Summary: typical profiles » [du guide des réglages](../../../guides/reglages-agents-petits-modeles.md), écrit pour le ticket 98.

## Les règles ajoutées par le code

Quelques valeurs découlent des réponses plutôt que d'une table. Chaque règle écrit sa raison au-dessus de la valeur qu'elle fixe :

- **Raisonnement activé : une température d'au moins 0.6 et `max_tokens: 16384`.** Un modèle qui raisonne tourne en boucle à basse température, et ses pensées ont besoin de place en plus de l'appel d'outil. Sans raisonnement, la limite est 4096.
- **La température précise ne s'applique que sans raisonnement.** Elle sert quand l'usage la demande (developer, reviewer, docs, json…).
- **Avec bash, `watchdogTimeout` est aligné sur `bashTimeout`**, comme le dit la section 3 du guide des réglages. Sinon une commande longue passerait pour un modèle bloqué.
- **`parallel_tool_calls: false` dès que l'agent a des outils.** Sinon les petits modèles lancent une vérification avant que la modification qu'elle vérifie soit faite.
- **`contextWindow: 0` et `context.threshold: 75`.** mm demande au serveur la fenêtre qu'il sert vraiment. La proposition prévoyait un seuil calculé sur la fenêtre native du modèle. Il a été abandonné pendant l'écriture du code : Ollama sert souvent 4k à 8k, donc un pourcentage de la fenêtre native compresserait presque tout de suite.
- **`skillsDir: no-skills`.** Un nouvel agent démarre sans skills, et le commentaire dit comment en ajouter.

## Chaque valeur dit comment elle a été obtenue

Depuis le ticket 121, chaque valeur liée au modèle porte une étiquette dans son commentaire. L'en-tête du fichier explique celles qu'il utilise :

| Étiquette | Sens | Après un changement de modèle ou de quantification |
|---|---|---|
| `[server]` | lue sur le serveur au moment de l'écriture du fichier | relancer `mm init` |
| `[measured]` | une démo de ce dépôt a tourné avec | mesurer à nouveau |
| `[card]` | copiée de la fiche du modèle, du GGUF ou de la référence de l'API, pas mesurée ici | relire la fiche |
| `[rule]` | une règle générale, rien de propre au modèle | vérifier qu'elle convient encore |
| `[guide]` | la ligne du guide des réglages pour la machine | — |

Un commentaire au-dessus de `model:` liste ce qu'il faut refaire quand on change de modèle. Les commentaires font que le fichier explique en même temps qu'il configure, à la manière des `agent.yaml` des démos : on voit quelles valeurs ont été mesurées sur une vraie exécution et lesquelles ont seulement été recopiées.

## Le fichier est vérifié avant que l'assistant ait fini

L'assistant n'écrase jamais un fichier existant. Après l'écriture, il charge le fichier avec le `config.Load` de mm, donc un fichier que mm refuserait est signalé tout de suite. Avec `--check`, il lance aussi le même mm sur le nouveau fichier avec une question (`Say hello in one line.`), pour prouver que le modèle répond.

## Pourquoi c'est conçu ainsi

**Un générateur sans modèle.** Le ticket 97 demandait un `agent.yaml` depuis la ligne de commande, selon la famille du modèle et l'usage. La proposition écrite pour le ticket a d'abord listé ce qui existait déjà : `agent.creator.yaml` et son skill `create-agent`, `model_facts.py`, le guide des réglages, `config.samples/` et les réglages testés des démos. Au lieu d'une nouvelle source de connaissances, `mm init` assemble ces morceaux dans du Go déterministe. C'est instantané et cela marche avant qu'aucun agent n'existe.

**Le serveur d'abord, la table ensuite.** Une table ne peut connaître qu'une famille, alors que le serveur connaît le fichier exact qui est chargé : sa fenêtre, l'échantillonnage de son GGUF, son template. La table couvre les serveurs qui ne disent rien, comme Docker Model Runner.

**Seulement des valeurs sourcées.** L'utilisateur a décidé que la table des familles utiliserait les fiches de modèles **et** les démos mesurées. Une valeur sans source n'y entre pas. Une famille qui n'a ni l'un ni l'autre retombe sur `other`, et le fichier dit que son échantillonnage n'est qu'un point de départ.

**Une seule table.** `presets.yaml` est intégré au binaire. Son en-tête dit qu'il doit être partagé avec le skill Claude du ticket 111 (un skill construit à partir du guide des réglages). Ce ticket est encore ouvert, et le skill `mm-agent-creator` ne lit pas ce fichier aujourd'hui.

## Alternatives écartées

- **Générer le fichier avec un modèle** (`agent.creator.yaml`). Conservé pour les cas qui sortent de l'ordinaire, mais pas par défaut : il faut un modèle de 27B chargé et plusieurs minutes par agent.
- **Un seuil calculé sur la fenêtre native.** Écarté, voir plus haut : il compresserait presque tout de suite avec les fenêtres que sert Ollama.
- **Les skills, les serveurs MCP, les hooks et les `mmConfigs` dans l'assistant.** Laissés hors de la première version. Le commentaire de fin du fichier renvoie aux guides pratiques.
- **Des prompts dans la langue de l'utilisateur.** Écarté par le choix de l'utilisateur : les prompts générés sont en anglais.

## Limites connues

- Les vérifications en direct n'ont été faites qu'avec llmman (Qwen3.5 4B, gemma-4-E4B). Ollama, Docker Model Runner et llama-server ont été testés contre de faux serveurs enregistrés dans les tests. L'API OpenAI elle-même n'a pas été essayée ; ses contraintes viennent de sa référence.
- Une valeur `[card]` a été recopiée, pas mesurée dans ce dépôt.
- Les familles sont reconnues sur des mots de l'identifiant du modèle : un modèle renommé par son éditeur peut tomber dans `other`.

## Liens avec le reste

- [Fournisseurs](providers.md) : les cinq serveurs que l'assistant peut interroger, et pourquoi chacun a sa propre entrée.
- [Modèles à raisonnement](thinking-models.md) : ce que fait à l'exécution l'interrupteur de raisonnement que fixe l'assistant.
- [Compression du contexte](context-compression.md) : ce que déclenche `context.threshold`.
- [Sortie structurée](structured-output.md) : pourquoi l'usage `json` n'a pas d'outils.
- [Interroger un autre agent](asking-another-agent.md) : ce sur quoi s'appuie l'usage `coordinator`.