wise-decision-engine 0.2.9

Uma abstração moderna e inteligente para zen-engine com otimizações avançadas para Spark/Databricks

🧠 Wise Decision Engine

Motor de decisão que separa a definição das regras de negócio do seu local de processamento

---

💼 Problema de Negócio

Em ambientes corporativos, as regras de negócio mudam constantemente mas estão frequentemente acopladas ao código de processamento. Isso gera:

• ⏳ Demora para mudanças: Alterações simples requerem deploy completo
• 🔄 Dependência técnica: Regras de negócio presas no pipeline de dados
• 🚫 Falta de governança: Regras espalhadas e sem controle centralizado
• 💸 Alto custo de manutenção: Equipe técnica para mudanças de negócio

🎯 Solução: Separação de Responsabilidades

O Wise Decision Engine permite:

🏛️ DEFINIÇÃO DA REGRA	⚙️ PROCESSAMENTO DOS DADOS
Armazenada em tabelas/arquivos	Executado em Spark/Databricks
Modificável por analistas	Gerenciado por engenheiros
Governança centralizada	Performance otimizada
Versionamento de regras	Processamento distribuído

🔧 Como Funciona

1. Defina a Regra (Uma vez)

// Salva em tabela Databricks ou arquivo JSON
{
  "name": "aprovacao-credito",
  "rules": {
    "if": [{"var": "renda"}, ">", 5000],
    "then": {"aprovado": true, "limite": 10000},
    "else": {"aprovado": false, "limite": 0}
  }
}

2. Processe os Dados (Sempre que necessário)

from wise_decision_engine import DatabricksHelper

# Uma linha aplica a regra para milhões de registros
resultado = DatabricksHelper.quick_decision_apply(
    catalog="regras_catalog",
    schema="public", 
    table="decisoes",
    decision_name="aprovacao-credito",
    input_df=clientes_df  # DataFrame com milhões de clientes
)

# ✅ Resultado: DataFrame com decisões aplicadas automaticamente
resultado.show()

3. Mude a Regra (Sem redeploy)

-- Analista de negócio altera diretamente na tabela
UPDATE regras_catalog.public.decisoes 
SET content = '{"rules": {"if": [{"var": "renda"}, ">", 8000], ...}}'
WHERE name = 'aprovacao-credito';

-- ✅ Próxima execução já usa a nova regra (cache automático)

📦 Instalação

pip install wise-decision-engine

🚀 Casos de Uso Reais

Aprovação de Crédito

# Regra armazenada em tabela Databricks
# Processamento em Spark para milhões de clientes
resultado = DatabricksHelper.quick_decision_apply(
    "financeiro_catalog", "regras", "decisoes",
    "aprovacao-pf", clientes_df
)

Detecção de Fraude

# Mesma interface, regra diferente
# Analista atualiza regra sem código
resultado = DatabricksHelper.quick_decision_apply(
    "risco_catalog", "regras", "decisoes", 
    "deteccao-fraude", transacoes_df
)

Precificação Dinâmica

# Regras de pricing atualizadas em tempo real
resultado = DatabricksHelper.quick_decision_apply(
    "comercial_catalog", "regras", "decisoes",
    "precificacao-produto", vendas_df
)

🎯 Benefícios de Negócio

Para Analistas de Negócio

• ✅ Autonomia total: Alteram regras sem depender de TI
• ✅ Versionamento: Histórico completo de mudanças
• ✅ Teste A/B: Diferentes versões de regras facilmente
• ✅ Governança: Controle centralizado de todas as regras

Para Engenheiros de Dados

• ✅ Menos deploy: Mudanças de regra não requerem código
• ✅ Performance: Processamento otimizado para Spark
• ✅ Manutenibilidade: Código limpo e desacoplado
• ✅ Escalabilidade: Engine preparada para big data

Para Organização

• 💰 Redução de custos: 80% menos tempo para mudanças
• ⚡ Time-to-market: Novas regras em minutos, não semanas
• 🔒 Compliance: Auditoria completa de regras aplicadas
• 📈 Agilidade: Resposta rápida a mudanças de mercado

🏗️ Arquitetura da Solução

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   📋 REGRAS     │    │  🔄 PROCESSING   │    │  📊 RESULTADO   │
│                 │    │                  │    │                 │
│ • Tabela Delta  │───▶│ • Spark Engine   │───▶│ • DataFrame     │
│ • Arquivos JSON │    │ • Cache Auto     │    │ • Schema Auto   │
│ • Versionadas   │    │ • UDFs Otimizas  │    │ • Performance   │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Separação Clara de Responsabilidades

• 📋 Camada de Regras: Definição e governança (Analistas)
• 🔄 Camada de Processamento: Performance e escala (Engenheiros)
• 📊 Camada de Resultado: Consumo e análise (Usuários finais)

⚙️ Configuração Avançada

Adapters Disponíveis

from wise_decision_engine import WiseDecisionEngine, DatabricksAdapter, FileAdapter

# Para tabelas Databricks
adapter = DatabricksAdapter(
    catalog="meu_catalog",
    schema="regras", 
    table="decisoes"
)

# Para arquivos JSON locais
adapter = FileAdapter(file_path="/path/to/rules.json")

# Engine configurável
engine = WiseDecisionEngine(adapter=adapter)

💡 Exemplo Completo

Notebook Databricks

# 1. Instalar
%pip install wise-decision-engine

# 2. Aplicar decisão
from wise_decision_engine import DatabricksHelper

resultado = DatabricksHelper.quick_decision_apply(
    catalog="regras_catalog",
    schema="public", 
    table="decisoes",
    decision_name="minha-regra",
    input_df=meus_dados_df
)

# 3. Visualizar resultado
resultado.display()

🤝 Contribuição e Suporte

Repositório

• Código: GitHub
• Issues: Reportar problemas
• Documentação: Wiki

Como Contribuir

1. Fork o repositório
2. Crie sua feature branch
3. Commit suas mudanças
4. Abra um Pull Request

---

📄 Licença

MIT License - veja LICENSE para detalhes.

Construído pela Five Acts 🎆