Metadata-Version: 2.5
Name: shade-sdk
Version: 0.4.0
Summary: O runtime dos robôs da ShadeOne: ledger por chave de negócio, recuperação, relatório e o protocolo com o executor.
Author: ShadeOne
License-Expression: Apache-2.0
Requires-Python: >=3.11
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# 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`.

```python
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.
