From 1cc95f027ae29bf8cb93991a84279436a0f090c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Wed, 28 Jan 2026 09:02:41 -0300 Subject: [PATCH] docs: Refatora PRD com arquitetura de API e LLM Local MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Porque foi feita essa alteração? Ajuste completo do escopo para remover ingestão de arquivos e focar em consumo via API, RAG com Llama 3 local e execução CPU-only, conforme feedback do usuário. Quais testes foram feitos? Revisão do documento. A alteração gerou um novo teste que precisa ser implementado no pipeline de testes? Não. --- .gemini/PRD_Classificacao_Bancaria.md | 101 ++++++++++++-------------- 1 file changed, 47 insertions(+), 54 deletions(-) diff --git a/.gemini/PRD_Classificacao_Bancaria.md b/.gemini/PRD_Classificacao_Bancaria.md index fa22ca8..998e908 100644 --- a/.gemini/PRD_Classificacao_Bancaria.md +++ b/.gemini/PRD_Classificacao_Bancaria.md @@ -2,74 +2,67 @@ ## Agente de IA para Classificação de Transações Bancárias ### 1. Visão Geral -Este documento define os requisitos para o desenvolvimento de um Agente de Inteligência Artificial especializado na análise, categorização e classificação de transações bancárias. O objetivo é automatizar o processo de conciliação financeira, transformando dados brutos de extratos em informações organizadas e acionáveis. +Este documento define os requisitos para o desenvolvimento de um Agente de Inteligência Artificial especializado na classificação de transações bancárias. O sistema operará exclusivamente via API, consumindo dados já tratados e utilizando técnicas de RAG (Retrieval-Augmented Generation) para sugerir classificações com base em histórico prévio, priorizando eficiência em ambientes com restrição de hardware (CPU-only). ### 2. Objetivos do Produto -- **Automação:** Reduzir em 90% o trabalho manual de classificação de lançamentos financeiros. -- **Precisão:** Alcançar uma taxa de assertividade superior a 95% na categorização automática. -- **Inteligência:** Identificar padrões de recorrência e anomalias (possíveis fraudes ou erros). -- **Escalabilidade:** Capaz de processar milhares de transações em segundos. +- **Classificação Inteligente:** Categorizar transações com base na descrição, utilizando similaridade (RAG) e inferência de modelo local. +- **Eficiência de Recurso:** Operar com baixo consumo de RAM e exclusivamente em CPU. +- **Desacoplamento:** Interação exclusiva via API, sem interface direta com usuário final. +- **Autonomia:** Processamento assíncrono sem bloqueio aguardando feedback humano imediato. ### 3. Escopo #### 3.1 Incluso -- Leitura de extratos bancários em formatos padrão (OFX, CSV, Excel, PDF). -- Processamento de Linguagem Natural (NLP) para entender descrições de transações (ex: "IFOOD *BR" -> "Alimentação"). -- Aprendizado contínuo com feedback do usuário. -- Geração de relatórios categorizados. +- Integração via API para recebimento de dados de transações (já parseados). +- Busca de transações similares em base vetorial (RAG). +- Motor de inferência utilizando LLM Local (Llama 3). +- Cálculo de taxa de acerto e confiança. +- Mecanismo de feedback diferido (Human-in-the-loop passivo). -#### 3.2 Não Incluso (nesta fase) -- Integração direta via API bancária (Open Finance) - *Fase 2*. -- Execução de pagamentos ou transferências. -- Gestão de fluxo de caixa (Dashboard financeiro complexo). +#### 3.2 Não Incluso +- Leitura ou parsing de arquivos (OFX, CSV, PDF, Excel). +- OCR ou extração de dados de imagens. +- Interface de usuário direta para o agente (o agente é um backend service). +- Bloqueio de execução por espera humana. ### 4. Funcionalidades Principais -#### 4.1 Ingestão de Dados -O sistema deve aceitar arquivos de upload contendo extratos bancários. -- **Entrada:** Arquivos .csv, .xlsx, .ofx. -- **Processamento:** Normalização de datas, valores e descrições. +#### 4.1 Interface de Entrada +- O agente não processa arquivos. Ele expõe endpoints ou consome filas onde recebe objetos JSON contendo os dados da transação (ID, Descrição, Valor, Data, metadados). -#### 4.2 Motor de Classificação (Core AI) -O agente deve analisar a descrição da transação e atribuir uma: -1. **Categoria Principal** (ex: Despesas Administrativas). -2. **Sub-categoria** (ex: Material de Escritório). -3. **Tags** opcionais (ex: #reembolsavel, #projeto-alpha). +#### 4.2 Motor de Classificação (Core AI - RAG + LLM Local) +- **Estratégia:** + 1. Recebe a descrição da transação. + 2. Consulta banco vetorial para encontrar transações passadas similares já classificadas (pelo agente ou humanos). + 3. LLM (Llama 3) analisa a descrição atual + exemplos recuperados (Contexto). + 4. Define a Categoria e Subcategoria. +- **Resources:** Otimizado para rodar localmente limitando uso de RAM. -Exemplos de mapeamento: -- `UBER DO BRASIL` -> Transporte -- `AWS EMEA` -> Infraestrutura / Cloud -- `PAGTO ELETRON COBRANCA` -> Tarifas Bancárias - -#### 4.3 Detecção de Padrões e Anomalias -- **Vencimentos Recorrentes:** Identificar pagamentos que se repetem mensalmente. -- **Anomalias:** Alertar sobre valores muito acima da média para um determinado fornecedor. - -#### 4.4 Interface de Correção (Human-in-the-loop) -O sistema deve apresentar as classificações com um "Score de Confiança". -- Baixa confiança (< 70%): Solicitar revisão manual. -- Alta confiança (> 90%): Aprovação automática (configurável). +#### 4.3 Métricas e Feedback +- **Dashboard de Métricas:** Exposição de dados sobre taxa de acerto e confiança do modelo. +- **Feedback Loop:** O sistema deve permitir que uma aplicação externa envie a correção de uma classificação. Essa correção é salva no banco para refinar futuras buscas RAG. ### 5. Requisitos Não Funcionais -- **Privacidade:** Dados sensíveis devem ser anonimizados antes de serem processados por LLMs externos, se aplicável. -- **Performance:** Tempo de resposta < 2 segundos por transação em lote. -- **Portabilidade:** Deve rodar localmente ou em container Docker. +- **Hardware:** Execução exclusiva em CPU. Mínimo consumo de RAM plausível. +- **Privacidade:** Dados processados localmente. Sem envio para APIs externas (OpenAI/Anthropic). +- **Latência:** Foco em throughput, aceitável latência de inferência local desde que não trave a aplicação chamadora. -### 6. Stack Tecnológica Sugerida -- **Linguagem:** Python 3.10+ -- **Framework de Agentes:** CrewAI, LangChain ou Phidata. -- **LLM:** OpenAI GPT-4o, Anthropic Claude 3.5 Sonnet (para raciocínio complexo) ou modelos locais (Llama 3, Mistral) para privacidade. -- **Base de Dados:** PostgreSQL ou SQLite para armazenamento estruturado; ChromaDB ou Qdrant para busca semântica (RAG) de históricos de classificação. +### 6. Stack Tecnológica Definida +- **Linguagem:** Python (Versão travada: 3.12.1). +- **Framework:** A definir (LangChain ou implementação customizada leve). +- **LLM:** Llama 3 (versão otimizada para CPU/Local, ex: GGUF/Ollama se aplicável). +- **Base de Dados:** + - **Relacional:** PostgreSQL (para dados estruturados, logs, ponteiros). + - **Vetorial:** Solução integrada ou leve para RAG, indexando descrições e classificações históricas. -### 7. Fluxo de Execução (High-Level) -1. **Input:** Usuário envia `extrato.csv`. -2. **Parser:** Script converte para JSON padronizado. -3. **Agent:** - - Consulta base vetorial para ver se já classificou algo similar antes (Few-Shot Learning). - - Se não, usa LLM para inferir categoria baseada na descrição. -4. **Output:** JSON/CSV enriquecido com colunas `Categoria`, `Subcategoria` e `Confiança`. -5. **Feedback:** Usuário corrige/valida e o sistema salva o exemplo para futuro fine-tuning/RAG. +### 7. Fluxo de Execução +1. **Trigger:** Aplicação externa envia transação via API para o Agente. +2. **Retrieval:** Agente busca no VectorDB as "Top-K" transações mais parecidas semanticamente com a atual. +3. **Inference:** Prompt montado com a Transação Atual + Exemplos Recuperados é enviado ao Llama 3 Local. +4. **Result:** Agente retorna a classificação sugerida + Score de Confiança. +5. **Human Review (Assíncrono):** Através da aplicação principal, o usuário valida. +6. **Learning:** Se houve correção, a aplicação notifica o Agente/Banco para atualizar o "Golden Record" usado no RAG. ### 8. Próximos Passos -- [ ] Definir a taxonomia padrão de categorias (Plano de Contas). -- [ ] Criar dataset de validação (Golden Dataset). -- [ ] Implementar MVP com script Python simples e chamada de API LLM. +- [ ] Definir a versão exata do Llama 3 e método de quantização para CPU. +- [ ] Modelar o schema do banco de dados (Tabela de Transações vs Tabela de Embeddings). +- [ ] Configurar ambiente Python 3.12 travado.