Plugin Service

Plugin HTTP Service (NemoService)

Class Signature

from typing import ClassVar
from nemo_platform_plugin.service import NemoService, RouterSpec

class MyService(NemoService):
    name: ClassVar[str] = "my-plugin"          # REQUIRED — entry-point key, URL prefix
    dependencies: ClassVar[list[str]] = ["entities"]  # platform services to wait for

    def get_routers(self) -> list[RouterSpec]:  # REQUIRED
        return [RouterSpec(_build_router(), tag="My Plugin", prefix="/v2/workspaces/{workspace}")]

    async def on_startup(self) -> None: ...     # optional — async init
    async def on_shutdown(self) -> None: ...    # optional — cleanup

Valid dependencies values: "entities", "auth", "jobs", "files", "secrets", "models", "inference-gateway". These services must be healthy before on_startup() is called.

URL Pattern

/apis/<name>/<spec.prefix>/<route-path>

Example: name="my-plugin", prefix="/v2/workspaces/{workspace}", route /widgets → /apis/my-plugin/v2/workspaces/{workspace}/widgets

Convention: always use prefix="/v2/workspaces/{workspace}" for resource endpoints.

Authorization

Every plugin HTTP route MUST carry a @path_rule — a route with no rule is a validation error, and under the default on_invalid_plugin=hard_fail the auth service refuses to build the OPA bundle rather than silently fence the route, so the platform 502s. Each route also declares exactly one OAuth scope with @AuthzScope.read / .write — a separate, orthogonal decorator. @router.<method> is the outermost decorator; @scope and @path_rule sit beneath it (their relative order is irrelevant):

from nemo_platform_plugin.authz import AuthzScope, CallerKind, PermissionSet, path_rule, perm

scope = AuthzScope("my-plugin")                    # owns my-plugin:read / my-plugin:write

class WidgetPerms(PermissionSet, namespace="my-plugin.widgets"):
    READ = perm("Read a widget")                   # -> "my-plugin.widgets.read"

@router.get("/widgets/{name}", response_model=Widget)
@scope.read                                        # OAuth scope gate
@path_rule(callers=[CallerKind.PRINCIPAL], permissions=[WidgetPerms.READ])
async def get_widget(...) -> Widget: ...

Reference PermissionSet members (never bare strings — a bare string raises TypeError at import), and pass authz=scope to route factories (add_job_routes / add_function_routes) so their routes are ruled too. See ../plugin-authz/SKILL.md for the full surface — caller kinds, compound permission ids, role grants, and fail-mode config.

Response Schemas

Entity objects as responses

Return entity objects directly — no separate response class needed:

from nemo_platform_plugin.authz import AuthzScope, CallerKind, PermissionSet, path_rule, perm
from nemo_platform_plugin.entity import NemoEntity

scope = AuthzScope("my-plugin")                    # owns my-plugin:read / my-plugin:write

class WidgetPerms(PermissionSet, namespace="my-plugin.widgets"):
    CREATE = perm("Create a widget")               # -> "my-plugin.widgets.create"

class Widget(NemoEntity, entity_type="my_plugin_widget"):
    colour: str
    weight_kg: float = 0.0

# Use the entity class directly as response_model:
@router.post("/widgets", response_model=Widget, status_code=201)
@scope.write                                       # OAuth scope gate
@path_rule(callers=[CallerKind.PRINCIPAL], permissions=[WidgetPerms.CREATE])
async def create_widget(...) -> Widget:
    saved = await entity_client.create(widget)
    return saved

NemoEntity subclasses expose id, created_at, updated_at, name, workspace, project as computed fields — they serialize correctly in responses without any adapter class.

For non-CRUD endpoints or computed responses, use a plain BaseModel subclass instead.

NemoListResponse

from nemo_platform_plugin.schema import NemoListResponse

WidgetPage = NemoListResponse[Widget]  # entity class used directly

NemoListResponse wire format:

{
    "data": [...],
    "pagination": {"page": 1, "page_size": 20, "current_page_size": 5,
                   "total_pages": 1, "total_results": 5},
    "sort": "-created_at",
    "filter": {"colour": "red"}
}

CRITICAL: entity_client.list() returns PaginationInfo (entity client internal). NemoListResponse expects PaginationData (API response layer). Always convert:

from nemo_platform_plugin.schema import PaginationData
pagination = PaginationData.model_validate(result.pagination.model_dump()) if result.pagination else None

NemoFilter

from nemo_platform_plugin.schema import NemoFilter

