djobs 0.1.0__py3-none-any.whl

djobs/__init__.py

@@ -0,0 +1,49 @@
+"""Distributed Job System — a durable job queue with retry, lease, and observability.
+
+Public API
+----------
+>>> from djobs import Job, QueueService, HandlerRegistry, WorkerPool, Daemon
+>>> repo = SQLiteJobRepository.from_path("jobs.db")
+>>> queue = QueueService(repo)
+>>> job = queue.submit("my_task", {"key": "value"})
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from djobs.core.errors import (
+    DJobsError,
+    DuplicateHandlerError,
+    HandlerNotFoundError,
+    InvalidStateTransitionError,
+    JobNotFoundError,
+    NonRetryableJobError,
+    RetryableJobError,
+)
+from djobs.core.models import Job
+from djobs.core.states import JobStatus
+from djobs.daemon import Daemon
+from djobs.queue.service import QueueService
+from djobs.storage.sqlite import SQLiteJobRepository
+from djobs.worker.pool import WorkerPool
+from djobs.worker.registry import HandlerRegistry
+from djobs.worker.runner import WorkerRunner
+
+__all__ = [
+    "DJobsError",
+    "Daemon",
+    "DuplicateHandlerError",
+    "HandlerNotFoundError",
+    "HandlerRegistry",
+    "InvalidStateTransitionError",
+    "Job",
+    "JobNotFoundError",
+    "JobStatus",
+    "NonRetryableJobError",
+    "QueueService",
+    "RetryableJobError",
+    "SQLiteJobRepository",
+    "WorkerPool",
+    "WorkerRunner",
+]

djobs/api/__init__.py

@@ -0,0 +1 @@
+"""External API and CLI entry points."""

djobs/api/ai_handlers.py

@@ -0,0 +1,100 @@
+"""Simulated AI job handlers for Phase 8 demo.
+
+These handlers simulate real AI workloads:
+- ai.summarize: text summarization (simulated token usage + latency)
+- ai.classify: text classification (fast, cheap)
+- ai.generate: long-running generation (expensive, may fail with rate limit)
+
+Each handler writes cost/token metadata into the job payload for tracking.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any
+
+from djobs.core.errors import RetryableJobError
+
+
+def ai_summarize_handler(payload: dict[str, Any]) -> Any:
+    """Simulate an AI summarization call.
+
+    Payload keys:
+        text: str — input text to summarize.
+
+    Side effects:
+        Adds ``result``, ``tokens_used``, ``cost_usd`` to payload.
+    """
+    text = payload.get("text", "")
+    tokens = max(len(text.split()), 10)
+
+    # Simulate 5% transient failure (rate limit)
+    if random.random() < 0.05:
+        raise RetryableJobError("AI API rate limit exceeded (429)")
+
+    time.sleep(0.05)  # simulate latency
+
+    payload["result"] = f"Summary of {tokens} tokens: {text[:60]}..."
+    payload["tokens_used"] = tokens
+    payload["cost_usd"] = round(tokens * 0.00003, 6)
+    return payload
+
+
+def ai_classify_handler(payload: dict[str, Any]) -> Any:
+    """Simulate an AI classification call.
+
+    Payload keys:
+        text: str — input text to classify.
+        labels: list[str] — candidate labels.
+    """
+    text = payload.get("text", "")
+    labels = payload.get("labels", ["positive", "negative", "neutral"])
+    tokens = max(len(text.split()), 5)
+
+    time.sleep(0.02)
+
+    chosen = random.choice(labels)
+    payload["result"] = chosen
+    payload["confidence"] = round(random.uniform(0.7, 0.99), 3)
+    payload["tokens_used"] = tokens
+    payload["cost_usd"] = round(tokens * 0.00001, 6)
+    return payload
+
+
+def ai_generate_handler(payload: dict[str, Any]) -> Any:
+    """Simulate a long-running AI generation call.
+
+    Payload keys:
+        prompt: str — generation prompt.
+        max_tokens: int — maximum output tokens (default 500).
+
+    This handler has a higher failure rate to demonstrate retry + cost control.
+    """
+    prompt = payload.get("prompt", "")
+    max_tokens = payload.get("max_tokens", 500)
+
+    # Simulate 15% transient failure
+    if random.random() < 0.15:
+        raise RetryableJobError("AI API timeout — generation too slow")
+
+    time.sleep(0.1)  # longer latency
+
+    output_tokens = random.randint(max_tokens // 2, max_tokens)
+    input_tokens = max(len(prompt.split()), 10)
+    total_tokens = input_tokens + output_tokens
+
+    payload["result"] = f"Generated {output_tokens} tokens for: {prompt[:40]}..."
+    payload["input_tokens"] = input_tokens
+    payload["output_tokens"] = output_tokens
+    payload["tokens_used"] = total_tokens
+    payload["cost_usd"] = round(total_tokens * 0.00006, 6)
+    return payload
+
+
+# Registry helper
+AI_HANDLERS: dict[str, Any] = {
+    "ai.summarize": ai_summarize_handler,
+    "ai.classify": ai_classify_handler,
+    "ai.generate": ai_generate_handler,
+}

djobs/cli.py

@@ -0,0 +1,160 @@
+"""CLI entry point for the distributed job system.
+
+Commands::
+
+    djobs serve              Start the background daemon
+    djobs serve --db my.db   Use a custom database path
+    djobs serve --workers 8  Set max concurrent workers
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import logging
+import sys
+from collections.abc import Callable
+from typing import Any
+
+Handler = Callable[[dict[str, Any]], Any]
+
+
+# ---------------------------------------------------------------------------
+# Built-in handlers
+# ---------------------------------------------------------------------------
+
+
+def _echo_handler(payload: dict[str, Any]) -> dict[str, Any]:
+    """Built-in handler that logs and returns the payload (for testing)."""
+    logging.getLogger("djobs.handlers.echo").info("echo: %s", payload)
+    return {"echoed": payload}
+
+
+BUILTIN_HANDLERS: dict[str, Handler] = {
+    "echo": _echo_handler,
+}
+
+
+# ---------------------------------------------------------------------------
+# Handler loading
+# ---------------------------------------------------------------------------
+
+
+def _load_handlers_module(dotted_path: str) -> dict[str, Handler]:
+    """Import a module and collect its HANDLERS dict.
+
+    The module must define ``HANDLERS: dict[str, Callable]``.
+    """
+    module = importlib.import_module(dotted_path)
+    handlers = getattr(module, "HANDLERS", None)
+    if handlers is None:
+        raise ImportError(f"Module {dotted_path!r} does not export a HANDLERS dict")
+    if not isinstance(handlers, dict):
+        raise TypeError(
+            f"HANDLERS in {dotted_path!r} must be a dict, got {type(handlers).__name__}"
+        )
+    return handlers
+
+
+# ---------------------------------------------------------------------------
+# serve command
+# ---------------------------------------------------------------------------
+
+
+def _cmd_serve(args: argparse.Namespace) -> None:
+    """Run the background daemon."""
+    from djobs.daemon import Daemon
+
+    # Collect handlers: builtins + user-provided modules.
+    handlers: dict[str, Handler] = dict(BUILTIN_HANDLERS)
+    for module_path in args.handlers or []:
+        loaded = _load_handlers_module(module_path)
+        handlers.update(loaded)
+
+    daemon = Daemon.from_db(
+        db_path=args.db,
+        handlers=handlers,
+        max_concurrent=args.workers,
+        poll_interval=args.poll_interval,
+        scheduler_interval=args.scheduler_interval,
+    )
+
+    registered = ", ".join(sorted(handlers)) or "(none)"
+    print(
+        f"djobs daemon starting\n"
+        f"  db:         {args.db}\n"
+        f"  workers:    {args.workers}\n"
+        f"  handlers:   {registered}\n"
+        f"  worker_id:  {daemon.worker_id}\n"
+    )
+
+    daemon.run()
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="djobs",
+        description="Distributed job system CLI",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # --- serve ---
+    serve_parser = subparsers.add_parser(
+        "serve",
+        help="Start the background daemon",
+    )
+    serve_parser.add_argument(
+        "--db",
+        default="djobs_mcp.db",
+        help="SQLite database path (default: djobs_mcp.db — same as MCP server)",
+    )
+    serve_parser.add_argument(
+        "--workers",
+        type=int,
+        default=4,
+        help="Max concurrent workers (default: 4)",
+    )
+    serve_parser.add_argument(
+        "--poll-interval",
+        type=float,
+        default=1.0,
+        help="Seconds between job claim attempts (default: 1.0)",
+    )
+    serve_parser.add_argument(
+        "--scheduler-interval",
+        type=float,
+        default=5.0,
+        help="Seconds between scheduler ticks (default: 5.0)",
+    )
+    serve_parser.add_argument(
+        "--handlers",
+        nargs="*",
+        metavar="MODULE",
+        help=(
+            "Python modules exporting a HANDLERS dict. "
+            "E.g. --handlers myapp.handlers myapp.extra_handlers"
+        ),
+    )
+    serve_parser.set_defaults(func=_cmd_serve)
+
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        sys.exit(1)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

djobs/core/__init__.py

@@ -0,0 +1 @@
+"""Core domain models, state machine, and domain errors."""

djobs/core/config.py

@@ -0,0 +1,25 @@
+"""Minimal configuration loader using dataclass + environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Config:
+    """Application configuration.
+
+    Reads from environment variables with sensible defaults.
+    Prefix: DJOBS_
+    """
+
+    db_path: str = field(default_factory=lambda: os.getenv("DJOBS_DB_PATH", "djobs.db"))
+    log_level: str = field(default_factory=lambda: os.getenv("DJOBS_LOG_LEVEL", "INFO"))
+    log_format: str = field(default_factory=lambda: os.getenv("DJOBS_LOG_FORMAT", "json"))
+    worker_id: str = field(default_factory=lambda: os.getenv("DJOBS_WORKER_ID", "worker-1"))
+
+    @classmethod
+    def from_env(cls) -> Config:
+        """Build config from current environment variables."""
+        return cls()

djobs/core/errors.py

@@ -0,0 +1,35 @@
+"""Domain exceptions."""
+
+from __future__ import annotations
+
+
+class DJobsError(Exception):
+    """Base exception for all djobs errors."""
+
+
+class InvalidStateTransitionError(DJobsError):
+    """Raised when a job state transition is not allowed."""
+
+
+# Alias for backward compatibility
+InvalidStateTransition = InvalidStateTransitionError
+
+
+class JobNotFoundError(DJobsError):
+    """Raised when a job id cannot be found."""
+
+
+class HandlerNotFoundError(DJobsError):
+    """Raised when a worker cannot find a handler for a job type."""
+
+
+class DuplicateHandlerError(DJobsError):
+    """Raised when a handler is registered more than once."""
+
+
+class RetryableJobError(DJobsError):
+    """Raised by a handler when a failure should be retried."""
+
+
+class NonRetryableJobError(DJobsError):
+    """Raised by a handler when a failure should become terminal failed."""

djobs/core/models.py

@@ -0,0 +1,45 @@
+"""Job domain model."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from djobs.core.states import JobStatus
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+@dataclass
+class Job:
+    """A durable unit of work.
+
+    Fields cover Phase 1 (basic lifecycle), Phase 2 (retry, idempotency),
+    Phase 3 (lease, heartbeat, crash recovery), and Phase 6 (correlation id,
+    execution duration).
+    """
+
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=_new_id)
+    status: JobStatus = JobStatus.PENDING
+    attempt: int = 0
+    max_attempts: int = 1
+    run_after: datetime | None = None
+    idempotency_key: str | None = None
+    correlation_id: str = field(default_factory=_new_id)
+    last_error: str | None = None
+    leased_by: str | None = None
+    lease_expires_at: datetime | None = None
+    heartbeat_at: datetime | None = None
+    started_at: datetime | None = None
+    created_at: datetime = field(default_factory=_utcnow)
+    updated_at: datetime = field(default_factory=_utcnow)

djobs/core/retry.py

@@ -0,0 +1,39 @@
+"""Retry policy and backoff calculation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Exponential backoff policy for retryable job failures."""
+
+    base_delay_seconds: float = 1.0
+    multiplier: float = 2.0
+    max_delay_seconds: float = 60.0
+
+    def __post_init__(self) -> None:
+        if self.base_delay_seconds <= 0:
+            raise ValueError("base_delay_seconds must be greater than 0")
+        if self.multiplier < 1:
+            raise ValueError("multiplier must be greater than or equal to 1")
+        if self.max_delay_seconds < self.base_delay_seconds:
+            raise ValueError(
+                "max_delay_seconds must be greater than or equal to base_delay_seconds"
+            )
+
+    def calculate_delay(self, attempt: int) -> timedelta:
+        """Return retry delay for the attempt that just failed."""
+        if attempt <= 0:
+            raise ValueError("attempt must be greater than 0")
+        delay_seconds = self.base_delay_seconds * (self.multiplier ** (attempt - 1))
+        return timedelta(seconds=min(delay_seconds, self.max_delay_seconds))
+
+    def next_run_after(self, attempt: int, now: datetime | None = None) -> datetime:
+        """Return the UTC time when the next retry should become eligible."""
+        current_time = now or datetime.now(UTC)
+        if current_time.tzinfo is None:
+            current_time = current_time.replace(tzinfo=UTC)
+        return current_time.astimezone(UTC) + self.calculate_delay(attempt)

djobs/core/states.py

@@ -0,0 +1,52 @@
+"""Job status enum and state transition validation."""
+
+from __future__ import annotations
+
+import enum
+
+
+class JobStatus(enum.StrEnum):
+    """All possible job states.
+
+    Phase 1 transitions:
+        pending -> running -> succeeded
+        pending -> running -> failed
+
+    Phase 2 transitions:
+        running -> retry_scheduled -> pending
+        running -> dead_lettered
+
+    Phase 3 transitions (lease recovery):
+        running -> pending  (only via recover_expired_leases)
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    RETRY_SCHEDULED = "retry_scheduled"
+    DEAD_LETTERED = "dead_lettered"
+
+
+# Valid (from_status -> to_status) pairs.
+_VALID_TRANSITIONS: set[tuple[JobStatus, JobStatus]] = {
+    (JobStatus.PENDING, JobStatus.RUNNING),
+    (JobStatus.PENDING, JobStatus.SUCCEEDED),  # AI agent completes without claim
+    (JobStatus.PENDING, JobStatus.FAILED),  # AI agent fails without claim
+    (JobStatus.RUNNING, JobStatus.SUCCEEDED),
+    (JobStatus.RUNNING, JobStatus.FAILED),
+    (JobStatus.RUNNING, JobStatus.RETRY_SCHEDULED),
+    (JobStatus.RUNNING, JobStatus.DEAD_LETTERED),
+    (JobStatus.RUNNING, JobStatus.PENDING),  # lease recovery
+    (JobStatus.RETRY_SCHEDULED, JobStatus.PENDING),
+}
+
+
+def validate_transition(from_status: JobStatus, to_status: JobStatus) -> None:
+    """Raise InvalidStateTransition if the transition is not allowed."""
+    from djobs.core.errors import InvalidStateTransitionError
+
+    if (from_status, to_status) not in _VALID_TRANSITIONS:
+        raise InvalidStateTransitionError(
+            f"Cannot transition from {from_status.value!r} to {to_status.value!r}"
+        )