new feature: External guardrails/judges

config/guardrails.yaml

@@ -10,14 +10,14 @@ input:
   - {code: VLOOP, enabled: true}
 
 output:
-  - {code: OOS, enabled: true}
-  - {code: AOFERTA, enabled: true}
-  - {code: REVPREC, enabled: true}
-#  - {code: FRASEOLOGIA, enabled: true}
+  - {code: TIM_OOS, type: external, class: app.extensions.tim_guardrails:TimOutOfScopeRail, enabled: true}
+  - {code: TIM_AOFERTA, type: external, class: app.extensions.tim_guardrails:TimProactiveOfferRail, enabled: true}
+  - {code: TIM_REVPREC, type: external, class: app.extensions.tim_guardrails:TimPrematureActionRail, enabled: true}
+#  - {code: TIM_FRASEOLOGIA, type: external, class: app.extensions.tim_guardrails:TimPhraseologyRail, enabled: true}
   - {code: PINJ, enabled: true}
   - {code: DLEX_OUT, enabled: true}
   - {code: TOXOUT, enabled: true}
-  - {code: CMP, enabled: true}
+  - {code: CMP, enabled: true, on_deny: retry}
   - {code: GND, enabled: true}
   - {code: ALUC_RISK, enabled: true}
 
@@ -27,3 +27,8 @@ retrieval:
 
 tool:
   - {code: TOOL_VAL, enabled: true}
+
+output_supervisor:
+  max_retries: 3
+  fallback_message: "Não consegui validar essa resposta com segurança. Posso reformular a resposta."
+  handover_message: "Vou encaminhar seu atendimento para continuidade com um especialista."

config/judges.yaml

@@ -2,7 +2,7 @@ enabled: true
 fail_closed: true
 profile: judge
 judges:
-  - {name: response_quality, enabled: true, threshold: 0.70}
-  - {name: groundedness, enabled: true, threshold: 0.60}
+  - {name: tim_response_quality, type: external, class: app.extensions.tim_judges:TimResponseQualityJudge, enabled: true, threshold: 0.70}
+  - {name: tim_groundedness, type: external, class: app.extensions.tim_judges:TimGroundednessJudge, enabled: true, threshold: 0.60}
 sample_rate: 0.10
 always_run_for_transactional: true

config/observability_mapping.yaml

@@ -0,0 +1,50 @@
+version: "2"
+
+# Registro canônico de observabilidade + compatibilidade de guardrails do Contas.
+#
+# Formas aceitas:
+#   guardrail.x: GRL.999                   # somente label externo (compatível com v1)
+#   guardrail.x: {action: retry}           # somente política de execução
+#   guardrail.x:                           # ambos + aliases
+#     label: GRL.999
+#     action: retry
+#     aliases: [X, OUTRO_X]
+#
+# Precedência para ação quando um rail nega a resposta:
+#   1) terminal_action explícito retornado pelo rail
+#   2) on_deny do guardrails.yaml
+#   3) action deste arquivo
+#   4) BLOCK (fail-safe)
+#
+# Códigos sem entrada passam pela observabilidade sem alteração.
+mappings:
+  # Contrato externo solicitado para este agente.
+  guardrail.dlex_in:
+    label: GRL.004
+    aliases: [DLEX_IN]
+
+  guardrail.tox:
+    label: GRL.005
+    aliases: [TOX]
+
+  # Compatibilidade histórica de ações do framework. Sem label: o nome
+  # observável continua sem alteração, mas a ação é resolvida pelo registry.
+  guardrail.revprec:
+    action: retry
+    aliases: [REVPREC, TIM_REVPREC]
+
+  guardrail.cmp:
+    action: retry
+    aliases: [CMP]
+
+  guardrail.sco:
+    action: retry
+    aliases: [SCO]
+
+  guardrail.gnd:
+    action: retry
+    aliases: [GND]
+
+  guardrail.handover:
+    action: handover
+    aliases: [HANDOVER, ATH, HUMAN]

config/tim_integration_defaults.yaml

@@ -0,0 +1,31 @@
+# Defaults de contrato legado TIM externalizados do Python.
+# Variáveis de ambiente têm precedência sobre estes valores.
+TIM_COMPLETE_INVOICES_CLIENT_ID: AIAGENTCR
+TIM_DIVERGENCIA_CLIENT_ID: AIAGENTCR
+TIM_DEFAULT_CHANNEL: AIAGENTCR
+TIM_CONSULTA_CLIENT_ID: AIAAGENTCR
+TIM_VAS_HISTORY_CLIENT_ID: AIAGENTCR
+TIM_DEFAULT_CSP_ID: "740"
+TIM_BLOCK_CLIENT_ID: AIAGENTCR
+TIM_BLOQUEIO_CLIENT_ID: AIAGENTCR
+TIM_CANCELAMENTO_CLIENT_ID: AIAGENTCR
+TIM_CONTRATO_CLIENT_ID: AIAGENTCR
+TIM_PROFILE_FULL_CLIENT_ID: AIAGENTCR
+TIM_DEFAULT_SOURCE: AIAGENTCR
+TIM_PROTOCOL_CLIENT_ID: BFFDIGITAL
+TIM_CUSTOMER_CONTESTATION_USER_ID: AIAGENTCR
+TIM_CUSTOMER_CONTESTATION_CLIENT_ID: AIAGENTCR
+TIM_SERVICE_REQUEST_STATUS_CLIENT_ID: AIAGENTCR
+TIM_TRACKING_ACTIVITIES_CHANNEL: AIAGENTCR
+TIM_TRACKING_ACTIVITIES_USER_LOGIN: SIEBELPOS_INBOUND
+TIM_TRACKING_ACTIVITIES_CLIENT_ID: AIAGENTCR
+TIM_SMS_SENDER_NAME: TIM Brasil
+TIM_SMS_CLIENT_ID: AIAGENTCR
+TIM_BILL_PDF_CLIENT_ID: AIAGENTCR
+TIM_SECURE_PDF_CLIENT_ID: AIAGENTCR
+TIM_INVOICE_RECOVER_CLIENT_ID: AIAGENTCR
+TIM_SMS_LONG_URL: https://meutim.com.br
+TIM_SMS_NOTIFY_URL: http://10.114.200.57:9003/teste
+TIM_DIVERGENCIA_CHANNEL: AIAGENTCR
+TIM_CANCELAMENTO_CHANNEL: AIAGENTCR
+TIM_PROTOCOL_CHANNEL: AIAGENTCR