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

algorithm_plugin_sdk/cli.py

@@ -1,536 +1,38 @@
 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/",
-    )
+from .cli_impl import configure as configure_command
+from .cli_impl import run as run_command
+from .cli_impl import serve as serve_command
 
 
 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)
+    subs = parser.add_subparsers(dest="command", required=True)
 
-    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",
+    run_command.configure_parser(
+        subs.add_parser("run", help="run datasets once")
     )
-    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")
+    serve_command.configure_parser(
+        subs.add_parser("serve", help="run the generated HTTP service")
     )
-    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",
+    configure_command.configure_parser(
+        subs.add_parser("configure", help="configure an existing Algorithm repository for systemd")
     )
-    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,
-    }
+    args = build_parser().parse_args(argv)
     try:
-        return handlers[args.command](args)
+        return args.handler(args)
     except KeyboardInterrupt:
         return 130
     except Exception as exc:

algorithm_plugin_sdk/cli_impl/__init__.py

@@ -0,0 +1 @@
+"""Implementation modules for the algorithm-plugin command line interface."""