nemo-platform-plugin 0.1.0__py3-none-any.whl

nemo_platform_plugin/schema.py

@@ -0,0 +1,216 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Plugin API schema interfaces — base classes for request/response models.
+
+Plugin authors import from here rather than ``nmp.common`` directly:
+
+    from nemo_platform_plugin.schema import NemoFilter, NemoListResponse, PaginationData
+
+Typical usage
+-------------
+
+**Single-resource response** (GET /{name}, POST, PATCH) — return entity objects directly::
+
+    from nemo_platform_plugin.entity import NemoEntity
+
+    class Widget(NemoEntity, entity_type="my_plugin_widget"):
+        colour: str
+        weight_kg: float = 0.0
+
+    # Entity objects are returned directly — no separate response class needed:
+    @router.post("/widgets", response_model=Widget, status_code=201)
+    async def create_widget(
+        workspace: str, body: CreateWidgetRequest,
+        entity_client: NemoEntitiesClient = Depends(get_entity_client),
+    ) -> Widget:
+        widget = Widget(name=body.name, workspace=workspace, colour=body.colour)
+        saved = await entity_client.create(widget)
+        return saved
+
+**List response** (GET /) — ``NemoListResponse[Widget]`` wraps the entity list::
+
+    from nemo_platform_plugin.schema import NemoFilter, NemoListResponse, PaginationData
+
+    class WidgetFilter(NemoFilter):
+        colour: str | None = None  # extra="forbid" inherited — typos → 422
+
+    WidgetPage = NemoListResponse[Widget]
+
+    @router.get("/widgets", response_model=WidgetPage)
+    async def list_widgets(...) -> WidgetPage:
+        result = await entity_client.list(Widget, workspace=workspace, ...)
+        pagination = (
+            PaginationData.model_validate(result.pagination.model_dump())
+            if result.pagination else None
+        )
+        return WidgetPage(data=result.data, pagination=pagination, sort=sort, filter=filter)
+
+**Request bodies** — plain Pydantic ``BaseModel``, no shared base::
+
+    from pydantic import BaseModel
+
+    class CreateWidgetRequest(BaseModel):
+        name: str
+        colour: str
+        weight_kg: float = 0.0
+
+    class UpdateWidgetRequest(BaseModel):
+        colour: str | None = None
+        weight_kg: float | None = None
+
+**Custom response models** — for non-CRUD endpoints or computed responses, use a
+plain ``BaseModel``::
+
+    from pydantic import BaseModel
+
+    class WidgetStatsResponse(BaseModel):
+        total: int
+        avg_weight_kg: float
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Generic, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+__all__ = [
+    "DatetimeFilter",
+    "Filter",
+    "NemoFilter",
+    "NemoListResponse",
+    "Page",
+    "PaginationData",
+    "Value",
+]
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class Value(BaseModel):
+    """The base class for all value types.
+
+    This also helps avoid confusion since Model and BaseModel in Pydantic
+    mean something different.
+    """
+
+    model_config = {"arbitrary_types_allowed": True, "protected_namespaces": ()}
+
+
+class PaginationData(Value):
+    page: int = Field(description="The current page number.")
+    page_size: int = Field(description="The page size used for the query.")
+    current_page_size: int = Field(description="The size for the current page.")
+    total_pages: int = Field(description="The total number of pages.")
+    total_results: int = Field(description="The total number of results.")
+
+
+class Filter(BaseModel):
+    """Base class for filter schemas.
+
+    We don't allow extra fields because filtering on the wrong property
+    (e.g., spelling error) would fail silently.
+    """
+
+    model_config = ConfigDict(extra="forbid", protected_namespaces=())
+
+    @model_validator(mode="before")
+    @classmethod
+    def skip_validation_on_raw_objects(cls, data: Any) -> Any:
+        if isinstance(data, dict) and data.get("*"):
+            data = {}
+        return data
+
+
+NemoFilter = Filter
+
+
+class NemoListResponse(BaseModel, Generic[T]):
+    """Paginated list response envelope.
+
+    Wire format is identical to the ``nmp_common`` ``Page`` envelope used
+    by all core NeMo Platform services::
+
+        {
+            "data": [...],
+            "pagination": {
+                "page": 1,
+                "page_size": 20,
+                "current_page_size": 5,
+                "total_pages": 1,
+                "total_results": 5
+            },
+            "sort": "-created_at",
+            "filter": {"colour": "red"}
+        }
+
+    Usage::
+
+        WidgetPage = NemoListResponse[Widget]
+
+        @router.get("/widgets", response_model=WidgetPage)
+        async def list_widgets(
+            workspace: str,
+            page: int = Query(default=1, ge=1),
+            page_size: int = Query(default=20, ge=1, le=100),
+            sort: str = Query(default="-created_at"),
+            filter: WidgetFilter = Depends(make_filter_dep(WidgetFilter)),
+            entity_client: NemoEntitiesClient = Depends(get_entity_client),
+        ) -> WidgetPage:
+            result = await entity_client.list(
+                Widget, workspace=workspace,
+                page=page, page_size=page_size, sort=sort, filter=filter,
+            )
+            pagination = (
+                PaginationData.model_validate(result.pagination.model_dump())
+                if result.pagination else None
+            )
+            return WidgetPage(data=result.data, pagination=pagination, sort=sort, filter=filter)
+    """
+
+    data: list[T]
+    pagination: PaginationData | None = Field(
+        default=None,
+        description="Pagination metadata — page, page_size, total_results, etc.",
+    )
+    sort: str | None = Field(
+        default=None,
+        description="Sort field applied to this result set (e.g. '-created_at').",
+    )
+    filter: Any = Field(
+        default=None,
+        description="Filter criteria echoed back from the request.",
+    )
+
+
+EntityT = TypeVar("EntityT")
+
+
+class Page(Value, Generic[EntityT]):
+    data: list[EntityT]
+    pagination: Optional[PaginationData] = Field(default=None, description="Pagination information.")
+    sort: Optional[str] = Field(default=None, description="The field on which the results are sorted.")
+    filter: Optional[dict] = Field(default=None, description="Filtering information.")
+
+
+class DatetimeFilter(Filter):
+    gte: Optional[datetime] = Field(
+        None,
+        alias="$gte",
+        serialization_alias="$gte",
+        description="Filter for results greater than or equal to this datetime.",
+    )
+    lte: Optional[datetime] = Field(
+        None,
+        alias="$lte",
+        serialization_alias="$lte",
+        description="Filter for results less than or equal to this datetime.",
+    )
+
+    model_config = ConfigDict(
+        extra="forbid",
+        protected_namespaces=(),
+        populate_by_name=True,
+    )

