orquestrador/shared/contracts/system_functional_configuration.py

"""Define o escopo de configuracao funcional governada entre admin e product."""

from __future__ import annotations

from enum import Enum

from pydantic import BaseModel

from shared.contracts.access_control import AdminPermission


class FunctionalConfigurationDomain(str, Enum):
    MODEL_CATALOG = "model_catalog"
    ATENDIMENTO_RUNTIME = "atendimento_runtime"
    TOOL_GENERATION_RUNTIME = "tool_generation_runtime"
    BOT_POLICY = "bot_policy"
    CHANNEL_OPERATION = "channel_operation"
    CONFIG_PUBLICATION = "config_publication"


class FunctionalConfigurationMutability(str, Enum):
    READ_ONLY = "read_only"
    DIRECTOR_GOVERNED = "director_governed"


class FunctionalConfigurationSource(str, Enum):
    PLATFORM_CATALOG = "platform_catalog"
    ADMIN_GOVERNED_STATE = "admin_governed_state"
    PRODUCT_EFFECTIVE_STATE = "product_effective_state"


class FunctionalConfigurationPropagation(str, Enum):
    OBSERVATION_ONLY = "observation_only"
    VERSIONED_PUBLICATION = "versioned_publication"


class FunctionalConfigurationFieldContract(BaseModel):
    name: str
    description: str
    writable: bool = True
    secret: bool = False


class FunctionalConfigurationContract(BaseModel):
    config_key: str
    domain: FunctionalConfigurationDomain
    description: str
    source: FunctionalConfigurationSource
    read_permission: AdminPermission = AdminPermission.VIEW_SYSTEM
    write_permission: AdminPermission | None = AdminPermission.MANAGE_SETTINGS
    mutability: FunctionalConfigurationMutability = FunctionalConfigurationMutability.DIRECTOR_GOVERNED
    propagation: FunctionalConfigurationPropagation = (
        FunctionalConfigurationPropagation.VERSIONED_PUBLICATION
    )
    affects_product_runtime: bool = True
    direct_product_write_allowed: bool = False
    fields: tuple[FunctionalConfigurationFieldContract, ...]


