shade-sdk

O runtime e o framework dos robôs da ShadeOne. O robô gerado pela plataforma importa este pacote, na versão fixada pelo requirements.lock da imagem do sandbox, e o robô escrito à mão importa o mesmo pacote (ADR 019, D1). O import é shade_sdk.

from shade_sdk import Item, Robo


class CadastroDePedido(Robo):
    chave = ("cliente", "pedido")                 # a chave de negócio do item

    def entrar(self, pagina) -> None:             # opcional: ao abrir a sessão e se ela cair
        ...

    def processar(self, item: Item, pagina) -> None:
        pagina.goto(self.config["base_url"] + "/pedidos/novo")
        pagina.get_by_label("Cliente").fill(item["cliente"])
        with item.efetivar("salvar pedido"):      # o ensaio para aqui; o real registra antes
            pagina.get_by_role("button", name="Salvar").click()

main.py na raiz do projeto: CadastroDePedido.main(). Sem flag, roda em modo real, como o robô gerado; --rehearsal é o ensaio. A entrada é --input <arquivo.json>, ou data/input.json (onde a plataforma a deixa), ou [itens] exemplo do shade.toml.

• Robo (uma lista de itens) e Tarefa (uma execução única, executar(item, pagina)).
• Item: item["campo"], item.chave, with item.efetivar(nome), item.saida(**campos), item.reter(motivo), item.log(texto).
• self.segredo(nome): só a credencial declarada em [credenciais] nomes; self.config: a tabela [config].
• Erros: ErroDeNegocio (não repete), SessaoPerdida (entra de novo e refaz), ErroDeContrato, e os sinais ParadaDoEnsaio e ItemRetido (BaseException: um except Exception não os engole).
• shade_sdk.testing: ExecutorLocal (o lado do executor do protocolo, com o robô em subprocesso) e pagina_local (um site local que conta os efeitos).

O runtime:

• shade_sdk.runtime.laco: o laço por item (ledger, retomada, recuperação, efetivar, resumo).
• shade_sdk.runtime.ledger: identidade do item por chave de negócio, o incerto gravado antes de efetivar e o canal do registro com o executor.
• shade_sdk.runtime.recovery: classificação da falha, sessão perdida e modal inesperado.
• shade_sdk.runtime.report: relatório HTML da execução e o histórico.
• shade_sdk.runtime.config: Settings e a carga do .env.
• shade_sdk.runtime.output: a planilha de saída, com ou sem mascaramento de PII.
• shade_sdk.runtime.protocolo: o número e o formato do contrato robô ↔ executor, inclusive a entrada (main.py, argv e ambiente).

Testes do pacote: cd sdk && uv run pytest (Chromium do Playwright instalado).

Licença: Apache-2.0.