Exemplos práticos

Configuração inicial

Para iniciar o uso do SDK PLDPro, você precisa configurar o cliente com as informações de conexão e autenticação. Veja um exemplo básico de como fazer isso:

from pldpro_sdk import SDKConfig, PLDProClient

 client = PLDProClient(
        SDKConfig(host="https://server-pldpro-api/v1", retries=3),
        tenant_code="tenant_Code",
        api_key="api_key"
    )

O host deve apontar para a URL da API do PLDPro. O parâmetro retries é opcional e define a quantidade de tentativas de requisição em caso de falha. A API key deve ser válida para permitir a autenticação e o uso da API.

O tenant_code é um parâmetro obrigatório que identifica a empresa do usuário; caso não seja informado, o SDK retornará um erro. Por exemplo, se você trabalha no CEPEL, seu tenant_code seria "cepel". Esse mesmo raciocínio se aplica aos demais clientes.

Boas práticas

Para casos em que há somente a necessidade de configurar um cliente simples, é recomendado utilizar variáveis de ambiente para armazenar informações sensíveis, como a chave de API. Isso evita que essas informações fiquem expostas diretamente no código-fonte.

Crie um arquivo .env na raiz do seu projeto com o seguinte conteúdo:

API_KEY=api_209
HOST=http://localhost:8080/v1
RETRIES=3

Em seguida, você pode criar uma função para carregar essas variáveis e configurar o cliente:

import os

from pldpro_sdk import SDKConfig, PLDProClient
from dotenv import load_dotenv

