taskmanager-engine 0.1.0__py3-none-any.whl

taskmanager/worker/heartbeat.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+
+import psutil
+from pydantic import BaseModel, Field
+
+from taskmanager.config import settings
+from taskmanager.core.broker import RedisBroker
+from taskmanager.core.job import JobStatus
+
+logger = logging.getLogger(__name__)
+
+
+class WorkerInfo(BaseModel):
+    id: str
+    name: str
+    queues: list[str]
+    concurrency: int
+    status: str = "idle"  # idle, busy, paused, stopped, dead
+    started_at: float = Field(default_factory=time.time)
+    last_heartbeat: float = Field(default_factory=time.time)
+    active_jobs_count: int = 0
+    completed_jobs_count: int = 0
+    failed_jobs_count: int = 0
+    cpu_percent: float = 0.0
+    memory_mb: float = 0.0
+
+
+class HeartbeatManager:
+    """Manages worker vitality heartbeats and orphaned job reaping."""
+
+    def __init__(self, broker: RedisBroker, worker_info: WorkerInfo):
+        self.broker = broker
+        self.worker_info = worker_info
+        self._running = False
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        self._running = True
+        try:
+            await self.send_heartbeat()
+        except Exception as err:
+            logger.warning(f"Initial heartbeat error: {err}")
+        self._task = asyncio.create_task(self._heartbeat_loop())
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        # Unregister worker on clean shutdown
+        await self.unregister_worker()
+
+    async def send_heartbeat(self) -> None:
+        """Sends a single heartbeat ping updating Redis state with TTL."""
+        try:
+            process = psutil.Process(os.getpid())
+            mem_info = process.memory_info()
+            self.worker_info.memory_mb = round(mem_info.rss / (1024 * 1024), 2)
+            self.worker_info.cpu_percent = psutil.cpu_percent(interval=None)
+        except Exception:
+            pass
+
+        self.worker_info.last_heartbeat = time.time()
+        key = self.broker._key_worker(self.worker_info.id)
+        data = self.worker_info.model_dump_json()
+
+        # Set worker info with TTL
+        await self.broker.redis.set(key, data, ex=int(settings.worker_heartbeat_ttl))
+        await self.broker.redis.sadd(self.broker._key_workers(), self.worker_info.id)
+        await self.broker.publish_event("worker:heartbeat", self.worker_info.model_dump())
+
+    async def unregister_worker(self) -> None:
+        """Removes worker from registry upon shutdown."""
+        self.worker_info.status = "stopped"
+        key = self.broker._key_worker(self.worker_info.id)
+        await self.broker.redis.delete(key)
+        await self.broker.redis.srem(self.broker._key_workers(), self.worker_info.id)
+        await self.broker.publish_event("worker:stopped", {"worker_id": self.worker_info.id})
+
+    async def _heartbeat_loop(self) -> None:
+        while self._running:
+            try:
+                await self.send_heartbeat()
+                await asyncio.sleep(settings.worker_heartbeat_interval)
+            except asyncio.CancelledError:
+                break
+            except Exception as err:
+                logger.warning(f"Heartbeat failure for worker {self.worker_info.id}: {err}")
+                await asyncio.sleep(settings.worker_heartbeat_interval)
+
+    @classmethod
+    async def get_all_workers(cls, broker: RedisBroker) -> list[WorkerInfo]:
+        """Returns all currently registered workers and cleans up expired ones."""
+        worker_ids = await broker.redis.smembers(broker._key_workers())
+        workers: list[WorkerInfo] = []
+        now = time.time()
+
+        for wid in list(worker_ids):
+            key = broker._key_worker(wid)
+            data = await broker.redis.get(key)
+            if data:
+                try:
+                    info = WorkerInfo.model_validate_json(data)
+                    if (now - info.last_heartbeat) > settings.worker_heartbeat_ttl:
+                        info.status = "dead"
+                    workers.append(info)
+                except Exception:
+                    pass
+            else:
+                # Expired from TTL -> Clean up from workers set
+                await broker.redis.srem(broker._key_workers(), wid)
+        return workers
+
+    @classmethod
+    async def reap_orphans(cls, broker: RedisBroker) -> int:
+        """Finds dead workers and recovers their un-acked active jobs back to pending."""
+        worker_ids = await broker.redis.smembers(broker._key_workers())
+        reaped_count = 0
+
+        for wid in worker_ids:
+            key = broker._key_worker(wid)
+            data = await broker.redis.get(key)
+            if not data:
+                # Worker TTL expired -> Reap active jobs
+                active_key = broker._key_active(wid)
+                orphaned_job_ids = await broker.redis.smembers(active_key)
+                for jid in orphaned_job_ids:
+                    job = await broker.get_job(jid)
+                    if job and job.status == JobStatus.ACTIVE:
+                        logger.warning(f"Reaping orphaned job {jid} from dead worker {wid}")
+                        job.status = JobStatus.PENDING
+                        job.worker_id = None
+                        await broker.save_job(job)
+                        await broker.redis.rpush(broker._key_queue(job.queue), job.id)
+                        await broker.publish_event(
+                            "job:reaped", {"job_id": job.id, "worker_id": wid}
+                        )
+                        reaped_count += 1
+                # Clean active set & remove dead worker from set
+                await broker.redis.delete(active_key)
+                await broker.redis.srem(broker._key_workers(), wid)
+        return reaped_count

