new feature: LOCALE pt-BR/en

LOCALIZACAO.md

@@ -0,0 +1,133 @@
+# Termos e frases configuráveis — pt-BR e en
+
+Esta distribuição inclui dois catálogos completos, em JSON UTF-8:
+
+- `libs/agent_framework/src/agent_framework/locales/pt-BR.json`
+- `libs/agent_framework/src/agent_framework/locales/en.json`
+
+Cada arquivo reúne termos reconhecidos, mensagens padronizadas, instruções de
+recuperação de guardrails e padrões de extração. JSON permite editar o catálogo
+sem uma dependência adicional no carregador. Os dois arquivos usam as mesmas chaves.
+
+## Selecionar o idioma
+
+No `.env` do backend:
+
+```dotenv
+AGENT_LOCALE=en
+```
+
+Para português, use `AGENT_LOCALE=pt-BR` ou omita a variável. Também são aceitos
+`pt`, `pt_BR`, `en-US` e `en-GB`. Uma opção inexistente gera erro; não há troca
+silenciosa para português quando o idioma solicitado não está disponível.
+
+O idioma é o padrão do backend. Os prompts e as configurações de negócio dos
+agentes continuam sendo definidos pelo projeto; use prompts e descrições no
+idioma desejado. Esta alteração não traduz automaticamente conteúdos de RAG,
+respostas dos servidores MCP, mensagens declaradas por um workflow, arquivos de
+exemplo, regras de negócio ou textos personalizados do aplicativo/frontend.
+Prompts internos de classificação podem continuar em português: as decisões são
+estruturadas. As instruções de recuperação que impunham português foram separadas
+nos catálogos, incluindo sua variante em inglês.
+
+## Personalizar sem alterar a biblioteca
+
+Copie os catálogos para um diretório da aplicação e configure:
+
+```dotenv
+AGENT_LOCALE=en
+AGENT_LOCALES_DIR=./config/locales
+```
+
+Nesse exemplo, o arquivo usado será `./config/locales/en.json`. O catálogo é
+completo, e não um arquivo de alterações parciais. Preserve as chaves e os campos
+como `{action}`, `{target}`, `{options}` e `{subject}` ao traduzir as frases.
+Não é necessário manter a mesma quantidade de termos nas listas.
+
+Reinicie o backend após editar os arquivos: o carregador mantém os catálogos em
+cache. Na inicialização, ele verifica a estrutura, os campos das mensagens, a
+sintaxe dos padrões e conflitos entre confirmação e recusa.
+
+As principais seções são:
+
+| Seção | Conteúdo |
+|---|---|
+| `terms.confirmation` | Confirmações e recusas explícitas de transações |
+| `terms.workflow` | Respostas de compatibilidade para checkpoints antigos |
+| `terms.multi_intent` | Conjunções, verbos e prefixos de confirmação |
+| `terms.global_router` | Termos de continuidade e encerramento |
+| `terms.groundedness` | Indícios de especificidade e incerteza |
+| `terms.mock` | Termos dos classificadores locais usados em testes/desenvolvimento |
+| `messages` | Frases de confirmação, nova tentativa, esclarecimento e fallback |
+| `prompts.fallback` | Instruções de reescrita e regeneração por guardrail |
+| `prompts.judge_rewrite` | Instruções de recuperação dos judges |
+| `memory` | Padrões para extração de memória de longo prazo |
+| `protocol` | Dígitos, letras e nomes usados na vocalização de protocolos |
+| `safety` | Padrões determinísticos de segurança e escopo |
+| `legacy_extraction` | Padrões do extrator legado de pedido/motivo |
+
+## Decisões internas e contratos de workflow
+
+Os códigos internos permanecem estáveis: `confirm`, `reject`, `SIM`, `NAO`,
+`OUTRO` e nomes de estados não devem ser traduzidos em arquivos existentes.
+O catálogo trata as palavras reconhecidas e os textos apresentados.
+
+Um workflow que declara `expected_input`, `reprompt` ou mensagens próprias
+continua tendo precedência. Para aceitar `YES` e `NO` em um contrato enumerado,
+configure essas opções no workflow e ajuste suas transições, ou mantenha os
+códigos atuais e use seu classificador semântico para mapear as respostas.
+O dicionário global não substitui silenciosamente o contrato de um fluxo.
+
+As listas de confirmação transacional usam correspondência da frase completa,
+ignorando maiúsculas, espaços repetidos e pontuação final simples. Não inclua
+frases ambíguas como “entendi”/“understood” nessas listas: compreender uma
+explicação não equivale a autorizar uma operação. O fallback semântico existente
+continua disponível para respostas que não constam do catálogo.
+
+Os padrões de segurança mantêm cobertura em português e inglês nos dois arquivos.
+Nomes de concorrentes presentes em `safety` preservam a configuração original de
+telecom; adapte essas regras quando mudar o domínio da aplicação.
+
+## Vários idiomas no mesmo processo
+
+Para aplicações que selecionam o idioma por agente ou atendimento, envolva a
+execução completa (roteamento, runtime e guardrails) no contexto correspondente:
+
+```python
+from agent_framework.localization import use_locale
+
+with use_locale("en"):
+    # Execute aqui o roteamento, o agente e seus guardrails.
+    result = await handle_turn(...)
+```
+
+`handle_turn` representa o ponto de entrada da sua aplicação; não é uma nova API
+do framework. O contexto usa `ContextVar`, é isolado entre tarefas assíncronas e
+restaura o idioma anterior ao sair. Não altere `os.environ` a cada atendimento.
+O idioma da conversa não é detectado automaticamente.
+
+## Validação desta entrega
+
+- 41 testes novos de localização aprovados.
+- 160 testes selecionados aprovados após a atualização de oito testes antigos.
+- As oito expectativas antigas estavam desalinhadas com mudanças de contrato
+  anteriores à localização. Histórico, escopo e validação estão em
+  `ATUALIZACAO_TESTES.md`. Os 66 testes dos quatro arquivos atualizados também
+  passaram com a biblioteca original do ZIP.
+- As verificações incluem execução/cancelamento real do runtime com ferramentas
+  simuladas, confirmação determinística no roteador sem LLM, múltiplas intenções,
+  retomada de workflows, memória, protocolos, segurança, concorrência e catálogo
+  personalizado.
+- Não foram feitas chamadas a modelos remotos, OCI ou ferramentas reais de negócio.
+
+Os testes novos estão em `tests/test_locale_catalogs.py`. Para executá-los em um
+ambiente com as dependências do projeto e pytest/pytest-asyncio:
+
+```bash
+PYTHONPATH=libs/agent_framework/src pytest -q tests/test_locale_catalogs.py
+```
+
+O pacote de entrega conserva os arquivos do projeto e remove metadados do macOS,
+cache de bytecode, builds antigos e diretórios de Git/IDE. As fontes corrigidas
+ficam em `libs/agent_framework/src`. As variantes de demonstração em
+`Tuning-Performance` mantêm suas configurações de domínio originais.