🏠 Início / 📚 Documentação / Guias de Uso / Checklist Trust Agent

Checklist Trust Agent

✅ Checklist: Trust Agent

Status: 🟢 Implementado e Deployado em DEV
Prioridade: 1 (INFRAESTRUTURA - alimenta Credit, Pricing, NBA, CRO)
Estimativa: 2-3 semanas
Versão do Modelo: v1.1 (com Evidence/Confidence)
Implementado em: 2026-01-25

📋 Resumo

Item Valor
Código trust
Porta 8012
Database csuite_context
Prefixo API /v1/trust
Traefik Path /trust/
Consumidores Credit, Pricing, NBA, CRO, Account-State

🎯 Objetivo

Calcular o Trust State (TS) unificado de cada cliente/revenda baseado em eventos comportamentais. É o "motor de reputação" do canal - outros agentes consomem esse estado para decisões de crédito, pricing, exceções e priorização.

Frase-guia: Confiança não é binária. Confiança é memória comportamental com contexto, tempo e intensidade.

⚡ Avaliação Externa (Trust Systems Evolution)

Avaliação técnica do modelo pelo ChatGPT (Janeiro 2026):

Dimensão Nota
Conceito 9.5/10
Matemática 8.5/10
Arquitetura 9/10
Governança 10/10
Prontidão Prod 7.5/10

🔧 Ajustes Críticos Incorporados (v1.1)

  1. ✅ Half-life interpretável - wₑ = 2^(-delta/h) ao invés de exp(-delta/τ)
  2. ✅ Volatilidade direcional - Piora errática pesa mais que melhora errática
  3. ✅ Dívida com decay - Ledger de pendências com "cura" temporal
  4. ✅ Evidence/Confidence - Metadado epistemológico (quanta evidência sustenta o TS)

🔥 Prod-Footgun Fixes (v1.1.1)

Identified during architecture review. These prevent production failures.

Fix Issue Solution Status
#1 ADD COLUMN IF NOT EXISTS fails on many MySQL 8.x variants Safe migration via information_schema + dynamic SQL ✅ migrate_v11_safe.sql
#2 Trend slope depends on trust_history (chicken/egg on new accounts) Fallback to event-based trend estimator when history < 3 points ✅ calculator_v11.py
#3 Evidence K=10 hardcoded can lie as event types change K (event_types_total) stored in trust_config, computed from weights ✅ calculator_v11.py

🧠 Modelo Matemático v1.1

1. Entrada: Eventos Comportamentais

Tipo de Evento Código Impacto Base (aₖ)
Pagamento no prazo PAY_ON_TIME +2
Atraso de pagamento LATE_PAYMENT -4
Chargeback CHARGEBACK -6
Devolução RETURN -3
Reclamação COMPLAINT -2
Recompra REPURCHASE +1
Crescimento relevante GROWTH +3
Exceção solicitada EXCEPTION_REQ -1
Exceção aprovada EXCEPTION_OK 0
Exceção negada EXCEPTION_DENIED 0

2. Fórmulas v1.1

Decay Temporal (Half-Life Interpretável) ⭐ NOVO

wₑ = 2^(-(T - tₑ) / h)

Onde h = 90 dias (evento perde metade do peso a cada 90 dias)

Por que mudou? Half-life é mais interpretável e calibrável que τ mágico.

Contribuição do Evento

vₑ = aₖ₍ₑ₎ × sₑ × log(1 + xₑ)

Onde:
- aₖ₍ₑ₎ = impacto base do tipo de evento
- sₑ = severidade [0,1]
- xₑ = exposição (valor do pedido, custo, horas)

Contribuição Ponderada

uₑ = wₑ × vₑ

Reputação Bruta

R*(c) = Σ uₑ  (para todos os eventos de c)

Reputação Normalizada (0-100)

R(c) = 100 × σ((R*(c) - μ) / β)

3. Volatilidade Direcional v1.1 ⭐ NOVO

Trend (slope da regressão linear)

