1. L'idea in due righe

Chiedi a Metnos con una richiesta come quella di questo esempio: «Trova i file PDF modificati oggi». Se ripeti la richiesta, Metnos può riusare il piano già riuscito; non devi scegliere o attivare manualmente il fastpath.

Prima di interpellare il pianificatore, Metnos prova a riconoscere la richiesta. Se esiste un piano riutilizzabile e ancora valido, esegue quella sequenza di executor. Se il contesto o il catalogo sono cambiati, tratta la voce come non valida e torna alla pianificazione normale.

2. Perché serve un fastpath

La pianificazione serve quando la richiesta è nuova o richiede una nuova composizione di capacità. Ripeterla quando il sistema possiede già un piano valido aggiunge invece lavoro e variabilità senza migliorare il risultato. Per esempio, una richiesta già risolta con get_urls e describe_entries può riusare quella sequenza, purché gli argomenti vengano ricavati dalla richiesta corrente.

Resta da capire come riconoscere una richiesta nota — e quando una soltanto somigliante è abbastanza vicina da trattarla allo stesso modo. Se ne occupano due livelli di riuso: riconoscono gradi diversi di somiglianza, ma hanno lo stesso scopo, eseguire un piano noto senza chiedere al pianificatore di costruirlo di nuovo.

3. I due livelli e il loro confine

I due livelli si distinguono per ciò che riconoscono del percorso. L0 riconosce l'intero piano, compresi gli argomenti: la stessa richiesta, con gli stessi valori concreti. L1 riconosce invece la struttura della soluzione, senza gli argomenti della richiesta d'origine, e può quindi servire un'intera famiglia di richieste affini.

L'ordine è fisso: prima si tenta L0; se non trova corrispondenza si passa a L1. Se mancano entrambi, la richiesta arriva al pianificatore (il motore), come sempre.

Il pianificatore non scompare: L0 e L1 sono scorciatoie controllate. Una richiesta nuova, ambigua, accompagnata da allegati o priva di una corrispondenza valida prosegue nel motore normale.

4. L0 — cache prodotta dal runtime (fastpath.py)

Il primo livello vive in runtime/engine/fastpath.py e custodisce, in un database SQLite (fastpaths.sqlite), i piani già eseguiti. Le voci nascono da sole: ogni volta che un turno va a buon fine — un piano nuovo del motore, il riuso di L1 oppure una corrispondenza semantica L0 — Metnos annota la richiesta canonica, la sua impronta, l'embedding prodotto dal modello configurato, il piano completo (la struttura, o framework) e l'intento, cioè il verbo e l'oggetto della richiesta. Non occorre un'approvazione separata: gli executor hanno già superato i controlli di ammissione e il turno ha avuto esito positivo.

Due modi di trovare la corrispondenza

La ricerca avviene in due fasi:

• 0a — confronto per impronta. La query, ridotta a forma normale, diventa un'impronta (un hash deterministico) e si cerca una corrispondenza esatta, senza modello linguistico né nuovo embedding. È l'unica via concessa ai piani legati a una singola richiesta: quelli con argomenti letterali presi dalla domanda — un nome proprio usato come chiave di ricerca, poniamo — che, riusati su una richiesta somigliante ma diversa, restituirebbero il dato sbagliato.
• 0b — coseno semantico. Se l'impronta non trova nulla, la query diventa un vettore e si confronta, per coseno, con le voci sopra la soglia configurata. Così cadono sotto la stessa risposta le varianti di una richiesta («che ora è?» e «dimmi l'ora»). Il coseno vale solo per i piani generali, quelli non legati a una singola richiesta: così gli argomenti di una domanda non finiscono per sbaglio su un'altra vicina di significato ma distinta.

Una voce L0 eliminata per invecchiamento, invalidazione o riscontro negativo può essere ricreata dal successivo turno riuscito. La cancellazione non rende quindi indisponibile la capacità sottostante.

Controlli e rimedi

