# Configuracoes Do Bot Governadas Pelo Admin

## Objetivo

Definir exatamente quais configuracoes do bot de atendimento entram sob governanca do `orquestrador-admin`.

Esta etapa detalha, em nivel de campo, a parte do runtime do bot que pode ser consultada por `colaborador` e alterada por `diretor`.

## Decisao

O `admin` governa apenas configuracoes funcionais do bot de atendimento.

Isso inclui:

- escolha do modelo homologado usado no atendimento
- politicas de resposta do bot
- politicas de uso de tools
- politicas de fallback e handoff humano
- politicas operacionais por canal

Essa fronteira fica formalizada em `shared/contracts/bot_governed_configuration.py`.

## Configuracoes governadas

### 1. Selecao de modelo do bot

Campos governados:

- `provider`
- `model_name`

Esses campos definem qual modelo homologado responde ao cliente final.

### 2. Geracao de resposta

Campos governados:

- `temperature`
- `max_output_tokens`
- `prompt_profile_ref`

Esses campos controlam o perfil funcional da resposta, sem expor o painel a segredos ou internals de infraestrutura.

### 3. Uso de tools

Campos governados:

- `tool_policy_ref`
- `max_tool_calls_per_turn`
- `confirmation_policy`

Esses campos definem como o bot pode usar tools e quando precisa de confirmacao antes de acao critica.

### 4. Fallback e handoff

Campos governados:

- `fallback_mode`
- `handoff_enabled`
- `handoff_intents`

Esses campos governam quando o fluxo segue fallback controlado e quando encaminha para atendimento humano.

### 5. Operacao por canal

Campos governados:

- `enabled`
- `maintenance_mode`
- `default_route`
- `operation_window_ref`

Esses campos permitem controlar disponibilidade e comportamento funcional por canal homologado.

## O que nao entra como configuracao do bot

As seguintes superficies ficam fora desta governanca:

- configuracao de modelo para geracao de tools
- credenciais de provedor e segredos
- conteudo bruto de prompt sensivel
- variaveis de ambiente e infraestrutura
- implementacao interna das tools
- alteracao direta em tabelas operacionais do `product`

## Regras obrigatorias

### 1. Leitura por `colaborador`, alteracao por `diretor`

- `colaborador` consulta via `view_system`
- `diretor` consulta e altera via `manage_settings`

### 2. Sem escrita direta no runtime do produto

O painel registra estado desejado e governado.
O `product` consome apenas configuracao publicada, versionada e auditavel.

### 3. Separacao do runtime de geracao

O runtime usado para gerar tools continua em trilha propria.
Ele nao deve ser tratado como configuracao do bot de atendimento.

## Consequencias positivas

- deixa a tela de configuracao do bot mais clara e segura
- evita que a UI misture atendimento com geracao de tools
- preserva a governanca de publicacao entre `admin` e `product`
- prepara a proxima etapa de rotas administrativas para configuracao funcional do sistema