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

nemo_platform_plugin/docs/ARCHITECTURE.md

@@ -0,0 +1,160 @@
+# NeMo Platform Plugin Architecture
+
+## Surfaces and entry-point groups
+
+Every plugin capability is a "surface" — a typed contract registered via a Python entry-point group. The platform discovers all surfaces at startup by scanning these groups.
+
+| Surface | Entry-point group | Base class | URL / mount point | Platform action |
+|---|---|---|---|---|
+| **HTTP service** ★ | `nemo.services` | `NemoService` | `/apis/<name>/...` | wraps in `NemoServiceAdapter`, mounts FastAPI router |
+| **CLI** ★ | `nemo.cli` | `NemoCLI` | `nemo <name> <cmd>` | calls `get_cli()`, mounts as Typer subcommand |
+| **Job** ★ | `nemo.jobs` | `NemoJob` | key: `<plugin>.<job>` | auto-generates `run` / `submit` / `explain` CLI verbs; the scheduler drives local runs and remote submission |
+| **Controller** ★ | `nemo.controllers` | `NemoController` | (background) | wraps in `NemoControllerAdapter`, runs reconcile loop |
+| SDK | `nemo.sdk` | (any class) | `nemo.<name>` on hub | instantiated as attribute on the `NeMo` hub |
+| MCP | `nemo.mcp` | `() -> list[dict]` | (MCP tool list) | returns MCP tool definitions |
+| Studio | `nemo.studio` | `() -> StudioSpec` | (UI page spec) | returns Studio web-UI page spec |
+| Skills | `nemo.skills` | `() -> Path` | (skill files) | returns path to agent skill markdown files |
+| Docs | `nemo.docs` | `() -> Path \| dict` | (docs path) | returns path to plugin documentation |
+| Executors | `nemo.executors` | Executor class | kind: `slurm`, `k8s`... | resolved by job scheduler cluster kind |
+
+★ = Primary surfaces; most plugins implement one or more of these four.
+
+## Discovery
+
+`discover(group)` scans `importlib.metadata` entry-points for the given group, loads each value (the class), and caches results per-group for the process lifetime. Fault-isolated: a broken plugin logs a warning and is skipped; all others load normally.
+
+Platform wraps each surface:
+- `NemoService` → `NemoServiceAdapter` → `FastAPI app.include_router`
+- `NemoCLI` → `get_cli()` → Typer subcommand
+- `NemoJob` → job scheduler
+- `NemoController` → `NemoControllerAdapter` → async reconcile loop
+
+## Startup sequence
+
+1. `NMP_SERVICES` env var consulted — if set, only listed services start
+2. All `NemoService.dependencies` are resolved — verify deps are available
+3. Each service's `on_startup()` called and **awaited** in dependency order
+4. FastAPI routes mounted at `/apis/<name>/...`
+5. `NemoController` instances start their reconcile loops — services are fully started by this point, so controller `on_startup()` can safely call entity store APIs
+6. `NemoJob` classes registered in the job scheduler
+
+## The `name` rule
+
+`_NamedPlugin.__init_subclass__` runs at class-definition time. It checks that every concrete subclass declares a non-empty `name: ClassVar[str]`.
+
+The `name` must **exactly match** the entry-point key in `pyproject.toml`. A mismatch logs a warning at startup — the entry-point key always wins for routing:
+
+```
+nemo.services entry 'my-plugin': class MyService declares name='my_plugin' —
+name must match the pyproject.toml entry-point key
+```
+
+## URL routing
+
+Formula: `/apis/<name>/<spec.prefix>/<route-path>`
+
+Platform convention: `/apis/<name>/v2/workspaces/{workspace}/<resource>`
+
+Plugin services should follow the same convention for consistency.
+
+## Job entry-point keys
+
+Job entry-point keys use a dot separator: `<plugin-name>.<job-name>`.
+
+`NemoJob.name` must equal the suffix after the first dot:
+
+```toml
+"example.say-hello" = "nemo_example_plugin.jobs.say_hello:SayHelloJob"
+```
+
+```python
+class SayHelloJob(NemoJob):
+    name = "say-hello"   # suffix only
+```
+
+Dispatch programmatically:
+
+```python
+from nemo_platform_plugin.discovery import discover_jobs
+from nemo_platform_plugin.scheduler import NemoJobScheduler
+
+job_cls = discover_jobs()["example.say-hello"]
+NemoJobScheduler().run_local(job_cls, {"name": "Alice"})
+```
+
+## Auto-generated three-verb CLI for jobs
+
+At startup, for every plugin that registers both `nemo.cli` and `nemo.jobs`, the platform injects three CLI subcommands per job into the plugin's Typer group: `run`, `submit`, `explain`. Plugin authors write no CLI code for their jobs.
+
+- `run` delegates to `NemoJobScheduler.run_local` — in-process, no platform.
+- `submit` delegates to `NemoJobScheduler.submit_remote` — POSTs to the plugin service's per-job endpoint; the cluster executes.
+- `explain` delegates to `NemoJobScheduler.explain` — reads schemas locally from the `NemoJob` class.
+
+Plugin services mount the matching POST/GET/LIST/DELETE endpoints with the `add_job_routes(job_cls)` helper from `nemo_platform_plugin.jobs.routes` — a one-liner that replaces the multi-arg `job_route_factory(...)` pattern.
+
+## Plugin manifests
+
+`discover_manifests()` assembles a `PluginManifest` (name, version, description) per installed plugin by scanning surface groups — no `nemo.plugins` group needed.
+
+## Test isolation
+
+`discover()` and `discover_entry_points()` are `@functools.cache`d per group for the process lifetime. Tests that mock entry-points must clear both caches. This is **mandatory, not optional** — stale cache state causes tests to interfere with each other:
+
+```python
+import pytest
+from nemo_platform_plugin.discovery import discover, discover_entry_points, discover_manifests
+
+@pytest.fixture(autouse=True)
+def clear_discovery_cache():
+    yield
+    discover.cache_clear()
+    discover_entry_points.cache_clear()
+    discover_manifests.cache_clear()
+```
+
+## Inter-service auth headers
+
+Every inter-service call carries principal headers. The NeMo Platform SDK factory handles this automatically. Four headers used in NeMo Platform:
+
+| Header | Value |
+|---|---|
+| `X-NMP-Principal-Id` | `user@example.com` or `service:my-plugin` |
+| `X-NMP-Principal-Email` | `user@example.com` |
+| `X-NMP-Principal-Groups` | `group1,group2` |
+| `X-NMP-Principal-On-Behalf-Of` | `user@example.com` (when a service acts for a user) |
+
+For the controller service-principal pattern, see [CONTROLLER.md](CONTROLLER.md).
+
+## SDK Surface
+
+`nemo.sdk` adds a `nemo.<name>` Python attribute on the `NeMo` hub — for Jupyter notebooks and scripts, not platform runtime.
+
+No abstract base class. Requirements:
+- `__init__(self, platform: Any)` — `platform.base_url` provides the service URL
+- Use synchronous `httpx.Client` (scripting contexts may have no event loop)
+- Sub-resources via lazy `@property`
+- `resp.raise_for_status()` — let `httpx.HTTPStatusError` propagate
+
+```python
+from typing import Any
+import httpx
+
+class MyResource:
+    def __init__(self, platform: Any) -> None:
+        self._platform = platform
+
+    def _base_url(self) -> str:
+        return str(getattr(self._platform, "base_url", "http://localhost:8000")).rstrip("/")
+
+    def create(self, *, name: str, workspace: str = "default") -> dict:
+        with httpx.Client(timeout=30) as client:
+            resp = client.post(
+                self._base_url() + f"/apis/my-plugin/v2/workspaces/{workspace}/items",
+                json={"name": name},
+            )
+            resp.raise_for_status()
+            return resp.json()
+```
+
+Entry-point: `[project.entry-points."nemo.sdk"]`
+Hub usage: `nemo = NeMo(base_url="http://localhost:8080"); nemo.my_plugin.create(name="x")`

