tenant-rpa-sdk 0.1.0
SDK de logging resiliente para RPAs no backend rpa_logs
Requires Python: >=3.10

# tenant-rpa-sdk

SDK Python para RPAs com foco em logging resiliente no backend `rpa_logs`, sem acoplamento ao `tenant-system`.

## Objetivo
- Padronizar logs de RPAs em `rpa_logs`
- Evitar perda de eventos em indisponibilidade temporaria do DB
- Fornecer API simples para uso em qualquer automacao Python

## Escopo
- Somente logging (sem lifecycle `start/heartbeat/finish`)
- Postgres-only (`psycopg`)
- Dedupe por `idempotency_key`
- Fallback local em JSONL + reconciliacao por `flush_pending()`

## Instalacao

### Desenvolvimento local
```bash
cd tenant-rpa-sdk
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .[dev]
```

### Consumo em RPAs (producao)
Use versao pinada:
```txt
tenant-rpa-sdk==0.1.0
```

Canal 1 (oficial) - PyPI publico:
```bash
pip install tenant-rpa-sdk==0.1.0
```

Canal 2 - package no GitHub (asset da Release):
```bash
pip install "https://github.com/tech-ops-ai/tenant-rpa-sdk/releases/download/tenant-rpa-sdk-v0.1.0/tenant_rpa_sdk-0.1.0-py3-none-any.whl"
```

Se seu ambiente usa mirror privado, ajuste `--index-url`/`--extra-index-url` no `pip`.

## Variaveis de ambiente
- `MAESTRO_PROD` ou `MAESTRO`
- `RPA_LOGS_TABLE` (default `rpa_logs`)
- `RPA_LOG_SOURCE` (default `rpa.app`)
- `RPA_LOG_FALLBACK_PATH` (default `/var/log/tenant-rpa/pending_rpa_logs.jsonl`)
- `RPA_LOG_FLUSH_ON_START` (default `true`)
- `RPA_LOG_DB_TIMEOUT_SECONDS` (default `5`)
- `RPA_LOG_MAX_MESSAGE_CHARS` (default `2000`)
- `RPA_LOG_MAX_METADATA_BYTES` (default `32768`)

## Conexao Maestro
Formato esperado:
```txt
postgres,<host>,<port>,<database>,<user>,<password>
```

Alias encadeado aceito:
```txt
MAESTRO_PROD=MAESTRO
MAESTRO=postgres,db.host,5432,maestro,rpa,***
```

Se `MAESTRO_PROD` nao existir, o SDK tenta automaticamente `MAESTRO`.

## Uso rapido
```python
from tenant_rpa_sdk import TenantBackendLogger

logger = TenantBackendLogger(
    project_name="c6-egv",
    source="rpa.cart-abandonment",
    execution_id=123,
    db_alias_env="MAESTRO_PROD",
    fallback_path="/tmp/pending_rpa_logs.jsonl",
    echo_stdout=True,
    flush_on_start=True,
)

logger.info("RPA iniciado", metadata={"step": "bootstrap"})
logger.warning("API lenta", metadata={"latency_ms": 1200})
logger.error("Falha em consulta", metadata={"query_id": "q-09", "token": "secret"})

result = logger.flush_pending(limit=200)
print(result)
```

## API publica
Classe principal: `tenant_rpa_sdk.logger.TenantBackendLogger`

Metodos:
- `debug(message, *, event_type="APP", metadata=None, execution_id=None)`
- `info(...)`
- `warning(...)`
- `error(...)`
- `critical(...)`
- `log(level, message, *, event_type="APP", metadata=None, execution_id=None)`
- `bind_execution(execution_id)`
- `flush_pending(limit=200) -> dict`

## Contrato de fallback JSONL
Cada linha contem:
- `idempotency_key`
- `created_at`
- `payload`
- `attempt`
- `last_error`
- `next_retry_at`

## Versionamento e release
- Politica: SemVer estrito (`MAJOR.MINOR.PATCH`)
- Tags de release: `tenant-rpa-sdk-vX.Y.Z`
- Publicacao automatica no PyPI por GitHub Actions ao criar tag valida
- Os artefatos `.whl` e `.tar.gz` tambem sao anexados na GitHub Release da mesma tag

Consulte:
- `CHANGELOG.md`
- `CONTRIBUTING.md`
- `docs/versionamento.md`
- `docs/release.md`
- `docs/uso-em-rpas.md`
- `docs/faq.md`

## Testes
Unitarios:
```bash
pytest tests/unit
```

Integracao (Postgres real, execucao opt-in):
```bash
export TENANT_RPA_SDK_INTEGRATION=true
pytest tests/integration
```