nemo_platform_plugin/sdk.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Plugin SDK resource container."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from nemo_platform import AsyncNeMoPlatform, NeMoPlatform
+
+SyncResourceT = TypeVar("SyncResourceT")
+AsyncResourceT = TypeVar("AsyncResourceT")
+
+
+@dataclass(frozen=True, slots=True)
+class NemoPluginSDKResources(Generic[SyncResourceT, AsyncResourceT]):
+    """Container for plugin SDK resources exposed on platform clients."""
+
+    sync_resource: Callable[[NeMoPlatform], SyncResourceT] | None = None
+    async_resource: Callable[[AsyncNeMoPlatform], AsyncResourceT] | None = None
+
+    def __post_init__(self) -> None:
+        if self.sync_resource is None and self.async_resource is None:
+            raise ValueError("At least one of sync_resource or async_resource must be provided")
+
+
+__all__ = [
+    "AsyncNeMoPlatform",
+    "NeMoPlatform",
+    "NemoPluginSDKResources",
+]

nemo_platform_plugin/seed.py

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Plugin seed interface — what plugin authors implement for platform seeding.
+
+Plugin authors subclass :class:`NemoSeedJob` and register the class under the
+``nemo.seed`` entry-point group. The platform calls :meth:`run` when services
+start up. This is useful to automatically create entities that should always
+exist in the system.
+
+An `AsyncNeMoPlatform` SDK instance and a `NemoEntitiesClient` instance are available as
+attributes on every `NemoSeedJob` instance. Any services called with these objects
+must be running and responding to requests; to indicate these services are
+required, add them to the `dependencies` ClassVar.
+
+Seed jobs are executed every time the services are restarted, so job implementations
+MUST be idempotent.
+
+Example::
+
+    # my_plugin/seed.py
+    from nemo_platform_plugin.entity_client import NemoEntityConflictError
+    from nemo_platform_plugin.seed import NemoSeedJob
+
+    _SEEDED_ITEM_NAME = "foo"
+
+    class MySeedJob(NemoSeedJob):
+        name = "my-plugin"
+        dependencies = ["entities"]
+
+        async def run(self) -> None:
+            item = MyPluginItem(name=_SEEDED_ITEM_NAME)
+            try:
+                await self.entities_client.create(item)
+                logger.info("Created example seed entity %r", _SEEDED_ITEM_NAME)
+            except NemoEntityConflictError:
+                logger.debug("Example seed entity %r already exists", _SEEDED_ITEM_NAME)
+
+
+    # pyproject.toml:
+    # [project.entry-points."nemo.seed"]
+    # my-plugin = "my_plugin.seed:MySeedJob"
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import ClassVar
+
+from nemo_platform_plugin._base import _NamedPlugin
+from nemo_platform_plugin.entity_client import NemoEntitiesClient
+from nemo_platform_plugin.sdk import AsyncNeMoPlatform
+
+
+class NemoSeedJob(_NamedPlugin):
+    """Abstract base class for plugin-contributed seed jobs.
+
+    The platform instantiates subclasses, injects ``sdk`` and ``entities_client``,
+    then awaits :meth:`run`.
+    """
+
+    name: ClassVar[str]
+    description: ClassVar[str] = ""
+    dependencies: ClassVar[list[str]] = []
+
+    sdk: AsyncNeMoPlatform
+    entities_client: NemoEntitiesClient
+
+    @abstractmethod
+    async def run(self) -> None:
+        """Execute the seed job. Implementations must be idempotent."""