nemo_platform_plugin/docs/CONFIG.md

@@ -0,0 +1,151 @@
+# Plugin Configuration (NemoConfig)
+
+## NemoConfig
+
+`NemoConfig` is a `pydantic-settings` base class that wires your plugin's typed configuration to environment variables and the platform YAML config file.
+
+Class signature:
+```python
+class NemoConfig(EnvironmentFirstSettings, metaclass=_NemoConfigMeta):
+    plugin_name: ClassVar[str]           # REQUIRED — kebab-case (matches CLI entry-point key)
+    plugin_description: ClassVar[str]    # REQUIRED — non-empty string
+
+    @classmethod
+    def get(cls) -> Self: ...            # returns cached singleton
+```
+
+Both `plugin_name` and `plugin_description` must be declared in the concrete subclass body. Omitting either raises `TypeError` at class-definition time.
+
+## Defining a config class
+
+```python
+from typing import ClassVar, Literal
+from pydantic import Field
+from nemo_platform_plugin.config import NemoConfig
+
+class ExampleConfig(NemoConfig):
+    plugin_name: ClassVar[str] = "example"
+    plugin_description: ClassVar[str] = "Configuration for the NeMo Platform example plugin."
+
+    greeting_style: Literal["formal", "casual"] = Field(
+        default="formal",
+        description="Controls the tone of /hello/{name} responses.",
+    )
+    log_requests: bool = Field(
+        default=False,
+        description="When True, emits structured INFO log for list endpoint calls.",
+    )
+```
+
+## Environment variables
+
+Env var formula: `NMP_<SAFE_NAME>_<FIELD>` where `SAFE_NAME = plugin_name.upper()` with non-word characters replaced by `_`.
+
+| `plugin_name` | Env prefix | Example field | Env var |
+|---|---|---|---|
+| `"my-plugin"` | `NMP_MY_PLUGIN_` | `debug` | `NMP_MY_PLUGIN_DEBUG` |
+| `"agents"` | `NMP_AGENTS_` | `runner_backend` | `NMP_AGENTS_RUNNER_BACKEND` |
+| `"example"` | `NMP_EXAMPLE_` | `greeting_style` | `NMP_EXAMPLE_GREETING_STYLE` |
+
+Nested fields use `_` as the delimiter:
+
+```bash
+NMP_AGENTS_CONTROLLER_INTERVAL_SECONDS=10
+NMP_AGENTS_CONTROLLER_PORT_RANGE_START=49152
+```
+
+## Config file
+
+The config key in `/etc/nmp/config.yaml` matches `plugin_name`:
+
+```yaml
+my_plugin:
+  debug: true
+  max_workers: 8
+```
+
+Override the config file path: `NMP_CONFIG_FILE_PATH=/my/custom/config.yaml`
+
+The platform logs a warning (not an error) when `/etc/nmp/config.yaml` does not exist. Defaults apply — expected for local development.
+
+## Priority order
+
+1. **Environment variables** (`NMP_<NAME>_<FIELD>`) — highest priority
+2. **Config file** (`/etc/nmp/config.yaml`)
+3. **Field defaults** — lowest priority
+
+## Accessing config
+
+```python
+# Option 1: classmethod (returns cached singleton — same instance every call)
+from nemo_my_plugin.config import MyPluginConfig
+config = MyPluginConfig.get()
+
+# Option 2: standalone function
+from nemo_platform_plugin.config import get_nemo_config
+config = get_nemo_config(MyPluginConfig)
+```
+
+## Nested config models
+
+Use a plain `BaseModel` (NOT `NemoConfig`) for nested config sections. `NemoConfig` is only for the top-level class.
+
+```python
+from typing import ClassVar
+from pydantic import BaseModel, Field
+from nemo_platform_plugin.config import NemoConfig
+
+class ControllerConfig(BaseModel):  # plain BaseModel — NOT NemoConfig
+    interval_seconds: int = Field(default=5)
+    health_check_timeout_seconds: int = Field(default=120)
+
+class AgentsConfig(NemoConfig):
+    plugin_name: ClassVar[str] = "agents"
+    plugin_description: ClassVar[str] = "Configuration for the NeMo Platform agents plugin."
+
+    controller: ControllerConfig = Field(default_factory=ControllerConfig)
+    runner_backend: str = Field(default="in_memory")
+
+# Access nested field:
+config = AgentsConfig.get()
+interval = config.controller.interval_seconds  # NMP_AGENTS_CONTROLLER_INTERVAL_SECONDS
+```
+
+## Testing
+
+```python
+import pytest
+from nemo_platform_plugin.config import (
+    set_nemo_config_override,
+    clear_nemo_config_override,
+    clear_nemo_config_overrides,
+)
+from nemo_my_plugin.config import MyPluginConfig
+
+# Per-test override with manual cleanup:
+def test_debug_mode():
+    set_nemo_config_override(MyPluginConfig(debug=True))
+    try:
+        config = MyPluginConfig.get()
+        assert config.debug is True
+    finally:
+        clear_nemo_config_override(MyPluginConfig)
+
+# Recommended: autouse fixture that clears all overrides after every test:
+@pytest.fixture(autouse=True)
+def reset_config():
+    yield
+    clear_nemo_config_overrides()
+```
+
+Three cleanup functions:
+- `clear_nemo_config_override(cls)` — removes override for one config class
+- `clear_nemo_config_overrides()` — removes ALL overrides (all config classes)
+
+## Common mistakes
+
+1. **`plugin_name` in snake_case** — use kebab-case to match your CLI entry-point key (e.g., `plugin_name = "my-plugin"`). The env prefix is derived by uppercasing and replacing `-` with `_`: `NMP_MY_PLUGIN_*`. Your YAML config key should also use `my-plugin:`.
+
+2. **Calling `MyPluginConfig()` directly in production code** — bypasses env/file loading entirely. Always use `MyPluginConfig.get()` or `get_nemo_config(MyPluginConfig)`.
+
+3. **Forgetting cleanup in tests** — config is cached; a test override bleeds into subsequent tests unless cleaned up. Use the autouse fixture pattern above.

