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).
• 📁 MetricsRagArchive: Consultas avançadas, pesquisas filtradas com paginação, cruzamentos relacionais de sessões/usuários e relatórios detalhados de custos de LLM e Embeddings.
• 🧠 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?")

5. Consultas Avançadas, Cruzamento de Dados e Relatório de Custos

from agno_metrics_rag import MetricsRagArchive

archive = MetricsRagArchive(db=metrics_db)

# Buscas filtradas e paginadas
runs = archive.search_eval_runs(user_id="user-1", status="completed", limit=10)
runtime_calls = archive.search_runtime_metrics(tool_name="search_knowledge", limit=20)

# Cruzamento de dados de um ciclo de avaliação completo
run_details = archive.get_eval_run_details(run_id="run-123")

# Visão consolidada da sessão ou do usuário
session_view = archive.get_session_overview(session_id="sess-456")
user_view = archive.get_user_overview(user_id="user-1")

# Relatório de custos de LLM e Embeddings
cost_list = archive.list_costs(user_id="user-1")
cost_summary = archive.get_cost_summary(user_id="user-1")

print("Custo Total:", cost_summary["total_cost"])
print("Consumo por Modelo:", cost_summary["by_model"])

🛠️ Publicação no PyPI

Você pode utilizar o script de automação para incrementar a versão e publicar no PyPI:

# Subversão (Minor) - Padrão (ex: 0.1.4 -> 0.2.0)
python scripts/publish.py

# Versão Principal (Major) (ex: 0.1.4 -> 1.0.0)
python scripts/publish.py --major

📄 Licença

Distribuído sob a licença MIT.