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

{optimizely_opal_opal_tools_sdk-0.1.10.dev0 → optimizely_opal_opal_tools_sdk-0.1.12.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.10.dev0
+Version: 0.1.12.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
@@ -33,7 +37,8 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 - Parameter validation and type checking
 - Authentication helpers
 - FastAPI integration
-- Island components for interactive UI responses
+- **Adaptive Blocks** for interactive forms and UI flows (new!)
+- Island components for interactive UI responses (legacy)
 
 ## Installation
 
@@ -45,7 +50,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, IslandResponse, IslandConfig
+from opal_tools_sdk import ToolsService, tool, Block, BlockResponse, IslandResponse, IslandConfig
 ```
 
 ## Usage
@@ -70,6 +75,65 @@ 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:
@@ -110,7 +174,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"]
@@ -162,7 +226,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=[
@@ -196,14 +260,16 @@ 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"`)
@@ -212,7 +278,9 @@ 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"`)
@@ -220,14 +288,18 @@ 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
 
@@ -236,20 +308,41 @@ 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.10.dev0 → optimizely_opal_opal_tools_sdk-0.1.12.dev0}/README.md

@@ -9,7 +9,8 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 - Parameter validation and type checking
 - Authentication helpers
 - FastAPI integration
-- Island components for interactive UI responses
+- **Adaptive Blocks** for interactive forms and UI flows (new!)
+- Island components for interactive UI responses (legacy)
 
 ## Installation
 
@@ -21,7 +22,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, IslandResponse, IslandConfig
+from opal_tools_sdk import ToolsService, tool, Block, BlockResponse, IslandResponse, IslandConfig
 ```
 
 ## Usage
@@ -46,6 +47,65 @@ 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:
@@ -86,7 +146,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"]
@@ -138,7 +198,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=[
@@ -172,14 +232,16 @@ 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"`)
@@ -188,7 +250,9 @@ 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"`)
@@ -196,14 +260,18 @@ 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
 
@@ -212,20 +280,41 @@ 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.10.dev0 → optimizely_opal_opal_tools_sdk-0.1.12.dev0}/opal_tools_sdk/__init__.py

@@ -3,6 +3,7 @@ from .decorators import tool
 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
 
 __version__ = "0.1.0"
 __all__ = [
@@ -17,4 +18,7 @@ __all__ = [
     "Environment",
     "IslandConfig",
     "IslandResponse",
+    # Block
+    "Block",
+    "BlockResponse",
 ]