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

{optimizely_opal_opal_tools_sdk-0.1.12.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.12.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
@@ -37,8 +37,7 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 - Parameter validation and type checking
 - Authentication helpers
 - FastAPI integration
-- **Adaptive Blocks** for interactive forms and UI flows (new!)
-- Island components for interactive UI responses (legacy)
+- Island components for interactive UI responses
 
 ## Installation
 
@@ -50,7 +49,7 @@ Note: While the package is installed as `optimizely-opal.opal-tools-sdk`, you'll
 
 ```python
 # Import using the package name
-from opal_tools_sdk import ToolsService, tool, Block, BlockResponse, IslandResponse, IslandConfig
+from opal_tools_sdk import ToolsService, tool, IslandResponse, IslandConfig
 ```
 
 ## Usage
@@ -75,65 +74,6 @@ async def get_weather(parameters: WeatherParameters):
 # Discovery endpoint is automatically created at /discovery
 ```
 
-## Adaptive Blocks
-
-Adaptive Blocks provide an interactive UI framework for tools to capture user input directly through forms, rather than having the LLM gather parameters through chat messages.
-
-### Basic Example
-
-```python
-from opal_tools_sdk import Block, BlockResponse, tool
-from pydantic import BaseModel, Field
-
-class MyToolParams(BaseModel):
-    user_input: str | None = Field(default=None, description="User input")
-
-@tool(
-    name="my_tool",
-    description="Example tool with Block Document",
-    type="block"  # Important: Specify type="block"
-)
-async def my_tool(params: MyToolParams) -> BlockResponse:
-    # If parameters are missing, show a form
-    if not params.user_input:
-        return BlockResponse(
-            content=Block.Document(
-                children=[
-                    Block.Heading(children="Enter Details", level="2"),
-                    Block.Field(
-                        label="User Input",
-                        required=True,
-                        children=Block.Input(
-                            name="user_input",
-                            placeholder="Enter something..."
-                        )
-                    ),
-                ],
-                actions=[
-                    Block.Action(name="submit", children="Submit"),
-                    Block.CancelAction(children="Cancel")
-                ],
-                blocking=True  # Hide chat prompt, force form interaction
-            )
-        )
-
-    # Process the input and return as Block Document
-    return BlockResponse(
-        content=Block.Document(
-            children=[
-                Block.Heading(children="Result", level="2"),
-                Block.Text(children=f"You entered: {params.user_input}")
-            ]
-        )
-    )
-```
-
-**Important:** When using `type="block"`, the function MUST:
-
-1. Have a return type annotation of `-> BlockResponse`
-2. Always return a `BlockResponse` object (even for success/error cases)
-3. Wrap all responses in `Block.Document()` for consistency
-
 ## Authentication
 
 The SDK provides two ways to require authentication for your tools:
@@ -174,7 +114,7 @@ async def get_calendar_events(parameters: CalendarParameters, auth_data: Optiona
 async def get_calendar_availability(parameters: CalendarParameters, auth_data: Optional[AuthData] = None):
     provider = ""
     token = ""
-
+    
     if auth_data:
         provider = auth_data["provider"]
         token = auth_data["credentials"]["access_token"]
@@ -226,7 +166,7 @@ class WeatherParameters(BaseModel):
 async def get_weather(parameters: WeatherParameters):
     # Get weather data (implementation details omitted)
     weather_data = {"temperature": 22, "condition": "sunny", "humidity": 65}
-
+    
     # Create an interactive island for weather settings
     island = IslandConfig(
         fields=[
@@ -260,16 +200,14 @@ async def get_weather(parameters: WeatherParameters):
             )
         ]
     )
-
+    
     return IslandResponse.create([island])
 ```
 
 ### Island Components
 
 #### IslandConfig.Field
-
 Fields represent data inputs in the UI:
-
 - `name`: Programmatic field identifier
 - `label`: Human-readable label
 - `type`: Field type (`"string"`, `"boolean"`, `"json"`)
@@ -278,9 +216,7 @@ Fields represent data inputs in the UI:
 - `options`: Available options for selection (optional)
 
 #### IslandConfig.Action
-
 Actions represent buttons or operations:
-
 - `name`: Programmatic action identifier
 - `label`: Human-readable button label
 - `type`: UI element type (typically `"button"`)
@@ -288,18 +224,14 @@ Actions represent buttons or operations:
 - `operation`: Operation type (default: `"create"`)
 
 #### IslandConfig
-
 Contains the complete island configuration:
-
 - `fields`: List of IslandConfig.Field objects
 - `actions`: List of IslandConfig.Action objects
 - `type`: Island type for UI rendering (optional, default: `None`)
 - `icon`: Icon to display in the island (optional, default: `None`)
 
 #### IslandResponse
-
 The response wrapper for islands:
-
 - Use `IslandResponse.create([islands])` to create responses
 - Supports multiple islands per response
 
@@ -308,41 +240,20 @@ The response wrapper for islands:
 The SDK provides several TypedDict and dataclass definitions for better type safety:
 
 ### Authentication Types
-
 - `AuthData`: TypedDict containing provider and credentials information
 - `Credentials`: TypedDict with access_token, org_sso_id, customer_id, instance_id, and product_sku
 - `AuthRequirement`: Dataclass for specifying authentication requirements
 
 ### Execution Environment
-
 - `Environment`: TypedDict specifying execution mode (`"headless"` or `"interactive"`)
 
 ### Parameter Types
-
 - `ParameterType`: Enum for supported parameter types (string, integer, number, boolean, list, dictionary)
 - `Parameter`: Dataclass for tool parameter definitions
 - `Function`: Dataclass for complete tool function definitions
 
 These types are automatically imported when you import from `opal_tools_sdk` and provide better IDE support and type checking.
 
-## Code Generation
-
-The Block Document types is automatically generated from the JSON schema for full type safety and Pydantic validation.
-
-### Generating Types
-
-To use the code generation:
-
-```bash
-# Install dev dependencies
-pip install -e ".[dev]"
-
-# Generate types from schema
-make generate-block
-```
-
-This generates Pydantic v2 models from `block-document-spec.json` to `opal_tools_sdk/block.py` with builder methods included.
-
 ## Documentation
 
 See full documentation for more examples and configuration options.

{optimizely_opal_opal_tools_sdk-0.1.12.dev0 → optimizely_opal_opal_tools_sdk-0.1.14.dev0}/README.md

@@ -9,8 +9,7 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 - Parameter validation and type checking
 - Authentication helpers
 - FastAPI integration
-- **Adaptive Blocks** for interactive forms and UI flows (new!)
-- Island components for interactive UI responses (legacy)
+- Island components for interactive UI responses
 
 ## Installation
 
@@ -22,7 +21,7 @@ Note: While the package is installed as `optimizely-opal.opal-tools-sdk`, you'll
 
 ```python
 # Import using the package name
-from opal_tools_sdk import ToolsService, tool, Block, BlockResponse, IslandResponse, IslandConfig
+from opal_tools_sdk import ToolsService, tool, IslandResponse, IslandConfig
 ```
 
 ## Usage
@@ -47,65 +46,6 @@ async def get_weather(parameters: WeatherParameters):
 # Discovery endpoint is automatically created at /discovery
 ```
 
-## Adaptive Blocks
-
-Adaptive Blocks provide an interactive UI framework for tools to capture user input directly through forms, rather than having the LLM gather parameters through chat messages.
-
-### Basic Example
-
-```python
-from opal_tools_sdk import Block, BlockResponse, tool
-from pydantic import BaseModel, Field
-
-class MyToolParams(BaseModel):
-    user_input: str | None = Field(default=None, description="User input")
-
-@tool(
-    name="my_tool",
-    description="Example tool with Block Document",
-    type="block"  # Important: Specify type="block"
-)
-async def my_tool(params: MyToolParams) -> BlockResponse:
-    # If parameters are missing, show a form
-    if not params.user_input:
-        return BlockResponse(
-            content=Block.Document(
-                children=[
-                    Block.Heading(children="Enter Details", level="2"),
-                    Block.Field(
-                        label="User Input",
-                        required=True,
-                        children=Block.Input(
-                            name="user_input",
-                            placeholder="Enter something..."
-                        )
-                    ),
-                ],
-                actions=[
-                    Block.Action(name="submit", children="Submit"),
-                    Block.CancelAction(children="Cancel")
-                ],
-                blocking=True  # Hide chat prompt, force form interaction
-            )
-        )
-
-    # Process the input and return as Block Document
-    return BlockResponse(
-        content=Block.Document(
-            children=[
-                Block.Heading(children="Result", level="2"),
-                Block.Text(children=f"You entered: {params.user_input}")
-            ]
-        )
-    )
-```
-
-**Important:** When using `type="block"`, the function MUST:
-
-1. Have a return type annotation of `-> BlockResponse`
-2. Always return a `BlockResponse` object (even for success/error cases)
-3. Wrap all responses in `Block.Document()` for consistency
-
 ## Authentication
 
 The SDK provides two ways to require authentication for your tools:
@@ -146,7 +86,7 @@ async def get_calendar_events(parameters: CalendarParameters, auth_data: Optiona
 async def get_calendar_availability(parameters: CalendarParameters, auth_data: Optional[AuthData] = None):
     provider = ""
     token = ""
-
+    
     if auth_data:
         provider = auth_data["provider"]
         token = auth_data["credentials"]["access_token"]
@@ -198,7 +138,7 @@ class WeatherParameters(BaseModel):
 async def get_weather(parameters: WeatherParameters):
     # Get weather data (implementation details omitted)
     weather_data = {"temperature": 22, "condition": "sunny", "humidity": 65}
-
+    
     # Create an interactive island for weather settings
     island = IslandConfig(
         fields=[
@@ -232,16 +172,14 @@ async def get_weather(parameters: WeatherParameters):
             )
         ]
     )
-
+    
     return IslandResponse.create([island])
 ```
 
 ### Island Components
 
 #### IslandConfig.Field
-
 Fields represent data inputs in the UI:
-
 - `name`: Programmatic field identifier
 - `label`: Human-readable label
 - `type`: Field type (`"string"`, `"boolean"`, `"json"`)
@@ -250,9 +188,7 @@ Fields represent data inputs in the UI:
 - `options`: Available options for selection (optional)
 
 #### IslandConfig.Action
-
 Actions represent buttons or operations:
-
 - `name`: Programmatic action identifier
 - `label`: Human-readable button label
 - `type`: UI element type (typically `"button"`)
@@ -260,18 +196,14 @@ Actions represent buttons or operations:
 - `operation`: Operation type (default: `"create"`)
 
 #### IslandConfig
-
 Contains the complete island configuration:
-
 - `fields`: List of IslandConfig.Field objects
 - `actions`: List of IslandConfig.Action objects
 - `type`: Island type for UI rendering (optional, default: `None`)
 - `icon`: Icon to display in the island (optional, default: `None`)
 
 #### IslandResponse
-
 The response wrapper for islands:
-
 - Use `IslandResponse.create([islands])` to create responses
 - Supports multiple islands per response
 
@@ -280,41 +212,20 @@ The response wrapper for islands:
 The SDK provides several TypedDict and dataclass definitions for better type safety:
 
 ### Authentication Types
-
 - `AuthData`: TypedDict containing provider and credentials information
 - `Credentials`: TypedDict with access_token, org_sso_id, customer_id, instance_id, and product_sku
 - `AuthRequirement`: Dataclass for specifying authentication requirements
 
 ### Execution Environment
-
 - `Environment`: TypedDict specifying execution mode (`"headless"` or `"interactive"`)
 
 ### Parameter Types
-
 - `ParameterType`: Enum for supported parameter types (string, integer, number, boolean, list, dictionary)
 - `Parameter`: Dataclass for tool parameter definitions
 - `Function`: Dataclass for complete tool function definitions
 
 These types are automatically imported when you import from `opal_tools_sdk` and provide better IDE support and type checking.
 
-## Code Generation
-
-The Block Document types is automatically generated from the JSON schema for full type safety and Pydantic validation.
-
-### Generating Types
-
-To use the code generation:
-
-```bash
-# Install dev dependencies
-pip install -e ".[dev]"
-
-# Generate types from schema
-make generate-block
-```
-
-This generates Pydantic v2 models from `block-document-spec.json` to `opal_tools_sdk/block.py` with builder methods included.
-
 ## Documentation
 
 See full documentation for more examples and configuration options.

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

@@ -1,14 +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 .block import Block, BlockResponse
+from .proteus import UI
 
-__version__ = "0.1.0"
+__version__ = "0.1.14-dev"
 __all__ = [
     "ToolsService",
     "tool",
+    "resource",
     "requires_auth",
     "register_logger_factory",
     # Models
@@ -18,7 +19,6 @@ __all__ = [
     "Environment",
     "IslandConfig",
     "IslandResponse",
-    # Block
-    "Block",
-    "BlockResponse",
+    # UI
+    "UI",
 ]

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

@@ -14,7 +14,7 @@ def tool(
     name: str,
     description: str,
     auth_requirements: Optional[List[Dict[str, Any]]] = None,
-    type: str = "json",
+    ui_resource: Optional[str] = None,
 ):
     """Decorator to register a function as an Opal tool.
 
@@ -24,7 +24,8 @@ def tool(
         auth_requirements: Authentication requirements (optional)
             Format: [{"provider": "oauth_provider", "scope_bundle": "permissions_scope", "required": True}, ...]
             Example: [{"provider": "google", "scope_bundle": "calendar", "required": True}]
-        type: Response type - 'json' (default) or 'block' for Block Documents (Adaptive Blocks)
+        ui_resource: URI of associated UI resource for dynamic rendering (optional)
+            Example: "ui://my-app/create-form"
 
     Returns:
         Decorator function
@@ -34,7 +35,8 @@ def tool(
         async def my_tool(parameters: ParametersModel, auth_data: Optional[Dict] = None):
             ...
 
-        If type='block', the tool should return a BlockResponse object.
+        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
@@ -161,7 +163,86 @@ def tool(
                 parameters=parameters,
                 endpoint=endpoint,
                 auth_requirements=auth_req_list,
-                response_type=type
+                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.12.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