• Riscontro negativo: un «✗» dell'utente cancella il fastpath della richiesta. Un turno successivo riuscito può crearlo di nuovo.
• Amministrazione: nella chat web apri Impostazioni > Memoria > Praxis per vedere le scorciatoie L0 e cancellarne una. Se chiedi istruzioni da Telegram, il percorso indicato resta quello della chat web; la pagina non si apre dentro Telegram.
• Strumenti non memorizzabili: undo_last_turn, get_inputs, get_approval e gli strumenti di navigazione autenticata non generano fastpath, perché il loro significato o il loro identificatore di sessione dipendono dal turno in corso.
• Date assolute: un piano con date ISO esplicite (per esempio since_iso="2026-06-11") non si registra: rieseguirlo un altro giorno aprirebbe una finestra temporale ormai congelata. Le date relative (time_window="today") invece sì, perché a ogni riesecuzione si ricalcolano da capo.

5. L1 — riuso per famiglia di richieste (autopath.py)

Il secondo livello vive in runtime/engine/autopath.py. Non cerca la ripetizione della stessa frase: individua una famiglia semantica, verifica che l'oggetto dell'intento coincida e riusa soltanto piani privi di argomenti letterali legati alla richiesta d'origine. Prima dell'esecuzione gli argomenti variabili vengono ricavati di nuovo dalla richiesta corrente.

Un autopath può nascere in due modi. Un riscontro positivo promuove un piano riuscito quando raggiunge la soglia configurata, pari a una conferma per impostazione predefinita. In alternativa, due esecuzioni riuscite dello stesso intento possono creare un autopath shadow quando il piano appena eseguito comprende almeno quattro passi. La voce shadow è utilizzabile, ma resta distinta da un piano confermato; il primo riscontro positivo la conferma. Questa seconda via riduce il costo delle richieste ricorrenti senza far passare per approvazione umana un segnale che non lo è.

Riscontri e scelta del piano

• Anti-autopath: dopo un riscontro negativo ripetuto (tre fallimenti o più), Metnos registra un anti-autopath che esclude quel piano dal gruppo per trenta giorni. Un riscontro positivo rimuove l'esclusione.
• Ripetizione richiesta dall'utente: il comando di ripetizione esclude temporaneamente il piano per un'ora, così il recupero può cercarne uno diverso.
• Più piani disponibili: l'ordine è deterministico: prima il punteggio complessivo, poi le conferme positive, gli utilizzi e infine l'identificatore.

Il confine è deliberato: L0 privilegia la ripetizione della stessa richiesta; L1 generalizza a un gruppo di intenti e può derivare da un riscontro esplicito oppure dalla semina shadow appena descritta. L0 viene prima nella cascata, ma entrambi devono superare gli stessi controlli di validità, corrispondenza degli argomenti con la richiesta e sicurezza prima dell'esecuzione.

6. Validità, invecchiamento e trasferimento degli utilizzi

Firme del contesto operativo

Ogni piano memorizzato porta due firme: una per gli executor che usa e una per la famiglia di candidati disponibile per quell'intento. La firma incorpora anche la versione delle regole di instradamento e presentazione. Al momento del riuso Metnos le ricalcola: un executor modificato o rimosso, una nuova capacità concorrente o una modifica all'instradamento trasformano la voce in un miss. Il sistema ripianifica invece di eseguire una decisione presa in un contesto ormai diverso.

Le firme sono indipendenti dall'utente e non contengono profili, affinità o preferenze personali. L1 rimane quindi una cache condivisa di decisioni di piano, con chiavi deterministiche. Gli effetti autorizzati per l'utente e la presentazione finale — lingua, tono, lunghezza e formato — si applicano fuori dalla chiave del piano.

La famiglia dei candidati deriva dal vocabolario canonico, comprese le relazioni tra contenuti specializzati e carrier del filesystem: per esempio, una nuova capacità sui files può cambiare un piano che opera su images o texts. Non vengono inserite nella firma le parole della domanda o le affinity del manifest; in questo modo l'invalidazione segue la semantica del catalogo senza rendere L1 specifica per utente o per formulazione.

I fastpath L0 vengono conservati o ritirati secondo regole fisse, senza decisioni di un modello. Ogni notte il processo task_state_reaper applica tre regole d'invecchiamento e quattro condizioni di ritiro.

Invecchiamento

Ritiro (solo con catalogo completo)

Trasferimento dei conteggi d'uso

Quando un fastpath viene ritirato perché un executor lo ha sostituito (le condizioni C2), i suoi conteggi d'uso (n_uses) passano a quell'executor attraverso il registro usato per il suo ciclo di vita. Gli utilizzi già osservati non vengono quindi azzerati.

