agno-metrics-rag

agno-metrics-rag é uma biblioteca de avaliação de qualidade e observabilidade contínua de RAG para o ecossistema Agno. Inspirada nas métricas do RAGAS, ela provê:

• 🗄️ Auto-provisionamento de Tabelas: Criação idempotente de tabelas PostgreSQL compatíveis com o Agno (PostgresDb / PgVector).
• 🧠 Geração de Datasets Sintéticos: Síntese de trios (pergunta, ground_truth, contextos) extraídos diretamente dos chunks gravados no seu Knowledge / PgVector usando qualquer LLM suportado pelo Agno.
• 📊 Família Completa de Métricas RAG (RAGAS-compliant):
  • Generation:
    • FaithfulnessMetric: Detecção de alucinações vs contexto.
    • AnswerRelevanceMetric: Relevância e completude da resposta vs pergunta.
    • AnswerCorrectnessMetric: F1-score factual (TP/FP/FN) + similaridade semântica com o Ground Truth.
    • AnswerSemanticSimilarityMetric: Grau de preservação do significado e intenção.
  • Retrieval:
    • ContextPrecisionMetric: Avaliação de Mean Average Precision (chunks relevantes no topo).
    • ContextRecallMetric: Cobertura dos fatos do Ground Truth no contexto.
    • ContextRelevanceMetric / Noise Ratio: Proporção de informação útil vs ruído nos chunks.
    • ContextEntityRecallMetric: Cobertura e fidelidade de entidades nomeadas (nomes, IDs, valores, datas).
  • Safety & Quality:
    • AspectCritiqueMetric: Auditoria de critérios (harmfulness, toxicity, conciseness, politeness, regras customizadas).
  • Agentic RAG:
    • ToolCallAccuracyMetric: Acurácia da seleção de tools e precisão dos argumentos gerados.
• ⚡ Tool Hook de Runtime (Síncrono ou em Background): Intercepta chamadas de busca (search_knowledge ou tool customizada) e computa a qualidade sem bloquear a resposta do agente ao usuário final.

📦 Instalação

pip install agno-metrics-rag

🚀 Guia de Uso Rápido

1. Inicializando o Banco de Métricas

from agno_metrics_rag import RagMetricsDb

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"
metrics_db = RagMetricsDb(db_url=db_url)

2. Gerando um Dataset Sintético a partir do Knowledge

from agno.models.openai import OpenAIChat
from agno.vectordb.pgvector import PgVector
from agno_metrics_rag import RagTestsetGenerator

judge_model = OpenAIChat(id="gpt-4o-mini")
vector_db = PgVector(table_name="minha_tabela_de_vetores", db_url=db_url)

generator = RagTestsetGenerator(
    model=judge_model,
    db=metrics_db,
    vector_db=vector_db,
)

# Gera perguntas e ground-truths baseados nos chunks reais gravados no banco
testset = generator.generate_testset(
    name="Dataset de Qualidade RAG",
    num_samples=10,
    persist=True,
)

3. Rodando um Ciclo de Testes e Avaliação

from agno_metrics_rag import RagEvaluator

evaluator = RagEvaluator(
    judge_model=judge_model,
    db=metrics_db,
)

# Executa a bateria de testes contra o Agente
report = evaluator.run_suite(
    agent=meu_agente_agno,
    testset=testset,
)

print("Resumo:", report.metrics_summary)
# Exemplo de saída:
# {
#   'avg_faithfulness': 0.94,
#   'avg_answer_relevance': 0.89,
#   'avg_context_precision': 0.92,
#   'avg_context_recall': 0.85
# }

4. Monitoramento Contínuo em Produção (Tool Hook em Background)

from agno.agent import Agent
from agno_metrics_rag import RagMetricsHook, HookMode

metrics_hook = RagMetricsHook(
    db=metrics_db,
    judge_model=judge_model,
    mode=HookMode.ASYNC_BACKGROUND, # Executa em background thread, zero impacto na latência
    target_tool_names=["search_knowledge"],
)

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    knowledge=knowledge,
    search_knowledge=True,
    tool_hooks=[metrics_hook],
)

agent.print_response("Quais as receitas disponíveis?")

🛠️ Publicação no PyPI

Para buildar e publicar a biblioteca:

pip install build twine
python -m build
twine upload dist/*

📄 Licença

Distribuído sob a licença MIT.