# 💼 Case Técnico Itaú — AI Engineering: Sistema Automatizado de Análise de Risco e Rastreabilidade

Este repositório contém a solução desenvolvida para o Case Técnico de Engenharia de IA. O projeto implementa um sistema híbrido de Compliance e PLD que combina **processamento determinístico de dados (Pandas)** com **inteligência cognitiva avançada (Google Gemini)**, estruturado em três níveis de maturidade arquitetural.

---

## 🚀 Arquitetura e Visão Geral do Projeto

A premissa central da arquitetura é a **separação estrita de responsabilidades**:
1. **Camada Determinística:** Cálculos matemáticos, conversões cambiais, normalização e aplicação de regras regulatórias puras (ex: detecção de fracionamento e *outliers*) executadas via **Pandas** para eliminar alucinações numéricas.
2. **Camada Cognitiva & Agêntica:** Uso de LLMs (**Gemini 3.5 Flash**) para interpretação comportamental, identificação de tipologias (*Structuring/Smurfing*) e geração de pareceres estruturados.
3. **Camada de Produção & Guardrails:** Validação estrita de tipos com **Pydantic** e execução de ferramentas autônomas via **Tool Calling** (Function Calling).

---

## 📂 Estrutura do Repositório

```text
├── dados/
│   └── dados_nivel_1.json      # Base de transações e taxa de câmbio
├── nivel_1.ipynb               # Notebook principal - Nível 1 e 1.1
├── nivel_2.ipynb               # Notebook do Agente Autônomo com Tool Calling
├── nivel_3.ipynb               # Notebook de Produção e Guardrails com Pydantic
├── DECISOES.md                 # Relatório de trade-offs e decisões arquiteturais
├── entrega.yaml                # Metadados de submissão do case
├── requirements.txt            # Dependências do projeto
└── README.md                   # Documentação do projeto

---

🛠️ Tecnologias Utilizadas

• Python 3.10+
• Pandas (Manipulação e agregação de dados financeiros)
• Google GenAI SDK (google-genai) (Integração oficial com os modelos Gemini)
• Pydantic (Validação de schemas e tipagem em tempo de execução)
• Jupyter Notebook / VS Code (Ambiente de desenvolvimento)

---

⚙️ Guia de Instalação e Execução

Siga os passos abaixo para rodar o projeto localmente:

1. Clonar o repositório e instalar dependências

Certifique-se de ter o Python instalado e execute no terminal:

pip install -r requirements.txt

2. Configurar a Chave de API do Google AI Studio

1. Acesse o Google AI Studio e gere uma chave de API gratuita.
2. Crie um arquivo chamado .env na raiz do projeto contendo a sua credencial:

GEMINI_API_KEY=sua_chave_aqui

3. Executar os Notebooks

Abra o VS Code ou o Jupyter Notebook e execute as células sequencialmente (Run All) para validar todas as etapas do case.

---

📊 Resumo dos Níveis Implementados

🔹 Nível 1: Ingestão, Limpeza e Regras Determinísticas

• Limpeza e Tratamento: Deduplicação de IDs de transações e conversão cambial automatizada de USD para BRL baseada no payload JSON.
• Regras de Compliance:
• Fracionamento (Structuring): Identificação de aglomerados de transações diárias abaixo de R$ 20k que somam mais de R$ 50k em múltiplos canais.
• Valores Atípicos (Outliers): Detecção de transações que superam $5\times$ a mediana individual do cliente (histórico $\ge 4$ operações).

🔹 Nível 1.1: Engenharia de Prompt e Otimização

Comparativo de performance utilizando o modelo gemini-3.5-flash:

• Versão 1 (Descritivo): Latência de ~59s | ~3.454 tokens consumidos.
• Versão 2 (Enxuto e Direto): Latência otimizada para ~27s (>50% de redução) | ~2.631 tokens (maior economia de custos e largura de banda).

🔹 Nível 2: Orquestrador e Agente Autônomo (Tool Calling)

• Implementação de agentes baseados em sessões de chat (client.chats.create) habilitados com funções Python nativas (consultar_resumo_cliente e verificar_alertas_compliance).
• O Gemini decide autonomamente quando consultar o DataFrame Pandas em tempo real para investigar clientes sinalizados.

🔹 Nível 3: Produção e Garantia de Schema (Pydantic Guardrails)

• Aplicação de response_schema com classes Pydantic (ParecerPLD), blindando a aplicação contra respostas fora do contrato e permitindo parsing seguro (model_validate_json) para consumo direto em microsserviços (FastAPI).

---

📝 Documentação Complementar

Para maiores detalhes sobre as escolhas de engenharia, justificativas de trade-offs e caminhos futuros de escalabilidade, consulte o arquivo DECISOES.md.