trend = slope(TS nos últimos W dias)

Fonte de dados: trust_history (snapshots diários).

Fallback: Se < 3 snapshots, usa estimador baseado em eventos recentes:
- Calcula net(weighted_contributions) dos últimos 30 dias
- pseudo_slope = net / 30

Classificação:
- IMPROVING se slope > ε
- DECLINING se slope < -ε
- STABLE caso contrário

Fator Multiplicador Direcional

m(trend) = {
    1.25  se DECLINING   ← piora pesa mais
    1.00  se STABLE
    0.85  se IMPROVING   ← melhora atenua
}

Penalidade de Volatilidade Final

V = Var({uₑ} na janela W)
pᵥ = σ((V - μᵥ) / βᵥ)
PenV = λᵥ × 100 × pᵥ × m(trend)

Por que mudou? Instabilidade durante queda vira alerta real; instabilidade durante recuperação não "mata" o cliente.

4. Dívida Comportamental com Decay v1.1 ⭐ NOVO

Itens de Dívida (Ledger)

Cada item tem:
- severidade qₐ ∈ [0,1]
- exposição yₐ ≥ 0 (horas/custo)
- data de criação tₐ
- status: OPEN/CLOSED

Peso Temporal da Dívida

gₐ = 2^(-(T - tₐ) / hD)

Onde hD = 30 dias (dívida "cura" mais rápido que reputação)

Score de Dívida

D*(c) = Σ gₐ × qₐ × log(1 + yₐ)
D(c) = 100 × σ((D*(c) - μD) / βD)
PenD = λD × D(c)

Por que mudou? Dívida estática cria clientes "condenados eternos". Agora promessa cumprida "cura" dívida.

5. Trust State Final v1.1

TS(c) = clamp₀₋₁₀₀(R(c) - PenV - PenD)

6. Evidence/Confidence ⭐ NOVO (CRÍTICO)

Sem isso, o TS "mente" - decisões baseadas em pouca evidência parecem super-confiantes.

Componentes

Eₙ = 1 - exp(-N₉₀ / kₙ)           ← quantidade de eventos (saturação)
Eₐᵢᵥ = H / ln(K)                   ← entropia normalizada (diversidade)
Eᵣₑc = média dos pesos wₑ          ← recência média

E(c) = 0.5×Eₙ + 0.3×Eₐᵢᵥ + 0.2×Eᵣₑc

Onde:
- N₉₀ = nº de eventos nos últimos 90 dias
- kₙ = 12 (com 12 eventos você já tem base ok)
- H = entropia da distribuição de tipos de evento
- K = event_types_total from trust_config.evidence_v11 (derivado de len(event_weights_v11))

Comportamento quando E < 0.40 (Low Evidence Gate)

Obrigatório: Se evidência é baixa, aplicar conservadorismo automático:

Métrica Ajuste
pd pd := max(pd, 0.08) (floor)
credit_limit credit_limit := credit_limit × 0.6
exception_eligibility.conservative true
Adjudicator recebe flag low_evidence = true

7. Derivações

Métrica Fórmula Uso
PD (Prob. Inadimplência) σ(αₚₐ - βₚₐ × TS/100 + γₚₐ × Stress) Credit Agent
Limite de Crédito BaseLimit × (1 - η × PD) × (1 + κ × (TS-50)/50) Credit Agent
CLV Σ E[GMₜ] × Retₜ / (1+r)ᵗ com Retₜ ligado a TS NBA, CRO
RiskScore 100 × σ((EL - μₑₗ) / βₑₗ) Todos

⚠️ Low Evidence Gate: Se E < 0.40, aplicar ajustes conservadores (ver seção 6).

8. Parâmetros Default v1.1

Parâmetro Valor Descrição
h 90 dias Half-life eventos
hD 30 dias Half-life dívida
W 30 dias Janela volatilidade/trend
ε 0.05 TS/dia Threshold slope trend
λᵥ 0.30 Peso volatilidade
λD 0.20 Peso dívida
μ 0 Centro sigmóide
β 3 Inclinação sigmóide
μᵥ 0.5 Centro vol sigmóide
βᵥ 0.3 Inclinação vol sigmóide
μD 0.0 Centro dívida sigmóide
βD 2.0 Inclinação dívida sigmóide
kₙ 12 Saturação eventos

