Developer Hub · schema diber-evaluation-v0.9.0

Integra, prova e audita DIBER Core.

Playground interattivo, installazione, CLI, API Reference, contratti JSON, formule delle metriche, statistiche su run ripetute, metodologia dei confronti e schema completo del report. Tutto in una singola reference tecnica.

Apri il Core Tester Esplora un report visuale

Deterministic

Stesso input e stessa configurazione producono lo stesso calcolo.

No AI judge

Il Core calcola su classificazioni e ground truth strutturate.

Run-aware

Aggregazioni, deviazione standard e intervalli per configurazioni identiche.

Auditable

Metriche, denominatori, transizioni e relazioni restano ispezionabili.

Live Core Tester

Esegui il motore direttamente nel browser.

L'esempio predefinito include due configurazioni, run ripetute, documenti di contesto, relazioni e dati comportamentali. Puoi sostituirlo con i tuoi JSON e ispezionare sia la sintesi sia il report completo.

1. ground_truth.json

2. evaluations.json

Premi Run Engine per calcolare il report.

3. report.json

Workflow mentale del Core

DIBER separa il contratto del test, le osservazioni point-by-point e il calcolo. Questo evita che la metrica nasconda come è stato costruito il giudizio di base.

Ground Truth

Punti materiali, importanza, documenti sorgente e relazioni semantiche.

Runs

Modello, prompt, documenti realmente disponibili e metadati comportamentali.

Evaluations

Per ogni punto: coverage + status, più eventuale assessment dell'input.

Report

Metriche, gruppi identici, confronti, transizioni e matrice model/prompt.

NPM & Quickstart

Il contratto mostrato in questa pagina è pensato per una libreria JavaScript/Node.js integrabile in backend e test suite.

npm install @anonipro/diber-core

import { buildExperimentReport, CB_CONFIG } from '@anonipro/diber-core';

const report = buildExperimentReport({
  experiment,
  groundTruth,
  evaluations
});

console.log(report.runs[0].metrics.effective_information);

Configurazione runtime

CB_CONFIG è esposto per consentire override espliciti dei pesi. Se cambi i pesi, versiona anche la configurazione del test per mantenere la confrontabilità.

CLI e quality gate CI/CD

Genera un report deterministico e applica soglie esplicite. La pipeline decide in base a numeri e regole dichiarate, non a un secondo modello.

# Generazione report standard
npx diber evaluate --truth ./tests/gt.json --evals ./tests/runs.json --out ./report.json

# Generazione con opzioni avanzate di comparazione (v0.9.0+)
npx diber evaluate --truth ./tests/gt.json --evals ./tests/runs.json --max-comparisons 500 --max-scanned-pairs 5000 --include-multidimensional --out ./report.json

# Quality gate deterministico
npx diber assert --max-hallucination 0.02 --max-math-error 0.0 --max-extra-hallucination-penalty 0.5 --min-quality 0.90 ./report.json

import { readFileSync } from 'node:fs';

const report = JSON.parse(readFileSync('./report.json', 'utf8'));
const latest = report.runs.at(-1);

if (!latest?.valid) throw new Error('DIBER: run non valida');

// gt_hallucination_rate sostituisce la legacy hallucination_rate a partire da v0.9.0
if (latest.metrics.gt_hallucination_rate > 0.02) {
  throw new Error('DIBER gate: gt_hallucination_rate > 2%');
}
if (latest.metrics.math_error_rate > 0.0) {
  throw new Error('DIBER gate: math_error_rate > 0');
}
if (latest.metrics.addressed_quality < 0.90) {
  throw new Error('DIBER gate: addressed_quality < 90%');
}

API Reference

Superficie principale del Core rappresentata nel materiale v0.9.0.

buildExperimentReport({ experiment, groundTruth, evaluations })

Report completo

Valuta le run, costruisce gruppi per configurazione identica, comparisons, transizioni point-by-point e model/prompt matrix.

evaluateExperiment({ experiment, groundTruth, evaluations })

Valutazione delle run

Restituisce run valide/non valide e le metriche primitive/derivate per ogni esecuzione.

calculateRunMetrics({ run, groundTruth, evaluation })

Singola run

Normalizza le evaluations, calcola metriche, counts, relazioni, availability e conserva gli assessment associati.

CB_CONFIG

