# onerom-core

SDK oficial Python para automações ONEROM.

Usado dentro de bots executados pelo ONEROM Runner.

## Instalação

```bash
pip install onerom-core
```

Ou via `pyproject.toml` do bot:

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

## Uso básico

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

```python
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 variável de ambiente `ONEROM_PARAMETERS`.

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

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

```python
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` | URL base da API runner-agent |
| `ONEROM_RUNNER_KEY` | Chave de autenticação do runner |
