1. Il problema: l’LLM “ci pensa su” e si perde

Il pianificatore di Metnos sceglie quale executor invocare a ogni passo. È un modello linguistico locale. Quando la richiesta si fa complessa — poniamo «proponi tre orari per un appuntamento di un'ora con un familiare, una mattina della settimana prossima; poi mandami la scelta per email» — il modello certe volte si avvita in un ragionamento e finisce per scrivere prosa invece di un tool_call strutturato. Il sistema non sa più cosa eseguire. Fine della corsa.

È il “ciclo di ragionamento”. I sintomi che abbiamo visto:

• Prosa al posto del JSON. Il modello scrive “Aspetta, ci penso…” e si scorda di chiudere con un tool_call.
• Nome e argomenti scambiati. Emette {"name":"get_inputs","arguments":{"kind":"choice","from_step":1,...}} — il nome di uno strumento con gli argomenti di un altro.
• Vie di fuga a sproposito. Sceglie request_new_executor (cioè «sintetizzami un verbo nuovo») anche quando un executor adatto c'è già. Oppure request_location_from_user per «crea la cartella /tmp/x» — che con la posizione GPS non c'entra nulla.

Senza la grammar il pianificatore arrivava in fondo in modo inaffidabile. Inaccettabile, per un assistente personale.

2. L’idea: la grammatica come binario

llama.cpp (il motore che fa girare il modello locale) offre uno strumento chiamato GBNF (Grammar Backus-Naur Form): un linguaggio per scrivere grammatiche formali, così:

root::= "{" ws "\"name\":" name ws "}"
name::= "\"get_now\"" | "\"find_files\"" | "\"send_messages\""
ws::= [ \t\n]*

Quando si dà una grammar al server, il modello non può proprio emettere token che la violino: ogni token candidato passa al vaglio della grammar prima di essere scelto. È un binario, non un consiglio.

L'idea, allora, è questa: a ogni passo del pianificatore costruiamo una grammar su misura a partire dagli strumenti del pool di quel passo, e la passiamo al server. Il modello resta libero di scegliere quale strumento chiamare e con quali argomenti, ma solo entro ciò che gli schemi dichiarano valido.

3. I tre pezzi: generatore, filtro, validatore

3.1 Generatore (runtime/tool_grammar.py::generate_tool_grammar)

Riceve l'elenco degli strumenti del pool e restituisce una stringa GBNF. Il cuore della grammar è un'unione discriminata:

root::= "{" ws "\"name\":" (pairGetInputs | pairSendMessages |...) ws "}"
pairGetInputs::= "\"get_inputs\"" sep "\"arguments\":" colon (argsGetInputs)
pairSendMessages::= "\"send_messages\"" sep "\"arguments\":" colon (argsSendMessages)...

La parola che conta è discriminata: se il modello imbocca il ramo pairGetInputs, gli argomenti saranno per forza conformi ad argsGetInputs. Non può più sposare il nome di uno strumento sugli argomenti di un altro — ed era proprio il difetto, visto dal vivo, che ci aveva bloccato per mezza giornata.

Per gli argomenti, il generatore legge il JSON Schema dichiarato nel manifest TOML dell'executor e lo traduce in regole GBNF. Per le strutture annidate (un array di oggetti, un oggetto dentro un oggetto) procede per ricorsione:

argsGetInputs::= "{" ws propGetInputsTitle sep propGetInputsDialog
 (sep (propGetInputsFromStep |...))* ws "}"
propGetInputsDialog::= "\"dialog\":" colon (
 "[" ws (GetInputsObjD1I0 (sep GetInputsObjD1I0)*)? ws "]"
)
GetInputsObjD1I0::= "{" ws propGetInputsObjD1I0Var sep propGetInputsObjD1I0Prompt sep
 propGetInputsObjD1I0Schema (sep (...))* ws "}"
propGetInputsObjD1I0Schema::= "\"schema\":" colon (GetInputsObjD3I2)
GetInputsObjD3I2::= "{" ws propGetInputsObjD3I2Kind (sep (...))* ws "}"
propGetInputsObjD3I2Kind::= "\"kind\":" colon (
 "\"text\"" | "\"credentials\"" | "\"yes_no\"" | "\"choice\"" |
 "\"choice_with_preview\"" | "\"multi_choice\"" | "\"number\"" |
 "\"date\"" | "\"file_path\"" | "\"location\""
)

