cueapi-worker 0.1.0__tar.gz

cueapi_worker-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: cueapi-worker
+Version: 0.1.0
+Summary: Local pull-based worker daemon for CueAPI — executes scheduled tasks without a public URL
+Author-email: "Vector Apps Inc." <hello@cueapi.ai>
+License: MIT
+Project-URL: Homepage, https://cueapi.ai
+Project-URL: Documentation, https://docs.cueapi.ai
+Project-URL: Repository, https://github.com/govindkavaturi-art/cueapi-worker
+Keywords: cueapi,worker,daemon,scheduling,ai-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyyaml>=6.0

cueapi_worker-0.1.0/cueapi_worker/__init__.py

@@ -0,0 +1,3 @@
+"""CueAPI Worker — local pull-based daemon for executing scheduled tasks."""
+
+__version__ = "0.1.0"

cueapi_worker-0.1.0/cueapi_worker/cli.py

@@ -0,0 +1,153 @@
+"""CLI entry point for cueapi-worker."""
+from __future__ import annotations
+
+import logging
+import platform
+import sys
+
+import click
+
+from cueapi_worker import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="cueapi-worker")
+def main():
+    """CueAPI Worker — local pull-based daemon for executing scheduled tasks."""
+    pass
+
+
+@main.command()
+@click.option(
+    "--config",
+    "-c",
+    required=True,
+    type=click.Path(exists=True),
+    help="Path to worker config YAML file.",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose (DEBUG) logging.")
+def start(config: str, verbose: bool):
+    """Start the worker daemon.
+
+    Polls CueAPI for claimable executions, matches them to handlers
+    defined in the config file, and executes them locally.
+    """
+    # Configure logging
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    from cueapi_worker.config import load_config
+    from cueapi_worker.daemon import WorkerDaemon
+
+    try:
+        cfg = load_config(config)
+    except (FileNotFoundError, ValueError) as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    click.echo(f"CueAPI Worker v{__version__}")
+    click.echo(f"  Worker ID:    {cfg.worker_id}")
+    click.echo(f"  API Base:     {cfg.api_base}")
+    click.echo(f"  Handlers:     {', '.join(cfg.handler_names())}")
+    click.echo(f"  Poll interval: {cfg.poll_interval}s")
+    click.echo(f"  Max concurrent: {cfg.max_concurrent}")
+    click.echo()
+
+    daemon = WorkerDaemon(cfg)
+    daemon.run()
+
+
+@main.command()
+@click.option(
+    "--config",
+    "-c",
+    required=True,
+    type=click.Path(exists=True),
+    help="Path to worker config YAML file.",
+)
+def status(config: str):
+    """Check worker status by sending a heartbeat.
+
+    Verifies connectivity to the CueAPI server and reports
+    whether the worker can authenticate and communicate.
+    """
+    from cueapi_worker.client import WorkerAPIClient
+    from cueapi_worker.config import load_config
+
+    try:
+        cfg = load_config(config)
+    except (FileNotFoundError, ValueError) as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    client = WorkerAPIClient(api_key=cfg.api_key, api_base=cfg.api_base)
+    ok = client.heartbeat(cfg.worker_id, cfg.handler_names())
+
+    if ok:
+        click.echo(f"Worker '{cfg.worker_id}' is connected and authenticated.")
+        click.echo(f"  Handlers: {', '.join(cfg.handler_names())}")
+    else:
+        click.echo("Failed to connect to CueAPI. Check your API key and network.", err=True)
+        sys.exit(1)
+
+
+@main.command("install-service")
+@click.option(
+    "--config",
+    "-c",
+    required=True,
+    type=click.Path(exists=True),
+    help="Path to worker config YAML file.",
+)
+def install_service(config: str):
+    """Install worker as a system service (launchd on macOS, systemd on Linux)."""
+    from cueapi_worker.service import install_launchd, install_systemd
+
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            path = install_launchd(config)
+            click.echo(f"Installed launchd service: {path}")
+            click.echo("The worker will start automatically on login.")
+        elif system == "Linux":
+            path = install_systemd(config)
+            click.echo(f"Installed systemd service: {path}")
+            click.echo("The worker is now running and will start on boot.")
+        else:
+            click.echo(f"Unsupported platform: {system}. Use 'cueapi-worker start' directly.", err=True)
+            sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error installing service: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command("uninstall-service")
+def uninstall_service():
+    """Uninstall the worker system service."""
+    from cueapi_worker.service import uninstall_launchd, uninstall_systemd
+
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            ok = uninstall_launchd()
+        elif system == "Linux":
+            ok = uninstall_systemd()
+        else:
+            click.echo(f"Unsupported platform: {system}", err=True)
+            sys.exit(1)
+
+        if ok:
+            click.echo("Service uninstalled successfully.")
+        else:
+            click.echo("Service not found. Nothing to uninstall.")
+    except Exception as e:
+        click.echo(f"Error uninstalling service: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cueapi_worker-0.1.0/cueapi_worker/client.py

@@ -0,0 +1,146 @@
+"""HTTP client for CueAPI worker endpoints."""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class WorkerAPIClient:
+    """Thin wrapper around httpx for CueAPI worker API calls."""
+
+    def __init__(self, api_key: str, api_base: str, timeout: float = 30.0):
+        self._api_key = api_key
+        self._api_base = api_base.rstrip("/")
+        self._timeout = timeout
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def get_claimable(self, task: Optional[str] = None) -> List[Dict[str, Any]]:
+        """GET /v1/executions/claimable — list pending worker executions.
+
+        Args:
+            task: Optional task name filter.
+
+        Returns:
+            List of claimable execution dicts.
+        """
+        params = {}
+        if task:
+            params["task"] = task
+
+        try:
+            resp = httpx.get(
+                f"{self._api_base}/v1/executions/claimable",
+                headers=self._headers(),
+                params=params,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+            return resp.json().get("executions", [])
+        except httpx.HTTPStatusError as e:
+            logger.error("Failed to get claimable: %s %s", e.response.status_code, e.response.text)
+            return []
+        except httpx.RequestError as e:
+            logger.error("Request error getting claimable: %s", e)
+            return []
+
+    def claim(self, execution_id: str, worker_id: str) -> Optional[Dict[str, Any]]:
+        """POST /v1/executions/{id}/claim — claim an execution.
+
+        Returns:
+            Claim response dict if successful, None if claim failed (409 or error).
+        """
+        try:
+            resp = httpx.post(
+                f"{self._api_base}/v1/executions/{execution_id}/claim",
+                headers=self._headers(),
+                json={"worker_id": worker_id},
+                timeout=self._timeout,
+            )
+            if resp.status_code == 409:
+                logger.debug("Execution %s already claimed", execution_id)
+                return None
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            logger.error("Failed to claim %s: %s %s", execution_id, e.response.status_code, e.response.text)
+            return None
+        except httpx.RequestError as e:
+            logger.error("Request error claiming %s: %s", execution_id, e)
+            return None
+
+    def report_outcome(
+        self,
+        execution_id: str,
+        success: bool,
+        result: Optional[str] = None,
+        error: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """POST /v1/executions/{id}/outcome — report execution result.
+
+        Returns:
+            True if outcome was recorded, False otherwise.
+        """
+        body: Dict[str, Any] = {"success": success}
+        if result is not None:
+            body["result"] = result
+        if error is not None:
+            body["error"] = error
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        try:
+            resp = httpx.post(
+                f"{self._api_base}/v1/executions/{execution_id}/outcome",
+                headers=self._headers(),
+                json=body,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+            return True
+        except httpx.HTTPStatusError as e:
+            logger.error(
+                "Failed to report outcome for %s: %s %s",
+                execution_id,
+                e.response.status_code,
+                e.response.text,
+            )
+            return False
+        except httpx.RequestError as e:
+            logger.error("Request error reporting outcome for %s: %s", execution_id, e)
+            return False
+
+    def heartbeat(self, worker_id: str, handlers: Optional[List[str]] = None) -> bool:
+        """POST /v1/worker/heartbeat — register/update worker.
+
+        Returns:
+            True if heartbeat acknowledged, False otherwise.
+        """
+        body: Dict[str, Any] = {"worker_id": worker_id}
+        if handlers is not None:
+            body["handlers"] = handlers
+
+        try:
+            resp = httpx.post(
+                f"{self._api_base}/v1/worker/heartbeat",
+                headers=self._headers(),
+                json=body,
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+            return True
+        except httpx.HTTPStatusError as e:
+            logger.error("Heartbeat failed: %s %s", e.response.status_code, e.response.text)
+            return False
+        except httpx.RequestError as e:
+            logger.error("Heartbeat request error: %s", e)
+            return False

cueapi_worker-0.1.0/cueapi_worker/config.py

@@ -0,0 +1,138 @@
+"""Configuration loading for cueapi-worker."""
+from __future__ import annotations
+
+import json
+import os
+import platform
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+
+@dataclass
+class HandlerConfig:
+    """Configuration for a single task handler."""
+
+    cmd: str
+    cwd: Optional[str] = None
+    timeout: int = 300
+    env: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class WorkerConfig:
+    """Top-level worker configuration."""
+
+    api_key: str
+    api_base: str = "https://api.cueapi.ai"
+    worker_id: str = ""
+    poll_interval: int = 5
+    heartbeat_interval: int = 30
+    max_concurrent: int = 4
+    handlers: Dict[str, HandlerConfig] = field(default_factory=dict)
+
+    def handler_names(self) -> List[str]:
+        """Return list of handler task names."""
+        return list(self.handlers.keys())
+
+
+def _resolve_api_key(raw: Optional[str]) -> str:
+    """Resolve API key: config value > CUEAPI_API_KEY env > credentials file."""
+    # 1. Explicit value from config
+    if raw:
+        return raw
+
+    # 2. Environment variable
+    env_key = os.environ.get("CUEAPI_API_KEY")
+    if env_key:
+        return env_key
+
+    # 3. Credentials file (same as CLI)
+    creds_path = Path.home() / ".config" / "cueapi" / "credentials.json"
+    if creds_path.exists():
+        try:
+            data = json.loads(creds_path.read_text())
+            default = data.get("default", {})
+            key = default.get("api_key")
+            if key:
+                return key
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    raise ValueError(
+        "No API key found. Set 'api_key' in config, CUEAPI_API_KEY env var, "
+        "or run 'cueapi login' to save credentials."
+    )
+
+
+def _default_worker_id() -> str:
+    """Generate default worker_id from hostname."""
+    return platform.node() or "worker-unknown"
+
+
+def load_config(path: str) -> WorkerConfig:
+    """Load and validate worker config from a YAML file.
+
+    Args:
+        path: Path to the YAML config file.
+
+    Returns:
+        Validated WorkerConfig instance.
+
+    Raises:
+        FileNotFoundError: If config file doesn't exist.
+        ValueError: If config is invalid.
+    """
+    config_path = Path(path)
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    with open(config_path) as f:
+        raw = yaml.safe_load(f)
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"Invalid config file: expected a YAML mapping, got {type(raw).__name__}")
+
+    # Resolve API key
+    api_key = _resolve_api_key(raw.get("api_key"))
+
+    # Parse handlers
+    handlers: Dict[str, HandlerConfig] = {}
+    raw_handlers = raw.get("handlers", {})
+    if not isinstance(raw_handlers, dict):
+        raise ValueError("'handlers' must be a mapping of task_name -> handler config")
+
+    for task_name, handler_raw in raw_handlers.items():
+        if isinstance(handler_raw, str):
+            # Short form: just a command string
+            handlers[task_name] = HandlerConfig(cmd=handler_raw)
+        elif isinstance(handler_raw, dict):
+            cmd = handler_raw.get("cmd")
+            if not cmd:
+                raise ValueError(f"Handler '{task_name}' must have a 'cmd' field")
+            handlers[task_name] = HandlerConfig(
+                cmd=cmd,
+                cwd=handler_raw.get("cwd"),
+                timeout=handler_raw.get("timeout", 300),
+                env=handler_raw.get("env"),
+            )
+        else:
+            raise ValueError(f"Handler '{task_name}' must be a string or mapping")
+
+    if not handlers:
+        raise ValueError("At least one handler must be defined")
+
+    # Build config
+    worker_id = raw.get("worker_id") or _default_worker_id()
+
+    return WorkerConfig(
+        api_key=api_key,
+        api_base=raw.get("api_base", "https://api.cueapi.ai"),
+        worker_id=worker_id,
+        poll_interval=raw.get("poll_interval", 5),
+        heartbeat_interval=raw.get("heartbeat_interval", 30),
+        max_concurrent=raw.get("max_concurrent", 4),
+        handlers=handlers,
+    )

cueapi_worker-0.1.0/cueapi_worker/daemon.py

@@ -0,0 +1,194 @@
+"""Worker daemon — main poll loop that claims and executes tasks."""
+from __future__ import annotations
+
+import logging
+import signal
+import time
+from concurrent.futures import ThreadPoolExecutor, Future
+from typing import Dict, Set
+
+from cueapi_worker.client import WorkerAPIClient
+from cueapi_worker.config import WorkerConfig
+from cueapi_worker.executor import execute_handler
+from cueapi_worker.heartbeat import HeartbeatThread
+
+logger = logging.getLogger(__name__)
+
+
+class WorkerDaemon:
+    """Main worker daemon.
+
+    Poll loop: get_claimable -> match handler -> claim -> execute in
+    ThreadPoolExecutor -> report outcome. Respects max_concurrent.
+    Handles SIGINT/SIGTERM gracefully.
+    """
+
+    def __init__(self, config: WorkerConfig):
+        self._config = config
+        self._client = WorkerAPIClient(
+            api_key=config.api_key,
+            api_base=config.api_base,
+        )
+        self._heartbeat = HeartbeatThread(
+            client=self._client,
+            worker_id=config.worker_id,
+            handlers=config.handler_names(),
+            interval=config.heartbeat_interval,
+        )
+        self._executor = ThreadPoolExecutor(
+            max_workers=config.max_concurrent,
+            thread_name_prefix="cueapi-handler",
+        )
+        self._running = False
+        self._active_futures: Set[Future] = set()
+
+    def run(self) -> None:
+        """Start the daemon and run until interrupted."""
+        self._running = True
+
+        # Install signal handlers
+        signal.signal(signal.SIGINT, self._handle_signal)
+        signal.signal(signal.SIGTERM, self._handle_signal)
+
+        logger.info(
+            "Worker daemon starting: worker_id=%s, handlers=%s, poll_interval=%ds, max_concurrent=%d",
+            self._config.worker_id,
+            self._config.handler_names(),
+            self._config.poll_interval,
+            self._config.max_concurrent,
+        )
+
+        # Start heartbeat thread
+        self._heartbeat.start()
+
+        try:
+            while self._running:
+                self._poll_cycle()
+                if self._running:
+                    time.sleep(self._config.poll_interval)
+        finally:
+            self._shutdown()
+
+    def _poll_cycle(self) -> None:
+        """Run one poll cycle: fetch claimable, match, claim, execute."""
+        # Clean up completed futures
+        done = {f for f in self._active_futures if f.done()}
+        self._active_futures -= done
+
+        # Check available capacity
+        available = self._config.max_concurrent - len(self._active_futures)
+        if available <= 0:
+            logger.debug("At max concurrent (%d), skipping poll", self._config.max_concurrent)
+            return
+
+        # Fetch claimable executions
+        executions = self._client.get_claimable()
+        if not executions:
+            return
+
+        claimed = 0
+        for exec_data in executions:
+            if claimed >= available:
+                break
+
+            task = exec_data.get("task")
+            execution_id = exec_data.get("execution_id")
+
+            # Match handler
+            handler_config = self._config.handlers.get(task) if task else None
+            if handler_config is None:
+                logger.debug(
+                    "No handler for task=%s, skipping execution=%s",
+                    task,
+                    execution_id,
+                )
+                continue
+
+            # Claim
+            claim_result = self._client.claim(execution_id, self._config.worker_id)
+            if claim_result is None:
+                logger.debug("Failed to claim execution=%s", execution_id)
+                continue
+
+            claimed += 1
+            logger.info(
+                "Claimed execution=%s task=%s cue=%s",
+                execution_id,
+                task,
+                exec_data.get("cue_name"),
+            )
+
+            # Submit to thread pool
+            future = self._executor.submit(
+                self._execute_and_report,
+                handler_config,
+                exec_data,
+            )
+            self._active_futures.add(future)
+
+        if claimed > 0:
+            logger.info("Poll cycle: claimed %d executions", claimed)
+
+    def _execute_and_report(self, handler_config, exec_data: Dict) -> None:
+        """Execute a handler and report the outcome. Runs in thread pool."""
+        execution_id = exec_data.get("execution_id", "")
+        cue_id = exec_data.get("cue_id", "")
+        cue_name = exec_data.get("cue_name", "")
+        payload = exec_data.get("payload", {})
+
+        try:
+            success, output = execute_handler(
+                handler=handler_config,
+                payload=payload,
+                execution_id=execution_id,
+                cue_id=cue_id,
+                cue_name=cue_name,
+                worker_id=self._config.worker_id,
+            )
+
+            # Report outcome
+            if success:
+                self._client.report_outcome(
+                    execution_id=execution_id,
+                    success=True,
+                    result=output or "completed",
+                )
+            else:
+                self._client.report_outcome(
+                    execution_id=execution_id,
+                    success=False,
+                    error=output or "handler failed",
+                )
+
+        except Exception as e:
+            logger.error("Unhandled error executing %s: %s", execution_id, e)
+            self._client.report_outcome(
+                execution_id=execution_id,
+                success=False,
+                error=f"Worker error: {e}",
+            )
+
+    def _handle_signal(self, signum: int, frame) -> None:
+        """Handle SIGINT/SIGTERM gracefully."""
+        sig_name = signal.Signals(signum).name
+        logger.info("Received %s, shutting down gracefully...", sig_name)
+        self._running = False
+
+    def _shutdown(self) -> None:
+        """Clean shutdown: stop heartbeat, wait for active tasks."""
+        logger.info("Shutting down worker daemon...")
+
+        # Stop heartbeat
+        self._heartbeat.stop()
+
+        # Wait for active tasks to complete
+        if self._active_futures:
+            logger.info("Waiting for %d active tasks to complete...", len(self._active_futures))
+            for future in self._active_futures:
+                try:
+                    future.result(timeout=30)
+                except Exception as e:
+                    logger.error("Task error during shutdown: %s", e)
+
+        self._executor.shutdown(wait=False)
+        logger.info("Worker daemon stopped")