mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: focus public documentation on product usage

Browse Source
This commit is contained in:
marcopan
2026-08-26 10:15:07 +02:00
parent 23bc2f6555
commit a54d4769dd
67 changed files with 290 additions and 9963 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/general/pi-configuration.md
+34 -30
View File
@@ -1,6 +1,10 @@
# Configurazione dei modelli in Pi: built-in, utente, progetto
# Configurazione locale dei modelli Pi
Pi (il coding agent che orchestra il workflow NL→SQL) può risolvere un `provider/model` in tre modi diversi. Non sono alternativi: coesistono, e la scelta di quale usare dipende da **quanto è standard l'endpoint** e da **quanto deve essere ampia la visibilità** del modello (tutti i progetti vs. un progetto solo).
Pi, l'agente che orchestra il workflow NL→SQL, risolve i modelli integrati e i provider
OpenAI-compatible dichiarati nel catalogo locale. ThothII applica una regola più stretta di Pi:
un provider o un modello custom non può essere registrato da codice in `harness/.pi/extensions/`.
Endpoint, protocollo, compatibilità e identificatori dei modelli appartengono esclusivamente ai file
locali `deploy/pi/models.json` e `deploy/pi/settings.json`.
> **ThothII operator note:** ThothII runs Pi only in Docker Compose. Paths under
> `~/.pi/agent/` in this document describe Pi's container-side behavior. Operators edit
@@ -17,8 +21,10 @@ In produzione configurare una sola sorgente generica: il bundle `THT_SECRETS_FIL
selezionato e passa al solo child Pi la variabile nativa appropriata
(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, ecc.). Il percorso generico,
le chiavi di provider non selezionati e il vecchio `PI_PROVIDER_API_KEY` vengono rimossi dall'ambiente
del child. Provider locali come `ollama`, `lmstudio` e `aritmolab` continuano senza chiave; un provider
hosted non mappato o un secret mancante/non sicuro fallisce prima dello spawn con errore sanitizzato.
del child. Per un provider custom, il backend deriva il nome della variabile dal campo dichiarativo
`apiKey` di `models.json`; un valore letterale indica che il catalogo è autosufficiente. Non esistono
eccezioni per nomi di provider compilate nel codice. Un secret mancante o non sicuro fallisce prima
dello spawn con errore sanitizzato.
La sorgente generica supporta soltanto provider con una singola chiave: `ant-ling`, `anthropic`,
`cerebras`, `deepseek`, `fireworks`, `github-copilot`, `google` (anche tramite alias `gemini`),
@@ -33,7 +39,7 @@ dello spawn (anche durante l'elenco modelli); tutte le credenziali ambientali AW
Cloudflare restano comunque rimosse. Servirà una futura configurazione dedicata per provider per
supportare questi bundle senza ambiguità.
## I tre livelli di provenienza di un modello
## Le fonti di un modello
### 1. Built-in (compilato dentro Pi)
@@ -48,8 +54,8 @@ Per un endpoint **OpenAI-compatible** che non è tra i built-in — ma che non r
Nelle installazioni gestite da ThothII il file deve essere interamente dichiarativo. ThothII
rifiuta ricorsivamente qualsiasi valore JSON che inizi con `!`, anche dentro `headers`, `models`,
`modelOverrides`, `compat`, array o campi non ancora conosciuti. Pi 0.80.3 tratterebbe quel prefisso
come un comando shell al momento della richiesta; questa forma non è ammessa né dall'elenco gestito
dei modelli né dallo smoke isolato. L'errore restituito è fisso e non include comando, percorso o
come un comando shell al momento della richiesta; questa forma non è ammessa dall'elenco gestito
dei modelli. L'errore restituito è fisso e non include comando, percorso o
secret.
Per i secret usare un riferimento ambiente come `"$ZAI_API_KEY"` o `"${ZAI_API_KEY}"`. Il backend
@@ -86,25 +92,27 @@ Esempio reale in uso su questa macchina — GLM (provider `zai`):
Essendo a livello utente, GLM è visibile da **qualsiasi progetto**.
### 3. Estensione (`.pi/extensions/*.js`, utente o progetto)
### Provider da estensione: non ammessi in ThothII
Quando l'endpoint richiede codice — ad esempio conversione di eventi (thinking→text), un `streamSimple` custom, o comunque logica che un file dichiarativo non può esprimere — serve un'estensione Pi che chiama `pi.registerProvider(...)`. Le estensioni possono vivere sia in `~/.pi/agent/extensions/` (tutti i progetti) sia in `<progetto>/.pi/extensions/` (solo quel progetto, se Pi viene lanciato con quella cwd).
Esempio reale — il provider AritmoLab (Qwen), interno all'ospedale, usato solo da ThothII: [harness/.pi/extensions/aritmolab-provider.js](../../harness/.pi/extensions/aritmolab-provider.js).
Pi supporta tecnicamente provider registrati da estensioni JavaScript, ma ThothII non usa questa
possibilità. Le estensioni di progetto sono riservate al workflow e ai gate; non devono contenere
`registerProvider(...)`. Un endpoint che non può essere descritto dal catalogo OpenAI-compatible
non è un provider supportato da questa installazione finché il contratto dichiarativo non viene
esteso in modo generico.
## Tabella riassuntiva (stato attuale di questa macchina)
| Modello | Livello | Perché | Visibilità |
|---|---|---|---|
| `deepseek/deepseek-v4-pro` | Built-in Pi | API pubblica nota, già nella build | Tutti i progetti |
| `zai/glm-5.2` | `~/.pi/agent/models.json` | Endpoint OpenAI-compatible custom (z.ai), nessuna logica speciale | Tutti i progetti |
| `aritmolab/qwen3.6-35b-a3b` | Estensione di progetto | Endpoint interno ospedaliero + conversione eventi thinking→text custom | Solo ThothII (cwd=`harness/`) |
| `zai/glm-5.3` | `deploy/pi/models.json` | Endpoint OpenAI-compatible custom | Installazione ThothII |
| `local-qwen/qwen3.6-35b-a3b` | `deploy/pi/models.json` | Endpoint OpenAI-compatible configurato localmente | Installazione ThothII |
## Come scegliere il livello giusto per un nuovo modello
1. **L'endpoint è un'API pubblica già nota a Pi?** → niente da fare, verifica con `pi --list-models`.
2. **È OpenAI-compatible, nessuna logica custom, e deve essere visibile ovunque?** → `~/.pi/agent/models.json`.
3. **Serve codice custom (auth non standard, conversione eventi, trasporto non-OpenAI) oppure deve restare visibile a un solo progetto?** → estensione, in `~/.pi/agent/extensions/` (globale) o `<progetto>/.pi/extensions/` (locale).
1. **L'endpoint è un'API pubblica già nota a Pi?** → abilita l'identificatore esatto in `deploy/pi/settings.json`.
2. **È OpenAI-compatible ma non built-in?** → dichiaralo in `deploy/pi/models.json`, poi abilitalo in `deploy/pi/settings.json`.
3. **Richiede codice di trasporto specifico del provider?** → non aggiungere un'estensione specifica; il provider non è supportato finché manca una capacità dichiarativa generica.
---
@@ -126,7 +134,6 @@ Oltre ai modelli, Pi carica altre risorse da due alberi paralleli: `~/.pi/agent/
```
harness/.pi/
├── extensions/
│ ├── aritmolab-provider.js ← provider LLM solo-progetto
│ ├── tht-gate.js ← gate human-in-the-loop
│ └── gate/
│ ├── core/ ← enforcement e utility condivise del gate
@@ -139,19 +146,17 @@ harness/.pi/
### Comportamento rispetto alla cwd
La directory da cui lanci `pi` determina quale `.pi/` di progetto viene trovata:
La directory da cui lanci `pi` determina quali estensioni del workflow vengono trovate, ma non
quali modelli ThothII rende disponibili: il catalogo è montato nel Pi agent directory del container.
```bash
# Da harness/ — trova harness/.pi/extensions/aritmolab-provider.js
# Da harness/ — carica il gate di progetto e il catalogo locale montato
cd /path/to/ThothII/harness
pi --model aritmolab/qwen3.6-35b-a3b "..."
# Dalla radice di ThothII — nessun .pi/ trovato lì o nei genitori, solo config utente
cd /path/to/ThothII
pi --model aritmolab/qwen3.6-35b-a3b "..." # ❌ Error: model not found
pi --model local-qwen/qwen3.6-35b-a3b "..."
```
Il backend di ThothII (`PiProcessManager`, `list-models.ts`, `model-matrix.mjs`) lancia sempre `pi` con `cwd: harnessDir`, per questo Qwen è visibile in produzione.
Il backend di ThothII lancia sempre Pi con `cwd: harnessDir` per il workflow; la disponibilità del
modello continua a dipendere soltanto da `models.json`, `settings.json` e dalle credenziali locali.
---
@@ -177,15 +182,15 @@ Se serve un modulo condiviso importato da un'estensione, usa `.mjs` proprio per
```bash
pi --list-models
```
Mostra i built-in + i modelli utente da `models.json`. **Non mostra** i provider registrati da estensione (come AritmoLab) — quelli vanno verificati con la cwd giusta.
Mostra i built-in e i modelli dichiarati in `models.json`.
### Verifica che un'estensione sia caricata
### Verifica il catalogo usato dall'applicazione
```bash
cd harness # o la cwd rilevante per il progetto
pi --mode rpc
# poi: {"type": "get_available_models", "id": "1"}
```
La risposta RPC include tutti i modelli disponibili, inclusi quelli da estensione.
La risposta RPC deve includere soltanto modelli built-in o dichiarati nel catalogo locale.
---
@@ -193,6 +198,5 @@ La risposta RPC include tutti i modelli disponibili, inclusi quelli da estension
| Problema | Causa | Soluzione |
|---|---|---|
| `Model "X/Y" not found` lanciando da fuori progetto | Il modello è registrato da un'estensione locale, non visibile fuori dalla cwd giusta | Lancia `pi` dalla directory di progetto corretta (es. `harness/`) |
| Estensione non caricata pur essendo nella cartella giusta | File `.mjs` invece di `.js`/`.ts` | Rinomina in `.js` |
| `Model "X/Y" not found` | Provider/modello assente da `models.json` oppure identificatore assente da `enabledModels` | Correggi i due file locali e ricarica Pi |
| Impostazioni di progetto non applicate | `settings.json` di progetto ha errori di sintassi, o si sta lanciando `pi` dalla cwd sbagliata | Valida il JSON, controlla la cwd |