1. L'idea in due righe

Quando una richiesta arriva a Metnos, prima di scomodare il pianificatore LLM si cerca di riconoscerla. Se l'abbiamo già vista e abbiamo già deciso bene come rispondere, la rieseguiamo così com'è e torniamo all'utente in mezzo secondo invece che in dieci. Niente modelli linguistici nel percorso critico, solo memoria.

2. Perché serve un fast-path

Il pianificatore di Metnos è un Qwen 3.6 35B-A3B locale: pensa bene ma ci mette circa dodici secondi a decidere il primo passo di un turno. Per molte richieste questa attesa è spropositata. «Che ora è» non ha bisogno di un LLM: ha bisogno di get_now. Anche «scaricami questa pagina e descrivila in due righe» non ha bisogno del pianificatore se è una richiesta che facciamo spesso e di cui sappiamo già la sequenza: get_urls e poi describe_entries.

Da qui la domanda: come riconosciamo che una richiesta è già nota? E come ci accorgiamo che quasi nota è abbastanza? La risposta è il fast-path introvertivo, organizzato in due livelli — ciascuno coglie un grado diverso di certezza, e tutti convergono allo stesso esito: l'assistente esegue la sequenza giusta senza pensarci due volte.

3. I due livelli

Il flusso è rigorosamente sequenziale: prima si tenta L0, se non matcha si tenta L1. Se entrambi mancano, si arriva al pianificatore LLM (Engine v2) come sempre.

4. L0 — cache auto-prodotta (fastpath.py)

Il primo livello vive in runtime/engine/fastpath.py e gestisce un database SQLite (fastpaths.sqlite) di piani già eseguiti. Le entry si producono in automatico: ogni volta che un turno si completa con successo (piano pieno dal motore, hit L1, o promozione da cosine 0b), Metnos registra la query canonica, il suo hash, l'embedding BGE-M3, il piano completo (framework) e l'intent (verbo + oggetto). Non serve nessuna approvazione: le catene sono fatte di executor già vagliati e testati.

Due sotto-livelli di match

La ricerca avviene in due fasi:

