# Plugin Entities

> Plugin Entities (NemoEntity + NemoEntitiesClient)

- Skill: `nvidia-nemo/plugin-entities` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nvidia-nemo/plugin-entities`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-nemo/plugin-entities/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: NVIDIA NeMo (https://skillmd.com/u/nvidia-nemo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nvidia-nemo/plugin-entities

---


# Plugin Entities (NemoEntity + NemoEntitiesClient)

## Defining an Entity

```python
from nemo_platform_plugin.entity import NemoEntity

class Widget(NemoEntity, entity_type="example_widget"):
    """Stored in entity store under entity type 'example_widget'."""
    colour: str
    weight_kg: float = 0.0
    tags: list[str] = []
```

`entity_type` is **required** on every concrete subclass. It must be snake_case and plugin-scoped (e.g., `"my_plugin_widget"` not `"widget"`). Omitting it raises `TypeError` at class-definition time.

Inherited fields from `EntityBase` (no need to declare):

- `name: str` — human-readable name within workspace
- `workspace: str` — workspace identifier (required, validated against `ID_PATTERN`)
- `project: str | None` — optional project association
- `id: str` — UUID (empty string `""` before persistence — NEVER use in response before save)
- `created_at`, `updated_at`, `created_by`, `updated_by`

## Abstract Intermediate Bases

Two patterns to exempt a class from the `entity_type` requirement:

```python
# Option 1: __abstract__ = True
class BasePluginEntity(NemoEntity):
    __abstract__ = True
    status: str = "pending"

class Widget(BasePluginEntity, entity_type="example_widget"):
    colour: str

# Option 2: inherit from ABC
from abc import ABC

class BasePluginEntity(NemoEntity, ABC):
    status: str = "pending"
```

> **Note:** `__abstract__ = True` only exempts the class that declares it directly. It is **not inherited** — subclasses of `BasePluginEntity` that don't re-declare `__abstract__ = True` must provide `entity_type`.

## Entity CRUD — FastAPI Endpoints

Imports used in every CRUD route:

```python
from nemo_platform_plugin.entity_client import (
    NemoEntitiesClient,
    NemoEntityConflictError,
    NemoEntityNotFoundError,
    get_entity_client,
)
from fastapi import Depends, HTTPException
```

**Create (POST → 201):**

```python
widget = Widget(name=body.name, workspace=workspace, colour=body.colour)
try:
    saved = await entity_client.create(widget)
except NemoEntityConflictError as exc:
    raise HTTPException(status_code=409, detail=f"Widget '{body.name}' already exists.") from exc
return saved
```

**List (GET → 200 with pagination):**

```python
filter_dict = filter if isinstance(filter, dict) else filter.model_dump(exclude_none=True)
result = await entity_client.list(
    Widget,
    workspace=workspace,
    page=page,
    page_size=page_size,
    sort=sort,
    filter_obj=filter_dict or None,
)
pagination = PaginationData.model_validate(result.pagination.model_dump()) if result.pagination else None
return WidgetPage(data=result.data, pagination=pagination, ...)
```

**Get single (GET → 200 or 404):**

```python
try:
    widget = await entity_client.get(Widget, name=name, workspace=workspace)
except NemoEntityNotFoundError as exc:
    raise HTTPException(status_code=404, detail=f"Widget '{name}' not found.") from exc
return widget
```

**Update (PATCH → 200 or 404 or 409):**

```python
try:
    widget = await entity_client.get(Widget, name=name, workspace=workspace)
except NemoEntityNotFoundError as exc:
    raise HTTPException(status_code=404, detail=f"Widget '{name}' not found.") from exc

if body.colour is not None:
    widget.colour = body.colour

try:
    saved = await entity_client.update(widget)
except NemoEntityConflictError as exc:
    raise HTTPException(status_code=409, detail="Concurrent modification.") from exc
except NemoEntityNotFoundError as exc:
    raise HTTPException(status_code=404, detail=f"Widget '{name}' not found.") from exc
return saved
```

**Delete (DELETE → 204):**

```python
try:
    await entity_client.delete(Widget, name=name, workspace=workspace)
except NemoEntityNotFoundError as exc:
    raise HTTPException(status_code=404, detail=f"Widget '{name}' not found.") from exc
```

## filter_obj Patterns

Pass field names directly — **NEVER add a `data.` prefix**. The entity client adds it automatically for non-base fields.

```python
# CORRECT — client adds data. prefix for custom fields automatically
filter_obj={"colour": "red"}          # → search: {"data.colour": "red"}
filter_obj={"name": "my-widget"}      # base field → no prefix: {"name": "my-widget"}

# WRONG — double-prefix bug
filter_obj={"data.colour": "red"}     # → search: {"data.data.colour": "red"} ← broken!
```

Base fields (no prefix): `name`, `workspace`, `project`, `id`, `created_at`, `updated_at`, `entity_type`.

## Pagination

`entity_client.list()` returns `PaginationInfo` (internal). `NemoListResponse` expects `PaginationData` (API layer). They are structurally identical — always convert:

```python
from nemo_platform_plugin.schema import PaginationData