nemo_platform_plugin/docs/CONTROLLER.md

@@ -0,0 +1,209 @@
+# Controller Surface (NemoController)
+
+## NemoController
+
+```python
+from nemo_platform_plugin.controller import NemoController
+
+class NemoController(_NamedPlugin):
+    name: ClassVar[str]                    # REQUIRED — kebab-case; matches entry-point key
+    dependencies: ClassVar[list[str]] = [] # platform services to wait for before startup
+
+    # Must implement:
+    @abstractmethod
+    async def list_objects(self) -> list: ...
+    # Called once per cycle. Return all objects to reconcile.
+
+    @abstractmethod
+    async def reconcile_one(self, obj: object) -> None: ...
+    # Called for each item from list_objects(). Errors are caught per-item.
+
+    # May override:
+    async def reconcile(self) -> None: ...          # default: list → reconcile_one each
+    async def on_startup(self) -> None: ...         # called once before first cycle
+    async def on_shutdown(self) -> None: ...        # called after last cycle
+    @property
+    def is_healthy(self) -> bool: ...               # health check (default: True)
+    @property
+    def interval_seconds(self) -> float: ...        # default: 10.0
+```
+
+## Lifecycle
+
+```
+Platform startup
+    ↓
+NemoControllerAdapter wraps NemoController instance
+    ↓
+on_startup() — load config, build entity client, initialize backends
+    ↓
+Loop begins (runs every interval_seconds):
+    reconcile()
+        → list_objects()        — fetch entities from store
+        → reconcile_one(obj)    — per-item, with error isolation
+    ↓
+SIGINT/SIGTERM received
+    → platform sets stop signal
+    → waits for current reconcile() to complete
+    → on_shutdown()
+```
+
+## Initialization
+
+`__init__()` must **only** set attributes to `None`. The platform is not ready at class-definition time — all async initialization must happen in `on_startup()`.
+
+```python
+class MyController(NemoController):
+    name = "my-controller"
+
+    def __init__(self) -> None:
+        self._entities: NemoEntitiesClient | None = None
+        self._interval_seconds: float = 10.0
+
+    @property
+    def entities(self) -> NemoEntitiesClient:
+        if self._entities is None:
+            raise RuntimeError("entities accessed before on_startup()")
+        return self._entities
+```
+
+## internal=True — why it's required
+
+Without `internal=True`, controller polling floods the entity store's access log — omit it and the store logs every cycle.
+
+```python
+async def on_startup(self) -> None:
+    from nmp.common.sdk_factory import get_async_platform_sdk
+    from nemo_platform.resources.entities import AsyncEntitiesResource
+    from nemo_platform_plugin.entity_client import NemoEntitiesClient
+
+    sdk = get_async_platform_sdk(as_service="my-controller", internal=True)
+    self._entities = NemoEntitiesClient(AsyncEntitiesResource(sdk))
+```
+
+`as_service="my-controller"` sets `X-NMP-Principal-Id: service:my-controller`, granting the service principal access needed to list entities across all workspaces.
+
+## Cross-workspace listing
+
+Controllers typically reconcile all entities platform-wide. Use `workspace="-"` in `list_objects()`:
+
+```python
+async def list_objects(self) -> list:
+    try:
+        result = await self.entities.list(MyEntity, workspace="-")
+        return result.data
+    except Exception:
+        logger.exception("Failed to list entities across workspaces")
+        return []  # Return [] on exception — silently skip the cycle
+```
+
+`workspace="-"` is a sentinel. Never use it to create entities.
+
+> Exceptions from `list_objects()` propagate out of `reconcile()`. Always catch and return `[]`.
+
+## Optimistic lock conflicts
+
+`NemoEntityConflictError` from `entity_client.update()` in a controller means another process modified the entity between your `list_objects()` and `reconcile_one()` calls. Catch it, log at debug (NOT error), and skip — it will be retried automatically on the next cycle:
+
+```python
+from nemo_platform_plugin.entity_client import NemoEntityConflictError
+
+async def reconcile_one(self, obj: object) -> None:
+    try:
+        await self._reconcile_one(obj)
+    except NemoEntityConflictError:
+        logger.debug(
+            "Optimistic lock conflict on '%s' — will retry next cycle.", obj.name
+        )
+```
+
+## Overriding reconcile()
+
+Override `reconcile()` entirely for controllers with complex multi-phase logic:
+
+```python
+async def reconcile(self) -> None:
+    # Phase 1: sync state from external backend
+    external_state = await self._fetch_external_state()
+    # Phase 2: reconcile entities against external state
+    entities = await self.entities.list(MyEntity, workspace="-")
+    for entity in entities.data:
+        await self._sync_one(entity, external_state)
+```
+
+When overriding `reconcile()`, `list_objects()` and `reconcile_one()` are not called — stub them with `raise NotImplementedError`. Use `raise NotImplementedError` rather than `return []` / `pass` — this makes it immediately obvious if these stubs are accidentally called after a future refactor.
+
+## interval_seconds from config
+
+```python
+class MyController(NemoController):
+    name = "my-controller"
+
+    def __init__(self) -> None:
+        self._interval_seconds: float = 10.0  # default
+
+    @property
+    def interval_seconds(self) -> float:
+        return self._interval_seconds  # driven by config, set in on_startup
+
+    async def on_startup(self) -> None:
+        from nemo_my_plugin.config import MyPluginConfig
+        config = MyPluginConfig.get()
+        self._interval_seconds = float(config.controller_interval_seconds)
+```
+
+## Minimal example
+
+The `ExampleController` from the example plugin:
+
+```python
+import logging
+from nemo_platform_plugin.controller import NemoController
+
+logger = logging.getLogger(__name__)
+
+_OBJECTS: list[str] = ["alpha", "beta", "gamma"]
+
+
+class ExampleController(NemoController):
+    """Reference controller showing config loading and reconcile loop patterns."""
+
+    name = "example-controller"
+
+    @property
+    def interval_seconds(self) -> float:
+        return 30.0
+
+    async def on_startup(self) -> None:
+        from nemo_example_plugin.config import ExampleConfig
+
+        config = ExampleConfig.get()
+        logger.info(
+            "ExampleController starting up — greeting_style=%r  log_requests=%r",
+            config.greeting_style,
+            config.log_requests,
+        )
+
+    async def list_objects(self) -> list:
+        """Return the set of objects to reconcile this cycle."""
+        return list(_OBJECTS)
+
+    async def reconcile_one(self, obj: object) -> None:
+        """Reconcile a single object — here we just log it."""
+        logger.debug("ExampleController reconciling object: %s", obj)
+```
+
+## Production example
+
+See the **Production State Machine Example** in [`plugin-controller` skill](../.agents/skills/plugin-controller/SKILL.md) for the full `DeploymentController` pattern with state dispatch, `__init__` sentinels, and `on_startup` SDK factory.
+
+## Service / controller decoupling
+
+```
+User → POST /deployments → service creates entity (status="pending") → 201
+                                                              ↓
+                                             controller polls every N seconds
+                                             → finds entity with status="pending"
+                                             → starts process
+                                             → updates entity (status="running")
+```