mmo-runtime 0.1.3__tar.gz

mmo_runtime-0.1.3/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: mmo-runtime
+Version: 0.1.3
+Summary: Runtime library for MMO gRPC tools
+Author-email: tool-mmo <tranduythuc2003@gmail.com>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/tool-mmo3/base/toolkit-mmo
+Project-URL: Repository, https://gitlab.com/tool-mmo3/base/toolkit-mmo
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: import-linter>=2.4; extra == "dev"
+
+# mmo-runtime
+
+Runtime library for MMO gRPC tools.
+
+## Worker execution
+
+`stream_in_worker(workflow, request, ctx, *, pool=None, timeout=None)` yields
+`ProgressEvent` objects in order, then one `ResultEnvelope` or `ErrorEnvelope`.
+Even without a supplied pool the workflow runs on a worker thread, so progress
+is available before completion. Progress is buffered up to 64 events; slow
+consumers apply backpressure rather than dropping events or growing memory
+without bound. Close abandoned iterators to release blocked producers.
+
+Timeout is measured from the first iterator advance and includes queue time.
+`None` disables the deadline; zero (or a negative value) expires immediately.
+Cancellation, timeout, and iterator closure signal `ctx.cancel` and cancel jobs
+which have not started. Running workflows must cooperatively check the token
+and bound their own blocking I/O. Python threads are **not** forcibly terminated;
+an uncooperative job can retain its worker slot and delay process exit.
+
+`run_in_worker` retains its legacy `(terminal, progress_list)` API, including
+inline execution without a pool and pooled cancellation/admission exceptions.
+Its accumulated progress list is intentionally not memory-bounded; use the
+streaming API for long-running jobs. `WorkerPool.shutdown(cancel_futures=True)`
+cancels waiting jobs; it does not interrupt running jobs.
+
+## Transport and lifecycle
+
+`ToolClient.channel` is public for constructing service stubs. Unary and stream
+calls accept `deadline` (including zero) and keyword-only `metadata`, a sequence
+of `(key, value)` pairs. Unknown error-envelope codes normalize to `INTERNAL`.
+Unavailable transports map to retryable `PROVIDER_ERROR`; resource exhaustion,
+invalid requests, cancellation, and expired deadlines retain their error codes.
+Health polling limits each probe and sleep to the remaining polling budget.
+
+Plain Unix socket paths, explicit `unix://` targets, TCP `host:port` (including
+IPv6), and resolver targets are normalized without duplicate Unix prefixes.
+The default on Windows is `127.0.0.1:50051`; choose explicit per-tool ports to
+avoid collisions. Unix keeps `/tmp/tool.sock` as its default.
+
+The server tracks the full handler lifetime of unary and streaming application
+RPCs. Health probes do not keep an otherwise idle server alive. The idle period
+restarts after the last active handler exits. Shutdown is one-shot, marks
+health not-serving, signals the server cancellation token, waits for gRPC's
+graceful stop, then cleans up transport resources and invokes `on_stop` once.
+Signal handlers are installed only on the Unix main thread and restored on exit.
+An instance is single-use; create a new instance to restart.
+
+The server cancellation token is available for embedded workflows; generated
+servicers use their own per-RPC token and gRPC cancellation callback. Graceful
+shutdown therefore lets existing generated RPCs finish until grace expires.
+Neither `job_timeout_sec` nor the server token is automatically injected into
+arbitrary registered handlers: pass explicit worker deadlines and cancellation
+tokens when implementing custom handlers.

mmo_runtime-0.1.3/README.md

