docs: consolidate historical records and verify public manual publication
Publish documentation / publish (push) Successful in 29s
Publish documentation / publish (push) Successful in 29s
This commit is contained in:
Codex
@@ -1,420 +0,0 @@
|
||||
# Inventario delle funzionalità legacy di gestione metadati di ThothAI
|
||||
|
||||
Data dell'inventario: 2026-08-23
|
||||
|
||||
Ultima verifica rispetto a ThothII: 2026-08-31
|
||||
|
||||
Stato: **inventario storico verificato; non è una specifica dello stato corrente**.
|
||||
|
||||
Issue originaria: [mptyl/ThothII#6](https://git.tylconsulting.it/mptyl/ThothII/issues/6)
|
||||
|
||||
Fonte primaria: repository legacy annidato `Thoth/ThothAI`, commit
|
||||
`55855de0f18e5cb4bc72f0a2ab0a7317995186dd`.
|
||||
|
||||
Le citazioni che iniziano con `/Thoth/ThothAI/` sono relative alla radice di quella copia legacy
|
||||
fissata al commit indicato. Alla verifica del 2026-08-31 tutti i 68 riferimenti univoci puntavano a
|
||||
file esistenti e a intervalli di righe validi.
|
||||
|
||||
> Questo documento conserva l'inventario e le evidenze degli anti-pattern di ThothAI. Le frasi di
|
||||
> requisito nelle sezioni successive descrivono la baseline proposta il 2026-08-23; non prevalgono
|
||||
> su ADR, contratti, codice o `PROJECT_STATE.md` correnti.
|
||||
|
||||
## Stato rispetto al codice corrente
|
||||
|
||||
### Fonti autorevoli correnti
|
||||
|
||||
Per capire cosa esiste oggi, usare nell'ordine:
|
||||
|
||||
- `PROJECT_STATE.md`, per lo snapshot operativo aggiornato;
|
||||
- `CONTEXT.md`, per il modello di dominio corrente;
|
||||
- il [piano accettato del Metadata Catalog](../plans/2026-08-26-metadata-catalog-from-thothai.md)
|
||||
e il [contratto dello schema snapshot](../contracts/catalog-schema-snapshot.md);
|
||||
- gli ADR del catalogo, in particolare
|
||||
[0001](../adr/0001-postgres-metadata-catalog.md),
|
||||
[0004](../adr/0004-fastify-kysely-metadata-catalog.md),
|
||||
[0006](../adr/0006-separate-physical-and-logical-relationships.md),
|
||||
[0007](../adr/0007-durable-authoritative-schema-synchronization.md),
|
||||
[0008](../adr/0008-allow-manual-catalog-metadata-cleanup.md),
|
||||
[0009](../adr/0009-use-one-sequential-description-generation-run.md),
|
||||
[0010](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md) e
|
||||
[0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md);
|
||||
- l'implementazione, soprattutto `backend/src/catalog/types.ts`,
|
||||
`backend/src/routes/catalog-databases.ts`, `backend/src/routes/catalog-schema.ts`,
|
||||
`backend/src/routes/catalog-description-generation.ts`,
|
||||
`backend/src/routes/catalog-description-consolidation.ts` e
|
||||
`frontend/src/shell/DatabaseManagementPage.tsx`.
|
||||
|
||||
### Disposizione della baseline storica
|
||||
|
||||
| Capacità inventariata | Disposizione al 2026-08-31 | Evidenza corrente o nota |
|
||||
|---|---|---|
|
||||
| Configurazione per workspace, secret separati e test connessione | **Adottata e implementata** | PostgreSQL interno, binding `postgres_direct`, `rest_api` o `ssh_tunnel`, secret write-only; ADR [0001](../adr/0001-postgres-metadata-catalog.md)–[0004](../adr/0004-fastify-kysely-metadata-catalog.md) e `backend/src/routes/catalog-databases.ts`. |
|
||||
| Inventario fisico di tabelle, colonne, PK e FK | **Adottato e implementato** | La struttura osservata è distinta dai contenuti curati; `backend/src/catalog/types.ts`, `backend/src/routes/catalog-schema.ts` e ADR [0006](../adr/0006-separate-physical-and-logical-relationships.md). |
|
||||
| Riconciliazione completa e osservabile dello schema | **Implementata; semantica storica parzialmente superata** | I durable Catalog Sync Runs sono autoritativi, fail-closed, atomici e richiedono conferma per diff distruttivi. Non esiste il lifecycle `drift/removed` proposto qui: la sincronizzazione riconcilia la membership e ADR [0008](../adr/0008-allow-manual-catalog-metadata-cleanup.md) consente anche cleanup manuale esplicito, superando ADR-0005. |
|
||||
| Descrizione curata e Generated Description separate | **Adottata e implementata** | Tabelle e colonne espongono entrambi i campi in `backend/src/catalog/types.ts`; la copia selettiva AI → curato è in `backend/src/routes/catalog-description-consolidation.ts`. |
|
||||
| Generazione AI selettiva con run, stato e log | **Adottata e implementata** | Un run asincrono installazione-wide, sequenziale, con eventi persistiti e senza resume automatico; ADR [0009](../adr/0009-use-one-sequential-description-generation-run.md) e `backend/src/routes/catalog-description-generation.ts`. I thread daemon legacy sono **esclusi**. |
|
||||
| Campioni reali per la generazione e protezione dei campi sensibili | **Implementata come estensione correttiva** | ADR [0010](../adr/0010-allow-bounded-real-source-samples-for-description-generation.md) e [0011](../adr/0011-gate-source-samples-with-a-sensitive-data-flag.md): campioni bounded per colonne non sensibili e valori sintetici deterministici per quelle sensibili. |
|
||||
| Proposte persistenti, diff e versioni dei testi AI | **Escluse** | Resta un solo Generated Description modificabile. La cronologia dei run è operativa: non conserva prompt, output grezzo, proposta per colonna o audit della decisione umana. |
|
||||
| Relazioni fisiche | **Adottate e implementate** | Sono constraint immutabili con coppie ordinate di colonne; ADR [0006](../adr/0006-separate-physical-and-logical-relationships.md). |
|
||||
| Relazioni logiche curate o inferite | **Differite/aperto** | ADR-0006 riserva un modello e un lifecycle separati; non sono ancora parte del catalogo corrente. |
|
||||
| Alias semantici, descrizioni dei valori, sinonimi e concetti | **Differiti/aperti** | `PROJECT_STATE.md` li assegna a slice dedicate; non vanno dedotti dai campi fisici già implementati. |
|
||||
| Scope AI, ERD Mermaid e documentazione aggregata | **Differiti/aperti** | Restano capacità legacy inventariate, non una feature corrente del Metadata Catalog. Un eventuale lavoro dovrà avere contratto e gate propri. |
|
||||
| Export CSV e script SQL dei commenti | **Differiti/aperti; varianti insicure escluse** | Non risultano nella API corrente. Export di segreti, CSV incoerenti e SQL ricostruito da tipi incompleti restano vietati dagli anti-pattern sotto. |
|
||||
| Inferenza euristica e validazione di relazioni candidate | **Differita/aperta** | Non va confusa con la sincronizzazione delle FK fisiche; dipende dal futuro lifecycle delle relazioni logiche. |
|
||||
| Pubblicazione del catalogo al core/schema-linking/Qdrant | **Differita e richiesta come design gate successivo** | Il runtime NL→SQL continua a usare configurazione e annotations del workspace; il cutover è esplicitamente rinviato in `PROJECT_STATE.md`. |
|
||||
| Sette motori database del legacy | **Baseline superata** | La prima versione corrente supporta PostgreSQL; l'aggiunta di altri dialetti è una decisione futura, non parità automatica. |
|
||||
| GDPR e import da installazioni ThothAI | **Fuori dalla baseline iniziale; import differito** | GDPR resta escluso. Un eventuale import richiede una iniziativa idempotente e un cutover separati, non il riuso degli ID Django. |
|
||||
| Django Admin, modifica manuale della struttura sorgente, password nel catalogo, duplicazione opaca dei database | **Esclusi** | La UI e le API correnti amministrano il catalogo e non eseguono DDL sul DWH esterno; binding e segreti hanno ownership separata. |
|
||||
|
||||
## Sintesi storica
|
||||
|
||||
La baseline di parità proposta il 2026-08-23 comprende un catalogo dei database, l'inventario
|
||||
completo di tabelle, colonne e relazioni fisiche, metadati descrittivi modificabili, relazioni
|
||||
logiche, introspezione dello schema, generazione AI di descrizioni, scope, ERD Mermaid,
|
||||
documentazione ed esportazioni operative. La UI Django Admin è soltanto l'interfaccia legacy:
|
||||
non è un requisito architetturale da riprodurre.
|
||||
|
||||
Il flusso AI per le descrizioni individuato come baseline è volutamente semplice:
|
||||
|
||||
1. l'AI scrive nel campo `generated_comment` della tabella o colonna;
|
||||
2. l'utente seleziona gli elementi desiderati;
|
||||
3. un'azione copia il testo generato nel campo descrittivo canonico, sovrascrivendolo.
|
||||
|
||||
Nel codice esaminato **non esiste un'azione inversa che copi la descrizione canonica in
|
||||
`generated_comment`**. Le due azioni inverse presenti sulle colonne copiano invece il nome
|
||||
originale nel nome espanso e viceversa. Non risultano proposal, versioni, diff o workflow di
|
||||
approvazione: aggiungerli non sarebbe parità con ThothAI.
|
||||
|
||||
La parità deve essere di capacità e comportamento utile, non dei difetti del legacy. In
|
||||
particolare non vanno replicate esportazioni di password, SQL costruito con identificatori non
|
||||
quotati, job in thread daemon, incoerenze CSV e azioni admin non funzionanti.
|
||||
|
||||
## 1. Modello dati legacy
|
||||
|
||||
### Database
|
||||
|
||||
`SqlDb` contiene:
|
||||
|
||||
- identità e connessione (`name`, host, tipo motore, nome database, porta, schema, utente e
|
||||
password);
|
||||
- configurazione SSH e ambiente (`dev`, `test`, `prod`);
|
||||
- lingua per database, scope testuale e JSON, ERD Mermaid, direttive e report GDPR;
|
||||
- stato e log separati per generazione commenti tabella/colonna, introspezione, scope, ERD,
|
||||
documentazione e GDPR.
|
||||
|
||||
Evidenze: `/Thoth/ThothAI/backend/thoth_core/models.py:298-350`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/models.py:355-439`.
|
||||
|
||||
I motori dichiarati sono sette: Informix, MariaDB, MySQL, Oracle, PostgreSQL, SQL Server e
|
||||
SQLite (`/Thoth/ThothAI/backend/thoth_core/models.py:116-123`).
|
||||
|
||||
Il modello `Workspace` collega un solo `SqlDb`; contiene inoltre configurazioni degli agenti e
|
||||
duplica parte degli stati operativi (`/Thoth/ThothAI/backend/thoth_core/models.py:731-754`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/models.py:847-877`).
|
||||
|
||||
### Tabelle e colonne
|
||||
|
||||
`SqlTable` contiene nome, descrizione canonica, commento generato e riferimento al database
|
||||
(`/Thoth/ThothAI/backend/thoth_core/models.py:454-465`).
|
||||
|
||||
`SqlColumn` contiene nome originale, nome espanso, formato dati normalizzato, descrizione
|
||||
canonica, commento generato, descrizione dei valori e indicazioni PK/FK testuali
|
||||
(`/Thoth/ThothAI/backend/thoth_core/models.py:468-485`).
|
||||
|
||||
La cancellazione usa le cascade Django: database → tabelle → colonne e relazioni. Nei modelli
|
||||
non sono definite unicità composte per database/tabella/colonna. Ogni database ha un solo
|
||||
campo `schema`; tabelle e colonne non portano una propria identità di schema. Questi limiti
|
||||
non devono diventare vincoli del nuovo catalogo.
|
||||
|
||||
### Relazioni
|
||||
|
||||
`Relationship` collega tabella e colonna sorgente a tabella e colonna destinazione
|
||||
(`/Thoth/ThothAI/backend/thoth_core/models.py:488-503`). Il metodo
|
||||
`update_pk_fk_fields` ricostruisce stringhe descrittive PK/FK sulle colonne coinvolte
|
||||
(`/Thoth/ThothAI/backend/thoth_core/models.py:505-526`).
|
||||
|
||||
Il form admin verifica che le due tabelle appartengano allo stesso database e che ogni colonna
|
||||
appartenga alla tabella selezionata
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:19-165`).
|
||||
|
||||
Per ThothII occorre distinguere:
|
||||
|
||||
- struttura fisica importata dal database, da trattare come inventario non modificabile;
|
||||
- descrizioni e metadati semantici, modificabili con CRUD completo;
|
||||
- relazioni logiche aggiunte dall'utente, modificabili con CRUD completo.
|
||||
|
||||
Questa separazione conserva le capacità utili del legacy senza permettere che la UI alteri o
|
||||
falsifichi accidentalmente lo schema fisico osservato.
|
||||
|
||||
## 2. Capacità esposte dal Django Admin
|
||||
|
||||
La registrazione degli admin fornisce il CRUD Django standard per database, tabelle, colonne e
|
||||
relazioni (`/Thoth/ThothAI/backend/thoth_core/admin.py:13-24`). Oltre al CRUD, le azioni
|
||||
specifiche sono le seguenti.
|
||||
|
||||
### Database
|
||||
|
||||
L'admin di `SqlDb` espone:
|
||||
|
||||
- export/import CSV;
|
||||
- scansione delle tabelle, creazione delle relazioni e introspezione completa;
|
||||
- validazione FK e inferenza di relazioni candidate;
|
||||
- test della connessione;
|
||||
- duplicazione della configurazione;
|
||||
- generazione commenti AI per tabelle e colonne;
|
||||
- generazione sincrona o asincrona di scope, ERD e documentazione;
|
||||
- report GDPR;
|
||||
- export della struttura e script SQL dei commenti.
|
||||
|
||||
Evidenza: `/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:237-274`.
|
||||
|
||||
I campi di configurazione, contenuto e stato sono esposti in fieldset distinti
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:275-462`). In ThothII i segreti di
|
||||
connessione non devono essere campi ordinari del catalogo né essere restituiti dalle API di
|
||||
gestione metadati.
|
||||
|
||||
### Tabelle
|
||||
|
||||
L'admin delle tabelle permette export/import CSV, introspezione colonne, validazione e pulizia
|
||||
PK/FK, copia del commento AI nella descrizione, generazione commenti sincrona/asincrona e
|
||||
download dello script SQL (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:133-150`).
|
||||
|
||||
L'azione di applicazione AI opera solo sulle righe selezionate, ignora commenti generati vuoti
|
||||
e sovrascrive direttamente `description`
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqltable.py:165-190`).
|
||||
|
||||
### Colonne
|
||||
|
||||
L'admin delle colonne permette export/import CSV, copia del commento AI nella descrizione,
|
||||
copia bidirezionale fra nome originale e nome espanso, validazione FK e generazione AI sulle
|
||||
colonne selezionate (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:167-196`).
|
||||
|
||||
L'applicazione AI sovrascrive `column_description` soltanto per le colonne selezionate con
|
||||
`generated_comment` valorizzato
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:219-245`). Le azioni inverse riguardano
|
||||
esclusivamente i due campi nome
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqlcolumn.py:247-261`).
|
||||
|
||||
### Relazioni
|
||||
|
||||
L'admin delle relazioni offre il CRUD standard, filtri e ricerca, export/import e dichiara
|
||||
un'azione per aggiornare i campi PK/FK
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245`). L'ultima azione è però un
|
||||
difetto: `RelationshipAdmin` non implementa il metodo dichiarato; esiste soltanto il metodo
|
||||
statico sul model. La capacità da conservare è la ricostruzione coerente degli indicatori, non
|
||||
l'azione admin rotta.
|
||||
|
||||
## 3. Introspezione e riconciliazione dello schema
|
||||
|
||||
Il factory del database manager associa i sette motori ai rispettivi adapter e gestisce anche
|
||||
il tunnel SSH (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:77-227`).
|
||||
|
||||
L'introspezione legacy:
|
||||
|
||||
- riduce i tipi nativi a un insieme generico limitato, con fallback `VARCHAR`
|
||||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:237-266`);
|
||||
- legge e crea le colonne mancanti, ma non aggiorna tipo o commento di quelle già note
|
||||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:269-351`);
|
||||
- crea le tabelle mancanti e aggiorna la descrizione di quelle esistenti
|
||||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:431-481`);
|
||||
- legge le foreign key fisiche, crea al bisogno colonne mancanti e crea relazioni assenti
|
||||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:484-641`);
|
||||
- esegue l'intero processo nell'ordine tabelle → colonne → relazioni
|
||||
(`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:718-891`).
|
||||
|
||||
Il comportamento è additivo: gli oggetti scomparsi dal database sorgente non sono eliminati o
|
||||
marcati come obsoleti. Per ThothII la capacità richiesta è una scansione completa e
|
||||
riconciliabile, con provenienza, data dell'osservazione e stato degli oggetti rimossi o cambiati;
|
||||
non la semantica incompleta del refresh legacy.
|
||||
|
||||
L'inferenza di relazioni candidate combina convenzioni sui nomi, individuazione euristica delle
|
||||
PK e campionamento dei valori, con soglia di corrispondenza del 70%
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:605-801`). Deve rimanere una proposta
|
||||
esplicita da convalidare, non essere confusa con una foreign key fisica.
|
||||
|
||||
## 4. Generazione AI delle descrizioni
|
||||
|
||||
### Tabelle
|
||||
|
||||
La generazione procede in batch da dieci, utilizza lingua e contesto del database, schema
|
||||
osservato, descrizioni disponibili e fino a cinque righe di esempio; il risultato JSON aggiorna
|
||||
soltanto `table.generated_comment`
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:181-267`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:269-482`).
|
||||
|
||||
### Colonne
|
||||
|
||||
La generazione usa contesto della tabella, nomi delle colonne selezionate ed esempi reali, e
|
||||
scrive soltanto `column.generated_comment`
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:185-280`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:283-487`).
|
||||
|
||||
Provider e modello AI provengono dalla configurazione globale del backend; la lingua è invece
|
||||
per database (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/comment_generation_utils.py:156-219`).
|
||||
|
||||
### Comportamento di parità proposto il 2026-08-23
|
||||
|
||||
Il contratto funzionale minimo è esattamente questo:
|
||||
|
||||
- due campi per elemento: descrizione canonica e commento generato;
|
||||
- comando AI su elementi selezionati o su un insieme più ampio esplicitamente scelto;
|
||||
- scrittura/sovrascrittura del solo commento generato;
|
||||
- azione separata, su selezione dell'utente, che copia il generato nel canonico;
|
||||
- nessuna proposta persistente aggiuntiva, diff obbligatorio, approvazione multilivello o
|
||||
versionamento del testo.
|
||||
|
||||
Non è stata trovata una copia `descrizione → commento generato`. Se si desiderasse in futuro,
|
||||
sarebbe una nuova capacità, non parità legacy.
|
||||
|
||||
## 5. Scope, Mermaid e documentazione
|
||||
|
||||
### Scope
|
||||
|
||||
La generazione dello scope raccoglie nomi e descrizioni di tabelle e colonne, nome e lingua del
|
||||
database, richiede JSON al modello e persiste sia il JSON sia una resa Markdown. Se il JSON non
|
||||
è valido conserva il testo grezzo e svuota `scope_json`
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:25-163`).
|
||||
|
||||
### ERD Mermaid
|
||||
|
||||
L'ERD è prodotto dall'AI usando tabelle, colonne, PK/FK e relazioni. Il codice estrae un blocco
|
||||
Mermaid oppure usa la risposta grezza e la salva in `SqlDb.erd`, senza una validazione
|
||||
sintattica o semantica preventiva
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:18-145`).
|
||||
|
||||
Il rendering attivo usa un servizio Mermaid locale: health check, POST a `/svg` o `/png`,
|
||||
timeout e file temporanei
|
||||
(`/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:29-72`,
|
||||
`/Thoth/ThothAI/backend/thoth_ai_backend/mermaid_utils.py:281-464`). Il servizio Express espone
|
||||
`/health`, `/svg` e `/png` ed applica un limite al body
|
||||
(`/Thoth/ThothAI/docker/mermaid-service/src/server.js:13-23`,
|
||||
`/Thoth/ThothAI/docker/mermaid-service/src/server.js:70-115`). È distribuito come servizio
|
||||
Compose autonomo con health check
|
||||
(`/Thoth/ThothAI/docker-compose.yml:184-201`).
|
||||
|
||||
La vista ERD renderizza il Mermaid memorizzato in SVG tramite tale servizio e poi elimina il
|
||||
file temporaneo (`/Thoth/ThothAI/backend/thoth_ai_backend/views.py:227-288`).
|
||||
|
||||
### Documento del database
|
||||
|
||||
La documentazione HTML combina scope, relazioni, tabelle e colonne. Per le descrizioni usa il
|
||||
campo canonico e, quando vuoto, il commento generato
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188`).
|
||||
|
||||
Il processo di generazione chiede all'AI il diagramma Mermaid, lo salva nell'ERD e costruisce
|
||||
deterministicamente l'HTML corrente; l'HTML generato non incorpora il diagramma
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:767-922`). La UI espone il
|
||||
documento del database del workspace corrente e le route per HTML/PDF ed ERD/PDF
|
||||
(`/Thoth/ThothAI/backend/thoth_ai_backend/views.py:86-179`,
|
||||
`/Thoth/ThothAI/backend/thoth_ai_backend/urls.py:179-188`).
|
||||
|
||||
Per la parità ThothII servono quindi contenuto documentale strutturato, sorgente Mermaid
|
||||
persistita e rendering locale. La validazione Mermaid prima della pubblicazione è una
|
||||
correzione necessaria, non un cambiamento di scopo.
|
||||
|
||||
## 6. Export e comandi operativi
|
||||
|
||||
Le capacità utili rilevate sono:
|
||||
|
||||
- CSV di tabelle e colonne selezionate
|
||||
(`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:150-195`);
|
||||
- export CSV generico dei modelli e della struttura completa
|
||||
(`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:198-261`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:399-569`);
|
||||
- script SQL dei commenti per PostgreSQL, SQL Server, MySQL e MariaDB
|
||||
(`/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:25-316`);
|
||||
- comandi `generate_scope` e `generate_documentation`, indirizzabili per workspace, database o
|
||||
tutti i database (`/Thoth/ThothAI/backend/thoth_core/management/commands/generate_scope.py:12-89`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/management/commands/generate_documentation.py:12-89`);
|
||||
- export globale e per workspace
|
||||
(`/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/management/commands/export_workspace.py:19-96`);
|
||||
- aggiornamento delle descrizioni colonna da CSV per workspace
|
||||
(`/Thoth/ThothAI/backend/thoth_ai_backend/management/commands/update_column_descriptions.py:24-92`).
|
||||
|
||||
I comandi di importazione dalla produzione legacy sono deliberatamente esclusi da questo
|
||||
inventario di parità: costituiscono un progetto CLI `tht` separato, con mapping, validazione e
|
||||
cutover propri.
|
||||
|
||||
## 7. Esecuzioni asincrone e stato
|
||||
|
||||
Scope, ERD, documentazione e commenti possono essere lanciati in background. Il legacy crea
|
||||
thread daemon e memorizza task id, stato e log sui modelli
|
||||
(`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_erd.py:21-30`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_documentation.py:21-30`,
|
||||
`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_table_comments.py:39-87`).
|
||||
|
||||
La capacità da mantenere è: operazione lunga non bloccante, esclusione di esecuzioni
|
||||
confliggenti, stato osservabile e log. Il meccanismo daemon non è durevole, non permette
|
||||
recovery o cancellazione e non deve essere replicato letteralmente.
|
||||
|
||||
## 8. Difetti e comportamenti da non replicare
|
||||
|
||||
| Area | Evidenza legacy | Decisione di parità |
|
||||
|---|---|---|
|
||||
| Segreti negli export | L'export struttura include `password` in chiaro (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:516-559`); l'export generico serializza tutti i campi (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_models.py:19-64`). | Escludere sempre credenziali e segreti. |
|
||||
| SQL euristico | Il campionamento per inferire FK interpola identificatori senza quoting e usa query costruite come stringhe (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:697-750`). | Usare adapter sicuri, quoting per dialetto e query read-only con limiti. |
|
||||
| Refresh incompleto | L'introspezione aggiunge oggetti ma non riconcilia rimozioni e non aggiorna tutte le proprietà (`/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:318-351`, `/Thoth/ThothAI/backend/thoth_core/dbmanagement.py:459-481`). | Scansioni versionate e stato drift/removed. |
|
||||
| Relazioni denormalizzate | L'aggiornamento ricostruisce stringhe PK/FK solo sulle colonne partecipanti e non ripulisce esplicitamente valori obsoleti (`/Thoth/ThothAI/backend/thoth_core/models.py:505-526`). | Derivare indicatori dalle relazioni correnti. |
|
||||
| Azione relazione rotta | L'admin dichiara `update_pk_fk_fields` ma non lo implementa (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_relationship.py:219-245`). | Esporre un comando applicativo testato. |
|
||||
| CSV colonne incoerente | L'header ha sei colonne, le righe ne emettono otto incluse PK/FK (`/Thoth/ThothAI/backend/thoth_core/utilities/utils.py:165-195`). | Contratto CSV versionato e testato. |
|
||||
| Comando export rotto | `export_single_model` usa l'app label `toth_be` e un attributo non definito (`/Thoth/ThothAI/backend/thoth_core/management/commands/export_single_model.py:19-67`). | Non portare il comando; sostituirlo con export catalogo coerente. |
|
||||
| Batch AI colonne | Un batch usa la prima tabella selezionata come contesto per tutte le colonne (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_column_comments.py:230-268`). | Raggruppare sempre per database e tabella. |
|
||||
| Contesto AI tabelle | Il fallback al commento generato è calcolato ma non incluso nel dataframe finale (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_table_comments.py:485-525`). | Costruire il contesto dal valore effettivamente visibile. |
|
||||
| Duplicazione DB | Duplica configurazione e vector DB, azzerando soltanto una data di aggiornamento (`/Thoth/ThothAI/backend/thoth_core/admin_models/admin_sqldb.py:514-569`). | Se mantenuta, duplicare soltanto metadati esplicitamente scelti, mai segreti o stati. |
|
||||
| Scope non JSON | Il generatore intercetta internamente il JSON non valido, mentre l'azione può comunque mostrare successo (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/create_db_scope.py:92-192`). | Stato `failed` o `needs_review`, senza falso successo. |
|
||||
| Mermaid non validato | La risposta AI viene salvata dopo la sola estrazione del blocco (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_erd.py:88-121`). | Validare prima di pubblicare e conservare l'errore di rendering. |
|
||||
| HTML non escapato | I valori descrittivi sono interpolati direttamente nell'HTML (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/generate_db_documentation.py:35-188`). | Escape/sanitizzazione obbligatori. |
|
||||
| Job daemon | I task sono thread in-process (`/Thoth/ThothAI/backend/thoth_core/thoth_ai/thoth_workflow/async_scope.py:21-62`). | Esecuzione durevole o almeno recuperabile, con idempotenza. |
|
||||
| Script MySQL | I commenti colonna usano `ALTER ... MODIFY COLUMN` basandosi sul tipo normalizzato (`/Thoth/ThothAI/backend/thoth_core/admin_utils/sql_comment_script.py:244-316`). | Generare solo con tipo nativo completo oppure bloccare l'export rischioso. |
|
||||
|
||||
Il modulo contiene anche un helper verso `mermaid.ink`, ma non risultano call site nel tree
|
||||
legacy; il percorso attivo è il servizio locale. Non va quindi considerata una dipendenza
|
||||
funzionale da conservare.
|
||||
|
||||
## 9. Baseline di parità proposta il 2026-08-23
|
||||
|
||||
### Necessario
|
||||
|
||||
- database gestiti derivati dalla configurazione dei workspace;
|
||||
- inventario completo del database, anche oltre il sottoinsieme usato dal workflow core;
|
||||
- scansione di tabelle, colonne, chiavi e relazioni fisiche con drift osservabile;
|
||||
- descrizioni canoniche e commenti AI separati per tabelle e colonne;
|
||||
- generazione AI selettiva e copia selettiva AI → descrizione, senza workflow aggiuntivo;
|
||||
- CRUD dei metadati semantici e delle relazioni logiche;
|
||||
- scope strutturato, documento generale strutturato ed ERD Mermaid;
|
||||
- servizio locale per validazione/rendering Mermaid in SVG/PNG/PDF;
|
||||
- test connessione, inferenza/validazione delle relazioni e operazioni lunghe con stato/log;
|
||||
- export CSV sicuro e script SQL commenti solo quando il dialetto può essere ricostruito senza
|
||||
perdita;
|
||||
- API e UI dedicate, separate dal workflow NL→SQL;
|
||||
- pubblicazione esplicita e controllata del sottoinsieme utile al core/Qdrant.
|
||||
|
||||
### Estensione, non requisito di parità iniziale
|
||||
|
||||
- analisi e report GDPR;
|
||||
- importazione dei dati da installazioni ThothAI in produzione, da progettare come iniziativa
|
||||
CLI `tht` separata.
|
||||
|
||||
### Esplicitamente escluso
|
||||
|
||||
- replica del Django Admin o del suo modello di permessi implicito;
|
||||
- modifica manuale della struttura fisica osservata;
|
||||
- memorizzazione o export di password nel catalogo;
|
||||
- dipendenza del workflow SQL dalla disponibilità della nuova UI;
|
||||
- proposal/versioning/diff per i commenti AI;
|
||||
- copia descrizione → commento AI, non presente nelle fonti;
|
||||
- difetti tecnici e comportamenti insicuri elencati sopra.
|
||||
|
||||
## Conclusione
|
||||
|
||||
ThothAI fornisce già il perimetro funzionale di un catalogo metadati, ma lo realizza mescolando
|
||||
configurazione di connessione, inventario fisico, contenuti semantici, job e UI nel modello
|
||||
Django. ThothII può raggiungere la parità separando questi aspetti e mantenendo invariato il
|
||||
workflow SQL: il catalogo gestisce l'intero database, mentre il core continua a consumare
|
||||
soltanto il sottoinsieme dichiarato dal workspace e pubblicato nel proprio indice Qdrant.
|
||||
|
||||
La regola di Q6 è semplice e verificata nelle fonti: generazione nel campo AI, selezione
|
||||
esplicita dell'utente, copia nel campo canonico. Ogni meccanismo ulteriore sarebbe una nuova
|
||||
funzionalità e non è necessario per la parità.
|
||||
@@ -1,206 +0,0 @@
|
||||
# PostgreSQL deployment and failure-isolation constraints for the Metadata Catalog
|
||||
|
||||
Original research: 2026-08-23
|
||||
|
||||
Last verified against the repository: 2026-08-31
|
||||
|
||||
Issue: [#8 — Assess PostgreSQL deployment and failure-isolation constraints](https://git.tylconsulting.it/mptyl/ThothII/issues/8)
|
||||
|
||||
> **Status: partially superseded by ADR-0004.** This is historical research, not the current
|
||||
> architecture contract. The recommendation to run a separate `catalog-api` process was rejected
|
||||
> by [ADR-0004](../adr/0004-fastify-kysely-metadata-catalog.md). Operational constraints that do
|
||||
> not depend on that process boundary remain useful, but the status table below is authoritative
|
||||
> for what the 2026-08-31 code actually adopts, rejects, or leaves pending.
|
||||
|
||||
## Question
|
||||
|
||||
How can a Metadata Catalog PostgreSQL service be deployed, backed up, diagnosed, and made
|
||||
non-blocking for the NL→SQL workflow across local and server installations?
|
||||
|
||||
## Current decision and implementation
|
||||
|
||||
[ADR-0001](../adr/0001-postgres-metadata-catalog.md) selects PostgreSQL as the catalog authority.
|
||||
[ADR-0003](../adr/0003-installation-local-database-bindings.md) keeps database bindings
|
||||
installation-local. [ADR-0004](../adr/0004-fastify-kysely-metadata-catalog.md) then places the
|
||||
catalog in the existing Fastify backend as an isolated Kysely module rather than a microservice.
|
||||
|
||||
The implemented dependency graph is therefore:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI[Frontend]
|
||||
Core[Core: Fastify workflow and catalog modules]
|
||||
Pi[Pi and tht workflow]
|
||||
PG[(catalog-db PostgreSQL)]
|
||||
Semantic[Qdrant and embedding]
|
||||
|
||||
UI --> Core
|
||||
Core --> Pi
|
||||
Core --> PG
|
||||
Core --> Semantic
|
||||
```
|
||||
|
||||
The catalog module is isolated behind a repository interface, but it is not process-isolated.
|
||||
`core` owns the catalog pool and Compose waits for `catalog-db` health before starting `core`
|
||||
(`compose.yaml`, `backend/src/app.ts`, `backend/src/catalog/repository.ts`). Database-management records still do
|
||||
not feed the NL→SQL handoff, so a running workflow does not read catalog rows; that cutover remains
|
||||
future work (`PROJECT_STATE.md`).
|
||||
|
||||
## Verification result
|
||||
|
||||
| Area | Status on 2026-08-31 | Evidence and consequence |
|
||||
| --- | --- | --- |
|
||||
| PostgreSQL as canonical catalog store | **Adopted** | ADR-0001 is implemented by the PostgreSQL-backed Kysely repository and the internal `catalog-db` service. |
|
||||
| One Workspace Database per workspace and installation-local bindings | **Adopted** | ADR-0003 and the catalog migrations enforce the model; workspace identity remains in the workspace registry. |
|
||||
| Separate `catalog-api` process | **Superseded/rejected** | ADR-0004 explicitly chooses an isolated module inside the existing Fastify process. There is no catalog microservice or separate catalog liveness endpoint. |
|
||||
| No catalog pool, credential, or Compose dependency in `core` | **Superseded/rejected** | `core` owns the runtime pool, receives the runtime password secret, and declares `depends_on: catalog-db: service_healthy`. The old process-level isolation acceptance criterion is not current architecture. |
|
||||
| Private PostgreSQL service and durable volume | **Adopted** | `catalog-db` uses a version-and-digest-pinned PostgreSQL 17.6 image, the private `thothii` network, no published host port, a `pg_isready`-based healthcheck, and `catalog-data`. Compose contract tests assert this topology (`scripts/test-default-compose.sh`). |
|
||||
| Different local and server database topology | **Superseded/rejected** | Both current profiles inherit the same internal `catalog-db` and named volume. `deploy/compose.server.yaml` does not replace it with an operator-provided endpoint. |
|
||||
| Runtime and migrator role separation | **Adopted** | `core` receives only `thothii_catalog_runtime`; the profile-gated `catalog-migrate` job receives only `thothii_catalog_migrate`. Bootstrap grants runtime DML/sequence privileges without DDL (`docker/catalog-db-init.sql`). |
|
||||
| Dedicated backup role | **Pending** | There is no `catalog_backup` role or backup secret. |
|
||||
| Explicit one-shot migrations | **Adopted** | `backend/src/catalog/migrate.ts` registers ordered Kysely migrations and uses a pool of one. `scripts/run-stack.sh` starts PostgreSQL and runs `catalog-migrate` before local startup; migrations are not hidden in backend startup. |
|
||||
| Checksums, drift/pending refusal, and migration readiness | **Pending** | No repository-owned checksum policy, drift report, or readiness gate exists for catalog migrations. The backend can start without checking the Kysely migration head when launched outside the local helper. |
|
||||
| Bounded runtime connection pool | **Adopted** | `backend/src/catalog/repository.ts` sets `max: 5` and `connectionTimeoutMillis: 3000`, and closes Kysely with the Fastify lifecycle. |
|
||||
| `lock_timeout`, `statement_timeout`, and catalog TLS policy | **Pending** | The runtime pool does not set query or lock timeouts. Catalog connection configuration has no explicit CA/hostname-verification contract; the server profile still uses the private Compose network. |
|
||||
| Process liveness independent of catalog queries | **Adopted** | `GET /health` returns `{status: "ok"}` without probing PostgreSQL, and `backend/test/health.test.ts` preserves that behavior. `/catalog/status` performs the catalog-specific availability check. |
|
||||
| Stack startup independent of catalog availability | **Superseded/rejected** | Compose blocks `core` on healthy `catalog-db`. The host service health fold does not list `catalog-db`, but it cannot make `core` start while its Compose dependency is unhealthy. |
|
||||
| Uniform catalog-outage response (`503` plus `Retry-After`) | **Pending** | Routes map the domain `CatalogUnavailableError` to a sanitized `503`, and an omitted catalog configuration uses an unavailable repository. PostgreSQL driver failures are not uniformly translated to that domain error, and no `Retry-After` contract is implemented. |
|
||||
| Catalog-specific readiness and `tht doctor` checks | **Pending** | There is no `/health/ready` for the catalog and no doctor section for connection, migration head, pool saturation, backup age, or publication lag (`tools/tht/internal/doctor/report.go`). |
|
||||
| Logical catalog backup and restore | **Pending** | Current backup archives omit `catalog-data` and do not run `pg_dump`; server archives include only Qdrant and embedding volumes. A backup can therefore succeed without preserving the Metadata Catalog (`tools/tht/internal/backup/create.go`). |
|
||||
| Last-good Publication and catalog-to-Qdrant cutover | **Pending** | The current database-management slice does not change the NL→SQL runtime or publish catalog metadata to Qdrant. |
|
||||
|
||||
## Current operational contract
|
||||
|
||||
### Deployment and credentials
|
||||
|
||||
- Local and server Compose profiles currently use the same installation-owned `catalog-db`
|
||||
container and `catalog-data` named volume. PostgreSQL is private to the Compose network.
|
||||
- The database bootstrap login is the migrator. The init script creates the separate runtime login
|
||||
from a Docker secret and grants only runtime DML and sequence access.
|
||||
- Runtime and migrator passwords are separate protected host files exposed as separate Docker
|
||||
secrets. Neither value belongs in tracked environment files
|
||||
(`deploy/env/local.env.example`, `deploy/env/server.env.example`).
|
||||
- The Fastify catalog repository uses a five-connection pool with a three-second connection
|
||||
timeout. Fastify closes the repository pool during shutdown.
|
||||
|
||||
### Migrations
|
||||
|
||||
The compiled `catalog-migrate` entry point owns schema changes and uses the migrator credential.
|
||||
The current ordered series is under
|
||||
`backend/src/catalog/migrations/`. The local launcher runs
|
||||
it before the normal stack, while production rollout must invoke the profile-gated service
|
||||
explicitly.
|
||||
|
||||
This is weaker than the original recommendation in two ways: there is no catalog readiness check
|
||||
for pending or unknown migrations, and the repository does not maintain content checksums for
|
||||
migration drift. Until those checks exist, “the migrator completed” is the available deployment
|
||||
gate; the application itself does not prove migration compatibility.
|
||||
|
||||
### Failure behavior actually provided
|
||||
|
||||
| Failure | Current catalog behavior | Current workflow behavior |
|
||||
| --- | --- | --- |
|
||||
| Catalog configuration omitted when launching the backend directly | Fastify uses `UnavailableCatalogRepository`; `/catalog/status` reports unavailable and domain-mapped catalog operations return sanitized `503` | `/health`, sessions, and SSE remain available |
|
||||
| `catalog-db` unhealthy before Compose startup | `core` is not started because its dependency is not healthy | Workflow startup is blocked |
|
||||
| PostgreSQL becomes unavailable after startup | `/health` remains process-only and `/catalog/status` reports unavailable; route errors are sanitized, but a uniform `503`/`Retry-After` mapping is not guaranteed | Existing session code does not read catalog rows, but both surfaces still share one Fastify process |
|
||||
| Migrations are pending or incompatible | No dedicated readiness refusal exists; affected catalog operations fail | No catalog-to-workflow handoff exists yet, but local deployment correctness depends on running `catalog-migrate` first |
|
||||
| Catalog backup is requested through current `tht backup` | No PostgreSQL dump is added and `catalog-data` is omitted | The archive may succeed while being unable to restore catalog state |
|
||||
|
||||
The shared process means resource exhaustion, fatal process errors, and startup hooks remain a
|
||||
common failure domain even though repository calls are separated. Conversely, placing the module
|
||||
inside Fastify does not require workflow code to consume catalog rows: preserving that data-flow
|
||||
boundary is still the useful part of the original isolation recommendation.
|
||||
|
||||
## Historical recommendations that remain valid backlog
|
||||
|
||||
The following constraints survive ADR-0004 because they can be implemented inside the current
|
||||
Fastify deployment:
|
||||
|
||||
1. **Bound every database operation.** Keep the adopted pool and connection timeout; add explicit
|
||||
request query and lock timeouts. Long model calls and source sampling must not hold catalog
|
||||
transactions.
|
||||
2. **Make failures component-specific.** Translate connection, timeout, and pool-exhaustion errors
|
||||
into one sanitized catalog-unavailable response, add bounded retry guidance, and keep `/health`
|
||||
process-only.
|
||||
3. **Make migration compatibility observable.** Report applied, pending, unknown, and drifted
|
||||
migrations through a catalog readiness check and `tht doctor`; do not put migrator credentials
|
||||
in `core`.
|
||||
4. **Define a server TLS topology before externalizing PostgreSQL.** If the server profile moves to
|
||||
an operator-provided endpoint, use a dedicated database and roles, protected CA material, and
|
||||
hostname verification. Sharing a cluster leaves connection, maintenance, WAL, and storage blast
|
||||
radius even when schemas are separate. PostgreSQL documents the relevant connection and TLS
|
||||
parameters in its
|
||||
[connection parameter reference](https://www.postgresql.org/docs/current/libpq-connect.html).
|
||||
5. **Keep derived semantic data non-canonical.** When catalog publication is implemented, activate
|
||||
complete immutable revisions and retain the last successfully activated revision rather than
|
||||
exposing mutable catalog rows to the workflow.
|
||||
|
||||
## Backup and restore target
|
||||
|
||||
The original logical-backup recommendation is still valid and is now a confirmed implementation
|
||||
gap.
|
||||
|
||||
### Backup
|
||||
|
||||
Extend `tht backup create` with a catalog step that runs `pg_dump --format=custom` through a
|
||||
one-shot helper and adds the dump plus checksum to the installation manifest. Do not treat a tar of
|
||||
a live data volume as a PostgreSQL consistency contract. PostgreSQL documents that `pg_dump`
|
||||
creates a consistent export while the database remains in use and that custom format supports
|
||||
selective restore ([`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html)).
|
||||
|
||||
Use a dedicated least-privilege backup role, never write dumps into a workspace repository, and
|
||||
record at least the server version, migration head, checksum, creation time, and catalog revision
|
||||
identifiers. A filesystem/Qdrant archive with a failed or absent catalog dump must be reported as
|
||||
incomplete.
|
||||
|
||||
### Restore
|
||||
|
||||
Restore only through an explicit maintenance operation into an empty or deliberately cleaned
|
||||
target. Validate the archive checksum, run `pg_restore --exit-on-error --single-transaction`, then
|
||||
verify migration compatibility, referential integrity, bounded entity counts, and an authenticated
|
||||
catalog smoke test. The controls are documented by PostgreSQL
|
||||
([`pg_restore`](https://www.postgresql.org/docs/current/app-pgrestore.html)). Keep the old database
|
||||
until validation passes; rollback should switch the endpoint or retained volume, not dual-write.
|
||||
|
||||
## Diagnostics target
|
||||
|
||||
- Keep the shared `GET /health` endpoint process-only.
|
||||
- Treat `/catalog/status` as the current minimal availability surface; add a bounded catalog
|
||||
readiness check covering connection and migration compatibility before using it as a rollout
|
||||
gate.
|
||||
- Add read-only `tht doctor` checks for secret-file presence and permissions, PostgreSQL
|
||||
reachability, authentication, migration state, pool saturation, and last successful catalog
|
||||
backup. Sanitize all DSNs and errors.
|
||||
- Use `pg_isready` only for server transport readiness. Its result does not prove schema or runtime
|
||||
authorization correctness
|
||||
([`pg_isready`](https://www.postgresql.org/docs/current/app-pg-isready.html)).
|
||||
- Add structured metrics for connection acquisition failures, pool use, query/lock timeout,
|
||||
migration head, background-job backlog, and backup age. Do not log connection strings, source
|
||||
samples, prompts, or generated descriptions at info level.
|
||||
|
||||
## Recommended closure criteria
|
||||
|
||||
1. Decide whether ADR-0004's statement that catalog unavailability does not make sessions or SSE
|
||||
unavailable must also hold at Compose startup. If yes, remove or soften the hard `core` →
|
||||
`catalog-db` startup dependency without reintroducing a microservice.
|
||||
2. Prove a configured PostgreSQL outage produces the same sanitized catalog response across every
|
||||
catalog route while `/health`, session creation, and SSE continue to work.
|
||||
3. Add catalog migration compatibility to readiness and `tht doctor`, including pending, unknown,
|
||||
and drifted states.
|
||||
4. Add a real `pg_dump`/`pg_restore` round-trip to local and server backup tests, and fail backup
|
||||
publication when the catalog dump is absent or fails.
|
||||
5. Before enabling a remote server catalog, define TLS verification, credential files, connection
|
||||
limits, and the accepted cluster-level blast radius.
|
||||
6. Before the NL→SQL cutover, define and test an immutable last-good Publication boundary; do not
|
||||
dual-read mutable PostgreSQL rows and legacy metadata as competing authorities.
|
||||
|
||||
## Decision summary
|
||||
|
||||
PostgreSQL, installation-local bindings, private deployment, role separation, one-shot migrations,
|
||||
bounded pooling, and process-only liveness are implemented. The separate `catalog-api` process and
|
||||
the claim that `core` has no catalog dependency are not current design: ADR-0004 chose the existing
|
||||
Fastify process, and Compose currently blocks `core` startup on `catalog-db` health. Logical
|
||||
backup/restore, catalog migration readiness and drift detection, consistent outage mapping,
|
||||
catalog-specific doctor checks, server TLS/external topology, and last-good publication remain
|
||||
pending. Those open constraints should be treated as backlog, not as capabilities already provided
|
||||
by the repository.
|
||||
@@ -1,301 +0,0 @@
|
||||
# ThothII metadata publication and Qdrant revision seams
|
||||
|
||||
**Research question:** Which existing workspace, snapshot, preprocessing, Qdrant,
|
||||
session-pinning, and runtime read-only contracts constrain metadata publication without changing
|
||||
the NL→SQL workflow?
|
||||
|
||||
**Last verified:** 2026-08-31
|
||||
|
||||
**Validity:** Active architectural research; the catalog-to-core integration described below is
|
||||
still **deferred**, not implemented.
|
||||
|
||||
**Current authorities:** `PROJECT_STATE.md`,
|
||||
[`workspace-evidence-v3.md`](../contracts/workspace-evidence-v3.md),
|
||||
[`workspace-preprocessing-cli.md`](../contracts/workspace-preprocessing-cli.md),
|
||||
[`tht-dwh.md`](../contracts/tht-dwh.md),
|
||||
[`ADR-0001`](../adr/0001-postgres-metadata-catalog.md), and
|
||||
[`ADR-0004`](../adr/0004-fastify-kysely-metadata-catalog.md). These sources and current code
|
||||
override this research note if they diverge.
|
||||
|
||||
## Revalidation against the current implementation
|
||||
|
||||
| Finding | Status on 2026-08-31 | Current evidence and consequence |
|
||||
| --- | --- | --- |
|
||||
| PostgreSQL metadata authority in the existing Fastify backend | **Adopted/current** | ADR-0001 and ADR-0004 are implemented; the catalog is the management-plane authority. |
|
||||
| Git workspace revision, immutable registry snapshot, and revision-pinned runtime | **Adopted/current** | Registry activation and the Workspace Evidence v3 contract still provide the publication boundary for runtime-owned files. |
|
||||
| Qdrant read isolation for schema and Evidence by `workspace_id` + `workspace_revision` | **Adopted/current** | `QdrantVectorStore.search()` applies `_revision_filter()` to schema/Evidence; Memory and solved questions intentionally remain workspace-wide (`harness/tht/adapters/vector/qdrant.py`). |
|
||||
| Physical schema as a file in the Git publication | **Superseded clarification** | `physical.yaml` is owned by the immutable `.tht-dwh` generation selected by `ACTIVE`, not by the Git workspace revision ([DWH contract](../contracts/tht-dwh.md)). Git currently supplies the revision-pinned curated `schema/annotations.yaml`. |
|
||||
| Catalog-to-core publisher | **Open/deferred** | No current route or service projects catalog records into core artifacts. `PROJECT_STATE.md` explicitly defers the schema-linking integration (`PROJECT_STATE.md:160-171`). |
|
||||
| Explicit Core Schema Selection | **Open/deferred** | The workspace descriptor selects one database and one physical schema, but has no table/column allowlist (`backend/src/workspaces/schema.ts`); no catalog selection is handed to `tht`. |
|
||||
| Cross-revision hash lookup used by schema synchronization | **Open defect** | Reads are revision-filtered, but `existing_hashes()` is not. A same-key/same-content point from an older revision can suppress the required upsert into the new revision (`harness/tht/adapters/vector/qdrant.py`, `harness/tht/cli/vector_cmd.py`). |
|
||||
| Deletion/GC | **Current for Evidence; open for schema** | Evidence has generation inventory, retention, compensation, and exact-generation deletion. `sync_canonical_records()` never deletes schema records absent from the new canonical set, and no revision-retention GC exists for schema points. |
|
||||
| Annotation consumption | **Current but incomplete** | M-Schema rendering and schema embeddings consume `Annotations`; `tht schema columns` still returns only physical comments, so F4 does not display annotation descriptions (`harness/tht/cli/schema_cmd.py`, `harness/.pi/extensions/tht-gate.js`). |
|
||||
|
||||
## Conclusion
|
||||
|
||||
The lowest-impact **proposed** publication seam is not a new writer inside the NL→SQL workflow and
|
||||
is not a direct CRUD-to-Qdrant path. The existing core consumes an introspected `PhysicalSchema`
|
||||
from the active immutable DWH generation and a curated, Git-revision-pinned `Annotations`
|
||||
document. A future explicit publication operation should project the approved catalog subset into
|
||||
a new Core Schema Selection contract and the curated annotations, activate a new immutable Git
|
||||
revision, and then invoke the existing `workspace index-schema` preprocessing operation. Qdrant
|
||||
remains a derived, rebuildable projection. None of this catalog-to-core handoff exists yet;
|
||||
`PROJECT_STATE.md:160-164` deliberately defers it to the next design
|
||||
gate.
|
||||
|
||||
The proposed flow would preserve the existing runtime path:
|
||||
|
||||
```text
|
||||
approved catalog data
|
||||
-> explicit Core Schema Selection + curated annotations projection (future)
|
||||
-> workspace Git revision (annotations and selection contract; physical.yaml stays DWH-owned)
|
||||
-> immutable registry snapshot
|
||||
-> revision-bound runtime configuration
|
||||
-> existing tht vector index-schema
|
||||
-> Qdrant records filtered by workspace_id + workspace_revision
|
||||
-> existing retrieval_pack / schema render / F4 review
|
||||
```
|
||||
|
||||
The complete database inventory remains in the Metadata Catalog. Only an explicit Core Schema
|
||||
Selection and approved semantic fields should be projected into the artifacts used by the SQL
|
||||
workflow. ThothII does not currently model or publish that table/column-level selection, so both
|
||||
the projection contract and its operational publisher are new work.
|
||||
|
||||
## 1. Current authority and publication boundary
|
||||
|
||||
The workspace descriptor identifies one PostgreSQL database and one physical schema, plus one
|
||||
workspace-owned Qdrant collection; it has no table or column allowlist
|
||||
(`backend/src/workspaces/schema.ts`).
|
||||
Consequently, a full-database metadata catalog and the subset eligible for the SQL core cannot be
|
||||
represented as the same current descriptor object.
|
||||
|
||||
The existing public contract makes the Git workspace repository curator-owned. Changes occur in a
|
||||
separate authoring clone followed by installation pull, and the API does not write workspace,
|
||||
schema, or Evidence paths
|
||||
([Workspace Evidence v3 contract](../contracts/workspace-evidence-v3.md)).
|
||||
Therefore a browser CRUD service cannot silently make its PostgreSQL state authoritative for the
|
||||
core without either:
|
||||
|
||||
1. exporting/committing a deterministic workspace projection through the existing curator flow;
|
||||
or
|
||||
2. deliberately replacing this Git-authority contract.
|
||||
|
||||
The first option preserves current architecture and session reproducibility.
|
||||
|
||||
Registry activation validates every descriptor at one exact commit, validates and synchronizes
|
||||
the commit's `schema/annotations.yaml`, and rejects duplicate ownership of a Qdrant collection
|
||||
(`backend/src/workspaces/registry.ts`,
|
||||
`backend/src/workspaces/git-repository.ts`,
|
||||
`backend/src/workspaces/annotations-sync.ts`).
|
||||
It writes the candidate snapshot into a staging directory, records file digests in
|
||||
`snapshot.json`, atomically renames the directory, and only then moves active state
|
||||
(`backend/src/workspaces/registry.ts`).
|
||||
That is the existing atomic publication boundary to reuse.
|
||||
|
||||
## 2. Canonical schema inputs already consumed by the core
|
||||
|
||||
The harness separates source facts from curated semantics:
|
||||
|
||||
- `PhysicalSchema` contains database/schema identity and tables; table facts include comments,
|
||||
columns, physical foreign keys, and indexes; columns contain type, nullability, primary-key,
|
||||
default, source comment, examples, and eligibility
|
||||
(`harness/tht/mschema/models.py`).
|
||||
- `Annotations` contains curated table descriptions, concepts and notes, column descriptions,
|
||||
synonyms, concepts, evidence, notes and eligibility overrides, plus logical foreign keys
|
||||
(`harness/tht/mschema/models.py`).
|
||||
|
||||
Rendering already gives annotations precedence over source comments and merges physical and
|
||||
logical foreign keys. It also applies column eligibility before producing M-Schema context
|
||||
(`harness/tht/mschema/render.py`). This makes
|
||||
`Annotations` the natural narrow projection target for approved descriptions, synonyms, logical
|
||||
relationships, and eligibility from the new catalog.
|
||||
|
||||
There are two current compatibility gaps:
|
||||
|
||||
- `schema_records()` embeds table descriptions/concepts and column descriptions/synonyms/examples,
|
||||
but does not include physical or logical foreign keys in vector record content
|
||||
(`harness/tht/vectorstore/records.py`).
|
||||
Relationships still reach the model through deterministic schema rendering, not through schema
|
||||
candidate embeddings.
|
||||
- The F4 widget loads columns with `tht schema columns`
|
||||
(`harness/.pi/extensions/tht-gate.js`), but that
|
||||
command still returns only `PhysicalSchema.comment` values and does not merge
|
||||
`Annotations`
|
||||
(`harness/tht/cli/schema_cmd.py`).
|
||||
A publisher that writes only annotations would improve vector search and rendered M-Schema but
|
||||
not the table/column descriptions displayed by this existing reviewer widget. Fixing the command
|
||||
to use the existing merged description helpers would preserve the workflow shape while closing
|
||||
the inconsistency.
|
||||
|
||||
## 3. Existing preprocessing seam
|
||||
|
||||
`workspace index-schema` is already the supported operator seam. It creates a revision-bound
|
||||
runtime, checks collection compatibility, and runs the harness command
|
||||
`vector index-schema --json`
|
||||
(`backend/src/workspaces/preprocessing-service.ts`,
|
||||
[`workspace-preprocessing-cli.md`](../contracts/workspace-preprocessing-cli.md)).
|
||||
The full preprocessing operation performs DWH preparation, FK suggestion/review, schema indexing,
|
||||
and optional Evidence preprocessing as separate resumable stages
|
||||
(`backend/src/workspaces/preprocessing-service.ts`).
|
||||
Metadata-only publication should normally use the narrow `index-schema` operation after its
|
||||
workspace artifacts are valid, rather than coupling catalog CRUD to the full pipeline.
|
||||
|
||||
The harness indexer reads the active immutable physical schema and revision-specific annotations,
|
||||
constructs schema records, embeds only changed content, and writes them through the configured
|
||||
vector adapter
|
||||
(`harness/tht/cli/vector_cmd.py`). Its
|
||||
machine result carries the physical/annotation artifact digests, workspace revision, collection,
|
||||
and counts
|
||||
(`harness/tht/cli/vector_cmd.py`). This is
|
||||
the right place to retain publication evidence and audit linkage.
|
||||
|
||||
Preprocessing state is already revision- and binding-aware. A resumed job must match operation,
|
||||
workspace revision, descriptor/catalog blobs, runtime config and binding digests or it fails with
|
||||
`preprocessing_resume_mismatch`
|
||||
(`backend/src/workspaces/preprocessing-state.ts`).
|
||||
|
||||
There is an important operational gate: every preprocessing operation calls
|
||||
`assertSessionInventoryCompatible`; a non-finalized, non-archived session pinned to another
|
||||
revision blocks preprocessing
|
||||
(`backend/src/workspaces/preprocessing-service.ts`,
|
||||
`backend/src/workspaces/preprocessing-state.ts`).
|
||||
A catalog publication UX must expose this as a pending/blocking condition rather than report a
|
||||
generic indexing failure.
|
||||
|
||||
## 4. Qdrant identity, payload and collection contracts
|
||||
|
||||
The collection contract is fixed at the descriptor's dimensions/distance and eight keyword payload
|
||||
indexes: `content_hash`, `document_id`, `kind`, `record_key`, `record_kind`,
|
||||
`vector_generation`, `workspace_id`, and `workspace_revision`
|
||||
(`backend/src/workspaces/qdrant-collection.ts`).
|
||||
`self_heal` may create a missing compatible collection or indexes; `require_existing` only validates
|
||||
and refuses an incompatible collection
|
||||
(`backend/src/workspaces/qdrant-collection.ts`).
|
||||
The publication path must use this shared manager instead of inventing collection setup.
|
||||
|
||||
Schema payloads include both the workspace and workspace revision, record identity, semantic kind,
|
||||
content and content hash
|
||||
(`harness/tht/vectorstore/records.py`).
|
||||
Qdrant point IDs for schema and Evidence also include the revision, and upserts use the same
|
||||
revision in the payload
|
||||
(`harness/tht/adapters/vector/qdrant.py`).
|
||||
Reads always filter by `workspace_id`; schema and Evidence reads additionally filter by the bound
|
||||
`workspace_revision`, while memory and solved-question records intentionally remain
|
||||
workspace-wide
|
||||
(`harness/tht/adapters/vector/qdrant.py:125-145`).
|
||||
|
||||
This means an approved semantic change needs a new workspace revision if old sessions must retain
|
||||
their previous view. Directly overwriting points under the same Git revision would mutate the
|
||||
meaning of that supposedly immutable revision; adding an independent catalog-publication version
|
||||
would require changing the current runtime filter contract.
|
||||
|
||||
### Qdrant synchronization defect to resolve before catalog publication
|
||||
|
||||
The current incremental schema synchronizer compares canonical records by content hash and upserts
|
||||
changed records, but it has no deletion step
|
||||
(`harness/tht/cli/vector_cmd.py:77-99`). More
|
||||
importantly, `QdrantVectorStore.existing_hashes()` filters by workspace and record kind but does not
|
||||
apply `_revision_filter()`
|
||||
(`harness/tht/adapters/vector/qdrant.py:266-286`),
|
||||
even though point IDs and reads are revision-scoped. Therefore a same-key/same-content record from
|
||||
an older revision may be classified as unchanged and never written under the new revision. This is
|
||||
an implementation defect/risk inferred directly from the two code paths, and it should be fixed
|
||||
and regression-tested before the catalog relies on `index-schema` for multi-revision publication.
|
||||
|
||||
Deletion/GC must be stated per record family. Evidence cleanup is implemented: the corpus pipeline
|
||||
retains the configured number of published generations, protects active/job-referenced
|
||||
generations, and calls exact-generation deletion for evicted or compensated generations
|
||||
(`harness/tht/evidence/corpus/pipeline.py`,
|
||||
`harness/tht/adapters/vector/qdrant.py:350-390`). Schema cleanup is
|
||||
not implemented: `delete_kinds()` exists as a workspace-scoped adapter primitive, but the schema
|
||||
synchronizer never calls it, it is not revision-scoped, and there is no retention policy for old
|
||||
schema revisions. Publication therefore still needs exact current-revision deletion semantics and
|
||||
separate safe GC for unleased historical schema revisions.
|
||||
|
||||
## 5. Session pinning and why the SQL workflow can remain unchanged
|
||||
|
||||
Normal session creation acquires an immutable registry revision, passes its snapshot path,
|
||||
workspace ID and commit to `tht session new`, and only releases the retention lease after the
|
||||
manifest has been persisted
|
||||
(`backend/src/routes/sessions.ts`). The
|
||||
manifest stores `workspace_id` and `workspace_revision` next to database/schema identity
|
||||
(`harness/tht/session/store.py`). Resume and
|
||||
saved-SQL paths reopen that exact retained snapshot rather than the current installation default
|
||||
(`backend/src/routes/sessions.ts`,
|
||||
`backend/src/routes/sql.ts`).
|
||||
|
||||
The runtime renderer places the same workspace revision in `runtime_identity`, points the harness
|
||||
at the descriptor-owned Qdrant collection, and supplies the internal embedding service
|
||||
(`backend/src/workspaces/runtime-renderer.ts`).
|
||||
The vector adapter is constructed directly from that configuration, including the revision
|
||||
(`harness/tht/adapters/factory.py`).
|
||||
|
||||
At session bootstrap the backend invokes the existing `search pack` command
|
||||
(`backend/src/routes/sessions.ts`). That
|
||||
command queries schema records with the existing schema kinds, ranks tables and persists the
|
||||
candidate list
|
||||
(`harness/tht/cli/search_cmd.py`). The Pi
|
||||
extension reads the persisted retrieval pack through the CLI
|
||||
(`harness/.pi/extensions/tht-gate.js`),
|
||||
and F4 starts from those candidates while loading full table/column context through existing schema
|
||||
commands. Thus catalog publication can improve the inputs without changing phases, gate semantics,
|
||||
or persisted session artifacts.
|
||||
|
||||
## 6. DWH reuse across metadata-only revisions
|
||||
|
||||
DWH preparation uses immutable generations selected by an `ACTIVE` pointer
|
||||
([DWH contract](../contracts/tht-dwh.md)). The effective-configuration
|
||||
identity deliberately excludes `runtime_identity`, so a content-only Git revision does not force a
|
||||
database re-introspection
|
||||
([DWH contract](../contracts/tht-dwh.md)). This is the key enabling property for future metadata
|
||||
publication: a new Git revision can carry updated curated annotations and a future Core Schema
|
||||
Selection contract, reuse the compatible DWH-owned `physical.yaml`, and rebuild only the
|
||||
revision-scoped schema projection. Today only the curated annotations part of that statement exists.
|
||||
|
||||
## 7. Constraints for the Metadata Catalog design
|
||||
|
||||
The following remain proposed requirements for the deferred catalog-to-core design gate; they are
|
||||
not claims about current implementation:
|
||||
|
||||
1. **Separate full inventory from core projection.** PostgreSQL may hold the complete database
|
||||
catalog, drafts and AI-generated text. Only an explicit Core Schema Selection and approved
|
||||
semantic fields are exported to core artifacts/Qdrant.
|
||||
2. **Publish; do not live-link.** CRUD changes are not visible to the SQL workflow until an explicit,
|
||||
audited publication succeeds. A failed projection, Git activation or Qdrant index operation
|
||||
leaves the previous revision active.
|
||||
3. **Use a new Git revision as the publication identity.** This preserves current snapshot,
|
||||
retention, session resume and Qdrant filtering semantics. A separate mutable catalog revision
|
||||
cannot be safely introduced without changing runtime reads.
|
||||
4. **Respect artifact ownership.** Keep introspected physical facts in the immutable DWH generation;
|
||||
project the future Core Schema Selection through an explicit contract and approved semantic
|
||||
edits into `Annotations`. Keep Mermaid and long-form database documentation outside Qdrant
|
||||
unless a separate record kind and retrieval policy is designed.
|
||||
5. **Reuse the operator boundary.** Trigger `workspace index-schema`, observe its schema-versioned
|
||||
result and persist its artifact identities. Do not call Qdrant from browser CRUD handlers.
|
||||
6. **Keep runtime read-only.** The session/Pi process continues to read the pinned snapshot,
|
||||
retrieval pack and Qdrant projection. AI generation and catalog writes belong to the separate
|
||||
management control plane.
|
||||
7. **Surface publication gates.** UI status must distinguish Git activation, incompatible/missing
|
||||
collection, resumable-session revision conflict, embedding failure and completed publication.
|
||||
8. **Repair and test cross-revision schema synchronization first.** Scope `existing_hashes()` to
|
||||
the bound revision, delete records removed from the current revision's canonical schema, and
|
||||
define safe schema-revision GC. Reuse rather than duplicate the already implemented Evidence
|
||||
generation GC.
|
||||
9. **Close the annotation display gap without changing the workflow.** Make `schema columns` read
|
||||
the same merged descriptions used by M-Schema/vector rendering, so the current F4 widget sees
|
||||
the approved catalog text.
|
||||
|
||||
## Proposed decision summary for the Wayfinder map
|
||||
|
||||
- Keep the Metadata Catalog as a separate management subsystem and source of editable metadata.
|
||||
- Keep Qdrant derived and revision-scoped; it is not the catalog database or source of truth.
|
||||
- Publish through immutable workspace revisions plus the existing preprocessing service.
|
||||
- Preserve the current NL→SQL workflow, Pi extension, phase model and session artifacts.
|
||||
- Add a new, explicit Core Schema Selection contract because no table/column selection exists in
|
||||
the current descriptor.
|
||||
- Treat direct same-revision Qdrant writes, implicit CRUD publication, and bypassing the Git
|
||||
snapshot boundary as rejected integration paths.
|
||||
|
||||
This summary remains design input. The authoritative current state is that catalog-to-core
|
||||
integration and Sensitive Data Policy enforcement in schema-linking are deferred in
|
||||
`PROJECT_STATE.md:160-171`.
|
||||
@@ -114,7 +114,7 @@ La review dei join durante una sessione è distinta dalla curatela globale: il r
|
||||
| Retrieval | Le relationship entrano nel render M-Schema ma non nei record vettoriali | Va deciso se e come influenzano selezione tabelle, ranking e descrizioni, oltre al rendering finale |
|
||||
| Drift | Sync fisica è autoritativa; annotazioni sono una revisione separata | Servono semantiche per endpoint rinominati/eliminati, candidate stale, orphan e riapprovazione |
|
||||
|
||||
Le analisi già presenti nel repository trattano l'integrazione catalogo→core, la selezione pubblicabile e la riparazione degli indici come questioni ancora aperte; le loro proposte non sono decisioni implementate (`docs/research/2026-08-23-thothii-metadata-publication-qdrant-seams.md:20-43`; `docs/research/2026-08-23-thothii-metadata-publication-qdrant-seams.md:239-301`). Anche il piano di migrazione rinvia il lifecycle/admin delle relationship logiche (`docs/plans/2026-08-26-metadata-catalog-from-thothai.md:681-691`).
|
||||
Nota storica: questa analisi precede il passaggio PostgreSQL catalog-to-core. Per il contratto implementato usare [architettura corrente](../architecture/overview.md) e ADR 0016; le vecchie ipotesi di pubblicazione non sono istruzioni operative.
|
||||
|
||||
## Direzione confermata nel grill
|
||||
|
||||
|
||||
@@ -1,122 +0,0 @@
|
||||
# Google Antigravity e Gemini 3.8 Flash: convenienza costo/qualità
|
||||
|
||||
Verifica effettuata il **7 settembre 2026**, privilegiando documentazione e annunci
|
||||
ufficiali Google. Le prove indipendenti su Gemini 3.8 Flash sono ancora limitate perché il
|
||||
modello è stato pubblicato il 2 settembre 2026.
|
||||
|
||||
## Giudizio sintetico
|
||||
|
||||
- **Registrazione gratuita: decisamente conveniente.** Il piano Individual da $0 include
|
||||
Gemini 3.8 Flash, l'ultima versione Flash, oltre alla CLI e alle funzioni principali di
|
||||
Antigravity. È difficile ottenere un rapporto costo/qualità migliore di un accesso gratuito
|
||||
a un modello di questa fascia.
|
||||
- **Google AI Pro da circa $20/mese: probabilmente conveniente per uso regolare**, ma solo dopo
|
||||
aver misurato il consumo sul piano gratuito. Google non pubblica un numero fisso di prompt o
|
||||
token inclusi, quindi non è possibile calcolare un break-even affidabile contro l'API.
|
||||
- **Ultra da $100 o $200: non lo comprerei per il solo Gemini Flash** senza aver già dimostrato
|
||||
di saturare Pro. Il piano da $100 offre 5 volte la quota Pro; quello da $200 ne offre 20 volte.
|
||||
- Per il server dietro CyberArk, Antigravity ha un vantaggio concreto: la CLI ufficiale `agy`
|
||||
funziona direttamente in Linux e prevede esplicitamente un flusso OAuth remoto tramite URL e
|
||||
codice, senza tunnel né port forwarding.
|
||||
|
||||
## Accesso e prezzi
|
||||
|
||||
La [pagina ufficiale dei piani Antigravity](https://www.antigravity.google/docs/plans/) e la
|
||||
[tabella dei modelli](https://www.antigravity.google/docs/models/) indicano che Gemini 3.8 Flash
|
||||
è disponibile su Individual gratuito, AI Plus, AI Pro, AI Ultra ed Enterprise. Il piano gratuito
|
||||
include anche completamenti Tab illimitati e tutte le funzioni del prodotto, inclusa la CLI, ma
|
||||
ha un limite settimanale di base.
|
||||
|
||||
Google AI Pro costa normalmente **$19,99/mese** nella pagina internazionale di
|
||||
[Google One](https://one.google.com/about/plans) e offre quote Antigravity superiori, con rinnovo
|
||||
ogni cinque ore finché non viene raggiunto il limite settimanale. Google AI Ultra è offerto a
|
||||
[$100/mese con quota 5× Pro oppure $200/mese con quota 20× Pro](https://blog.google/products-and-platforms/products/google-one/google-ai-subscriptions/).
|
||||
|
||||
Il problema è la misurabilità: Google dichiara che i limiti dipendono dalla capacità disponibile
|
||||
e dalla quantità di lavoro compiuta dall'agente, possono cambiare e non corrispondono a un numero
|
||||
pubblico fisso di richieste o token. Pro e Ultra possono acquistare crediti per continuare oltre
|
||||
la quota base, con consumo ai prezzi della piattaforma Gemini.
|
||||
|
||||
Usando direttamente la Gemini API, Gemini 3.8 Flash costa fino al 31 dicembre 2026:
|
||||
|
||||
- **$0,75 per milione di token di input**;
|
||||
- **$3,75 per milione di token di output**, inclusi i token di ragionamento;
|
||||
- la metà in modalità Batch o Flex.
|
||||
|
||||
Dal 1º gennaio 2027 questi prezzi raddoppieranno a $1,50/$7,50. Esiste anche un free tier API,
|
||||
con limiti, nel quale input e output sono gratuiti ma i contenuti possono essere usati per
|
||||
migliorare i prodotti Google. Fonte: [pricing ufficiale Gemini API](https://ai.google.dev/gemini-api/docs/pricing).
|
||||
|
||||
## Qualità del modello
|
||||
|
||||
[Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash) è GA, offre un
|
||||
contesto da 1.048.576 token, output fino a 65.536 token, livelli di ragionamento low/medium/high e
|
||||
strumenti per code execution, computer use, file search, function calling e search grounding.
|
||||
|
||||
I risultati pubblicati da Google lo collocano molto vicino ai modelli flagship su alcuni test di
|
||||
coding, ma non su tutti:
|
||||
|
||||
| Benchmark | Gemini 3.8 Flash | Claude Opus 5 | GPT-5.6 Sol | Lettura onesta |
|
||||
|---|---:|---:|---:|---|
|
||||
| DeepSWE v1.1 | 73,7% | 74,0% | 72,7% | Prestazione quasi flagship sul software engineering end-to-end |
|
||||
| Terminal-Bench 2.1 | 89,4% | 89,1% | 88,8% | Eccellente nel terminale sul benchmark più maturo |
|
||||
| Terminal-Bench 4.0 | 19,1% | 51,8% | 37,3% | Forte calo sul test nuovo e più difficile: non è universalmente al livello dei flagship |
|
||||
|
||||
La [metodologia ufficiale Google](https://deepmind.google/models/evals-methodology/gemini-3-8-flash/)
|
||||
precisa che diversi punteggi Gemini sono calcolati internamente e che i concorrenti provengono
|
||||
anche da risultati auto-dichiarati; inoltre DeepSWE usa mini-swe, mentre Terminal-Bench usa un
|
||||
harness diverso. I numeri vanno quindi letti come indicazione, non come garanzia. Una
|
||||
[ricostruzione della tabella e dei confronti](https://www.vellum.ai/blog/gemini-3-8-flash-benchmarks-explained)
|
||||
mostra lo stesso andamento: molto competitivo sui compiti di coding già ben rappresentati, più
|
||||
debole su alcune prove nuove e aperte.
|
||||
|
||||
La conclusione qualitativa è: **ottimo implementatore quotidiano e subagente veloce**, con qualità
|
||||
da modello molto più costoso in diversi task; per architettura difficile, debugging ambiguo o
|
||||
lavori ad alto rischio è ancora sensato affiancargli un modello più forte come pianificatore o
|
||||
revisore.
|
||||
|
||||
## Perché Antigravity è particolarmente adatto al server
|
||||
|
||||
La [CLI ufficiale Antigravity](https://antigravity.google/docs/cli/overview/) è una TUI interattiva
|
||||
con editing multi-file, cronologia, tool calling, sandbox e subagenti. La
|
||||
[guida d'installazione e autenticazione](https://antigravity.google/docs/cli/install/) conferma:
|
||||
|
||||
- esecuzione nativa su Linux, macOS e Windows;
|
||||
- binario `agy` installato in `~/.local/bin` su Linux/macOS;
|
||||
- quando rileva SSH, stampa un URL da aprire sul Mac e richiede di incollare nel terminale il
|
||||
codice ottenuto;
|
||||
- nessuna porta in ascolto e nessun port forwarding sono necessari per questo login.
|
||||
|
||||
Questo risolve meglio di ZCode il vincolo CyberArk, purché il server possa effettuare connessioni
|
||||
HTTPS in uscita e sia consentita l'installazione del binario.
|
||||
|
||||
Per consumare la quota della registrazione Antigravity bisogna usare il client ufficiale. I
|
||||
[termini Antigravity](https://antigravity.google/terms) vietano di riutilizzare il login/OAuth con
|
||||
Pi, OMP, Claude Code, OpenCode o altri client. Con questi harness si può invece usare una normale
|
||||
chiave Gemini API, pagando o consumando la quota API separata.
|
||||
|
||||
## Privacy e codice aziendale
|
||||
|
||||
Con un account personale Google registra le interazioni e può usarle per valutare e migliorare
|
||||
prodotti e modelli; l'utente può disattivare l'uso dalle impostazioni. I termini Enterprise sono
|
||||
diversi e la documentazione dichiara che codice, prompt e trascrizioni delle organizzazioni non
|
||||
sono usati per addestrare i modelli Google. Fonti:
|
||||
[termini Antigravity](https://antigravity.google/terms) e
|
||||
[integrazioni Enterprise](https://antigravity.google/docs/ide/extensions/).
|
||||
|
||||
Su un server aziendale protetto da CyberArk userei quindi una registrazione personale solo dopo
|
||||
aver verificato la policy interna; in caso contrario sceglierei l'accesso Antigravity Enterprise
|
||||
tramite il progetto Google Cloud dell'organizzazione.
|
||||
|
||||
## Raccomandazione finale
|
||||
|
||||
1. Creare l'account gratuito e usare `agy` sul server per una settimana con task reali.
|
||||
2. Tenere disabilitato l'uso automatico dei crediti extra e osservare i due indicatori di quota.
|
||||
3. Passare a Pro soltanto se il limite gratuito interferisce con il lavoro.
|
||||
4. Non acquistare Ultra finché Pro non viene saturato con regolarità.
|
||||
5. Usare Gemini 3.8 Flash come modello principale per esplorazione, implementazione e test; per le
|
||||
decisioni più difficili, mantenere Codex/Sol/Opus o un altro modello forte come revisore.
|
||||
|
||||
In breve: **sì, oggi Antigravity gratuito o Pro offre uno dei migliori rapporti costo/qualità per
|
||||
Gemini 3.8 Flash**, e nel caso specifico la CLI ufficiale senza tunnel aumenta ulteriormente il
|
||||
valore. Il limite commerciale da accettare è la quota non numerica e modificabile da Google.
|
||||
@@ -1,154 +0,0 @@
|
||||
# DeepSeek Harness su un server raggiunto tramite CyberArk
|
||||
|
||||
Data della verifica: 7 settembre 2026.
|
||||
|
||||
## Risposta breve
|
||||
|
||||
Sì. Il progetto che ha attirato molta attenzione è **DeepSeek Harness**, comando
|
||||
`dsh`, pubblicato da DeepSeek nel repository ufficiale
|
||||
[`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness).
|
||||
Può lavorare direttamente sul server senza SSH port forwarding usando il profilo
|
||||
ufficiale **headless**:
|
||||
|
||||
```sh
|
||||
export DEEPSEEK_API_KEY='...'
|
||||
npx @deepseek-ai/dsh --profile headless \
|
||||
"Esamina questo repository e correggi i test che falliscono"
|
||||
```
|
||||
|
||||
Questo profilo esegue un incarico, stampa la risposta e termina. Non avvia GUI,
|
||||
browser o server HTTP e, soprattutto, **non apre alcuna porta**. Lo documentano sia
|
||||
il [README del profilo headless](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/README.md)
|
||||
sia il [riferimento della CLI](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md).
|
||||
Pertanto il port forwarding non serve: basta la shell che CyberArk già consente e
|
||||
connettività HTTPS in uscita.
|
||||
|
||||
La limitazione importante è che non si tratta, per ora, di un'interfaccia terminale
|
||||
interattiva come Pi, OMP, Claude Code o Codex: il profilo ufficiale headless accetta
|
||||
**un solo task per invocazione e non permette follow-up interattivi**.
|
||||
|
||||
## Che cos'è, e cosa non è
|
||||
|
||||
DeepSeek lo presenta come un harness open source in *developer preview*, basato su
|
||||
un'architettura in cui modelli, strumenti, skill, sessioni, sandbox, storage,
|
||||
subagenti e UI sono plugin componibili. La pagina ufficiale descrive inoltre
|
||||
modalità Standard, Code, Minimal e Creator e la registrazione append-only delle
|
||||
esecuzioni. Non è semplicemente il modello DeepSeek e non è uno dei numerosi wrapper
|
||||
creati dalla comunità. Fonti: [pagina ufficiale DeepSeek Harness](https://www.deepseek.com/harness/en/)
|
||||
e [README ufficiale](https://github.com/deepseek-ai/deepseek-harness#readme).
|
||||
|
||||
L'identità del pacchetto è verificabile anche nel
|
||||
[`package.json` della CLI](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/package.json):
|
||||
il pacchetto pubblico è `@deepseek-ai/dsh` e installa l'eseguibile `dsh`.
|
||||
Il [record ufficiale del repository](https://api.github.com/repos/deepseek-ai/deepseek-harness)
|
||||
ne data la creazione al 13 agosto 2026; alla data di questa verifica la release
|
||||
più recente è la prerelease
|
||||
[`dsh-v0.1.3-alpha.2`](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.2),
|
||||
pubblicata il 7 settembre 2026. Questo conferma quanto il progetto sia giovane e
|
||||
rafforza l'avvertenza sulla stabilità delle interfacce.
|
||||
|
||||
## Le tre modalità rilevanti nel tuo scenario
|
||||
|
||||
| Modalità | Porta/tunnel | Interazione | Utilità con CyberArk |
|
||||
|---|---:|---|---|
|
||||
| `dsh --profile headless "task"` | Nessuna | One-shot, non interattiva | **Sì, è la soluzione semplice** |
|
||||
| `dsh web` | HTTP locale su `127.0.0.1:3080` | Web interattiva | No dal Mac senza forwarding, reverse proxy autorizzato o browser sul server |
|
||||
| `dsh --profile acp` | Nessuna porta; JSON-RPC su stdin/stdout | Persistente, pilotata da un client ACP | Possibile, ma l'integrazione attraverso CyberArk va provata |
|
||||
|
||||
La Web UI ufficiale ascolta per default su `127.0.0.1:3080`; il README afferma
|
||||
esplicitamente che, durante un lancio SSH, il forwarding è responsabilità del client
|
||||
SSH o dell'editor. È quindi inadatta al vincolo descritto, a meno di cambiare
|
||||
l'architettura di accesso con l'approvazione dell'amministrazione
|
||||
([README ufficiale](https://github.com/deepseek-ai/deepseek-harness#run)).
|
||||
|
||||
Il profilo ACP ufficiale è invece un server di automazione persistente su
|
||||
**JSON-RPC stdio**, senza UI. Un client ACP avvia `dsh --profile acp`, crea una
|
||||
sessione indicando una directory di lavoro assoluta e scambia richieste e risposte
|
||||
su standard input/output
|
||||
([README ACP ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/acp-app/README.md)).
|
||||
|
||||
Da ciò segue una possibilità tecnica: un client locale potrebbe usare come comando
|
||||
qualcosa di equivalente a `ssh <server> dsh --profile acp`, trasportando lo stdio
|
||||
senza alcun port forwarding. Questa è però un'**inferenza architetturale**, non una
|
||||
configurazione dichiarata compatibile con CyberArk da DeepSeek. Banner di login,
|
||||
MFA interattivo, testo aggiunto su stdout, divieto di `ssh host command`, timeout o
|
||||
riscrittura dei flussi da parte del proxy CyberArk possono corrompere JSON-RPC o
|
||||
impedire del tutto l'avvio. Se CyberArk offre soltanto una console web/interattiva,
|
||||
ACP non collega automaticamente Zed sul Mac al processo remoto.
|
||||
|
||||
## Requisiti di rete e di sistema
|
||||
|
||||
- Il repository richiede Node.js `^22.19.0` oppure `>=24.0.0`, come specificato
|
||||
nel [`package.json` ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/package.json).
|
||||
- Il primo `npx` deve poter scaricare `@deepseek-ai/dsh` dal registry npm. In un
|
||||
ambiente bloccato occorre un mirror aziendale o un'installazione preventiva
|
||||
autorizzata.
|
||||
- Per usare il provider predefinito occorrono `DEEPSEEK_API_KEY` e traffico HTTPS
|
||||
in uscita verso `https://api.deepseek.com`. `DEEPSEEK_BASE_URL` può sostituire
|
||||
l'endpoint, per esempio con un proxy OpenAI-compatible
|
||||
([adapter DeepSeek ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-deepseek/README.md)).
|
||||
- Se la rete aziendale impone un proxy HTTP, il riferimento della CLI indica
|
||||
`NODE_USE_ENV_PROXY=1` affinché una versione Node compatibile rispetti
|
||||
`HTTP_PROXY` e `HTTPS_PROXY`
|
||||
([riferimento della CLI, sezione Source execution](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md#source-execution)).
|
||||
- Le operazioni richieste dall'agente possono necessitare altri host in uscita
|
||||
(`git`, registry dei pacchetti, documentazione). Non sono necessari per il
|
||||
trasporto DSH in sé, ma possono esserlo per il task affidato.
|
||||
|
||||
In altre parole, serve **HTTPS outbound**, non una connessione in ingresso verso il
|
||||
server e non un tunnel dal Mac.
|
||||
|
||||
## Limiti pratici specifici di CyberArk
|
||||
|
||||
1. **Accesso alla shell:** se CyberArk consente di aprire una normale sessione shell
|
||||
e di eseguire Node, `headless` funziona concettualmente come qualunque altro
|
||||
comando. Se applica allowlist ai binari, servirà l'autorizzazione per `node`,
|
||||
`npx`/`dsh` e per gli strumenti che l'agente vuole eseguire.
|
||||
2. **Egress:** firewall e proxy devono consentire almeno l'endpoint del modello;
|
||||
CyberArk non sostituisce questa autorizzazione di rete.
|
||||
3. **Durata della sessione:** un timeout o la chiusura della sessione privilegiata
|
||||
può terminare il task. `headless` non lascia un demone dietro di sé, ma incarichi
|
||||
lunghi vanno confrontati con i limiti della sessione CyberArk.
|
||||
4. **Credenziali e registrazione:** evitare di digitare o stampare la chiave API in
|
||||
una sessione registrata. Conviene usare il meccanismo aziendale approvato per
|
||||
iniettare il secret e verificare cosa CyberArk registra.
|
||||
5. **Approvals:** l'headless ufficiale non ha un interlocutore umano integrato. Le
|
||||
richieste di escalation senza un *answerer* vengono negate in modo fail-closed;
|
||||
le normali scritture consentite nella workspace restano possibili
|
||||
([contratto delle approvazioni](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-approval/README.md)).
|
||||
6. **Sicurezza:** DeepSeek dichiara il progetto non sottoposto a security audit e
|
||||
non pronto per produzione. Può eseguire codice generato dal modello e accedere
|
||||
a file, processi, rete e credenziali disponibili al processo. Il progetto stesso
|
||||
raccomanda privilegi minimi e un ambiente dedicato o usa-e-getta
|
||||
([Safety notice ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md)).
|
||||
|
||||
Un dettaglio importante in un server aziendale: la sandbox corrente descritta da
|
||||
DeepSeek governa gli effetti sul filesystem, mentre rete e visibilità dei processi
|
||||
sono fuori dal suo vocabolario di enforcement. Non considerarla quindi un sostituto
|
||||
di firewall, container, account dedicato e policy CyberArk
|
||||
([documentazione sandbox ufficiale](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/sandbox.md)).
|
||||
|
||||
## TUI interattiva: stato reale
|
||||
|
||||
Il prodotto ufficiale offre oggi Web UI, headless one-shot e interfacce di
|
||||
automazione SDK/ACP. Una TUI a schermo intero chiamata `dsh-tui` è stata presentata
|
||||
nell'area community del repository, ma il pacchetto e il repository appartengono a
|
||||
terzi, non a DeepSeek
|
||||
([discussione nella community DSH](https://github.com/deepseek-ai/deepseek-harness/discussions/3715)).
|
||||
Non va confusa con la CLI ufficiale e, dato che DSH avverte di possibili cambiamenti
|
||||
incompatibili durante la developer preview, non la considererei la prima scelta su
|
||||
un server aziendale protetto.
|
||||
|
||||
## Giudizio
|
||||
|
||||
Per il tuo vincolo concreto la risposta è **sì, ma in modalità one-shot**:
|
||||
`dsh --profile headless` è utilizzabile dalla normale shell CyberArk, non apre porte
|
||||
e non richiede tunnel. È una soluzione tecnicamente più adatta della Web UI, ma
|
||||
meno comoda di Pi/OMP o Codex CLI per un dialogo iterativo.
|
||||
|
||||
La proverei inizialmente su una copia non sensibile del repository, con
|
||||
`workspace-write`, egress ristretto e secret iniettato secondo le regole aziendali.
|
||||
Se vuoi un'esperienza persistente dal Mac, ACP su stdio merita un piccolo test di
|
||||
compatibilità con il gateway CyberArk; non lo darei per funzionante finché non si
|
||||
verifica che il gateway permetta un comando remoto non interattivo e mantenga
|
||||
stdin/stdout completamente puliti.
|
||||
@@ -1,127 +0,0 @@
|
||||
# OMP con GPT-5.6 Sol, Codex ufficiale e ZCode CLI
|
||||
|
||||
_Verifica effettuata il 7 settembre 2026 su documentazione e codice/fonti primarie correnti._
|
||||
|
||||
## Risposta breve
|
||||
|
||||
Se l'obiettivo è usare **GPT-5.6 Sol attraverso la quota inclusa nel piano ChatGPT/Codex**, la
|
||||
scelta consigliata è **Codex ufficiale**: CLI per il lavoro da terminale, app desktop per più task,
|
||||
worktree e revisione visuale. OMP è un harness molto capace e può essere preferibile per ACP/Zed,
|
||||
multi-provider, LSP/DAP e orchestrazione dei subagenti, ma il suo accesso “OpenAI Codex OAuth” non
|
||||
è una superficie che OpenAI documenta ufficialmente come client supportato.
|
||||
|
||||
Se invece OMP usa una **chiave API OpenAI**, l'integrazione è tecnicamente normale e GPT-5.6 Sol è
|
||||
disponibile tramite Responses API con function calling, structured outputs e diversi tool. In quel
|
||||
caso, però, il consumo è fatturato come API e non attinge alla quota inclusa nel piano ChatGPT.
|
||||
|
||||
Per **ZCode di Z.ai**, la documentazione ufficiale corrente presenta un'app desktop/ADE, non una
|
||||
CLI pubblica autonoma. Esiste `zcode-app-cli`, ma è un progetto comunitario che si dichiara non
|
||||
ufficiale ed estrae il runtime distribuito con l'app. Non esiste una garanzia ufficiale che riceva
|
||||
un presunto bonus di quota del 50%; la documentazione corrente non promette neppure un diritto
|
||||
fisso “150%” per tutti gli utenti ZCode.
|
||||
|
||||
## 1. OMP + GPT-5.6 Sol oppure Codex?
|
||||
|
||||
### Il modello è solo una parte del risultato
|
||||
|
||||
Usare lo stesso modello non rende equivalenti due agenti. L'harness decide prompt di sistema,
|
||||
selezione e schema dei tool, raccolta del contesto, compaction, gestione degli errori, permessi,
|
||||
parallelismo e verifica. Non risultano benchmark first-party che confrontino direttamente
|
||||
GPT-5.6 Sol dentro OMP contro lo stesso modello dentro Codex: un vincitore assoluto non è quindi
|
||||
dimostrabile.
|
||||
|
||||
GPT-5.6 Sol è il modello flagship general-purpose della famiglia 5.6 e supporta Responses API,
|
||||
function calling, structured outputs, hosted shell, apply patch, skills, MCP e tool search.
|
||||
[Scheda ufficiale GPT-5.6 Sol](https://developers.openai.com/api/docs/models/gpt-5.6-sol).
|
||||
|
||||
### Accesso tramite abbonamento
|
||||
|
||||
OMP dichiara un provider **OpenAI Codex OAuth** e consente il login dal proprio harness.
|
||||
[README OMP](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/README.md).
|
||||
|
||||
La documentazione OpenAI, però, indica il login ChatGPT per l'accesso in abbonamento soltanto per
|
||||
l'app desktop ChatGPT/Codex, Codex CLI e l'estensione IDE. Non include OMP tra i client supportati.
|
||||
Questo non prova che OMP non funzioni, ma significa che compatibilità, continuità dell'accesso e
|
||||
interpretazione della quota non sono garantite da OpenAI per quel percorso.
|
||||
[Autenticazione ufficiale Codex](https://learn.chatgpt.com/docs/auth).
|
||||
|
||||
Con una chiave API la situazione è diversa: l'accesso al modello è ufficiale, ma è fatturato ai
|
||||
prezzi API. OpenAI specifica inoltre che l'autenticazione API usa il pricing API invece dei crediti
|
||||
inclusi nel piano ChatGPT.
|
||||
[Pricing Codex](https://learn.chatgpt.com/docs/pricing),
|
||||
[pricing del modello](https://developers.openai.com/api/docs/models/gpt-5.6-sol).
|
||||
|
||||
### Confronto operativo
|
||||
|
||||
| Priorità | Scelta migliore | Motivo |
|
||||
|---|---|---|
|
||||
| GPT-5.6 Sol con quota ChatGPT e supporto prevedibile | Codex ufficiale | Login, quota e aggiornamenti sono first-party |
|
||||
| Esperienza terminale, scripting e CI | Codex CLI | Loop locale, `codex exec`, review e handoff cloud |
|
||||
| Task paralleli, worktree e review visuale | App desktop Codex | Gestione visuale dei task e isolamento mediante Git worktree |
|
||||
| ACP/Zed, molti provider, LSP/DAP e Agent Hub | OMP | Harness più estensibile e ricco di strumenti |
|
||||
| OMP con stabilità contrattuale dell'accesso | OMP + API key | API ufficiale, ma costo separato dal piano ChatGPT |
|
||||
|
||||
La CLI ufficiale è consigliata per terminale, automazione e CI.
|
||||
[Codex CLI](https://learn.chatgpt.com/docs/codex/cli). L'app desktop è più comoda per task
|
||||
concorrenti isolati, diff visuali e passaggio fra checkout locale e worktree.
|
||||
[Worktree Codex](https://learn.chatgpt.com/docs/environments/git-worktrees).
|
||||
|
||||
CLI e app non danno due quote separate: quando si accede con ChatGPT, fanno parte dello stesso
|
||||
ecosistema Codex/ChatGPT e consumano la stessa quota del piano. Il consumo concreto dipende da
|
||||
modello, lunghezza del contesto e complessità del task.
|
||||
[Pricing e limiti](https://learn.chatgpt.com/docs/pricing).
|
||||
|
||||
### Giudizio
|
||||
|
||||
Per un flusso principale basato su GPT-5.6 Sol sceglierei **Codex CLI**; affiancherei l'app quando
|
||||
servono task paralleli, worktree e review visuale. Sceglierei OMP come harness principale soltanto
|
||||
se le sue capacità specifiche — soprattutto Zed/ACP, routing multi-provider o Agent Hub — valgono
|
||||
più del supporto first-party. Se OMP deve essere affidabile nel tempo, userei una API key anziché
|
||||
fondare il workflow sul login OAuth non documentato da OpenAI per client terzi.
|
||||
|
||||
## 2. Il “150%” di Codex non è quota aggiuntiva
|
||||
|
||||
Nella documentazione OpenAI, **1,5× indica la velocità del Fast mode**, non un aumento della quota.
|
||||
Con GPT-5.6, Fast mode consuma crediti a **2,5×** il tasso Standard. È disponibile nei client
|
||||
Codex ufficiali quando si accede con ChatGPT.
|
||||
[Fast mode](https://learn.chatgpt.com/docs/agent-configuration/speed).
|
||||
|
||||
## 3. Esiste una CLI ufficiale ZCode?
|
||||
|
||||
La guida ufficiale ZCode offre download desktop per macOS, Windows e Linux e descrive ZCode come
|
||||
ADE con terminale integrato. Non documenta un comando autonomo ufficiale equivalente a `codex`.
|
||||
La presenza di directory chiamate `~/.zcode/cli/` riguarda il runtime/config interno e non equivale
|
||||
alla pubblicazione di una CLI supportata.
|
||||
[Installazione ZCode](https://zcode.z.ai/en/docs/install),
|
||||
[FAQ ufficiale](https://zcode.z.ai/en/docs/qa).
|
||||
|
||||
Esiste il progetto comunitario
|
||||
[`zcode-app-cli`](https://github.com/kingsword09/zcode-cli), installabile con npm. Il progetto si
|
||||
definisce esplicitamente non affiliato né approvato da Z.ai e dichiara di estrarre il runtime
|
||||
dall'app desktop. Va quindi considerato non ufficiale e soggetto a possibili rotture e problemi di
|
||||
compatibilità o licenza.
|
||||
|
||||
### Ha il 150% della quota?
|
||||
|
||||
Non c'è una conferma ufficiale corrente. Le pagine ZCode attuali descrivono quote Coding Plan su
|
||||
finestre di cinque ore e settimanali, quota MCP mensile, crediti e reset card promozionali/dinamiche;
|
||||
non dichiarano un moltiplicatore fisso 150% applicabile alla CLI.
|
||||
[Statistiche e quota ZCode](https://zcode.z.ai/en/docs/usage-stats),
|
||||
[connessione al Coding Plan](https://zcode.z.ai/en/docs/configuration).
|
||||
|
||||
Alcuni benefici sono esplicitamente legati all'app e al login ZCode: per esempio le reset card
|
||||
richiedono di essere connessi a ZCode, mentre gli idle-time task gratuiti sono una funzione
|
||||
dell'app in rollout. Questo non autorizza a concludere che un client comunitario riceva gli stessi
|
||||
benefici.
|
||||
[ZCode Usage Stats](https://zcode.z.ai/en/docs/usage-stats),
|
||||
[ZCode overview](https://zcode.z.ai/en/docs/welcome).
|
||||
|
||||
Inoltre, i termini del GLM Coding Plan avvertono che l'uso tramite strumenti non autorizzati o non
|
||||
supportati può comportare restrizioni di alcuni benefici. Di conseguenza non userei una CLI
|
||||
comunitaria con l'obiettivo specifico di ottenere quota extra.
|
||||
[Termini del GLM Coding Plan](https://docs.z.ai/legal-agreement/subscription-terms).
|
||||
|
||||
La scelta prudente è usare l'app ZCode ufficiale — incluso il suo terminale integrato o Remote
|
||||
Development — e considerare valido soltanto il saldo mostrato in tempo reale nell'app. Se Z.ai
|
||||
pubblicherà una CLI ufficiale o una regola “+50%”, servirà una dichiarazione esplicita applicabile
|
||||
alla versione e al piano usati.
|
||||
@@ -1,148 +0,0 @@
|
||||
# Pi + `pi-config` di Amos vs Oh My Pi
|
||||
|
||||
_Ricerca aggiornata al 7 settembre 2026. Fonti: esclusivamente repository, documentazione, sorgenti, issue tracker e release ufficiali dei progetti._
|
||||
|
||||
## Risposta breve
|
||||
|
||||
**Per la maggior parte degli sviluppatori che vuole un agente completo e pronto all'uso, sceglierei Oh My Pi (OMP), ma non con le impostazioni di sicurezza predefinite.** OMP integra provider, routing per ruolo, LSP/DAP, subagent, web, browser, sessioni, memoria, marketplace e una UX terminale molto più ampia. È un prodotto coerente, installabile e aggiornabile come tale.
|
||||
|
||||
**Sceglierei invece Pi con pezzi selezionati di `pi-config` se volessi un nucleo piccolo, leggibile e fortemente personalizzabile**, accettando di assemblare, verificare e mantenere personalmente ogni componente. Il vantaggio non è avere più funzioni: è sapere con precisione quali funzioni si stanno aggiungendo.
|
||||
|
||||
La prima distinzione è fondamentale:
|
||||
|
||||
- [`amosblomqvist/pi-config`](https://github.com/amosblomqvist/pi-config) **non è una distribuzione alternativa di Pi**. È la configurazione personale di Amos Blomqvist: una raccolta di estensioni e skill da copiare selettivamente sopra il [Pi ufficiale](https://github.com/earendil-works/pi). Il README invita esplicitamente a non installarla come un unico pacchetto e a non clonarla sopra la propria configurazione.
|
||||
- Per “Oh My Pi” qui si intende [`can1357/oh-my-pi`](https://github.com/can1357/oh-my-pi), il fork integrato di Pi che si presenta come agente “batteries included”. Non è un semplice tema o dotfile pack.
|
||||
|
||||
Di conseguenza il confronto corretto è **Pi ufficiale + componenti scelti da `pi-config` e dai repository companion** contro **OMP come fork/prodotto integrato**.
|
||||
|
||||
## Confronto spalla a spalla
|
||||
|
||||
| Area | Pi + `pi-config` | Oh My Pi | Valutazione |
|
||||
|---|---|---|---|
|
||||
| Installazione | Prima si installa [Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md), poi si copiano singole estensioni/skill in `~/.pi/agent/`; alcuni componenti richiedono `npm install`, Chromium, Python o tool di sistema. Il [README di `pi-config`](https://github.com/amosblomqvist/pi-config#installation) raccomanda la selezione manuale. | Installer shell/PowerShell, Homebrew, Bun, Nix e `mise`, più binari multipiattaforma nelle [release](https://github.com/can1357/oh-my-pi/releases). | **OMP**: onboarding e aggiornamento più coerenti. |
|
||||
| Filosofia | Pi è un harness terminale minimale, esteso tramite TypeScript, skill, prompt template, temi e pacchetti; evita intenzionalmente alcune funzionalità integrate, inclusi subagent e plan mode, per lasciarle alle estensioni ([README Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md)). `pi-config` porta questa filosofia all'estremo: si prendono solo i pezzi voluti. | Fork “batteries included”: molte capacità sono native o integrate e configurabili da una superficie comune ([README OMP](https://github.com/can1357/oh-my-pi)). | **Dipende**: controllo e semplicità a Pi; completezza a OMP. |
|
||||
| Provider e modelli | `pi-config` non aggiunge provider. Eredita da Pi login per Anthropic/OpenAI/Copilot, numerosi provider API, servizi cloud, OpenRouter e modelli locali/custom ([provider Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#providers-and-models)). | Dichiara oltre 60 provider e modelli locali/remoti; assegna modelli distinti ai ruoli `default`, `smol`, `slow`, `plan`, `commit`, `vision`, `task`, `advisor` e `tiny`, con fallback e credenziali multiple ([model routing OMP](https://github.com/can1357/oh-my-pi#sixty-plus-providers-a-thousand-models-one-model-away)). | **OMP** per ampiezza e routing; Pi resta già provider-agnostic. |
|
||||
| Prompt e istruzioni | Pi supporta `AGENTS.md`, `SYSTEM.md`, `APPEND_SYSTEM.md` e prompt template. `prompt-snippets` aggiunge piccoli frammenti attivabili per singolo messaggio, poi azzerati ([sorgente/README](https://github.com/amosblomqvist/pi-config/tree/main/extensions/prompt-snippets)). | Stessi concetti di personalizzazione del prompt, con override globali/progetto/modello ([documentazione](https://github.com/can1357/oh-my-pi/blob/main/docs/system-prompt-customization.md)); aggiunge ruoli modello, advisor e agent personalizzati. | **OMP** per orchestrazione; **pi-config** ha la migliore micro-UX per regole effimere per messaggio. |
|
||||
| Subagent | Non nativi nel core. Il companion [`pi-interactive-subagents`](https://github.com/amosblomqvist/pi-interactive-subagents) avvia agent asincroni in pannelli tmux, persistenti e pilotabili; include `scout`, `researcher` e `worker`, loadout a allowlist e nesting esplicito. | Subagent di prima classe con batch, modalità sincrona/asincrona, output strutturato, Agent Hub, steering/revive/kill e ricorsione controllata. L'isolamento del workspace esiste, ma è **opt-in**, non una proprietà automatica di ogni spawn ([task](https://github.com/can1357/oh-my-pi/blob/main/docs/tools/task.md)). | **OMP** per orchestrazione complessiva; **Amos** per pannelli tmux e minimo privilegio più semplice da verificare. |
|
||||
| Tool di coding | Il core Pi espone un set volutamente piccolo; `pi-config` aggiunge soprattutto browser, fetch/search, guard e UI di domande. | Lettura/scrittura/editing e AST, grep/glob, shell ed evaluator persistenti, LSP, DAP, code review, security scan, checkpoint/rewind e altri tool elencati nel [README](https://github.com/can1357/oh-my-pi#thirty-one-first-class-tools). Alcuni sono disattivati inizialmente. | **OMP**, nettamente, per intelligence sul codice e debug. |
|
||||
| Web e browser | [`browser`](https://github.com/amosblomqvist/pi-config/tree/main/extensions/browser) usa Playwright/Chromium headless ed è spento di default; è una singola pagina senza download/upload. `web-search` usa Google Custom Search e richiede API key/CSE ([sorgente](https://github.com/amosblomqvist/pi-config/blob/main/extensions/web-search/index.ts)); c'è anche `web-fetch`. | Browser/computer integrati e ricerca con numerosi backend, inclusi servizi a pagamento, locali/pubblici e motori specializzati ([README](https://github.com/can1357/oh-my-pi#web-search)). | **OMP** per copertura; `pi-config` è più piccolo e comprensibile. |
|
||||
| Skill e plugin | Skill file-based native di Pi più quattro skill incluse: analisi sessioni, PDF, web debug e trascrizione YouTube ([inventario](https://github.com/amosblomqvist/pi-config#skills)). `learn`, dictation, memoria e subagent sono repository separati. | Skill caricate progressivamente tramite metadata e URI `skill://` ([skill docs](https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md)); marketplace per plugin Git/local/catalogo, con skill, comandi, agent, hook, tool, MCP e LSP ([marketplace](https://github.com/can1357/oh-my-pi/blob/main/docs/marketplace.md)). | **OMP** per distribuzione e composizione. |
|
||||
| MCP e interoperabilità | Dipende dalle capacità/estensioni del Pi base; `pi-config` non offre un livello MCP proprio. | Configurazione MCP utente/progetto e discovery di configurazioni provenienti anche da altri editor/agenti ([MCP docs](https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md)). | **OMP**. |
|
||||
| UX/TUI | TUI Pi pulita con editor, fuzzy file search, immagini, shell, steering/follow-up e alberi di sessione. `ask-user-question` aggiunge un dialogo strutturato; snippets e pannelli tmux sono distintivi. [`pi-dictate`](https://github.com/amosblomqvist/pi-dictate) aggiunge dettatura Deepgram. | TUI più ricca con card dei tool, preview/accettazione edit, picker, Agent Hub e time-travel; include sia sintesi vocale sia STT tramite scorciatoia `Alt+H` ([README OMP](https://github.com/can1357/oh-my-pi)). | **OMP** in generale; la semplicità di Pi può essere un pregio. La voce non è esclusiva della configurazione Amos. |
|
||||
| Sessioni | Pi salva JSONL ad albero, consente resume/fork/clone/tree e compaction conservando lo storico ([sessioni Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#sessions)). | JSONL append-only, struttura ad albero, blob esterni e ricostruzione versionata ([formato](https://github.com/can1357/oh-my-pi/blob/main/docs/session.md)); dump/export/share/fork/resume sono documentati come operazioni native ([operazioni](https://github.com/can1357/oh-my-pi/blob/main/docs/session-operations-export-share-fork-resume.md)). | **OMP**, di poco, per operazioni integrate; i due condividono una base concettuale simile. |
|
||||
| Memoria | [`pi-observational-memory`](https://github.com/amosblomqvist/pi-observational-memory) è opzionale e spento di default: observer LLM paralleli distillano i turni, una compaction deterministica crea un ledger e un consolidatore produce file Markdown per sessione. È auditabile, ma aggiunge costo e complessità. | Memoria spenta di default con backend `local`, Hindsight, Mnemopi e Sharpshooter; sommari/lezioni possono attraversare sessioni e alimentare skill, con esplicita avvertenza che la memoria può essere obsoleta ([memory docs](https://github.com/can1357/oh-my-pi/blob/main/docs/memory.md)). | **OMP** per scelta e integrazione; **Amos** per un modello per-sessione semplice da ispezionare. |
|
||||
| Sicurezza applicativa | Pi dichiara di non avere un permission system integrato per filesystem, processi, rete o credenziali e consiglia container/microVM ([security Pi](https://github.com/earendil-works/pi#permissions--containerization)). [`bash-guard`](https://github.com/amosblomqvist/pi-config/tree/main/extensions/bash-guard) intercetta euristicamente solo chiamate al tool `bash`: non protegge `write`, `edit` né i comandi `!`. | Ha policy per tool e tre approval mode, ma il default è **`yolo`**; in tale modalità gli override di comandi bash critici non forzano il prompt. Anche quando si approva un comando non c'è contenimento di filesystem, rete o subprocessi ([approval docs](https://github.com/can1357/oh-my-pi/blob/main/docs/approval-mode.md)). L'offuscamento dei segreti esiste ma è spento di default ([secrets docs](https://github.com/can1357/oh-my-pi/blob/main/docs/secrets.md)). | **Nessun vincitore sicuro di default**. OMP offre controlli migliori, ma sceglie un default molto permissivo. |
|
||||
| Isolamento | Nessun sandbox OS o worktree per-agent documentato; l'allowlist del loadout limita i tool, non il filesystem raggiungibile dai tool concessi. | Gli spawn normali condividono la `cwd` del parent. Workspace separato e merge patch/branch richiedono `task.isolation.enabled` **e** `isolated: true` sul task; l'opzione non è disponibile in plan mode ([task](https://github.com/can1357/oh-my-pi/blob/main/docs/tools/task.md#inputs)). Neppure questo è un sandbox OS. | **OMP** per isolamento anti-collisione opt-in; **parità negativa** come confine di sicurezza. |
|
||||
| Portabilità | I componenti sono piccoli file TypeScript/Markdown copiabili, quindi il lock-in concettuale è basso. Però molte estensioni Amos importano ancora il vecchio scope `@mariozechner/*`; il Pi attuale usa `@earendil-works/*`. L'[advisory ufficiale](https://github.com/earendil-works/pi/security/advisories/GHSA-r95r-rj6r-c39x) depreca il vecchio pacchetto, quindi oggi serve una verifica/possibile migrazione degli import. | Binari e setup multipiattaforma; importa varie convenzioni esterne. Tuttavia si è allontanato dal Pi upstream: scope `@oh-my-pi`, runtime/test Bun, moduli nativi, auth e API proprie sono differenze dichiarate nella [guida di porting](https://github.com/can1357/oh-my-pi/blob/main/docs/porting-from-pi-mono.md). | **Pi + selezione manuale** per lock-in ridotto; **OMP** per portabilità operativa immediata. |
|
||||
| Migrazione delle estensioni | È l'ambiente nativo della raccolta Amos, salvo la transizione di package scope appena citata. | Non tratta `.pi/extensions` come root nativa. Può leggere dichiarazioni `pi.extensions` nei manifest, ma il caricamento e le API non rendono la migrazione automaticamente compatibile ([extension loading](https://github.com/can1357/oh-my-pi/blob/main/docs/extension-loading.md)). | **Non è drop-in in nessuna direzione**; verificare ogni estensione. |
|
||||
| Aggiornamenti e manutenzione | `pi-config` è un piccolo snapshot personale, senza release versionate; il [registro commit](https://github.com/amosblomqvist/pi-config/commits/main/) mostra pochissimi cambiamenti e l'integrazione è responsabilità dell'utente. I companion hanno cicli propri. | Distribuzione versionata con release frequenti e asset per piattaforma; al 7 settembre 2026 la release più recente è [`v18.1.13`](https://github.com/can1357/oh-my-pi/releases/tag/v18.1.13). | **OMP** per manutenzione di prodotto; le release molto rapide aumentano anche il rischio di churn. |
|
||||
| Maturità pratica | Il Pi sottostante è un progetto attivo e maturo, ma `pi-config` non è testato o pubblicato come distribuzione unitaria. L'autore di `pi-dictate`, per esempio, lo presenta esplicitamente come tool personale mantenuto per il proprio uso ([README](https://github.com/amosblomqvist/pi-dictate)). | Repository ampio, migliaia di commit e cadenza di release elevata ([storia](https://github.com/can1357/oh-my-pi/commits/main/), [release](https://github.com/can1357/oh-my-pi/releases)). Più integrazione e utenti implicano più validazione reale, ma anche superficie di bug e regressioni maggiore. | **OMP** come prodotto; nessuna garanzia che “più grande” significhi “più stabile”. |
|
||||
|
||||
## Approfondimento: gestione dei subagenti
|
||||
|
||||
**Sì: OMP ha una gestione dei subagenti paragonabile e, come orchestratore automatico, più completa.** La proposta Amos non è però semplicemente inferiore: privilegia un diverso modello operativo, nel quale ogni agente vive in un vero pannello tmux che l'utente può osservare e usare direttamente, con un loadout strettamente autorizzato.
|
||||
|
||||
| Capacità | Pi + Amos `pi-interactive-subagents` | Oh My Pi |
|
||||
|---|---|---|
|
||||
| Esecuzione e fan-out | Sempre asincrono e non bloccante; più chiamate partono in parallelo e notificano il parent indipendentemente ([README, “How it works”](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#how-it-works)). Non è documentato un limite di concorrenza configurabile. | `task.batch` è attivo di default e accetta `tasks[]`; con `async.enabled=true` gli agenti sono job in background, altrimenti il parent attende. Un semaforo `task.maxConcurrency` limita sia sync sia async ([task: input, modi e limiti](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#modes--variants)). |
|
||||
| Messaggi fra agenti | `subagent_message` corregge uno spawn in corsa al prossimo confine di turno o riapre quello concluso; `ask_question` permette al child di parcheggiarsi e interrogare il parent ([messaging](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#messaging)). | `hub send` consegna steering/follow-up, anche agli agenti parcheggiati, che vengono riattivati; la messaggistica peer è disponibile anche ai child ([task, “Notes”](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#notes)). Limite documentato: lo steering è testo libero, non uno stato condiviso strutturato di goal/todo. |
|
||||
| Supervisione e intervento umano | Widget con stati `starting/active/waiting/stalled/running`, tool corrente e completamenti espandibili; il pannello tmux è la sessione reale, quindi l'utente può entrarvi e scrivere direttamente ([status widget](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#status-widget--configuration)). | `Alt+A` apre Agent Hub: roster/albero, attività, modello, costo/token, transcript live, steering, revive e kill; l'utente può mettere a fuoco la sessione del child e scrivergli ([Agent Hub](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/agent-hub.md)). **OMP non manca quindi della supervisione interattiva**; Amos la rende più concreta e terminal-native tramite pannelli separati. |
|
||||
| Resume e persistenza | Registro nome→sessione persistente attraverso i riavvii; il resume ripristina lo snapshot del loadout originale. Supporta sessioni `standalone`, `lineage-only` o `fork` con contesto del parent ([resume](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#messaging), [session mode](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#session-mode)). | Salva output e transcript (`agent://`, `history://`); agenti idle/parcheggiati sono riattivabili anche dopo il resume del parent ([Agent Hub, “Persisted agents”](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/agent-hub.md#persisted-agents-and-advisors)). Eccezione importante: un task eseguito in workspace isolato viene smontato dopo merge/cattura patch e **non è riattivabile** ([task flow](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#flow)). |
|
||||
| Definizioni e routing modelli | File Markdown in `.pi/agents` o `~/.pi/agent/agents`, con modello, thinking, skill, tool, `cwd` e modalità sessione; il singolo spawn può sovrascrivere il modello. Include tre profili (`scout`, `researcher`, `worker`) ([custom agents](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#custom-agents)). | File Markdown `.omp/agents`, agent inclusi e provenienti da estensioni/plugin; routing con override per nome, lista fallback e alias `modelRoles`, più effort per task, prewalk e advisor opzionali ([agent definition](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/task-agent-discovery.md#agent-definition-shape), [routing](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/task-agent-discovery.md#model-and-structured-output-precedence)). |
|
||||
| Tool e sicurezza applicativa | Allowlist stretta: il child parte con `--no-extensions` e riceve soltanto i tool e le estensioni esplicitamente elencati; lo snapshot preserva il vincolo al resume ([tool access](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#tool-access-control)). È minimo privilegio applicativo, non sandbox OS. | Ogni definizione può limitare `tools` e `spawns`, e il limite di profondità rimuove `task`; però i child headless forzano `tools.approvalMode: yolo`, perché non hanno una UI locale per le conferme ([task flow](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#flow)). Di conseguenza la qualità dell'allowlist/deny policy del parent è un confine essenziale. |
|
||||
| Agenti annidati | Solo se `subagent_agents` è presente; la lista autorizza nomi precisi a ogni livello e non esiste uno spawn senza profilo nominato ([tool access](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#tool-access-control)). Il parent attende anche i nipoti prima dell'auto-exit. | Supportati con policy `spawns` e limite `task.maxRecursionDepth` (default `2`); al limite il tool `task` viene rimosso ([recursion gating](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/task-agent-discovery.md#recursion-depth-gating)). Agent Hub conserva la gerarchia parent/child. |
|
||||
| Filesystem, worktree e conflitti | `cwd` può assegnare una directory diversa, ma il README non documenta workspace/worktree isolati né merge automatici ([role folders](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#role-folders)). **Inferenza:** più worker scriventi nella stessa checkout possono quindi collidere; separare le `cwd` resta responsabilità dell'orchestratore/utente. | Lo spawn ordinario usa la `cwd` del parent. L'isolamento è disponibile soltanto con configurazione globale attiva, `isolated: true`, repository Git e fuori dal plan mode; può applicare patch o cherry-pickare un branch ([task modes](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#modes--variants)). Verifica l'applicabilità della patch; in caso di conflitto lascia l'artefatto per intervento manuale e preserva lo stash in branch mode ([gestione conflitti](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#notes)). |
|
||||
| Output | Il risultato è l'ultimo messaggio assistant, inoltrato al parent; non è documentato un contratto JSON Schema né un merge di file ([auto-exit](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#auto-exit)). | `outputSchema` per item, modalità `permissive`/`strict`, risultato parsato e artefatti completi tramite `agent://`; il child deve concludere con `yield`, con fino a tre reminder ([task outputs](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#outputs), [flow](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#flow)). |
|
||||
| Portabilità e prerequisiti | Questa variante è esplicitamente **tmux-only** e richiede Pi + tmux ([requirements](https://github.com/amosblomqvist/pi-interactive-subagents/blob/c3e8b53c0754ae5ccc19fdab5a7481ec039bc2f7/README.md#requirements)); l'upstream HazAT supporta più multiplexer, ma non è il componente qui confrontato. | Il runtime OMP è multipiattaforma; l'isolamento seleziona backend diversi per Linux, macOS e Windows e ricade su copia ricorsiva quando necessario ([backend di isolamento](https://github.com/can1357/oh-my-pi/blob/4c6feacddb6ff26e5219df7283bc371ad7e1de55/docs/tools/task.md#side-effects)). |
|
||||
|
||||
### Giudizio mirato
|
||||
|
||||
**Per orchestrazione di subagenti sceglierei OMP**, perché combina fan-out controllato, sync/async, Agent Hub, messaggistica peer, output tipizzato, nesting con limiti e isolamento anti-collisione opzionale. Quindi la risposta alla domanda “ce l'ha anche OMP?” è **sì, e sul piano funzionale offre di più**.
|
||||
|
||||
**Pi + Amos resta preferibile in due casi:** quando si vuole entrare fisicamente nei pannelli dei worker mentre lavorano, oppure quando si considera prioritaria una politica child “deny by default” molto leggibile. La sua gestione può essere ottimale per un power user tmux; non è però altrettanto completa come orchestratore automatico, soprattutto per output strutturato, concorrenza limitata e gestione/merge degli artefatti.
|
||||
|
||||
Due caveat impediscono un verdetto semplicistico:
|
||||
|
||||
1. in OMP “subagent isolato” non significa “ogni subagent”: senza entrambi i toggle necessari, gli agenti scriventi condividono la checkout;
|
||||
2. isolamento e continuità sono in tensione: il child OMP isolato evita collisioni, ma dopo il merge/cleanup non può essere riattivato; uno non isolato può invece essere parcheggiato e ripreso.
|
||||
|
||||
## Cosa include davvero `pi-config`
|
||||
|
||||
Nel repository principale ci sono:
|
||||
|
||||
- `ask-user-question`: richiesta strutturata con popup TUI e serializzazione dell'interazione;
|
||||
- `bash-guard`: conferma/blocco euristico di comandi shell pericolosi;
|
||||
- `browser`: automazione Playwright su Chromium headless, disattivata inizialmente;
|
||||
- `custom-header`: header TUI personalizzato;
|
||||
- `prompt-snippets`: regole brevi attivabili sul singolo messaggio;
|
||||
- `web-fetch` e `web-search`;
|
||||
- skill per analisi sessioni, PDF, debug web e trascrizione YouTube.
|
||||
|
||||
L'elenco e i prerequisiti sono nel [README ufficiale](https://github.com/amosblomqvist/pi-config). Le capacità più ambiziose sono in repository distinti:
|
||||
|
||||
- [`pi-interactive-subagents`](https://github.com/amosblomqvist/pi-interactive-subagents), subagent interattivi in tmux;
|
||||
- [`pi-observational-memory`](https://github.com/amosblomqvist/pi-observational-memory), memoria osservazionale per sessione;
|
||||
- [`pi-dictate`](https://github.com/amosblomqvist/pi-dictate), STT con Deepgram;
|
||||
- [`learn`](https://github.com/amosblomqvist/learn), ambiente didattico con quiz, log e agent di ricerca/visualizzazione.
|
||||
|
||||
Questi componenti **non formano automaticamente una singola installazione testata, aggiornata e versionata insieme**. Considerarli una “suite” è un'inferenza utile per il confronto, non una promessa del maintainer.
|
||||
|
||||
## Dove OMP è realmente superiore
|
||||
|
||||
1. **È coerente come prodotto.** Installazione, configurazione YAML, schema, tool, sessioni e aggiornamenti fanno parte dello stesso rilascio ([settings](https://github.com/can1357/oh-my-pi/blob/main/docs/settings.md)).
|
||||
2. **Il routing dei modelli è molto più sofisticato.** Non si sceglie soltanto un modello: si possono assegnare costi/capacità differenti a pianificazione, task, vision, commit, advisor e attività leggere.
|
||||
3. **L'intelligence sul codice è integrata.** LSP, DAP, editing AST, evaluator persistenti e review non richiedono di costruire un proprio stack di estensioni.
|
||||
4. **Subagent e memoria sono parti del sistema**, non componenti companion da sincronizzare a mano.
|
||||
5. **Ha più opzioni di interoperabilità**: MCP, marketplace e discovery di configurazioni da altri strumenti.
|
||||
|
||||
Questa superiorità è soprattutto di **copertura e integrazione**, non una prova automatica di qualità superiore per ogni singola funzione. Le quantità dichiarate nel README di OMP sono affermazioni del progetto, non benchmark indipendenti.
|
||||
|
||||
## Dove Pi + la configurazione Amos è migliore
|
||||
|
||||
1. **È più facile capire il perimetro.** Ogni estensione è piccola, selezionabile e sostituibile. Si può usare `prompt-snippets` senza accettare browser, memoria o subagent.
|
||||
2. **Ha meno lock-in architetturale.** Le skill Markdown e molte estensioni TypeScript restano vicine all'ecosistema Pi, anche se oggi gli import verso il vecchio package scope richiedono attenzione.
|
||||
3. **Alcune idee sono più eleganti che “integrate”.** Gli snippet effimeri per messaggio, gli agent visibili nei pannelli tmux e la memoria in file Markdown per sessione sono facili da osservare e modificare.
|
||||
4. **Favorisce l'apprendimento del sistema.** È una buona base per chi vuole costruirsi il proprio harness anziché adottare una piattaforma già opinionata.
|
||||
|
||||
Il prezzo è tempo operativo: installazione, dipendenze, compatibilità, aggiornamenti e test ricadono sull'utente.
|
||||
|
||||
## Sicurezza: la conclusione scomoda
|
||||
|
||||
**Né Pi + `pi-config` né OMP forniscono, da soli, un sandbox di sicurezza.**
|
||||
|
||||
- In Pi, `bash-guard` è un buon guardrail UX, ma non vede tutte le scritture e non contiene il processo. Le estensioni Pi hanno accesso al sistema con i privilegi dell'utente; la documentazione raccomanda esplicitamente container o microVM ([Pi security](https://github.com/earendil-works/pi#permissions--containerization)).
|
||||
- In OMP esistono più policy, deny list e modalità di approvazione. Tuttavia `tools.approvalMode` parte da **`yolo`**, i safety override bash non diventano prompt in quella modalità, un comando approvato conserva accesso ambientale e le estensioni girano nello stesso processo ([approval mode](https://github.com/can1357/oh-my-pi/blob/main/docs/approval-mode.md), [extension loading](https://github.com/can1357/oh-my-pi/blob/main/docs/extension-loading.md)). Anche la protezione dei segreti è opt-in.
|
||||
|
||||
Se scegliessi OMP imposterei subito almeno:
|
||||
|
||||
1. `tools.approvalMode: always-ask` per un ambiente sensibile, oppure `write` come compromesso;
|
||||
2. deny/prompt espliciti per evaluator, browser/computer e tool non necessari;
|
||||
3. offuscamento segreti abilitato e configurato;
|
||||
4. esecuzione in container, VM o microVM quando repository, credenziali o rete sono sensibili.
|
||||
|
||||
Con Pi farei la stessa cosa a livello OS e tratterei `bash-guard` come seconda cintura, non come sandbox.
|
||||
|
||||
## Raccomandazione per profilo
|
||||
|
||||
| Profilo | Scelta consigliata | Perché |
|
||||
|---|---|---|
|
||||
| Sviluppatore che vuole essere produttivo subito | **Oh My Pi** | Meno assemblaggio; LSP/DAP, modelli, agent e sessioni sono già integrati. |
|
||||
| Power user multi-model / molti provider | **Oh My Pi** | Routing per ruolo, fallback e credenziali multiple sono capacità native. |
|
||||
| Team che vuole una configurazione ripetibile | **Oh My Pi**, release fissata | Installer, Nix/mise, config e release versionate sono più riproducibili; fissare la versione riduce il churn. |
|
||||
| Hacker di Pi che vuole costruire il proprio ambiente | **Pi + componenti `pi-config`** | Superficie ridotta, sorgenti leggibili, composizione libera. |
|
||||
| Utente che vuole solo snippet, guard o browser | **Pi + singole estensioni** | Non serve adottare un fork molto più grande per tre capacità. |
|
||||
| Chi apprezza subagent visibili e interattivi in tmux | **Pi + `pi-interactive-subagents`** | È una scelta UX specifica e ben distinta dall'Agent Hub. |
|
||||
| Ambiente ad alta sicurezza | **Nessuno dei due senza isolamento OS** | I controlli applicativi non sostituiscono container/microVM; OMP va inoltre tolto da `yolo`. |
|
||||
| Runtime Pi già integrato via RPC, come ThothII | **Restare su Pi salvo progetto di migrazione dedicato** | OMP offre RPC/ACP, ma package scope, caricamento estensioni, eventi e semantiche del fork richiedono test contrattuali: non è una sostituzione drop-in. |
|
||||
|
||||
### Nota specifica per ThothII
|
||||
|
||||
Per usare un agente nel terminale del repository, OMP può essere valutato senza cambiare l'architettura. **Sostituire invece il processo Pi che ThothII avvia in modalità RPC è un'altra decisione.** ThothII dipende dal contratto degli eventi RPC, dall'estensione gate, dal resume e dal comportamento di sessione. La [guida di porting di OMP](https://github.com/can1357/oh-my-pi/blob/main/docs/porting-from-pi-mono.md) e la sua [documentazione di caricamento estensioni](https://github.com/can1357/oh-my-pi/blob/main/docs/extension-loading.md) mostrano divergenze sufficienti da richiedere almeno una suite di compatibilità end-to-end prima di considerarlo un sostituto.
|
||||
|
||||
## Verdetto
|
||||
|
||||
**Il migliore in assoluto, per me, è Oh My Pi — con una release fissata e una configurazione iniziale più restrittiva del default.** Vince quasi tutte le categorie funzionali e riduce drasticamente il lavoro di integrazione.
|
||||
|
||||
Non lo sceglierei però “alla cieca”: `yolo` come default è un caveat serio, la superficie enorme rende probabile qualche regressione e il fork crea più dipendenza dalle proprie API. Per una workstation con codice e credenziali reali lo metterei dietro approvazioni esplicite e isolamento OS.
|
||||
|
||||
**Pi + `pi-config` è la scelta migliore quando l'obiettivo è un ambiente personale minimale e intenzionale**, non quando si cerca il maggior numero di funzioni. Installerei solo i componenti necessari, controllerei gli import dopo la migrazione da `@mariozechner/*` a `@earendil-works/*` e aggiungerei test prima di usarli in un flusso critico.
|
||||
@@ -1,44 +0,0 @@
|
||||
# Z.ai Coding Plan: bonus di quota e client CLI
|
||||
|
||||
Verifica effettuata il **7 settembre 2026**, esclusivamente su fonti ufficiali Z.ai/ZCode.
|
||||
|
||||
## Risposta breve
|
||||
|
||||
**No: Z.ai non documenta un bonus permanente del 150% (+50%) per un altro harness CLI.** La sola pagina ufficiale che usa oggi l'espressione “150% quota boost” è quella di **AutoClaw**: lo presenta come vantaggio a tempo limitato per piani Individual e Team, ma non precisa se significhi quota finale al 150% o incremento del 150%. AutoClaw è inoltre descritto come applicazione desktop per macOS e Windows, non come CLI da installare su un server. ([AutoClaw](https://autoclaw.z.ai/))
|
||||
|
||||
C'è però una promozione temporanea più interessante e formulata senza ambiguità: dal **3 al 20 settembre 2026**, ogni giorno fra le **23:00 e le 09:00 UTC+8**, GLM-5.3-Flash consuma zero quota in ZCode, mentre negli **altri agenti ufficialmente supportati la quota disponibile è raddoppiata**. In Italia, nel periodo della campagna, la finestra corrisponde alle **17:00–03:00 CEST**. La promozione vale per tutti i piani a pagamento e soltanto per GLM-5.3-Flash; GLM-5.3 continua a consumare la quota normale. ([GLM-5.3-Flash Usage Campaign](https://docs.z.ai/devpack/notice/event-glm-5.3-flash))
|
||||
|
||||
## Quali alternative CLI sono ufficialmente ammesse
|
||||
|
||||
La pagina corrente dei tool supportati nomina espressamente questi client utilizzabili da terminale:
|
||||
|
||||
| Harness | CLI/server | Stato nella documentazione Z.ai | Quota |
|
||||
|---|---:|---|---|
|
||||
| **Pi** | Sì | Esplicitamente incluso fra i Coding Agent Tool | Quota ordinaria; **2× su GLM-5.3-Flash nella finestra della campagna** |
|
||||
| **Codex** | Sì | Esplicitamente incluso fra i Coding Agent Tool | Come sopra |
|
||||
| **Claude Code** | Sì | Supportato e corredato da guida CLI ufficiale Z.ai | Come sopra |
|
||||
| **OpenCode** | Sì | Supportato; guida ufficiale intitolata esplicitamente “OpenCode CLI” | Come sopra |
|
||||
| **Droid** | Sì | Descritto da Z.ai come agente che gira nel terminale | Come sopra |
|
||||
| **Crush** | Sì | Descritto esplicitamente come CLI/TUI | Come sopra |
|
||||
| **Goose** | Sì | Incluso fra i Coding Agent Tool, con esecuzione locale | Come sopra |
|
||||
| **Oh My Pi (OMP)** | Sì, tecnicamente | **Non è nominato** nell'elenco ufficiale; Z.ai nomina Pi, non OMP | Bonus e conformità **non confermati ufficialmente** |
|
||||
|
||||
Fonti: [elenco ufficiale dei tool e endpoint Coding Plan](https://docs.z.ai/devpack/tool/others), [guida Claude Code](https://docs.z.ai/devpack/tool/claude), [guida OpenCode CLI](https://docs.z.ai/devpack/tool/opencode).
|
||||
|
||||
Z.ai espone endpoint Coding Plan per Anthropic Messages, OpenAI Chat Completions e OpenAI Responses, ma questo **non rende automaticamente autorizzato qualunque client compatibile**: le condizioni limitano la quota ai tool ufficialmente supportati e avvertono che l'uso con integrazioni non autorizzate può comportare restrizioni. ([Subscription Terms](https://docs.z.ai/legal-agreement/subscription-terms), [Usage Policy](https://docs.z.ai/devpack/usage-policy))
|
||||
|
||||
## Implicazione pratica per il server
|
||||
|
||||
Per il caso in esame sceglierei **Pi + configurazione Amos direttamente sul server**: Pi è ora nominato ufficialmente da Z.ai, funziona da terminale e, durante la campagna attuale, rientra ragionevolmente negli “other supported Agents” con quota raddoppiata per GLM-5.3-Flash. La configurazione Amos estende Pi senza sostituire il client; resta comunque prudente verificare nel pannello consumi che le chiamate vengano classificate come Pi.
|
||||
|
||||
La seconda scelta è **OpenCode**, perché Z.ai fornisce una procedura CLI esplicita (`opencode auth login` → `Z.AI Coding Plan`). Claude Code è altrettanto documentato, ma la scelta dipende dalla preferenza per il suo harness.
|
||||
|
||||
Non sceglierei OMP confidando nel bonus: benché possa usare endpoint compatibili, **Oh My Pi non compare per nome** nell'elenco autorizzato. La risposta ufficialmente difendibile è quindi: **Pi sì; OMP non confermato**.
|
||||
|
||||
Infine, ZCode dispone oggi di pacchetti Linux, ma la documentazione li definisce sempre **desktop app** (`.AppImage`, `.deb`, `.rpm`) da lanciare con interfaccia grafica; non documenta una modalità CLI/headless equivalente a Pi o OpenCode. ([Installazione ZCode](https://zcode.z.ai/en/docs/install))
|
||||
|
||||
## Verdetto
|
||||
|
||||
- Se si cerca **esattamente un +50% permanente**, non risulta alcun harness CLI ufficialmente documentato.
|
||||
- Se si vuole sfruttare la **promozione corrente**, Pi, Codex, Claude Code, OpenCode, Droid, Crush e Goose sono alternative CLI ufficialmente supportate; nel periodo e nella fascia indicati ottengono **2×**, non 150%, usando GLM-5.3-Flash.
|
||||
- Per questa infrastruttura sceglierei **Pi+Amos sul server**, oppure **OpenCode** se si desidera il percorso d'installazione più esplicitamente documentato da Z.ai.
|
||||
@@ -1,67 +0,0 @@
|
||||
# ACP di Zed, Oh My Pi e Pi
|
||||
|
||||
_Verifica effettuata il 7 settembre 2026 su documentazione e codice sorgente primari._
|
||||
|
||||
## In breve
|
||||
|
||||
ACP (Agent Client Protocol) è un protocollo aperto che standardizza il collegamento tra un
|
||||
editor/IDE e un coding agent. Il paragone utile è con LSP: LSP standardizza editor ↔ language
|
||||
server, ACP standardizza editor ↔ agente. Il client (per esempio Zed) ospita l'interfaccia;
|
||||
l'agent process conserva normalmente runtime, modelli, autenticazione, strumenti e configurazione.
|
||||
|
||||
ACP usa JSON-RPC 2.0. Copre inizializzazione e autenticazione, creazione/ripristino delle sessioni,
|
||||
prompt e cancellazione, streaming di testo e pensieri, piani e tool call, comandi, richieste di
|
||||
permesso e — se entrambe le parti lo supportano — operazioni su filesystem e terminale.
|
||||
|
||||
Fonti: [introduzione ACP](https://agentclientprotocol.com/overview/introduction),
|
||||
[flusso e metodi del protocollo](https://agentclientprotocol.com/protocol/overview),
|
||||
[External Agents in Zed](https://zed.dev/docs/ai/external-agents).
|
||||
|
||||
## Confronto in Zed
|
||||
|
||||
| Aspetto | Oh My Pi | Pi |
|
||||
|---|---|---|
|
||||
| Tipo di integrazione | Server ACP incorporato: `omp acp` | Adapter comunitario `pi-acp`, installabile dal registry di Zed |
|
||||
| Collegamento al motore | ACP è una modalità dello stesso motore OMP | L'adapter avvia `pi --mode rpc` e traduce RPC ↔ ACP |
|
||||
| Output e tool call | Streaming e tool call ACP nativi | Streaming, tool card, posizioni nei file e diff strutturati tradotti dall'adapter |
|
||||
| File | Può inoltrare `read`/`write` al filesystem del client | Nessuna delega ACP `fs/*`; Pi legge e scrive localmente |
|
||||
| Terminale | Può creare e seguire terminali del client | Nessuna delega ACP `terminal/*`; i comandi girano localmente |
|
||||
| Permessi | `edit` e `bash` possono usare `session/request_permission` nell'editor | La UI riceve i tool call, ma non ha la stessa integrazione nativa di file/terminale |
|
||||
| Sessioni | Implementazione diretta di sessioni, comandi e configurazione ACP | Mappa le sessioni ACP ai file di sessione Pi e supporta `session/load` |
|
||||
| Skills/comandi | Carica skills, estensioni e slash command OMP | Carica skills e comandi Pi; l'adapter aggiunge comandi per l'uso headless |
|
||||
| MCP configurati in Zed | OMP contiene il plumbing ACP/MCP nel proprio server | Accettati nei parametri ACP ma non inoltrati a Pi dall'adapter corrente |
|
||||
| Maturità dichiarata | Funzionalità first-class del progetto | L'adapter si definisce “MVP-style” e centrato soprattutto su Zed |
|
||||
|
||||
L'integrazione OMP non è solo una dichiarazione nel README: il comando ACP è parte del sorgente e
|
||||
il `ClientBridge` instrada `read`, `write`, `bash`, `edit` e richieste di permesso verso il client
|
||||
quando Zed annuncia le capacità corrispondenti. Fonti:
|
||||
[README OMP](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/README.md),
|
||||
[comando ACP](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/commands/acp.ts),
|
||||
[ACP ClientBridge](https://github.com/can1357/oh-my-pi/blob/daf07999c2fee9b22edc7bf8fea1fb6272e0df5e/packages/coding-agent/src/modes/acp/acp-client-bridge.ts).
|
||||
|
||||
Pi è comunque supportato esplicitamente da Zed: si installa `pi ACP` dal registry. L'integrazione
|
||||
è però un progetto separato e non una modalità presente nel core Pi. L'adapter corrente conserva
|
||||
molto dell'esperienza utile — streaming, tool call, diff, resume, comandi e skills — ma dichiara
|
||||
esplicitamente di non delegare filesystem o terminale a Zed e di non collegare a Pi gli MCP server
|
||||
ricevuti dal client. Fonti:
|
||||
[scheda Pi nel registry Zed](https://zed.dev/acp/agent/pi),
|
||||
[manifest del registry](https://github.com/agentclientprotocol/registry/blob/9ec416a76f69c9ff8a8316931e38f4c74ad41fa8/pi-acp/agent.json),
|
||||
[README e limiti di `pi-acp`](https://github.com/svkozak/pi-acp/blob/d1cffc047ab37a096ee70ca39cfc1de463db8d12/README.md),
|
||||
[RPC di Pi](https://github.com/earendil-works/pi/blob/9211da172325117dc59e6f9f25f248dc628b3f81/packages/coding-agent/docs/rpc.md).
|
||||
|
||||
## Giudizio
|
||||
|
||||
**OMP si trova meglio con ACP perché ACP è una sua interfaccia nativa e il suo livello strumenti è
|
||||
stato progettato per delegare operazioni all'editor.** Zed non è soltanto una finestra per la chat:
|
||||
partecipa a file, terminale e autorizzazioni.
|
||||
|
||||
**Pi si trova comunque bene con Zed per l'uso quotidiano**, specialmente per conversazione,
|
||||
streaming, modifiche, diff e ripresa delle sessioni. Oggi, però, l'integrazione è meno profonda:
|
||||
Zed controlla un adapter che controlla Pi via RPC, mentre file e shell rimangono dal lato Pi.
|
||||
|
||||
Per Pi+Amos, i subagenti tmux non diventano automaticamente thread/subagenti nativi di Zed: ACP
|
||||
espone la sessione Pi principale, mentre l'orchestrazione Amos continua nel proprio runtime e nei
|
||||
pane tmux. È quindi una combinazione possibile, ma per osservare e pilotare direttamente quei pane
|
||||
l'esperienza terminale/tmux resta più fedele. Questa conclusione è un'inferenza dall'architettura
|
||||
dell'adapter (`pi-acp` avvia una singola sessione Pi RPC per sessione ACP) e dai limiti dichiarati,
|
||||
non una garanzia esplicita del progetto Amos.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Prodotti text-to-SQL e natural-language-to-SQL
|
||||
|
||||
Ricognizione di prodotti e siti ufficiali che consentono di interrogare dati strutturati
|
||||
in linguaggio naturale e/o di generare SQL. Sono escluse pubblicazioni accademiche,
|
||||
benchmark e articoli di terze parti. Le descrizioni riportano solo capacità dichiarate
|
||||
nelle fonti ufficiali collegate.
|
||||
|
||||
Data della ricerca: 2026-09-09.
|
||||
|
||||
Nota di verifica: al 2026-09-09 SQLPilot non è stato verificato come raggiungibile. Il fetch
|
||||
del sito ufficiale `https://sqlpilot.ai/` restituisce `502 Bad Gateway`; anche
|
||||
`https://www.sqlpilot.ai/`, `http://sqlpilot.ai/`, `/download` e `/signup` non risultano
|
||||
raggiungibili dal controllo diretto (risoluzione DNS fallita), senza redirect osservabili.
|
||||
La pagina ufficiale indicizzata in precedenza resta una fonte storica, non una conferma di
|
||||
disponibilità odierna. Non è stato individuato un URL ufficiale alternativo funzionante.
|
||||
|
||||
| Prodotto | URL ufficiale | Descrizione verificabile | Modello |
|
||||
|---|---|---|---|
|
||||
| [Vanna AI](https://vanna.ai/) | [Sito](https://vanna.ai/) · [Documentazione](https://vanna.ai/docs/index.html) | Framework/agente SQL che permette agli utenti di porre domande in linguaggio naturale su un database. La documentazione descrive un flusso RAG: si addestra il modello con SQL, DDL e documentazione, poi `ask` genera SQL che può essere eseguito sul database. | Open source; disponibile anche come servizio/soluzione hosted ed enterprise. |
|
||||
| [Wren AI](https://github.com/Canner/WrenAI) | [Repository ufficiale](https://github.com/Canner/WrenAI) · [Documentazione CLI](https://github.com/Canner/WrenAI/blob/main/docs/core/reference/cli.md) | Layer semantico open source per agenti e applicazioni GenBI. Il progetto dichiara supporto a text-to-SQL su oltre 20 sorgenti dati; la CLI conserva coppie natural-language-to-SQL e usa il contesto semantico/MDL per scrivere ed eseguire query. | Open source (licenza Apache-2.0 per il core dichiarato nel repository). |
|
||||
| [Dataherald](https://github.com/Dataherald/dataherald) | [Repository ufficiale](https://github.com/Dataherald/dataherald) | Engine natural-language-to-SQL per domande su dati relazionali. Il repository descrive un’API che espone un database in modo interrogabile in linguaggio naturale e include componenti per engine, API enterprise, console amministrativa e Slackbot. | Open source (Apache-2.0); include componenti enterprise self-hosted. |
|
||||
| [DB-GPT](https://github.com/eosphoros-ai/DB-GPT) | [Repository ufficiale](https://github.com/eosphoros-ai/DB-GPT) · [DB-GPT-Hub](https://github.com/eosphoros-ai/DB-GPT-Hub) | Framework open source per applicazioni data-driven e agenti, con un workflow Text-to-SQL documentato e un progetto Hub per dataset, modelli e fine-tuning dedicati alla conversione testo-SQL. | Open source. |
|
||||
| [Snowflake Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) | [Documentazione ufficiale](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) | Servizio gestito di Snowflake con cui utenti business pongono domande in linguaggio naturale e ricevono risposte senza scrivere SQL. La documentazione lo descrive esplicitamente come sistema agentico che genera risposte text-to-SQL, usando semantic model/views per il contesto. | SaaS/enterprise gestito nella piattaforma Snowflake. |
|
||||
| [Databricks Genie / Genie Agents](https://docs.databricks.com/gcp/en/genie-agents/concepts) | [Documentazione ufficiale](https://docs.databricks.com/gcp/en/genie-agents/concepts) · [API](https://docs.databricks.com/gcp/en/genie-agents/conversation-api) | Funzionalità Databricks per interagire con dati tramite linguaggio naturale. La documentazione dichiara che Genie converte i prompt in SQL, restituisce quando possibile la query generata e i risultati, e può porre domande di chiarimento. | SaaS/enterprise, integrato in Databricks. |
|
||||
| [ThoughtSpot Spotter](https://www.thoughtspot.com/product/spotter-semantics) | [Pagina prodotto ufficiale](https://www.thoughtspot.com/product/spotter-semantics) · [SpotGuide](https://tsa-guide.thoughtspot.com/) | Interfaccia di analytics conversazionale: l’utente descrive ciò che vuole in linguaggio naturale e il motore genera query SQL deterministiche tramite il layer semantico. La guida ufficiale presenta Spotter come esperienza “no SQL” per cercare e interrogare i dati. | SaaS/enterprise analytics. |
|
||||
| [Seek AI](https://www.seek.ai/ai-data-analyst) | [AI Data Analyst](https://www.seek.ai/ai-data-analyst) · [Product Overview](https://www.seek.ai/product-overview) | Piattaforma/agent per dati strutturati con un Dialogue Agent che interpreta domande in linguaggio naturale e un Semantic Parsing Agent che genera query; l’offerta include anche un’interfaccia embedded per prodotti SaaS e un’app nativa Snowflake. | SaaS/enterprise; disponibile anche come componente embedded e Snowflake Native App. |
|
||||
| ~~SQLPilot~~ | [Sito ufficiale](https://sqlpilot.ai/) | **Non verificato al 2026-09-09**: il dominio ufficiale non è risultato raggiungibile (502/DNS) e non è stato trovato un redirect o un URL ufficiale alternativo funzionante. Una precedente indicizzazione ufficiale descriveva un editor SQL assistito da AI, ma non costituisce conferma di disponibilità odierna. | Non verificato. |
|
||||
|
||||
## Note di perimetro
|
||||
|
||||
- “Open source” indica un progetto il cui repository ufficiale dichiara una licenza o un core open source; non implica che eventuali servizi hosted siano gratuiti.
|
||||
- “SaaS/enterprise” indica un prodotto gestito o venduto come piattaforma aziendale; le fonti ufficiali non sempre pubblicano prezzi o dettagli contrattuali.
|
||||
- Le capacità possono dipendere dal database collegato, dal modello semantico configurato e dai permessi dell’installazione.
|
||||
Reference in New Issue
Block a user