optimizely-opal.opal-tools-sdk 0.1.27.dev0__tar.gz → 0.1.30.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.27.dev0 → optimizely_opal_opal_tools_sdk-0.1.30.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.27.dev0
+Version: 0.1.30.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely
@@ -19,9 +19,11 @@ 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: datamodel-code-generator>=0.56.0; extra == "dev"
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: requires-python
@@ -144,6 +146,78 @@ async def get_email(parameters: EmailParameters, auth_data: Optional[AuthData] =
     return {"emails": ["Email 1", "Email 2"]}
 ```
 
+## Interactions
+
+Interactions are app-only handlers — actions callable from the UI but hidden from the LLM. Use them when a tool surface needs to expose a button, form submit, or other follow-up action that the model should not be able to call. They follow the MCP "app-only tools" pattern (`visibility: ["app"]`) and are not listed in the `/discovery` endpoint.
+
+**When to use `@interaction` vs `@tool`:**
+
+- Use `@tool` when the LLM should be able to call the function on its own.
+- Use `@interaction` when only the UI (action cards, islands) should call it — the model should never see it.
+
+### Declaring an interaction
+
+```python
+from typing import Optional
+from opal_tools_sdk import ToolsService, interaction, InteractionContext
+from pydantic import BaseModel, Field
+from fastapi import FastAPI
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+
+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 validated against TaskFormInput
+    # context.auth_data carries credentials when auth is configured
+    return {"task_id": "task-123", "message": f"Task '{parameters.title}' created"}
+```
+
+The first parameter is introspected from the Pydantic model the same way `@tool` does it (typing the parameter as `dict` skips schema extraction). The second parameter is an `InteractionContext`.
+
+### Handler signature & `InteractionContext`
+
+`InteractionContext` carries the auth data resolved by TMS from the parent tool's `auth_requirements`:
+
+```python
+@dataclass
+class InteractionContext:
+    auth_data: AuthData | None = None
+```
+
+If the parent tool did not declare auth requirements (or no credentials are available), `context.auth_data` is `None`.
+
+### Generated endpoint
+
+The SDK exposes a single shared endpoint for all interactions:
+
+```
+POST /interactions/execute
+Content-Type: application/json
+
+{
+  "name": "submit_task_form",
+  "parameters": {"title": "Ship docs", "priority": "high"},
+  "auth": {"provider": "...", "credentials": {...}}
+}
+```
+
+The response is whatever the handler returns, serialized as JSON. Interactions are **not** listed in `/discovery`.
+
+### Name uniqueness
+
+Interaction names must be unique across both tools and interactions in the same service, since both can be exported as MCP tools. Registering an interaction with a name that conflicts with an existing tool or interaction raises `ValueError`.
+
 ## Island Components
 
 The SDK includes Island components for creating interactive UI responses that allow users to input data and trigger actions.
@@ -235,6 +309,120 @@ The response wrapper for islands:
 - Use `IslandResponse.create([islands])` to create responses
 - Supports multiple islands per response
 
+## Resources & Proteus UI
+
+The SDK supports defining MCP resources that serve dynamic UI specifications using the Proteus framework. This enables tools to render rich, interactive interfaces without hardcoded frontend integrations.
+
+For the full Proteus component reference and visual designer, see the [Proteus documentation](https://optimizely-axiom.github.io/optiaxiom/guides/proteus/).
+
+### Defining a Resource with `@resource`
+
+Use the `@resource` decorator to register a function as an MCP resource:
+
+```python
+from opal_tools_sdk import UI
+from opal_tools_sdk.decorators import resource
+
+@resource(
+    uri="ui://my-app/create-form",
+    name="create-form",
+    description="Form for creating new items",
+)
+async def get_create_form():
+    return UI.Document(
+        title="Create Item",
+        body=[
+            UI.Heading(children="New Item"),
+            UI.Field(
+                label="Item Name",
+                children=UI.Input(name="item_name", placeholder="Enter item name"),
+            ),
+            UI.Field(
+                label="Description",
+                children=UI.Textarea(name="description", placeholder="Enter description"),
+            ),
+        ],
+        actions=[
+            UI.Action(children="Save", appearance="primary"),
+            UI.CancelAction(children="Cancel"),
+        ],
+    )
+```
+
+**Parameters:**
+- `uri` (required): Unique URI for the resource (e.g., `"ui://my-app/create-form"`)
+- `name` (required): Name of the resource
+- `description` (optional): Description of the resource
+- `mime_type` (optional): MIME type of the content. Auto-set to `"application/vnd.opal.proteus+json"` when returning a `UI.Document`
+- `title` (optional): Human-readable title
+
+The handler function can return either a `str` (manual JSON serialization) or a `UI.Document` (automatic serialization with MIME type set automatically).
+
+### Linking a Tool to a UI Resource
+
+Use the `ui_resource` parameter on `@tool` to associate a tool with a Proteus UI resource. The frontend fetches and renders the resource when the tool is invoked:
+
+```python
+from opal_tools_sdk import tool
+from pydantic import BaseModel, Field
+
+class CreateItemParams(BaseModel):
+    item_name: str = Field(description="Name of the item")
+    description: str = Field(description="Item description")
+
+@tool(
+    "create_item",
+    "Create a new item",
+    ui_resource="ui://my-app/create-form",
+)
+async def create_item(parameters: CreateItemParams):
+    return {"id": "item-123", "name": parameters.item_name, "status": "created"}
+```
+
+### Building UI with `UI.Document`
+
+Import the `UI` namespace from `opal_tools_sdk` or `opal_tools_sdk.ui`. It provides type-safe builders for all Proteus components:
+
+```python
+from opal_tools_sdk import UI
+```
+
+**Available components:**
+
+| Category | Components |
+|----------|-----------|
+| Layout | `UI.Document`, `UI.Group`, `UI.Card`, `UI.CardHeader`, `UI.CardLink`, `UI.Separator` |
+| Typography | `UI.Heading`, `UI.Text`, `UI.Link` |
+| Data Display | `UI.Avatar`, `UI.Badge`, `UI.DataTable`, `UI.Chart`, `UI.IconCalendar`, `UI.Image`, `UI.ImageCarousel`, `UI.Time` |
+| Form Controls | `UI.Field`, `UI.Input`, `UI.Textarea`, `UI.Select`, `UI.SelectTrigger`, `UI.SelectContent`, `UI.Switch`, `UI.Range`, `UI.Question` |
+| Actions | `UI.Action`, `UI.CancelAction` |
+| Dynamic | `UI.Value`, `UI.Map`, `UI.MapIndex`, `UI.Show`, `UI.Concat`, `UI.Zip` |
+
+**Data binding** with `UI.Value` resolves paths from the tool response:
+
+```python
+@resource(uri="ui://my-app/results", name="results")
+async def get_results():
+    return UI.Document(
+        title=UI.Value(path="/title"),
+        body=UI.Map(
+            path="/items",
+            children=UI.Text(children=UI.Value(path="name")),
+        ),
+    )
+```
+
+**Conditional rendering** with `UI.Show`:
+
+```python
+UI.Show(
+    when={"!!": UI.Value(path="/error")},
+    children=UI.Text(children="An error occurred", color="fg.error"),
+)
+```
+
+The MIME type constant is available as `UI.MIME_TYPE` (`"application/vnd.opal.proteus+json"`).
+
 ## Type Definitions
 
 The SDK provides several TypedDict and dataclass definitions for better type safety:

{optimizely_opal_opal_tools_sdk-0.1.27.dev0 → optimizely_opal_opal_tools_sdk-0.1.30.dev0}/README.md

@@ -116,6 +116,78 @@ async def get_email(parameters: EmailParameters, auth_data: Optional[AuthData] =
     return {"emails": ["Email 1", "Email 2"]}
 ```
 
+## Interactions
+
+Interactions are app-only handlers — actions callable from the UI but hidden from the LLM. Use them when a tool surface needs to expose a button, form submit, or other follow-up action that the model should not be able to call. They follow the MCP "app-only tools" pattern (`visibility: ["app"]`) and are not listed in the `/discovery` endpoint.
+
+**When to use `@interaction` vs `@tool`:**
+
+- Use `@tool` when the LLM should be able to call the function on its own.
+- Use `@interaction` when only the UI (action cards, islands) should call it — the model should never see it.
+
+### Declaring an interaction
+
+```python
+from typing import Optional
+from opal_tools_sdk import ToolsService, interaction, InteractionContext
+from pydantic import BaseModel, Field
+from fastapi import FastAPI
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+
+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 validated against TaskFormInput
+    # context.auth_data carries credentials when auth is configured
+    return {"task_id": "task-123", "message": f"Task '{parameters.title}' created"}
+```
+
+The first parameter is introspected from the Pydantic model the same way `@tool` does it (typing the parameter as `dict` skips schema extraction). The second parameter is an `InteractionContext`.
+
+### Handler signature & `InteractionContext`
+
+`InteractionContext` carries the auth data resolved by TMS from the parent tool's `auth_requirements`:
+
+```python
+@dataclass
+class InteractionContext:
+    auth_data: AuthData | None = None
+```
+
+If the parent tool did not declare auth requirements (or no credentials are available), `context.auth_data` is `None`.
+
+### Generated endpoint
+
+The SDK exposes a single shared endpoint for all interactions:
+
+```
+POST /interactions/execute
+Content-Type: application/json
+
+{
+  "name": "submit_task_form",
+  "parameters": {"title": "Ship docs", "priority": "high"},
+  "auth": {"provider": "...", "credentials": {...}}
+}
+```
+
+The response is whatever the handler returns, serialized as JSON. Interactions are **not** listed in `/discovery`.
+
+### Name uniqueness
+
+Interaction names must be unique across both tools and interactions in the same service, since both can be exported as MCP tools. Registering an interaction with a name that conflicts with an existing tool or interaction raises `ValueError`.
+
 ## Island Components
 
 The SDK includes Island components for creating interactive UI responses that allow users to input data and trigger actions.
@@ -207,6 +279,120 @@ The response wrapper for islands:
 - Use `IslandResponse.create([islands])` to create responses
 - Supports multiple islands per response
 
+## Resources & Proteus UI
+
+The SDK supports defining MCP resources that serve dynamic UI specifications using the Proteus framework. This enables tools to render rich, interactive interfaces without hardcoded frontend integrations.
+
+For the full Proteus component reference and visual designer, see the [Proteus documentation](https://optimizely-axiom.github.io/optiaxiom/guides/proteus/).
+
+### Defining a Resource with `@resource`
+
+Use the `@resource` decorator to register a function as an MCP resource:
+
+```python
+from opal_tools_sdk import UI
+from opal_tools_sdk.decorators import resource
+
+@resource(
+    uri="ui://my-app/create-form",
+    name="create-form",
+    description="Form for creating new items",
+)
+async def get_create_form():
+    return UI.Document(
+        title="Create Item",
+        body=[
+            UI.Heading(children="New Item"),
+            UI.Field(
+                label="Item Name",
+                children=UI.Input(name="item_name", placeholder="Enter item name"),
+            ),
+            UI.Field(
+                label="Description",
+                children=UI.Textarea(name="description", placeholder="Enter description"),
+            ),
+        ],
+        actions=[
+            UI.Action(children="Save", appearance="primary"),
+            UI.CancelAction(children="Cancel"),
+        ],
+    )
+```
+
+**Parameters:**
+- `uri` (required): Unique URI for the resource (e.g., `"ui://my-app/create-form"`)
+- `name` (required): Name of the resource
+- `description` (optional): Description of the resource
+- `mime_type` (optional): MIME type of the content. Auto-set to `"application/vnd.opal.proteus+json"` when returning a `UI.Document`
+- `title` (optional): Human-readable title
+
+The handler function can return either a `str` (manual JSON serialization) or a `UI.Document` (automatic serialization with MIME type set automatically).
+
+### Linking a Tool to a UI Resource
+
+Use the `ui_resource` parameter on `@tool` to associate a tool with a Proteus UI resource. The frontend fetches and renders the resource when the tool is invoked:
+
+```python
+from opal_tools_sdk import tool
+from pydantic import BaseModel, Field
+
+class CreateItemParams(BaseModel):
+    item_name: str = Field(description="Name of the item")
+    description: str = Field(description="Item description")
+
+@tool(
+    "create_item",
+    "Create a new item",
+    ui_resource="ui://my-app/create-form",
+)
+async def create_item(parameters: CreateItemParams):
+    return {"id": "item-123", "name": parameters.item_name, "status": "created"}
+```
+
+### Building UI with `UI.Document`
+
+Import the `UI` namespace from `opal_tools_sdk` or `opal_tools_sdk.ui`. It provides type-safe builders for all Proteus components:
+
+```python
+from opal_tools_sdk import UI
+```
+
+**Available components:**
+
+| Category | Components |
+|----------|-----------|
+| Layout | `UI.Document`, `UI.Group`, `UI.Card`, `UI.CardHeader`, `UI.CardLink`, `UI.Separator` |
+| Typography | `UI.Heading`, `UI.Text`, `UI.Link` |
+| Data Display | `UI.Avatar`, `UI.Badge`, `UI.DataTable`, `UI.Chart`, `UI.IconCalendar`, `UI.Image`, `UI.ImageCarousel`, `UI.Time` |
+| Form Controls | `UI.Field`, `UI.Input`, `UI.Textarea`, `UI.Select`, `UI.SelectTrigger`, `UI.SelectContent`, `UI.Switch`, `UI.Range`, `UI.Question` |
+| Actions | `UI.Action`, `UI.CancelAction` |
+| Dynamic | `UI.Value`, `UI.Map`, `UI.MapIndex`, `UI.Show`, `UI.Concat`, `UI.Zip` |
+
+**Data binding** with `UI.Value` resolves paths from the tool response:
+
+```python
+@resource(uri="ui://my-app/results", name="results")
+async def get_results():
+    return UI.Document(
+        title=UI.Value(path="/title"),
+        body=UI.Map(
+            path="/items",
+            children=UI.Text(children=UI.Value(path="name")),
+        ),
+    )
+```
+
+**Conditional rendering** with `UI.Show`:
+
+```python
+UI.Show(
+    when={"!!": UI.Value(path="/error")},
+    children=UI.Text(children="An error occurred", color="fg.error"),
+)
+```
+
+The MIME type constant is available as `UI.MIME_TYPE` (`"application/vnd.opal.proteus+json"`).
+
 ## Type Definitions
 
 The SDK provides several TypedDict and dataclass definitions for better type safety:

{optimizely_opal_opal_tools_sdk-0.1.27.dev0 → optimizely_opal_opal_tools_sdk-0.1.30.dev0}/opal_tools_sdk/__init__.py

@@ -1,9 +1,17 @@
-from .service import ToolsService
-from .decorators import tool, resource, interaction
 from .auth import requires_auth
+from .decorators import interaction, resource, tool
 from .logging import register_logger_factory
-from .models import AuthData, AuthRequirement, Credentials, Environment, InteractionContext, IslandConfig, IslandResponse
+from .models import (
+    AuthData,
+    AuthRequirement,
+    Credentials,
+    Environment,
+    InteractionContext,
+    IslandConfig,
+    IslandResponse,
+)
 from .proteus import UI
+from .service import ToolsService
 
 __version__ = "0.1.14-dev"
 __all__ = [

{optimizely_opal_opal_tools_sdk-0.1.27.dev0 → optimizely_opal_opal_tools_sdk-0.1.30.dev0}/opal_tools_sdk/_registry.py

@@ -1,3 +1,5 @@
 """Internal registry for ToolsService instances."""
 
-services = []
+from typing import Any
+
+services: list[Any] = []

{optimizely_opal_opal_tools_sdk-0.1.27.dev0 → optimizely_opal_opal_tools_sdk-0.1.30.dev0}/opal_tools_sdk/auth.py

@@ -1,7 +1,9 @@
-from typing import Callable, Dict, Any, Optional, List
+from collections.abc import Callable
 from functools import wraps
+
 from fastapi import Header, HTTPException
 
+
 def requires_auth(provider: str, scope_bundle: str, required: bool = True):
     """Decorator to indicate that a tool requires authentication.
 
@@ -13,9 +15,10 @@ def requires_auth(provider: str, scope_bundle: str, required: bool = True):
     Returns:
         Decorator function
     """
+
     def decorator(func: Callable):
         @wraps(func)
-        async def wrapper(*args, authorization: Optional[str] = Header(None), **kwargs):
+        async def wrapper(*args, authorization: str | None = Header(None), **kwargs):
             if required and not authorization:
                 raise HTTPException(status_code=401, detail="Authentication required")
 
@@ -24,18 +27,14 @@ def requires_auth(provider: str, scope_bundle: str, required: bool = True):
             return await func(*args, authorization=authorization, **kwargs)
 
         # Store auth requirements in function metadata
-        auth_req = {
-            "provider": provider,
-            "scope_bundle": scope_bundle,
-            "required": required
-        }
+        auth_req = {"provider": provider, "scope_bundle": scope_bundle, "required": required}
 
         # Initialize the list if it doesn't exist
         if not hasattr(wrapper, "__auth_requirements__"):
-            wrapper.__auth_requirements__ = []
+            wrapper.__auth_requirements__ = []  # type: ignore[attr-defined]
 
         # Add this auth requirement to the list
-        wrapper.__auth_requirements__.append(auth_req)
+        wrapper.__auth_requirements__.append(auth_req)  # type: ignore[attr-defined]
 
         return wrapper