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

Il PLANNER di Metnos sceglie quale executor invocare a ogni step. E’ un LLM locale (Qwen 3.6 35B-A3B). Quando la query e’ complessa — tipo «proponi 3 orari per un appuntamento di un’ora con un familiare la mattina della settimana prossima, dopo la scelta mandami una email con la scelta» — l’LLM a volte entra in un loop di ragionamento e finisce per emettere prosa al posto di un tool_call strutturato. Il sistema non sa cosa eseguire. Game over.

Si chiama “thinking loop”. Sintomi osservati:

• Prosa al posto di JSON. L’LLM scrive “Wait, I’ll think...” e dimentica di chiudere con un tool_call.
• Mix-match name/args. Emette {"name":"get_inputs","arguments": {"kind":"choice","from_step":1,...}} — il nome di un tool con gli argomenti di un altro tool.
• Escape-hatch arbitrari. Sceglie request_new_executor (cioe’ «sintetizzati un nuovo verbo») anche quando c’e’ gia’ un executor canonico ovvio. O request_location_from_user per la query «crea cartella /tmp/x» (no, non mi serve la tua posizione GPS).

Senza la grammar il PLANNER convergeva in modo inaffidabile. Inaccettabile per un assistente personale.

2. L’idea: la grammatica come binario

llama.cpp (il motore che esegue Qwen) supporta una feature chiamata GBNF (Grammar Backus-Naur Form). E’ un linguaggio per scrivere grammatiche formali, tipo:

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

Quando passi una grammar al server, l’LLM fisicamente non puo’ emettere token che la violino. Ogni token candidato a essere generato viene filtrato contro la grammar prima della scelta. E’ un binario, non una linea guida.

L’idea di e’: a ogni step del PLANNER, generiamo una grammar specifica a partire dai tools del pool dello step, e la passiamo al server. Il modello e’ libero di scegliere quale tool chiamare e quali argomenti passargli, ma SOLO entro quello che gli schemi dichiarano valido.

3. I tre pezzi: generator, filter, validator

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

Riceve la lista di tools del pool e ritorna una stringa GBNF. Il core della grammar e’ una discriminated union:

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

La parola chiave e’ discriminated: se l’LLM sceglie il ramo pairGetInputs, gli args saranno per forza conformi a argsGetInputs. Non puo’ mescolare il nome di un tool con gli args di un altro — ed era il bug live che ci ha bloccato per mezza giornata.

Per gli args, il generator legge il JSON Schema dichiarato nel manifest TOML dell’executor e lo traduce in regole GBNF. Per i casi nested (array di object, object dentro object) il generator e’ ricorsivo:

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\""
)

Esempio reale per get_inputs: lo schema dichiara dialog come array di object, ognuno con {var, prompt, schema}, dove schema.kind e’ un enum di 10 valori. Tutto questo finisce nella grammar: il modello non puo’ emettere kind: "banana", e non puo’ dimenticarsi var.

3.2 Pool filter (runtime/tool_grammar.py::filter_pool_for_grammar)

Anche con la grammar perfetta, c’era un problema: certi tool sono escape-hatch — iniettati sempre nel pool per uso speciale — e con la grammar attiva il modello li sceglie a sproposito.

Il filter usa word-boundary regex (\bmarker\b) per evitare i falsi positivi tipo «qua» ⊂ «qualcosa» che ci ha fatto perdere un altro giro di bench. La logica e’ una funzione pura: la testi con 12 unit-test, garantisci determinismo (§7.9).

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

La grammar e’ tight, ma non e’ perfetta — alcuni vincoli (es. mutua esclusivita’ tra due property) non si esprimono naturalmente in GBNF. Per quelli c’e’ un validator post-decode:

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 validator dice no, l’executor NON viene chiamato. L’errore viene iniettato nel history dell’LLM come messaggio role=tool, e allo step successivo il modello vede «mi mancano title e dialog» e corregge. Un contatore consecutive_blocked previene loop infiniti.

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.
• Args coerenti col nome. Discriminated union: nome A ⇒ args di A.
• Tipi delle property top-level e nested. String, integer, boolean, enum, array, object — ognuno emette la sua regola.
• Enum stretti. Se kind ha 10 valori, il modello ne sceglie SOLO uno tra quei 10.

Non garantisce

• Valore semanticamente giusto. La grammar accetta title: "": e’ una stringa. Toccaall’executor controllare.
• Required nested troppo profondi. Cap _MAX_RECURSION_DEPTH = 4: oltre, fallback su jsonObject generico. Casi rari, da monitorare.
• Tool giusto per la query. Se il pool ha 8 tool tutti plausibili, il modello sceglie quello che gli sembra meglio — e puo’ sbagliare. Per quello c’e’ il ranker (top-K) prima della grammar, ed eventualmente il pool filter.

