107 lines
7.0 KiB
Markdown
107 lines
7.0 KiB
Markdown
# 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) <!-- id: 14 -->
|
|
- [x] Modelar pipeline de exportação de dados para Fine-tuning futuro (Data Flywheel) <!-- id: 15 -->
|
|
- [ ] Configurar container Zabbix Agent.
|
|
|