From bac9a659bd4d1a4c29b10025790552523695d705 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Wed, 28 Jan 2026 12:11:54 -0300 Subject: [PATCH] update das regras do nosso agent interno de dev --- .gemini/GEMINI.md | 4 +- .gemini/PRD_Classificacao_Bancaria.md | 106 -------------------------- .gemini/TASKS-TODO.md | 34 --------- 3 files changed, 2 insertions(+), 142 deletions(-) delete mode 100644 .gemini/PRD_Classificacao_Bancaria.md delete mode 100644 .gemini/TASKS-TODO.md diff --git a/.gemini/GEMINI.md b/.gemini/GEMINI.md index d2e2d0e..b7c9b26 100644 --- a/.gemini/GEMINI.md +++ b/.gemini/GEMINI.md @@ -8,11 +8,11 @@ Você atua como um Desenvolvedor de IA especializado. Siga rigorosamente as dire ### 2. Contexto e Escopo - **Objetivo:** Desenvolver um agente de IA para classificação de transações bancárias. -- **Referência:** Sempre consulte o arquivo `C:\Users\joao.goncalves\Desktop\Projetos\minions-da-itguys\.gemini\PRD_Classificacao_Bancaria.md` para entender o escopo antes de qualquer ação. +- **Referência:** Sempre consulte o arquivo `C:\Users\joao.goncalves\Desktop\Projetos\minions-da-itguys\.gemini\PRD_Suporte_Tecnico_N2.md` para entender o escopo antes de qualquer ação. - **Limites:** Se uma solicitação estiver fora do PRD, interrompa o trabalho e retorne ao planejamento para alinhamento. ### 3. Fluxo de Trabalho e Gestão -- **Tarefas:** Gerencie todo o progresso via `C:\Users\joao.goncalves\Desktop\Projetos\minions-da-itguys\.gemini\TODO.md`. Siga o plano à risca e evite criar tarefas por conta própria. +- **Tarefas:** Gerencie todo o progresso via `C:\Users\joao.goncalves\Desktop\Projetos\minions-da-itguys\.gemini\TODO_Arthur.md`. Siga o plano à risca e evite criar tarefas por conta própria. - **Modos de Operação:** Nunca decida sozinho mudar do modo "Planejamento" para o modo "Desenvolvimento". Aguarde o comando explícito do usuário. ### 4. Protocolo de Commit e Git diff --git a/.gemini/PRD_Classificacao_Bancaria.md b/.gemini/PRD_Classificacao_Bancaria.md deleted file mode 100644 index 8f87050..0000000 --- a/.gemini/PRD_Classificacao_Bancaria.md +++ /dev/null @@ -1,106 +0,0 @@ -# PRD - Product Requirements Document -## 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 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 -- **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 -- 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 -- 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 Interface de Entrada -- O agente expõe endpoints para receber objetos JSON contendo estritamente: - - `idTransacao` (varchar 1000): Identificador único da transação na origem. - - `dataEntrada` (date): Data de competência da transação. - - `descricao` (varchar 500): Texto descritivo da transação bancária. - - `tipoOperacao` (varchar 500): Indicador de entrada/saída (ex: 'C'/'D', 'Crédito'/'Débito'). - - `tipoTransacao` (varchar 500): Método da transação (ex: 'pix', 'pagamento', 'boleto', 'débito'). - - `titulo` (varchar 500): Título amigável da transação (ex: "Pix Enviado", "Boleto Pago"). -- **Nota:** O campo de Valor foi removido para evitar vieses. O modelo usará a descrição combinada com os tipos e título para categorização. - -#### 4.2 Motor de Classificação (Core AI - RAG + LLM Local) -- **Estratégia:** - 1. **Embedding:** Gera vetor da descrição usando `BGE-small`. - 2. **Retrieval (Qdrant):** Busca 3-5 transações similares confirmadas. - 3. **Context Injection:** Injeta os exemplos no prompt do Llama 3.2 1B. - 4. **Inference (PydanticAI):** Modelo classifica e PydanticAI valida se a categoria existe no Enum permitido. - 5. **Output:** Retorna classificação validada. -- **Resources:** Otimizado para rodar localmente limitando uso de RAM. - -#### 4.3 Métricas e Observabilidade -- **Monitoramento Lógico (AgentOps):** Uso do **Langfuse** (self-hosted) para rastreamento (tracing) passo a passo de cada inferência. (Integração com Zabbix via Webhooks/API desejável, mas não obrigatória nesta fase). -- **Monitoramento de Infraestrutura:** Uso de **Zabbix Agent** para monitoramento de CPU/RAM/IO do host e containers. -- **Feedback Loop:** O sistema deve registrar feedback de usuário como "Scores" no trace do Langfuse para avaliação de qualidade. - -### 5. Requisitos Não Funcionais -- **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 Definida -- **Linguagem:** Python (Versão travada: 3.12.1). -- **Framework:** FastAPI (Exposição) + **PydanticAI** (Validação estrita e Orquestração). -- **Observabilidade:** **Langfuse** (Tracing) + **Prometheus/Grafana** (Métricas). -- **LLM:** **Llama 3.2 1B Instruct** Local (GGUF Q4). - - **Otimização:** Uso de **GGUF Q4_K_M** (Recomendado). - - *Por que Q4?* Com ~4 bits por peso, o modelo ocupa ~700MB de RAM. - - *Por que não menor (Q2/Q3)?* Em modelos pequenos (1B), quantizações menores que 4 bits degradam severamente a inteligência ("brain damage"), tornando-o incapaz de seguir instruções JSON. - - *Por que não maior (Q8)?* Ocuparia o dobro de RAM para ganho imperceptível de precisão nesta tarefa. -- **Base de Dados e RAG:** - - **Relacional:** PostgreSQL. - - **Vetorial (RAG):** **Qdrant**. Configurado com `on_disk: true` e quantização escalar para economia de RAM. - - **Embeddings:** `BGE-small-en-v1.5` ou similar (FastEmbed) para geração rápida em CPU. - - - -### 7. MLOps e Data Flywheel (Pipeline RAG Completo) -O pipeline RAG não serve apenas para inferência, mas é o **motor de geração de dataset** para o Agente. -- **Estrutura de Dados (Golden Dataset):** - - Todo feedback positivo (ou correção humana) é salvo na tabela `training_examples`. - - **Campos:** `input_text` (Descrição + Metadados), `output_json` (Categoria Correta), `source` (Human/Auto), `timestamp`. -- **Ciclo de Vida do Dado:** - 1. **Ingestão:** Transação chega via API. - 2. **Busca & Inferência:** Agente sugere classificação. - 3. **Feedback:** Aplicação confirma ou corrige a classificação. - 4. **Persistência:** O par `{Input, Correct_Output}` é salvo no PostgreSQL e indexado no Qdrant. - 5. **Exportação:** Script `export_dataset.py` gera arquivo JSONL formatado para LoRA (`instruction`, `input`, `output`) a partir apenas de exemplos validados. - -- **Model Registry & Git Flow:** - - Todo novo treino gera um commit automático em uma branch isolada `candidatos-pos-treino/v{DATA}`. - - O artefato (`adapter.gguf`) é salvo e preservado independente do resultado do benchmark. -- **Benchmarking e Promoção (Nível 1 - Manual):** - - O sistema roda o teste comparativo e anexa o relatório no Pull Request ou Issue. - - **Aprovação:** Se aprovado pelo humano, faz merge para `iris-classificacao-bancaria` e o deploy ocorre. - - **Reprovação:** Se reprovado, a branch é mantida para análise histórica (não é descartada), mas o PR é fechado/ignorado. - -### 8. 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:** Integração com pipeline de MLOps descrito acima. - -### 9. Próximos Passos -- [x] Definir versão exata do Llama 3.2 1B e método de quantização (Q4_K_M) -- [x] Modelar pipeline de exportação de dados para Fine-tuning futuro (Data Flywheel) -- [ ] Configurar container Zabbix Agent. - diff --git a/.gemini/TASKS-TODO.md b/.gemini/TASKS-TODO.md deleted file mode 100644 index 0727e92..0000000 --- a/.gemini/TASKS-TODO.md +++ /dev/null @@ -1,34 +0,0 @@ -# Projeto Agente de Classificação Bancária - -- [ ] Configuração do Ambiente e Dependências - - [ ] Criar/Configurar ambiente virtual Python 3.12 - - [ ] Atualizar `requirements.txt` (FastAPI, Qdrant-client, llama-cpp-python, langfuse, pydantic-ai) - - [ ] Configurar variáveis de ambiente (`.env`) - -- [ ] Infraestrutura Base - - [ ] Configurar `docker-compose.yml` para Qdrant (Persistent) - - [ ] Configurar conexão com PostgreSQL (Persistência) - - [ ] Configurar conexão com Langfuse (Observabilidade) - -- [ ] Implementação do Core (Backend) - - [ ] Implementar Modelos de Dados (`src/models.py`) - - [ ] Request/Response Schemas - - [ ] Implementar Serviço Vector Store (`src/services/vector_db.py`) - - [ ] Inicialização Qdrant - - [ ] Embedding (BGE-small) - - [ ] Retrieval Logic - - [ ] Implementar LLM Engine (`src/services/llm_engine.py`) - - [ ] Carregamento do Llama 3.2 1B (GGUF) - - [ ] Prompt Template com Contexto - - [ ] Implementar Orquestrador (`src/controller.py` ou similar) - - [ ] Fluxo RAG + Inferência - -- [ ] API REST (FastAPI) - - [ ] Definir Rotas (`src/api/routes.py`) - - [ ] POST `/api/v1/classify` - - [ ] Configurar `main.py` - - [ ] Adicionar Health Checks - -- [ ] Testes e Verificação - - [ ] Teste de carga simples (garantir que roda em CPU) - - [ ] Validação da acurácia básica (Smoke test) \ No newline at end of file