SYSTEM_FUNCTIONAL_CONFIGURATIONS: tuple[FunctionalConfigurationContract, ...] = (
    FunctionalConfigurationContract(
        config_key="allowed_model_catalog",
        domain=FunctionalConfigurationDomain.MODEL_CATALOG,
        description="Catalogo de modelos liberados pela plataforma para atendimento e geracao de tools.",
        source=FunctionalConfigurationSource.PLATFORM_CATALOG,
        write_permission=None,
        mutability=FunctionalConfigurationMutability.READ_ONLY,
        propagation=FunctionalConfigurationPropagation.OBSERVATION_ONLY,
        affects_product_runtime=False,
        fields=(
            FunctionalConfigurationFieldContract(
                name="runtime_target",
                description="Destino funcional do modelo, como atendimento ou geracao de tools.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="provider",
                description="Provedor homologado para o modelo.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="model_name",
                description="Nome tecnico do modelo liberado.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="capability_tags",
                description="Capacidades suportadas pelo modelo homologado.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="status",
                description="Estado de homologacao do modelo no catalogo da plataforma.",
                writable=False,
            ),
        ),
    ),
    FunctionalConfigurationContract(
        config_key="atendimento_runtime_profile",
        domain=FunctionalConfigurationDomain.ATENDIMENTO_RUNTIME,
        description="Perfil funcional ativo para o bot de atendimento no servico de produto.",
        source=FunctionalConfigurationSource.ADMIN_GOVERNED_STATE,
        fields=(
            FunctionalConfigurationFieldContract(
                name="provider",
                description="Provedor selecionado para o atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="model_name",
                description="Modelo selecionado para o atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="temperature",
                description="Temperatura aplicada nas respostas do atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="max_output_tokens",
                description="Limite de saida usado pelo atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="prompt_profile_ref",
                description="Referencia da estrategia de prompt publicada para o atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="tool_policy_ref",
                description="Referencia da politica de uso de tools pelo atendimento.",
            ),
        ),
    ),
    FunctionalConfigurationContract(
        config_key="tool_generation_runtime_profile",
        domain=FunctionalConfigurationDomain.TOOL_GENERATION_RUNTIME,
        description="Perfil funcional usado para geracao e validacao automatica de novas tools.",
        source=FunctionalConfigurationSource.ADMIN_GOVERNED_STATE,
        fields=(
            FunctionalConfigurationFieldContract(
                name="provider",
                description="Provedor selecionado para a geracao de tools.",
            ),
            FunctionalConfigurationFieldContract(
                name="model_name",
                description="Modelo selecionado para a geracao de tools.",
            ),
            FunctionalConfigurationFieldContract(
                name="reasoning_profile",
                description="Perfil de raciocinio aprovado para geracao de codigo.",
            ),
            FunctionalConfigurationFieldContract(
                name="max_output_tokens",
                description="Limite de saida usado na geracao de tools.",
            ),
            FunctionalConfigurationFieldContract(
                name="validation_profile_ref",
                description="Referencia da politica de validacao automatica de tools.",
            ),
        ),
    ),
    FunctionalConfigurationContract(
        config_key="bot_behavior_policy",
        domain=FunctionalConfigurationDomain.BOT_POLICY,
        description="Politicas funcionais do fluxo do bot para fallback, handoff e uso de tools.",
        source=FunctionalConfigurationSource.ADMIN_GOVERNED_STATE,
        fields=(
            FunctionalConfigurationFieldContract(
                name="fallback_mode",
                description="Modo funcional de fallback quando o bot nao conclui a tarefa.",
            ),
            FunctionalConfigurationFieldContract(
                name="handoff_enabled",
                description="Sinaliza se o fluxo pode encaminhar para atendimento humano.",
            ),
            FunctionalConfigurationFieldContract(
                name="handoff_intents",
                description="Lista de intencoes que forcam handoff humano.",
            ),
            FunctionalConfigurationFieldContract(
                name="max_tool_calls_per_turn",
                description="Limite de chamadas de tools por turno de atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="confirmation_policy",
                description="Politica de confirmacao antes de acao critica no fluxo.",
            ),
        ),
    ),
    FunctionalConfigurationContract(
        config_key="channel_operation_policy",
        domain=FunctionalConfigurationDomain.CHANNEL_OPERATION,
        description="Politicas funcionais por canal, incluindo habilitacao, manutencao e janela operacional.",
        source=FunctionalConfigurationSource.ADMIN_GOVERNED_STATE,
        fields=(
            FunctionalConfigurationFieldContract(
                name="channel",
                description="Canal operacional ao qual a politica se aplica.",
            ),
            FunctionalConfigurationFieldContract(
                name="enabled",
                description="Indica se o canal esta habilitado para atendimento.",
            ),
            FunctionalConfigurationFieldContract(
                name="maintenance_mode",
                description="Sinaliza se o canal esta em manutencao controlada.",
            ),
            FunctionalConfigurationFieldContract(
                name="default_route",
                description="Rota funcional padrao usada pelo canal.",
            ),
            FunctionalConfigurationFieldContract(
                name="operation_window_ref",
                description="Referencia da janela operacional aplicada ao canal.",
            ),
        ),
    ),
    FunctionalConfigurationContract(
        config_key="published_runtime_state",
        domain=FunctionalConfigurationDomain.CONFIG_PUBLICATION,
        description="Estado efetivo publicado no produto para auditoria de versao e aplicacao runtime.",
        source=FunctionalConfigurationSource.PRODUCT_EFFECTIVE_STATE,
        write_permission=None,
        mutability=FunctionalConfigurationMutability.READ_ONLY,
        propagation=FunctionalConfigurationPropagation.OBSERVATION_ONLY,
        fields=(
            FunctionalConfigurationFieldContract(
                name="config_scope",
                description="Escopo funcional da configuracao publicada.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="active_version",
                description="Versao funcional atualmente ativa no produto.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="published_by",
                description="Identificador administrativo de quem publicou a configuracao.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="published_at",
                description="Momento da ultima publicacao governada.",
                writable=False,
            ),
            FunctionalConfigurationFieldContract(
                name="applied_at",
                description="Momento em que o produto aplicou a configuracao em runtime.",
                writable=False,
            ),
        ),
    ),
)


def get_functional_configuration(config_key: str) -> FunctionalConfigurationContract | None:
    normalized = str(config_key or "").strip().lower()
    for configuration in SYSTEM_FUNCTIONAL_CONFIGURATIONS:
        if configuration.config_key == normalized:
            return configuration
    return None