• 0a — hash lookup. La query normalizzata viene trasformata in un hash deterministico e cercata per corrispondenza esatta. Costo sotto i 5 ms. Niente modello linguistico, niente embedding. Il match hash è l'unica via per le query query-specific, cioè piani con argomenti letterali legati alla richiesta originale (es. un nome proprio come parametro di ricerca): replicarli su una query simile ma diversa restituirebbe dati stantii.
• 0b — cosine semantico. Se il match hash fallisce, la query viene trasformata nel suo vettore BGE-M3 e confrontata per coseno con tutte le entry la cui soglia supera il valore configurato. Questo copre le varianti lessicali della stessa richiesta («che ora è» vs «dimmi l'ora»). Il match cosine serve solo piani non query-specific, per evitare di applicare argomenti di una query a un'altra semanticamente vicina ma distinta.

Valvole di sicurezza

• Feedback negativo: un feedback «✗» dell'utente elimina il fastpath per quella query (last-writer-wins: si ricrea al prossimo turno completato con successo).
• Admin: i fastpath si eliminano dalla console /admin/praxis.
• Tool non cacheabili: undo_last_turn e get_inputs non generano fastpath, perché la loro semantica dipende dal contesto del turno.
• Date assolute: un piano con date ISO letterali (es. since_iso="2026-06-11") non viene registrato, perché il replay in un giorno diverso eseguirebbe una finestra temporale congelata. Le date relative (time_window="today") restano cacheabili, perché il replay le ri-risolve correttamente.

5. L1 — autopath promossi da feedback (autopath.py)

Il secondo livello vive in runtime/engine/autopath.py e opera su una logica diversa: non ripete la stessa query, ma generalizza a un cluster di intent confermato dal feedback positivo dell'utente.

Quando l'utente dà un feedback «✓», Metnos registra il framework del turno, il suo hash e il cluster semantico (intent hash + cluster ID). Dopo un numero minimo di conferme (configurabile, default 1) sullo stesso framework hash e cluster, il piano diventa una autopath riusabile: la prossima volta che arriva un intent nello stesso cluster, il piano viene rieseguito senza passare dal pianificatore.

Anti-autopath e champion/challenger

• Anti-autopath: se l'utente dà feedback negativo (3 o più fallimenti), Metnos registra una anti-autopath che blocca quel piano per quel cluster per 30 giorni. È una simmetria last-writer-wins: un feedback positivo rimuove l'anti-autopath corrispondente.
• Champion/challenger: quando più framework competono per lo stesso cluster, Metnos calcola un punteggio composito che favorisce il piano con più conferme e meno fallimenti.

6. Invecchiamento, morte e eredità

I fastpath L0 invecchiano e muoiono in modo deterministico, senza alcun intervento LLM. Il job notturno task_state_reaper applica tre regole di invecchiamento e quattro condizioni di morte.

Invecchiamento (aging)

Morte (solo con catalogo completo)

Eredità dei punti

Quando un fastpath muore per superamento (C2), i suoi conteggi d'uso (n_uses) vengono trasferiti all'executor erede tramite il sistema di aging degli executor. La domanda accumulata non va persa.

7. L'estrattore di argomenti

Riconoscere la richiesta è metà del lavoro. L'altra metà è ricostruire i valori concreti degli argomenti: quali path, quali URL, quale data, quale soglia. Metnos ha un estrattore deterministico (args_extractor.py) che lavora a regole:

• Regole chiuse. Espressioni regolari per i tipi noti: URL (https://...), path (~/... o /..., con la scorciatoia «home» che diventa ~/), email, numeri, estensioni di file («file PDF» diventa *.pdf), date (oggi/ieri/domani/dopodomani in italiano e inglese, mappate a formato ISO), finestre temporali («questa settimana», «ultime 24 ore», «last 7 days»).
• Ri-risoluzione slot query-specific. Al momento dell'esecuzione (e della registrazione), gli argomenti dipendenti dalla query (come l'account mail e la finestra temporale) vengono ri-risolti sulla query corrente, non ereditati dal piano cachato.

8. Configurazione

I parametri del fast-path sono controllati da variabili d'ambiente METNOS_*. Un file TOML (~/.config/metnos/runtime.toml) stabilisce valori persistenti; il default codificato nel modulo è l'ultima rete di sicurezza.

Layer 0 (fastpath)

Layer 1 (autopath)

Promozione a executor

9. Promozione a executor sintetico

Quando un gruppo di fastpath L0 ricorrenti condivide la stessa struttura di piano (framework hash) e lo stesso intent, un job notturno (task_fastpath_promotion) li valuta come candidati per diventare un executor sintetico completo. La promozione è cluster-based, mai per singola istanza: servono almeno 3 fastpath distinti, 15 utilizzi cumulati e 30 giorni di età. Solo i pattern multi-step vengono promossi: quelli a step singolo hanno già il loro executor, e il valore del fastpath lì è saltare l'LLM, non il piano.

Due tier di promozione

• Tier 1 (default, attivo). Il candidato viene emesso come proposta human-gated nel backlog introvertiva: visibile in /admin/proposals e nell'hub unificato. L'approvazione scrive un marker synt_pending/ che avvia la pipeline di sintesi completa (5 stadi + test + firma + installazione).
• Tier 2 (flag, spento). Sopra una soglia molto più alta, il sistema sintetizza l'executor automaticamente senza approvazione umana. La sicurezza è garantita dal fatto che la pipeline synt completa include vaglio, test e firma, come per ogni executor sintetizzato. Hard cap: 1 tentativo per notte.

Provenienza

Ogni candidato emesso registra gli ID e gli hash canonici dei fastpath d'origine in una tabella promotions. Quando l'executor entra nel catalogo, la morte C2 per provenienza è esatta: il legame fra il fastpath originale e il suo erede è registrato, non inferito dal nome.

© 2026 Roberto Brunialti · documentazione Metnos