RAG_CONTEXT.md

Ratio - RAG Project Context & Status

Este repositório contém um sistema RAG (Retrieval-Augmented Generation) construído para realizar buscas semânticas mistas sobre uma base consolidada da Jurisprudência do STF e STJ, gerando respostas fundamentadas com a API do Gemini.

🚀 Arquitetura

O sistema é dividido em fases lógicas que transformam dados extraídos da web em tensores semânticos consultáveis.

1. Extração Original (scrapers/ e download_stj.py)
   • Downloads de decisões via API Elasticsearch do STF e web scraping de PDFs de Informativos do STJ.
2. Processamento e Estruturação (processors/ e data/)
   • Normalização dos dados "sujos" em bancos SQLite padronizados, extração de texto em PDFs com regex.
3. Database Vetorial e Ingestão (rag/ingest.py e lancedb_store/)
   • Uso de LanceDB serverless (no disco).
   • Embedding: gemini-embedding-001 (Dimensão 768).
   • Busca Híbrida nativa na DB (Embeddings + Full-Text Search).
4. Engine de Busca e Reranking (rag/query.py)
   • Realiza a Vector Search + BM25 combinadas.
   • Aplica Reranker cross-encoder/ms-marco-MiniLM-L-6-v2 nas amostras encontradas para precisão máxima.
5. Geração LLM com Strict Citation (rag/query.py)
   • O Gemini (Padrão: gemini-3-flash-preview / Raciocínio: gemini-3.1-pro-preview) recebe os documentos formatados com um prompt restritivo (REGRA 2: Não invente, diga 'Não encontrei' se não houver no acervo).

---

📂 Estrutura de Pastas e Arquivos

├── data/                       # Bancos locais SQLite limpos (Fase 0)
│   ├── acordaos/               # STF Acórdãos (~223k registros)
│   ├── informativos/           # STF Informativos (~11k)
│   ├── monocraticas/           # STF Monocráticas (~712k)
│   ├── sumulas/                # STF Súmulas (736)
│   └── stj_informativos/       # STJ Informativos (4.9k)
├── lancedb_store/              # Arquivos binários do LanceDB (Fase 1 e 2)
│   └── jurisprudencia.lance/   # Banco vetorial criado no run de ingest.py
├── processors/                 # Scripts Python que limpam, criam SQLite e padronizam
│   ├── organize_stj_informativos.py
│   └── parse_stj_to_sqlite.py  # Parser PDF -> SQLite para o STJ
├── rag/                        # Pipeline do RAG e Query Engine (Fase 3 e 4)
│   ├── ingest.py               # Leitor SQLite -> Gemini Embedding -> LanceDB
│   └── query.py                # Interface de Busca (Busca híbrida -> Reranker -> LLM)
├── scrapers/                   # Códigos para download bruto (Fase -1)
│   └── ...
├── .env                        # [Necessário criar] Variáveis como GEMINI_API_KEY
├── download_stj.py             # Script de download automatizado de PDFs do STJ
├── README.md                   # Repositório documentation
└── RAG_CONTEXT.md              # Este contexto

---

⚡ Como acelerar a Ingestão (Embeddings)?

Ao rodar py rag/ingest.py --source all, o processo enviará milhares de textos para o Google. Atualmente o script tem time.sleep(1.0) para não bater na parede de limite de taxa gratuita (Rate Limit 429 RESOURCE_EXHAUSTED).

Opções para Agilizar:

1. Tier Pago / Upgrade no Google AI Studio / Google Cloud (Pay-as-you-go):

   • Acesse o Google Cloud Console ou o Google AI Studio.
   • Adicione dados de faturamento (Billing) na sua Google Cloud Project associada à sua API Key.
   • O modelo gemini-embedding-001 passará a aceitar milhares de requests por minuto (RPM) em vez do limite do Tier Gratuito.
   • Uma vez feito o upgrade de conta, edite em rag/ingest.py a variável EMBED_DELAY = 1.0 para EMBED_DELAY = 0.0 e aumente o EMBED_BATCH_SIZE até o limite pago da sua cota.

2. Google Batch API [Opção para Produtização via GCP]:

   • O Google Cloud suporta enviar os textos para armazenamento no Cloud Storage (GCS) em massa como um arquivo JSONL, executar um Job Batch Assíncrono com desconto de 50%, e devolver todos os embeddings de uma só vez (sem limite prático de Rate Limit). Isso exige criar Cloud Storage Buckets.

---

🛠� Como Instalar e Rodar

Requisitos:

• Python 3.10+
• Conta Google e API Key (Google AI Studio ou Vertex AI).

Instalação:

# Instalar principais pacotes via pip
pip install lancedb google-genai python-dotenv pyarrow sentence-transformers PyMuPDF

Configuração:

Crie um arquivo .env na raiz do projeto com sua chave e configure:

GEMINI_API_KEY="SUA_CHAVE_GEMINI_AQUI"

Ingestão (Gerando o LanceDB Vetorial)

py rag/ingest.py --source sumulas       # Teste rápido
py rag/ingest.py --source stj           # Demorado (Vários minutos, ~5k requests)
py rag/ingest.py --source informativos  # Bem Demorado (~11k requests)
py rag/ingest.py --source acordaos      # Apenas caso Premium Tier! (223k reqs)

Consulta (RAG Query)

# Busca Rápida (Flash 3.0)
py rag/query.py "Qual o entendimento do STJ sobre IPTU em zona rural?"

# Busca Complexa / Raciocínio Lento e Analítico (Pro 3.1)
py rag/query.py "Discorra sobre a repercussão geral tema X em face dos precedentes..." --reasoning