pagination = PaginationData.model_validate(result.pagination.model_dump()) if result.pagination else None
```

Sort format: `"-created_at"` (descending), `"status"` (ascending). Non-base fields are auto-prefixed with `data.` by the client.

## Optimistic Locking

`NemoEntityConflictError` covers two distinct scenarios:

1. **Create**: entity with that `(name, workspace, entity_type)` already exists → respond 409
2. **Update**: `_db_version` mismatch — another request modified the entity between your `get()` and `update()` → respond 409 in services, log debug + skip in controllers

## Cross-Workspace Listing (Controllers)

```python
# workspace="-" lists entities across ALL workspaces
result = await entity_client.list(Widget, workspace="-")
```

`workspace="-"` is a sentinel value handled specially by the entity store. **Never create or update entities with `workspace="-"`.**

## Building Entity Client Without Request Context

For controllers and background tasks where FastAPI's `Depends()` is not available:

```python
from nmp.common.sdk_factory import get_async_platform_sdk
from nemo_platform_plugin.client.adapter import client_from_platform
from nemo_platform_plugin.entities.client import AsyncEntitiesClient
from nmp.common.entities.client import EntityClient

sdk = get_async_platform_sdk(as_service="my-plugin", internal=True)
entity_client = EntityClient(client_from_platform(sdk, AsyncEntitiesClient))
```

`internal=True` adds headers that suppress the access log flood from controller polling every few seconds. Always use `internal=True` for background/controller clients.

## Entity computed fields in API responses

`NemoEntity` subclasses expose `id`, `created_at`, `updated_at` as `@computed_field` properties that appear in `model_dump()` output automatically. Return entity objects directly from route handlers:

```python
@router.post("/widgets", response_model=Widget, status_code=201)
async def create_widget(...) -> Widget:
    saved = await entity_client.create(widget)
    return saved  # id, created_at, etc. are in the serialized output
```

## Test Helper Pattern

```python
from datetime import datetime, timezone
from unittest.mock import AsyncMock
from nemo_platform_plugin.entity_client import NemoEntityNotFoundError

NOW = datetime(2024, 1, 1, tzinfo=timezone.utc)

def _make_widget(name: str = "w1", workspace: str = "default") -> Widget:
    """Build a fake persisted Widget with store-populated private attrs."""
    w = Widget(name=name, workspace=workspace, colour="red")
    w._id = f"id-{name}"          # set private attr directly
    w._created_at = NOW
    return w

# AsyncMock setup
from unittest.mock import MagicMock
from nemo_platform_plugin.entity_client import NemoPaginationInfo

mock_client = AsyncMock()
mock_client.create.return_value = _make_widget("w1")
mock_client.get.side_effect = NemoEntityNotFoundError("not found")

# ListResponse mock — use MagicMock to avoid internal import dependencies
list_resp = MagicMock()
list_resp.data = [_make_widget("w1")]
list_resp.pagination = NemoPaginationInfo(
    page=1, page_size=20, current_page_size=1, total_pages=1, total_results=1
)
mock_client.list.return_value = list_resp
```

## Retry on Optimistic Lock (Services)

In services (not controllers), retry with backoff rather than returning 409:

```python
import asyncio
from nemo_platform_plugin.entity_client import NemoEntityConflictError

async def update_with_retry(entity_client, name, workspace, update_fn):
    for attempt in range(3):
        try:
            entity = await entity_client.get(Widget, name=name, workspace=workspace)
            update_fn(entity)
            return await entity_client.update(entity)
        except NemoEntityConflictError:
            if attempt == 2:
                raise
            await asyncio.sleep(0.1 * (attempt + 1))
```

## Page Through All Entities

```python
async def list_all(entity_client, workspace):
    page = 1
    while True:
        result = await entity_client.list(Widget, workspace=workspace, page=page, page_size=100)
        for entity in result.data:
            yield entity
        if page >= result.pagination.total_pages:
            break
        page += 1
```

## Parent-Child Entities

Child uniqueness is `(workspace, entity_type, parent, name)` instead of the usual `(workspace, entity_type, name)`:

```python
parent = await entity_client.create(ParentEntity(name="p1", workspace="default"))

child = ChildEntity(name="c1", workspace="default")
child._parent = parent.id  # link via UUID
child = await entity_client.create(child)

# Retrieve with parent context
child = await entity_client.get(ChildEntity, "c1", workspace="default", parent=parent.id)
```

## Gotchas

- **`entity_type` REQUIRED on concrete classes**: `TypeError` at class-definition time if missing. Error message shows exact correct syntax.
- **`entity.id` is `""` (empty string) before persistence**: Never return an unsaved entity from a route — the empty `id` will appear in the API response. Always call `entity_client.create()` or `entity_client.get()` first.
- **`filter_obj` with `data.` prefix**: Double-prefix bug — `{"data.colour": "red"}` becomes `{"data.data.colour": "red"}` in the actual query. Always pass bare field names.
- **`workspace="-"` is a sentinel**: Never use it for creating/updating entities — only for listing across workspaces.
- **`entity_type` auto-derivation is DISABLED**: `NemoEntity` explicitly disables the `EntityBase` behavior of deriving `entity_type` from the class name. You must always pass it as a keyword.
- **`workspace` and `name` must match `ID_PATTERN`**: Pattern is `^[\w\-\+.@:]+$`. Spaces and forward slashes cause validation errors on both fields.
- **`NemoEntityConflictError` has two meanings**: check call site — `create()` means duplicate; `update()` means version mismatch.