@@ -0,0 +1,54 @@
+# mmo-runtime
+
+Runtime library for MMO gRPC tools.
+
+## Worker execution
+
+`stream_in_worker(workflow, request, ctx, *, pool=None, timeout=None)` yields
+`ProgressEvent` objects in order, then one `ResultEnvelope` or `ErrorEnvelope`.
+Even without a supplied pool the workflow runs on a worker thread, so progress
+is available before completion. Progress is buffered up to 64 events; slow
+consumers apply backpressure rather than dropping events or growing memory
+without bound. Close abandoned iterators to release blocked producers.
+
+Timeout is measured from the first iterator advance and includes queue time.
+`None` disables the deadline; zero (or a negative value) expires immediately.
+Cancellation, timeout, and iterator closure signal `ctx.cancel` and cancel jobs
+which have not started. Running workflows must cooperatively check the token
+and bound their own blocking I/O. Python threads are **not** forcibly terminated;
+an uncooperative job can retain its worker slot and delay process exit.
+
+`run_in_worker` retains its legacy `(terminal, progress_list)` API, including
+inline execution without a pool and pooled cancellation/admission exceptions.
+Its accumulated progress list is intentionally not memory-bounded; use the
+streaming API for long-running jobs. `WorkerPool.shutdown(cancel_futures=True)`
+cancels waiting jobs; it does not interrupt running jobs.
+
+## Transport and lifecycle
+
+`ToolClient.channel` is public for constructing service stubs. Unary and stream
+calls accept `deadline` (including zero) and keyword-only `metadata`, a sequence
+of `(key, value)` pairs. Unknown error-envelope codes normalize to `INTERNAL`.
+Unavailable transports map to retryable `PROVIDER_ERROR`; resource exhaustion,
+invalid requests, cancellation, and expired deadlines retain their error codes.
+Health polling limits each probe and sleep to the remaining polling budget.
+
+Plain Unix socket paths, explicit `unix://` targets, TCP `host:port` (including
+IPv6), and resolver targets are normalized without duplicate Unix prefixes.
+The default on Windows is `127.0.0.1:50051`; choose explicit per-tool ports to
+avoid collisions. Unix keeps `/tmp/tool.sock` as its default.
+
+The server tracks the full handler lifetime of unary and streaming application
+RPCs. Health probes do not keep an otherwise idle server alive. The idle period
+restarts after the last active handler exits. Shutdown is one-shot, marks
+health not-serving, signals the server cancellation token, waits for gRPC's
+graceful stop, then cleans up transport resources and invokes `on_stop` once.
+Signal handlers are installed only on the Unix main thread and restored on exit.
+An instance is single-use; create a new instance to restart.
+
+The server cancellation token is available for embedded workflows; generated
+servicers use their own per-RPC token and gRPC cancellation callback. Graceful
+shutdown therefore lets existing generated RPCs finish until grace expires.
+Neither `job_timeout_sec` nor the server token is automatically injected into
+arbitrary registered handlers: pass explicit worker deadlines and cancellation
+tokens when implementing custom handlers.

mmo_runtime-0.1.3/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "mmo-runtime"
+description = "Runtime library for MMO gRPC tools"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "tool-mmo", email = "tranduythuc2003@gmail.com"},
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://gitlab.com/tool-mmo3/base/toolkit-mmo"
+Repository = "https://gitlab.com/tool-mmo3/base/toolkit-mmo"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+    "pyright>=1.1",
+    "import-linter>=2.4",
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mmo_runtime*"]
+
+[tool.setuptools_scm]
+write_to = "src/mmo_runtime/_version.py"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.11"
+
+[tool.importlinter]
+root_package = "mmo_runtime"
+include_external_packages = true
+contracts = [
+    {name = "no_ai", type = "forbidden", source_modules = ["mmo_runtime"], forbidden_modules = ["torch", "transformers", "onnx", "tensorflow", "numpy", "cv2", "PIL"]},
+]

mmo_runtime-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mmo_runtime-0.1.3/src/mmo_runtime/__init__.py

@@ -0,0 +1,55 @@
+"""mmo-runtime: Runtime library for MMO gRPC tools."""
+
+from .client import ToolClient, consume_stream, ensure_running
+from .config import BaseServerConfig, load_config
+from .context import CancelToken, ProgressReporter, RunContext
+from .errors import (
+    Cancelled,
+    DeadlineExceeded,
+    Internal,
+    InvalidRequest,
+    ProviderError,
+    ResourceExhausted,
+    ToolError,
+    to_grpc_status,
+    wrap_unknown,
+)
+from .events import ErrorEnvelope, ProgressEvent, ResultEnvelope
+from .layout import RunLayout
+from .logging import setup_logging
+from .manifest import Manifest
+from .server import serve
+from .worker import run_in_worker
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "BaseServerConfig",
+    "CancelToken",
+    "Cancelled",
+    "DeadlineExceeded",
+    "ErrorEnvelope",
+    "Internal",
+    "InvalidRequest",
+    "Manifest",
+    "ProgressEvent",
+    "ProgressReporter",
+    "ProviderError",
+    "ResourceExhausted",
+    "ResultEnvelope",
+    "RunContext",
+    "RunLayout",
+    "ToolClient",
+    "ToolError",
+    "consume_stream",
+    "ensure_running",
+    "load_config",
+    "run_in_worker",
+    "serve",
+    "setup_logging",
+    "to_grpc_status",
+    "wrap_unknown",
+]

