nutria-plugin 0.2.0__tar.gz → 0.2.1__tar.gz

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.1
+
+- Add manifest schema `2.1` with typed world providers, custom resource types,
+  stable identity fields, safe projections, and provider capability references.
+- Keep schema `2.0` compatible and export the new provider descriptor models.
+- Scaffold new plugins with schema `2.1` while preserving the 0.3.0 roadmap.
+
 ## 0.2.0
 
 - Make manifest schema `2.0` the single production schema.

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nutria-plugin
-Version: 0.2.0
+Version: 0.2.1
 Summary: SDK for building, validating, signing, and packaging Nutria plugins
 Project-URL: Homepage, https://github.com/AlRos14/nutria-plugin-sdk
 Project-URL: Repository, https://github.com/AlRos14/nutria-plugin-sdk
@@ -21,8 +21,8 @@ Description-Content-Type: text/markdown
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.2.0` introduces the typed capability graph and manifest schema
-`2.0`. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
+Release `0.2.1` adds provider-backed world graph descriptors in manifest schema
+`2.1` while continuing to accept schema `2.0`. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
 plugin only reads channel state and delivers the exact approved snapshot.
 
 This release also supports **declarative admin extensions**, allowing plugins
@@ -62,7 +62,7 @@ my-workspace-plugin/
 
 ```json
 {
-  "schema_version": "2.0",
+  "schema_version": "2.1",
   "id": "my-workspace-plugin",
   "name": "My Workspace Plugin",
   "version": "0.1.0",
@@ -81,7 +81,20 @@ my-workspace-plugin/
       "tool": "search_workspace",
       "connection_id": "workspace"
     }
-  ]
+  ],
+  "world_providers": [{
+    "id": "workspace",
+    "title": "Workspace",
+    "description": "Authoritative workspace resources.",
+    "connection_id": "workspace",
+    "resource_types": [{
+      "id": "workspace.item",
+      "title": "Workspace item",
+      "description": "One stable workspace item.",
+      "identity_fields": ["id"],
+      "search_capability": "workspace.search"
+    }]
+  }]
 }
 ```
 

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/README.md

@@ -2,8 +2,8 @@
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.2.0` introduces the typed capability graph and manifest schema
-`2.0`. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
+Release `0.2.1` adds provider-backed world graph descriptors in manifest schema
+`2.1` while continuing to accept schema `2.0`. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
 plugin only reads channel state and delivers the exact approved snapshot.
 
 This release also supports **declarative admin extensions**, allowing plugins
@@ -43,7 +43,7 @@ my-workspace-plugin/
 
 ```json
 {
-  "schema_version": "2.0",
+  "schema_version": "2.1",
   "id": "my-workspace-plugin",
   "name": "My Workspace Plugin",
   "version": "0.1.0",
@@ -62,7 +62,20 @@ my-workspace-plugin/
       "tool": "search_workspace",
       "connection_id": "workspace"
     }
-  ]
+  ],
+  "world_providers": [{
+    "id": "workspace",
+    "title": "Workspace",
+    "description": "Authoritative workspace resources.",
+    "connection_id": "workspace",
+    "resource_types": [{
+      "id": "workspace.item",
+      "title": "Workspace item",
+      "description": "One stable workspace item.",
+      "identity_fields": ["id"],
+      "search_capability": "workspace.search"
+    }]
+  }]
 }
 ```
 

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/docs/index.md

@@ -31,6 +31,7 @@ Plugins define:
 - **Settings schema** — admin-configurable options shown in the Nutria UI
 - **Admin extensions** — safe, declarative operator views rendered by the Nutria host
 - **Admin flows** — safe, declarative operator workflows such as external login/pairing
+- **World providers** — resource types and capability paths injected into the host graph
 
 ## Minimal plugin structure
 
@@ -53,7 +54,7 @@ my-plugin/
 
 ## Version
 
-This documentation describes `nutria-plugin` **v0.2.0** and manifest schema
-**2.0**.
+This documentation describes `nutria-plugin` **v0.2.1** and manifest schema
+**2.1**. Schema 2.0 remains accepted for plugins that do not declare world providers.
 
 API and file format compatibility are not yet guaranteed between pre-release releases.

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/docs/manifest.md