class WidgetFilter(NemoFilter):      # extra="forbid" inherited — typos → 422
    colour: str | None = None
    tag: str | None = None

• extra="forbid" means unknown filter fields return 422 (not silently ignored)
• deepObject query syntax: ?filter[colour]=red
• Factory: make_filter_obj_dep(WidgetFilter) from nmp.common.entities.filters
• Always check isinstance(filter, dict) — make_filter_obj_dep can return either a NemoFilter instance or a raw dict for wildcard filters:

filter_dict = filter if isinstance(filter, dict) else filter.model_dump(exclude_none=True)
result = await entity_client.list(Widget, workspace=workspace, filter_obj=filter_dict or None)

Dependency Injection

from nemo_platform_plugin.entity_client import NemoEntitiesClient, get_entity_client
from nmp.common.auth.dependencies import get_auth_client
from nmp.common.auth.client import AuthClient
from nmp.common.service.dependencies import get_sdk_client  # transitive dep via nmp-common; not re-exported by nemo_platform_plugin
from nemo_platform import AsyncNeMoPlatform
from nemo_platform_plugin.authz import AuthzScope, CallerKind, PermissionSet, path_rule, perm
from fastapi import Depends

scope = AuthzScope("my-plugin")

class WidgetPerms(PermissionSet, namespace="my-plugin.widgets"):
    LIST = perm("List widgets")                    # -> "my-plugin.widgets.list"

@router.get("/widgets")
@scope.read
@path_rule(callers=[CallerKind.PRINCIPAL], permissions=[WidgetPerms.LIST])
async def list_widgets(
    workspace: str,
    entity_client: NemoEntitiesClient = Depends(get_entity_client),
    auth_client: AuthClient = Depends(get_auth_client),
    sdk: AsyncNeMoPlatform = Depends(get_sdk_client),
) -> WidgetPage:
    principal_id = auth_client.principal.id
    ...

get_entity_client is a placeholder — the platform injects the real implementation at startup via app.dependency_overrides.

CRUD Quick Reference

Complete implementation: See crud-example.md — full entity-backed CRUD service with all imports, error handling, and tests.

All raise statements must use from exc syntax for error chaining.

Testing Pattern

from fastapi import FastAPI
from fastapi.testclient import TestClient
from unittest.mock import AsyncMock
from nemo_platform_plugin.entity_client import get_entity_client

def _make_app(mock_client: AsyncMock) -> FastAPI:
    service = MyService()
    app = FastAPI()
    for spec in service.get_routers():
        app.include_router(spec.router, prefix=spec.prefix)
    app.dependency_overrides[get_entity_client] = lambda: mock_client
    return app

def test_get_widget():
    mock_client = AsyncMock()
    mock_client.get.return_value = _make_widget("w1")
    app = _make_app(mock_client)
    client = TestClient(app)
    response = client.get("/v2/workspaces/default/widgets/w1")
    assert response.status_code == 200
    assert response.json()["name"] == "w1"

Gotchas

• PaginationInfo ≠ PaginationData: entity_client.list() returns PaginationInfo; NemoListResponse expects PaginationData. Always convert: PaginationData.model_validate(result.pagination.model_dump()).
• isinstance(filter, dict) check is required: make_filter_obj_dep may return either a NemoFilter instance or a raw dict for wildcard filters. Calling .model_dump() on a dict raises AttributeError.
• entity.id is "" before persistence: Never return an entity from a route before saving it — the empty id will appear in the response.
• from exc on all raises: Use raise HTTPException(...) from exc for all error re-raises to preserve the exception chain.
• get_entity_client is a placeholder: The platform injects the real implementation via app.dependency_overrides. In tests, override it with lambda: mock_client.
• NemoFilter extra="forbid": Unknown filter query params return 422. This is by design — it prevents typos from silently returning unfiltered results.
• URL formula: Routes mount at /apis/<name>/<prefix>/<route>. The prefix in RouterSpec is appended after the service name, not replacing it.
• Unruled route → OPA bundle build fails: A route with no @path_rule is a validation error; under the default on_invalid_plugin=hard_fail the auth service refuses to build the bundle and the platform 502s. Attach @path_rule (plus @scope.read/.write) to every handler, or authz= on a route factory.

See Also

• crud-example.md — Complete CRUD implementation with all imports
• ../plugin-entities/SKILL.md — Entity definitions and client
• ../plugin-platform-services/SKILL.md — Calling other platform services
• ../plugin-authz/SKILL.md — Authorization for plugin routes