optimizely-opal.opal-tools-sdk 0.1.26.dev0__tar.gz → 0.1.28.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.26.dev0 → optimizely_opal_opal_tools_sdk-0.1.28.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.26.dev0
+Version: 0.1.28.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely
@@ -235,6 +235,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.26.dev0 → optimizely_opal_opal_tools_sdk-0.1.28.dev0}/README.md

@@ -207,6 +207,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.26.dev0 → optimizely_opal_opal_tools_sdk-0.1.28.dev0}/opal_tools_sdk/proteus.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  proteus-document-spec.json
-#   timestamp: 2026-04-17T20:57:26+00:00
+#   timestamp: 2026-04-27T14:20:49+00:00
 
 from __future__ import annotations
 
@@ -22,6 +22,9 @@ class ProteusEventHandler1(BaseModel):
         extra='forbid',
     )
     interaction: str = Field(..., description='Name of registered interaction to call')
+    params: dict[str, Any] | None = Field(
+        default=None, description='Parameters to pass to the interaction handler'
+    )
 
 
 class Series(BaseModel):
@@ -276,6 +279,10 @@ class ProteusDocument(BaseModel):
         description='If true, hides chat prompt and forces user interaction with document. User can press ESC or close to abandon.',
     )
     body: ProteusNode | None = Field(..., description='The main content of the document.')
+    compact: bool | None = Field(
+        default=None,
+        description='If true, constrains the body to a max height and makes it scrollable when content overflows.',
+    )
     subtitle: ProteusNode | None = Field(
         default=None,
         description="A brief description or tagline that provides additional context about the Proteus document's purpose.",
@@ -588,6 +595,22 @@ class ProteusBadge(BaseModel):
     z: SprinklePropZ | None = None
 
 
+class ProteusBridge(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    field_type: Literal['Bridge'] = Field(default='Bridge', alias='$type')
+    fallback: ProteusNode | None = Field(
+        default=None,
+        description="Content rendered on platforms without iframe support (Teams, Slack, mobile). If omitted, a default 'View in Opal web' message is shown.",
+    )
+    height: float | None = Field(default=None, description='Height of the iframe in pixels')
+    resource: str = Field(
+        ...,
+        description="Resource URI identifying the MCP app to render (e.g., 'ui://sample-widget')",
+    )
+
+
 class ProteusButton(BaseModel):
     model_config = ConfigDict(
         extra='forbid',
@@ -918,7 +941,7 @@ class ProteusDataTable(BaseModel):
         extra='forbid',
     )
     field_type: Literal['DataTable'] = Field(default='DataTable', alias='$type')
-    columns: list[Column] | None = Field(default=None, description='Column definitions')
+    columns: list[Column] | ProteusExpression | None = None
     data: list[dict[str, Any]] | ProteusExpression | ProteusZip | None = None
 
 
@@ -2166,6 +2189,7 @@ class ProteusElement(
         ProteusAction
         | ProteusAvatar
         | ProteusBadge
+        | ProteusBridge
         | ProteusButton
         | ProteusCard
         | ProteusCardHeader
@@ -2201,6 +2225,7 @@ class ProteusElement(
         ProteusAction
         | ProteusAvatar
         | ProteusBadge
+        | ProteusBridge
         | ProteusButton
         | ProteusCard
         | ProteusCardHeader
@@ -3877,6 +3902,7 @@ ProteusZip.model_rebuild()
 ProteusAction.model_rebuild()
 ProteusAvatar.model_rebuild()
 ProteusBadge.model_rebuild()
+ProteusBridge.model_rebuild()
 ProteusButton.model_rebuild()
 ProteusCard.model_rebuild()
 ProteusCardHeader.model_rebuild()
@@ -3921,6 +3947,7 @@ class UI:
     Action = ProteusAction
     Avatar = ProteusAvatar
     Badge = ProteusBadge
+    Bridge = ProteusBridge
     Button = ProteusButton
     Card = ProteusCard
     CardHeader = ProteusCardHeader

{optimizely_opal_opal_tools_sdk-0.1.26.dev0 → optimizely_opal_opal_tools_sdk-0.1.28.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.26.dev0
+Version: 0.1.28.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely
@@ -235,6 +235,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.26.dev0 → optimizely_opal_opal_tools_sdk-0.1.28.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optimizely-opal.opal-tools-sdk"
-version = "0.1.26-dev"
+version = "0.1.28-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.26.dev0 → optimizely_opal_opal_tools_sdk-0.1.28.dev0}/setup.py

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