taskmanager/worker/worker.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import traceback
+import uuid
+from typing import Any
+
+from taskmanager.core.broker import RedisBroker
+from taskmanager.core.job import Job
+from taskmanager.core.task import TaskRegistry, registry
+from taskmanager.worker.heartbeat import HeartbeatManager, WorkerInfo
+
+logger = logging.getLogger(__name__)
+
+
+class Worker:
+    """Asyncio background worker daemon capable of concurrent job execution."""
+
+    def __init__(
+        self,
+        queues: list[str] | None = None,
+        concurrency: int = 5,
+        name: str | None = None,
+        max_memory_mb: float | None = None,
+        max_cpu_percent: float | None = None,
+        broker: RedisBroker | None = None,
+        task_registry: TaskRegistry | None = None,
+    ):
+        self.id = str(uuid.uuid4())
+        self.name = name or f"worker-{self.id[:8]}"
+        self.queues = queues or ["default"]
+        self.concurrency = concurrency
+        self.max_memory_mb = max_memory_mb
+        self.max_cpu_percent = max_cpu_percent
+        self.registry = task_registry or registry
+        self.broker = broker or self.registry.get_broker()
+        self.semaphore = asyncio.Semaphore(concurrency)
+
+        self.info = WorkerInfo(
+            id=self.id,
+            name=self.name,
+            queues=self.queues,
+            concurrency=self.concurrency,
+            status="idle",
+        )
+        self.heartbeat = HeartbeatManager(self.broker, self.info)
+        self._running = False
+        self._paused = False
+        self._active_tasks: set[asyncio.Task[Any]] = set()
+        self._control_task: asyncio.Task[Any] | None = None
+
+    def pause(self) -> None:
+        """Pauses job consumption."""
+        self._paused = True
+        self.info.status = "paused"
+        logger.info(f"Worker {self.name} paused.")
+
+    def resume(self) -> None:
+        """Resumes job consumption."""
+        self._paused = False
+        self.info.status = "idle" if self.info.active_jobs_count == 0 else "busy"
+        logger.info(f"Worker {self.name} resumed.")
+
+    async def _listen_control(self) -> None:
+        """Listens for remote control signals (pause, resume, stop) via Redis pub/sub."""
+        try:
+            async for cmd in self.broker.subscribe_control():
+                target_id = cmd.get("worker_id")
+                if target_id is None or target_id == self.id or target_id == self.name:
+                    action = cmd.get("action")
+                    if action == "pause":
+                        self.pause()
+                    elif action == "resume":
+                        self.resume()
+                    elif action == "stop":
+                        asyncio.create_task(self.stop())
+        except asyncio.CancelledError:
+            pass
+        except Exception as err:
+            logger.debug(f"Worker control listener closed: {err}")
+
+    async def start(self) -> None:
+        """Starts the worker processing loop, heartbeat manager, and control listener."""
+        self._running = True
+        self.info.status = "idle"
+        for q in self.queues:
+            await self.broker.redis.sadd(self.broker._key_queues(), q)
+        await self.heartbeat.start()
+        self._control_task = asyncio.create_task(self._listen_control())
+        limits_str = ""
+        if self.max_memory_mb or self.max_cpu_percent:
+            limits_str = f" [limits: memory={self.max_memory_mb or 'unlimited'}MB, cpu={self.max_cpu_percent or 'unlimited'}%]"
+        logger.info(
+            f"Worker {self.name} [{self.id}] started listening on {self.queues} (concurrency={self.concurrency}){limits_str}"
+        )
+
+        try:
+            while self._running:
+                if self._paused:
+                    await asyncio.sleep(0.5)
+                    continue
+
+                # 1. Resource Backpressure / Guardrails check
+                if self.max_memory_mb and self.info.memory_mb >= self.max_memory_mb:
+                    logger.warning(
+                        f"⚠️ Worker {self.name} atingiu teto de memória ({self.info.memory_mb:.1f}MB >= {self.max_memory_mb}MB). Backpressure ativo (aguardando liberação de memória)..."
+                    )
+                    self.info.status = "throttled"
+                    await asyncio.sleep(2.0)
+                    continue
+
+                if self.max_cpu_percent and self.info.cpu_percent >= self.max_cpu_percent:
+                    logger.warning(
+                        f"⚠️ Worker {self.name} atingiu teto de CPU ({self.info.cpu_percent:.1f}% >= {self.max_cpu_percent}%). Backpressure ativo..."
+                    )
+                    self.info.status = "throttled"
+                    await asyncio.sleep(1.0)
+                    continue
+
+                if self.info.status == "throttled":
+                    self.info.status = "idle" if self.info.active_jobs_count == 0 else "busy"
+
+                # 2. Wait for available concurrency slot
+                await self.semaphore.acquire()
+
+                # 3. Fetch next job
+                job = await self.broker.fetch_next_job(self.queues, worker_id=self.id)
+                if job:
+                    self.info.active_jobs_count += 1
+                    self.info.status = "busy"
+                    t = asyncio.create_task(self._process_job(job))
+                    self._active_tasks.add(t)
+                    t.add_done_callback(self._active_tasks.discard)
+                else:
+                    # Release slot if no job was found
+                    self.semaphore.release()
+                    await asyncio.sleep(0.2)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self.stop()
+
+    async def _process_job(self, job: Job) -> None:
+        """Executes a single job with timeout handling and error catching."""
+        try:
+            task_def = self.registry.get(job.task_name)
+            if not task_def:
+                raise ValueError(
+                    f"Task '{job.task_name}' is not registered in Worker task registry."
+                )
+
+            # Execute with timeout if specified
+            timeout = job.timeout or task_def.timeout
+            if timeout and timeout > 0:
+                result = await asyncio.wait_for(task_def(*job.args, **job.kwargs), timeout=timeout)
+            else:
+                result = await task_def(*job.args, **job.kwargs)
+
+            await self.broker.mark_completed(job, result=result)
+            self.info.completed_jobs_count += 1
+            logger.info(f"Job {job.id} [{job.task_name}] completed successfully.")
+
+        except TimeoutError:
+            error_msg = f"Job timed out after {job.timeout or task_def.timeout}s"
+            tb_str = traceback.format_exc()
+            logger.error(f"Job {job.id} timed out: {error_msg}")
+            await self.broker.mark_failed(job, error=error_msg, traceback_str=tb_str)
+            self.info.failed_jobs_count += 1
+
+        except Exception as err:
+            error_msg = str(err) or type(err).__name__
+            tb_str = traceback.format_exc()
+            logger.error(f"Job {job.id} failed: {error_msg}")
+            await self.broker.mark_failed(job, error=error_msg, traceback_str=tb_str)
+            self.info.failed_jobs_count += 1
+
+        finally:
+            self.info.active_jobs_count = max(0, self.info.active_jobs_count - 1)
+            if self.info.active_jobs_count == 0 and not self._paused:
+                self.info.status = "idle"
+            self.semaphore.release()
+
+    async def stop(self, drain: bool = True, timeout: float = 10.0) -> None:
+        """Stops the worker, optionally draining in-flight jobs."""
+        if not self._running and self.info.status == "stopped":
+            return
+
+        self._running = False
+        self.info.status = "stopped"
+        logger.info(f"Worker {self.name} stopping (drain={drain})...")
+
+        if self._control_task and not self._control_task.done():
+            self._control_task.cancel()
+
+        if drain and self._active_tasks:
+            try:
+                await asyncio.wait_for(
+                    asyncio.gather(*list(self._active_tasks), return_exceptions=True),
+                    timeout=timeout,
+                )
+            except TimeoutError:
+                logger.warning(f"Worker {self.name} drain timed out. Forcing shutdown.")
+
+        await self.heartbeat.stop()
+        logger.info(f"Worker {self.name} stopped.")
+

