onerom-core 0.2.2

SDK oficial para automacoes ONEROM

onerom-core

SDK oficial Python para automações ONEROM.

Usado dentro de bots executados pelo ONEROM Runner.

Instalação

pip install onerom-core

Ou via pyproject.toml do bot:

[project]
dependencies = ["onerom-core>=0.1.0"]

Uso básico

from onerom_core import OneromExecution
import logging

# Inicializa contexto da execução
# - Carrega parâmetros da execução automaticamente
# - Anexa handler de log estruturado ao logger raiz
exec = OneromExecution()

# Acesso a parâmetros tipados
nome = exec.params.nome
count = exec.params.count

# Logging — capturado pelo runner e enviado ao backend
logging.info(f"Processando {nome}")

# Contagem de itens
for item in get_items():
    try:
        process(item)
        exec.add_success_item()
    except Exception:
        exec.add_failed_item()

# Finaliza com sucesso
exec.finish_success()

Uso com wrapper automático

from onerom_core import OneromExecution

exec = OneromExecution()

def main():
    logging.info("Bot iniciado")
    # ... lógica do bot ...

# Gerencia mark_running → main() → finish_success/failed automaticamente
exec.run(main)

Ciclo de vida

Método	Descrição
mark_running()	Notifica backend que a execução começou
add_success_item()	Incrementa contador de itens processados
add_failed_item()	Incrementa contador de itens que falharam
report_progress(processed, total)	Reporta progresso parcial
finish_success()	Finaliza como bem-sucedida
finish_failed(error_message)	Finaliza como falha
run(fn)	Wrapper automático completo

Parâmetros

Os parâmetros são injetados pelo runner via ONEROM_CONTEXT e ONEROM_PARAMETERS.

exec = OneromExecution()

# Acesso por atributo
valor = exec.params.meu_parametro

# Acesso como dict (sem schema)
dados = exec.params.as_dict()

Schema tipado (opcional)

Se ONEROM_PARAM_SCHEMA estiver definido, os parâmetros são validados com Pydantic:

# Backend retorna schema:
# [{"name": "cnpj", "type": "string", "required": true}]
# Validação automática e acesso tipado:
cnpj: str = exec.params.cnpj

Tipos suportados: string, int, double, bool, json, list

Logging

O OneromLogHandler é anexado automaticamente ao logger raiz. Cada chamada de log gera uma linha JSON no stdout, que o runner captura e envia ao backend.

import logging

logging.info("Processando item")    # → backend via runner
logging.warning("Item ignorado")
logging.error("Falha ao processar")

# Logger customizado
exec.attach_logger(logging.getLogger("meu_modulo"))

Variáveis de ambiente

Injetadas automaticamente pelo runner:

Variável	Descrição
ONEROM_EXECUTION_ID	ID da execução atual
ONEROM_BOT_NAME	Nome do bot
ONEROM_RUNNER_ID	ID do runner
ONEROM_PARAMETERS	JSON com parâmetros da execução
ONEROM_CONTEXT	JSON com contexto completo
ONEROM_METRICS_FILE	Caminho do arquivo de métricas
ONEROM_API_URL	Base da API runner-agent (.../api/v1/runner-agent)
ONEROM_RUNNER_KEY	Chave de autenticação do runner

Contrato oficial: ../RUNNER_ENV_CONTRACT.md