Execuções

A feature Execuções inicia, acompanha e interrompe o processamento de um caso. O SDK envia a solicitação para a API PLDPro; a execução efetiva ocorre na infraestrutura selecionada pelo backend.

No SDK, essa funcionalidade é disponibilizada por client.execucoes.

Duas configurações diferentes

O request de execução contém duas escolhas independentes:

Escolha	Campo	Valores	O que controla
Etapas do processamento	`tipoScript`	`GERA_DECK_ONLY`, `PLDPRO_ONLY`, `COMPLETE`	Se a execução gera o deck, executa o PLDPro ou faz as duas etapas.
Destino da execução	`optionsExecutaModelo.localExecution`	`CLOUD`, `DATACENTER`, `AUTO`	Em qual infraestrutura o job será despachado.

Por exemplo, tipoScript="GERA_DECK_ONLY" com localExecution="CLOUD" significa gerar o deck na infraestrutura cloud. O valor de tipoScript não escolhe a infraestrutura, e localExecution não escolhe quais etapas serão realizadas.

Mudança em relação ao contrato anterior

tipoScript substitui tipoEntrada. Os valores antigos DEFAULT e CONVERSOR não devem mais ser enviados. A necessidade de conversão agora é expressa pela etapa escolhida em tipoScript.

Fluxo SDK -> API

Crie ou associe um caso e prepare seus arquivos.
Selecione um ou mais AuthNodes candidatos.
Monte um ExecutionStartRequest com o tipo de script e as opções de infraestrutura.
Chame client.execucoes.start_execution(caso_uuid, request).
A API escolhe um AuthNode compatível, gera o script correspondente e despacha o job.
Consulte o estado e os logs usando o UUID do caso.

O endpoint usado pelo SDK é POST /casos/{uuid}/execution, em que {uuid} é o UUID do caso.

Estrutura do request

As classes do request podem ser importadas diretamente de pldpro_sdk.api_client:

from pldpro_sdk.api_client import ExecutionStartRequest, OptionsExecutaModelo

request = ExecutionStartRequest(
    version="7.0.0",
    tipoScript="COMPLETE",
    listaUUIDAuthNodes=[auth_node_uuid],
    optionsExecutaModelo=OptionsExecutaModelo(
        localExecution="CLOUD",
        projectId="projeto-exemplo",
        machineType="c2std60",
    ),
)

Os nomes em camelCase dos exemplos correspondem aos aliases do JSON da API. O modelo Python também expõe os atributos em snake_case, como request.tipo_script e request.lista_uuid_auth_nodes.

Campos de `ExecutionStartRequest`

Campo	Regra	Descrição
`version`	Obrigatório pelo contrato do endpoint	Tag da imagem `xlibs_pldpro`. É usada por `PLDPRO_ONLY` e `COMPLETE`; `GERA_DECK_ONLY` recebe o campo, mas não o consome.
`tipoScript`	Obrigatório	Define as etapas executadas.
`listaUUIDAuthNodes`	Obrigatório e não vazio na prática	Lista ordenada de UUIDs de `AuthNodes` candidatos.
`optionsExecutaModelo`	Necessário na preparação atual	Define o destino e os parâmetros do job.

Há uma diferença importante entre o modelo Python e o comportamento do endpoint: o modelo gerado permite omitir version, mas a documentação da API o define como obrigatório. Para manter o request compatível, envie version em todos os modos, mesmo em GERA_DECK_ONLY, que não usa esse valor. Da mesma forma, envie optionsExecutaModelo explicitamente, pois a preparação atual do backend depende desse objeto.

listaUUIDAuthNodes pode conter mais de um UUID. A API mantém somente os AuthNodes existentes e seleciona o primeiro compatível com o destino resolvido. Se nenhum candidato válido e compatível for encontrado, a execução falha antes do despacho.

Tipos de script

`GERA_DECK_ONLY`

Executa apenas o Conversor PLDPro e termina após a geração do deck. Não inicia a imagem xlibs_pldpro.

Use quando quiser separar a preparação do deck da execução dos modelos:

request = ExecutionStartRequest(
    version="7.0.0",  # exigida pelo request, mas não usada neste modo
    tipoScript="GERA_DECK_ONLY",
    listaUUIDAuthNodes=[auth_node_uuid],
    optionsExecutaModelo=OptionsExecutaModelo(
        localExecution="DATACENTER",
        projectId="PRJ-001",
    ),
)

Esse modo requer a entrada do conversor. Durante a preparação, a API trata esse arquivo como entrada_conversor.txt; o script o disponibiliza ao conversor como entrada.txt. Não envie simultaneamente versões diferentes de entrada.txt e entrada_conversor.txt, pois a API prioriza a entrada do conversor.

`PLDPRO_ONLY`

Inicia apenas o PLDPro, sem executar o conversor. O caso já deve conter um deck válido.

request = ExecutionStartRequest(
    version="7.0.0",
    tipoScript="PLDPRO_ONLY",
    listaUUIDAuthNodes=[auth_node_uuid],
    optionsExecutaModelo=OptionsExecutaModelo(
        localExecution="DATACENTER",
        projectId="PRJ-001",
    ),
)

Nesse modo, a API não renomeia entrada.txt para entrada_conversor.txt.

`COMPLETE`

Combina as duas etapas. Quando há uma entrada preparada para o conversor, gera o deck e, após o sucesso dessa etapa, inicia o PLDPro. Se não houver entrada_conversor.txt, o script pula a conversão e inicia diretamente o PLDPro.

request = ExecutionStartRequest(
    version="7.0.0",
    tipoScript="COMPLETE",
    listaUUIDAuthNodes=[auth_node_uuid],
    optionsExecutaModelo=OptionsExecutaModelo(
        localExecution="CLOUD",
        projectId="projeto-cloud",
        machineType="c2std60",
    ),
)

Na preparação de COMPLETE, a API aplica à entrada o mesmo tratamento usado por GERA_DECK_ONLY: se existir entrada.txt, ela é preparada como entrada_conversor.txt. Portanto, use PLDPRO_ONLY quando entrada.txt já fizer parte de um deck pronto e não deva passar pelo conversor.

Se o conversor não produzir o marcador de sucesso esperado, a etapa do PLDPro não é iniciada.

Opções de infraestrutura

OptionsExecutaModelo possui os seguintes campos:

Campo	Descrição
`localExecution`	Destino solicitado: `CLOUD`, `DATACENTER` ou `AUTO`.
`projectId`	Projeto/conta registrado na configuração do job. Em `AUTO`, pode vir do catálogo da reserva quando não for informado.
`reservationId`	Identificador de uma reserva de capacidade do datacenter.
`machineType`	Tipo de máquina usado no cloud e nos fallbacks para cloud.
`optionModeloCore`	Lista de pares `modelType`/`coresPerNode`, um por modelo que precise de dimensionamento específico.
`jobEmail`	Identificação usada como e-mail e usuário do job na configuração do executor.
`configDir`	Diretório de configuração do executor. É um parâmetro transitório e deve ser informado somente se a implantação exigir.

coresPerNode não é um atributo direto de OptionsExecutaModelo. Ele pertence a cada item de optionModeloCore:

from pldpro_sdk.api_client import OptionModeloCore, OptionsExecutaModelo

options = OptionsExecutaModelo(
    localExecution="CLOUD",
    projectId="projeto-cloud",
    machineType="c2std60",
    optionModeloCore=[
        OptionModeloCore(modelType="DECOMP", coresPerNode=30),
        OptionModeloCore(modelType="NEWAVE", coresPerNode=60),
    ],
    jobEmail="operacao@exemplo.br",
)

Os valores aceitos atualmente em modelType são GEVAZP, DECOMP, NEWAVE, DESSEM, CONVERTE_NOMES e NWLISTOP. Quando um modelo licenciado não aparece em optionModeloCore, o backend usa seu valor padrão de cores.

`CLOUD`

CLOUD solicita diretamente a infraestrutura de nuvem. Informe um machineType suportado pela implantação e inclua na lista pelo menos um AuthNode compatível com cloud.

options = OptionsExecutaModelo(
    localExecution="CLOUD",
    projectId="projeto-cloud",
    machineType="c2std60",
)

`DATACENTER`

DATACENTER mantém a execução no datacenter. reservationId é opcional: quando informado, a API tenta alocar capacidade nessa reserva. Se a alocação falhar em uma solicitação explicitamente DATACENTER, o job continua no datacenter sem a reserva.

options = OptionsExecutaModelo(
    localExecution="DATACENTER",
    projectId="PRJ-001",
    reservationId="reserva-dc-01",
)

`AUTO`

AUTO permite que a API escolha entre datacenter e cloud:

Situação	Destino resolvido
Sem `reservationId`	`CLOUD`
Reserva encontrada, habilitada e com capacidade	`DATACENTER`
Reserva inexistente, desabilitada ou sem capacidade	`CLOUD`
Falha ao efetivar a alocação da reserva	`CLOUD`

Como AUTO pode terminar no cloud, forneça também um machineType válido e candidatos de AuthNode compatíveis com os possíveis destinos.

options = OptionsExecutaModelo(
    localExecution="AUTO",
    reservationId="reserva-dc-01",
    machineType="c2std60",
)

O status da execução informa a decisão em campos como resolvedExecutionTarget e decisionReason. Isso permite distinguir a escolha solicitada do destino efetivamente utilizado.

Exemplo completo

O exemplo abaixo executa o fluxo completo em modo AUTO e acompanha o caso até sair dos estados transitórios:

import os
import time
from uuid import UUID

from dotenv import load_dotenv

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.api_client import (
    ExecutionStartRequest,
    OptionModeloCore,
    OptionsExecutaModelo,
)

load_dotenv()

client = PLDProClient(
    SDKConfig(host=os.environ["PLDPRO_API_URL"], retries=3),
    tenant_code=os.environ["PLDPRO_TENANT_CODE"],
    api_key=os.environ["APP_API_KEY"],
)

caso_uuid = UUID(os.environ["PLDPRO_CASO_UUID"])
auth_node_uuids = [
    UUID(value)
    for value in os.environ["PLDPRO_AUTH_NODE_UUIDS"].split(",")
]

request = ExecutionStartRequest(
    version=os.getenv("PLDPRO_VERSION", "7.0.0"),
    tipoScript="COMPLETE",
    listaUUIDAuthNodes=auth_node_uuids,
    optionsExecutaModelo=OptionsExecutaModelo(
        localExecution="AUTO",
        projectId=os.getenv("PLDPRO_PROJECT_ID"),
        reservationId=os.getenv("PLDPRO_RESERVATION_ID"),
        machineType=os.getenv("PLDPRO_MACHINE_TYPE", "c2std60"),
        optionModeloCore=[
            OptionModeloCore(modelType="DECOMP", coresPerNode=30),
        ],
        jobEmail=os.getenv("PLDPRO_JOB_EMAIL"),
    ),
)

execucao = client.execucoes.start_execution(caso_uuid, request)
if execucao is None:
    raise RuntimeError("A API não iniciou a execução.")

while True:
    status = client.execucoes.get_execution_status(caso_uuid)
    if status is None:
        raise RuntimeError("Não foi possível consultar a execução.")

    print(
        status.status,
        getattr(status, "resolved_execution_target", None),
        getattr(status, "decision_reason", None),
    )

    if status.status not in {"NAO_INICIALIZADO", "EXECUTANDO"}:
        break
    time.sleep(10)

print(client.execucoes.get_execution_console_logs(caso_uuid))

Monitoramento e interrupção

Os métodos de consulta recebem o UUID do caso, não o UUID retornado para a execução:

status = client.execucoes.get_execution_status(caso_uuid)
log = client.execucoes.get_execution_logs(caso_uuid)
console = client.execucoes.get_execution_console_logs(caso_uuid)
client.execucoes.stop_execution(caso_uuid)

Para listar as execuções associadas a um ambiente autenticado, use:

execucoes = client.execucoes.list_executions(auth_node_uuid)

Request padrão do SDK

É possível chamar start_execution(caso_uuid) sem fornecer um request. Atualmente o SDK cria um payload COMPLETE/CLOUD com versão e tipo de máquina padrão, mas envia listaUUIDAuthNodes=[]. Como o backend precisa encontrar pelo menos um AuthNode válido, esse atalho não é adequado para uma execução real sem configuração adicional.

Para automações e produção, sempre construa ExecutionStartRequest explicitamente. Isso também evita que uma alteração futura nos valores padrão mude silenciosamente o comportamento da execução.