docs: add video explanations comparing RAGAS vs DeepEval

.github/workflows/eval.yml

@@ -21,14 +21,10 @@ jobs:
       - name: Install dependencies
         run: pip install -r requirements.txt
 
-      - name: Login no Confident AI
-        env:
-          CONFIDENT_API_KEY: ${{ secrets.CONFIDENT_API_KEY }}
-        run: deepeval login --confident-api-key $CONFIDENT_API_KEY
-
-      - name: Rodar avaliação
+      - name: Run DeepEval tests
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CONFIDENT_API_KEY: ${{ secrets.CONFIDENT_API_KEY }}
         run: deepeval test run tests/
 
       # resultados já sobem automaticamente ao Confident AI via deepeval login

README.md

@@ -9,71 +9,139 @@ para comparar resultados entre os dois frameworks.
 
 | | RAGAS-Project | DeepEval-Project |
 |---|---|---|
-| Avaliador | RAGAS 0.1.21 | DeepEval >= 0.21 |
+| Avaliador | RAGAS 0.1.21 | DeepEval 3.9.x |
 | Juiz LLM | Claude + OpenAI obrigatória | 100% Anthropic |
 | Resultado | scores 0.0–1.0 em CSV | PASSED/FAILED + reasoning |
 | Visualização | CSV manual | Confident AI (dashboard web) |
 | Métricas customizadas | Não | G-Eval em linguagem natural |
 | CI/CD | Não | GitHub Actions + Pytest |
 
+## Demos em vídeo
+
+Nestes vídeos apresento na prática a diferença entre os dois frameworks — com foco no
+reasoning do DeepEval, nas métricas G-Eval customizadas e no dashboard do Confident AI.
+
+Comparamos as mesmas 5 métricas (Faithfulness, Correctness, Relevancy, Context Precision
+e Context Recall) nos dois frameworks usando os mesmos dados: `historia_ia.txt` e o
+golden dataset de 10 perguntas. Enquanto o RAGAS entrega scores numéricos sem explicação,
+o DeepEval entrega um reasoning completo para cada falha — identificando, por exemplo,
+que o retriever estava rankeando chunks irrelevantes antes do chunk correto. Além disso,
+exploramos as métricas G-Eval, que permitem definir critérios em linguagem natural
+específicos para o seu domínio, e vimos como o Confident AI transforma os resultados em
+um dashboard navegável com histórico de runs, rastreabilidade por test case e comparação
+de regressões.
+
+- [Parte 1 — RAGAS vs DeepEval: reasoning e métricas](https://youtu.be/BId3YL5fP3I)
+- [Parte 2 — Confident AI: dashboard de métricas](https://www.youtube.com/watch?v=l0YHa5kU25M)
+
 ## Estrutura
 
 ```
 DeepEval-Project/
 ├── data/
-│   ├── golden_dataset.csv     # copiado do RAGAS-Project/outputs/
-│   └── historia_ia.txt        # copiado do RAGAS-Project/data/sample_docs/
+│   ├── golden_dataset.csv         # dataset de perguntas e ground truths
+│   ├── chroma_db/                 # VectorStore persistido localmente
+│   └── docs/
+│       └── historia_ia.txt        # documento-fonte do pipeline RAG
+│
+├── outputs/
+│   └── golden_dataset.csv         # dataset lido pelo conftest nas avaliações
+│
+├── src/
+│   └── deepeval_project/
+│       ├── __init__.py
+│       └── rag_pipeline.py        # pipeline RAG (ChromaDB + Claude Haiku)
 │
 ├── tests/
-│   ├── test_evaluate.py       # 5 métricas equivalentes ao RAGAS
-│   └── test_geval.py          # métricas customizadas G-Eval
+│   ├── conftest.py                # ClaudeJudge + fixtures compartilhadas
+│   ├── test_evaluate.py           # métricas equivalentes ao RAGAS
+│   └── test_geval.py              # métricas customizadas G-Eval
 │
-├── conftest.py                # ClaudeJudge + fixtures compartilhadas
+├── pyproject.toml
 ├── requirements.txt
 ├── .env.example
 └── .github/
     └── workflows/
-        └── eval.yml           # CI/CD com GitHub Actions
+        └── eval.yml               # CI/CD com GitHub Actions
+```
+
+## Instalação
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Linux/Mac
+# .venv\Scripts\activate         # Windows
+
+pip install -r requirements.txt
+
+cp .env.example .env
+# editar .env com suas chaves
 ```
 
 ## Dados reutilizados do RAGAS-Project
 
 Copie os arquivos antes de rodar:
 
 ```bash
-cp ../RAGAS-project/outputs/golden_dataset.csv data/
-cp ../RAGAS-project/data/sample_docs/historia_ia.txt data/
+cp ../RAGAS-project/outputs/golden_dataset.csv outputs/
+cp ../RAGAS-project/data/sample_docs/historia_ia.txt data/docs/
 ```
 
-## Instalação
+## Como rodar
+
+### Localmente com pytest (só terminal, não envia ao Confident AI)
 
 ```bash
-python -m venv venv
-source venv/bin/activate        # Linux/Mac
-# venv\Scripts\activate         # Windows
+pytest tests/test_evaluate.py -v
+pytest tests/test_geval.py -v
+```
 
-pip install -r requirements.txt
+Roda os testes e mostra os resultados no terminal — scores, PASSED/FAILED e reasoning —
+mas **não sincroniza nada com o Confident AI**.
 
-cp .env.example .env
-# editar .env com suas chaves
-```
+### Com DeepEval (terminal + dashboard Confident AI)
 
-## Uso
+**Passo 1 — login (uma vez só)**
 
 ```bash
-# 1. conectar ao Confident AI (uma vez só)
 deepeval login
+```
 
-# 2. rodar todos os testes
+Vai pedir a API key que você copia em `app.confident-ai.com → Settings → Project API Key`.
+
+**Passo 2 — rodar com o comando do DeepEval, não com pytest direto**
+
+```bash
+deepeval test run tests/test_evaluate.py
+deepeval test run tests/test_geval.py
+# ou os dois de uma vez:
 deepeval test run tests/
+```
+
+Esse comando faz as duas coisas: roda os testes **e** sincroniza os resultados com o
+Confident AI automaticamente.
 
-# 3. abrir o dashboard no browser
+**Passo 3 — abrir o dashboard**
+
+```bash
 deepeval view
 ```
 
-## Confident AI
+Abre o browser direto no dashboard com os resultados daquela execução — cada pergunta,
+cada score, cada reasoning, tudo que você viu no terminal mas agora navegável e visual.
+
+## CI/CD com GitHub Actions
+
+O workflow em `.github/workflows/eval.yml` roda automaticamente a cada push em `main`
+ou `develop`. Requer dois secrets configurados no repositório:
+
+- `ANTHROPIC_API_KEY`
+- `CONFIDENT_API_KEY`
 
 Os resultados sobem automaticamente para `app.confident-ai.com` após cada execução.
+
+## Confident AI
+
 Crie uma conta gratuita em https://app.confident-ai.com
 
 ## Referências