Configurazione

Dizionari supportati, pesi di importanza e score numerici usati dal calcolo.

Schema: Ground Truth

Definisce il perimetro materiale del test. Il Core indicizza i punti tramite point_id.

Campo	Tipo	Req.	Descrizione
points	Array<Object>	Sì	Elenco dei punti materiali che possono essere valutati.
points[].point_id	String	Sì	ID univoco. Deve corrispondere a quello usato nelle evaluations.
points[].importance	String	No	`Critical`, `High`, `Medium`, `Low`. Se assente usa il peso `undefined`.
points[].weight	Number	No	Override numerico del peso derivato da `importance`.
points[].source_document_id	String	No	Collega il punto al documento sorgente per calcolare `available_to_model`.
relations	Array<Object>	No	Relazioni semantiche/logiche tra punti.
relations[].source_point_id	String	Sì*	Punto sorgente della relazione.
relations[].target_point_id	String	Sì*	Punto destinazione della relazione.
relations[].type	String	Sì*	`depends_on`, `supports`, `contradicts`. *Richiesto se la relation è presente.

{
  "points": [
    { "point_id": "PT-001", "importance": "Critical", "source_document_id": "DOC-A" },
    { "point_id": "PT-002", "importance": "High",     "source_document_id": "DOC-B" },
    { "point_id": "PT-003", "importance": "Medium" }
  ],
  "relations": [
    { "source_point_id": "PT-001", "target_point_id": "PT-002", "type": "depends_on" }
  ]
}

Schema: Experiment / Runs

Descrive il batch e le condizioni operative di ogni esecuzione.

Campo	Tipo	Req.	Uso
experiment_id	String	No	ID del batch. Se assente il report usa `null`.
runs	Array<Object>	Sì	Elenco delle esecuzioni. Il Core richiede che sia un array.
runs[].run_id	String	Sì	Chiave usata per recuperare `evaluations[run_id]`.
runs[].model_id	String	No	Usato in aggregazioni, confronti e matrice model/prompt.
runs[].prompt_id	String	No	Usato in aggregazioni, confronti e matrice model/prompt.
runs[].context_document_ids	Array<String>	No	Documenti effettivamente disponibili alla run; alimenta `available_to_model`.
runs[].behavioral_test	Object	No	Dimensioni comportamentali numeriche e/o transizioni osservate.

Schema: Evaluations

Dizionario indicizzato per run_id. Ogni voce contiene l'eventuale assessment dell'input e le classificazioni point-by-point.

Campo	Tipo	Req.	Descrizione
evaluations[run_id]	Object	Sì*	Richiesto affinché la run venga processata; una run senza entry viene saltata.
input_data_assessment	Object	No	Metadati sull'input, ad esempio `overall_exposure`, presenza di dati sensibili o note di contesto.
evaluations	Array<Object>	Sì	Array delle classificazioni.
evaluations[].point_id	String	Sì	Deve corrispondere a un punto della Ground Truth; gli ID sconosciuti producono warning.
evaluations[].coverage	String	No	Se assente viene normalizzato a `unrated`.
evaluations[].status	String	No	Se assente viene normalizzato a `unrated`.
extra_claims	Array<Object>	No	Affermazioni non richieste dal Ground Truth aggiunte dal modello.
extra_claims[].status	String	Sì*	Stato del claim extra: `hallu`, `over`, `error`.
extra_claims[].weight	Number	No	Peso dell'affermazione extra per il calcolo della penalità.

{
  "experiment": {
    "experiment_id": "EXP-001",
    "runs": [
      {
        "run_id": "run-01",
        "model_id": "model-a",
        "prompt_id": "prompt-v1",
        "context_document_ids": ["DOC-A", "DOC-B"],
        "behavioral_test": { "tone_adaptation_rate": 0.80 }
      }
    ]
  },
  "evaluations": {
    "run-01": {
      "input_data_assessment": { "overall_exposure": "low", "personal_data": true },
      "evaluations": [
        { "point_id": "PT-001", "coverage": "addressed", "status": "correct" }
      ],
      "extra_claims": [
        { "status": "hallu", "weight": 1.0, "excerpt": "Dato inventato non richiesto" }
      ]
    }
  }
}

Dizionario Coverage / Status