mmo_runtime-0.1.3/src/mmo_runtime/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.3'
+__version_tuple__ = version_tuple = (0, 1, 3)
+
+__commit_id__ = commit_id = None

mmo_runtime-0.1.3/src/mmo_runtime/client.py

@@ -0,0 +1,294 @@
+"""gRPC client with deadline, stream consumption, and ensure_running."""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Callable, Iterator, Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NoReturn, Self, TypeVar
+
+import grpc
+from grpc_health.v1 import health_pb2, health_pb2_grpc
+
+from .errors import Cancelled, DeadlineExceeded, ErrorCode, Internal, ToolError
+from .events import ProgressEvent, ResultEnvelope
+from .transport import normalize_target
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+T = TypeVar("T")
+
+
+def _get_target_address(socket_path: str) -> str:
+    """Determine gRPC target address for the current platform.
+
+    On Windows ``socket_path`` is a TCP ``host:port`` (grpc Python has no
+    ``windows://`` named-pipe resolver). On Unix it is a Unix domain socket path.
+    """
+    return normalize_target(socket_path)
+
+
+def consume_stream(
+    stream: Iterator[Any],
+    on_progress: Callable[[ProgressEvent], None] | None = None,
+) -> ResultEnvelope:
+    """
+    Consume a server-streaming RPC, yielding progress and returning final result.
+    Raises ToolError on error status or error envelope.
+    """
+    result: ResultEnvelope = ResultEnvelope(payload=None)
+    has_result = False
+    for msg in stream:
+        # Check for progress/result/error oneof
+        if hasattr(msg, "WhichOneof"):
+            oneof = msg.WhichOneof("payload")
+            if oneof == "progress":
+                prog = msg.progress
+                event = ProgressEvent(
+                    step=prog.step,
+                    done=prog.done,
+                    total=prog.total if prog.total > 0 else None,
+                    message=prog.message if prog.message else None,
+                    meta=dict(prog.meta) if hasattr(prog, "meta") else {},
+                )
+                if on_progress:
+                    on_progress(event)
+            elif oneof == "result":
+                result = ResultEnvelope(
+                    payload=msg.result.payload if hasattr(msg.result, "payload") else msg.result,
+                    artifacts=list(msg.result.artifacts)
+                    if hasattr(msg.result, "artifacts")
+                    else [],
+                    meta=dict(msg.result.meta) if hasattr(msg.result, "meta") else {},
+                )
+                has_result = True
+            elif oneof == "error":
+                err = msg.error
+                raise ToolError(
+                    code=err.code,
+                    step=err.step if err.step else None,
+                    provider=err.provider if err.provider else None,
+                    message=err.message,
+                    retryable=err.retryable,
+                )
+        else:
+            # Fallback: assume message is result
+            result = ResultEnvelope(payload=msg)
+            has_result = True
+
+    if not has_result:
+        raise Internal("Stream ended without result")
+    return result
+
+
+class ToolClient:
+    """Client for tool gRPC service."""
+
+    def __init__(
+        self,
+        socket_path: str,
+        default_deadline: float = 30.0,
+        health_check_timeout: float = 5.0,
+    ):
+        self.socket_path = socket_path
+        self.default_deadline = default_deadline
+        self.health_check_timeout = health_check_timeout
+        self._channel: grpc.Channel | None = None
+        self._health_stub: health_pb2_grpc.HealthStub | None = None
+        self._log = logging.getLogger(__name__)
+        self._channel_lock = threading.RLock()
+
+    @property
+    def channel(self) -> grpc.Channel:
+        """Public lazily-created channel for generated service stubs."""
+        return self._ensure_channel()
+
+    def _ensure_channel(self) -> grpc.Channel:
+        with self._channel_lock:
+            if self._channel is None:
+                target = _get_target_address(self.socket_path)
+                self._channel = grpc.insecure_channel(target)
+                self._health_stub = health_pb2_grpc.HealthStub(self._channel)
+            return self._channel
+
+    def close(self) -> None:
+        with self._channel_lock:
+            if self._channel is not None:
+                self._channel.close()
+                self._channel = None
+                self._health_stub = None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def health_check(
+        self,
+        service: str = "",
+        *,
+        timeout: float | None = None,
+    ) -> health_pb2.HealthCheckResponse.ServingStatus:
+        self._ensure_channel()
+        try:
+            resp: health_pb2.HealthCheckResponse = self._health_stub.Check(  # type: ignore[attr-defined]
+                health_pb2.HealthCheckRequest(service=service),
+                timeout=self.health_check_timeout if timeout is None else timeout,
+            )
+            # grpc_health pb2 ships untyped; status enum member is Unknown to pyright
+            return resp.status  # type: ignore[return-value]
+        except grpc.RpcError as e:
+            if e.code() in (grpc.StatusCode.UNAVAILABLE, grpc.StatusCode.DEADLINE_EXCEEDED):
+                return health_pb2.HealthCheckResponse.ServingStatus.SERVICE_UNKNOWN
+            raise
+
+    def wait_healthy(self, timeout: float = 30.0, interval: float = 0.5) -> bool:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            remaining = min(timeout, max(0, deadline - time.monotonic()))
+            if (
+                self.health_check(timeout=min(self.health_check_timeout, remaining))
+                == health_pb2.HealthCheckResponse.ServingStatus.SERVING
+            ):
+                return True
+            time.sleep(max(0, min(interval, deadline - time.monotonic())))
+        return False
+
+    def call_unary(
+        self,
+        method: Callable[..., Any],
+        request: Any,
+        deadline: float | None = None,
+        *,
+        metadata: Sequence[tuple[str, str | bytes]] | None = None,
+    ) -> Any:
+        """Call a unary RPC with deadline."""
+        self._ensure_channel()
+        try:
+            kwargs: dict[str, Any] = {
+                "timeout": self.default_deadline if deadline is None else deadline,
+            }
+            if metadata is not None:
+                kwargs["metadata"] = metadata
+            return method(request, **kwargs)
+        except grpc.RpcError as e:
+            self._handle_grpc_error(e)
+
+    def call_stream(
+        self,
+        method: Callable[..., Iterator[Any]],
+        request: Any,
+        on_progress: Callable[[ProgressEvent], None] | None = None,
+        deadline: float | None = None,
+        *,
+        metadata: Sequence[tuple[str, str | bytes]] | None = None,
+    ) -> ResultEnvelope:
+        """Call a server-streaming RPC with deadline."""
+        self._ensure_channel()
+        try:
+            kwargs: dict[str, Any] = {
+                "timeout": self.default_deadline if deadline is None else deadline,
+            }
+            if metadata is not None:
+                kwargs["metadata"] = metadata
+            stream = method(request, **kwargs)
+            try:
+                return consume_stream(stream, on_progress)
+            finally:
+                cancel = getattr(stream, "cancel", None)
+                if callable(cancel):
+                    cancel()
+        except grpc.RpcError as e:
+            self._handle_grpc_error(e)
+
+    def _handle_grpc_error(self, e: grpc.RpcError) -> NoReturn:
+        status = e.code()
+        message = e.details() or f"RPC error: {status}"
+        if status == grpc.StatusCode.DEADLINE_EXCEEDED:
+            raise DeadlineExceeded(message) from e
+        if status == grpc.StatusCode.CANCELLED:
+            raise Cancelled(message) from e
+        code = {
+            grpc.StatusCode.INVALID_ARGUMENT: ErrorCode.INVALID_REQUEST,
+            grpc.StatusCode.RESOURCE_EXHAUSTED: ErrorCode.RESOURCE_EXHAUSTED,
+            grpc.StatusCode.UNKNOWN: ErrorCode.PROVIDER_ERROR,
+            grpc.StatusCode.UNAVAILABLE: ErrorCode.PROVIDER_ERROR,
+        }.get(status, ErrorCode.INTERNAL)
+        raise ToolError(
+            code=code,
+            message=message,
+            retryable=status in (grpc.StatusCode.RESOURCE_EXHAUSTED, grpc.StatusCode.UNAVAILABLE),
+        ) from e
+
+
+# Process management for ensure_running
+_spawn_locks: dict[str, threading.Lock] = {}
+_spawn_locks_lock = threading.Lock()
+
+
+def get_spawn_lock(socket_path: str) -> threading.Lock:
+    with _spawn_locks_lock:
+        if socket_path not in _spawn_locks:
+            _spawn_locks[socket_path] = threading.Lock()
+        return _spawn_locks[socket_path]
+
+
+def ensure_running(
+    tool_name: str,
+    command: list[str],
+    socket_path: str,
+    timeout: float = 30.0,
+    env: dict[str, str] | None = None,
+    cwd: Path | None = None,
+) -> ToolClient:
+    """
+    Ensure tool server is running. Spawns if not healthy.
+    Uses a per-socket lock to avoid duplicate spawns.
+    """
+    client = ToolClient(socket_path)
+    if client.wait_healthy(timeout=2.0):
+        return client
+
+    lock = get_spawn_lock(socket_path)
+    with lock:
+        # Double-check after acquiring lock
+        if client.wait_healthy(timeout=2.0):
+            return client
+
+        # Spawn server
+        proc_env = os.environ.copy()
+        if env:
+            proc_env.update(env)
+        # On Windows, use CREATE_NEW_PROCESS_GROUP for proper termination
+        creationflags = 0
+        if sys.platform == "win32":
+            creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
+        proc = subprocess.Popen(
+            command,
+            env=proc_env,
+            cwd=cwd,
+            creationflags=creationflags,
+        )
+
+        # Wait for healthy
+        if not client.wait_healthy(timeout=timeout):
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+            raise RuntimeError(f"Tool {tool_name} failed to start within {timeout}s")
+
+    return client

