Metadata-Version: 2.4
Name: yt-gsheet-orchestrator
Version: 0.1.1
Summary: Sistema de orquestração distribuída para processar playlists e canais do YouTube usando Google Sheets como camada de coordenação
Project-URL: Homepage, https://github.com/AndreKoraleski/YT-G-Sheets-Orchestrator
Project-URL: Documentation, https://github.com/AndreKoraleski/YT-G-Sheets-Orchestrator#readme
Project-URL: Repository, https://github.com/AndreKoraleski/YT-G-Sheets-Orchestrator
Project-URL: Issues, https://github.com/AndreKoraleski/YT-G-Sheets-Orchestrator/issues
Author-email: Andre Koraleski <andrekorale@gmail.com>
License: Copyright (c) 2025 Andre Koraleski
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: distributed,google-sheets,metadata,orchestration,pipeline,task-queue,youtube,yt-dlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Requires-Dist: google-auth>=2.0.0
Requires-Dist: gspread>=6.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: yt-dlp>=2024.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# YT G-Sheets Orchestrator

Sistema de orquestração distribuída para processar playlists e canais do YouTube usando Google Sheets como camada de coordenação.

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

---

**Documentação**: [Início Rápido](QUICKSTART.md) | [Exemplos](examples/) | [Deployment](DEPLOYMENT.md) | [Contribuindo](CONTRIBUTING.md) | [Changelog](CHANGELOG.md)

---

## Visão Geral

Este projeto implementa um sistema de processamento distribuído de tarefas onde múltiplos workers se coordenam através do Google Sheets para extrair metadados de fontes do YouTube e processar vídeos individuais. Cada worker opera independentemente com sua própria service account, usando eleição de liderança e ownership baseado em claim para distribuir trabalho com segurança entre o cluster.

## Arquitetura

O sistema usa um padrão de pipeline com três tabelas tanto para sources quanto para tasks:

- **Fila Principal**: Itens pendentes aguardando reivindicação
- **History**: Itens completados com sucesso
- **DLQ (Dead Letter Queue)**: Itens falhados com mensagens de erro

Workers se registram em uma tabela Workers com IDs únicos, heartbeats e estatísticas de processamento. Eleição de liderança é usada para coordenar o processamento de sources, enquanto tasks individuais podem ser reivindicadas por qualquer worker ativo.

## Requisitos

- Python 3.10+
- Google Cloud service account com acesso à API do Sheets
- yt-dlp para extração de metadados do YouTube

## Instalação

### Via PyPI

```bash
# Usando uv (recomendado)
uv pip install yt-gsheet-orchestrator

# Ou usando pip
pip install yt-gsheet-orchestrator
```

### Para Desenvolvimento

```bash
# Clone o repositório
git clone https://github.com/AndreKoraleski/YT-G-Sheets-Orchestrator.git
cd YT-G-Sheets-Orchestrator

# Instale com dependências de desenvolvimento
uv pip install -e ".[dev]"
```

## Configuração

Crie um arquivo `.env` na raiz do projeto com as seguintes variáveis:

```env
WORKER_NAME=worker-1
SPREADSHEET_ID=your-spreadsheet-id
SERVICE_ACCOUNT_FILE=path/to/service-account.json
```

### Variáveis de Ambiente

- `WORKER_NAME`: Identificador único para esta instância de worker (obrigatório)
- `SPREADSHEET_ID`: ID da planilha do Google Sheets (obrigatório)
- `SERVICE_ACCOUNT_FILE`: Caminho para o arquivo JSON da service account do Google Cloud (obrigatório)

## Uso

### Executando um Worker

```bash
# Com uv
uv run python -m orc

# Ou diretamente se instalado no ambiente
python -m orc
```

O worker irá:
1. Registrar ou recuperar sua sessão na tabela Workers
2. Tentar reivindicar tasks disponíveis da fila Tasks
3. Se não houver tasks, adquirir liderança para processar sources
4. Extrair metadados de URLs do YouTube e criar novas tasks
5. Processar tasks chamando a função callback configurada
6. Realizar shutdown gracioso em SIGINT/SIGTERM

### Uso Programático

```python
from orc import Config, Orchestrator

# Inicializa com variáveis de ambiente
config = Config()
orchestrator = Orchestrator(config)

# Define callback de processamento de task
def process_video(url: str) -> None:
    """
    IMPORTANTE: Propague exceções! O orchestrator capturará erros
    automaticamente e moverá tasks falhadas para a DLQ com detalhes.
    """
    print(f"Processando: {url}")
    
    # Se algo der errado, levante uma exceção
    if not url.startswith("https://"):
        raise ValueError(f"URL inválida: {url}")
    
    # Sua lógica de processamento aqui
    # Qualquer exceção será capturada e registrada na DLQ

# Processa tasks em loop
while orchestrator.process_next_task(process_video):
    orchestrator.send_heartbeat()
```