📊 Trust State Faixas

TS Classificação Cor Comportamento
80-100 🥇 Ouro #f6d365 Flexibilização máxima
65-79 🥈 Prata #667eea Aprovação com condições
50-64 🥉 Bronze #f093fb Exceções pequenas + escalonamento
35-49 ⚠️ Alerta #fa709a Monitoramento ativo
0-34 🚨 Crítico #ff0844 Negação/pagamento antecipado

✅ Fases de Implementação

Fase 1: Estrutura Base ✅

Fase 2: Schema SQL ✅

Fase 3: Modelos Python ✅

Fase 4: Repository (Queries) ✅

Fase 5: Calculator (Motor Matemático) ✅

Fase 6: Heuristics (Lógica de Decisão) ✅

Fase 7: Routes/API ✅

Fase 8: Exception Adjudicator (Sub-agente LLM)

Fase 9: Policies ✅

Fase 10: Scheduler/Batch

Fase 11: Docker ✅

Fase 12: Deploy DEV

Fase 13: Integração com Outros Agentes

Credit Agent

Pricing Agent

NBA Agent

Account-State Agent

Fase 14: Integração Seller Cockpit (Backend)

Fase 15: Integração Seller Cockpit (Frontend)

Fase 16: Documentação ✅

Fase 17: Testes

📁 Estrutura de Arquivos

trust/
├── .env.example          ✅
├── Dockerfile            ✅
├── README.md             ✅
├── deploy.sh             ✅
├── docker-stack.yml      ✅
├── main.py               ✅
├── requirements.txt      ✅
├── app/
│   ├── __init__.py       ✅
│   ├── adjudicator.py    ⏳ Pendente
│   ├── batch.py          ⏳ Pendente
│   ├── calculator.py     ✅ (precisa v1.1 updates)
│   ├── database.py       ✅
│   ├── heuristics.py     ✅
│   ├── models.py         ✅ (precisa v1.1 updates)
│   ├── repository.py     ✅ (precisa v1.1 updates)
│   └── settings.py       ✅
├── policies/
│   ├── __init__.py       ✅
│   ├── adjudication.py   ✅
│   ├── tiers.py          ✅
│   └── weights.py        ✅
├── routes/
│   ├── __init__.py       ✅
│   ├── alerts.py         ✅
│   ├── core.py           ✅
│   ├── derivatives.py    ✅
│   ├── events.py         ✅
│   ├── exceptions.py     ⏳ Pendente
│   └── scores.py         ✅
└── sql/
    ├── schema.sql        ✅ (precisa v1.1 updates)
    └── views.sql         ✅

🔌 API Endpoints

Eventos

Método Endpoint Descrição
POST /v1/trust/events/record Registrar evento
POST /v1/trust/events/record/bulk Registrar múltiplos
GET /v1/trust/events/{account_id} Listar eventos

Scores

Método Endpoint Descrição
GET /v1/trust/score/{account_id} Score completo
POST /v1/trust/score/evaluate Forçar recálculo
GET /v1/trust/score/by-tier/{tier} Listar por tier
GET /v1/trust/history/{account_id} Histórico
GET /v1/trust/summary Dashboard

Derivações (para outros agentes)

Método Endpoint Descrição
GET /v1/trust/credit/{account_id} View para Credit
GET /v1/trust/clv/{account_id} View para NBA/CRO
GET /v1/trust/risk/{account_id} View de risco
GET /v1/trust/exception-eligibility/{account_id} Pode pedir exceção?

Exceções

Método Endpoint Descrição
POST /v1/trust/exceptions/adjudicate Avaliar exceção
GET /v1/trust/exceptions/log Histórico de decisões

Alertas

