Il modello propone un piano, ma non decide liberamente la forma del comando. Metnos gli presenta un insieme ristretto di executor e, quando il servizio del modello supporta GBNF, vincola la decodifica alla struttura del Framework e ai nomi ammessi. Parsing, validazione e Vaglio controllano poi il risultato prima di ogni esecuzione.

1. Un esempio

Chiedi a Metnos con una richiesta come questa:

Trova i PDF modificati questa settimana nella cartella Progetti,
calcola l'impronta SHA-256 di ciascuno e mostrami il risultato.

Il pianificatore non deve rispondere con una spiegazione vaga. Deve produrre una struttura simile a questa, limitata ai nomi presenti nel sottoinsieme calcolato per il turno:

{
  "steps": [
    {"tool": "find_files", "args": {"path": "Progetti", "extension": "pdf"}},
    {"tool": "compute_signatures", "args": {"algorithm": "sha256"}}
  ]
}

L'esempio illustra la forma, non autorizza i percorsi e non sostituisce il riempimento degli argomenti. Le date relative, i riferimenti fra passi e gli ambiti del file system vengono risolti e verificati dagli strati successivi.

2. I due livelli di grammatica

runtime/tool_grammar.py contiene il traduttore da JSON Schema a GBNF, la validazione della chiamata e i filtri semantici riusati dal motore. L'API generate_tool_grammar genera una singola tool_call; il pianificatore usa invece la grammatica del Framework, che può contenere più passi.

3. Dal sottoinsieme di executor al piano

1. Il motore estrae intento, oggetto e segnali semantici dalla richiesta.
2. Il prefiltraggio riduce il catalogo agli executor pertinenti e disponibili per quell'utente.
3. I filtri deterministici conservano i produttori necessari, escludono le vie speciali non richieste e scelgono la variante del fornitore soltanto quando la richiesta la indica.
4. Il generatore costruisce la GBNF usando esattamente i nomi rimasti.
5. Il servizio del modello decodifica un Framework compatibile con quella grammatica.
6. Il parser ricostruisce il piano; validatori, riempimento degli argomenti, policy e Vaglio controllano ciò che la grammatica non può decidere.

I segnali in linguaggio naturale — per esempio annullamento, ricorrenza, prossimità, skill e nomi dei fornitori — provengono dal lessico di riconoscimento traducibile. Una nuova lingua richiede dati lessicali per quella lingua, non condizioni inserite nel codice per singole frasi.

3.1 Unione discriminata degli argomenti

Quando il vincolo sugli argomenti è attivo, ogni passo ha un ramo proprio: il nome compute_signatures può essere seguito soltanto dagli argomenti ricavati dal suo schema. Gli elenchi chiusi diventano alternative GBNF; stringhe, numeri, booleani, array e oggetti annidati sono tradotti nelle primitive corrispondenti. Se uno schema non è tipizzabile, quel ramo usa argomenti JSON liberi e lascia la verifica all'executor.

4. Garanzie e limiti

La profondità della traduzione degli schemi è limitata. Oltre il limite, o davanti a costrutti complessi, il generatore ricorre a JSON generico. La validazione successiva controlla forma superiore, nome, argomenti obbligatori e terminali sintetici; la convalida profonda resta responsabilità dell'executor e del contratto comune.

5. Vincoli di compatibilità

La costruzione della grammatica applica alcune regole necessarie al servizio locale attuale:

• i nomi delle regole GBNF generate non contengono trattini bassi;
• vengono emesse soltanto le primitive raggiungibili dalla regola principale;
• una stessa regola non viene definita due volte quando la grammatica del Framework e quella degli argomenti vengono unite;
• in modalità GBNF la richiesta al servizio non invia contemporaneamente il campo nativo tools;
• il ragionamento esteso del modello viene disattivato per questo passaggio, così l'uscita resta entro il bilancio e la forma vincolata.

Se il servizio non accetta il parametro grammar, il passaggio alla modalità senza grammatica viene registrato. Il piano deve comunque superare l'analisi sintattica e la validazione, ma non beneficia più del vincolo applicato durante la decodifica.

6. Determinismo e costo

Dato lo stesso sottoinsieme ordinato e gli stessi schemi, la stringa GBNF generata è deterministica. Questo rende confrontabile la superficie offerta al modello e impedisce che un nome assente compaia nel percorso vincolato. Non rende deterministica l'intera risposta del modello: testo libero, valori semantici e piani nuovi restano prodotti da un'inferenza probabilistica.

La grammatica viene costruita in memoria e non compie chiamate di rete. Il costo principale è nella decodifica, perché il servizio deve eliminare a ogni passo i token non ammessi. Metnos riduce tale costo costruendo la grammatica sul sottoinsieme del turno, non sull'intero catalogo, e assegna al proponente un bilancio di uscita calcolato dalla complessità della richiesta.

7. Verifiche

Le prove non sono descritte con un conteggio fisso, che diventerebbe presto obsoleto. Le suite principali sono:

tests/runtime/engine/test_tool_grammar.py
tests/runtime/engine/test_grammar_args_typed.py
tests/runtime/engine/test_routing_pool.py
tests/runtime/engine/test_tool_call_parser.py

Coprono generazione deterministica, unione nome-argomenti, schemi annidati, elenchi chiusi, filtri per intento e fornitore, terminali sintetici, eliminazione dei duplicati e recupero delle uscite troncate. Le prove del motore verificano inoltre che il piano non possa nominare executor esclusi dal sottoinsieme.

8. Rapporto con i servizi dei modelli

GBNF è il meccanismo usato dal servizio locale compatibile con llama.cpp. Altri servizi possono offrire JSON Schema vincolato o chiamate di strumenti native. Il contratto di Metnos non dipende dal nome commerciale del fornitore: un adattatore è adatto soltanto se dichiara con precisione quale livello di vincolo applica e restituisce dati che il parser e i validatori comuni possono controllare.

La pagina Virtualizzazione dei modelli spiega come i ruoli logici vengono associati ai servizi configurati. Cambiare servizio non deve cambiare il vocabolario degli executor, l'autorità dell'utente o le regole del Vaglio.

9. Fonti canoniche

• runtime/engine/grammar_framework.py — grammatica del Framework e variante con argomenti tipizzati;
• runtime/tool_grammar.py — traduzione degli schemi, validazione e filtri deterministici;
• runtime/engine/proposer.py — scelta della modalità e invocazione del modello;
• runtime/llm_provider.py — trasporto della grammatica e parsing delle risposte del servizio.