Coverage risponde a “il punto era/è stato trattato?”, Status a “come è stato trattato?”. Le due dimensioni non sono intercambiabili.

Coverage

addressed — punto materialmente affrontato.
should — necessario ma omesso.
gap — mancanza informativa riconosciuta.
out_context — sorgente non disponibile alla run.
not_relevant — sorgente disponibile ma punto non necessario.
unrated — non classificato.

Status / score

correct → 1.00
partial → 0.50
inference → 0.25
over → 0.25
error, math_error, hallu, omission → 0.00
missing → 1.00
na, unrated → null

Regola di contesto

Nel playground v0.9.0, se una run dichiara context_document_ids, un punto con source_document_id assente da quel contesto viene marcato available_to_model: false. Se era stato indicato come addressed, la normalizzazione lo porta a out_context.

Metriche & denominatori

Le metriche non sono etichette opache: il denominatore è parte del significato. Qui sono riportate le formule implementate nel Core Tester.

coverage_raw

addressed_count / (addressed_count + should_count)

Copertura non pesata dei punti materialmente rilevanti.

coverage_weighted

Σ weight(addressed) / Σ weight(addressed + should)

Dà più impatto ai punti con peso maggiore.

addressed_quality

Σ statusScore × weight / Σ weight, solo coverage=addressed

Misura la qualità di ciò che la risposta ha effettivamente affrontato.

usable_information

Σ weight(correct | partial) / Σ weight(addressed)

Quota pesata degli addressed classificati correct o partial.

effective_information

Σ addressed(weight × statusScore) / Σ weight(addressed + should)

Combina copertura e qualità in un'unica misura effettiva.

defect rates

Σ weight(defect matching coverage) / Σ weight(addressed + should)

gt_hallucination_rate, error_rate, math_error_rate usano difetti su coverage addressed; omission_rate usa coverage should.

relation_consistency

consistent_relations / total_relations

Null se non ci sono relazioni valutabili.

Null non significa zero

Quando il denominatore non esiste o una dimensione non è applicabile, il Core restituisce null. Questo evita di trasformare “non misurabile” in “prestazione zero”.

Relazioni logiche

Le relazioni consentono di controllare la coerenza strutturale tra premesse e conclusioni, non solo lo status isolato dei punti.

depends_on

Dipendenza

Nel Core v0.9.0 una target correct è incoerente se la source è error, hallu, omission o missing.

supports

Supporto

Una relazione è incoerente quando la source è hallu.

contradicts

Contraddizione

Il tipo è ammesso dallo schema. Nel Core Tester fornito non introduce ancora una regola aggiuntiva oltre al tracciamento della relazione.

Context availability & Input Exposure

DIBER distingue ciò che era materialmente richiesto da ciò che era effettivamente disponibile al modello.

available_to_model

Il punto può dichiarare source_document_id.
La run può dichiarare context_document_ids.
Se il documento sorgente non compare nel contesto della run, available_to_model=false.
Questo dato viene conservato in normalized_evaluations.

input_data_assessment

È un oggetto opzionale legato alla singola evaluation/run.
Genera il nuovo input_profile per tracciare overall_exposure, personal_data, special_category_data e confidential_data.
Il Core lo conserva nel report per policy di data security.

Repeated runs & statistiche aggregate

Le run con stessa combinazione di modello, prompt e documenti di contesto vengono raggruppate in groups.exact_configurations.

n

Numero di osservazioni numeriche valide.

mean / min / max

Centro e estremi della metrica.

range / variance / stddev

Dispersione assoluta e statistica.

CI 95%

mean ± 1.96 × stddev / √n, limitato all'intervallo 0–1.

Nota statistica

L'intervallo implementato usa l'approssimazione normale 1.96. Con campioni molto piccoli va interpretato come indicatore operativo, non come sostituto di una metodologia inferenziale più sofisticata.

A/B methodology audit

Prima di leggere un delta, DIBER rende esplicito che cosa è cambiato tra le due run.

replication

0 variabili cambiate

Stessa configurazione. È utile per misurare la variabilità tra run.

strictly_controlled

1 variabile cambiata

Confronto controllato: cambia solo modello, prompt oppure set di documenti.

multidimensional

2+ variabili cambiate

Il delta resta calcolabile, ma non va attribuito causalmente a una singola modifica.

