docs: set up MkDocs site with technical/general docs split
Add mkdocs.yml (windmill theme, mermaid2, matching ~/Chirone/chirone/etl setup) with nav split into "ThothII (Documentazione Tecnica)" — architecture overview, existing design specs/plans, reports — and "Considerazioni Generali" for cross-project notes. Add docs/general/pi-configuration.md explaining Pi's three model-resolution tiers (built-in, user models.json, project extension) and where GLM/DeepSeek/ Qwen each sit. Add docs/architecture/overview.md synthesizing the ThothII architecture for the doc site. Relocate the L2 run report into docs/reports/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,149 @@
|
||||
# Configurazione dei modelli in Pi: built-in, utente, progetto
|
||||
|
||||
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).
|
||||
|
||||
## I tre livelli di provenienza di un modello
|
||||
|
||||
### 1. Built-in (compilato dentro Pi)
|
||||
|
||||
Pi viene distribuito con un elenco di modelli già noti (`models.generated.js` dentro il pacchetto `@mariozechner/pi-ai`): Anthropic, OpenAI, Google, e anche provider di terze parti con API pubblica ben nota come DeepSeek. Per questi **non serve alcuna configurazione**: bastano le credenziali (env var o `pi auth`).
|
||||
|
||||
`deepseek/deepseek-v4-pro` è così: è nella build di Pi perché `api.deepseek.com` è un'API pubblica documentata, non un endpoint interno.
|
||||
|
||||
### 2. `models.json` a livello utente (`~/.pi/agent/models.json`)
|
||||
|
||||
Per un endpoint **OpenAI-compatible** che non è tra i built-in — ma che non richiede nessuna logica di trasporto speciale — basta *dichiararlo*: baseUrl, apiKey, lista modelli. Questo file esiste **solo a livello utente**: non c'è un equivalente project-level (un `./.pi/models.json` non viene letto).
|
||||
|
||||
Esempio reale in uso su questa macchina — GLM (provider `zai`):
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"zai": {
|
||||
"baseUrl": "https://api.z.ai/api/coding/paas/v4",
|
||||
"api": "openai-completions",
|
||||
"apiKey": "$ZAI_API_KEY",
|
||||
"models": [
|
||||
{
|
||||
"id": "glm-5.2",
|
||||
"name": "GLM-5.2",
|
||||
"reasoning": true,
|
||||
"contextWindow": 200000,
|
||||
"maxTokens": 131072
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Essendo a livello utente, GLM è visibile da **qualsiasi progetto**.
|
||||
|
||||
### 3. Estensione (`.pi/extensions/*.js`, utente o progetto)
|
||||
|
||||
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).
|
||||
|
||||
## 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/`) |
|
||||
|
||||
## 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).
|
||||
|
||||
---
|
||||
|
||||
## Ambito utente vs. progetto — riepilogo generale
|
||||
|
||||
Oltre ai modelli, Pi carica altre risorse da due alberi paralleli: `~/.pi/agent/` (utente) e `<cwd>/.pi/` (progetto, risolto in base alla directory da cui viene lanciato `pi`).
|
||||
|
||||
| File/Directory | Livello utente | Livello progetto | Auto-discovery | Precedenza |
|
||||
|---|---|---|---|---|
|
||||
| `models.json` | `~/.pi/agent/models.json` | non supportato | no | solo utente |
|
||||
| `settings.json` | `~/.pi/agent/settings.json` | `./.pi/settings.json` | no | progetto sovrascrive utente |
|
||||
| `extensions/` | `~/.pi/agent/extensions/` | `./.pi/extensions/` | sì (`.ts`/`.js`) | uniti (progetto + utente) |
|
||||
| `prompts/` | `~/.pi/agent/prompts/` | `./.pi/prompts/` | sì (`.md`) | uniti |
|
||||
| `themes/` | `~/.pi/agent/themes/` | `./.pi/themes/` | sì (`.json`) | progetto preferito |
|
||||
| `skills/` | `~/.pi/agent/skills/` | `./.pi/skills/` | sì (`.md`) | uniti |
|
||||
|
||||
### Esempio reale: ThothII
|
||||
|
||||
```
|
||||
harness/.pi/
|
||||
├── extensions/
|
||||
│ ├── aritmolab-provider.js ← provider LLM solo-progetto
|
||||
│ ├── tht-gate.js ← gate human-in-the-loop
|
||||
│ ├── reserved-labels.mjs ← utility condivisa (NON auto-caricata; .mjs ignorato)
|
||||
│ └── gate/ ← modulo usato da tht-gate.js
|
||||
├── settings.json ← (opzionale) override delle impostazioni utente
|
||||
└── themes/
|
||||
└── thothii-mono.json ← tema del progetto
|
||||
```
|
||||
|
||||
### Comportamento rispetto alla cwd
|
||||
|
||||
La directory da cui lanci `pi` determina quale `.pi/` di progetto viene trovata:
|
||||
|
||||
```bash
|
||||
# Da harness/ — trova harness/.pi/extensions/aritmolab-provider.js
|
||||
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
|
||||
```
|
||||
|
||||
Il backend di ThothII (`PiProcessManager`, `list-models.ts`, `model-matrix.mjs`) lancia sempre `pi` con `cwd: harnessDir`, per questo Qwen è visibile in produzione.
|
||||
|
||||
---
|
||||
|
||||
## Trappola nell'auto-discovery: `.mjs` viene ignorato
|
||||
|
||||
Il pattern di auto-discovery delle estensioni in Pi è **`/\.(ts|js)$/`** — non include `.mjs`.
|
||||
|
||||
```
|
||||
.pi/extensions/
|
||||
├── my-extension.js ✅ auto-caricata
|
||||
├── my-extension.ts ✅ auto-caricata
|
||||
├── my-extension.mjs ❌ ignorata silenziosamente (non combacia col pattern)
|
||||
└── shared-module.mjs ✅ va bene per moduli helper (deliberatamente non caricato come estensione)
|
||||
```
|
||||
|
||||
Se serve un modulo condiviso importato da un'estensione, usa `.mjs` proprio per evitare che venga trattato come estensione a sé.
|
||||
|
||||
---
|
||||
|
||||
## Verifica
|
||||
|
||||
### Elenco modelli
|
||||
```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.
|
||||
|
||||
### Verifica che un'estensione sia caricata
|
||||
```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.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| 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` |
|
||||
| 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 |
|
||||
Reference in New Issue
Block a user