nemo_platform_plugin/service.py

@@ -0,0 +1,130 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Plugin service interface — what plugin authors implement.
+
+Plugin authors subclass :class:`NemoService` and register a module-level
+instance under the ``nemo.services`` entry-point group.  The platform wraps
+each instance in a :class:`NemoServiceAdapter` at startup so it can be
+treated as a first-class internal :class:`~nmp.common.service.Service`.
+
+Example::
+
+    # my_plugin/service.py
+    from fastapi import APIRouter
+    from nemo_platform_plugin.service import NemoService, RouterSpec
+
+    class MyService(NemoService):
+        name = "my-plugin"
+        dependencies = ["entities"]
+
+        def get_routers(self) -> list[RouterSpec]:
+            router = APIRouter()
+
+            @router.get("/health")
+            async def health() -> dict[str, str]:
+                return {"status": "ok"}
+
+            return [RouterSpec(router, tag="My Plugin")]
+
+    # pyproject.toml:
+    # [project.entry-points."nemo.services"]
+    # my-plugin = "my_plugin.service:MyService"
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from fastapi import APIRouter
+from nemo_platform_plugin._base import _NamedPlugin
+from starlette.requests import Request
+from starlette.responses import Response
+
+ExceptionHandler = Callable[[Request, Exception], Response | Awaitable[Response]]
+
+
+@dataclass
+class RouterSpec:
+    """Minimal router descriptor contributed by a plugin.
+
+    The platform adapter converts this to its internal ``RouterConfig`` at
+    startup.  Plugin authors never import ``RouterConfig`` directly.
+
+    Attributes:
+        router: The FastAPI router to mount.
+        tag: OpenAPI tag grouping.  Defaults to the plugin name if left empty.
+        description: Human-readable description shown in the OpenAPI docs.
+        prefix: URL prefix appended after ``/apis/<plugin-name>``.  Rarely
+            needed — leave empty unless you have multiple routers with
+            overlapping paths.
+    """
+
+    router: APIRouter
+    tag: str = field(default="")
+    description: str = field(default="")
+    prefix: str = field(default="")
+
+
+class NemoService(_NamedPlugin):
+    """Abstract base class for plugin-contributed services.
+
+    Subclasses declare their identity via class variables and implement
+    :meth:`get_routers`.  The platform instantiates and wraps them at
+    startup — plugin authors do not call the platform directly.
+
+    Class variables:
+
+    .. attribute:: name
+        :type: str
+
+        Unique kebab-case service name.  Must match the ``nemo.services``
+        entry-point key and becomes the URL prefix (``/apis/<name>``).
+
+    .. attribute:: dependencies
+        :type: list[str]
+
+        Names of platform services that must start before this one.
+        Defaults to ``[]``.
+    """
+
+    name: ClassVar[str]
+    dependencies: ClassVar[list[str]] = []
+
+    @abstractmethod
+    def get_routers(self) -> list[RouterSpec]:
+        """Return the routers this service contributes.
+
+        Each :class:`RouterSpec` is mounted at ``/apis/<name>/<spec.prefix>``.
+        """
+
+    async def on_startup(self) -> None:
+        """Called at platform startup before the HTTP server accepts requests.
+
+        Override for custom initialisation (e.g. connecting to a database).
+        The default implementation does nothing.
+        """
+
+    async def on_shutdown(self) -> None:
+        """Called at platform shutdown after requests stop being served.
+
+        Override for cleanup (e.g. closing connections).
+        The default implementation does nothing.
+        """
+
+    def get_exception_handlers(self) -> dict[type[Exception], ExceptionHandler]:
+        """Return a mapping of exception types to handler functions.
+
+        Each handler receives ``(request, exc)`` and must return a
+        :class:`~starlette.responses.Response` (sync or async).
+
+        The platform registers these on the service's FastAPI app so that
+        unhandled exceptions of the given types are caught and converted to
+        appropriate HTTP responses.
+
+        Default returns an empty dict.
+        """
+        return {}

