# ZSyncTech Studio SDK

SDK Python para monitoramento de execuções com integração à plataforma ZSyncTech.

## O que é o ZSyncTech Studio SDK?

O ZSyncTech Studio SDK é uma biblioteca Python desenvolvida para facilitar a criação de robôs de automação que se integram perfeitamente com a plataforma ZSyncTech. Ele fornece uma estrutura padronizada para organizar seu código em execuções, tarefas e passos, permitindo monitoramento em tempo real, tratamento de erros e rastreabilidade completa de cada operação.

Com o SDK, você pode transformar qualquer script Python em um robô de automação profissional, com logs estruturados, métricas de desempenho e integração com a plataforma de gerenciamento.

## Funcionalidades Principais

### Decorators Intuitivos
Use `@execution`, `@task` e `@step` para estruturar seu código de forma clara e organizada. Cada decorator adiciona automaticamente monitoramento, logging e integração com a plataforma sem necessidade de código adicional.

### Monitoramento em Tempo Real
Acompanhe o progresso das suas execuções diretamente na plataforma ZSyncTech. Veja em tempo real quantas tarefas foram processadas, quais estão em andamento e identifique rapidamente problemas quando ocorrem.

### Tratamento Inteligente de Exceções
Mapeie exceções específicas para status personalizados da plataforma. Por exemplo, configure para que uma exceção `OutOfHoursError` finalize a execução com status `OUT_OF_OPERATING_HOURS` ao invés de um erro genérico.

### Sistema de Observers
Receba notificações de eventos durante a execução através de observers customizáveis. Ideal para integração com sistemas de alerta, logging personalizado ou qualquer ação que precise ser executada em resposta a eventos específicos.

### Deploy Simplificado
Transforme seu robô em um serviço que aguarda comandos da plataforma com apenas uma chamada de método. O SDK gerencia toda a comunicação HTTP, autenticação e sincronização de status automaticamente.

## Instalação

```bash
pip install zsynctech-studio-sdk
```

Ou usando uv:

```bash
uv add zsynctech-studio-sdk
```

## Exemplo Rápido

```python
from zsynctech_studio_sdk import execution, task, step, set_total_tasks

@step(code="0001")
def processar_dados():
    # Sua lógica aqui
    pass

@task
def minha_tarefa():
    processar_dados()

@execution
def minha_execucao():
    set_total_tasks(10)

    for i in range(10):
        minha_tarefa()

if __name__ == "__main__":
    minha_execucao()
```

### Deploy para Plataforma

Para integrar com a plataforma ZSyncTech:

```python
from zsynctech_studio_sdk import execution, task, step, set_total_tasks, ExecutionStatus

class OutOfHoursError(Exception):
    pass

@step(code="STEP-001")
def passo_um():
    print("Executando passo 1")

@task
def processar_item():
    passo_um()

@execution(
    exception_handlers={
        KeyboardInterrupt: ExecutionStatus.INTERRUPTED,
        OutOfHoursError: ExecutionStatus.OUT_OF_OPERATING_HOURS
    }
)
def meu_robo():
    set_total_tasks(10)

    for _ in range(10):
        processar_item()

if __name__ == "__main__":
    meu_robo.deploy(
        instance_id="seu-instance-id",
        secret_key="sua-secret-key",
        server="https://api.zsynctech.com",
        port=8080
    )
```

## Estrutura Hierárquica

O SDK segue uma hierarquia de três níveis que reflete a estrutura típica de um processo de automação:

```
Execution
├── Task 1
│   ├── Step 1
│   ├── Step 2
│   └── Step 3
├── Task 2
│   ├── Step 1
│   └── Step 2
└── Task 3
    └── Step 1
```

### Execution (Execução)
Representa uma execução completa do robô. É o nível mais alto da hierarquia e engloba todo o processamento. Uma execução pode conter múltiplas tasks e mantém métricas gerais como total de tarefas, tarefas concluídas e tempo de execução.

**Exemplo**: "Processamento diário de notas fiscais"

### Task (Tarefa)
Representa uma unidade de trabalho dentro da execução. Geralmente corresponde ao processamento de um item individual. Tasks podem ser configuradas com retry automático e mantêm métricas dos steps executados.

**Exemplo**: "Processar nota fiscal #12345"

### Step (Passo)
Representa uma ação atômica dentro de uma task. É o nível mais granular e permite rastreamento detalhado de cada operação realizada. Steps são úteis para identificar exatamente onde um erro ocorreu.

**Exemplo**: "Preencher campo CNPJ", "Clicar no botão Salvar"
