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, Retentativa, Robo


class CadastroDePedido(Robo):
    chave = ("cliente", "pedido")  # a chave de negócio do item
    retentativas = Retentativa(sistema=3)  # erro de sistema repete; negócio nunca

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

    def processar(self, item: Item, pagina) -> None:
        with item.etapa("preencher"):  # tempo, resultado e erro no relatório
            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), with item.etapa(nome), item.saida(**campos), item.reter(motivo), item.log(texto).
• Retentativa(sistema=N, espera=Exponencial(base, teto), sessao_perdida="reentrar" | "falhar"): a política por classe de falha. Negócio nunca repete, e nada repete depois do __enter__ de efetivar().
• O item que falha deixa a tela e o trecho do trace do Playwright em evidencias/<sha256 da chave>/, com teto por item e por run e os dados do item mascarados (SHADE_MASCARAR_PII=0 desliga); o que passa não guarda nada.
• 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, política de retentativa, efetivar, etapas, resumo).
• shade_sdk.runtime.evidencia: o trace por item, a tela, a máscara e os tetos.
• 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.