Método Endpoint Descrição
GET /v1/trust/alerts/declining TS caindo
GET /v1/trust/alerts/risk RiskScore alto

📊 Schema SQL v1.1

⚠️ DO NOT copy/paste raw ALTER statements. Use the safe migration script.

Migration

# Run this to apply v1.1 schema changes safely
mysql -h $MYSQL_HOST -u $MYSQL_USER -p $MYSQL_DB < sql/migrate_v11_safe.sql

File: sql/migrate_v11_safe.sql

The migration script:
1. Uses information_schema checks + dynamic SQL (no IF NOT EXISTS traps)
2. Adds columns: evidence_confidence, trend_slope, penalty_volatility, penalty_debt, debt_raw, debt_normalized
3. Creates table: trust_debt_items (debt ledger)
4. Seeds trust_config with v1.1 parameters including event_types_total

🎨 Cores dos Tiers (Frontend)

.tier-gold { 
    background: linear-gradient(135deg, #f6d365 0%, #fda085 100%); 
    color: #333;
}
.tier-silver { 
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); 
    color: #fff;
}
.tier-bronze { 
    background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%); 
    color: #fff;
}
.tier-alert { 
    background: linear-gradient(135deg, #fa709a 0%, #fee140 100%); 
    color: #333;
}
.tier-critical { 
    background: linear-gradient(135deg, #ff0844 0%, #ffb199 100%); 
    color: #fff;
}

🔗 Exemplo de Resposta da API v1.1

GET /v1/trust/score/{account_id}

{
  "account_id": "7781",
  "trust_state": 72,
  "tier": "SILVER",
  "tier_label": "Prata",
  "tier_color": "#667eea",

  "evidence_confidence": 0.81,

  "reputation": {
    "raw": 8.42,
    "normalized": 75,
    "volatility": 0.18,
    "volatility_penalty": 6.2
  },

  "debt": {
    "raw": 1.4,
    "normalized": 14,
    "penalty": 2.8
  },

  "derivatives": {
    "pd": 0.06,
    "suggested_credit_limit": 85000.00,
    "clv_12m": 185000.00,
    "risk_score": 41,
    "expected_loss": 5100.00
  },

  "trend": "DECLINING",
  "trend_slope": -0.08,
  "trend_30d": {
    "start_ts": 76,
    "end_ts": 72,
    "delta": -4,
    "direction": "DECLINING"
  },

  "penalties": {
    "volatility": 6.2,
    "debt": 2.8
  },

  "exception_eligibility": {
    "eligible": true,
    "max_discount_pct": 4.0,
    "max_terms_days": 56,
    "reason": "TS >= 65 e PD <= 0.08",
    "conservative": false
  },

  "events_summary": {
    "total_90d": 12,
    "positive": 8,
    "negative": 4,
    "last_event_at": "2026-01-24T10:30:00Z"
  },

  "last_calculated_at": "2026-01-25T00:00:00Z"
}

⚠️ Riscos Arquiteturais (do documento de avaliação)

🔥 Trust Agent pode virar gargalo de escrita

Problema: Muitos eventos frequentes + recálculos + snapshots → gargalo

Solução:
1. Event write é append-only (sem locks)
2. Cálculo é assíncrono (fila ou batch)
3. API de score sempre lê último snapshot válido (cache)

"Se tentar calcular síncrono em produção, vai doer."

✅ Critérios de Conclusão

📚 Referências

📋 Próximos Passos (Ordem Recomendada)

  1. ✅ ~~Congelar modelo matemático v1.1~~
  2. 🔄 Implementar updates v1.1 no calculator.py
  3. 🔄 Executar schema SQL no RDS DEV
  4. ⏳ Implementar Exception Adjudicator
  5. ⏳ Plugar Pricing / Credit

"Esse Trust Agent, bem feito, vira o sistema nervoso do CSuite. Não é mais feature. É fundação."

Criado: 2026-01-25
Atualizado: 2026-01-25 (v1.1 com Evidence/Confidence)

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir