Execuções

A feature Execuções é responsável por iniciar, acompanhar e interromper execuções de casos no SDK PLDPro. Ela é a camada que conecta um Caso já preparado ao backend responsável por processar o estudo, seja em DATACENTER ou em CLOUD.

No SDK, essa funcionalidade é disponibilizada pela classe Execucoes.

Visão geral

Uma execução representa a etapa operacional do processamento de um caso. Na prática, essa feature permite:

iniciar uma execução
consultar o status do processamento
recuperar logs de arquivo e console
interromper execuções em andamento
listar execuções associadas a um AuthNode

Ela complementa o fluxo iniciado em Casos e Nodes/AuthNodes, fechando o ciclo entre preparação do estudo, despacho para infraestrutura e acompanhamento operacional.

Fluxo SDK -> API

O fluxo de execução segue a sequência abaixo:

O cliente Python cria um PLDProClient autenticado.
O caso é criado ou associado a um ambiente já existente.
Os arquivos de entrada são enviados ou reaproveitados.
O SDK monta um ExecucaoStartRequest.
O método client.execucoes.start_execution(...) envia um POST /casos/{uuid}/execution para a API.
A API valida o caso, o ambiente de execução e os parâmetros de infraestrutura.
O backend despacha o processamento para o destino configurado em optionsExecutaModelo.localExecution.
O monitoramento passa a ser feito por get_execution_status, get_execution_logs e get_execution_console_logs.

Em outras palavras, o SDK não executa o modelo diretamente na máquina do usuário. Ele orquestra a chamada para a API PLDPro, e a API decide como despachar a execução no destino configurado.

Relação com Casos, Nodes e AuthNodes

Antes de iniciar a execução, o caso precisa existir e estar preparado. Dependendo do fluxo adotado pela sua implantação, isso normalmente envolve:

um Caso com os dados de entrada
um Node/AuthNode para localizar credenciais, workdir e artefatos remotos
um ExecucaoStartRequest compatível com o ambiente de destino

Além disso:

para hosts em modo NATIVE, o campo version tende a ser opcional
para hosts em modo CONTAINER, o campo version é obrigatório

Sobre a versão do PLDPro

Em execuções com infraestrutura baseada em container, a version informada no request deve ser compatível com a imagem PLDPro disponível no ambiente de execução.

Estrutura do request de execução

O SDK envia a execução por meio de ExecucaoStartRequest, que possui os campos principais abaixo:

from pldpro_sdk.api_client.models.execucao_start_request import ExecucaoStartRequest
from pldpro_sdk.api_client.models.execucao_start_request_options_executa_modelo import (
    ExecucaoStartRequestOptionsExecutaModelo,
)
from pldpro_sdk.api_client.models.type_node_execution_enum import TypeNodeExecutionEnum

request = ExecucaoStartRequest(
    version="7.0.0",
    tipoEntrada="DEFAULT",
    optionsExecutaModelo=ExecucaoStartRequestOptionsExecutaModelo(
        localExecution=TypeNodeExecutionEnum.DATACENTER,
        projectId="PRJ-001",
    ),
)

Campos principais

Campo	Descrição
`version`	Versão do PLDPro/container utilizada na execução.
`tipoEntrada`	Tipo de entrada processada pelo backend. Valores aceitos atualmente: `DEFAULT` e `CONVERSOR`.
`optionsExecutaModelo`	Objeto com a estratégia de despacho da execução e parâmetros de infraestrutura.

`optionsExecutaModelo`

O objeto optionsExecutaModelo define para onde a execução será enviada e quais metadados de infraestrutura devem acompanhar a requisição.

`localExecution`

Campo que direciona o cenário de execução:

TypeNodeExecutionEnum.DATACENTER: despacha a execução para o datacenter
TypeNodeExecutionEnum.CLOUD: despacha a execução para a nuvem

Esse é o campo que separa explicitamente os cenários DATACENTER e CLOUD no request.

`projectId`

Identificador do projeto associado à execução. Pela definição atual do modelo OpenAPI do SDK, este campo é:

obrigatório para execução em DATACENTER
opcional em CLOUD

`reservationId`

Identificador de reserva de recursos computacionais.

Use esse campo quando a sua operação exigir o vínculo da execução a uma reserva previamente provisionada.

`machineType`

Tipo da máquina a ser usada na execução. Pela definição atual do modelo OpenAPI do SDK, este campo é:

obrigatório para execução em CLOUD
não aplicável para o cenário padrão de DATACENTER

`coresPerNode`

Quantidade de cores por nó. O próprio modelo do SDK informa a convenção de que esse valor normalmente corresponde à metade do número representado em machineType.

Exemplo:

machineType="c2std60" -> coresPerNode=30

Matriz de aplicabilidade por cenário

Execução em DATACENTER

Parâmetro	Status	Observação
`localExecution`	obrigatório	Deve ser `DATACENTER`.
`projectId`	obrigatório	Identifica o projeto associado à execução no datacenter.
`reservationId`	opcional	Use apenas se a operação no datacenter exigir reserva explícita.
`machineType`	não aplicável	O dimensionamento costuma ser controlado pela infraestrutura do datacenter.
`coresPerNode`	opcional	Só informe se o backend da sua implantação usar esse ajuste.

Execução em CLOUD

Parâmetro	Status	Observação
`localExecution`	obrigatório	Deve ser `CLOUD`.
`projectId`	opcional	Pode ser exigido por políticas internas de cobrança ou organização, mas não é obrigatório pelo modelo atual.
`reservationId`	opcional	Use quando houver reserva de capacidade previamente criada.
`machineType`	obrigatório	Define a classe de máquina que executará o caso.
`coresPerNode`	opcional	Recomendado quando a esteira cloud exigir o valor explicitamente.

Sobre obrigatoriedade

A tabela acima reflete o contrato atual exposto pelos modelos do SDK e pela documentação gerada da API. Regras operacionais adicionais podem existir na implantação do seu ambiente, especialmente para reservationId e coresPerNode.

Como usar `localExecution` para alternar entre CLOUD e DATACENTER

O campo optionsExecutaModelo.localExecution é o seletor de destino da execução.

DATACENTER

options = ExecucaoStartRequestOptionsExecutaModelo(
    localExecution=TypeNodeExecutionEnum.DATACENTER,
    projectId="PRJ-DATACENTER-001",
)

CLOUD

options = ExecucaoStartRequestOptionsExecutaModelo(
    localExecution=TypeNodeExecutionEnum.CLOUD,
    machineType="c2std60",
    coresPerNode=30,
)

Ao mudar apenas esse campo, mais os parâmetros específicos do destino, o mesmo fluxo do SDK continua válido:

criar ou localizar caso
preparar arquivos
enviar ExecucaoStartRequest
monitorar status e logs

Pré-requisitos operacionais

Datacenter

Antes de executar em datacenter, confirme:

acesso à PLDPro API
API key válida
node cadastrado e acessível
AuthNode configurado com usuário, senha e workdir
conectividade entre a API e o servidor do datacenter
versão do PLDPro disponível no ambiente, quando aplicável
dados do caso carregados no local esperado
projectId válido para o processo operacional

Cloud

Antes de executar em cloud, confirme:

acesso à PLDPro API
API key válida
caso criado e preparado
política de execução cloud habilitada no backend
machineType suportado pela implantação
coresPerNode compatível com o machineType
reservationId, quando o ambiente exigir reserva prévia
credenciais e permissões da infraestrutura cloud já configuradas no backend da API

Variáveis de ambiente, credenciais e dependências

Para testes

O SDK já possui um conjunto de variáveis de ambiente documentadas em tests/.env.example. As principais são:

Variável	Uso
`PLDPRO_API_URL`	URL base da API usada nos testes de integração.
`APP_API_KEY`	Chave de autenticação da API.
`PLDPRO_TEST_HOST_IP`	IP do host usado pelos testes de integração.
`PLDPRO_TEST_NODE_USER`	Usuário do `AuthNode` de teste.
`PLDPRO_TEST_NODE_PASSWORD`	Senha do `AuthNode` de teste.
`PLDPRO_TEST_NODE_WORKDIR`	Diretório remoto usado pelos testes.
`PLDPRO_TEST_UPLOAD_DIR`	Diretório local com dados de entrada para upload.
`PLDPRO_TEST_ATTACH_CASO_REMOTE_PATH`	Caminho remoto de attach do caso.

Dependências mínimas para testes:

Python compatível com o SDK
uv para sincronização do ambiente
dependências instaladas com uv sync
arquivo .env preenchido com base em tests/.env.example
acesso ao ambiente remoto de testes

Para uso em ambiente real

Em produção ou automações reais, normalmente você precisa de:

Item	Finalidade
`PLDPRO_API_URL`	Endereço da API do ambiente real.
`APP_API_KEY`	Credencial de autenticação da aplicação.
`DATACENTER_UUID` ou identificador equivalente	Localizar o node alvo quando o fluxo usar datacenter.
usuário e senha do `AuthNode`	Acesso operacional ao ambiente remoto, quando aplicável.
`projectId`, `reservationId`, `machineType`, `coresPerNode`	Parâmetros de despacho da execução, conforme o cenário.

Dependências mínimas para uso real:

conectividade com a API
permissões válidas para criar casos, fazer upload e iniciar execução
infraestrutura remota já provisionada
observabilidade mínima para acompanhamento de logs e status

Exemplo funcional completo: DATACENTER

import os
import time
from uuid import UUID

from dotenv import load_dotenv

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.api_client.models.caso_request import CasoRequest
from pldpro_sdk.api_client.models.execucao_start_request import ExecucaoStartRequest
from pldpro_sdk.api_client.models.execucao_start_request_options_executa_modelo import (
    ExecucaoStartRequestOptionsExecutaModelo,
)
from pldpro_sdk.api_client.models.type_node_execution_enum import TypeNodeExecutionEnum

load_dotenv()


def create_client() -> PLDProClient:
    return PLDProClient(
        SDKConfig(host=os.environ["PLDPRO_API_URL"], retries=3),
        api_key=os.environ["APP_API_KEY"],
    )


client = create_client()
node_uuid = UUID(os.environ["DATACENTER_UUID"])
auth_node = client.nodes.get_auth_node_from_user(
    node_uuid=node_uuid,
    auth_node_user=os.environ["PLDPRO_AUTH_NODE_USER"],
)

caso = client.casos.create_caso_attach(
    CasoRequest(
        nome="caso-datacenter-sdk",
        pathRemote="",
        uuidAuthNode=auth_node.uuid,
    )
)

client.casos.upload_files(caso.uuid, os.environ["PLDPRO_INPUT_PATH"], True)

request = ExecucaoStartRequest(
    version=os.environ.get("PLDPRO_VERSION", "7.0.0"),
    tipoEntrada="DEFAULT",
    optionsExecutaModelo=ExecucaoStartRequestOptionsExecutaModelo(
        localExecution=TypeNodeExecutionEnum.DATACENTER,
        projectId=os.environ["PLDPRO_PROJECT_ID"],
        reservationId=os.getenv("PLDPRO_RESERVATION_ID"),
    ),
)

execucao = client.execucoes.start_execution(caso.uuid, request)
print(f"Execucao iniciada: {execucao.uuid}")

while True:
    status = client.execucoes.get_execution_status(execucao.uuid)
    print(f"Status: {status.status}")
    if str(status.status) not in {"EXECUTANDO", "PENDENTE"}:
        break
    time.sleep(10)

print(client.execucoes.get_execution_console_logs(caso.uuid))

Exemplo funcional completo: CLOUD

import os
import time

from dotenv import load_dotenv

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.api_client.models.execucao_start_request import ExecucaoStartRequest
from pldpro_sdk.api_client.models.execucao_start_request_options_executa_modelo import (
    ExecucaoStartRequestOptionsExecutaModelo,
)
from pldpro_sdk.api_client.models.type_node_execution_enum import TypeNodeExecutionEnum

load_dotenv()


def create_client() -> PLDProClient:
    return PLDProClient(
        SDKConfig(host=os.environ["PLDPRO_API_URL"], retries=3),
        api_key=os.environ["APP_API_KEY"],
    )


client = create_client()
caso_uuid = os.environ["PLDPRO_CASO_UUID"]

request = ExecucaoStartRequest(
    version=os.environ.get("PLDPRO_VERSION", "7.0.0"),
    tipoEntrada="DEFAULT",
    optionsExecutaModelo=ExecucaoStartRequestOptionsExecutaModelo(
        localExecution=TypeNodeExecutionEnum.CLOUD,
        projectId=os.getenv("PLDPRO_PROJECT_ID"),
        reservationId=os.getenv("PLDPRO_RESERVATION_ID"),
        machineType=os.environ["PLDPRO_MACHINE_TYPE"],
        coresPerNode=int(os.getenv("PLDPRO_CORES_PER_NODE", "30")),
    ),
)

execucao = client.execucoes.start_execution(caso_uuid, request)
print(f"Execucao iniciada: {execucao.uuid}")

while True:
    status = client.execucoes.get_execution_status(execucao.uuid)
    print(f"Status: {status.status}")
    if str(status.status) not in {"EXECUTANDO", "PENDENTE"}:
        break
    time.sleep(10)

print(client.execucoes.get_execution_console_logs(caso_uuid))

Responsabilidades da classe `Execucoes`

Início da execução

start_execution(caso_id, execucao_start_request=None)

Quando execucao_start_request não é informado, o SDK monta um request padrão. Para cenários controlados de produção, recomenda-se sempre enviar explicitamente version, tipoEntrada e optionsExecutaModelo.

Status e monitoramento

get_execution_status(execucao_id)

Consulta o estado atual da execução e permite reagir aos estados finais de sucesso, erro ou cancelamento.

Logs da execução

get_execution_logs(caso_id)
get_execution_console_logs(caso_id)

Esses métodos retornam, respectivamente, o log textual da execução e a saída de console do processamento.

Interrupção

stop_execution(execucao_id)

A interrupção é tratada de forma idempotente para simplificar fluxos operacionais.

Listagem por ambiente autenticado

list_executions(auth_node_uuid)

Útil para operações de suporte, observabilidade e troubleshooting em ambientes com múltiplos casos em execução.

Resumo

A classe Execucoes é a porta de entrada do SDK para despacho e observabilidade de execuções. O campo optionsExecutaModelo.localExecution é o ponto central para escolher entre DATACENTER e CLOUD, enquanto projectId, reservationId, machineType e coresPerNode refinam o comportamento conforme a infraestrutura de destino.