load_dotenv()

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST", "http://localhost:8080/v1")
    retries = int(os.getenv("RETRIES", "3"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

Por fim o usuário pode criar o cliente chamando a função create_client_from_env():

client = create_client_from_env()

Cadastro de Node

Após o cliente estar configurado, você pode cadastrar um novo node na plataforma PLDPro. O exemplo abaixo demonstra como garantir que um node seja criado.

from pldpro_sdk import SDKConfig, PLDProClient
from pldpro_sdk.api_client.models import (NodeRequest)
from pldpro_sdk.api_client.models.execution_mode import ExecutionMode

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()

node_request = NodeRequest(
        nome="Node Example",
        ip="",
        dns="node.example.br",
        porta=22,
        modoExecucao=ExecutionMode.CONTAINER)

node = client.nodes.register(node_request)

Para listar todos os host cadastrados, você pode usar o seguinte código:

nodes = client.nodes.list_nodes()
for n in nodes:
    print(f"Node UUID: {n.uuid}, Nome: {n.nome}, DNS: {n.dns}, IP: {n.ip}, Porta: {n.porta}")

Boas Práticas

Para garantir que na criação de um novo node não seja duplicado, você pode implementar uma lógica para verificar se um node com a mesma combinação de (IP/DNS + porta) já existe antes de tentar cadastrá-lo. O exemplo completo está disponível abaixo:

def get_or_create_node(client: PLDProClient, node_request: NodeRequest):
    """
    Garante que exista um node com a mesma combinação de (IP/DNS + porta).
    Se existir, retorna o existente; se não, cria um novo.
    Essa lógica segue a mesma regra de unicidade aplicada pelo backend.
    """
    nodes = client.nodes.list_nodes()

    for n in nodes:
        same_dns = (n.dns or "") and (n.dns == (node_request.dns or ""))
        same_ip = (n.ip or "") and (n.ip == (node_request.ip or ""))
        same_port = n.porta == node_request.porta

        if same_port and (same_dns or same_ip):
            logger.info(
                f"Node existente encontrado pela combinação IP/DNS+porta: "
                f"{n.nome} (UUID: {n.uuid})"
            )
            return n

    logger.info("Node não encontrado pela combinação IP/DNS+porta. Cadastrando novo...")

    new_node = client.nodes.register(node_request)

    if not new_node:
        raise RuntimeError("Falha ao cadastrar node.")

    logger.info(f"Node cadastrado: {new_node.nome} (UUID: {new_node.uuid})")
    return new_node

Cadastro AuthNode

Para iniciar a execução de casos em um node, é necessário cadastrar um AuthNode para autenticação, para mais informações acesse Funcionalidades -> Nodes. O SDK tem duas funções que realizam o cadastro, o primeiro modo é passando usuário e senha para que a própria API crie a comunicação e faça a troca de chaves que são criadas, o outro modo é passando somente o usuário o retorno é a chave pública gerada pela API para que o próprio usuário possa cadastra-la no servidor de execução.

O exemplo abaixo demonstra como garantir que um AuthNode seja criado, a partir do usuário e senha, para o usuário 'user' em um node específico.

Info

Vale ressaltar que o workir passado é o diretório no Node onde os casos serão armazenados e executados, ou seja, é necessário que o caminho exista no Node para que a execução funcione corretamente.

from pldpro_sdk import SDKConfig, PLDProClient
from pldpro_sdk.api_client.models import (NodeRequest)
from pldpro_sdk.api_client.models.execution_mode import ExecutionMode
from pldpro_sdk.core.helpers import logger

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

USERNAME = "user"

client = create_client_from_env()

nodes = client.nodes.list_nodes()

node_uuid = nodes[0].uuid 

workdir = "/home/user/workdir"
password = "sua_senha_aqui"

auth_node = client.nodes.create_auth_node(
        node_uuid,
        USERNAME,
        workdir,
        password,
    )

print(auth_node)

O exemplo abaixo demonstra como garantir que um AuthNode seja criado, a partir do usuário, para o usuário 'user' em um node específico.

from pldpro_sdk import SDKConfig, PLDProClient
from pldpro_sdk.api_client.models import (NodeRequest)
from pldpro_sdk.api_client.models.execution_mode import ExecutionMode
from pldpro_sdk.core.helpers import logger

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

USERNAME = "user"

client = create_client_from_env()

output = "/home/user/downloads"
workdir = "/home/user/workdir"

auth_node = client.nodes.create_auth_node(
        node_uuid, # UUID do Node
        USERNAME,
        workdir,
        output,
    )

A chave pública gerada após a finalização da função será armazenada em output.

Para listar todos os AuthNodes cadastrados em um node específico, você pode usar o seguinte código:

auth_nodes = client.nodes.list_auth_nodes(node_uuid)
for auth in auth_nodes:
    print(f"AuthNode UUID: {auth.uuid}, Usuário: {auth.usuario}, Workdir: {auth.path_workdir}")

Boas Práticas

Para garantir que o AuthNode não seja duplicado para o mesmo usuário em um node, você pode implementar uma lógica para verificar se um AuthNode com a mesma combinação de (node_uuid + username) já existe antes de tentar cadastrá-lo. O exemplo completo está disponível abaixo:

def get_or_create_auth_node_for_user(
        client: PLDProClient,
        node_uuid,
        workdir: str,
        password: str,
):
    """
    Garante que exista um AuthNode para o usuário 'user' no node informado.
    Se existir (mesmo com outro workdir), retorna o existente.
    Se não existir, cria um novo.
    """
    USERNAME = "user"

    auth_nodes = client.nodes.list_auth_nodes(node_uuid)

    for auth in auth_nodes:
        if auth.usuario == USERNAME:
            logger.info(
                f"AuthNode existente encontrado para usuário {USERNAME}: {auth.uuid}"
            )

            existing_workdir = getattr(auth, "path_workdir", None) or ""
            desired_workdir = workdir or ""
            if existing_workdir != desired_workdir:
                logger.warning(
                    f"Workdir diferente do desejado para o AuthNode {auth.uuid}. "
                    f"Existente='{existing_workdir}', Desejado='{desired_workdir}'"
                )

            return auth

    logger.info(f"AuthNode para usuário {USERNAME} não encontrado. Cadastrando novo...")

    new_auth = client.nodes.create_auth_node(
        node_uuid,
        USERNAME,
        workdir,
        password,
    )

    if not new_auth:
        raise RuntimeError(f"Falha ao cadastrar AuthNode para o usuário {USERNAME}.")

    logger.info(
        f"AuthNode cadastrado para {USERNAME}: {new_auth.uuid}"
    )
    return new_auth

Cadastro de Caso

Para o cadastro de um caso na plataforma PLDPro, você pode utilizar o seguinte exemplo de código. Este exemplo demonstra como criar um novo caso associado a um AuthNode específico. É necessário entender que para a criação de um caso você precisa ter um AuthNode previamente cadastrado e sinalizar onde o caminho do caso que será feito o upload dos dados.

Caso com upload de dados local

Se o script precisar carregar os dados de um caso que estão armazenados localmente, a API irá criar uma pasta no workdir definido no AuthNode e fazer o upload dos dados para essa pasta. O exemplo abaixo demonstra como fazer isso:

from uuid import UUID
from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.use_cases.helpers.case_helpers import create_caso

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

 # Caminho onde o caso esta localmente para o upload
file_path_origin = "home/cases/examples/case_1"

auth_nodes = client.nodes.list_auth_nodes(node_uuid)
auth_node_uuid = auth_nodes[0].uuid

client = create_client_from_env()
caso = create_caso(client, file_path_origin, auth_node_uuid)
print(caso)

Caso com associação remota

Se o caso já existir no node de execução, você pode associá-lo diretamente sem a necessidade de upload dos dados. O exemplo abaixo demonstra como fazer isso:

from pldpro_sdk import PLDProClient, CasoRequest

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()

auth_nodes = client.nodes.list_auth_nodes(node_uuid)
auth_node_uuid = auth_nodes[0].uuid

pathRemote = "/home/user/workdir/cases/case_remoto_exemplo"

caso_request = CasoRequest(
        nome=f"Caso_Remoto_Exemplo",
        pathRemote=pathRemote,
        uuidAuthNode=auth_node_uuid,
    )

caso = client.casos.create_case(caso_request)

Licenças

Para a execução dos modelos do PLDPro, é necessário que o usuário possua licenças válidas e carregue para o sistema . Assim , na execução de um caso pelo SDK o sistema irá manipular as devidas licenças para garantir que a execução seja realizada com sucesso. Abaixo segue um exemplo para o cadastro das licenças pelo SDK:

license = client.license.create_license(
    file="/home/user/licencas/gevazp.lic",
    license_request=LicenseRequest(
        modelType=ModelTypeEnum.GEVAZP,
        licenseType=LicenseTypeEnum.MODELOS_ENERGETICOS,
        active=True,
        startAt="2026-01-01T00:00:00",
        endAt="2026-12-31T23:59:59"
    )
)

print(f"License: {license.uuid} - Modelo: {license.model_type} - Tipo: {license.license_type} - Ativa: {license.active}")

Também são disponibilizadas funções para consultas das licenças cadastradas e ativas. Abaixo segue um exemplo para obter todas as licenças, verificar uma licença específica e listar as licenças ativas para um modelo específico:

def get_license(client:PLDProClient):
    active_licenses = client.license.get_all_licenses()

    for license in active_licenses:
        print(f"License: {license.uuid} - Modelo: {license.model_type} - Tipo: {license.license_type} - Ativa: {license.active}")

def get_ative_license(client:PLDProClient):
    active_licenses = client.license.get_all_valid_licenses()

    for license in active_licenses:
        print(f"License: {license.uuid} - Modelo: {license.model_type} - Tipo: {license.license_type} - Ativa: {license.active}")


client = create_client_from_env()

print("Licenses do Tenant")
get_license(client)

print("Licenses Ativas")
get_ative_license(client)

print("Verificando disponibilidade de licenca para modelo newave...")
print(client.license.check_valide_license(model_type=ModelTypeEnum.NEWAVE))

print("Pegando detalhes da licenca ativa para newave...")
license_newave = client.license.get_license_by_model_type(model_type=ModelTypeEnum.NEWAVE)
if license_newave:
    print(f"Licenca: {license_newave.uuid} - Modelo: {license_newave.model_type} - Tipo: {license_newave.license_type} - Ativa: {license_newave.active}")

Warning

O gerenciamento de licenças é uma parte crucial para garantir a execução bem-sucedida dos casos no PLDPro. Certifique-se de que as licenças estejam ativas e válidas para os modelos que você pretende utilizar. O SDK facilita o processo de carregamento e verificação das licenças, mas é responsabilidade do usuário garantir que as licenças corretas estejam em vigor para evitar falhas na execução dos casos. O usuário verá somente as licenças ativas pela sua empresa (tenant).

Configuracao das Informacoes Iniciais do Caso

Apos criar um caso e, quando necessario, realizar o upload dos arquivos de entrada, e possivel configurar as informacoes iniciais da execucao usando o metodo config_informacoes_iniciais.

Esse metodo recebe o UUID do caso e um objeto CasoInitialDataRequest, que contem dados como periodo inicial e final, revisao inicial, encadeamento semanal, horizonte NEWAVE e nome do caso.

O metodo retorna True quando a configuracao e realizada com sucesso e False caso ocorra algum erro.

Info

O parametro caso_uuid pode ser informado como str ou UUID. Internamente, o SDK converte strings validas para UUID antes de chamar a API.

import os

from pldpro_sdk import SDKConfig, PLDProClient
from pldpro_sdk.api_client.models.caso_initial_data_request import CasoInitialDataRequest
from pldpro_sdk.api_client.models.tipo_encadeamento_semanal import (
    TipoEncadeamentoSemanal,
)


def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variavel de ambiente 'API_KEY' nao esta definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)


client = create_client_from_env()

caso_uuid = "uuid-do-caso"

initial_info = CasoInitialDataRequest(
    anoInicial=2025,
    mesInicial=8,
    anoFinal=2025,
    mesFinal=12,
    tipoEncadeamentoSemanal=TipoEncadeamentoSemanal.SEMANAL,
    mesFinalSemanal=12,
    anoFinalSemanal=2025,
    revisaoFinalSemanal=3,
    revisaoInicial=2,
    horizonteAnosNw=[2025, 2026],
    nomeCaso="caso_exemplo",
)

is_configured = client.casos.config_informacoes_iniciais(
    caso_uuid,
    initial_info,
)

if not is_configured:
    raise RuntimeError("Falha ao configurar as informacoes iniciais do caso.")

print("Informacoes iniciais configuradas com sucesso.")

Campos principais

Campo	Descricao
`anoInicial`	Ano inicial do caso.
`mesInicial`	Mes inicial do caso.
`anoFinal`	Ano final do caso.
`mesFinal`	Mes final do caso.
`tipoEncadeamentoSemanal`	Tipo de encadeamento semanal. Pode ser `TipoEncadeamentoSemanal.SEMANAL` ou `TipoEncadeamentoSemanal.MENSAL`.
`mesFinalSemanal`	Mes final da etapa semanal.
`anoFinalSemanal`	Ano final da etapa semanal.
`revisaoFinalSemanal`	Revisao final semanal.
`revisaoInicial`	Revisao inicial do caso.
`horizonteAnosNw`	Lista de anos do horizonte NEWAVE prospectivo.
`nomeCaso`	Nome do caso a ser configurado.

Boas Praticas

Para garantir que a configuracao foi aplicada corretamente, recomenda-se encapsular a chamada em uma funcao que valide o retorno do metodo:

from uuid import UUID

from pldpro_sdk import PLDProClient
from pldpro_sdk.api_client.models.caso_initial_data_request import CasoInitialDataRequest
from pldpro_sdk.api_client.models.tipo_encadeamento_semanal import (
    TipoEncadeamentoSemanal,
)


def configure_initial_info(
    client: PLDProClient,
    caso_uuid: UUID,
):
    initial_info = CasoInitialDataRequest(
        anoInicial=2025,
        mesInicial=8,
        anoFinal=2025,
        mesFinal=12,
        tipoEncadeamentoSemanal=TipoEncadeamentoSemanal.SEMANAL,
        mesFinalSemanal=12,
        anoFinalSemanal=2025,
        revisaoFinalSemanal=3,
        revisaoInicial=2,
        horizonteAnosNw=None,
        nomeCaso=f"caso_auto_{caso_uuid}",
    )

    ok = client.casos.config_informacoes_iniciais(caso_uuid, initial_info)

    if not ok:
        raise RuntimeError("Falha ao configurar informacoes iniciais do caso.")

    return ok

Esse metodo e util principalmente antes da etapa de execucao do caso, pois garante que os parametros basicos de periodo, revisao e encadeamento estejam configurados na API.

Execução de um Caso

Para executar um caso no SDK do PLDPro, você pode seguir o exemplo abaixo. Este exemplo demonstra como iniciar a execução de um caso previamente cadastrado na plataforma.

Execução em DATACENTER e CLOUD

A documentação detalhada dos cenários de execução, incluindo o fluxo SDK -> API, o uso de optionsExecutaModelo e exemplos completos para DATACENTER e CLOUD, está em Funcionalidades -> Execução Remota.

from pldpro_sdk import PLDProClient, CasoRequest

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()

auth_nodes = client.nodes.list_auth_nodes(node_uuid)
auth_node_uuid = auth_nodes[0].uuid

client = create_client_from_env()
caso = create_caso(client, file_path_origin, auth_node_uuid)

start(client, caso.uuid, ExecucaoStartRequest(version="7.0.0", tipoEntrada="DEFAULT"))

No exemplo acima, o terceiro parâmetro da função start define o payload de execução enviado para a API. Se os dados do usuário estiverem no formato padrão do PLDPro, o tipo deverá ser DEFAULT. Caso precise converter os dados da planilha Excel para o formato PLDPro, o tipo de entrada é CONVERSOR.

Quando for necessário controlar explicitamente o destino da execução, utilize ExecucaoStartRequest.optionsExecutaModelo com localExecution=DATACENTER ou localExecution=CLOUD, conforme detalhado na documentação de Execução Remota.

Warning

A função de start tem como objetivo iniciar a execução do PLDPro, seja ela com o conversor ou não. Não é possivel chamar somente o conversor pelo SDK.

Boas Práticas

Para facilitar o uso do SDK, é recomendável definir os parâmetros como nome do node e auth_node_user em variáveis. Isso torna o código mais legível e fácil de manter e facilita as chamadas que precisam de um auth_node. O Exemplo abaixo, demostra como obter o UUID do AuthNode a partir do nome do node e do usuário, criar um caso e executar.

from pldpro_sdk import PLDProClient, CasoRequest
from pldpro_sdk.use_cases.helpers.auth_node_helpers import get_auth_node_uuid_for_node_name_and_user

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

NODE_NAME = "Node Example"
AUTH_NODE_USER = "user"

file_path_origin = "home/cases/examples/case_1"

client = create_client_from_env()

auth_node_uuid = get_auth_node_uuid_for_node_name_and_user(client, NODE_NAME, AUTH_NODE_USER)

caso = create_caso(client, file_path_origin, auth_node_uuid)

start(client, caso.uuid, ExecucaoStartRequest(version="7.0.0", tipoEntrada="DEFAULT"))

Monitoramento de Casos em execução

Para monitorar os casos que estão executando em um node específico, você pode utilizar o seguinte exemplo de código. Este exemplo demonstra como obter o UUID do AuthNode a partir do nome do node e do usuário, e listar as execuções associadas a esse AuthNode.

from pldpro_sdk import PLDProClient, SDKConfig
from dotenv import load_dotenv

from pldpro_sdk.use_cases.helpers.auth_node_helpers import get_auth_node_uuid_for_node_name_and_user

load_dotenv()

NODE_NAME = "Node Example"
AUTH_NODE_USER = "user"

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()

auth_node_uuid = get_auth_node_uuid_for_node_name_and_user(client, NODE_NAME, AUTH_NODE_USER)
execucoes = client.execucoes.list_executions(auth_node_uuid) or []

for s in statuses:
    print(f"{s.caso_uuid}  ->  {s.status.value}")

Listar todos os casos existentes

from pldpro_sdk import PLDProClient, SDKConfig
from dotenv import load_dotenv

rom pprint import pprint
from uuid import UUID

load_dotenv()

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()

casos = client.casos.list_casos()

for caso in casos.elements:
    print(caso)
    print("----------------")

Informações de um caso

Para obter informações detalhadas sobre um caso específico, você pode utilizar o seguinte exemplo de código. Este exemplo demonstra como buscar um caso pelo seu UUID e exibir suas informações principais.

from pldpro_sdk import PLDProClient, SDKConfig
from dotenv import load_dotenv

rom pprint import pprint
from uuid import UUID

load_dotenv()

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()

execucoes = client.execucoes.list_executions(auth_node_uuid) or []
#Mudar a posição
print(client.casos.get_caso(execucoes[0].caso_uuid))

Troca de arquivos

Para registrar trocas de arquivos associadas ao entrada.txt de um caso, o SDK disponibiliza builders específicos para NEWAVE e DECOMP. Com isso, o consumidor informa apenas os metadados de cada troca e o caminho do arquivo correspondente, enquanto a API valida os itens, vincula cada arquivo ao seu respectivo registro e gera automaticamente os registros de controle e detalhe no entrada.txt.

Troca de arquivos do NEWAVE

from uuid import UUID
from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.models.change_files import NewaveChangeFilesBuilder

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

builder = (
    NewaveChangeFilesBuilder()
    .add_file(
        "/tmp/pldpro-sdk/change-files/newave/clast-6-2026.dat",
        mes=6,
        ano=2026,
        nome_arquivo="clast",
        extensao="dat",
    )
    .add_file(
        "/tmp/pldpro-sdk/change-files/newave/clast-7-2026.dat",
        mes=7,
        ano=2026,
        nome_arquivo="clast",
        extensao="dat",
    )
)

response = client.casos.change_files_newave(caso_uuid, builder)
print(response)

Troca de arquivos do DECOMP

from uuid import UUID
from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.models.change_files import DecompChangeFilesBuilder

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

builder = (
    DecompChangeFilesBuilder()
    .add_file(
        "/tmp/pldpro-sdk/change-files/decomp/dadger-12-2025.rv0",
        mes=12,
        ano=2025,
        nome_arquivo="dadger",
        extensao="rv0",
    )
    .add_file(
        "/tmp/pldpro-sdk/change-files/decomp/renovaveis-3-2026-rv0.csv",
        mes=3,
        ano=2026,
        nome_arquivo="renovaveis",
        extensao="csv",
        revisao=0,
    )
)

response = client.casos.change_files_decomp(caso_uuid, builder)
print(response)

Boas práticas

Utilize o builder correspondente ao tipo de troca: NewaveChangeFilesBuilder para NEWAVE e DecompChangeFilesBuilder para DECOMP.
Garanta que cada item adicionado possua um arquivo físico correspondente no caminho informado.
Evite duplicidade de competência para o mesmo tipo de troca, isto é, não envie dois itens com o mesmo mês e ano para o mesmo grupo.
Deixe a ordenação cronológica por conta da API. O ideal é focar em enviar os dados corretos, sem depender da ordem de inserção no cliente.

Parar a execução de um caso

Para parar a execução de um caso específico, você pode utilizar o seguinte exemplo de código. Este exemplo demonstra como interromper uma execução pelo UUID do caso.

import os
from dotenv import load_dotenv

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.use_cases.helpers.auth_node_helpers import get_auth_node_uuid_for_node_name_and_user

load_dotenv()

def create_client_from_env():
    api_key = os.getenv("API_KEY")
    host = os.getenv("HOST")
    retries = int(os.getenv("RETRIES"))

    if not api_key:
        raise ValueError("A variável de ambiente 'API_KEY' não está definida.")

    return PLDProClient(SDKConfig(host=host, retries=retries), api_key)

NODE_NAME = "datacenter_ampere"
AUTH_NODE_USER = "xlibs"

client = create_client_from_env()

auth_node_uuid = get_auth_node_uuid_for_node_name_and_user(client, NODE_NAME, AUTH_NODE_USER)
execucoes = client.execucoes.list_executions(auth_node_uuid) or []

client.execucoes.stop_execution(execucoes[0].caso_uuid)

Troca de versões

Para registrar trocas de versão dos modelos ao longo do horizonte do prospectivo, o SDK disponibiliza builders específicos para NEWAVE, DECOMP e GEVAZP. A API gera automaticamente os registros de controle e detalhe no entrada.txt, sem que o consumidor precise conhecer os cards do entrada.

Troca de versões do NEWAVE

from uuid import UUID
from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.models import NewaveChangeVersionsBuilder

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

builder = (
    NewaveChangeVersionsBuilder()
    .add_version(mes=1, ano=2025, versao="newave_v1")
    .add_version(mes=3, ano=2025, versao="newave_v2")
)

response = client.casos.change_versions_newave(caso_uuid, builder)
print(response)

Troca de versões do DECOMP

from pldpro_sdk.models import DecompChangeVersionsBuilder

builder = (
    DecompChangeVersionsBuilder()
    .add_version(mes=2, ano=2025, versao="decomp_v1")
    .add_version(mes=4, ano=2025, versao="decomp_v2")
)

response = client.casos.change_versions_decomp(caso_uuid, builder)
print(response)

Troca de versões do GEVAZP

from pldpro_sdk.models import GevazpChangeVersionsBuilder

builder = (
    GevazpChangeVersionsBuilder()
    .add_version(mes=1, ano=2025, versao="gevazp_v1")
    .add_version(mes=5, ano=2025, versao="gevazp_v2")
)

response = client.casos.change_versions_gevazp(caso_uuid, builder)
print(response)

Remover trocas existentes

Para remover todas as trocas de versão de um modelo, basta passar um builder vazio. A API gera o card com indicativo de ausência (n).

response = client.casos.change_versions_newave(caso_uuid, NewaveChangeVersionsBuilder())
print(response)

Boas práticas

Utilize o builder correspondente ao modelo: NewaveChangeVersionsBuilder, DecompChangeVersionsBuilder ou GevazpChangeVersionsBuilder.
A ordem de inserção não importa — a API sempre ordena cronologicamente por ano e mês.
Não envie dois itens com o mesmo mês e ano para o mesmo modelo.
A operação atualiza o entrada.txt no servidor da API. O arquivo local do deck não é modificado.

Número de processadores dos modelos

Para registrar o número de processadores dos modelos NEWAVE e DECOMP, o SDK disponibiliza métodos de alto nível que recebem apenas a quantidade de processadores. A API valida o valor informado e atualiza automaticamente os registros correspondentes no entrada.txt, sem que o consumidor precise conhecer os cards do entrada.txt.

Número de processadores do NEWAVE

from uuid import UUID
from pldpro_sdk import PLDProClient, SDKConfig

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

response = client.casos.change_processors_newave(caso_uuid, 8)

if response is not None:
    print(response.tipo)
    print(response.quantidade_processadores)
    print(response.entrada_atualizada)

Número de processadores do DECOMP

from uuid import UUID
from pldpro_sdk import PLDProClient, SDKConfig

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

response = client.casos.change_processors_decomp(caso_uuid, 12)

if response is not None:
    print(response.tipo)
    print(response.quantidade_processadores)
    print(response.entrada_atualizada)

Boas práticas

Informe sempre um valor inteiro e não negativo.
Para o NEWAVE, utilize valores entre 0 e 999.
Para o DECOMP, utilize valores entre 0 e 99.
O SDK abstrai os cards, enquanto a API reflete automaticamente os valores em NUMPROCSNW e NWNUMPROCSRE para NEWAVE, e em NUMPROCSDC e DCNUMPROCSRE para DECOMP.
A leitura do entrada.txt continua considerando apenas os cards locais como fonte de verdade: NUMPROCSNW para NEWAVE e NUMPROCSDC para DECOMP.

Configuração de geração e seleção de registros do DADGER

Para configurar a geração do DADGER e selecionar quais registros deverão ser modificados, utilize o DadgerConfigBuilder. O SDK recebe uma intenção de configuração e a API reflete os valores necessários no entrada.txt, sem exigir que o consumidor conheça os cards.

from uuid import UUID

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.models import DadgerConfigBuilder, DadgerGenerationType, RegistroDadger

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

builder = (
    DadgerConfigBuilder()
    .enable(DadgerGenerationType.MIXED, stop_after_generation=False)
    .set_complete_start(mes=1, ano=2025)
    .set_selection_start(mes=3, ano=2025)
    .select_records([
        RegistroDadger.DP,
        RegistroDadger.VE,
        RegistroDadger.HE,
    ])
)

response = client.casos.configure_dadger(caso_uuid, builder)

if response is not None:
    print(response.gerar_dadger)
    print(response.tipo_geracao_dadger)
    print(response.parar_apos_gerar_dadger)
    print(response.registros_dadger_modificados)
    print(response.entrada_atualizada)

Para desativar a geração do DADGER, use o builder desabilitado. Nesse caso, a API mantém o comportamento de comentário dos demais cards associados.

builder = DadgerConfigBuilder().disable()
response = client.casos.configure_dadger(caso_uuid, builder)
print(response)

Boas práticas

Utilize DadgerGenerationType.COMPLETE para DADGER completo, DadgerGenerationType.RECORD_SELECTION para seleção de registros e DadgerGenerationType.MIXED para o modo misto.
Informe as datas necessárias conforme o tipo de geração escolhido.
Use os enums de RegistroDadger, como RegistroDadger.DP, RegistroDadger.VE e RegistroDadger.HE, em vez de informar nomes de cards manualmente.
Evite repetir o mesmo registro na seleção, pois o SDK valida duplicidade antes de enviar a requisição.

Configuração de execução com partida

Para configurar a execução com partida, utilize o ExecutionWithPartidaBuilder. Ele permite definir se o caso usa partida, se há partida mensal e qual modelo será usado como ponto de partida quando aplicável.

from uuid import UUID

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.models import ExecutionWithPartidaBuilder, ModeloPartida

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

builder = (
    ExecutionWithPartidaBuilder()
    .use_partida(True)
    .set_monthly_partida(True)
    .set_starting_model(ModeloPartida.NW)
)

response = client.casos.configure_execution_with_partida(caso_uuid, builder)

if response is not None:
    print(response.executa_partida)
    print(response.partida_mensal)
    print(response.modelo_partida)
    print(response.entrada_atualizada)

Também é possível desabilitar o uso de partida. Quando use_partida(False) é informado, o modelo de partida não é obrigatório.

builder = (
    ExecutionWithPartidaBuilder()
    .use_partida(False)
    .set_monthly_partida(False)
)

response = client.casos.configure_execution_with_partida(caso_uuid, builder)
print(response)

Boas práticas

Use ModeloPartida.GV, ModeloPartida.NW ou ModeloPartida.DC para selecionar o modelo de partida.
Informe set_starting_model apenas quando a execução com partida estiver habilitada.
Deixe a conversão para os cards EXECUTAPARTIDA, PARTMES e MODELOPPQ sob responsabilidade do SDK e da API.

Configuração de execução dos modelos, revisão de parada, versões e viabilização do DECOMP

Para configurar a execução dos modelos e seus dados relacionados, utilize o ModelExecutionConfigBuilder. A mesma chamada pode configurar execução, versões, revisão de parada e viabilização do DECOMP, mas também é possível enviar apenas parte dessas informações em uma chamada incremental.

from uuid import UUID

from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.models import ModelExecutionConfigBuilder

client = create_client_from_env()
caso_uuid = UUID("00000000-0000-0000-0000-000000000000")

builder = (
    ModelExecutionConfigBuilder()
    .set_newave(enabled=True, version="29.1")
    .set_gevazp(enabled=True, version="4.2")
    .set_decomp(enabled=True, version="31.17")
    .set_dessem(True)
    .set_stop_revision(3)
    .set_decomp_viabilization(enabled=True, max_attempts=5)
)

response = client.casos.configure_execution_models(caso_uuid, builder)

if response is not None:
    print(response.executa_newave, response.versao_newave)
    print(response.executa_gevazp, response.versao_gevazp)
    print(response.executa_decomp, response.versao_decomp)
    print(response.executa_dessem)
    print(response.revisao_parada)
    print(response.viabiliza_decomp)
    print(response.numero_tentativas_viabiliza_decomp)
    print(response.entrada_atualizada)

Exemplo de atualização parcial, alterando apenas a revisão de parada e a viabilização do DECOMP:

builder = (
    ModelExecutionConfigBuilder()
    .set_stop_revision(2)
    .set_decomp_viabilization(enabled=True, max_attempts=3)
)

response = client.casos.configure_execution_models(caso_uuid, builder)
print(response)

Boas práticas

Configure a versão do modelo quando habilitar sua execução, garantindo que o estado final do caso fique consistente.
Use set_newave, set_gevazp, set_decomp e set_dessem para trabalhar por intenção, sem manipular diretamente EXECNW, EXECGVP, EXECDCP ou EXECDSS.
Use set_stop_revision para refletir REVPARADA quando houver revisão de parada aplicável.
Use set_decomp_viabilization para configurar a flag e o número máximo de tentativas de FLAGVIABDC.