5. Perche’ tre “bug llama-server” ci hanno fatto perdere mezza giornata

llama.cpp e’ software vivo, e la sua implementazione GBNF ha un paio di quirk’. Tutti scoperti in convergence test durante la sessione.

Sono workaround stabili, ma sono workaround. Se in futuro llama.cpp li risolve, possiamo semplificare. Sono presidiati da test.

6. Robustezza, velocita’, estensibilita’

Robustezza

Bench n=10 query rappresentative (simple/medium/complex/ambiguous), n=1 run per query: 100% convergenza, 100% first_tool_match, latenza media ~41s.

Tre cose vale la pena notare:

• Il thinking-loop e’ sparito. L’LLM non spreca cicli a ragionare in cerchio.
• La pipeline propose+notify (il caso «proponi-orari-poi-avvisa») converge sempre. Era il caso peggiore.
• Anche le query ambigue («fai qualcosa di interessante») chiudono in un final_answer sensato, invece di scegliere un escape-hatch a caso.

Velocita’

La generazione della grammar e’ deterministica e veloce: per un pool tipico di 8 tool produce ~80 regole in ~2 ms. La grammar «costa» un po’ al server durante la generazione (filtering token candidati), ma il guadagno netto e’ enorme perche’ eliminiamo:

• Il pensiero in prosa (centinaia di token «Wait, I’ll check...»).
• I retry causati da JSON malformato o args sbagliati.
• I loop di reasoning ricorsivo.

Estensibilita’

Aggiungere un nuovo provider qualifier (es. _notion o _telegram_bot) costa una riga:

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

Aggiungere un nuovo executor con schema nested complesso costa zero: il generator legge il JSON Schema dichiarato nel manifest e produce la grammar automaticamente, ricorsivamente, fino al cap di depth.

7. Come si testa

43 unit-test in runtime/tests/test_tool_grammar.py verdi. Coprono:

• Complexity scoring (args_complexity, is_complex).
• Generator outer (root, name enum, args alternation, deterministico).
• Discriminated union (pair rules, no cross-pollination).
• B2 recursive (array of object, nested object, cap depth, no collisione cross-tool).
• Anti-bug (no underscore in rules, no primitives unused emesse).
• Validator (missing name, missing args, unknown tool, required missing, happy path, enum top-level passa).
• Pool filter (escape-hatch, word-boundary, provider suffix, safety, determinismo).
• Smoke integration con catalog reale (get_inputs.dialog emette sub-rule).

Bench end-to-end: runtime/bench_grammar.py:

METNOS_GRAMMAR=1 python3 runtime/bench_grammar.py --label grammar_v8
# 10 query × 1 run, ~7 minuti totali
# output: /tmp/bench_grammar_grammar_v8_<ts>.json
# stampa tabella aggregata + per-complexity + detail riga-per-riga

Per attivare grammar mode 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 constrained generation non e’ un’invenzione di Metnos. Ecco una mappa veloce di chi fa cosa nell’ecosistema LLM/agent — serve per capire dove si colloca la scelta di e cosa abbiamo guadagnato (o rinunciato) rispetto alle alternative.

Dove si colloca Metnos

La scelta GBNF di e’ allineata con la frontiera tecnica: i serving stack moderni stanno tutti convergendo su sampler-level constraints (Outlines, xgrammar, llama.cpp GBNF). E’ il pattern state of the art per tool calling locale.

La differenza rispetto a OpenAI/Anthropic e’ che noi scriviamo la grammar invece di delegarla a un modello fine-tuned. Vantaggi:

• Locale, zero rete, zero costi $. Allineato al principio Metnos §10.3 (open-source self-hosted come default).
• Deterministico §7.9 — testabile con 43 unit-test.
• Trasparenza totale: la grammar e’ stringa testuale, ispezionabile, versionabile.
• Aggiornamento immediato: aggiungere un executor non richiede re-training. Schema TOML → grammar emessa al volo.

Svantaggi:

• I grandi modelli frontier addestrati al tool_call (per esempio Claude) sono piu’ fluenti su query molto aperte — non scelgono mai un tool a sproposito, perché sono addestrati a ragionare semanticamente sul match. Compensiamo con ranker top-K + pool filter contestuale.
• I bug del server (vedi §5) ci ricadono su. Mitigati da test regression.

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