🐢 Libreria open-source di valutazione e testing per agenti LLM
<p align="center">
<img alt="giskardlogo" src="https://assets.kitploit.com/production/public/readmes/50936/c1f328b3f3cefd9e527b0ff1f2991be7d3336ce13cd265993c62b57ce676cab5/a720b322f89a71f208538a57a11e96baef88a9c0bafe7779659f1b4bafcfc27e-display-v1.webp">
<img alt="giskardlogo" src="https://assets.kitploit.com/production/public/readmes/50936/2fd9c4a7c2204d367db301019e2fc0e3de34eacd445004fd705b27cbb7aff5fc/ab0feb5722a650948a83c6cdc420dc43f15ae5e7a8000d26b22fd7effb8f1ca8-display-v1.webp">
</p>
<h1 align="center" weight='300' >Evals, Red Teaming e Generazione di Test per Sistemi Agentici</h1>
<h3 align="center" weight='300' >Modulare, Leggero, Dinamico e Async-first </h3>
<div align="center">
[](https://github.com/Giskard-AI/giskard-oss/releases)
[](https://github.com/Giskard-AI/giskard/blob/main/LICENSE)
[](https://pepy.tech/project/giskard)
[](https://github.com/Giskard-AI/giskard-oss/actions/workflows/ci.yml/badge.svg?branch=main)
[](https://gisk.ar/discord)
<a rel="me" href="https://fosstodon.org/@Giskard"></a>
</div>
<h3 align="center">
<a href="https://docs.giskard.ai/oss"><b>Documentazione</b></a> •
<a href="https://www.giskard.ai/?utm_source=github&utm_medium=github&utm_campaign=github_readme&utm_id=readmeblog"><b>Sito Web</b></a> •
<a href="https://gisk.ar/discord"><b>Community</b></a>
</h3>
<br />
> [!IMPORTANT]
> **Giskard v3** è una riscrittura completa progettata per il testing dinamico e multi-turn degli agenti AI. Questa release elimina le dipendenze pesanti per una maggiore efficienza, introducendo al contempo uno scanner di vulnerabilità AI più potente e una valutazione RAG migliorata — entrambi ora disponibili nativamente in `giskard-scan`, senza alcuna dipendenza da v2. Solo la scansione legacy per **modelli tabellari/ML** rimane esclusiva di v2.
> **Giskard v2 rimane disponibile ma non è più attivamente mantenuto.**
> Segui i progressi → [Leggi l'Annuncio di v3](https://github.com/orgs/Giskard-AI/discussions/2250) · [Roadmap](https://github.com/Giskard-AI/giskard-oss/issues/2252)
## Installazione
```sh
pip install giskard # checks (+ agents, llm, core)
pip install "giskard[scan]" # + vulnerability / quality scan
pip install "giskard[openai]" # provider SDK for LLM judges / generators
```
Richiede Python 3.12+.
| Extra | Aggiunge |
| --- | --- |
| *(nessuno)* | `giskard-checks` e dipendenze |
| `scan` | `giskard-scan` |
| `openai` / `anthropic` / … | SDK dei provider (vedi le dipendenze opzionali in `pyproject.toml`) |
**Telemetria:** analisi aggregate opzionali tramite `giskard-core`. Nessun prompt o output viene inviato.
Disattivala con `export DO_NOT_TRACK=1` o `export GISKARD_TELEMETRY_DISABLED=1` (o le stesse chiavi in un file `.env` nella directory di lavoro). Impostale prima dell'import per evitare la creazione di `~/.giskard/id`; impostarle in seguito interrompe comunque gli invii successivi.
Dettagli: [README di `giskard-core`](https://github.com/giskard-ai/giskard-oss/blob/main/libs/giskard-core/README.md#telemetry).
---
Giskard è una libreria Python open-source per **testare e valutare sistemi agentici**. L'architettura v3 è un insieme modulare di pacchetti mirati — ciascuno con solo le dipendenze di cui ha bisogno — costruita da zero per avvolgere qualsiasi cosa: un LLM, un agente black-box o una pipeline multi-step.
| Stato | Pacchetto | Descrizione |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ✅ Stabile | `giskard-checks` | Testing e valutazione — API di scenario, check integrati, LLM-as-judge |
| ✅ Stabile | `giskard-scan` | Scanner di vulnerabilità per agenti + valutazione RAG/qualità — red teaming, prompt injection, jailbreak e contenuti dannosi (`vulnerability_scan`, successore di [v2 Scan](https://legacy-docs.giskard.ai/en/stable/open_source/scan/index.html)), più valutazione della qualità della knowledge base (`quality_scan`, successore di [v2 RAGET](https://legacy-docs.giskard.ai/en/stable/open_source/testset_generation/index.html)) |
Questi si basano su tre librerie fondamentali — `giskard-core` (utility condivise e telemetria), `giskard-llm` (routing LLM indipendente dal provider) e `giskard-agents` (orchestrazione di agenti e workflow) — che vengono incluse automaticamente e raramente utilizzate direttamente.
## Giskard Checks — crea e applica eval per testare gli agenti
```sh
pip install giskard-checks
```
**[Giskard Checks](https://docs.giskard.ai/oss/checks)** è una libreria leggera per creare valutazioni (eval) che testano sistemi basati su LLM — da semplici asserzioni a valutazioni LLM-as-judge. A differenza dei tradizionali unit test, le eval sono progettate per **output non deterministici**, in cui lo stesso input può produrre risposte valide diverse.
Usa Giskard Checks per:
- **Individuare regressioni** — verificare che il tuo sistema si comporti ancora correttamente dopo le modifiche
- **Validare la qualità del RAG** — controllare se le risposte sono fondate sul contesto recuperato
- **Applicare regole di sicurezza** — assicurarti che gli output siano conformi alle tue politiche sui contenuti
- **Valutare agenti multi-turno** — testare conversazioni complete, non solo singoli scambi
Le eval integrate includono string matching, confronti, regex, similarità semantica e controlli LLM-as-judge (`Groundedness`, `Conformity`, `LLMJudge`).
### Concetti
- **Target** — il tuo sistema sotto test: qualsiasi callable sync/async `(inputs) -> outputs` (opzionalmente con `trace`)
- **Scenario** — una eval: interazioni + controlli
- **Check** — asserzione o giudice LLM sulla trace
- **Suite** — molti scenari eseguiti insieme
`giskard.agents.Generator` è un client LLM per workflow/giudici — non è lo stesso dei
generatori di input di `giskard.checks` (`LLMGenerator`) che sintetizzano messaggi utente.
### Avvio rapido
In uno script senza un event loop in esecuzione:
```python
from giskard.checks import Scenario, Groundedness
def get_answer(inputs: str) -> str:
return "Paris" # replace with your model / agent
scenario = (
Scenario("test_france_capital")
.interact(inputs="What is the capital of France?", outputs=get_answer)
.check(
Groundedness(
name="answer is grounded",
context="France is in Western Europe. Its capital is Paris.",
)
)
)
result = scenario.run_sync()
result.print_report()
```
In una cella di notebook o all'interno di una funzione asincrona, usa invece await sullo scenario:
```python
result = await scenario.run()
result.print_report()
```
`Groundedness` è un giudice LLM — installa un extra del provider (ad es. `pip install "giskard[openai]"`) e imposta la chiave API corrispondente. Modello predefinito: `openai/gpt-4o-mini`.
Consulta la [documentazione completa](https://docs.giskard.ai/oss/checks) per `Suites`, `LLMJudge`, scenari multi-turno e altro ancora.
---
## Giskard Scan — scanner di vulnerabilità per agenti AI
```sh
pip install "giskard[scan]" # or: pip install giskard-scan
```
**Giskard Scan** è il livello di red-teaming e scansione delle vulnerabilità per sistemi agentici. Genera automaticamente suite di test avversariali a partire da una descrizione in linguaggio naturale del tuo agente, coprendo prompt injection, contenuti dannosi, stereotipi, disinformazione e altro ancora.
Usa Giskard Scan per:
- **Fare red-teaming del tuo agente** — genera automaticamente input avversariali attraverso le categorie di minacce OWASP LLM Top-10
- **Eseguire sonde di prompt-injection** — dataset integrato di payload di injection pronti all'uso
- **Estendere con generatori personalizzati** — passa le tue istanze `ScenarioGenerator` a `generate_suite`, oppure registrale su `vulnerability_suite_generator_registry`
### Avvio rapido
```python
import asyncio
from giskard.scan import vulnerability_scan
async def my_agent(inputs: str) -> str:
# Replace with your agent / model call
return f"Echo: {inputs}"
async def main() -> None:
await vulnerability_scan(
target=my_agent,
description="A customer support chatbot for an e-commerce platform.",
languages=["en"],
)
asyncio.run(main())
```
Anche i generatori di scan necessitano di un provider LLM extra e di una chiave API (come per i giudici di Checks sopra).
## Cerchi Giskard v2?
Giskard v2 includeva **Scan** (rilevamento automatico delle vulnerabilità) e **RAGET** (generazione di set di test per la valutazione RAG).
Per gli **agenti LLM**, entrambi sono superati nella v3 da `giskard-scan`: usa [`vulnerability_scan`](#giskard-scan--vulnerability-scanner-for-ai-agents) al posto dello scan LLM di v2, e `quality_scan` (con `KnowledgeBase`) al posto di RAGET.
La v3 funziona anche con i modelli ML — incapsulane uno come target e valutalo con `giskard-checks` o `giskard-scan`. Ciò che coprono gli esempi seguenti è lo **scan tabellare automatico esclusivo della v2** — la suite di rilevatori che analizza un `giskard.Model` + `giskard.Dataset` per rilevare automaticamente problemi di prestazioni, bias e robustezza — insieme alla suite di test ML `giskard.testing` e al Giskard Hub. Questi non sono previsti per la v3.
```sh
pip install "giskard[llm]>2,<3"
```
### [Scan](https://legacy-docs.giskard.ai/en/stable/open_source/scan/index.html) — rileva automaticamente problemi di prestazioni, bias e sicurezza
Avvolgi il tuo modello ed esegui la scansione:
```python
import giskard
import pandas as pd
# Replace my_llm_chain with your actual LLM chain or model inference logic
def model_predict(df: pd.DataFrame):
"""The function takes a DataFrame and must return a list of outputs (one per row)."""
return [my_llm_chain.run({"query": question}) for question in df["question"]]
giskard_model = giskard.Model(
model=model_predict,
model_type="text_generation",
name="My LLM Application",
description="A question answering assistant",
feature_names=["question"],
)
scan_results = giskard.scan(giskard_model)
display(scan_results)
```
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50936/0e863e60ab4173f4812139f38ba772f996644774946dc27aca07ffb1271f5626/9df9e5e47d8be5ce2e756bdd7315613fecc468a1e6096030cbc25d147a50cdf3-display-v1.webp" alt="Esempio di scansione" width="800">
</p>
### [RAGET](https://legacy-docs.giskard.ai/en/stable/open_source/testset_generation/index.html) — genera dataset di valutazione per applicazioni RAG
Genera automaticamente domande, risposte di riferimento e contesto dalla tua knowledge base:
```python
import pandas as pd
from giskard.rag import generate_testset, KnowledgeBase
# Load your knowledge base documents
df = pd.read_csv("path/to/your/knowledge_base.csv")
knowledge_base = KnowledgeBase.from_pandas(df, columns=["column_1", "column_2"])
testset = generate_testset(
knowledge_base,
num_questions=60,
language="en",
agent_description="A customer support chatbot for company X",
)
```
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50936/65cc932276b9d3a86425700b3717748e952a622722b9e129ff43efb0fb91c4d1/1f8abfc8a571f084d70ddfe3c484ad8ecf71d362e52cebfcb8581af12be8c0e9-display-v1.webp" alt="Esempio RAGET" width="800">
</p>
[Documentazione completa v2](https://legacy-docs.giskard.ai)
<h1 id="community">👋 Community</h1>
Accogliamo con favore i contributi della community AI! Leggi questa [guida](https://github.com/giskard-ai/giskard-oss/blob/main/CONTRIBUTING.md) per iniziare e unisciti alla nostra fiorente community su [Discord](https://gisk.ar/discord).
Segui i progressi e condividi il tuo feedback:
[Annuncio v3](https://github.com/orgs/Giskard-AI/discussions/2250) · [Roadmap](https://github.com/Giskard-AI/giskard-oss/issues/2252)
🌟 [Lasciaci una stella](https://github.com/Giskard-AI/giskard), aiuta il progetto a farsi scoprire da altri e ci mantiene motivati a costruire fantastici strumenti open-source! 🌟
❤️ Se trovi utile il nostro lavoro, ti invitiamo a considerare di [sponsorizzarci](https://github.com/sponsors/Giskard-AI) su GitHub. Con una sponsorizzazione mensile, puoi ottenere un badge da sponsor, mostrare la tua azienda in questo readme e ottenere la priorità nella gestione delle tue segnalazioni di bug. Offriamo anche sponsorizzazioni una tantum se desideri coinvolgerci in un progetto di consulenza, condurre un workshop o tenere un intervento presso la tua azienda.