O IRPF Copilot 2026 é uma aplicação inteligente desenvolvida para acabar com a ansiedade e a complexidade na hora de prestar contas ao Leão. Operando sob uma arquitetura Multi-Agente, o sistema ingere documentos brutos (PDFs, fotos de recibos, contratos) e gera um Plano de Preenchimento exato para ser espelhado no software oficial da Receita Federal.
Este projeto nasceu de uma dor pessoal e familiar. Todo ano, eu me via ajudando pessoas próximas a preencherem suas declarações. O processo era sempre caótico: dezenas de recibos médicos amassados, contratos de compra e venda de veículos ilegíveis e a dúvida constante sobre onde colocar cada informação no software do governo.
A ideia inicial era simples: construir um "Cofre Digital" onde o usuário joga qualquer documento, e a IA diz o que fazer. No entanto, após uma pesquisa profunda de mercado e análise de concorrentes, percebi que os LLMs (Large Language Models) comuns falham miseravelmente em duas coisas: matemática exata e leis tributárias.
Para resolver isso e transformar a ferramenta em um verdadeiro Auditor Bidirecional, o projeto escalou. Implementei um RAG (Retrieval-Augmented Generation) alimentado diretamente pelos manuais de uso oficiais do software do IRPF do ano e legislações vigentes, além de uma arquitetura que separa o raciocínio da matemática.
- Alucinação Jurídica (Knowledge Leakage): IAs puras inventam deduções baseadas em senso comum, colocando o usuário em risco de malha fina.
- Cálculos Probabilísticos: IAs erram contas básicas. Um teto de dedução não pode ser "aproximadamente" R$ 3.561,50.
- Extração Superficial: Ferramentas comuns leem apenas o título de um contrato, ignorando o valor da transação, a data e os CPFs envolvidos.
- RAG Especializado e Blindado: A base de conhecimento (Supabase/pgvector) é alimentada com o manual do programa do IRPF e leis. Usamos scripts em Cheerio para higienizar textos governamentais, removendo parágrafos tachados ou revogados antes da vetorização.
- Motor Omnívoro (Cérebro 1 - Visão): Utilização do
gemini-2.5-flashem Modo JSON estrito. Ele ingere Fichas de Declarações Anteriores, recibos médicos e faturas, mapeando exaustivamente valores no nódados_financeiros_extensos. (Nota: A arquitetura possui taxonomia preditiva para notas de corretagem da B3, prontas para testes futuros). - MSLR (Multi-Step Legal Reasoning): O Cérebro 2 (Groq/Llama-3.3) apenas extrai a intenção. A validação matemática (as "travas" da lei) ocorre puramente no TypeScript (
deduction_guard.ts), devolvendo à IA o valor seguro para aconselhar o usuário.
A arquitetura do IRPF Copilot não foi construída baseada em achismos. Realizamos um deep dive em repositórios e frameworks globais de Tax-Tech para extrair as melhores abordagens de engenharia:
- Inspirado pelo
QWED-Tax: Adotamos o padrão arquitetural que fragmenta a transação em motores dedicados, blindando o sistema contra alucinações matemáticas (a origem do nosso MSLR). - Inspirado pelo
Rag-Tax-Helper: Implementamos a lógica de Query Rewriting e sanitização de dados governamentais para garantir que a busca vetorial (pgvector) traga apenas a lei vigente. - Otimização de I/O (
Nota-de-corretagem-to-csv): Estruturação do envio de binários densos (PDFs/Imagens) convertendo-os nativamente para Base64 na memória do Next.js, evitando o bloqueio da interface do usuário. - Sessões e Estado (
AI-tax-agent/TaxEase.AI): Adoção de Server-Sent Events (SSE) para manter o estado da sessão fluido, trocando o modelo antigo de spinners de carregamento por um fluxo contínuo de dados.
O design foi projetado com foco absoluto em IHC (Interação Humano-Computador). Para eliminar a fadiga cognitiva (Context Switching), adotamos a tela dividida: de um lado a conversa, do outro os dados.
- Stateful Whiteboard (Split-Screen): Painel monocromático limpo. Chat à esquerda (40%), Quadro de Documentos Extraídos à direita (60%).
- Uploader Omnívoro com Backoff: Suporte a Drag & Drop de PDFs e Imagens. Sistema de fila (
for...of) inteligente com throttling (pausa automática) para contornar o limite de429 Too Many Requestsdo Free Tier da API do Gemini, sem falhar silenciosamente. - Extração Financeira Profunda: O Zod Schema obriga a IA a varrer cada documento buscando
entidade_ou_ativo,valor_identificado, enatureza(Aquisição, Alienação, Imposto Retido, etc.). - Stream Nativo (SSE): O Cérebro 2 "digita" a resposta em tempo real na tela, respeitando quebras de linha e formatação Markdown.
- Animações Fluidas (GSAP): A cada novo documento processado, os "Cards" de operações surgem no painel com suavidade, transmitindo a sensação de uma auditoria acontecendo ao vivo.
A estrutura reflete a blindagem entre Visão Computacional, Raciocínio (LLM) e Determinismo (TypeScript):
📦 irpf-copilot
┣ 📂 public
┣ 📂 src
┃ ┣ 📂 app
┃ ┃ ┣ 📂 api
┃ ┃ ┃ ┣ 📂 chat
┃ ┃ ┃ ┃ ┗ 📜 route.ts # Cérebro 2: RAG, MSLR Interception e SSE Stream
┃ ┃ ┃ ┣ 📂 extract
┃ ┃ ┃ ┃ ┗ 📜 route.ts # Cérebro 1: Motor Omnívoro (Gemini 2.5 Flash)
┃ ┃ ┃ ┗ 📂 ingest
┃ ┃ ┃ ┗ 📜 route.ts # Ingestão de Leis e Manuais do IRPF (pgvector)
┃ ┃ ┣ 📜 globals.css # Tailwind v4
┃ ┃ ┣ 📜 layout.tsx
┃ ┃ ┗ 📜 page.tsx # Ponto de entrada do Cockpit
┃ ┣ 📂 components
┃ ┃ ┣ 📜 ChatPanel.tsx # UI de Conversa
┃ ┃ ┣ 📜 DocumentUploader.tsx# Fila de Uploads Multi-formato
┃ ┃ ┗ 📜 FinancialWhiteboard.tsx # Renderizador de Cards de Dados
┃ ┣ 📂 hooks
┃ ┃ ┗ 📜 useChatStream.ts # Fetch API nativa para ler o stream (Uint8Array)
┃ ┣ 📂 lib
┃ ┃ ┣ 📂 constants
┃ ┃ ┃ ┗ 📜 tax_limits.ts # Única fonte de verdade para números (ex: 3561.50)
┃ ┃ ┗ 📂 guards
┃ ┃ ┗ 📜 deduction_guard.ts# A "Alfândega" Matemática (Motor TS)
┃ ┣ 📂 scripts
┃ ┃ ┗ 📜 sanitize_laws.ts # Limpeza de HTML/DOM governamental
┃ ┣ 📂 types
┃ ┃ ┗ 📜 finance.ts # Zod UniversalDocumentSchema
┃ ┗ 📜 proxy.ts
┣ 📜 .env.local
┣ 📜 package.json
┗ 📜 tsconfig.json
- Next.js 16.2 (App Router) - Escolhido pela facilidade em orquestrar Serverless Functions (para as APIs de extração) e suportar SSE nativo para o chat.
- TypeScript & Zod - O coração da confiabilidade. Sem tipagem estrita e validação de Schema, os LLMs injetariam dados corrompidos na aplicação.
- Google Generative AI (Gemini 2.5 Flash) - Escolhido para o Cérebro 1 por possuir alto limite de RPM gratuito e capacidade multimodal nativa de forçar respostas em
json_objectperfeitamente estruturadas. - Groq (Llama-3.3-70b) - O Cérebro 2. Utilizado pela velocidade absurda de inferência (Tokens por segundo) para guiar o usuário em tempo real.
- Supabase (pgvector) - Banco de dados PostgreSQL com extensão vetorial para buscas semânticas ultrarrápidas nas cartilhas do imposto de renda.
- Tailwind CSS v4 & GSAP - Estilização limpa, sem arquivos de configuração pesados, e animações profissionais.
- Integração Real B3: Testar e validar a taxonomia de Day-Trade vs. Operação Comum com notas SINACOR reais assim que os dados estiverem disponíveis.
- Privacidade Absoluta (On-Device): Estudar a viabilidade de empacotar o software (Tauri/Electron) e rodar LLMs locais via WebGPU ou Ollama no PC do usuário, garantindo que nenhum PDF contendo CPF saia da máquina local (100% Privacy).
- Captação de Fomento: Estruturar o projeto com métricas sólidas para submissão a editais estaduais de subvenção e inovação (ex: Fapesc).
- Geração de Payload e-CAC: Fazer com que a IA, além de aconselhar, gere um arquivo ou script compatível com a importação direta do programa PGD da Receita Federal.
-
Clone este repositório:
git clone https://github.com/jefheee/irpf-copilot.git
-
Acesse a pasta:
cd irpf-copilot -
Configure as Variáveis de Ambiente: Renomeie
.env.examplepara.env.locale insira suas chaves (Google AI Studio, Groq, Supabase).GOOGLE_API_KEY=sua_chave_gemini GROQ_API_KEY=sua_chave_groq NEXT_PUBLIC_SUPABASE_URL=seu_url_supabase NEXT_PUBLIC_SUPABASE_ANON_KEY=sua_chave_anon_supabase -
Instale as dependências:
npm install
-
Inicie o ambiente de desenvolvimento:
npm run dev
Arquitetura e Design por Jefherson Luiz | IA Powered.