taskmanager_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: taskmanager-engine
+Version: 0.1.0
+Summary: High-performance background task execution engine with dynamic cron scheduling and Linear-themed SPA dashboard
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.28.0
+Requires-Dist: redis[hiredis]>=5.0.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: croniter>=2.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: fakeredis>=2.21.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: fakeredis>=2.21.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: websockets>=12.0; extra == "dev"
+
+# TaskManager ⚡
+
+<div align="center">
+
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688?style=for-the-badge&logo=fastapi&logoColor=white)
+![Django](https://img.shields.io/badge/Django-4.2%2B%20%7C%205.0%2B-092E20?style=for-the-badge&logo=django&logoColor=white)
+![Redis](https://img.shields.io/badge/Redis-7%2B_AOF_Durable-DC382D?style=for-the-badge&logo=redis&logoColor=white)
+![UI](https://img.shields.io/badge/UI-Linear_Dark_System-5E6AD2?style=for-the-badge&logo=linear&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)
+
+**Engine moderna de execução e gerenciamento de background tasks em Python inspirada no Celery e BullMQ.**  
+*Agendador Cron Dinâmico • Observabilidade LGTM Completa • Dead Letter Queue Multi-Fila • Telemetria com Backpressure • Dashboard SPA Linear Dark.*
+
+<br/>
+
+<img src="docs/images/01_dashboard_overview.png" alt="TaskManager Dashboard Overview" width="100%" style="border-radius: 12px; border: 1px solid #23252a; box-shadow: 0 20px 40px rgba(0,0,0,0.6);" />
+
+</div>
+
+---
+
+## 🌟 Principais Destaques
+
+- **🚀 Asyncio & Sync Worker Runtime**: Suporte nativo e transparente para corrotinas assíncronas (`async def`) e funções síncronas (`def`), com concorrência ajustável e timeouts granulares.
+- **📦 Redis Broker com Durabilidade AOF**: Sem brokers pesados. Utiliza listas atômicas do Redis (`LPOP`/`BLPOP`), conjuntos ordenados para jobs agendados e histórico, e persistência AOF para garantia de *Zero Data Loss*.
+- **🧠 Fallback In-Memory Automático**: Modo de desenvolvimento zero-dependência (`fakeredis`) quando o Redis local não estiver em execução.
+- **✨ Decorator `@task` & Introspecção**: Enfileiramento via `.delay(*args, **kwargs)` ou `.apply_async(...)` com geração automática de schemas e payload no painel.
+- **⏰ Agendador Cron & Intervalos em Tempo Real**: Sintaxe padrão de 5 posições (`*/5 * * * *`) ou intervalo em segundos com distributed leader locking e execução garantida.
+- **🛡️ Resiliência, DLQ & Backpressure**: Retentativas com exponential backoff, Dead Letter Queue (DLQ) com inspeção de stacktrace e *One-Click Replay*. Circuit breaker de CPU e Memória RSS por worker.
+- **📊 Observabilidade LGTM Nativa**:
+  - **📈 Mimir / Prometheus**: KPIs em tempo real (Taxa de Sucesso %, Duração Média ms, Latência P95 ms, Throughput/min).
+  - **📜 Loki**: Console de logs de execução, erros e tracebacks capturados.
+  - **⏱️ Tempo**: Linha do tempo em cascata (Enqueued ➔ Dequeued ➔ Executing ➔ Finished/Failed).
+- **🎨 Design System Linear Dark**: Interface minimalista com atalho global **`Ctrl+K` (Command Palette)**, menu de ação unificado **`+ Criar ▾`**, e realce suave de linhas.
+- **🔌 Plug-and-Play em Qualquer Framework**: Use como aplicação independente ou embarque facilmente dentro do seu projeto **FastAPI**, **Django** ou **Flask**.
+
+---
+
+## 📦 Como Usar o TaskManager no seu Projeto (Biblioteca / Framework)
+
+Você pode adicionar o TaskManager ao seu projeto Python existente de 3 maneiras:
+
+```bash
+# Instalar no seu projeto:
+pip install taskmanager
+# ou usando UV:
+uv add taskmanager
+```
+
+---
+
+### Método 1: Embutir no FastAPI / Starlette (Sub-Aplicação / Mount)
+
+Monte o dashboard e os endpoints do TaskManager diretamente dentro da sua aplicação FastAPI existente:
+
+```python
+# main.py
+from fastapi import FastAPI
+from taskmanager import TaskManager, task
+
+# 1. Cria sua aplicação principal
+app = FastAPI(title="Minha API Principal")
+
+# 2. Configura a instância do TaskManager apontando para o Redis
+tm = TaskManager(redis_url="redis://localhost:6379/0", prefix="meu_app")
+
+# 3. Define tarefas usando o decorator @task
+@task(name="emails.enviar_boas_vindas", queue="emails", max_retries=3)
+async def enviar_boas_vindas(email: str, nome: str):
+    print(f"Enviando e-mail para {nome} <{email}>...")
+    return {"status": "enviado"}
+
+# 4. Monta o dashboard do TaskManager sob a rota /tasks
+tm.mount_to(app, path="/tasks")
+
+@app.post("/cadastro")
+async def cadastrar_usuario(email: str, nome: str):
+    # Enfileira o job em background
+    job = await enviar_boas_vindas.delay(email=email, nome=nome)
+    return {"mensagem": "Usuário cadastrado!", "job_id": job.id}
+```
+
+*Ao acessar `http://localhost:8000/tasks/`, o dashboard completo estará rodando dentro da sua própria aplicação!*
+
+---
+
+### Método 2: Integração com Django (`taskmanager.contrib.django`)
+
+O TaskManager possui integração de primeira classe com o ecossistema Django:
+
+1. Adicione `'taskmanager.contrib.django'` ao seu `INSTALLED_APPS` em `settings.py`:
+```python
+# settings.py
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    ...,
+    "taskmanager.contrib.django",  # <- Adicione aqui
+    "meu_app_vendas",
+]
+
+# Configurações opcionais do Redis
+TASKMANAGER_REDIS_URL = "redis://localhost:6379/0"
+TASKMANAGER_REDIS_PREFIX = "django_app"
+```
+
+2. Crie um arquivo `tasks.py` dentro dos seus apps Django:
+```python
+# meu_app_vendas/tasks.py
+from taskmanager import task
+
+@task(name="vendas.gerar_fatura", queue="faturamento", max_retries=2)
+async def gerar_fatura(pedido_id: int):
+    # O taskmanager.contrib.django descobre e carrega automaticamente
+    # todos os módulos tasks.py de todos os apps em INSTALLED_APPS!
+    ...
+```
+
+3. Adicione as URLs no seu `urls.py`:
+```python
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    path("admin/", admin.site.urls),
+    path("tasks/", include("taskmanager.contrib.django.urls")),  # <- Dashboard
+]
+```
+
+4. Execute workers e schedulers nativamente com `manage.py`:
+```bash
+# Iniciar worker consumindo as filas do Django:
+python manage.py run_worker --queues faturamento,default --concurrency 5
+
+# Iniciar o scheduler de rotinas cron:
+python manage.py run_scheduler
+```
+
+---
+
+### Método 3: Modo Standalone / CLI (Sidecar Desacoplado)
+
+Se preferir manter o TaskManager como um serviço separado (sidecar):
+
+```bash
+# Modo Dev (Dashboard + Worker + Scheduler apontando para seus módulos de tarefas):
+taskmanager dev --modules meu_projeto.tasks --port 8000
+
+# Processos isolados para Produção:
+taskmanager worker --modules meu_projeto.tasks --queues emails,default -c 8
+taskmanager scheduler --modules meu_projeto.tasks
+taskmanager server --port 8080
+```
+
+---
+
+## 📂 Pasta de Exemplos Práticos (`samples/`)
+
+O repositório inclui projetos de exemplo completos e prontos para rodar:
+
+| Exemplo | Descrição | Como Executar |
+| :--- | :--- | :--- |
+| [📁 samples/fastapi_sample](samples/fastapi_sample) | API FastAPI completa montando o TaskManager em `/tasks/` com endpoints de checkout e e-mail. | `uv run python -m samples.fastapi_sample.main` |
+| [📁 samples/django_sample](samples/django_sample) | Projeto Django configurado com `taskmanager.contrib.django`, `tasks.py` e comandos `manage.py`. | `python samples/django_sample/manage.py run_worker` |
+| [📁 samples/standalone_cli](samples/standalone_cli) | Demonstração de uso puro via linha de comando desacoplada. | `uv run taskmanager dev --modules samples.standalone_cli.tasks` |
+
+---
+
+## 🛠️ Como Compilar e Publicar a Biblioteca (PyPI)
+
+Para gerar os pacotes `.whl` (Wheel) e `.tar.gz` (Source Distribution) com todos os arquivos de UI embutidos:
+
+```bash
+# 1. Compilar os artefatos de distribuição
+uv build
+# (ou via python -m build)
+
+# 2. Testar instalação local em modo editável
+pip install -e .
+
+# 3. Publicar no PyPI
+uv publish --token <SEU_TOKEN_PYPI>
+# (ou twine upload dist/*)
+```
+
+---
+
+## 📸 Galeria de Telas do Dashboard
+
+### 1. Visão Geral & Métricas em Tempo Real
+Acompanhe o estado de todas as filas, consumo de hardware dos workers e log de eventos ao vivo via WebSockets.
+<img src="docs/images/01_dashboard_overview.png" alt="Visão Geral" width="100%" style="border-radius: 8px; border: 1px solid #23252a; margin-bottom: 24px;" />
+
+---
+
+### 2. Menu Unificado `+ Criar ▾` & Paleta de Comandos (`Ctrl+K`)
+Navegue e execute qualquer ação em milissegundos sem tirar as mãos do teclado.
+<div align="center">
+  <img src="docs/images/08_quick_create_menu.png" alt="Menu Criar" width="48%" style="border-radius: 8px; border: 1px solid #23252a; margin-right: 2%;" />
+  <img src="docs/images/07_command_palette.png" alt="Command Palette Ctrl+K" width="48%" style="border-radius: 8px; border: 1px solid #23252a;" />
+</div>
+
+---
+
+### 3. Gerenciamento de Workers & Proteção de Recursos
+Monitore o uso de CPU/RAM de cada worker individual e pause ou interrompa processos com um clique.
+<img src="docs/images/02_workers_management.png" alt="Gerenciamento de Workers" width="100%" style="border-radius: 8px; border: 1px solid #23252a; margin-bottom: 24px;" />
+
+---
+
+### 4. Agendamentos Cron & Rotinas Periódicas
+Crie e edite agendamentos em tempo real sem precisar reiniciar os serviços ou fazer deploy.
+<img src="docs/images/04_cron_schedules.png" alt="Agendamentos Cron" width="100%" style="border-radius: 8px; border: 1px solid #23252a; margin-bottom: 24px;" />
+
+---
+
+### 5. Dead Letter Queue (DLQ) & Inspeção de Falhas
+Monitore jobs que esgotaram retentativas, visualize o stacktrace completo e faça o replay imediato para a fila.
+<img src="docs/images/05_dlq_inspector.png" alt="Dead Letter Queue" width="100%" style="border-radius: 8px; border: 1px solid #23252a; margin-bottom: 24px;" />
+
+---
+
+### 6. Observabilidade & Trace Waterfall (LGTM Stack)
+Inspecione a linha do tempo exata de execução de cada tarefa com logs capturados e payloads serializados.
+<img src="docs/images/06_observability_trace.png" alt="Observabilidade e Tracing" width="100%" style="border-radius: 8px; border: 1px solid #23252a; margin-bottom: 24px;" />
+
+---
+
+## 🐳 Stack Docker & Docker Compose
+
+Suba o cluster completo em contêineres com um único comando:
+
+```bash
+# Iniciar todos os serviços com Redis AOF persistente
+docker compose up --build -d
+
+# Visualizar status e healthchecks
+docker compose ps
+
+# Escalar workers dinamicamente
+docker compose up -d --scale worker-emails=3
+```
+
+---
+
+## 🧪 Testes & Qualidade
+
+```bash
+# Executar suíte completa de testes
+uv run pytest -v tests/
+
+# Executar linter de código
+uv run ruff check taskmanager tests samples
+
+# Sensor de Spec Drift (SDD)
+node .agents/scripts/check-spec-drift.js
+```
+
+---
+
+## 📄 Licença
+Distribuído sob a licença [MIT](LICENSE). Pronto para uso individual ou corporativo.

taskmanager_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+taskmanager/__init__.py,sha256=LsgOv2VOcBsLHnWzlEE9prFNqAtJLdCMggKyDDaktBg,4606
+taskmanager/cli.py,sha256=lHUrhCxGUdg2uuXke0qXcdtApNDrpO2d8NBY9qPVq1U,11216
+taskmanager/config.py,sha256=wvoRn2hq1JjvX0xlKRTX01H6lW182pcV6IolnsT8a5o,559
+taskmanager/api/app.py,sha256=zrb-8XW8SfnCOz1IjdFMHk6YqsNe2sWFxE0L_XdNhu0,18886
+taskmanager/api/events.py,sha256=FeUvUHqNTGCKjZJ04u7SLkfgnYzaAWmb3F94dYWckUQ,2253
+taskmanager/contrib/__init__.py,sha256=9o6M3my91wl6rPXmerFS7sF7ENDjNHJoPJWsI7XqNIM,93
+taskmanager/contrib/fastapi.py,sha256=SO2xtaWVRGV3KHcbLMfgMxp_CobQt5o6EdZPFSZq7ok,820
+taskmanager/contrib/django/__init__.py,sha256=0BTjX3gIyArCz5QaZddPqIiCrAG38z92yQzbLQbHY5g,205
+taskmanager/contrib/django/apps.py,sha256=6tQptFHxvR7L5u4FhSzIp-3U-FMYnN9DpGTfs0Bankk,1303
+taskmanager/contrib/django/urls.py,sha256=BnxYCjsM7SnsJJRr2Dp3pa7z0s30ANrpAwkJEfPSF_E,778
+taskmanager/contrib/django/management/__init__.py,sha256=XtGiUSnEbzJRa3QYOpERYL-doT2gPWt1BsJzLcjSdRo,48
+taskmanager/contrib/django/management/commands/__init__.py,sha256=2lIYz8CyM8idv5jZovEFzEpngh9iuOqCuOeFsk8qLp0,62
+taskmanager/contrib/django/management/commands/run_scheduler.py,sha256=Mox1KrycIwZTadBHVx7IbbgzgNc_NG_n1UJ-TNTqbek,1333
+taskmanager/contrib/django/management/commands/run_worker.py,sha256=O44lu6e5QdAQrWt2IYzFj-fo_RbCJAlajVJp3BzvrNI,2294
+taskmanager/core/broker.py,sha256=mS316ZX-6OlnOI6myNJ2-fVkJQ-BpFO1SqoEbONrmdQ,21069
+taskmanager/core/builtin_tasks.py,sha256=pizSiIDUJHhAHmXYDLzhp2ahQ9YmubnOx9rYI-KOnVM,2067
+taskmanager/core/job.py,sha256=CN7QMLOXFfI4YtwFGfWuZ9CXoa5wdXkcTmlyp42CioE,1536
+taskmanager/core/task.py,sha256=s9D_0R2rIsP0qYCZdToxMLUiTtdCYvfXn8feTuhUK1I,8093
+taskmanager/scheduler/cron.py,sha256=-JXljWCCupZtEXldOA_xfNAA2IpsNl0NspHdJMEMIkk,1909
+taskmanager/scheduler/scheduler.py,sha256=dMfQXJp6lYw8IXCcslTcKQLZitTjshdt1vpXGDrz9Ew,6748
+taskmanager/ui/app.js,sha256=8cpEkexz7skpByu2GoGuud0EWvI9CC-x0Hi-CiHBgjE,53217
+taskmanager/ui/index.html,sha256=Vm7ZNswh72CFe5XIzB1aPZUVMUO1eZ5qUeLOtBZjLpQ,34016
+taskmanager/ui/styles.css,sha256=bRVkbe9IhtIYcfEFckYrvp_BAR4V2gRBYaBEjZmO6Q0,19665
+taskmanager/worker/heartbeat.py,sha256=h3KIQUhIjGZZrbydmP8YG-QPjIvaUgPyf4DGaKWPU7c,6086
+taskmanager/worker/worker.py,sha256=2tggPDdtyjmRnTSa2oH1leXV-Yekp6ZLcx3rm2RGY0Y,8458
+taskmanager_engine-0.1.0.dist-info/METADATA,sha256=g9wm6hT6hwhoq8Jqr7ltqR7SGJel5yZcdb-6tVN4Da4,11605
+taskmanager_engine-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+taskmanager_engine-0.1.0.dist-info/entry_points.txt,sha256=Y0FYW_fak5JsupHPyp7E1WO0x5s_Mb40uM6G7UvIMqg,53
+taskmanager_engine-0.1.0.dist-info/top_level.txt,sha256=DpRB7L9fWggaPMvAQLe6BpA4-ULwMkx0QUwasv9rN14,12
+taskmanager_engine-0.1.0.dist-info/RECORD,,

taskmanager_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taskmanager_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+taskmanager = taskmanager.cli:main

taskmanager_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+taskmanager