@@ -8,7 +8,7 @@ directory as `plugin.json`.
 
 ```json
 {
-  "schema_version": "2.0",
+  "schema_version": "2.1",
   "id": "my-plugin",
   "name": "My Plugin",
   "version": "0.1.0",
@@ -42,6 +42,19 @@ directory as `plugin.json`.
       "connection_id": "workspace"
     }
   ],
+  "world_providers": [{
+    "id": "workspace",
+    "title": "Workspace",
+    "description": "Authoritative workspace resources.",
+    "connection_id": "workspace",
+    "resource_types": [{
+      "id": "workspace.item",
+      "title": "Workspace item",
+      "description": "One stable workspace item.",
+      "identity_fields": ["id"],
+      "search_capability": "workspace.search"
+    }]
+  }],
   "tags": ["crm", "sales"],
   "admin_extensions": [
     {
@@ -73,7 +86,8 @@ directory as `plugin.json`.
 
 ### `schema_version` *(string, required)*
 
-The manifest schema is `"2.0"`. Every plugin must declare this version.
+The current manifest schema is `"2.1"`; schema `"2.0"` remains accepted for
+backward compatibility. Schema 2.1 adds provider-backed world graph contracts.
 Capabilities and reviewable actions are typed by the SDK; schema `1.x` is not
 accepted by the production host.
 
@@ -285,6 +299,20 @@ See [reviewable-actions.md](reviewable-actions.md) for the complete schema.
 
 ---
 
+### `world_providers` *(array of objects, optional; schema 2.1)*
+
+Each provider declares a stable `id`, title, description, optional
+`connection_id` and `health_capability`, plus one or more resource types. A
+resource type has a stable built-in or plugin-namespaced custom `id`, at least
+one `identity_fields` entry, optional `search_capability` and
+`inspect_capability`, bounded `ttl_seconds`, and named safe `projections`.
+
+Referenced capabilities must exist in the same manifest. Provider declarations
+describe navigation only: the host still enforces audience, persona assignment,
+connection state, and effect authorization before executing a tool.
+
+---
+
 ### `tags` *(array of strings, optional)*
 
 Discovery tags shown in the plugin marketplace.

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nutria-plugin"
-version = "0.2.0"
+version = "0.2.1"
 description = "SDK for building, validating, signing, and packaging Nutria plugins"
 readme = "README.md"
 license = {text = "MIT"}

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/src/nutria_plugin/__init__.py

@@ -15,7 +15,7 @@ Signing:
     generate_keypair, sign_manifest, verify_manifest, SignatureStatus
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from .capabilities import (
     CapabilityDescriptor,
@@ -25,6 +25,9 @@ from .capabilities import (
     CapabilityRequirement,
     ResourceBinding,
     ResourceType,
+    ResourceTypeDescriptor,
+    WorldProjectionDescriptor,
+    WorldProviderDescriptor,
 )
 
 
@@ -74,6 +77,9 @@ __all__ = [
     "CapabilityRequirement",
     "ResourceBinding",
     "ResourceType",
+    "ResourceTypeDescriptor",
+    "WorldProjectionDescriptor",
+    "WorldProviderDescriptor",
     # Bundle
     "PluginBundleError",
     "load_plugin_bundle",

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/src/nutria_plugin/capabilities.py

@@ -8,6 +8,9 @@ from typing import Any
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 
+_RESOURCE_TYPE_PATTERN = r"^[a-z][a-z0-9_.-]{0,127}$"
+
+
 class CapabilityEffect(str, Enum):
     READ = "read"
     PREPARE = "prepare"
@@ -44,6 +47,14 @@ class ResourceType(str, Enum):
     WHATSAPP_CHAT = "whatsapp_chat"
     WHATSAPP_MESSAGE = "whatsapp_message"
     WHATSAPP_ATTACHMENT = "whatsapp_attachment"
+    PRODUCT = "product"
+    FILE = "file"
+    TASK = "task"
+    TRELLO_BOARD = "trello_board"
+    TRELLO_CARD = "trello_card"
+    TRELLO_LABEL = "trello_label"
+    MRW_SHIPMENT = "mrw_shipment"
+    MRW_LABEL = "mrw_label"
 
 
 class CapabilityRequirement(BaseModel):
@@ -65,34 +76,126 @@ class ResourceBinding(BaseModel):
     """A resource consumed or produced by a capability."""
 
     name: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
-    resource_type: ResourceType
+    resource_type: ResourceType | str
     required: bool = True
     many: bool = False
 
     model_config = {"extra": "forbid"}
 
+    @field_validator("resource_type")
+    @classmethod
+    def _validate_resource_type(cls, value: ResourceType | str) -> ResourceType | str:
+        _validate_resource_type_id(value)
+        return value
+
 
 class CapabilityInputBinding(BaseModel):
     """Maps a semantic input to one plugin tool argument."""
 
     semantic_field: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
     argument_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
-    resource_type: ResourceType | None = None
+    resource_type: ResourceType | str | None = None
     required: bool = True
 
     model_config = {"extra": "forbid"}
 
+    @field_validator("resource_type")
+    @classmethod
+    def _validate_resource_type(cls, value: ResourceType | str | None) -> ResourceType | str | None:
+        if value is not None:
+            _validate_resource_type_id(value)
+        return value
+
 
 class CapabilityOutputBinding(BaseModel):
     """Maps one plugin result field to a typed resource output."""
 
     field_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$")
-    resource_type: ResourceType
+    resource_type: ResourceType | str
     output_name: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
     many: bool = False
 
     model_config = {"extra": "forbid"}
 
+    @field_validator("resource_type")
+    @classmethod
+    def _validate_resource_type(cls, value: ResourceType | str) -> ResourceType | str:
+        _validate_resource_type_id(value)
+        return value
+
+
+def _validate_resource_type_id(value: ResourceType | str) -> None:
+    import re
+
+    raw = value.value if isinstance(value, ResourceType) else str(value)
+    if not re.fullmatch(_RESOURCE_TYPE_PATTERN, raw):
+        raise ValueError("resource type must be a stable lowercase identifier")
+
+
+class WorldProjectionDescriptor(BaseModel):
+    """Named provider projection; payload fields remain provider-owned."""
+
+    id: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,63}$")
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(default="", max_length=1_000)
+    fields: list[str] = Field(default_factory=list, max_length=64)
+    sensitivity: str = Field(default="safe", pattern=r"^(safe|authorized)$")
+
+    model_config = {"extra": "forbid"}
+
+
+class ResourceTypeDescriptor(BaseModel):
+    """How one provider exposes a stable resource namespace to the world."""
+
+    id: ResourceType | str
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(..., min_length=1, max_length=2_000)
+    identity_fields: list[str] = Field(default_factory=list, min_length=1, max_length=16)
+    version_field: str | None = Field(default=None, max_length=128)
+    search_capability: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    inspect_capability: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    ttl_seconds: int = Field(default=300, ge=0, le=86_400)
+    projections: list[WorldProjectionDescriptor] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("id")
+    @classmethod
+    def _validate_id(cls, value: ResourceType | str) -> ResourceType | str:
+        _validate_resource_type_id(value)
+        return value
+
+    @model_validator(mode="after")
+    def _validate_projections(self) -> "ResourceTypeDescriptor":
+        ids = [item.id for item in self.projections]
+        if len(ids) != len(set(ids)):
+            raise ValueError("resource projections must not repeat IDs")
+        return self
+
+
+class WorldProviderDescriptor(BaseModel):
+    """Static contract projected into the host-owned agent world graph."""
+
+    id: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(..., min_length=1, max_length=2_000)
+    connection_id: str | None = Field(
+        default=None, pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$"
+    )
+    health_capability: str | None = Field(
+        default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$"
+    )
+    resource_types: list[ResourceTypeDescriptor] = Field(default_factory=list, min_length=1)
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def _validate_resources(self) -> "WorldProviderDescriptor":
+        ids = [item.id.value if isinstance(item.id, ResourceType) else str(item.id) for item in self.resource_types]
+        if len(ids) != len(set(ids)):
+            raise ValueError("world provider resource types must not repeat IDs")
+        return self
+
 
 class CapabilityDescriptor(BaseModel):
     """Declarative capability contract shared by SDK, host, and plugins."""

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/src/nutria_plugin/manifest.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
-from .capabilities import CapabilityDescriptor, CapabilityEffect
+from .capabilities import CapabilityDescriptor, CapabilityEffect, ResourceType, WorldProviderDescriptor
 
 _SEMVER_RE = re.compile(
     r"^(0|[1-9]\d*)\."
@@ -325,7 +325,7 @@ class PluginAdminFlow(BaseModel):
 class PluginManifest(BaseModel):
     """Manifest stored in plugin.json — the single source of truth for plugin metadata."""
 
-    schema_version: str = Field(..., pattern=r"^2\.0$")
+    schema_version: str = Field(..., pattern=r"^2\.(0|1)$")
     id: str = Field(..., pattern=r"^[a-z][a-z0-9\-]*$", max_length=64)
     name: str = Field(..., min_length=1, max_length=128)
     version: str = Field(..., min_length=5, max_length=64)
@@ -339,6 +339,7 @@ class PluginManifest(BaseModel):
     optional_secrets: List[str] = Field(default_factory=list)
     remote_endpoints: List[str] = Field(default_factory=list)
     capabilities: List[CapabilityDescriptor] = Field(default_factory=list)
+    world_providers: List[WorldProviderDescriptor] = Field(default_factory=list)
     tags: List[str] = Field(default_factory=list)
     reviewable_actions: List[ReviewableActionContract] = Field(default_factory=list)
     admin_extensions: List[PluginAdminExtension] = Field(default_factory=list)
@@ -376,6 +377,26 @@ class PluginManifest(BaseModel):
         if len(action_ids_list) != len(set(action_ids_list)):
             raise ValueError("reviewable_actions must not contain duplicate contract IDs")
         capability_map = {capability.id: capability for capability in self.capabilities}
+        provider_ids = [provider.id for provider in self.world_providers]
+        if len(provider_ids) != len(set(provider_ids)):
+            raise ValueError("world_providers must not contain duplicate IDs")
+        for provider in self.world_providers:
+            for resource in provider.resource_types:
+                resource_id = resource.id.value if isinstance(resource.id, ResourceType) else str(resource.id)
+                for field_name, capability_id in (
+                    ("search_capability", resource.search_capability),
+                    ("inspect_capability", resource.inspect_capability),
+                ):
+                    if capability_id and capability_id not in capability_map:
+                        raise ValueError(
+                            f"world provider resource {resource_id!r} {field_name} references "
+                            f"unknown capability {capability_id!r}"
+                        )
+                if provider.health_capability and provider.health_capability not in capability_map:
+                    raise ValueError(
+                        f"world provider {provider.id!r} references unknown health capability "
+                        f"{provider.health_capability!r}"
+                    )
         action_ids = set(action_ids_list)
         for action in self.reviewable_actions:
             execute = capability_map.get(action.execute_capability)

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/src/nutria_plugin/packaging.py

@@ -25,7 +25,7 @@ class PackagingError(Exception):
 SCAFFOLD_TEMPLATE = {
     "plugin.json": lambda plugin_id, name: json.dumps(
         {
-            "schema_version": "2.0",
+            "schema_version": "2.1",
             "id": plugin_id,
             "name": name,
             "version": "0.1.0",

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/tests/test_manifest.py

@@ -64,7 +64,7 @@ def test_version_must_be_semver():
         PluginManifest.model_validate(_minimal_manifest(version="1.0"))
 
 
-def test_schema_version_must_be_2_0():
+def test_schema_version_must_be_2_x():
     with pytest.raises(ValidationError):
         PluginManifest.model_validate(_minimal_manifest(schema_version="1.1"))
 
@@ -74,6 +74,80 @@ def test_schema_version_1_x_is_rejected():
         PluginManifest.model_validate(_minimal_manifest(schema_version="1.0"))
 
 
+def test_schema_2_1_world_provider_accepts_custom_resource_type():
+    manifest = PluginManifest.model_validate(
+        _minimal_manifest(
+            schema_version="2.1",
+            capabilities=[
+                {
+                    "id": "workspace.search",
+                    "title": "Search workspace",
+                    "description": "Find authoritative workspace items.",
+                    "effect": "read",
+                    "tool": "search_workspace",
+                    "connection_id": "workspace",
+                    "produces": [
+                        {
+                            "field_name": "items",
+                            "resource_type": "workspace.item",
+                            "output_name": "items",
+                            "many": True,
+                        }
+                    ],
+                }
+            ],
+            world_providers=[
+                {
+                    "id": "workspace",
+                    "title": "Workspace",
+                    "description": "Authoritative workspace provider.",
+                    "connection_id": "workspace",
+                    "resource_types": [
+                        {
+                            "id": "workspace.item",
+                            "title": "Workspace item",
+                            "description": "A stable workspace item.",
+                            "identity_fields": ["id"],
+                            "search_capability": "workspace.search",
+                            "projections": [
+                                {"id": "admin", "title": "Admin", "fields": ["id"]}
+                            ],
+                        }
+                    ],
+                }
+            ],
+        )
+    )
+
+    assert manifest.schema_version == "2.1"
+    assert manifest.world_providers[0].resource_types[0].id == "workspace.item"
+
+
+def test_world_provider_rejects_unknown_capability_reference():
+    with pytest.raises(ValidationError, match="unknown capability"):
+        PluginManifest.model_validate(
+            _minimal_manifest(
+                schema_version="2.1",
+                world_providers=[
+                    {
+                        "id": "workspace",
+                        "title": "Workspace",
+                        "description": "Authoritative workspace provider.",
+                        "resource_types": [
+                            {
+                                "id": "workspace.item",
+                                "title": "Workspace item",
+                                "description": "A stable workspace item.",
+                                "identity_fields": ["id"],
+                                "search_capability": "workspace.missing",
+                            }
+                        ],
+                    }
+                ],
+            )
+        )
+
+
 def test_empty_runtime_types_rejected():
     with pytest.raises(ValidationError):
         PluginManifest.model_validate(_minimal_manifest(runtime_types=[]))

{nutria_plugin-0.2.0 → nutria_plugin-0.2.1}/uv.lock

@@ -262,7 +262,7 @@ wheels = [
 
 [[package]]
 name = "nutria-plugin"
-version = "0.1.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },