optimizely-opal.opal-tools-sdk 0.1.11.dev0__tar.gz → 0.1.14.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.11.dev0 → optimizely_opal_opal_tools_sdk-0.1.14.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.11.dev0
+Version: 0.1.14.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely
@@ -18,6 +18,10 @@ Description-Content-Type: text/markdown
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: httpx>=0.24.1
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: requires-python

{optimizely_opal_opal_tools_sdk-0.1.11.dev0 → optimizely_opal_opal_tools_sdk-0.1.14.dev0}/opal_tools_sdk/__init__.py

@@ -1,13 +1,15 @@
 from .service import ToolsService
-from .decorators import tool
+from .decorators import tool, resource
 from .auth import requires_auth
 from .logging import register_logger_factory
 from .models import AuthData, AuthRequirement, Credentials, Environment, IslandConfig, IslandResponse
+from .proteus import UI
 
-__version__ = "0.1.0"
+__version__ = "0.1.14-dev"
 __all__ = [
     "ToolsService",
     "tool",
+    "resource",
     "requires_auth",
     "register_logger_factory",
     # Models
@@ -17,4 +19,6 @@ __all__ = [
     "Environment",
     "IslandConfig",
     "IslandResponse",
+    # UI
+    "UI",
 ]

{optimizely_opal_opal_tools_sdk-0.1.11.dev0 → optimizely_opal_opal_tools_sdk-0.1.14.dev0}/opal_tools_sdk/decorators.py

@@ -10,7 +10,12 @@ from .logging import get_logger
 
 logger = get_logger(__name__)
 
-def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str, Any]]] = None):
+def tool(
+    name: str,
+    description: str,
+    auth_requirements: Optional[List[Dict[str, Any]]] = None,
+    ui_resource: Optional[str] = None,
+):
     """Decorator to register a function as an Opal tool.
 
     Args:
@@ -19,6 +24,8 @@ def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str,
         auth_requirements: Authentication requirements (optional)
             Format: [{"provider": "oauth_provider", "scope_bundle": "permissions_scope", "required": True}, ...]
             Example: [{"provider": "google", "scope_bundle": "calendar", "required": True}]
+        ui_resource: URI of associated UI resource for dynamic rendering (optional)
+            Example: "ui://my-app/create-form"
 
     Returns:
         Decorator function
@@ -27,6 +34,9 @@ def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str,
         If your tool requires authentication, define your handler function with two parameters:
         async def my_tool(parameters: ParametersModel, auth_data: Optional[Dict] = None):
             ...
+
+        If ui_resource is specified, the frontend can fetch the resource to render a dynamic UI
+        for this tool without hardcoded integrations.
     """
     def decorator(func: Callable):
         # Get the ToolsService instance from the global registry
@@ -152,7 +162,87 @@ def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str,
                 handler=func,
                 parameters=parameters,
                 endpoint=endpoint,
-                auth_requirements=auth_req_list
+                auth_requirements=auth_req_list,
+                ui_resource=ui_resource
+            )
+
+        return func
+
+    return decorator
+
+
+def resource(
+    uri: str,
+    name: str,
+    description: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    title: Optional[str] = None,
+):
+    """Decorator to register a function as an MCP resource.
+
+    Args:
+        uri: The unique URI for this resource (e.g., "ui://my-app/create-form")
+        name: Name of the resource
+        description: Description of the resource (optional)
+        mime_type: MIME type of the resource content (optional, e.g., "application/vnd.opal.proteus+json")
+        title: Human-readable title for the resource (optional)
+
+    Returns:
+        Decorator function
+
+    Note:
+        The handler function should be async and return either a str or a UI.Document.
+
+        When returning a UI.Document, the SDK will automatically:
+        - Serialize it to JSON based on the document's Pydantic model data
+        - Set the MIME type to "application/vnd.opal.proteus+json" (if not specified)
+
+        Examples:
+            # Example 1: Returning a string (manual serialization)
+            @resource(
+                uri="ui://my-app/create-form",
+                name="create-form",
+                description="Form for creating new items",
+                mime_type="application/vnd.opal.proteus+json"
+            )
+            async def get_create_form() -> str:
+                proteus_spec = {"type": "form", "fields": [...]}
+                return json.dumps(proteus_spec)
+
+            # Example 2: Returning a UI.Document (automatic serialization)
+            from opal_tools_sdk.ui import UI
+
+            @resource(
+                uri="ui://my-app/create-form",
+                name="create-form",
+                description="Form for creating new items"
+            )
+            async def get_create_form() -> UI.Document:
+                return UI.Document(
+                    body=[
+                        UI.Heading(children="Create Item"),
+                        UI.Field(label="Name", children=UI.Input(name="item_name"))
+                    ],
+                    actions=[UI.Action(children="Save", appearance="primary")]
+                )
+    """
+    def decorator(func: Callable):
+        # Get the ToolsService instance from the global registry
+        from . import _registry
+
+        logger.info(f"Registering resource {name} with URI {uri}")
+
+        if not _registry.services:
+            logger.warning("No services registered in registry! Make sure to create ToolsService before decorating functions.")
+
+        for service in _registry.services:
+            service.register_resource(
+                uri=uri,
+                name=name,
+                description=description,
+                mime_type=mime_type,
+                title=title,
+                handler=func,
             )
 
         return func

{optimizely_opal_opal_tools_sdk-0.1.11.dev0 → optimizely_opal_opal_tools_sdk-0.1.14.dev0}/opal_tools_sdk/models.py

@@ -83,6 +83,7 @@ class Function:
     endpoint: str
     auth_requirements: Optional[List[AuthRequirement]] = None
     http_method: str = "POST"
+    ui_resource: Optional[str] = None  # UI resource URI for dynamic UI rendering
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for the discovery endpoint."""
@@ -97,6 +98,9 @@ class Function:
         if self.auth_requirements:
             result["auth_requirements"] = [auth.to_dict() for auth in self.auth_requirements]
 
+        if self.ui_resource:
+            result["ui_resource"] = self.ui_resource
+
         return result