Metadata-Version: 2.5
Name: agno-metrics-rag
Version: 0.1.3
Summary: Ragas-inspired RAG quality evaluation, synthetic dataset generation, and continuous runtime observability for Agno.
Author: Agno Community
License: MIT
Keywords: agno,evals,llm,metrics,observability,rag,ragas
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: agno>=3.0.0
Requires-Dist: openai>=3.8.0
Requires-Dist: pgvector>=0.2.0
Requires-Dist: psycopg2>=2.9.12
Requires-Dist: psycopg[binary]>=3.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# agno-metrics-rag

[![PyPI version](https://img.shields.io/pypi/v/agno-metrics-rag.svg)](https://pypi.org/project/agno-metrics-rag/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**agno-metrics-rag** é uma biblioteca de avaliação de qualidade e observabilidade contínua de RAG para o ecossistema [Agno](https://github.com/agno-agi/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

```bash
pip install agno-metrics-rag
```

---

## 🚀 Guia de Uso Rápido

### 1. Inicializando o Banco de Métricas

```python
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

```python
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

```python
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)

```python
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:

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

---

## 📄 Licença

Distribuído sob a licença MIT.
