Quando riceve una richiesta, Metnos cerca prima un piano già riuscito che possa essere riutilizzato in sicurezza. Se non lo trova, ne costruisce uno nuovo. Nel codice questo piano interno si chiama framework: è una sequenza finita di executor e collegamenti fra i loro risultati. Il modello può proporla, ma sono controlli scritti nel codice a decidere se può essere eseguita.

1. Scopo

Il motore deve trasformare una richiesta naturale in una sequenza finita di capacità ammesse. Deve conciliare due esigenze:

• evitare una nuova pianificazione costosa quando esiste già un piano valido;
• non riutilizzare un piano quando richiesta, catalogo, schema, fornitore o destinazione possono averne cambiato il significato.

Per esempio, puoi chiedere: «Trova i PDF modificati questa settimana in Progetti, calcola l'hash SHA-256 di ciascuno e crea un foglio con nome, data e hash.» La prima esecuzione può richiedere un piano nuovo. Se ripeti la richiesta, Metnos riusa quel piano soltanto se è adatto al riuso e le firme degli executor e del catalogo sono ancora valide.

2. Che cosa riceve e restituisce il motore

Per pianificare, il motore riceve la richiesta, le azioni riconosciute nel loro ordine, il catalogo visibile, la lingua, l'utente, il canale, la destinazione e gli eventuali dati già prodotti nel turno. Al termine restituisce:

• testo e tipo finale: risposta, domanda, input necessario o errore;
• il piano eseguito e la sua impronta;
• origine della decisione: fastpath, autopath, motore, recupero o terminatore;
• passi realmente eseguiti, risultati e tempi;
• eventuale dialogo da riprendere dopo una scelta o un consenso.

Il catalogo è il confine effettivo dell'esecuzione. Un executor assente o non ammesso non diventa disponibile soltanto perché il modello lo nomina.

3. I quattro livelli

L2 non viene interrogato come livello separato: interviene fra la nuova proposta e l'esecuzione. Piani L0 e L1 attraversano comunque la finalizzazione corrente, che applica guardie, ordine, regole di presentazione e richieste di consenso.

4. Il percorso di un turno

1. L'instradamento costruisce l'insieme delle capacità pertinenti.
2. L0 tenta prima una corrispondenza esatta e poi, soltanto per piani generalizzabili, una corrispondenza semantica.
3. Se L0 non risponde, L1 cerca un campione attivo compatibile con intenti, oggetto e cluster.
4. In assenza di un riuso valido, il componente di proposta costruisce uno o più piani candidati, secondo la configurazione attiva.
5. Le guardie strutturali e il validatore controllano il candidato e, nei casi ammessi, chiedono una sola nuova proposta correttiva.
6. Il motore di esecuzione condiviso esegue il piano. Se fallisce senza aver già prodotto effetti, il recupero può tentare un'alternativa.
7. Il terminatore presenta il risultato, una richiesta di dati o un limite esplicito; un turno efficace e memorizzabile alimenta L0 e le osservazioni L1.

5. Il piano interno, o framework

Un framework descrive i passi da eseguire, gli argomenti di ciascun passo e il modo in cui un risultato alimenta il passo successivo. Il suo formato non dipende dal modello che lo ha proposto:

{
  "steps": [
    {"tool": "find_files", "args": {"base_path": "Progetti", "pattern": "*.pdf"}},
    {"tool": "compute_signatures", "args": {"from_step": 1}},
    {"tool": "create_files_spreadsheet", "args": {"from_step": 2}},
    {"tool": "final_answer", "args": {}}
  ],
  "fillers": {},
  "final_message": ""
}

from_step e i riferimenti ${stepN.field} collegano i dati senza chiedere al modello di ricopiarli. Il runtime può inserire valori interni con ${RUNTIME:key}. I campi di configurazione marcati runtime_resolved, come account o client predefinito, non vengono scelti dal componente di proposta: li risolve il contesto dell'utente.

6. L0: fastpath

L0 nasce automaticamente dopo un turno riuscito, efficace e cacheabile. Non richiede un pulsante di approvazione. La ricerca ha due forme:

• 0a, esatta. L'impronta della query può riusare anche un piano legato ai valori specifici di quella stessa frase.
• 0b, semantica. La somiglianza usa l'embedder configurato e può servire soltanto piani non legati a valori specifici della richiesta originale.

Sono esclusi i piani dipendenti dal contesto del turno, come dialoghi, consenso, annullamento e sessioni web autenticate. Sono esclusi anche valori temporali assoluti che diventerebbero obsoleti. Prima della riesecuzione, le firme degli executor e delle famiglie di candidati devono coincidere; per una mutazione, i valori discriminanti devono essere fondati nella richiesta corrente.

7. L1: autopath

L1 conserva i piani riutilizzabili insieme alle intenzioni riconosciute, ai gruppi semantici, ai tempi e ai riscontri. Un riscontro positivo può promuovere un piano a riferimento attivo per quel gruppo. Per sequenze lunghe riuscite più volte, il runtime può creare un riferimento shadow: può essere usato con le stesse guardie, ma resta distinto da un piano confermato dall'utente.

La corrispondenza semantica rispetta il confine dell'oggetto canonico e una soglia di pertinenza. Anche L1 rifiuta piani legati a valori specifici della richiesta e controlla le firme del catalogo al momento del riuso. Riscontri negativi ripetuti possono retrocedere il campione e creare un'anti-autopath temporanea; un riscontro positivo successivo può rimuovere l'esclusione corrispondente.