Variabili tracciate nel Core Tester

model, prompt, context_documents. Ogni comparison include inoltre metric_deltas, conteggi delle status_transitions e transizioni point-by-point.

Model / Prompt Matrix

Il report raggruppa le run per combinazione model_id + prompt_id e calcola le stesse statistiche delle metriche numeriche.

model_prompt_matrix: [
  {
    key: "model-a__prompt-v2",
    model_id: "model-a",
    prompt_id: "prompt-v2",
    run_count: 5,
    metrics: {
      effective_information: { n, mean, min, max, range, variance, stddev, ci_lower, ci_upper },
      ...
    }
  }
]

Behavioral profile

Le run possono portare un oggetto behavioral_test. La pagina aggrega automaticamente le dimensioni numeriche e conta eventuali transizioni categoriali esplicite.

Dimensioni numeriche

Esempi già usati nel materiale: irony_recognition_rate, tone_adaptation_rate. Qualsiasi proprietà numerica viene aggregata con n/mean/min/max/range/variance/stddev/CI.

behavior_transition

Se presente come stringa, viene contato per frequenza nel profilo aggregato. Non viene inferito automaticamente da un LLM.

Principio

Il Core non inventa la semantica di una dimensione comportamentale: aggrega i segnali strutturati forniti dalla tua pipeline di valutazione.

CB_CONFIG completo

Configurazione centrale usata dal Core Tester v0.9.0.

const CB_CONFIG = {
  version: "0.9.0",
  coverage: {
    addressed: true, should: true, gap: true,
    out_context: true, not_relevant: true, unrated: true
  },
  status: {
    correct: true, partial: true, omission: true,
    inference: true, over: true, error: true,
    math_error: true, hallu: true, missing: true,
    na: true, unrated: true
  },
  defaultImportanceWeight: {
    Critical: 2.00,
    High: 1.00,
    Medium: 0.50,
    Low: 0.25,
    undefined: 1.00
  },
  statusScore: {
    correct: 1.00,
    partial: 0.50,
    inference: 0.25,
    over: 0.25,
    error: 0.00,
    math_error: 0.00,
    hallu: 0.00,
    omission: 0.00,
    missing: 1.00,
    na: null,
    unrated: null
  },
  coverageScore: {
    addressed: 1.00,
    should: 0.00,
    gap: null,
    out_context: null,
    not_relevant: null,
    unrated: null
  }
};

Validation, errori e warning

La validazione distingue errori che impediscono la run da warning che segnalano incongruenze ma lasciano il dato ispezionabile.

Errori

evaluation_missing
ground_truth_missing
evaluations_not_array
ground_truth_points_not_array
point_id_missing
experiment.runs deve essere un array (eccezione a livello esperimento)

Warning

unknown_point:<id>
unknown_coverage:<value>
unknown_status:<value>

Run senza evaluations

Nel flusso v0.9.0 una run presente in experiment.runs ma senza evaluations[run_id] viene ignorata durante evaluateExperiment; non viene trasformata automaticamente in una run invalida.

Report output: diber-evaluation-v0.9.0

Struttura completa prodotta dal Core Tester incluso in questa pagina.

Top level

schema, deterministic, ai_judge
experiment_id, run_count
runs
groups.exact_configurations
comparisons
model_prompt_matrix
behavioral_profile
input_exposure_summary

Per run

valid + validation
metrics
counts.coverage + counts.status
relations
normalized_evaluations
input_data_assessment
behavioral_test
context_document_ids

{
  "schema": "diber-evaluation-v0.9.0",
  "deterministic": true,
  "ai_judge": false,
  "experiment_id": "EXP-DEMO-01",
  "run_count": 4,
  "runs": [ ... ],
  "groups": { "exact_configurations": { ... } },
  "comparisons": [
    {
      "run_a": "baseline-01",
      "run_b": "candidate-01",
      "methodology": {
        "changed_variables": ["prompt"],
        "comparison_type": "strictly_controlled",
        "is_valid_controlled": true
      },
      "metric_deltas": { ... },
      "status_transitions": { ... },
      "point_transitions": [ ... ]
    }
  ],
  "model_prompt_matrix": [ ... ],
  "behavioral_profile": { ... },
  "input_exposure_summary": { ... }
}

Vedi questo modello come report visuale →DIBERA Free →