Un caso vero, get_inputs: lo schema dichiara dialog come array di oggetti, ciascuno con {var, prompt, schema}, dove schema.kind è un elenco chiuso di dieci valori. Tutto questo finisce nella grammar: il modello non può emettere kind: "banana", e non può dimenticare var.

3.2 Filtro del pool (runtime/tool_grammar.py::filter_pool_for_grammar)

Anche con una grammar perfetta restava un problema: certi strumenti sono vie di fuga — sempre presenti nel pool per usi speciali — e con la grammar attiva il modello li imbocca a sproposito.

Il filtro confronta le parole intere (\bspia\b) per non cadere in falsi positivi come «qua» dentro «qualcosa», che ci è costato un altro giro di prove. La logica è una funzione pura: la provi con dodici test e ne garantisci il determinismo (§7.9).

3.3 Validatore (runtime/tool_grammar.py::validate_tool_call)

La grammar è stretta, ma non perfetta: certi vincoli — per esempio l'esclusione reciproca fra due proprietà — in GBNF non si esprimono con naturalezza. Per quelli c'è un validatore, che interviene dopo la decodifica:

tool_call = {"name": "get_inputs", "arguments": {"display_template": "x"}}
ok, err = validate_tool_call(tool_call, pool)
# ok=False, err="missing required args ['title', 'dialog'] for tool 'get_inputs'"

Se il validatore dice no, l'executor non viene chiamato. L'errore entra nella cronologia del modello come messaggio role=tool, e al passo dopo il modello legge «mancano title e dialog» e si corregge. Un contatore (consecutive_blocked) impedisce che la cosa giri all'infinito.

4. Cosa garantisce e cosa no

Garantisce

• Sintassi JSON valida. Il modello non puo’ emettere un JSON malformato.
• Nome tool nel pool. Solo i tool del pool dello step sono ammessi come name.
• Argomenti coerenti col nome. Unione discriminata: nome A ⇒ argomenti di A.
• I tipi delle proprietà, in cima e annidate. Stringa, intero, booleano, elenco chiuso, array, oggetto: ognuno ha la sua regola.
• Elenchi chiusi stretti. Se kind ammette dieci valori, il modello ne sceglie uno solo di quei dieci.

Non garantisce

• Il valore giusto nel merito. La grammar accetta title: "": è pur sempre una stringa. Controllarlo tocca all'executor.
• Gli obbligatori troppo in profondità. Oltre il limite _MAX_RECURSION_DEPTH = 4 si ripiega su un jsonObject generico. Casi rari, da tenere d'occhio.
• Lo strumento giusto per la richiesta. Se nel pool ci sono otto strumenti tutti plausibili, il modello prende quello che gli pare migliore — e può sbagliare. Per questo, prima della grammar, c'è l'ordinamento per pertinenza (i primi K) ed eventualmente il filtro del pool.

5. Perche’ tre difetti del llama-server ci hanno fatto perdere mezza giornata

llama.cpp è software vivo, e la sua resa di GBNF ha un paio di stranezze. Le abbiamo scovate tutte nelle prove di convergenza, durante la sessione.

Sono rimedi stabili, ma restano rimedi: se un domani llama.cpp risolve i tre casi, potremo semplificare. Intanto li presidiano i test.

6. Robustezza, velocita’, estensibilita’

Robustezza

Prova su dieci richieste rappresentative (semplici, medie, complesse, ambigue), una esecuzione per richiesta: convergenza 100%, strumento giusto al primo colpo 100%, latenza media ~41 s.

Tre cose vale la pena notare:

• Il ciclo di ragionamento è sparito: il modello non brucia più cicli a girare in tondo.
• La catena proponi-poi-avvisa (il caso «proponi gli orari, poi mandami la scelta») arriva sempre in fondo. Era il caso peggiore.
• Persino le richieste vaghe («fai qualcosa di interessante») si chiudono in un final_answer sensato, invece di ripiegare a caso su una via di fuga.

Velocita’

Generare la grammar è veloce e deterministico: per un pool tipico di otto strumenti produce un'ottantina di regole in circa 2 ms. Al server la grammar costa un po' durante la generazione (deve filtrare i token candidati), ma il guadagno netto è enorme, perché toglie di mezzo:

• il pensiero a voce alta (centinaia di token «Aspetta, controllo…»);
• i nuovi tentativi dovuti a JSON malformato o argomenti sbagliati;
• i cicli di ragionamento che si avvitano.

Estensibilita’

Aggiungere un nuovo qualifier di fornitore (per esempio _notion o _telegram_bot) costa una riga:

_PROVIDER_SUFFIX_MARKERS = {
 "_google_workspace": ("google", "drive", "gmail",...),
 "_notion": ("notion", "notion.so", "page"), # ← aggiunta
}

Aggiungere un executor con uno schema annidato complesso costa zero: il generatore legge il JSON Schema del manifest e produce la grammar da sé, per ricorsione, fino al limite di profondità.

7. Come si prova

Quarantatré test in runtime/tests/test_tool_grammar.py, tutti verdi. Coprono:

• il punteggio di complessità (args_complexity, is_complex);
• il guscio del generatore (root, elenco dei nomi, alternativa degli argomenti, determinismo);
• l'unione discriminata (regole appaiate, nessuna contaminazione fra rami);
• la ricorsione (array di oggetti, oggetti annidati, limite di profondità, nessuna collisione fra strumenti);
• i tre rimedi (niente underscore nei nomi di regola, niente primitive inutili);
• il validatore (nome mancante, argomenti mancanti, strumento ignoto, obbligatorio assente, caso felice, elenco chiuso in cima);
• il filtro del pool (vie di fuga, parole intere, qualifier di fornitore, sicurezza, determinismo);
• una prova d'insieme col catalogo reale (get_inputs.dialog che emette la sotto-regola).

Prova dall'inizio alla fine: runtime/bench_grammar.py:

METNOS_GRAMMAR=1 python3 runtime/bench_grammar.py --label grammar_v8
# 10 richieste × 1 esecuzione, ~7 minuti in tutto
# esito: /tmp/bench_grammar_grammar_v8_<ts>.json
# stampa la tabella aggregata, quella per complessità e il dettaglio riga per riga

Per attivare la modalità grammar in sviluppo:

echo '[Service]
Environment=METNOS_GRAMMAR=1' | sudo tee /etc/systemd/system/metnos-http.service.d/grammar.conf
sudo systemctl daemon-reload && sudo systemctl restart metnos-http.service

8. Confronto con altre piattaforme

La generazione vincolata non è un'invenzione di Metnos. Ecco una mappa rapida di chi fa cosa nell'ecosistema degli LLM e degli agenti: serve a capire dove si colloca la nostra scelta, e cosa ci abbiamo guadagnato (o a cosa abbiamo rinunciato) rispetto alle alternative.

Dove si colloca Metnos

La scelta di GBNF è in linea con la frontiera tecnica: gli ambienti di servizio moderni stanno convergendo tutti sui vincoli a livello di campionamento (Outlines, xgrammar, GBNF di llama.cpp). È oggi l'approccio più avanzato per il tool calling in locale.

La differenza rispetto a OpenAI e Anthropic è che la grammar la scriviamo noi, invece di affidarla a un modello addestrato apposta. I vantaggi:

• Locale, nessuna rete, nessun costo in denaro. In linea col principio Metnos §10.3 (open-source self-hosted come scelta di base).
• Deterministico (§7.9), e quindi verificabile con i quarantatré test.
• Trasparenza piena: la grammar è testo, la si ispeziona e la si tiene sotto versione.
• Aggiornamento immediato: aggiungere un executor non richiede un nuovo addestramento. Dallo schema TOML la grammar nasce al volo.

Gli svantaggi:

• I grandi modelli di frontiera addestrati al tool_call (Claude, per dire) sono più sciolti sulle richieste molto aperte: non scelgono mai uno strumento a sproposito, perché sono addestrati a ragionare sul significato. Lo compensiamo con l'ordinamento per pertinenza (i primi K) e il filtro del pool.
• I difetti del server (vedi §5) ricadono su di noi. Li teniamo a bada con i test di regressione.

Quando avrebbe senso cambiare

9. Riferimenti

• Generator: runtime/tool_grammar.py
• Provider wiring: runtime/llm_provider.py::LlamaCppProvider.chat_with_tools
• Bench: runtime/bench_grammar.py
• Test: runtime/tests/test_tool_grammar.py
• llama.cpp GBNF docs: grammars README
• JSON Schema basics: json-schema.org