8. L2: validatore

Il validatore è attivo per impostazione predefinita e non usa un modello. Controlla:

• esistenza del tool nel catalogo corrente;
• tipi dei campi e argomenti obbligatori;
• vincoli requires_one_of;
• from_step rivolti soltanto a passi precedenti;
• placeholder che il runtime possa risolvere.

Se trova un errore, il componente di proposta può essere invocato una volta escludendo l'impronta del piano non valido. Il nuovo candidato viene poi sottoposto di nuovo alle guardie deterministiche.

9. L3: proposta, esecuzione e recupero

Il componente che propone il piano è intercambiabile tramite configurazione. Le varianti supportate condividono il contratto Proposer: alcune producono un solo candidato, altre confrontano più alternative e ne restituiscono una. La grammatica, quando è attiva, limita la forma dell'output ma non rende deterministica la scelta semantica del modello.

Prima dell'esecuzione, il motore risolve i riferimenti, i dati raccolti da un dialogo e i valori interni del runtime. Poi controlla le condizioni di ogni passo e invoca l'executor previsto. Passi indipendenti vengono eseguiti in parallelo soltanto quando il contratto e il controllo preliminare lo consentono. Gli effetti esterni restano variabili: rete, filesystem, fornitori e contenuti possono cambiare fra due esecuzioni.

Il recupero distingue errori strutturali da errori operativi. Può cambiare piano per strumento, argomenti o input mancanti; non finge di riparare una rete assente. Se un passo ha già prodotto una modifica, non ripete l'intera sequenza e restituisce un esito parziale dichiarato come tale.

Le correzioni deterministiche restano indipendenti dal dominio e dalla lingua. Per esempio, un lessico sintattico comune e traducibile distingue una richiesta positiva come «usa il dispositivo» dalla sua negazione, «senza usare il dispositivo». Se il piano indica un'azione inversa ma omette la destinazione, il motore può ricavarla soltanto dal contratto di annullamento sigillato prodotto da un passo precedente, con executor esatto e schema compatibile; un valore esplicito non viene mai sostituito.

10. Riscontri e invecchiamento

Il riscontro valuta l'esito di un turno, non addestra direttamente il modello. L0 può eliminare la scorciatoia della query bocciata; L1 aggiorna osservazione, campione e anti-autopath. Le righe inutilizzate, retrocesse, scadute o riferite a executor non più presenti vengono eliminate dai processi di manutenzione.

Questa memoria conserva decisioni operative e osservazioni strutturate. Non è un profilo biografico dell'utente e non deve diventare una fonte di preferenze aperte inserite nel pianificatore.

11. Uso dalla chat

Non occorre conoscere L0, L1 o i nomi degli executor. L'utente descrive il risultato desiderato in linguaggio naturale. Per esempio:

Per esempio: «Confronta i file delle cartelle Preventivi e Contratti e mostrami quelli che hanno lo stesso contenuto ma un nome diverso.»

Per ispezionare o svuotare le cache serve invece la chat web: apri Impostazioni e scegli Praxis. Se la domanda parte da Telegram, Metnos deve spiegare questo percorso e specificare che la console non si trova nel client Telegram.

12. Confini delle garanzie

Il percorso completo è verificato da una certificazione logica eseguita fuori dal processo sotto prova. Ventiquattro flussi, ciascuno in italiano e in inglese, controllano piano, autorità, consenso, collocazione, effetti, recupero, risposta e postcondizioni. La certificazione non è una prova di carico e non sostituisce le sonde non distruttive sui confini reali.

• Un riuso valido della cache riprende lo stesso piano, ma non garantisce lo stesso risultato di un fornitore esterno.
• Una nuova proposta può variare anche con la stessa query. Insieme dei candidati, grammatica e validatore ne delimitano la forma, non ne provano la correttezza.
• I punteggi di ranking aiutano a scegliere fra candidati; non sono una prova oggettiva di qualità.
• L'osservazione del turno e la sorgente originaria restano l'evidenza utile; una spiegazione generata non può convalidare se stessa.

13. Console Praxis

La pagina /admin/praxis mostra gli strati persistenti: fastpath L0, autopath L1 attive o retrocesse, osservazioni e anti-autopath. Consente di eliminare una riga L0 o svuotare L0, L1 o entrambe. Lo svuotamento è amministrativo e non annullabile: rimuove capitale operativo appreso e può rallentare le richieste finché le cache non vengono ricostruite.

Le cache appartengono all'intera istanza. L0 conserva il testo normalizzato della richiesta e gli argomenti del piano; L1 conserva piani, impronte, intenzioni e vettori semantici. Non sono archivi di credenziali, ma possono contenere nomi, percorsi o altri dati presenti nella richiesta e vanno quindi trattate come dati riservati. A ogni riuso, account configurati, lingua, consenso, destinazione e autorizzazioni vengono risolti di nuovo nel contesto dell'utente corrente.

Riferimenti nel codice:

• runtime/engine/dispatch.py: percorso dei livelli e sequenza comune di finalizzazione;
• runtime/engine/fastpath.py: L0;
• runtime/engine/autopath.py: L1, riscontri e anti-autopath;
• runtime/engine/validator.py: L2;
• runtime/engine/proposer*.py, executor.py, recovery*.py e terminator*.py: L3;
• runtime/engine/cache_validity.py: validità del piano rispetto al catalogo corrente;
• runtime/http_routes_admin.py e runtime/templates/praxis.html: console.