### Adicionando Sources

Adicione URLs de playlists ou canais do YouTube diretamente na tabela Sources do Google Sheets:

| ID | URL | Nome | Quantidade de Vídeos | Timestamp de Reivindicação | Timestamp de Conclusão | Status | Worker Atribuído |
|----|-----|------|----------------------|---------------------------|------------------------|--------|------------------|
| | https://youtube.com/playlist?list=... | | | | | PENDING | |

O sistema automaticamente irá:
- Atribuir um UUID à source
- Extrair metadados usando yt-dlp
- Criar tasks individuais para cada vídeo
- Mover a source para History após conclusão

## Estrutura do Google Sheets

### Tabela Workers

Rastreia workers ativos e suas estatísticas de processamento.

**Cabeçalhos**: ID do Worker, Nome do Worker, Último Heartbeat, Status, Tarefas Processadas, Fontes Processadas

### Tabelas Tasks

- **Tasks**: Fila principal com tasks pendentes
- **Tasks History**: Tasks processadas com sucesso
- **Tasks DLQ**: Tasks falhadas com mensagens de erro

**Cabeçalhos**: ID, ID da Fonte, URL, Nome, Duração, Timestamp de Criação, Timestamp de Reivindicação, Timestamp de Conclusão, Status, Worker Atribuído

### Tabelas Sources

- **Sources**: Fila principal com sources pendentes
- **Sources History**: Sources processadas com sucesso
- **Sources DLQ**: Sources falhadas com mensagens de erro

**Cabeçalhos**: ID, URL, Nome, Quantidade de Vídeos, Timestamp de Reivindicação, Timestamp de Conclusão, Status, Worker Atribuído

### Tabela de Eleição de Líderes

Coordena liderança distribuída para processamento de sources.

**Cabeçalhos**: Nome da Eleição, Worker ID, Expira Em

## Funcionalidades

### Coordenação Distribuída

- **Registro de Workers**: Cada worker mantém uma sessão única com persistência de UUID
- **Eleição de Liderança**: Coordenação baseada em lease para processamento de sources (TTL de 5 minutos)
- **Ownership por Claim**: Workers reivindicam tasks/sources usando operações atômicas
- **Deduplicação**: Verificação automática contra History e DLQ antes do processamento

### Rate Limiting

O sistema implementa rate limiting dinâmico no nível do gateway:

- Rate limit base: 1.0 segundo entre chamadas de API
- Jitter escalável: Aumenta proporcionalmente com workers ativos
  - 1 worker: sem jitter
  - 2 workers: até 0.5s de jitter
  - 5 workers: até 2.0s de jitter

Isso previne esgotamento de quota da API enquanto permite que múltiplos workers operem eficientemente.

### Tolerância a Falhas

- **Shutdown Gracioso**: Handlers de SIGINT/SIGTERM marcam workers como INACTIVE e liberam liderança
- **Retry Automático**: Erros transientes são retentados com backoff exponencial
- **Dead Letter Queue (DLQ)**: Sistema de captura de erros
  - Qualquer exceção levantada no callback é automaticamente capturada
  - Tasks/Sources falhadas são movidas para DLQ com mensagem de erro completa
  - **IMPORTANTE**: Sempre propague exceções no seu callback - não as capture internamente
  - O orchestrator garante que `str(e)` seja registrado na coluna de erro da DLQ
  - Ideal para debugging: veja exatamente o que falhou e por quê
- **Recuperação de Sessão**: Workers podem retomar sua sessão anterior ao reiniciar

### Extração de Metadados

Usa yt-dlp para extrair:
- IDs de vídeo diretamente das URLs do YouTube (formato de 11 caracteres)
- Nomes de playlists/canais e contagens de vídeos
- Títulos e durações de vídeos individuais

### Estrutura do Projeto

```
src/orc/
├── __init__.py           # API pública (Config, Orchestrator)
├── __version__.py        # Versão do pacote
├── config.py             # Gerenciamento de configuração
├── orchestrator.py       # Lógica principal de orquestração
├── gateway/              # Operações do Google Sheets
│   ├── connection.py     # Conexão com planilha
│   ├── worksheet.py      # Gerenciamento de abas
│   ├── operations.py     # Operações CRUD
│   ├── leader.py         # Eleição de liderança
│   └── _retry.py         # Retry e rate limiting
└── tables/               # Lógica específica de tabelas
    ├── worker_table.py   # Gerenciamento de workers
    ├── task_table.py     # Operações da fila de tasks
    └── source_table.py   # Operações da fila de sources
```

## Licença

MIT License - Veja o arquivo LICENSE para detalhes.
