optimizely-opal.opal-tools-sdk 0.1.21.dev0__tar.gz → 0.1.23.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.21.dev0
+Version: 0.1.23.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/opal_tools_sdk/__init__.py

@@ -1,8 +1,8 @@
 from .service import ToolsService
-from .decorators import tool, resource
+from .decorators import tool, resource, interaction
 from .auth import requires_auth
 from .logging import register_logger_factory
-from .models import AuthData, AuthRequirement, Credentials, Environment, IslandConfig, IslandResponse
+from .models import AuthData, AuthRequirement, Credentials, Environment, InteractionContext, IslandConfig, IslandResponse
 from .proteus import UI
 
 __version__ = "0.1.14-dev"
@@ -10,6 +10,7 @@ __all__ = [
     "ToolsService",
     "tool",
     "resource",
+    "interaction",
     "requires_auth",
     "register_logger_factory",
     # Models
@@ -17,6 +18,7 @@ __all__ = [
     "AuthRequirement",
     "Credentials",
     "Environment",
+    "InteractionContext",
     "IslandConfig",
     "IslandResponse",
     # UI

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/opal_tools_sdk/decorators.py

@@ -279,6 +279,137 @@ def tool(
     return decorator
 
 
+def interaction(
+    name: str,
+    description: str = "",
+):
+    """Decorator to register a function as an interaction handler.
+
+    Interactions are app-only handlers — actions callable by the UI but hidden from the model.
+    They follow the MCP app-only tools pattern (visibility: ["app"]).
+
+    Args:
+        name: Name of the interaction. Must be unique across both tools and interactions
+            within the same service, since both may be exported as MCP tools.
+        description: Description of the interaction
+
+    Returns:
+        Decorator function
+
+    Note:
+        The handler's first parameter can be a Pydantic model defining the interaction's
+        input schema — the same pattern as @tool. The decorator introspects the model fields
+        to extract parameter definitions (type, description, required). If the first parameter
+        is typed as `dict`, no schema extraction is performed.
+
+    Example:
+        class TaskFormInput(BaseModel):
+            title: str = Field(description="Task title")
+            priority: str = Field(default="medium", description="Task priority")
+            assignee: Optional[str] = Field(default=None, description="Assignee email")
+
+        @interaction(
+            name="submit_task_form",
+            description="Handle task form submission"
+        )
+        async def handle_task_submission(parameters: TaskFormInput, context: InteractionContext):
+            # parameters is already validated and typed
+            task_id = await create_task(parameters.title, parameters.priority)
+            return {"task_id": task_id}
+    """
+    def decorator(func: Callable):
+        from . import _registry
+
+        logger.info(f"Registering interaction {name}")
+
+        # Extract parameters from Pydantic model in function signature (same as @tool)
+        sig = inspect.signature(func)
+        type_hints = get_type_hints(func)
+
+        parameters: List[Parameter] = []
+        param_model = None
+
+        for param_name, param in sig.parameters.items():
+            if param_name in type_hints:
+                param_type = type_hints[param_name]
+                if hasattr(param_type, '__fields__') or hasattr(param_type, 'model_fields'):
+                    param_model = param_type
+                    break
+
+        if param_model:
+            model_fields = getattr(param_model, 'model_fields', getattr(param_model, '__fields__', {}))
+            for field_name, field in model_fields.items():
+                field_info = field.field_info if hasattr(field, 'field_info') else field
+
+                if hasattr(field, 'outer_type_'):
+                    field_type = field.outer_type_
+                elif hasattr(field, 'annotation'):
+                    field_type = field.annotation
+                else:
+                    field_type = str
+
+                type_args = getattr(field_type, '__args__', ())
+                is_optional = get_origin(field_type) is Union and type(None) in type_args
+
+                if is_optional and type_args:
+                    field_type = next(
+                        (arg for arg in type_args if arg is not type(None)),
+                        field_type,
+                    )
+
+                param_type = ParameterType.string
+                if field_type is int:
+                    param_type = ParameterType.integer
+                elif field_type is float:
+                    param_type = ParameterType.number
+                elif field_type is bool:
+                    param_type = ParameterType.boolean
+                elif field_type is list or get_origin(field_type) is list:
+                    param_type = ParameterType.list
+                elif field_type is dict or get_origin(field_type) is dict:
+                    param_type = ParameterType.dictionary
+
+                field_info_extra = getattr(field_info, "json_schema_extra") or {}
+                if "required" in field_info_extra:
+                    required = field_info_extra["required"]
+                elif is_optional:
+                    required = False
+                elif hasattr(field_info, 'is_required'):
+                    required = field_info.is_required()
+                elif hasattr(field_info, 'default'):
+                    required = field_info.default is ...
+                else:
+                    required = True
+
+                description_text = ""
+                if hasattr(field_info, 'description'):
+                    description_text = field_info.description
+                elif hasattr(field, 'description'):
+                    description_text = field.description
+
+                parameters.append(Parameter(
+                    name=field_name,
+                    param_type=param_type,
+                    description=description_text,
+                    required=required,
+                ))
+
+        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_interaction(
+                name=name,
+                description=description,
+                handler=func,
+                parameters=parameters,
+            )
+
+        return func
+
+    return decorator
+
+
 def resource(
     uri: str,
     name: str,

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/opal_tools_sdk/models.py

@@ -71,6 +71,13 @@ class AuthData(TypedDict):
     credentials: Credentials
 
 
+@dataclass
+class InteractionContext:
+    """Context object passed to interaction handlers."""
+
+    auth_data: Optional[AuthData] = None
+
+
 class Environment(TypedDict):
     """Execution environment for an Opal tool. Interactive will provide interaction islands, while headless will not."""
 

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/opal_tools_sdk/proteus.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  proteus-document-spec.json
-#   timestamp: 2026-03-24T13:50:30+00:00
+#   timestamp: 2026-04-01T20:49:32+00:00
 
 from __future__ import annotations
 
@@ -15,38 +15,13 @@ class OpalProteusDocumentSpecification(RootModel[Any]):
 
 class ProteusEventHandler1(BaseModel):
     """
-    Server-side tool call
+    Server-side interaction call
     """
 
     model_config = ConfigDict(
         extra='forbid',
     )
-    tool: str = Field(..., description='Name of registered tool to call')
-
-
-class ProteusEventHandler2(BaseModel):
-    """
-    Client-side message action
-    """
-
-    model_config = ConfigDict(
-        extra='forbid',
-    )
-    message: str = Field(..., description='Message to send to LLM via sendNewMessage()')
-
-
-class ProteusEventHandler4(BaseModel):
-    """
-    Client-side component action - collects name/value pairs from a data array and sends as a message
-    """
-
-    model_config = ConfigDict(
-        extra='forbid',
-    )
-    action: Literal['message-from'] = Field(default='message-from', description='The action type')
-    path: str = Field(
-        ..., description='JSON pointer to an array of objects with name and value fields'
-    )
+    interaction: str = Field(..., description='Name of registered interaction to call')
 
 
 class Series(BaseModel):
@@ -1800,28 +1775,18 @@ class ProteusCondition7(BaseModel):
     )
 
 
-class ProteusEventHandler3(BaseModel):
+class ProteusCondition8(BaseModel):
     """
-    Client-side component action - for downloading a URL
+    Condition for Show component. Can be a comparison operator, logical AND, or logical OR. Supports nesting.
     """
 
     model_config = ConfigDict(
         extra='forbid',
     )
-    action: Literal['download'] = Field(default='download', description='The action type')
-    url: ProteusValue | str = Field(..., description='URL to download')
-
-
-class ProteusEventHandler(
-    RootModel[
-        ProteusEventHandler1 | ProteusEventHandler2 | ProteusEventHandler3 | ProteusEventHandler4
-    ]
-):
-    root: (
-        ProteusEventHandler1 | ProteusEventHandler2 | ProteusEventHandler3 | ProteusEventHandler4
-    ) = Field(
+    field_: str | float | bool | ProteusValue | None = Field(
         ...,
-        description='Handler for user interactions - a server-side tool call, client-side message, or client-side component action',
+        alias='!',
+        description='Falsy check - returns true if value is falsy (null, undefined, false, 0, or empty string)',
     )
 
 
@@ -2368,7 +2333,7 @@ class ProteusTime(BaseModel):
     z: SprinklePropZ | None = None
 
 
-class ProteusCondition8(BaseModel):
+class ProteusCondition9(BaseModel):
     """
     Condition for Show component. Can be a comparison operator, logical AND, or logical OR. Supports nesting.
     """
@@ -2384,7 +2349,7 @@ class ProteusCondition8(BaseModel):
     )
 
 
-class ProteusCondition9(BaseModel):
+class ProteusCondition10(BaseModel):
     """
     Condition for Show component. Can be a comparison operator, logical AND, or logical OR. Supports nesting.
     """
@@ -2432,6 +2397,34 @@ class ProteusDocument(BaseModel):
     )
 
 
+class ProteusEventHandler2(BaseModel):
+    """
+    Client-side message action
+    """
+
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    message: ProteusMap | ProteusValue | str = Field(
+        ...,
+        description='Message to send to LLM via sendNewMessage(). Can be a string, a Value reference, or a Map expression.',
+    )
+
+
+class ProteusEventHandler3(BaseModel):
+    """
+    Client-side component action - for downloading a URL
+    """
+
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    action: Literal['download'] = Field(default='download', description='The action type')
+    url: ProteusMap | ProteusValue | str = Field(
+        ..., description='URL to download, or a Map expression resolving to multiple URLs'
+    )
+
+
 class ProteusAction(BaseModel):
     model_config = ConfigDict(
         extra='forbid',
@@ -2507,6 +2500,9 @@ class ProteusAction(BaseModel):
     textAlign: SprinklePropTextAlign | None = None
     textTransform: SprinklePropTextTransform | None = None
     transition: SprinklePropTransition | None = None
+    type: Literal['button'] | Literal['reset'] | Literal['submit'] | ProteusValue | None = Field(
+        default=None, description='The default behavior of the button.'
+    )
     w: SprinklePropW | None = None
     whiteSpace: SprinklePropWhiteSpace | None = None
     z: SprinklePropZ | None = None
@@ -2958,6 +2954,17 @@ class ProteusCardLink(BaseModel):
     z: SprinklePropZ | None = None
 
 
+class ProteusConcat(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    field_type: Literal['Concat'] = Field(default='Concat', alias='$type')
+    children: list[ProteusNode | str | None] | None = Field(
+        default=None,
+        description='Array of values to concatenate into a single string. Each item is resolved and joined together.',
+    )
+
+
 class ProteusField(BaseModel):
     model_config = ConfigDict(
         extra='forbid',
@@ -3636,6 +3643,7 @@ class ProteusCondition(
         | ProteusCondition7
         | ProteusCondition8
         | ProteusCondition9
+        | ProteusCondition10
     ]
 ):
     root: (
@@ -3648,12 +3656,22 @@ class ProteusCondition(
         | ProteusCondition7
         | ProteusCondition8
         | ProteusCondition9
+        | ProteusCondition10
     ) = Field(
         ...,
         description='Condition for Show component. Can be a comparison operator, logical AND, or logical OR. Supports nesting.',
     )
 
 
+class ProteusEventHandler(
+    RootModel[ProteusEventHandler1 | ProteusEventHandler2 | ProteusEventHandler3]
+):
+    root: ProteusEventHandler1 | ProteusEventHandler2 | ProteusEventHandler3 = Field(
+        ...,
+        description='Handler for user interactions - a server-side interaction call, client-side message, or client-side component action',
+    )
+
+
 class ProteusElement(
     RootModel[
         ProteusAction
@@ -3664,6 +3682,7 @@ class ProteusElement(
         | ProteusCardHeader
         | ProteusCardLink
         | ProteusChart
+        | ProteusConcat
         | ProteusDataTable
         | ProteusField
         | ProteusGroup
@@ -3696,6 +3715,7 @@ class ProteusElement(
         | ProteusCardHeader
         | ProteusCardLink
         | ProteusChart
+        | ProteusConcat
         | ProteusDataTable
         | ProteusField
         | ProteusGroup
@@ -3746,9 +3766,11 @@ class ProteusNode(
     )
 
 
-ProteusCondition8.model_rebuild()
 ProteusCondition9.model_rebuild()
+ProteusCondition10.model_rebuild()
 ProteusDocument.model_rebuild()
+ProteusEventHandler2.model_rebuild()
+ProteusEventHandler3.model_rebuild()
 ProteusAction.model_rebuild()
 ProteusAvatar.model_rebuild()
 ProteusBadge.model_rebuild()
@@ -3756,6 +3778,7 @@ ProteusCancelAction.model_rebuild()
 ProteusCard.model_rebuild()
 ProteusCardHeader.model_rebuild()
 ProteusCardLink.model_rebuild()
+ProteusConcat.model_rebuild()
 ProteusField.model_rebuild()
 ProteusGroup.model_rebuild()
 ProteusHeading.model_rebuild()
@@ -3789,6 +3812,7 @@ class UI:
     CardHeader = ProteusCardHeader
     CardLink = ProteusCardLink
     Chart = ProteusChart
+    Concat = ProteusConcat
     DataTable = ProteusDataTable
     Document = ProteusDocument
     Field = ProteusField

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/opal_tools_sdk/service.py

@@ -6,7 +6,7 @@ from fastapi import FastAPI, APIRouter, HTTPException, Request
 from fastapi.routing import APIRoute
 from pydantic import BaseModel, ValidationError
 
-from .models import Function, Parameter, AuthRequirement
+from .models import Function, Parameter, AuthRequirement, InteractionContext
 from .proteus import ProteusDocument, UI
 from . import _registry
 
@@ -25,6 +25,7 @@ class ToolsService:
         self.app = app
         self.router = APIRouter()
         self.functions: List[Function] = []
+        self.interactions: Dict[str, Dict[str, Any]] = {}  # name -> {"handler": fn, "description": str, "parameters": List[Parameter]}
         self.resource_handlers: Dict[str, Tuple[Callable, Optional[str]]] = {}  # URI -> (handler, mime_type)
         self._init_routes()
 
@@ -98,6 +99,67 @@ class ToolsService:
                 logger.error(traceback.format_exc())
                 raise HTTPException(status_code=500, detail=str(e))
 
+        @self.router.post("/interactions/execute")
+        async def execute_interaction(request: Request):
+            """Execute an interaction by name with parameters."""
+            try:
+                body = await request.json()
+                name = body.get("name")
+                parameters = body.get("parameters", {})
+
+                if not name:
+                    raise HTTPException(status_code=400, detail="Missing 'name' field in request body")
+
+                if name not in self.interactions:
+                    raise HTTPException(status_code=404, detail=f"Interaction '{name}' not found")
+
+                interaction_info = self.interactions[name]
+                handler = interaction_info["handler"]
+
+                # Extract auth data if available
+                auth_data = body.get("auth")
+
+                # Build context object
+                context = InteractionContext(
+                    auth_data=auth_data,
+                )
+
+                # Introspect handler signature for Pydantic model (same pattern as tool endpoint)
+                sig = inspect.signature(handler)
+                type_hints = get_type_hints(handler)
+
+                param_model = None
+                for param_name, param in sig.parameters.items():
+                    if param_name in type_hints:
+                        param_type = type_hints[param_name]
+                        if hasattr(param_type, '__fields__') or hasattr(param_type, 'model_fields'):
+                            param_model = param_type
+                            break
+
+                try:
+                    if param_model:
+                        # Validate and deserialize parameters using the Pydantic model
+                        model_instance = param_model(**parameters)
+                        result = await handler(model_instance, context)
+                    else:
+                        # Fall back to raw dict
+                        result = await handler(parameters, context)
+                    return result
+                except ValidationError as e:
+                    logger.warning(f"Invalid parameters for interaction '{name}': {str(e)}")
+                    raise HTTPException(status_code=400, detail=str(e))
+                except Exception as e:
+                    logger.error(f"Interaction '{name}' failed: {e}", exc_info=True)
+                    raise HTTPException(status_code=500, detail=str(e))
+
+            except HTTPException:
+                raise
+            except Exception as e:
+                import traceback
+                logger.error(f"Error executing interaction: {str(e)}")
+                logger.error(traceback.format_exc())
+                raise HTTPException(status_code=500, detail=str(e))
+
         # Include router in app
         self.app.include_router(self.router)
 
@@ -148,6 +210,13 @@ class ToolsService:
         """
         logger.info(f"Registering tool: {name} with endpoint: {endpoint}")
 
+        # Validate name uniqueness across tools and interactions
+        if name in self.interactions:
+            raise ValueError(
+                f"Tool name '{name}' conflicts with an existing interaction name. "
+                "Tool and interaction names must be unique because both are exported as MCP tools."
+            )
+
         # Extract auth requirements from handler if decorated with @requires_auth
         handler_auth_requirements = self._extract_auth_requirements(handler)
 
@@ -263,3 +332,39 @@ class ToolsService:
 
         # Store the handler and mime_type as a tuple
         self.resource_handlers[uri] = (handler, mime_type)
+
+    def register_interaction(
+        self,
+        name: str,
+        description: str,
+        handler: Callable,
+        parameters: Optional[List[Parameter]] = None,
+    ) -> None:
+        """Register an interaction handler.
+
+        Args:
+            name: Name of the interaction. Must be unique across both tools and interactions.
+            description: Description of the interaction
+            handler: Async function that handles the interaction.
+                     Signature: async def handler(parameters: Model|dict, context: InteractionContext) -> dict
+            parameters: Parameter definitions extracted from the handler's Pydantic model
+
+        Raises:
+            ValueError: If the name conflicts with an existing tool or interaction name.
+        """
+        # Validate name uniqueness across tools and interactions
+        tool_names = {f.name for f in self.functions}
+        if name in tool_names:
+            raise ValueError(
+                f"Interaction name '{name}' conflicts with an existing tool name. "
+                "Tool and interaction names must be unique because both are exported as MCP tools."
+            )
+        if name in self.interactions:
+            raise ValueError(f"Interaction '{name}' is already registered.")
+
+        self.interactions[name] = {
+            "handler": handler,
+            "description": description,
+            "parameters": parameters or [],
+        }
+        logger.info(f"Registered interaction: {name}")

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/optimizely_opal.opal_tools_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.21.dev0
+Version: 0.1.23.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optimizely-opal.opal-tools-sdk"
-version = "0.1.21-dev"
+version = "0.1.23-dev"
 description = "SDK for creating Opal-compatible tools services"
 authors = [{ name = "Optimizely", email = "opal-team@optimizely.com" }]
 readme = "README.md"

{optimizely_opal_opal_tools_sdk-0.1.21.dev0 → optimizely_opal_opal_tools_sdk-0.1.23.dev0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="optimizely-opal.opal-tools-sdk",
-    version="0.1.21-dev",
+    version="0.1.23-dev",
     packages=find_packages(),
     install_requires=[
         "fastapi>=0.100.0",