190 lines
11 KiB
Markdown
190 lines
11 KiB
Markdown
# Evidence: sorgenti, preparazione e revisione
|
|
|
|
Questa pagina descrive il ciclo completo delle Evidence di workspace: dove si trova il materiale originale, come si producono le unità curate, quando diventano disponibili al runtime e quali responsabilità hanno autore e revisore.
|
|
|
|
## Regola di pubblicazione
|
|
|
|
Il workspace repository è la sorgente versionata. ThothII lo legge, lo valida e pubblica una generazione atomica. Non modifica, committa o pusha il repository dell'autore.
|
|
|
|
Una Evidence diventa utilizzabile dal workflow solo quando:
|
|
|
|
1. il materiale originale è presente in `source/`;
|
|
2. l'unità derivata è presente in `curated/`;
|
|
3. il manifest collega unità, sorgente e hash;
|
|
4. la validazione non produce errori o review item irrisolti;
|
|
5. la pipeline di preprocessing costruisce una generazione indicizzata e la attiva.
|
|
|
|
Una proposta generata durante una sessione non è automaticamente Evidence pubblicata. Il modello può proporre una formula o una spiegazione, ma un curatore deve importarla, revisionarla e pubblicarla nel repository prima che un'altra sessione possa recuperarla.
|
|
|
|
## Dove deve stare il primo sorgente
|
|
|
|
Per il filesystem Evidence v2, il primo sorgente autorevole deve stare nella directory `source/` del repository di workspace. `curated/` contiene il risultato revisionato e indicizzato, non il materiale originale.
|
|
|
|
```text
|
|
<workspace-repository>/
|
|
├── source/ # materiale originale, preservato
|
|
│ └── <dominio>/<file>.md
|
|
├── curated/ # Evidence Units revisionate
|
|
│ └── <dominio>/<unit>.md
|
|
├── manifest.yaml # legami, hash e metadati della preparazione
|
|
├── evaluation/ # fixture di valutazione del recupero
|
|
└── example/ # esempi e materiale di supporto
|
|
```
|
|
|
|
Il descriptor del workspace deve dichiarare `evidence.schema_version: 2` e, per una sorgente filesystem, usare esattamente:
|
|
|
|
```yaml
|
|
evidence:
|
|
schema_version: 2
|
|
source:
|
|
type: filesystem
|
|
uri: "<workspace.id>/evidence"
|
|
patterns:
|
|
- "curated/**/*.md"
|
|
```
|
|
|
|
La configurazione storica può esporre `source_root`, per esempio `${THT_DOCS_ROOT}` o `/data`. Per la struttura v2 il pattern runtime deve selezionare solo `curated/**/*.md`. Non bisogna indicizzare direttamente `source/`, mescolare `source/` e `curated/`, usare glob più ampi o includere file non Markdown.
|
|
|
|
HTTP e S3 sono adapter distinti. Non usano la struttura filesystem `source/` e `curated/`, ma devono comunque fornire una provenienza stabile, senza credenziali negli URI e con il contratto specifico dell'adapter.
|
|
|
|
## Come deve essere fatta un'unità curata
|
|
|
|
Le unità Markdown lette dal loader storico della CLI hanno frontmatter YAML. I campi minimi sono `id` e `title`; `tier`, `status`, `sources`, `tables`, `concepts` descrivono il contesto dell'unità.
|
|
|
|
```markdown
|
|
---
|
|
id: evidence:fascia-pediatrica
|
|
title: Fascia pediatrica
|
|
tier: structural
|
|
status: reviewed
|
|
sources:
|
|
- source/domain/patient.md
|
|
tables:
|
|
- patient
|
|
concepts:
|
|
- concept:patient-age
|
|
---
|
|
|
|
Definizione verificata della fascia pediatrica.
|
|
|
|
La regola deve essere abbastanza atomica da poter essere citata senza ricostruire
|
|
un intero capitolo. Il testo deve distinguere definizione, condizioni e limiti.
|
|
```
|
|
|
|
Le unità curate devono essere atomiche, leggibili da un secondo revisore e sostenute dal sorgente. I riferimenti di provenienza devono permettere di risalire al file originale e alla porzione che supporta l'affermazione. Non inserire segreti, token, password o credenziali nei metadati o negli URI.
|
|
|
|
La forma canonica moderna conserva anche il tipo di Evidence, la provenienza, gli estratti di supporto, `source_file` e `source_sha256`. Il contratto canonico rifiuta campi sconosciuti, metadati mutabili e URI con credenziali. Gli identificatori devono restare stabili anche quando cambia il tipo di unità.
|
|
|
|
## Preparazione: dal sorgente alla generazione attiva
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
SRC["source/<dominio>/*.md\nmateriale originale"] --> PREP["tht evidence prepare\npreparazione candidata"]
|
|
PREP --> CAND["curated/<dominio>/*.md\nunità proposte o aggiornate"]
|
|
CAND --> VAL["tht evidence validate\ncontrolli di struttura e legami"]
|
|
VAL -->|errori o review item| FIX["Correzioni dell'autore\ne revisione"]
|
|
FIX --> PREP
|
|
VAL -->|publishable| COMMIT["Commit del repository\nauthoring clone"]
|
|
COMMIT --> ING["tht preprocess evidence\nnormalizzazione e chunking"]
|
|
ING --> BM25["Indice BM25"]
|
|
ING --> VEC["Embedding e vector store"]
|
|
BM25 --> GEN["Generazione candidata"]
|
|
VEC --> GEN
|
|
GEN --> EVAL["tht evidence evaluate\nfixture di retrieval"]
|
|
EVAL -->|pass| ACT["Generazione attiva"]
|
|
EVAL -->|fail| FIX
|
|
ACT --> RUNTIME["Ricerca Evidence nel workflow"]
|
|
```
|
|
|
|
La preparazione può ristrutturare sorgenti cambiate, ma non pubblica da sola. `prepare` produce una proposta e può indicare il file sorgente coinvolto in caso di errore. `validate` non scrive né pubblica. Il commit è un'azione del curatore nel clone di authoring. Il runtime legge una revisione completa e validata, poi la pipeline crea una generazione versionata. L'attivazione è atomica: una generazione precedente resta disponibile secondo la policy di retention.
|
|
|
|
La ricerca runtime usa il recupero ibrido. Il ramo denso usa gli embedding, il ramo BM25 usa la ricerca lessicale e la fusione deterministica ordina i risultati. L'unità pubblicata conserva la provenienza, che il modello deve citare quando usa l'evidence.
|
|
|
|
## Responsabilità del creatore
|
|
|
|
Il creatore prepara il materiale e rende verificabile ogni unità. In pratica deve:
|
|
|
|
- mettere il materiale originale in `source/`, senza sovrascriverne il significato durante la curatela;
|
|
- suddividere il contenuto in unità atomiche, una regola o definizione per unità quando possibile;
|
|
- assegnare un identificatore stabile e un titolo comprensibile;
|
|
- indicare la provenienza, le tabelle e i concetti coinvolti quando sono noti;
|
|
- mantenere il testo nella lingua del workspace;
|
|
- separare fatti, regole, esempi, formule e limiti;
|
|
- riportare gli estratti che sostengono l'unità, senza estendere la conclusione oltre il sorgente;
|
|
- eseguire `tht evidence prepare` e `tht evidence validate`;
|
|
- risolvere ogni errore e ogni review item prima di proporre il commit;
|
|
- fornire al revisore il contesto necessario, inclusi i cambiamenti nel sorgente e il motivo di eventuali rinomini o ritiri.
|
|
|
|
Il creatore non deve:
|
|
|
|
- scrivere direttamente nel corpus attivo di produzione;
|
|
- trattare una proposta del modello come fatto verificato;
|
|
- eliminare un'unità solo perché non è più supportata senza registrare il ritiro o il relink;
|
|
- inserire credenziali nei metadati, nei file o negli URL di provenienza;
|
|
- modificare manualmente manifest, hash o generazioni per far passare la validazione.
|
|
|
|
## Responsabilità del revisore
|
|
|
|
Il revisore non approva la forma del testo soltanto perché è chiara. Verifica il rapporto tra sorgente, unità e uso previsto. Per ogni unità deve controllare:
|
|
|
|
1. che il sorgente indicato esista nella revisione esaminata;
|
|
2. che l'estratto sostenga davvero l'affermazione;
|
|
3. che l'unità non unisca regole incompatibili o concetti indipendenti;
|
|
4. che tabelle, colonne e concetti siano identificati correttamente;
|
|
5. che l'identificatore sia stabile e non duplichi un'altra unità;
|
|
6. che il testo distingua definizione, condizione, eccezione ed esempio;
|
|
7. che non contenga informazioni sensibili o dettagli non presenti nel sorgente;
|
|
8. che la valutazione del retrieval copra le query rilevanti e non nasconda risultati vuoti.
|
|
|
|
Il revisore può approvare, chiedere modifiche, rigettare, ritirare o riallacciare un'unità a un nuovo sorgente. Un ritiro deve essere esplicito. Un relink deve indicare il nuovo file e deve lasciare una traccia verificabile della decisione. L'approvazione non comporta la pubblicazione immediata: il repository deve passare la validazione e la generazione deve superare la valutazione prima dell'attivazione.
|
|
|
|
## Comandi disponibili
|
|
|
|
I comandi di authoring operano sul repository di workspace e non pubblicano direttamente.
|
|
|
|
```bash
|
|
# Prepara le sorgenti cambiate. Non committa e non pubblica.
|
|
tht evidence prepare <workspace-root>
|
|
|
|
# Rielabora tutte le sorgenti con la pipeline installata.
|
|
tht evidence prepare <workspace-root> --upgrade
|
|
|
|
# Valida struttura, manifest, legami e review item.
|
|
tht evidence validate <workspace-root>
|
|
|
|
# Restituisce JSON per CI o strumenti automatici.
|
|
tht evidence validate <workspace-root> --json
|
|
|
|
# Valuta il retrieval su una generazione o sulla generazione attiva.
|
|
tht evidence evaluate <workspace-root> --config <workspace-config>
|
|
tht evidence evaluate <workspace-root> --config <workspace-config> --generation <id> --json
|
|
|
|
# Risolve una unità senza pubblicare: ritiro oppure nuovo collegamento al sorgente.
|
|
tht evidence resolve <workspace-root> evidence:<id> --retire
|
|
tht evidence resolve <workspace-root> evidence:<id> --source source/domain/nuovo.md
|
|
|
|
# Materializza e indicizza una generazione versionata.
|
|
tht preprocess evidence --config <workspace-config>
|
|
|
|
# Esecuzione a secco e ripresa di un job, quando supportate dalla configurazione.
|
|
tht preprocess evidence --config <workspace-config> --dry-run
|
|
tht preprocess evidence --config <workspace-config> --resume <run-id>
|
|
```
|
|
|
|
`evidence prepare`, `evidence validate` e `evidence resolve` richiedono il path del repository. `preprocess evidence` usa invece la configurazione del workspace, perché deve conoscere embedding, vector store, policy di retention e artifact directory.
|
|
|
|
I codici di uscita sono parte del contratto operativo: `evidence validate` usa `0` quando il corpus è pubblicabile, `1` per errori di validazione e `3` quando restano solo elementi da revisionare o unità orfane. Con `--json`, stdout deve contenere solo JSON valido.
|
|
|
|
## Formule e proposte di sessione
|
|
|
|
Le formule hanno un formato distinto dalle Evidence documentali. Una formula proposta durante una sessione può essere citata nella proposta corrente, ma non entra nel corpus runtime, non riceve un ID `evidence:` utilizzabile e non scrive nel repository. Per diventare pubblicata deve seguire lo stesso percorso di importazione, revisione e preprocessing delle altre unità.
|
|
|
|
## Riferimenti contrattuali
|
|
|
|
- [Contratto Workspace Evidence v3](contracts/workspace-evidence-v3.md)
|
|
- [Contratto della CLI di preprocessing](contracts/workspace-preprocessing-cli.md)
|
|
- [ADR: confine di pubblicazione](adr/0001-evidence-publication-boundary.md)
|
|
- [ADR: preparazione atomica e ancorata al sorgente](adr/0006-grounded-atomic-evidence-preparation.md)
|
|
- [ADR: valutazione prima dell'attivazione](adr/0003-evaluate-evidence-before-activation.md)
|
|
- [ADR: recupero ibrido deterministico](adr/0008-make-hybrid-evidence-retrieval-deterministic.md)
|