La rimozione riguarda il percorso memorizzato, non gli executor. Se la stessa richiesta torna e viene risolta correttamente, L0 può registrare di nuovo il piano aggiornato.

7. L'estrattore di argomenti

Riconoscere la richiesta è metà del lavoro. L'altra metà è ricavarne i valori concreti: quali percorsi, quali URL, quale data, quale soglia. Se ne occupa un estrattore a regole (args_extractor.py), anch'esso senza modello:

• Regole deterministiche. Espressioni regolari per i tipi noti: URL (https://...), path (~/... o /..., con la scorciatoia «home» che diventa ~/), email, numeri, estensioni di file («file PDF» → *.pdf), date (oggi, ieri, domani, dopodomani — in italiano e in inglese — tradotte in formato ISO) e finestre temporali («questa settimana», «ultime 24 ore», «last 7 days»).
• Argomenti che dipendono dalla richiesta. Alcuni valori — l'account di posta, la finestra temporale — cambiano con la domanda: all'esecuzione (e alla registrazione) si ricalcolano sulla query attuale, non si ereditano dal piano in memoria.

8. Configurazione

Le soglie di fastpath e autopath sono lette dalle variabili d'ambiente del processo Metnos; se una variabile manca, vale il valore predefinito nel modulo. Le vecchie sezioni [fast_path] e [multi_tool_fast_path] di ~/.config/metnos/runtime.toml sono state ritirate e vengono ignorate. La pagina Praxis permette di osservare e svuotare le cache, ma non modifica queste soglie. Per rendere permanente un override, va quindi inserito nella configurazione del servizio; le costanti lette all'importazione richiedono il riavvio del processo.

Livello 0 (fastpath)

Livello 1 (autopath)

Promozione a executor

9. Promozione a executor sintetico

Quando più fastpath L0 ricorrenti condividono la stessa struttura di piano (l'impronta dello scheletro) e lo stesso intent, ogni notte il processo task_fastpath_promotion li valuta come candidati a diventare un executor sintetico. Conta il gruppo, non la singola voce: servono almeno tre fastpath distinti, quindici utilizzi complessivi e trenta giorni di età. Sono ammessi soltanto i piani a più passi: una sequenza di un solo passo corrisponde già a un executor e il fastpath evita soltanto una nuova chiamata al pianificatore.

Perché da L0 e non da L1. L'analisi guarda i fastpath L0, non gli autopath L1, perché la traccia delle richieste reali è in L0: quante richieste concrete e distinte tornano, quante volte, da quanto tempo (i tre numeri qui sopra). L1 è già generale e nasce dal riscontro dell'utente oppure dalla semina shadow, ma non conserva quel conteggio di richieste distinte. La generalizzazione avviene quindi qui, raggruppando i fastpath L0 per forma del piano e intento.

Due modalità di promozione

• Modalità 1 (predefinita, attiva). Il candidato diventa una proposta che attende l'approvazione di una persona: compare in Impostazioni > Ciclo di vita > Modifiche della chat web. Se la famiglia dell'intento non esiste ancora nel catalogo, l'approvazione accoda la sintesi completa: cinque stadi, test iniziali, firma e installazione. Se invece il piano compone già un executor della stessa famiglia, serve prima un qualificatore scelto da una persona; l'approvazione da sola non avvia la sintesi. Da Telegram si può chiedere una spiegazione, ma il percorso conduce sempre alla chat web.
• Modalità 2 (opzionale, spenta). Oltre una soglia più alta, Metnos può sintetizzare automaticamente soltanto un candidato la cui famiglia è ancora libera. Occorrono almeno cinque fastpath, cinquanta utilizzi, trenta giorni e tre osservazioni notturne della stessa proposta; una decisione umana precedente impedisce l'automazione. La sintesi attraversa comunque la procedura completa. È ammesso un solo tentativo per notte, riuscito o fallito.

Da dove viene un executor

Per i candidati la cui famiglia è libera, Metnos annota nella tabella promotions gli identificatori e le impronte dei fastpath di origine. Quando il nuovo executor entra nel catalogo, il processo notturno usa quel legame per ritirare esattamente le voci che lo hanno generato. I candidati di composizione non ricevono questa provenienza automatica, perché il loro nome finale dipende dal qualificatore scelto da una persona; le relative voci L0 restano gestibili da Impostazioni > Memoria > Praxis.

© 2026 Roberto Brunialti · documentazione Metnos