IRS Helper — RAG de Documentos Tributários Americanos
Sistema RAG completo de produção para documentos tributários do IRS (Internal Revenue Service dos EUA). Faz scraping de PDFs e EPUBs com Scrapy, vetoriza com embeddings OpenAI, armazena em PostgreSQL+pgvector e expõe uma API HTTP compatível com o formato OpenAI (`/v1/chat/completions` com suporte a streaming SSE). O retriever é dual-mode: detecta formulários por regex e devolve link direto, e para perguntas abertas faz busca semântica com rerank Cohere + geração GPT. A API é exposta via LiteLLM na frente do OpenWebUI, dando ao usuário final uma interface de chat completa.
## 🔧 Tech Stack
## 📈 Workflow
Scrapy (PDF + EPUB)
Spiders separadas para PDFs e EPUBs; persistência direta no PostgreSQL com pipeline
pdf_vectorizer.py
Lê documentos do banco, faz chunking, gera embeddings e armazena chunks vetorizados no pgvector (irs_document_chunks)
retrieve_server.py (FastAPI)
Servidor FastAPI que expõe /v1/chat/completions (formato OpenAI, com SSE streaming), /health e /dashboard
Form Detection (regex)
Detecta 'Form 1040', 'Schedule A' etc. e devolve link direto pro PDF (resposta determinística, sem custo de LLM)
Semantic Search (RAG)
Embeddings OpenAI + busca vetorial + rerank Cohere + geração GPT com contexto
OpenWebUI (via LiteLLM)
Interface de chat para usuário final; consome a API como se fosse OpenAI, sem saber que é RAG
vector_store_monitor.py
Script que monitora o vector store: contagem de documentos, chunks, drift de embeddings, falhas de indexação
## ✨ Features
- •Pipeline completo: Scrapy (PDF/EPUB) → PostgreSQL → vetorização → RAG → API
- •API HTTP compatível com o formato OpenAI (`/v1/chat/completions` com streaming SSE) — qualquer cliente OpenAI funciona sem mudança
- •Retriever dual-mode: detecção de formulários por regex (resposta determinística e gratuita) + busca semântica com rerank Cohere + GPT
- •Embeddings OpenAI text-embedding-3-small (1536 dims) + Cohere rerank-english-v3.0
- •Interface de chat pronta pro usuário final via OpenWebUI, com LiteLLM como gateway
- •Dashboard web (`/dashboard`) com estatísticas do vector store: contagem de docs, chunks, cobertura
- •Script de monitoramento do vector store (drift, falhas de indexação)
- •Container Docker (Python 3.9-slim) pronto pra deploy em qualquer VPS
- •EPUB→PDF converter com upload pra Cloudflare R2 (preserva o source original)
## 🎯 Results
- ✓API 100% compatível com o formato OpenAI — qualquer cliente (incluindo OpenWebUI, ChatBox,Continue) funciona sem mudança
- ✓Retriever dual-mode reduz custo e latência: regex resolve perguntas diretas sem chamar LLM
- ✓Pipeline de scraping + vetorização + retrieval + serving num único sistema, monitorado e observável
- ✓Monitor contínuo do vector store permite detectar regressões antes do usuário perceber
## 🧩 Use Case
Empresas ou profissionais que precisam transformar um corpus de documentos densos (jurídicos, regulatórios, técnicos, manuais) num produto de Q&A conversacional. O ponto-chave é que a API exposta é OpenAI-compatible: o cliente final usa a interface que quiser (OpenWebUI, ChatBox, Continue) sem saber que tem RAG por baixo. Demonstra capacidade de entregar um produto RAG completo, do scraping à interface final, em produção.
## 🔗 Related Projects
Plataforma SaaS full-stack para criar e gerenciar agentes de IA com BYOK (Anthropic + Open...
Automated pipeline for generating and publishing Instagram content using generative AI and...
Intelligent RAG system for tax law consultation with vector search and multi-format docume...