ls-algorithm-plugin-sdk 0.3.1__tar.gz → 0.3.4__tar.gz

{ls_algorithm_plugin_sdk-0.3.1 → ls_algorithm_plugin_sdk-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ls-algorithm-plugin-sdk
-Version: 0.3.1
+Version: 0.3.4
 Summary: Protocol-independent runtime SDK for dataset algorithms
 Author: Ling Robotics
 License: Proprietary

{ls_algorithm_plugin_sdk-0.3.1 → ls_algorithm_plugin_sdk-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ls-algorithm-plugin-sdk"
-version = "0.3.1"
+version = "0.3.4"
 description = "Protocol-independent runtime SDK for dataset algorithms"
 readme = "README.md"
 requires-python = ">=3.10"

{ls_algorithm_plugin_sdk-0.3.1 → ls_algorithm_plugin_sdk-0.3.4}/src/algorithm_plugin_sdk/cli_impl/configure.py

@@ -16,7 +16,7 @@ from ..deployment import (
     repository_root,
     stable_instance_key,
 )
-from .parsing import environment, gpu_ids
+from .parsing import environment, gpu_ids, json_object
 
 
 SYSTEMD_UNIT_DIR = Path("/etc/systemd/system")
@@ -56,14 +56,34 @@ def configure_parser(parser: argparse.ArgumentParser) -> None:
         action=argparse.BooleanOptionalAction,
         default=True,
     )
-    parser.add_argument("--max-concurrency", type=int, default=1)
+    parser.add_argument(
+        "--max-concurrency",
+        type=int,
+        help="maximum concurrent executions (default: GPU count, or 1)",
+    )
     parser.add_argument("--scratch-dir")
+    parser.add_argument(
+        "--local-scratch",
+        action="store_true",
+        help="override request scratchRoot with <repository>/.scratch",
+    )
+    parser.add_argument(
+        "--local-output",
+        action="store_true",
+        help="override request output paths with <repository>/.output/<job-id>",
+    )
     parser.add_argument(
         "--gpu-ids",
         type=gpu_ids,
         default=[],
         help="GPU IDs injected into every service execution",
     )
+    parser.add_argument(
+        "--default-parameters",
+        type=json_object,
+        default={},
+        help="JSON object used to fill missing request parameters",
+    )
     parser.add_argument("--service-token")
     parser.add_argument(
         "--compute-url",
@@ -139,10 +159,18 @@ def render_systemd_unit(
     repository: Path,
     config_path: Path,
     service_name: str,
+    gpu_ids: list[int] | None = None,
 ) -> str:
     root = repository.resolve()
+    working_directory = root / "jobs"
     launcher = root / ".venv" / "bin" / "algorithm-plugin"
     config = config_path.resolve()
+    environment = ["Environment=PYTHONUNBUFFERED=1"]
+    if gpu_ids:
+        environment.append(
+            "Environment=CUDA_VISIBLE_DEVICES="
+            + ",".join(str(gpu_id) for gpu_id in gpu_ids)
+        )
     return "\n".join(
         (
             "[Unit]",
@@ -153,12 +181,13 @@ def render_systemd_unit(
             "[Service]",
             "Type=simple",
             "User=root",
-            f"WorkingDirectory={_escape_systemd_path(root)}",
+            f"WorkingDirectory={_escape_systemd_path(working_directory)}",
             (
                 f"ExecStart={_quote_systemd_path(launcher)} "
                 f"serve --config {_quote_systemd_path(config)}"
             ),
-            "Environment=PYTHONUNBUFFERED=1",
+            *environment,
+            "LimitNOFILE=524288",
             "Restart=on-failure",
             "RestartSec=5s",
             "",
@@ -376,6 +405,11 @@ def generate_config(
     args: argparse.Namespace,
     repository: Path,
 ) -> DeploymentConfig:
+    max_concurrency = (
+        args.max_concurrency
+        if args.max_concurrency is not None
+        else max(len(args.gpu_ids), 1)
+    )
     config = DeploymentConfig.generate(
         output=args.config_output,
         root=repository,
@@ -383,12 +417,15 @@ def generate_config(
         host=args.host,
         port=args.port,
         webui=args.webui,
-        max_concurrency=args.max_concurrency,
+        max_concurrency=max_concurrency,
         scratch_dir=args.scratch_dir,
+        local_scratch=args.local_scratch,
+        local_output=args.local_output,
         token=args.service_token,
         registration=registration_from_args(args, repository),
         gpu_ids=args.gpu_ids,
         environment=dict(args.env),
+        default_parameters=args.default_parameters,
     )
     config.save()
     return config
@@ -407,6 +444,7 @@ def execute(args: argparse.Namespace) -> int:
         repository=repository,
         config_path=config_path,
         service_name=service_name,
+        gpu_ids=args.gpu_ids,
     )
 
     inspect_systemd_unit(
@@ -414,6 +452,7 @@ def execute(args: argparse.Namespace) -> int:
         content=unit,
         force=args.force,
     )
+    (repository / "jobs").mkdir(exist_ok=True)
     config = generate_config(args, repository)
     unit_path, changed = write_systemd_unit(
         service_name=service_name,

{ls_algorithm_plugin_sdk-0.3.1 → ls_algorithm_plugin_sdk-0.3.4}/src/algorithm_plugin_sdk/cli_impl/run.py

@@ -17,6 +17,7 @@ from typing import Any, Iterator
 
 from ..context import ExecutionContext, ProgressSnapshot
 from ..errors import ExecutionCancelled
+from ..gpu_isolation import apply_gpu_isolation
 from ..loader import load_algorithm
 from ..models import AlgorithmRequest
 from ..runner import AlgorithmRunner
@@ -125,6 +126,10 @@ def cancel_on_interrupt(
 
 def execute(args: argparse.Namespace) -> int:
     request = request_from_args(args)
+    request = replace(
+        request,
+        gpu_ids=apply_gpu_isolation(request.gpu_ids),
+    )
     progress = TerminalProgress()
     context = ExecutionContext(
         f"cli-{id(args)}",

{ls_algorithm_plugin_sdk-0.3.1 → ls_algorithm_plugin_sdk-0.3.4}/src/algorithm_plugin_sdk/cli_impl/serve.py

@@ -5,6 +5,7 @@ import os
 from pathlib import Path
 
 from ..deployment import DEFAULT_CONFIG_NAME, DeploymentConfig
+from ..gpu_isolation import apply_gpu_isolation
 from ..loader import load_algorithm
 from ..registration import PluginRegistrationAgent
 from ..release import ReleaseManifest
@@ -78,15 +79,22 @@ def configure_parser(parser: argparse.ArgumentParser) -> None:
 
 
 def execute(args: argparse.Namespace) -> int:
+    config: DeploymentConfig | None = None
+    service: dict[str, object] | None = None
+    local_scratch = False
+    local_output = False
     if args.config:
-        config = DeploymentConfig.load(args.config)
-        config.save()
+        # Apply the process mask before refreshing/loading the algorithm.  A
+        # repository module may import CUDA during module import.
+        config = DeploymentConfig.load(args.config, refresh=False)
         service = config.payload["service"]
         args.algorithm = config.algorithm_reference
         args.host = str(service["host"])
         args.port = int(service["port"])
         args.max_concurrent_executions = int(service["maxConcurrency"])
         args.scratch_dir = service.get("scratchDir")
+        local_scratch = bool(service.get("localScratch", False))
+        local_output = bool(service.get("localOutput", False))
         args.gpu_ids = list(service.get("gpuIds", []))
         args.webui = bool(service.get("webui"))
         values = config.process_environment()
@@ -96,6 +104,11 @@ def execute(args: argparse.Namespace) -> int:
     elif not args.algorithm:
         raise ValueError("algorithm is required unless --config is provided")
 
+    args.gpu_ids = apply_gpu_isolation(args.gpu_ids)
+    if config is not None:
+        config.refresh()
+        config.save()
+
     algorithm_reference = str(args.algorithm)
     algorithm = load_algorithm(algorithm_reference)
 
@@ -105,14 +118,21 @@ def execute(args: argparse.Namespace) -> int:
     release = ReleaseManifest.discover(algorithm, start=Path.cwd(), required=False)
     manager = ExecutionManager(
         AlgorithmRunner(algorithm),
+        default_parameters=(
+            service.get("defaultParameters", {})
+            if service is not None else None
+        ),
         max_concurrent_executions=args.max_concurrent_executions,
         scratch_dir=args.scratch_dir,
+        local_scratch=local_scratch,
+        local_output=local_output,
         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,
+        repository=(config.repository if config is not None else Path.cwd()),
     )
     registration = PluginRegistrationAgent.from_env(manager.manifest, manager.heartbeat)
     if registration is not None and release is None:

{ls_algorithm_plugin_sdk-0.3.1 → ls_algorithm_plugin_sdk-0.3.4}/src/algorithm_plugin_sdk/deployment.py

@@ -145,6 +145,9 @@ class DeploymentConfig:
         registration: dict[str, str] | None,
         gpu_ids: list[int] | None = None,
         environment: dict[str, str] | None = None,
+        default_parameters: dict[str, Any] | None = None,
+        local_scratch: bool = False,
+        local_output: bool = False,
     ) -> "DeploymentConfig":
         repository = repository_root(root)
         _make_repository_importable(repository)
@@ -188,8 +191,11 @@ class DeploymentConfig:
                 "webui": webui,
                 "maxConcurrency": max_concurrency,
                 "scratchDir": _absolute(scratch_dir, repository),
+                "localScratch": local_scratch,
+                "localOutput": local_output,
                 "gpuIds": configured_gpu_ids,
                 "token": token or None,
+                "defaultParameters": dict(default_parameters or {}),
             },
             "registration": registration,
             "environment": dict(sorted((environment or {}).items())),
@@ -266,6 +272,9 @@ class DeploymentConfig:
             raise RuntimeError("service port must be in [1, 65535]")
         if concurrency < 1:
             raise RuntimeError("service maxConcurrency must be positive")
+        for name in ("localScratch", "localOutput"):
+            if not isinstance(service.get(name, False), bool):
+                raise RuntimeError(f"service {name} must be a boolean")
         gpu_ids = service.get("gpuIds")
         if not isinstance(gpu_ids, list) or any(
             isinstance(gpu_id, bool) or not isinstance(gpu_id, int) or gpu_id < 0
@@ -273,6 +282,16 @@ class DeploymentConfig:
         ) or len(gpu_ids) != len(set(gpu_ids)):
             raise RuntimeError("service gpuIds must be unique non-negative integers")
 
+        default_parameters = service.get("defaultParameters", {})
+        if not isinstance(default_parameters, dict):
+            raise RuntimeError("defaultParameters must be an object")
+        if any(not isinstance(key, str) for key in default_parameters):
+            raise RuntimeError("defaultParameters keys must be strings")
+        try:
+            json.dumps(default_parameters)
+        except (TypeError, ValueError) as exc:
+            raise RuntimeError("defaultParameters must be JSON serializable") from exc
+
     def _validate_registration(self) -> None:
         registration = self.payload.get("registration")
         if registration is None:

ls_algorithm_plugin_sdk-0.3.4/src/algorithm_plugin_sdk/gpu_isolation.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+
+
+def apply_gpu_isolation(gpu_ids: Sequence[int] | None) -> list[int]:
+    """Mask physical GPUs for this process and return local GPU ordinals."""
+    if gpu_ids is None:
+        return []
+
+    physical_gpu_ids = list(gpu_ids)
+    if any(
+        isinstance(gpu_id, bool)
+        or not isinstance(gpu_id, int)
+        or gpu_id < 0
+        for gpu_id in physical_gpu_ids
+    ) or len(physical_gpu_ids) != len(set(physical_gpu_ids)):
+        raise ValueError("gpu_ids must be unique non-negative integers")
+
+    if not physical_gpu_ids:
+        return []
+
+    os.environ["CUDA_VISIBLE_DEVICES"] = ",".join(
+        str(gpu_id) for gpu_id in physical_gpu_ids
+    )
+    return list(range(len(physical_gpu_ids)))

ls_algorithm_plugin_sdk-0.3.4/src/algorithm_plugin_sdk/log_manager.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+from pathlib import Path
+from typing import Any
+
+from .context import utc_now
+
+_SAFE_NAME = re.compile(r"[^A-Za-z0-9._-]+")
+_TIMESTAMP_GLOB = "[0-9]" * 14
+_FILE_LOCKS_GUARD = threading.Lock()
+_FILE_LOCKS: dict[Path, threading.RLock] = {}
+
+
+def _safe_name(value: str) -> str:
+    cleaned = _SAFE_NAME.sub("_", str(value).strip()).strip("._")
+    return cleaned or "job"
+
+
+def _file_lock(path: Path) -> threading.RLock:
+    with _FILE_LOCKS_GUARD:
+        return _FILE_LOCKS.setdefault(path, threading.RLock())
+
+
+def _timestamp_prefix() -> str:
+    return utc_now().replace("-", "").replace(":", "").replace("T", "")[:14]
+
+
+def _job_log_path(directory: Path, job_id: str) -> Path:
+    safe_job_id = _safe_name(job_id)
+    pattern = f"{_TIMESTAMP_GLOB}-{safe_job_id}.log"
+    with _FILE_LOCKS_GUARD:
+        existing = sorted(directory.glob(pattern))
+        if existing:
+            return existing[0]
+        timestamp = _timestamp_prefix()
+        path = directory / f"{timestamp}-{safe_job_id}.log"
+        path.touch(exist_ok=True)
+        return path
+
+
+class ExecutionLog:
+    """Per-job, line-buffered log sink attached to context.logger."""
+
+    def __init__(
+        self,
+        *,
+        log_dir: str | Path,
+        job_id: str,
+        execution_id: str,
+        logger: logging.Logger,
+        task_id: str | None = None,
+    ) -> None:
+        resolved_task_id = task_id or execution_id
+        self._event_context = {
+            "jobId": job_id,
+            "taskId": resolved_task_id,
+            "executionId": execution_id,
+            "job_id": job_id,
+            "task_id": resolved_task_id,
+            "execution_id": execution_id,
+        }
+        directory = Path(log_dir).expanduser()
+        directory.mkdir(parents=True, exist_ok=True)
+        path = _job_log_path(directory, job_id)
+        self.path = path
+        self._stream = path.open("a", encoding="utf-8", buffering=1)
+        self._lock = _file_lock(path)
+        self._handler = _FlushFileHandler(self._stream, self._lock)
+        self._handler.setFormatter(
+            logging.Formatter(
+                f"%(asctime)s %(levelname)s [executionId={execution_id}] %(message)s"
+            )
+        )
+        self._handler.setLevel(logging.DEBUG)
+        self.logger = logger
+        self.logger.setLevel(logging.DEBUG)
+        self.logger.addHandler(self._handler)
+        self._closed = False
+
+    def write_event(self, event: str, **values: Any) -> None:
+        payload = {
+            "event": event,
+            "timestamp": utc_now(),
+            **self._event_context,
+            **values,
+        }
+        with self._lock:
+            if self._closed:
+                return
+            self._stream.write(json.dumps(payload, ensure_ascii=False, default=str) + "\n")
+            self._stream.flush()
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            self.logger.removeHandler(self._handler)
+            self._handler.close()
+            self._stream.close()
+
+
+class _FlushFileHandler(logging.Handler):
+    def __init__(self, stream: Any, lock: threading.RLock) -> None:
+        super().__init__()
+        self.stream = stream
+        self._lock = lock
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            with self._lock:
+                self.stream.write(self.format(record) + "\n")
+                self.stream.flush()
+        except Exception:
+            self.handleError(record)
+
+    def close(self) -> None:
+        try:
+            self.stream.flush()
+        finally:
+            super().close()