orquestrador/shared/contracts/bot_governed_configuration.py

"""Define quais configuracoes do bot ficam sob governanca administrativa."""

from __future__ import annotations

from enum import Enum

from pydantic import BaseModel

from shared.contracts.access_control import AdminPermission


class BotGovernanceArea(str, Enum):
    MODEL_SELECTION = "model_selection"
    RESPONSE_GENERATION = "response_generation"
    TOOL_USAGE = "tool_usage"
    FALLBACK_AND_HANDOFF = "fallback_and_handoff"
    CHANNEL_OPERATION = "channel_operation"


class BotGovernanceMutability(str, Enum):
    DIRECTOR_GOVERNED = "director_governed"


class BotGovernedSettingContract(BaseModel):
    setting_key: str
    parent_config_key: str
    field_name: str
    area: BotGovernanceArea
    description: str
    read_permission: AdminPermission = AdminPermission.VIEW_SYSTEM
    write_permission: AdminPermission = AdminPermission.MANAGE_SETTINGS
    mutability: BotGovernanceMutability = BotGovernanceMutability.DIRECTOR_GOVERNED
    versioned_publication_required: bool = True
    direct_product_write_allowed: bool = False


BOT_GOVERNED_SETTINGS: tuple[BotGovernedSettingContract, ...] = (
    BotGovernedSettingContract(
        setting_key="bot_model_provider",
        parent_config_key="atendimento_runtime_profile",
        field_name="provider",
        area=BotGovernanceArea.MODEL_SELECTION,
        description="Provedor do modelo usado pelo bot de atendimento.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_model_name",
        parent_config_key="atendimento_runtime_profile",
        field_name="model_name",
        area=BotGovernanceArea.MODEL_SELECTION,
        description="Modelo selecionado para responder ao cliente final.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_temperature",
        parent_config_key="atendimento_runtime_profile",
        field_name="temperature",
        area=BotGovernanceArea.RESPONSE_GENERATION,
        description="Temperatura aplicada nas respostas do bot.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_max_output_tokens",
        parent_config_key="atendimento_runtime_profile",
        field_name="max_output_tokens",
        area=BotGovernanceArea.RESPONSE_GENERATION,
        description="Limite de saida usado no runtime de atendimento.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_prompt_profile_ref",
        parent_config_key="atendimento_runtime_profile",
        field_name="prompt_profile_ref",
        area=BotGovernanceArea.RESPONSE_GENERATION,
        description="Referencia do perfil de prompt publicado para o bot.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_tool_policy_ref",
        parent_config_key="atendimento_runtime_profile",
        field_name="tool_policy_ref",
        area=BotGovernanceArea.TOOL_USAGE,
        description="Referencia da politica de uso de tools pelo bot.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_fallback_mode",
        parent_config_key="bot_behavior_policy",
        field_name="fallback_mode",
        area=BotGovernanceArea.FALLBACK_AND_HANDOFF,
        description="Modo funcional de fallback quando o bot nao conclui a tarefa.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_handoff_enabled",
        parent_config_key="bot_behavior_policy",
        field_name="handoff_enabled",
        area=BotGovernanceArea.FALLBACK_AND_HANDOFF,
        description="Habilita o encaminhamento para atendimento humano.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_handoff_intents",
        parent_config_key="bot_behavior_policy",
        field_name="handoff_intents",
        area=BotGovernanceArea.FALLBACK_AND_HANDOFF,
        description="Lista de intencoes que exigem handoff humano.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_max_tool_calls_per_turn",
        parent_config_key="bot_behavior_policy",
        field_name="max_tool_calls_per_turn",
        area=BotGovernanceArea.TOOL_USAGE,
        description="Limite de chamadas de tools por turno conversacional.",
    ),
    BotGovernedSettingContract(
        setting_key="bot_confirmation_policy",
        parent_config_key="bot_behavior_policy",
        field_name="confirmation_policy",
        area=BotGovernanceArea.TOOL_USAGE,
        description="Politica de confirmacao antes de acao critica no fluxo.",
    ),
    BotGovernedSettingContract(
        setting_key="channel_enabled",
        parent_config_key="channel_operation_policy",
        field_name="enabled",
        area=BotGovernanceArea.CHANNEL_OPERATION,
        description="Habilita ou desabilita o bot em um canal homologado.",
    ),
    BotGovernedSettingContract(
        setting_key="channel_maintenance_mode",
        parent_config_key="channel_operation_policy",
        field_name="maintenance_mode",
        area=BotGovernanceArea.CHANNEL_OPERATION,
        description="Liga manutencao controlada em um canal do bot.",
    ),
    BotGovernedSettingContract(
        setting_key="channel_default_route",
        parent_config_key="channel_operation_policy",
        field_name="default_route",
        area=BotGovernanceArea.CHANNEL_OPERATION,
        description="Define a rota funcional padrao por canal.",
    ),
    BotGovernedSettingContract(
        setting_key="channel_operation_window_ref",
        parent_config_key="channel_operation_policy",
        field_name="operation_window_ref",
        area=BotGovernanceArea.CHANNEL_OPERATION,
        description="Referencia a janela operacional aplicada por canal.",
    ),
)


def get_bot_governed_setting(setting_key: str) -> BotGovernedSettingContract | None:
    normalized = str(setting_key or "").strip().lower()
    for setting in BOT_GOVERNED_SETTINGS:
        if setting.setting_key == normalized:
            return setting
    return None