llm-eval-unb 0.1.0

Framework open-source para avaliação de confiabilidade de chatbots baseados em LLMs

🔍 llm-eval

Framework open-source para avaliação sistemática da confiabilidade de chatbots baseados em LLMs.

📚 Documentação completa: https://mateuspy.github.io/TCC2-llmEval/

---

Sobre

O llm-eval é um pacote Python que permite avaliar a confiabilidade de qualquer chatbot baseado em LLM de forma automatizada e reprodutível. Ele envia cenários de teste ao chatbot, coleta as respostas, avalia usando a estratégia LLM-as-a-Judge combinada com métricas computacionais como BERTScore, e gera relatórios estruturados.

O framework avalia três dimensões de confiabilidade:

Dimensão	O que avalia	Como avalia
Precisão Factual	O chatbot responde corretamente?	Compara respostas com ground truth verificável
Consistência Semântica	O chatbot dá a mesma resposta para a mesma pergunta feita de formas diferentes?	Envia reformulações e compara respostas entre si
Robustez	O chatbot mantém a qualidade diante de ruído, typos e inputs adversariais?	Envia variações com erros e compara com a resposta original

O projeto nasceu como parte de um Trabalho de Conclusão de Curso em Engenharia de Software na Universidade de Brasília (UnB), com o objetivo de preencher uma lacuna prática: embora a literatura proponha métricas e critérios para avaliar LLMs, faltam ferramentas acessíveis que permitam aplicá-los de forma sistemática.

---

Instalação

pip install llm-eval-unb

O pacote é distribuído como llm-eval-unb (o nome llm-eval já estava ocupado no PyPI). O import segue import llm_eval e o comando segue llm-eval.

Requer Python 3.11+. Guia completo (extras de dev, chaves por variável de ambiente): Instalação.

---

Quick Start

1. Crie um arquivo de configuração

# config.yaml

# Chatbot a ser avaliado
provider:
  type: gemini
  api_key: ${GEMINI_API_KEY}
  model: gemini-2.0-flash
  temperature: 0.0
  max_tokens: 1024

# LLM usado como juiz (avaliador)
judge:
  enabled: true
  provider:
    type: gemini
    api_key: ${GEMINI_API_KEY}
    model: gemini-2.0-flash
    temperature: 0.0
    max_tokens: 2048

# Dimensões a avaliar
dimensions:
  - factual
  - consistency
  - robustness

repetitions: 1
output_dir: ./results
output_format:
  - json
  - markdown

2. Defina sua API key

export GEMINI_API_KEY="sua-api-key-aqui"

3. Execute a avaliação

llm-eval run --config config.yaml

Os resultados são salvos em ./results/ — report.json (programático) e report.md (leitura humana). Passo a passo detalhado em Guia rápido.

Uso como biblioteca Python

from llm_eval import Config, Runner, ReportGenerator

config = Config.from_yaml("config.yaml")
result = Runner(config).run()

report = ReportGenerator(result)
report.to_json("results/report.json")
report.to_markdown("results/report.md")

---

Documentação

A referência completa fica no site de documentação:

• Instalação — requisitos, extras e chaves por variável de ambiente.
• Guia rápido — do zero a um relatório em três passos.
• Configuração — referência de todos os campos do config.yaml.
• Providers — Gemini, Mistral e o provider HTTP genérico (custom).
• Banco de cenários — formato dos cenários e como usar um banco próprio via scenarios_path.
• Avaliação — LLM-as-a-Judge (rubrica 1–5) e métricas como BERTScore.
• Quality gate em CI — rode o mesmo comando como portão de qualidade em PRs.
• Validação humana — concordância humano × juiz e templates de anotação.

O exemplo vivo de um chatbot avaliado em CI está em examples/demo-chatbot/.

---

CLI — comandos disponíveis

# Executar avaliação completa
llm-eval run --config config.yaml

# Validar configuração sem executar
llm-eval validate --config config.yaml

# Listar cenários disponíveis
llm-eval scenarios --list
llm-eval scenarios --dimension factual

# Validar o juiz contra um golden set
llm-eval validate-judge --provider gemini

# Regenerar relatório a partir de resultados salvos
llm-eval report --input results/run_result.json --format markdown --output report.md

# Ver versão
llm-eval --version

---

Como funciona

                          ┌─────────────────┐
                          │   config.yaml   │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │     Runner      │
                          └────────┬────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
             ┌───────────┐ ┌───────────┐ ┌───────────┐
             │  Factual  │ │Consistency│ │ Robustness│
             │ Scenarios │ │ Scenarios │ │ Scenarios │
             └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
                   │             │             │
                   ▼             ▼             ▼
             ┌─────────────────────────────────────┐
             │            Provider                 │
             │   (Gemini / Mistral / Custom)       │
             └──────────────────┬──────────────────┘
                                │
                                ▼
             ┌─────────────────────────────────────┐
             │           Evaluation                │
             │  ┌──────────┐  ┌─────────────────┐  │
             │  │  Judge   │  │    Metrics       │  │
             │  │(LLM-as-a-│  │  (BERTScore,    │  │
             │  │  Judge)  │  │   Variance)     │  │
             │  └──────────┘  └─────────────────┘  │
             └──────────────────┬──────────────────┘
                                │
                                ▼
             ┌─────────────────────────────────────┐
             │         Report Generator            │
             │     (JSON + Markdown output)        │
             └─────────────────────────────────────┘

---

Requisitos

• Python 3.11 ou superior
• API key de pelo menos um provider (Gemini, Mistral ou endpoint customizado)
• API key para o LLM-as-a-Judge (pode ser o mesmo provider)

---

Contribuindo

Contribuições são bem-vindas! Veja o CONTRIBUTING.md para o guia completo — setup do ambiente, padrões de código, testes e fluxo de PR.

Como você não tem permissão de push no repositório principal, comece pelo fork:

# Faça o fork em github.com/MateusPy/TCC2-llmEval e clone o SEU fork
git clone https://github.com/<seu-usuario>/TCC2-llmEval.git
cd TCC2-llmEval

# Ambiente + instalação editável com deps de dev
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Rodar testes e linter
pytest
ruff check .

---

Roadmap

• Arquitetura e estrutura do pacote
• Providers (Gemini, Mistral, Custom)
• Banco de cenários embutido
• Módulo de avaliação (LLM-as-a-Judge + BERTScore)
• Runner e relatórios
• CLI
• Site de documentação
• Publicação no PyPI
• Suporte a mais dimensões (imparcialidade, segurança)
• Dashboard web para visualização de resultados

---

Contexto Acadêmico

Este projeto foi desenvolvido como parte do Trabalho de Conclusão de Curso intitulado "Avaliação Sistemática da Confiabilidade de Chatbots baseados LLMs: Um Processo Reprodutível de Verificação da Qualidade", no curso de Engenharia de Software da Universidade de Brasília (UnB).

Autores: Mateus Orlando Medeiros Ribeiro e Johnny Da Ponte Lopes Orientador: Profa. Dra. Elaine Venson

---

Licença

Este projeto está licenciado sob a MIT License.