Motor de Modelagem de Risco de Crédito Agrícola (Credit Risk Engine) de alta performance.

Nota de Desenvolvimento: Este projeto é um estudo avançado de Arquitetura de Software (Modular Monolith) e Design Patterns (Strategy, Factory, Singleton).

Ele foi desenvolvido como um protótipo de alta complexidade com assistência de ferramentas de IA para acelerar a implementação de conceitos arquiteturais. O objetivo deste repositório é demonstrar visão sistêmica e capacidade de estruturar soluções robustas.

Modelos de crédito tradicionais (bancários) falham no agronegócio porque olham apenas para o passado (Bureaus/Serasa). Eles não detectam quando um produtor é tecnicamente solvente, mas está operacionalmente quebrado devido a fatores externos.

A Solução: Este motor implementa uma análise multidimensional em tempo real, correlacionando:

1. Mercado Global (CBOT): Volatilidade de preços e paridade de exportação.
2. Logística Local: Custo de frete e gargalos portuários (Risco de Base).
3. Climatologia: Impacto de anomalias hídricas na produtividade da safra.
4. Geopolítica (IA): Monitoramento de cisnes negros em cadeias de suprimento globais.

O resultado é um PD (Probability of Default) Dinâmico, capaz de prever crises de liquidez antes do vencimento dos contratos.

O sistema foi desenhado seguindo princípios de Modular Monolith, priorizando a integridade dos dados e a resiliência da ingestão.

• Ambiente Hermético (Nix & uv): Abandono do pip tradicional em favor do uv (Rust-based) e Nix, garantindo que o ambiente de desenvolvimento seja 100% reprodutível, bit-a-bit, em qualquer máquina.
• Ingestão Assíncrona Resiliente: O pipeline de dados (core/pipeline.py) utiliza asyncio e httpx com implementação manual de Semáforos para controle de concorrência (Backpressure) e Exponential Backoff para lidar com falhas de API externas.
• Design Patterns Aplicados:
  • Strategy Pattern: Para isolar regras de risco regionais (ex: MatoGrossoStrategy vs ParanaStrategy).
  • Factory Pattern: Para instanciar os motores de cálculo dinamicamente.
  • Singleton: Gerenciamento eficiente de conexões de banco de dados (core/db.py).
• Audit Trail: Todo dado ingerido possui rastreabilidade de fonte e timestamp, requisito fundamental para auditoria em instituições financeiras.

O coração do sistema (core/engine.py) opera uma máquina de estados baseada em 4 vetores de risco:

Calcula a probabilidade matemática de um produtor quebrar o contrato propositalmente.

• Lógica: Se Preço Atual > Preço Contratado + Multa E Produtividade < Break-even, o risco é máximo.
• Implementação: core/indicators/fundamental.py

Monitoramento antecipado de demanda via correlação cruzada.

• Lógica: O spread entre futuros de Suínos (Lean Hogs) e Farelo de Soja na China antecipa a demanda de exportação brasileira em ~3 semanas.

O risco climático é ponderado pelo calendário agrícola.

• Lógica: Uma seca de 10 dias em Janeiro (enchimento de grão) tem peso 5x maior no score do que uma seca em Abril (colheita).
• Implementação: core/seasonality.py

• Crush Margin: Viabilidade da indústria esmagadora.
• Efeito Tesoura: Relação de troca entre Receita (Soja) e Custo (Insumos/Petróleo).

O sistema possui um agente autônomo (core/scout.py) para análise de risco geopolítico:

• Monitoramento OSINT: Varredura contínua de feeds globais (Reuters, Google News).
• Zero-Shot Classification (BART): Utiliza LLMs via Hugging Face para classificar notícias em tempo real (ex: "Crise Logística", "Desastre Climático") sem necessidade de treinamento prévio.

Diferente de projetos acadêmicos, este motor possui um framework de validação temporal (core/backtest_engine.py) que:

• Walk-Forward Analysis: Simula a execução do modelo mês a mês sobre safras passadas.
• Point-in-Time Data: Garante que o modelo "não veja o futuro" (Look-ahead Bias), usando apenas dados disponíveis na data da simulação.
• Métricas de Risco: Calcula Expected Loss (Perda Esperada) e VaR (Value at Risk) da carteira simulada.

Este projeto utiliza ferramentas modernas. Certifique-se de ter o uv instalado.

1. Clone o repositório:

   git clone https://github.com/raphaelsoaresc/agro-risk-engine.git cd agro-risk-engine

2. Configuração de Ambiente: Crie um arquivo .env na raiz (baseado no .env.example).

   Nota: O sistema possui fallbacks para dados sintéticos caso as chaves de API (Supabase/WeatherAPI) não estejam presentes, permitindo a execução da demo.

3. Instalação de Dependências: Utilizando o pyproject.toml para gerenciar o ambiente:

   # 1. Cria o ambiente virtual uv venv # 2. Ativa o ambiente (Linux/Mac) source .venv/bin/activate # (No Windows use: .venv\Scripts\activate) # 3. Instala o projeto em modo editável com dependências de dev uv pip install -e ".[dev]"

4. Seed de Dados (Simulação): Popula o banco com uma carteira de crédito fictícia para teste de estresse.

   uv run python -m scripts.seed_portfolio

5. Execução do Pipeline:

   uv run python main.py --mode watch

• Linguagem: Python 3.10+
• Gerenciamento de Pacotes: uv (Astral)
• Ambiente: Nix (via devenv)
• Banco de Dados: PostgreSQL (Supabase)
• Bibliotecas Chave: Pandas, NumPy, Pydantic, HTTPX, AsyncIO.

Autor: Raphael Soares Data Engineer & Software Architect LinkedIn | Portfolio