🐢 Biblioteca de código aberto para avaliação e teste de Agentes de 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 Geração de Testes para Sistemas Agênticos</h1>
<h3 align="center" weight='300' >Modular, Leve, Dinâmico 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>Docs</b></a> •
<a href="https://www.giskard.ai/?utm_source=github&utm_medium=github&utm_campaign=github_readme&utm_id=readmeblog"><b>Website</b></a> •
<a href="https://gisk.ar/discord"><b>Community</b></a>
</h3>
<br />
> [!IMPORTANT]
> **Giskard v3** é uma reescrita completa concebida para testes dinâmicos e multi-turno de agentes de IA. Esta versão abandona dependências pesadas para maior eficiência, ao mesmo tempo que introduz um scanner de vulnerabilidades de IA mais poderoso e uma avaliação de RAG aprimorada — ambos agora disponibilizados nativamente em `giskard-scan`, sem dependência da v2. Apenas o scan legado para **modelos tabulares/ML** permanece exclusivo da v2.
> **O Giskard v2 continua disponível, mas já não é mantido ativamente.**
> Acompanhe o progresso → [Leia o Anúncio da v3](https://github.com/orgs/Giskard-AI/discussions/2250) · [Roadmap](https://github.com/Giskard-AI/giskard-oss/issues/2252)
## Instalação
```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
```
Requer Python 3.12+.
| Extra | Adiciona |
| --- | --- |
| *(nenhum)* | `giskard-checks` e dependências |
| `scan` | `giskard-scan` |
| `openai` / `anthropic` / … | SDKs de provedores (consulte as dependências opcionais em `pyproject.toml`) |
**Telemetria:** análise agregada opcional via `giskard-core`. Nenhum prompt ou saída é enviado.
Desative com `export DO_NOT_TRACK=1` ou `export GISKARD_TELEMETRY_DISABLED=1` (ou as mesmas chaves em um arquivo `.env` no diretório de trabalho). Defina-as antes da importação para evitar a criação de `~/.giskard/id`; defini-las depois ainda interrompe envios futuros.
Detalhes: [README do `giskard-core`](https://github.com/giskard-ai/giskard-oss/blob/main/libs/giskard-core/README.md#telemetry).
---
Giskard é uma biblioteca Python de código aberto para **testar e avaliar sistemas agênticos**. A arquitetura v3 é um conjunto modular de pacotes focados — cada um carregando apenas as dependências de que precisa — construídos do zero para envolver qualquer coisa: um LLM, um agente de caixa-preta ou um pipeline de múltiplas etapas.
| Status | Pacote | Descrição |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ✅ Estável | `giskard-checks` | Testes e avaliação — API de cenários, verificações integradas, LLM-as-judge |
| ✅ Estável | `giskard-scan` | Scanner de vulnerabilidades de agentes + avaliação de RAG/qualidade — red teaming, injeção de prompt, jailbreaks e conteúdo prejudicial (`vulnerability_scan`, sucessor do [v2 Scan](https://legacy-docs.giskard.ai/en/stable/open_source/scan/index.html)), além de avaliação de qualidade de base de conhecimento (`quality_scan`, sucessor do [v2 RAGET](https://legacy-docs.giskard.ai/en/stable/open_source/testset_generation/index.html)) |
Estes se baseiam em três bibliotecas fundamentais — `giskard-core` (utilitários compartilhados e telemetria), `giskard-llm` (roteamento de LLM independente de provedor) e `giskard-agents` (orquestração de agentes e fluxos de trabalho) — que são incluídas automaticamente e raramente usadas diretamente.
## Giskard Checks — crie e aplique avaliações para testar agentes
```sh
pip install giskard-checks
```
**[Giskard Checks](https://docs.giskard.ai/oss/checks)** é uma biblioteca leve para criar avaliações (evals) que testam sistemas baseados em LLM — de asserções simples a avaliações com LLM como juiz. Diferente dos testes unitários tradicionais, as evals são projetadas para **saídas não determinísticas**, em que a mesma entrada pode produzir respostas válidas diferentes.
Use o Giskard Checks para:
- **Detectar regressões** — verificar se o seu sistema continua se comportando corretamente após alterações
- **Validar a qualidade de RAG** — verificar se as respostas estão fundamentadas no contexto recuperado
- **Aplicar regras de segurança** — garantir que as saídas estejam em conformidade com as suas políticas de conteúdo
- **Avaliar agentes multiturno** — testar conversas completas, não apenas trocas únicas
As evals integradas incluem correspondência de strings, comparações, regex, similaridade semântica e verificações com LLM como juiz (`Groundedness`, `Conformity`, `LLMJudge`).
### Conceitos
- **Target** — o seu sistema em teste: qualquer callable síncrono/assíncrono `(inputs) -> outputs` (opcionalmente com `trace`)
- **Scenario** — uma eval: interações + verificações
- **Check** — asserção ou juiz LLM sobre o trace
- **Suite** — vários cenários executados em conjunto
`giskard.agents.Generator` é um cliente LLM para workflows/juízes — não é o mesmo que
os geradores de entrada de `giskard.checks` (`LLMGenerator`) que sintetizam mensagens do usuário.
### Início rápido
Em um script sem um event loop em execução:
```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()
```
Em uma célula de notebook ou dentro de uma função assíncrona, use `await` no cenário:
```python
result = await scenario.run()
result.print_report()
```
`Groundedness` é um juiz LLM — instale um extra de provedor (por exemplo, `pip install "giskard[openai]"`) e defina a chave de API correspondente. Modelo padrão: `openai/gpt-4o-mini`.
Consulte a [documentação completa](https://docs.giskard.ai/oss/checks) para `Suites`, `LLMJudge`, cenários multi-turno e muito mais.
---
## Giskard Scan — scanner de vulnerabilidades para agentes de IA
```sh
pip install "giskard[scan]" # or: pip install giskard-scan
```
**Giskard Scan** é a camada de red-teaming e varredura de vulnerabilidades para sistemas agênticos. Ele gera suítes de testes adversariais automaticamente a partir de uma descrição em linguagem natural do seu agente, cobrindo injeção de prompt, conteúdo prejudicial, estereótipos, desinformação e muito mais.
Use o Giskard Scan para:
- **Fazer red-team do seu agente** — gerar automaticamente entradas adversariais nas categorias de ameaças do OWASP LLM Top-10
- **Executar sondas de injeção de prompt** — conjunto de dados integrado de payloads de injeção prontos para uso
- **Estender com geradores personalizados** — passe suas próprias instâncias de `ScenarioGenerator` para `generate_suite`, ou registre-as em `vulnerability_suite_generator_registry`
### Início rápido
```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())
```
Os geradores de Scan também precisam de um extra de provedor de LLM e de uma chave de API (o mesmo que os juízes de Checks acima).
## Procurando o Giskard v2?
O Giskard v2 incluía **Scan** (detecção automática de vulnerabilidades) e **RAGET** (geração de conjuntos de testes de avaliação de RAG).
Para **agentes de LLM**, ambos foram substituídos na v3 por `giskard-scan`: use [`vulnerability_scan`](#giskard-scan--vulnerability-scanner-for-ai-agents) no lugar do scan de LLM da v2, e `quality_scan` (com `KnowledgeBase`) no lugar do RAGET.
A v3 também funciona com modelos de ML — envolva um como target e avalie-o com `giskard-checks` ou `giskard-scan`. O que os exemplos abaixo cobrem é o **scan tabular automático exclusivo da v2** — o conjunto de detetores que inspeciona um `giskard.Model` + `giskard.Dataset` para detetar automaticamente problemas de desempenho, viés e robustez — juntamente com o conjunto de testes de ML `giskard.testing` e o Giskard Hub. Estes não estão planeados para a v3.
```sh
pip install "giskard[llm]>2,<3"
```
### [Scan](https://legacy-docs.giskard.ai/en/stable/open_source/scan/index.html) — detecta automaticamente problemas de desempenho, viés e segurança
Envolva seu modelo e execute a verificação:
```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="Exemplo de varredura" width="800">
</p>
### [RAGET](https://legacy-docs.giskard.ai/en/stable/open_source/testset_generation/index.html) — gere conjuntos de dados de avaliação para aplicações RAG
Gere automaticamente perguntas, respostas de referência e contexto a partir da sua base de conhecimento:
```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="Exemplo do RAGET" width="800">
</p>
[Documentação completa da v2](https://legacy-docs.giskard.ai)
<h1 id="community">👋 Comunidade</h1>
Acolhemos contribuições da comunidade de IA! Leia este [guia](https://github.com/giskard-ai/giskard-oss/blob/main/CONTRIBUTING.md) para começar e junte-se à nossa próspera comunidade no [Discord](https://gisk.ar/discord).
Acompanhe o progresso e compartilhe feedback:
[Anúncio da v3](https://github.com/orgs/Giskard-AI/discussions/2250) · [Roadmap](https://github.com/Giskard-AI/giskard-oss/issues/2252)
🌟 [Deixe-nos uma estrela](https://github.com/Giskard-AI/giskard), isso ajuda o projeto a ser descoberto por outros e nos mantém motivados a construir ferramentas open-source incríveis! 🌟
❤️ Se você acha nosso trabalho útil, considere [nos patrocinar](https://github.com/sponsors/Giskard-AI) no GitHub. Com um patrocínio mensal, você recebe um selo de patrocinador, pode exibir sua empresa neste readme e ter seus relatórios de bugs priorizados. Também oferecemos patrocínio único caso você queira que nos envolvamos em um projeto de consultoria, realizemos um workshop ou façamos uma palestra na sua empresa.