ajuste no guardraild COE

tests/docs/EXTERNAL_GUARDRAILS_JUDGES.md

@@ -0,0 +1,71 @@
+# Guardrails e Judges externos — Contas
+
+## Objetivo
+O `agent_framework_oci` mantém apenas mecanismos e políticas realmente genéricos. O agente Contas mantém políticas, exemplos e prompts que conhecem TIM, Contas, VAS, fatura, cancelamento ou nomenclaturas comerciais.
+
+## Regra arquitetural
+- **Framework:** engine, contratos, execução paralela, fail-fast, telemetria, carregamento YAML e implementações genéricas.
+- **Agente:** prompts/policies de domínio e classes externas.
+- Um componente externo só é importado quando o YAML do agente declara `type: external`.
+- Guardrails/judges nativos continuam funcionando sem qualquer alteração de configuração.
+
+## Configuração de guardrail externo
+```yaml
+output:
+  - code: TIM_AOFERTA
+    type: external
+    class: app.extensions.tim_guardrails:TimProactiveOfferRail
+    enabled: true
+```
+O código `TIM_AOFERTA` deixa explícito que esta política é do agente Contas. O framework continua podendo oferecer `AOFERTA` como rail genérico para outros agentes.
+
+## Configuração de judge externo
+```yaml
+judges:
+  - name: tim_groundedness
+    type: external
+    class: app.extensions.tim_judges:TimGroundednessJudge
+    enabled: true
+    threshold: 0.60
+```
+
+## Concorrência e threads
+O `ParallelRailExecutor` executa todos os rails concorrentemente. `evaluate()` assíncrono roda no event loop; plugin síncrono roda por `asyncio.to_thread`, portanto não bloqueia o loop. Judges nativos e externos são disparados com `asyncio.gather`; judges síncronos também são deslocados para `asyncio.to_thread`. A ordem da lista de resultados permanece a ordem do YAML.
+
+## Compatibilidade
+A extensão é aditiva. Entradas antigas como `{code: PINJ}` e `{name: groundedness}` seguem nativas. Somente itens com `type: external` usam import dinâmico. Isso evita dependência reversa do framework para `app.*`.
+
+## Mapeamento nesta versão do Contas
+| Genérico no framework | Específico no Contas | Motivo |
+|---|---|---|
+| OOS | TIM_OOS | escopo do Contas/TIM |
+| AOFERTA | TIM_AOFERTA | política de oferta do atendimento TIM |
+| REVPREC | TIM_REVPREC | exemplos e ações transacionais TIM |
+| FRASEOLOGIA | TIM_FRASEOLOGIA | fraseologia própria (mantido desabilitado como antes) |
+| response_quality | tim_response_quality | prompt original do auditor Contas |
+| groundedness | tim_groundedness | prompt original de alucinação/grounding do Contas |
+
+Os prompts originais foram preservados em `app/extensions/tim_prompts/`. As versões sob `agent_framework/.../calibrated/prompts` foram generalizadas e não devem conter nomes comerciais TIM.
+
+## Como criar um novo componente
+1. Implemente uma classe no agente com `evaluate(...)`.
+2. Para guardrail, retorne `RailDecision`/`RailResult`; para judge, retorne `JudgeResult`.
+3. Declare `type: external` e o caminho `module:Class` no YAML.
+4. Não crie cliente LLM próprio: use o `llm` fornecido pelo framework/contexto para manter `llm_profiles.yaml`, Langfuse e contabilização.
+5. Teste convivência com os rails/judges nativos e o comportamento fail-closed.
+
+## Hardcodes de integração do Contas
+Os valores legados de `clientId`, `channel`, `cspId`, sender e URLs que antes apareciam como fallback em Python foram movidos para `config/tim_integration_defaults.yaml`. A precedência é:
+
+1. variável de ambiente;
+2. `config/tim_integration_defaults.yaml`;
+3. default explícito somente quando a chamada realmente define um default técnico.
+
+Isso preserva contratos diferentes por operação (`TIM_CANCELAMENTO_CHANNEL`, `TIM_DIVERGENCIA_CHANNEL`, etc.) sem usar um `TIM_DEFAULT_*` que altere silenciosamente o legado.
+
+## Validação de contestação
+`validate_contestation_items` é regra do domínio Contas e agora vive em `app/domain/contas/contestation_validation.py`. O módulo antigo no framework existe apenas como shim de compatibilidade/depreciação; código novo do Contas importa a implementação do agente diretamente.
+
+## Observabilidade dos códigos externos
+
+O código semântico de um guardrail/judge externo não deve ser alterado para atender um código numérico de um cliente. Use `config/observability_mapping.yaml` para o contrato de telemetria. Exemplo: a extensão pode continuar emitindo `GRL.TOXOUT`, enquanto o contrato publica `GRL.004`. Isso mantém a política do agente separada do catálogo externo de observabilidade.