mmo_runtime-0.1.3/src/mmo_runtime/config.py

@@ -0,0 +1,90 @@
+"""Configuration loading with precedence: defaults < yaml < env < CLI."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BaseServerConfig(BaseSettings):
+    """Base configuration for tool servers."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="TOOL_",
+        env_nested_delimiter="__",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Socket
+    socket_path: str = Field(
+        default_factory=lambda: "127.0.0.1:50051" if sys.platform == "win32" else "/tmp/tool.sock",
+        description="gRPC host:port or Unix domain socket path",
+    )
+    # Concurrency
+    max_concurrent_jobs: int = Field(default=1, ge=1, description="Max concurrent jobs")
+    max_queue_size: int = Field(default=4, ge=0, description="Max queued jobs (0 = no queue)")
+
+    @property
+    def thread_pool_size(self) -> int:
+        """Total thread pool size: workers + queue + buffer for health/gRPC internals."""
+        return self.max_concurrent_jobs + self.max_queue_size + 4
+
+    # Timeouts
+    idle_timeout_sec: int = Field(
+        default=300, ge=0, description="Idle timeout before shutdown (0 = disabled)"
+    )
+    job_timeout_sec: int = Field(default=0, ge=0, description="Per-job timeout (0 = no limit)")
+    # Device
+    device: str = Field(default="cpu", description="Compute device (cpu, cuda, mps, etc.)")
+    # Paths
+    runs_root: Path = Field(default=Path("runs"), description="Root directory for run outputs")
+    # Logging
+    log_level: str = Field(default="INFO", description="Log level")
+    log_json: bool = Field(default=False, description="Output JSON logs")
+
+    @field_validator("runs_root", mode="before")
+    @classmethod
+    def expand_runs_root(cls, v: str | Path) -> Path:
+        return Path(v).expanduser().resolve()
+
+    @field_validator("socket_path", mode="before")
+    @classmethod
+    def expand_socket_path(cls, v: str) -> str:
+        return os.path.expanduser(v)
+
+
+def load_config(
+    config_cls: type[BaseServerConfig],
+    yaml_path: Path | None = None,
+    cli_overrides: dict[str, Any] | None = None,
+) -> BaseServerConfig:
+    """
+    Load config with precedence: defaults < yaml < env < CLI.
+    """
+    yaml_data: dict[str, Any] = {}
+    if yaml_path and yaml_path.exists():
+        import yaml
+
+        with open(yaml_path) as f:
+            yaml_data = yaml.safe_load(f) or {}
+
+    # pydantic-settings ranks init kwargs above env vars, so yaml and CLI
+    # (both passed as init kwargs) would each beat env. To get yaml < env < CLI:
+    # drop yaml keys that the environment also provides; keep CLI keys so they
+    # win over env. Only flat (non-nested) yaml keys are env-matched.
+    cli = {k: v for k, v in (cli_overrides or {}).items() if v is not None}
+    merged: dict[str, Any] = {**yaml_data, **cli}
+
+    prefix = str(config_cls.model_config.get("env_prefix", ""))
+    env_keys = {k.upper() for k in os.environ}
+    for key in yaml_data:
+        if key not in cli and f"{prefix}{key}".upper() in env_keys:
+            merged.pop(key)
+
+    return config_cls(**merged)