nemo_platform_plugin/tasks/dispatcher.py

@@ -0,0 +1,226 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Task entrypoint dispatcher for :class:`~nemo_platform_plugin.job.NemoJob` subclasses.
+
+Mirrors :meth:`~nemo_platform_plugin.scheduler.NemoJobScheduler.run_local` for any
+process the platform spawns with the ``NEMO_JOB_*`` environment populated —
+both Docker-backed task containers and host subprocess executors land here.
+Reads the step config from the platform-injected file path, builds a
+:class:`~nemo_platform_plugin.job_context.JobContext` from the environment, and
+invokes ``job.run(...)`` with the same signature-based DI used locally
+(see :func:`~nemo_platform_plugin.run_dependencies.resolve_run_kwargs`).
+
+Because ``run_task`` only runs inside a platform-spawned process, the
+default ``ctx.results`` is :class:`~nemo_platform_plugin.job_results.PlatformJobResults`
+— results upload through the Files service whether the deployment is
+docker-backed or subprocess-on-local-host. Storage backend (local FS, S3,
+…) is the Files service's concern, not the plugin's. Plugins that need a
+different sink build a :class:`JobContext` and pass it via ``ctx=``.
+
+Usage from a plugin's ``__main__.py``::
+
+    import signal
+    import sys
+    from types import FrameType
+
+    from nemo_platform_plugin.tasks.dispatcher import run_task
+    from nmp.common.sdk_factory import get_task_sdk
+    from my_plugin.jobs.train import TrainJob
+
+
+    def _shutdown(signum: int, _frame: FrameType | None) -> None:
+        raise SystemExit(128 + signum)
+
+
+    if __name__ == "__main__":
+        signal.signal(signal.SIGTERM, _shutdown)
+        sys.exit(run_task(TrainJob, sdk=get_task_sdk("my-service")))
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from nemo_platform_plugin.job import NemoJob
+from nemo_platform_plugin.job_context import JobContext, StoragePaths
+from nemo_platform_plugin.job_results import PlatformJobResults
+from nemo_platform_plugin.jobs.constants import (
+    EPHEMERAL_TASK_STORAGE_PATH_ENVVAR,
+    NEMO_JOB_ID_ENVVAR,
+    NEMO_JOB_STEP_CONFIG_FILE_PATH_ENVVAR,
+    NEMO_JOB_WORKSPACE_ENVVAR,
+    PERSISTENT_JOB_STORAGE_PATH_ENVVAR,
+)
+from nemo_platform_plugin.run_dependencies import LocalRunError, resolve_run_kwargs
+
+logger = logging.getLogger(__name__)
+
+
+def run_task(
+    job_cls: type[NemoJob],
+    *,
+    sdk: Any | None = None,
+    async_sdk: Any | None = None,
+    ctx: JobContext | None = None,
+) -> int:
+    """Run *job_cls* in a platform-spawned task process; return a process exit code.
+
+    Reads the step config from :data:`NEMO_JOB_STEP_CONFIG_FILE_PATH_ENVVAR`,
+    builds a :class:`JobContext` from the platform-injected env when *ctx* is
+    omitted, and invokes ``job.run(config, **kwargs)`` with signature DI of
+    ``ctx`` / ``sdk`` / ``async_sdk``. Exit codes follow :func:`_exit_code_for`;
+    :class:`~nemo_platform_plugin.run_dependencies.LocalRunError` propagates verbatim.
+
+    The auto-built ``ctx`` wires
+    :class:`~nemo_platform_plugin.job_results.PlatformJobResults` as ``ctx.results``,
+    so *sdk* is required when *ctx* is not supplied.
+
+    Args:
+        job_cls: The :class:`~nemo_platform_plugin.job.NemoJob` subclass to run.
+        sdk: :class:`~nemo_platform.NeMoPlatform` handle, typically built via
+            ``get_task_sdk("<plugin>")`` so ``NMP_PRINCIPAL`` threads through
+            as on-behalf-of auth. Required unless *ctx* is supplied.
+        async_sdk: Async SDK counterpart for jobs that delegate to async helpers.
+        ctx: Override for the auto-built :class:`JobContext` — used to inject
+            a non-default ``results`` sink (e.g. :class:`LocalJobResults` for
+            offline runs).
+
+    Returns:
+        Process exit code suitable for :func:`sys.exit`.
+    """
+    try:
+        config = _read_step_config()
+    except Exception:
+        logger.exception("Failed to read step config")
+        return 2
+
+    if ctx is None:
+        if sdk is None:
+            logger.error(
+                "%s.run_task requires sdk= when no explicit ctx is provided (default ctx wires PlatformJobResults).",
+                job_cls.__name__,
+            )
+            return 2
+        try:
+            ctx = _build_ctx_from_env(sdk)
+        except Exception:
+            logger.exception("Failed to build JobContext from environment")
+            return 2
+
+    try:
+        job = job_cls()
+    except Exception:
+        # Constructor failures are setup errors, not run errors — surface as 2.
+        logger.exception("Failed to instantiate %s", job_cls.__name__)
+        return 2
+
+    try:
+        kwargs = resolve_run_kwargs(job_cls, job.run, sdk=sdk, async_sdk=async_sdk, ctx=ctx, is_local=False)
+    except LocalRunError:
+        # Plugin-author bug (e.g. required sdk param without a handle); propagate
+        # rather than collapse into the same exit-2 bucket as a missing env var.
+        raise
+    except Exception:
+        logger.exception("Failed to resolve run kwargs for %s", job_cls.__name__)
+        return 2
+
+    try:
+        result = job.run(config, **kwargs)
+    except LocalRunError:
+        # Propagate verbatim per run_task's contract.
+        raise
+    except Exception:
+        logger.exception("%s.run raised", job_cls.__name__)
+        return 1
+
+    logger.info("%s result: %s", job_cls.__name__, result)
+    return _exit_code_for(result)
+
+
+def _exit_code_for(result: Any) -> int:
+    """Map a ``NemoJob.run`` return value to a process exit code.
+
+    Recognises two in-tree failure shapes — ``{"status": "failed", ...}``
+    and ``{"exit_code": <non-zero>, ...}`` — and treats ``None`` as failure
+    (likely a missing ``return``).  Anything else is success.
+    """
+    if result is None:
+        logger.warning("Job returned None; treating as failure")
+        return 1
+    if not isinstance(result, dict):
+        return 0
+    if result.get("status") == "failed":
+        return 1
+    exit_code = result.get("exit_code")
+    if isinstance(exit_code, int) and exit_code != 0:
+        return 1
+    return 0
+
+
+def _read_step_config() -> dict:
+    path_str = os.environ.get(NEMO_JOB_STEP_CONFIG_FILE_PATH_ENVVAR)
+    if not path_str:
+        raise RuntimeError(f"{NEMO_JOB_STEP_CONFIG_FILE_PATH_ENVVAR} not set; running outside the platform?")
+    path = Path(path_str)
+    if not path.exists():
+        raise FileNotFoundError(f"Step config not found at {path}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        # JSONDecodeError already carries line/column. The byte count is for
+        # diagnosing empty or truncated platform-written config files.
+        try:
+            size = path.stat().st_size
+        except OSError:
+            size_text = "unknown size"
+        else:
+            size_text = f"{size} bytes"
+        raise RuntimeError(f"Invalid JSON in step config at {path} ({size_text})") from exc
+    if not isinstance(data, dict):
+        raise RuntimeError(f"Step config at {path} must be a JSON object, got {type(data).__name__}")
+    return data
+
+
+def _build_ctx_from_env(sdk: Any) -> JobContext:
+    """Build a :class:`JobContext` from the platform-injected ``NEMO_JOB_*`` env.
+
+    Wires :attr:`JobContext.results` to :class:`PlatformJobResults` so results
+    upload through the Files service — works the same in docker-backed and
+    subprocess-on-local-host deployments. Each ``NEMO_JOB_*`` envvar is required;
+    a missing one raises rather than silently falling back to a path that only
+    exists inside task containers.
+
+    ``PlatformJobResults.job_name`` is the *submitted* platform job name, not
+    the job class name — :class:`~nemo_platform_plugin.jobs.result_manager.ResultManager`
+    uses it to look up the job via ``jobs_sdk.jobs.retrieve`` so each
+    ``ctx.results.save()`` registers against the correct job record. The
+    backends inject this as ``NEMO_JOB_ID = step.job``; the NemoJob class
+    identifier (e.g. ``"evaluate"``) would point at a non-existent job and
+    break result registration.
+    """
+    workspace = os.environ.get(NEMO_JOB_WORKSPACE_ENVVAR, "").strip()
+    if not workspace:
+        raise RuntimeError(f"{NEMO_JOB_WORKSPACE_ENVVAR} not set; running outside the platform?")
+    persistent_str = os.environ.get(PERSISTENT_JOB_STORAGE_PATH_ENVVAR)
+    if not persistent_str:
+        raise RuntimeError(f"{PERSISTENT_JOB_STORAGE_PATH_ENVVAR} not set; running outside the platform?")
+    ephemeral_str = os.environ.get(EPHEMERAL_TASK_STORAGE_PATH_ENVVAR)
+    if not ephemeral_str:
+        raise RuntimeError(f"{EPHEMERAL_TASK_STORAGE_PATH_ENVVAR} not set; running outside the platform?")
+    job_id = os.environ.get(NEMO_JOB_ID_ENVVAR, "").strip()
+    if not job_id:
+        raise RuntimeError(f"{NEMO_JOB_ID_ENVVAR} not set; running outside the platform?")
+    return JobContext(
+        workspace=workspace,
+        storage=StoragePaths(ephemeral=Path(ephemeral_str), persistent=Path(persistent_str)),
+        results=PlatformJobResults(job_name=job_id, workspace=workspace, sdk=sdk),
+        job_id=job_id,
+    )
+
+
+__all__ = ["run_task"]