Evals, Red Teaming e generazione di test per sistemi agentici

Modulare, leggero, dinamico e async-first

Documentazione • Sito web • Community

[!IMPORTANT] Giskard v3 è una riscrittura completa pensata per test dinamici multi-turno degli agenti AI. Questa versione 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 inclusi nativamente in giskard-scan (beta), senza dipendenza dalla v2. Solo la scansione legacy per modelli tabulari/ML rimane esclusiva della v2. Giskard v2 rimane disponibile ma non è più mantenuta attivamente. Segui i progressi → Leggi l'annuncio della v3 · Roadmap

Installazione

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+.

Telemetria: analisi aggregate opzionali tramite giskard-core. Nessun prompt o output viene inviato. Per disattivare prima di importare Giskard: export DO_NOT_TRACK=1 oppure export GISKARD_TELEMETRY_DISABLED=1. Dettagli: giskard-core README.

Giskard è una libreria Python open-source per testare e valutare sistemi agentici. L'architettura v3 è un insieme modulare di pacchetti focalizzati — 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.

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 installate automaticamente e raramente usate direttamente.

Giskard Checks — creare e applicare eval per testare gli agenti

pip install giskard-checks

Giskard Checks è una libreria leggera per creare valutazioni (eval) che testano sistemi basati su LLM — dalle semplici asserzioni alle valutazioni LLM-as-judge. A differenza dei test unitari tradizionali, gli eval sono progettati per output non deterministici, dove lo stesso input può produrre diverse risposte valide.

Usa Giskard Checks per:

• Individuare regressioni — verifica che il tuo sistema continui a comportarsi correttamente dopo le modifiche
• Validare la qualità RAG — verifica se le risposte sono fondate sul contesto recuperato
• Applicare regole di sicurezza — assicurati che gli output rispettino le tue policy sui contenuti
• Valutare agenti multi-turno — testa conversazioni complete, non solo singoli scambi

Gli eval integrati includono corrispondenza di stringhe, confronti, regex, similarità semantica e check LLM-as-judge (Groundedness, Conformity, LLMJudge).

Concetti

• Target — il tuo sistema sotto test: qualsiasi callable sincrona/asincrona (inputs) -> outputs (opzionalmente con trace)
• Scenario — un eval: interazioni + check
• Check — asserzione o giudice LLM sul trace
• Suite — molti scenari eseguiti insieme

giskard.agents.Generator è un client LLM per workflow/giudici — non è la stessa cosa dei generatori di input di giskard.checks (LLMGenerator) che sintetizzano messaggi utente.

Avvio rapido

import asyncio
from giskard.checks import Scenario, Groundedness


def get_answer(inputs: str) -> str:
    return "Paris"  # replace with your model / agent


async def main() -> None:
    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 = await scenario.run()
    result.print_report()


asyncio.run(main())

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 per Suites, LLMJudge, scenari multi-turno e altro.

Giskard Scan — scanner di vulnerabilità per agenti AI

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 adversariali a partire da una descrizione in linguaggio semplice del tuo agente, coprendo prompt injection, contenuti dannosi, stereotipi, disinformazione e altro.

Usa Giskard Scan per:

• Sottoporre il tuo agente a red-teaming — genera automaticamente input adversariali nelle categorie di minaccia OWASP LLM Top-10
• Eseguire probe di prompt injection — dataset integrato di payload di injection pronto all'uso
• Estendere con generatori personalizzati — passa le tue istanze di ScenarioGenerator a generate_suite, oppure registrale su vulnerability_suite_generator_registry

Avvio rapido

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 richiedono un extra provider LLM e 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 test set per la valutazione RAG).

Per agenti LLM, entrambi sono sostituiti in v3 da giskard-scan: usa vulnerability_scan al posto della scan LLM della v2, e quality_scan (con KnowledgeBase) al posto di RAGET.

La v3 funziona anche con modelli ML — avvolgine uno come target e valutalo con giskard-checks o giskard-scan. Ciò che gli esempi seguenti coprono è la scansione tabulare automatica esclusiva della v2 — la suite di detector che analizza internamente un giskard.Model + giskard.Dataset per rilevare automaticamente problemi di performance, bias e robustezza — insieme alla suite di test ML giskard.testing e a Giskard Hub. Queste non sono previste per la v3.

pip install "giskard[llm]>2,<3"

Scan — rileva automaticamente performance, bias e problemi di sicurezza

Avvolgi il tuo modello ed esegui la scansione:

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)

RAGET — genera dataset di valutazione per applicazioni RAG

Genera automaticamente domande, risposte di riferimento e contesto dalla tua knowledge base:

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",
)

Documentazione completa della v2

👋 Comunità

Diamo il benvenuto ai contributi della community AI! Leggi questa guida per iniziare e unisciti alla nostra vivace community su Discord.

Segui i progressi e condividi feedback: Annuncio della v3 · Roadmap

🌟 Lasciaci una stella, aiuta il progetto a farsi scoprire da altri e ci mantiene motivati a costruire fantastici strumenti open-source! 🌟

❤️ Se trovi utile il nostro lavoro, considera di sostenerci su GitHub. Con una sponsorizzazione mensile puoi ottenere un badge di sponsor, mostrare la tua azienda in questo readme e dare priorità alle tue segnalazioni di bug. Offriamo anche sponsorizzazioni una tantum se vuoi che ci coinvolgiamo in un progetto di consulenza, teniamo un workshop o facciamo un talk presso la tua azienda.