bot-runner

Executor integrado de automações — conecta yaml-workflow-engine e bot-report-api em um único runner com CLI.

---

O problema

Com múltiplas libs de automação, falta um componente que:

1. Execute o workflow definido em YAML
2. Registre início e fim da execução automaticamente
3. Reporte o resultado para uma API central de observabilidade

bot-runner resolve isso, fechando o ciclo ponta a ponta.

---

Arquitetura do ecossistema

┌──────────────────────────────────────────────────────┐
│                      bot-runner                      │
│                                                      │
│   ┌──────────────────┐    ┌────────────────────┐    │
│   │ yaml-workflow-   │    │  bot-report-api    │    │
│   │    engine        │───▶│  (registro e       │    │
│   │ (executa YAML)   │    │   métricas)        │    │
│   └──────────────────┘    └────────────────────┘    │
└──────────────────────────────────────────────────────┘

---

Instalação

git clone https://github.com/EricJoness/bot-runner.git
cd bot-runner
pip install -e "."

---

Uso via CLI

# Executar um workflow (bot-report-api em localhost:8000)
bot-runner examples/pipeline_dados.yaml

# Apontar para API em outro servidor
bot-runner workflow.yaml --api http://meu-server:8000

# Executar sem reportar para a API
bot-runner workflow.yaml --sem-api

Saída:

🤖 Iniciando: pipeline_dados.yaml

[LOG:INFO] 🤖 Iniciando pipeline de dados...
[LOG:INFO] 📥 Buscando dados da origem...
[LOG:INFO] ✅ Dados processados com sucesso!
[LOG:INFO] 📧 Relatório enviado para o time!

✅ Pipeline de Dados — 4/4 steps em 0.01s

---

Uso como biblioteca

from bot_runner import BotRunner, Config

config = Config(
    api_url="http://localhost:8000",  # URL do bot-report-api
    parar_na_falha=True,
    log_level="INFO",
)

runner = BotRunner(config=config)
resultado = runner.executar(
    "workflow.yaml",
    nome_bot="Pipeline de Dados",
    dados_iniciais={"ambiente": "producao"},
)

print(resultado)
# ✅ Pipeline de Dados — 3/3 steps em 0.45s

print(resultado.exec_id)       # ID no bot-report-api
print(resultado.sucesso)       # True / False
print(resultado.duracao_segundos)

---

Workflow YAML de exemplo

nome: Pipeline de Dados

steps:
  - type: log
    mensagem: "🤖 Iniciando pipeline..."

  - type: http_get
    url: "https://api.exemplo.com/dados"
    salvar_como: resposta

  - type: log
    mensagem: "✅ Concluído!"

---

Comportamento sem API

Se o bot-report-api não estiver disponível, o bot-runner ainda executa o workflow normalmente — a integração com a API é opcional e não bloqueia a automação.

---

Configuração via variáveis de ambiente

Variável	Padrão	Descrição
BOT_REPORT_API_URL	http://localhost:8000	URL do bot-report-api
BOT_REPORT_API_TIMEOUT	10	Timeout HTTP em segundos
BOT_RUNNER_LOG_LEVEL	INFO	Nível de log
BOT_RUNNER_PARAR_NA_FALHA	true	Interrompe ao falhar step

---

Executar os testes

pip install -e ".[dev]"
pytest tests/ -v --cov=bot_runner

---

Estrutura do projeto

bot-runner/
├── bot_runner/
│   ├── runner.py      # BotRunner (orquestrador principal)
│   ├── api_client.py  # Cliente HTTP para o bot-report-api
│   ├── config.py      # Configuração via env vars
│   └── cli.py         # Interface de linha de comando
├── tests/
│   └── test_runner.py
└── examples/
    ├── pipeline_dados.yaml
    └── exemplo_uso.py

---

Relacionado

Repo	Papel
yaml-workflow-engine	Engine que executa os workflows YAML
bot-report-api	API REST que recebe os relatórios
botflow	Orquestrador alternativo orientado a steps Python

---

Licença

MIT © Eric Jones Silva