ls-algorithm-plugin-sdk 0.2.5__py3-none-any.whl

algorithm_plugin_sdk/__init__.py

@@ -0,0 +1,52 @@
+from .algorithm import Algorithm
+from .context import (
+    DatasetProgress,
+    EpisodeProgress,
+    ExecutionContext,
+    ProgressSnapshot
+)
+from .deployment import DeploymentConfig
+from .errors import (
+    AlgorithmLoadError,
+    AlgorithmPluginError,
+    ExecutionCancelled,
+    InvalidAlgorithmResult,
+    InvalidRequest
+)
+from .loader import load_algorithm
+from .models import (
+    AlgorithmInput,
+    AlgorithmMetadata,
+    AlgorithmRequest,
+    AlgorithmResult,
+    DatasetResult
+)
+from .registration import PluginRegistrationAgent, RegistrationSettings
+from .release import ReleaseManifest
+from .runner import AlgorithmRunner
+from .service import ExecutionManager
+
+__all__ = [
+    "Algorithm",
+    "AlgorithmInput",
+    "AlgorithmLoadError",
+    "AlgorithmMetadata",
+    "AlgorithmPluginError",
+    "AlgorithmRequest",
+    "AlgorithmResult",
+    "AlgorithmRunner",
+    "DeploymentConfig",
+    "DatasetProgress",
+    "DatasetResult",
+    "EpisodeProgress",
+    "ExecutionCancelled",
+    "ExecutionContext",
+    "ExecutionManager",
+    "InvalidAlgorithmResult",
+    "InvalidRequest",
+    "PluginRegistrationAgent",
+    "ProgressSnapshot",
+    "RegistrationSettings",
+    "ReleaseManifest",
+    "load_algorithm",
+]

algorithm_plugin_sdk/algorithm.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .context import ExecutionContext
+from .models import AlgorithmMetadata, AlgorithmRequest, AlgorithmResult
+
+
+class Algorithm(ABC):
+    """The only runtime contract an algorithm package must implement."""
+
+    @classmethod
+    @abstractmethod
+    def metadata(cls) -> AlgorithmMetadata:
+        """Describe the algorithm without loading models or datasets."""
+
+    def startup(self) -> None:
+        """Initialize process-level resources before the first execution."""
+
+    @abstractmethod
+    def execute(
+        self,
+        request: AlgorithmRequest,
+        context: ExecutionContext,
+    ) -> AlgorithmResult:
+        """Run all datasets and return their final results.
+
+        Algorithms own dataset/GPU scheduling and optional merging. Concurrent
+        workers report live progress through ``context.report_progress()``.
+        """
+
+    def shutdown(self) -> None:
+        """Release process-level resources during service shutdown."""

algorithm_plugin_sdk/cli.py

@@ -0,0 +1,542 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import replace
+import logging
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from contextlib import ExitStack, contextmanager, redirect_stderr, redirect_stdout
+from pathlib import Path
+from typing import Any
+
+from .context import ExecutionContext, ProgressSnapshot
+from .deployment import DEFAULT_CONFIG_NAME, DeploymentConfig, repository_root
+from .errors import ExecutionCancelled
+from .loader import load_algorithm
+from .models import AlgorithmRequest
+from .registration import PluginRegistrationAgent
+from .release import ReleaseManifest
+from .runner import AlgorithmRunner
+from .service import (
+    MAX_ATTEMPTS,
+    RETRY_JITTER_RATIO,
+    RETRY_SECONDS,
+    ExecutionManager,
+    run_server
+)
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _json_object(value: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"invalid JSON: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise argparse.ArgumentTypeError("value must be a JSON object")
+    return parsed
+
+
+def _gpu_ids(value: str) -> list[int]:
+    if not value.strip():
+        return []
+    try:
+        return [int(item.strip()) for item in value.split(",")]
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            "GPU IDs must be comma-separated integers"
+        ) from exc
+
+
+def _environment(value: str) -> tuple[str, str]:
+    name, separator, setting = value.partition("=")
+    if not separator or not name or not name.replace("_", "").isalnum():
+        raise argparse.ArgumentTypeError("environment must use NAME=VALUE")
+    if name.startswith("LDP_") or name.startswith("ALGORITHM_"):
+        raise argparse.ArgumentTypeError(
+            "SDK-managed LDP_/ALGORITHM_ settings must use dedicated options"
+        )
+    return name, setting
+
+
+def _add_serve_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("algorithm", help="entry-point name or package.module:AlgorithmClass")
+    parser.add_argument("--host", default=os.getenv("ALGORITHM_HOST", "0.0.0.0"))
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.getenv("ALGORITHM_PORT", os.getenv("LDP_PLUGIN_PORT", "9000"))),
+    )
+    parser.add_argument(
+        "--max-concurrent-executions",
+        type=int,
+        default=int(
+            os.getenv(
+                "ALGORITHM_MAX_CONCURRENT_EXECUTIONS",
+                os.getenv("LDP_PLUGIN_MAX_CONCURRENCY", "1"),
+            )
+        ),
+    )
+    parser.add_argument("--scratch-dir", default=os.getenv("ALGORITHM_SCRATCH_DIR"))
+    parser.add_argument(
+        "--gpu-ids", type=_gpu_ids, default=None,
+        help="GPU IDs injected into every service execution",
+    )
+    parser.add_argument(
+        "--max-attempts",
+        type=int,
+        default=int(os.getenv("ALGORITHM_MAX_ATTEMPTS", str(MAX_ATTEMPTS))),
+    )
+    parser.add_argument(
+        "--retry-seconds",
+        type=float,
+        default=float(os.getenv("ALGORITHM_RETRY_SECONDS", str(RETRY_SECONDS))),
+    )
+    parser.add_argument(
+        "--retry-jitter-ratio",
+        type=float,
+        default=float(
+            os.getenv("ALGORITHM_RETRY_JITTER_RATIO", str(RETRY_JITTER_RATIO))
+        ),
+    )
+    parser.add_argument(
+        "--webui",
+        action=argparse.BooleanOptionalAction,
+        default=_env_bool("ALGORITHM_WEBUI"),
+        help="serve the SDK processing UI at /ui/",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="algorithm-plugin")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = subparsers.add_parser("run", help="run datasets once")
+    run_parser.add_argument("algorithm", help="entry-point name or package.module:AlgorithmClass")
+    run_parser.add_argument("--input", action="append", type=_json_object, default=[])
+    run_parser.add_argument("--merge", action="store_true", default=None)
+    run_parser.add_argument("--gpu-ids", type=_gpu_ids)
+    run_parser.add_argument("--parameters", type=_json_object)
+    run_parser.add_argument("--request-file", type=Path)
+    run_parser.add_argument("--scratch-dir")
+    run_parser.add_argument("--algorithm-log", type=Path)
+
+    serve_parser = subparsers.add_parser("serve", help="run the generated HTTP service")
+    _add_serve_options(serve_parser)
+
+    config_parser = subparsers.add_parser(
+        "config", help="generate deployment config from the current repository"
+    )
+    config_parser.add_argument("algorithm", nargs="?", help="normally auto-detected")
+    config_parser.add_argument("--output", type=Path, default=Path(DEFAULT_CONFIG_NAME))
+    config_parser.add_argument("--repository", type=Path, default=Path.cwd())
+    config_parser.add_argument("--host", default="0.0.0.0")
+    config_parser.add_argument("--port", type=int, default=9000)
+    config_parser.add_argument(
+        "--webui", action=argparse.BooleanOptionalAction, default=True
+    )
+    config_parser.add_argument("--max-concurrency", type=int, default=1)
+    config_parser.add_argument("--scratch-dir")
+    config_parser.add_argument(
+        "--gpu-ids", type=_gpu_ids, default=[],
+        help="GPU IDs injected into every service execution",
+    )
+    config_parser.add_argument("--service-token")
+    config_parser.add_argument("--compute-url", default=os.getenv("LDP_COMPUTE_URL"))
+    config_parser.add_argument("--api-key", default=os.getenv("LDP_INTERNAL_API_KEY"))
+    config_parser.add_argument("--public-url", default=os.getenv("LDP_PLUGIN_PUBLIC_URL"))
+    config_parser.add_argument("--input-root", default=os.getenv("LDP_JOB_INPUT_ROOT"))
+    config_parser.add_argument(
+        "--workspace-root", default=os.getenv("LDP_JOB_WORKSPACE_ROOT")
+    )
+    config_parser.add_argument("--instance-key", default=os.getenv("LDP_PLUGIN_INSTANCE_KEY"))
+    config_parser.add_argument("--cluster", default=os.getenv("LDP_CLUSTER"))
+    config_parser.add_argument("--namespace", default=os.getenv("POD_NAMESPACE"))
+    config_parser.add_argument("--node-name", default=os.getenv("NODE_NAME"))
+    config_parser.add_argument(
+        "--local",
+        action="store_true",
+        help="generate a local config without compute registration",
+    )
+    config_parser.add_argument(
+        "--env", action="append", type=_environment, default=[], metavar="NAME=VALUE"
+    )
+
+    start_parser = subparsers.add_parser("start", help="start the configured service")
+    start_parser.add_argument("--config", type=Path, default=Path(DEFAULT_CONFIG_NAME))
+    start_parser.add_argument(
+        "--foreground", action="store_true", help="stay in foreground for systemd"
+    )
+
+    stop_parser = subparsers.add_parser("stop", help="stop the configured service")
+    stop_parser.add_argument("--config", type=Path, default=Path(DEFAULT_CONFIG_NAME))
+    stop_parser.add_argument("--timeout", type=float, default=30.0)
+    return parser
+
+
+def _request_from_args(args: argparse.Namespace) -> AlgorithmRequest:
+    values: dict[str, Any] = {}
+    if args.request_file is not None:
+        try:
+            values = json.loads(args.request_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"cannot read request file: {exc}") from exc
+        if not isinstance(values, dict):
+            raise ValueError("request file must contain a JSON object")
+    if args.input:
+        values["input"] = args.input
+    if args.merge is not None:
+        values["merge"] = args.merge
+    if args.gpu_ids is not None:
+        values["gpuIds"] = args.gpu_ids
+    if args.parameters is not None:
+        values["parameters"] = args.parameters
+    request = AlgorithmRequest.from_dict(values)
+    if args.gpu_ids is not None:
+        request = replace(request, gpu_ids=args.gpu_ids)
+    return request
+
+
+class TerminalProgress:
+    def __init__(self, stream: Any = None) -> None:
+        self.stream = stream or sys.stderr
+        self.enabled = bool(getattr(self.stream, "isatty", lambda: False)())
+        self._line_count = 0
+        self._lock = threading.Lock()
+
+    def update(self, snapshot: ProgressSnapshot) -> None:
+        if not self.enabled:
+            return
+        lines = []
+        for dataset, progress in snapshot.datasets.items():
+            lines.append(self._format_line(dataset, progress))
+            lines.extend(
+                self._format_line(f"  {episode}", episode_progress)
+                for episode, episode_progress in progress.episodes.items()
+            )
+        with self._lock:
+            if self._line_count:
+                self.stream.write(f"\x1b[{self._line_count}F")
+            for line in lines:
+                self.stream.write(f"\x1b[2K{line}\n")
+            self.stream.flush()
+            self._line_count = len(lines)
+
+    def close(self) -> None:
+        if self.enabled:
+            self.stream.flush()
+
+    @staticmethod
+    def _format_line(dataset: str, progress: Any) -> str:
+        name = dataset.rstrip("/") or dataset
+        percent = "  --%" if progress.percent is None else f"{progress.percent:5.1f}%"
+        filled = 0 if progress.percent is None else round(progress.percent / 5)
+        bar = f"[{'#' * filled}{'-' * (20 - filled)}]"
+        message = f" {progress.message}" if progress.message else ""
+        return f"{name:24.24} {bar} {percent} {progress.stage:16} {progress.status:9}{message}"
+
+
+@contextmanager
+def _cancel_on_interrupt(context: ExecutionContext, stream: Any):
+    interrupted = False
+    previous_handler = signal.getsignal(signal.SIGINT)
+
+    def handle_interrupt(_signum: int, _frame: Any) -> None:
+        nonlocal interrupted
+        if interrupted:
+            raise KeyboardInterrupt
+        interrupted = True
+        context.cancel("interrupted by user")
+        stream.write("\nCancellation requested; waiting for the algorithm to stop.\n")
+        stream.flush()
+
+    signal.signal(signal.SIGINT, handle_interrupt)
+    try:
+        yield
+    finally:
+        signal.signal(signal.SIGINT, previous_handler)
+
+
+def _run(args: argparse.Namespace) -> int:
+    request = _request_from_args(args)
+    progress = TerminalProgress()
+    context = ExecutionContext(
+        f"cli-{id(args)}",
+        [item.dataset for item in request.inputs],
+        scratch_dir=args.scratch_dir,
+        progress_callback=progress.update,
+    )
+    try:
+        with ExitStack() as stack:
+            if args.algorithm_log is not None:
+                args.algorithm_log.parent.mkdir(parents=True, exist_ok=True)
+                stream = stack.enter_context(
+                    args.algorithm_log.open("w", encoding="utf-8", buffering=1)
+                )
+                stack.enter_context(redirect_stdout(stream))
+                stack.enter_context(redirect_stderr(stream))
+            runner = AlgorithmRunner(load_algorithm(args.algorithm))
+            try:
+                with _cancel_on_interrupt(context, progress.stream):
+                    result = runner.run(request, context=context)
+            except ExecutionCancelled as exc:
+                print(f"CANCELLED: {exc}", file=progress.stream)
+                return 130
+            finally:
+                runner.close()
+    finally:
+        progress.close()
+    print(json.dumps({"type": "result", **result.to_dict()}, ensure_ascii=False))
+    return 0 if result.status == "succeeded" else 1
+
+
+def _serve(args: argparse.Namespace) -> int:
+    algorithm = load_algorithm(args.algorithm)
+
+    def create_runner() -> AlgorithmRunner:
+        return AlgorithmRunner(load_algorithm(args.algorithm))
+
+    release = ReleaseManifest.discover(algorithm, start=Path.cwd(), required=False)
+    manager = ExecutionManager(
+        AlgorithmRunner(algorithm),
+        max_concurrent_executions=args.max_concurrent_executions,
+        scratch_dir=args.scratch_dir,
+        gpu_ids=args.gpu_ids,
+        runner_factory=create_runner,
+        max_attempts=args.max_attempts,
+        retry_seconds=args.retry_seconds,
+        retry_jitter_ratio=args.retry_jitter_ratio,
+        release_manifest=release,
+    )
+    registration = PluginRegistrationAgent.from_env(manager.manifest, manager.heartbeat)
+    if registration is not None and release is None:
+        raise RuntimeError(
+            "compute registration requires release-manifest.json in the Algorithm repository"
+        )
+    run_server(
+        manager,
+        host=args.host,
+        port=args.port,
+        webui=args.webui,
+        token=os.getenv("LDP_PLUGIN_TOKEN") or None,
+        lifecycle=registration,
+    )
+    return 0
+
+
+def _config(args: argparse.Namespace) -> int:
+    registration = None
+    if not args.local:
+        supplied = {
+            "computeUrl": args.compute_url,
+            "apiKey": args.api_key,
+            "publicUrl": args.public_url,
+            "inputRoot": args.input_root,
+            "workspaceRoot": args.workspace_root,
+            "cluster": args.cluster,
+            "namespace": args.namespace,
+            "nodeName": args.node_name,
+        }
+        missing = [name for name, value in supplied.items() if not str(value or "").strip()]
+        if missing:
+            raise ValueError(
+                "deployment registration requires "
+                + ", ".join(missing)
+                + "; use --local to disable registration"
+            )
+        registration = {name: str(value) for name, value in supplied.items()}
+        if args.instance_key:
+            registration["instanceKey"] = args.instance_key
+    root = repository_root(args.repository)
+    output = args.output if args.output.is_absolute() else root / args.output
+    config = DeploymentConfig.generate(
+        output=output,
+        root=root,
+        algorithm=args.algorithm,
+        host=args.host,
+        port=args.port,
+        webui=args.webui,
+        max_concurrency=args.max_concurrency,
+        scratch_dir=args.scratch_dir,
+        token=args.service_token,
+        gpu_ids=args.gpu_ids,
+        registration=registration,
+        environment=dict(args.env),
+    )
+    config.save()
+    identity = config.payload["algorithm"]
+    print(
+        f"Generated {config.path} for {identity['type']}@{identity['version']} "
+        f"({identity['implementationDigest']})"
+    )
+    return 0
+
+
+def _proc_start_time(pid: int) -> str | None:
+    try:
+        fields = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").split()
+    except OSError:
+        return None
+    return fields[21] if len(fields) > 21 else None
+
+
+def _read_process_state(config: DeploymentConfig) -> dict[str, Any] | None:
+    try:
+        state = json.loads(config.pid_file.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"cannot read PID state {config.pid_file}: {exc}") from exc
+    if not isinstance(state, dict) or not isinstance(state.get("pid"), int):
+        raise RuntimeError(f"invalid PID state: {config.pid_file}")
+    return state
+
+
+def _is_managed_process(config: DeploymentConfig, state: dict[str, Any]) -> bool:
+    pid = int(state["pid"])
+    if _proc_start_time(pid) != str(state.get("startTime")):
+        return False
+    try:
+        command = Path(f"/proc/{pid}/cmdline").read_bytes().replace(b"\0", b" ").decode()
+    except OSError:
+        return False
+    return (
+        "algorithm_plugin_sdk.cli" in command
+        and " serve " in f" {command} "
+        and config.algorithm_reference in command
+    )
+
+
+def _start(args: argparse.Namespace) -> int:
+    config = DeploymentConfig.load(args.config)
+    config.save()  # Persist any auto-refreshed release identity.
+    service = config.payload["service"]
+    command = [
+        sys.executable,
+        "-m",
+        "algorithm_plugin_sdk.cli",
+        "serve",
+        config.algorithm_reference,
+        "--host",
+        str(service["host"]),
+        "--port",
+        str(service["port"]),
+        "--max-concurrent-executions",
+        str(service["maxConcurrency"]),
+    ]
+    command.append("--webui" if service.get("webui") else "--no-webui")
+    if service.get("scratchDir"):
+        command.extend(("--scratch-dir", str(service["scratchDir"])))
+    if "gpuIds" in service:
+        command.extend(("--gpu-ids", ",".join(str(value) for value in service["gpuIds"])))
+
+    if args.foreground:
+        os.chdir(config.repository)
+        os.execve(sys.executable, command, config.process_environment())
+
+    existing = _read_process_state(config)
+    if existing and _is_managed_process(config, existing):
+        print(f"Algorithm service is already running (pid {existing['pid']})")
+        return 0
+    if existing:
+        config.pid_file.unlink(missing_ok=True)
+
+    config.log_file.parent.mkdir(parents=True, exist_ok=True)
+    with config.log_file.open("ab", buffering=0) as log:
+        process = subprocess.Popen(
+            command,
+            cwd=config.repository,
+            env=config.process_environment(),
+            stdin=subprocess.DEVNULL,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+    time.sleep(0.25)
+    status = process.poll()
+    if status is not None:
+        raise RuntimeError(
+            f"algorithm service exited with status {status}; see {config.log_file}"
+        )
+    start_time = _proc_start_time(process.pid)
+    if start_time is None:
+        raise RuntimeError("algorithm service disappeared during startup")
+    config.pid_file.write_text(
+        json.dumps(
+            {
+                "pid": process.pid,
+                "startTime": start_time,
+                "algorithm": config.algorithm_reference,
+                "config": str(config.path),
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    print(f"Started algorithm service (pid {process.pid}); log: {config.log_file}")
+    return 0
+
+
+def _stop(args: argparse.Namespace) -> int:
+    if args.timeout < 0:
+        raise ValueError("timeout cannot be negative")
+    config = DeploymentConfig.load(args.config, refresh=False)
+    state = _read_process_state(config)
+    if state is None:
+        print("Algorithm service is not running")
+        return 0
+    if not _is_managed_process(config, state):
+        config.pid_file.unlink(missing_ok=True)
+        print("Algorithm service is not running; removed stale PID state")
+        return 0
+    pid = int(state["pid"])
+    os.kill(pid, signal.SIGTERM)
+    deadline = time.monotonic() + args.timeout
+    while _is_managed_process(config, state) and time.monotonic() < deadline:
+        time.sleep(0.1)
+    if _is_managed_process(config, state):
+        os.kill(pid, signal.SIGKILL)
+        while _is_managed_process(config, state):
+            time.sleep(0.05)
+    config.pid_file.unlink(missing_ok=True)
+    print(f"Stopped algorithm service (pid {pid})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handlers = {
+        "run": _run,
+        "serve": _serve,
+        "config": _config,
+        "start": _start,
+        "stop": _stop,
+    }
+    try:
+        return handlers[args.command](args)
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:
+        print(f"ERROR: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())