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

optimizely_opal_opal_tools_sdk-0.1.10.dev0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: optimizely-opal.opal-tools-sdk
+Version: 0.1.10.dev0
+Summary: SDK for creating Opal-compatible tools services
+Home-page: https://github.com/optimizely/opal-tools-sdk
+Author: Optimizely
+Author-email: Optimizely <opal-team@optimizely.com>
+License: MIT
+Project-URL: Homepage, https://github.com/optimizely/opal-tools-sdk
+Project-URL: Bug Tracker, https://github.com/optimizely/opal-tools-sdk/issues
+Keywords: opal,tools,sdk,ai,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: httpx>=0.24.1
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Opal Tools SDK for Python
+
+This SDK simplifies the creation of tools services compatible with the Opal Tools Management Service.
+
+## Features
+
+- Easy definition of tool functions with decorators
+- Automatic generation of discovery endpoints
+- Parameter validation and type checking
+- Authentication helpers
+- FastAPI integration
+- Island components for interactive UI responses
+
+## Installation
+
+```bash
+pip install optimizely-opal.opal-tools-sdk
+```
+
+Note: While the package is installed as `optimizely-opal.opal-tools-sdk`, you'll still import it in your code as `opal_tools_sdk`:
+
+```python
+# Import using the package name
+from opal_tools_sdk import ToolsService, tool, IslandResponse, IslandConfig
+```
+
+## Usage
+
+```python
+from opal_tools_sdk import ToolsService, tool
+from pydantic import BaseModel
+from fastapi import FastAPI
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+class WeatherParameters(BaseModel):
+    location: str
+    units: str = "metric"
+
+@tool("get_weather", "Gets current weather for a location")
+async def get_weather(parameters: WeatherParameters):
+    # Implementation...
+    return {"temperature": 22, "condition": "sunny"}
+
+# Discovery endpoint is automatically created at /discovery
+```
+
+## Authentication
+
+The SDK provides two ways to require authentication for your tools:
+
+### 1. Using the `@requires_auth` decorator
+
+```python
+from opal_tools_sdk import ToolsService, tool, AuthData
+from opal_tools_sdk.auth import requires_auth
+from pydantic import BaseModel
+from fastapi import FastAPI
+from typing import Optional
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+class CalendarParameters(BaseModel):
+    date: str
+    timezone: str = "UTC"
+
+# Single authentication requirement
+@requires_auth(provider="google", scope_bundle="calendar", required=True)
+@tool("get_calendar_events", "Gets calendar events for a date")
+async def get_calendar_events(parameters: CalendarParameters, auth_data: Optional[AuthData] = None):
+    # The auth_data parameter contains authentication information
+    if auth_data:
+        token = auth_data["credentials"]["access_token"]
+
+    # Use the token to make authenticated requests
+    # ...
+
+    return {"events": ["Meeting at 10:00", "Lunch at 12:00"]}
+
+# Multiple authentication requirements (tool can work with either provider)
+@requires_auth(provider="google", scope_bundle="calendar", required=True)
+@requires_auth(provider="microsoft", scope_bundle="outlook", required=True)
+@tool("get_calendar_availability", "Check calendar availability")
+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"]
+
+        if provider == "google":
+            # Use Google Calendar API
+            pass
+        elif provider == "microsoft":
+            # Use Microsoft Outlook API
+            pass
+
+    return {"available": True, "provider_used": provider}
+```
+
+### 2. Specifying auth requirements in the `@tool` decorator
+
+```python
+@tool(
+    "get_email",
+    "Gets emails from the user's inbox",
+    auth_requirements=[
+        {"provider": "google", "scope_bundle": "gmail", "required": True}
+    ]
+)
+async def get_email(parameters: EmailParameters, auth_data: Optional[AuthData] = None):
+    # Implementation...
+    return {"emails": ["Email 1", "Email 2"]}
+```
+
+## Island Components
+
+The SDK includes Island components for creating interactive UI responses that allow users to input data and trigger actions.
+
+### Weather Tool with Interactive Island
+
+```python
+from opal_tools_sdk import ToolsService, tool, IslandResponse, IslandConfig
+from pydantic import BaseModel
+from fastapi import FastAPI
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+class WeatherParameters(BaseModel):
+    location: str
+    units: str = "metric"
+
+@tool("get_weather", "Gets current weather for a location")
+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=[
+            IslandConfig.Field(
+                name="location",
+                label="Location",
+                type="string",
+                value=parameters.location
+            ),
+            IslandConfig.Field(
+                name="units",
+                label="Temperature Units",
+                type="string",
+                value=parameters.units,
+                options=["metric", "imperial", "kelvin"]
+            ),
+            IslandConfig.Field(
+                name="current_temp",
+                label="Current Temperature",
+                type="string",
+                value=f"{weather_data['temperature']}°{'C' if parameters.units == 'metric' else 'F'}"
+            )
+        ],
+        actions=[
+            IslandConfig.Action(
+                name="refresh_weather",
+                label="Refresh Weather",
+                type="button",
+                endpoint="/tools/get_weather",
+                operation="update"
+            )
+        ]
+    )
+    
+    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"`)
+- `value`: Current field value (optional)
+- `hidden`: Whether to hide from user (optional, default: False)
+- `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"`)
+- `endpoint`: API endpoint to call
+- `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
+
+## Type Definitions
+
+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.
+
+## Documentation
+
+See full documentation for more examples and configuration options.

optimizely_opal_opal_tools_sdk-0.1.10.dev0/README.md

@@ -0,0 +1,231 @@
+# Opal Tools SDK for Python
+
+This SDK simplifies the creation of tools services compatible with the Opal Tools Management Service.
+
+## Features
+
+- Easy definition of tool functions with decorators
+- Automatic generation of discovery endpoints
+- Parameter validation and type checking
+- Authentication helpers
+- FastAPI integration
+- Island components for interactive UI responses
+
+## Installation
+
+```bash
+pip install optimizely-opal.opal-tools-sdk
+```
+
+Note: While the package is installed as `optimizely-opal.opal-tools-sdk`, you'll still import it in your code as `opal_tools_sdk`:
+
+```python
+# Import using the package name
+from opal_tools_sdk import ToolsService, tool, IslandResponse, IslandConfig
+```
+
+## Usage
+
+```python
+from opal_tools_sdk import ToolsService, tool
+from pydantic import BaseModel
+from fastapi import FastAPI
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+class WeatherParameters(BaseModel):
+    location: str
+    units: str = "metric"
+
+@tool("get_weather", "Gets current weather for a location")
+async def get_weather(parameters: WeatherParameters):
+    # Implementation...
+    return {"temperature": 22, "condition": "sunny"}
+
+# Discovery endpoint is automatically created at /discovery
+```
+
+## Authentication
+
+The SDK provides two ways to require authentication for your tools:
+
+### 1. Using the `@requires_auth` decorator
+
+```python
+from opal_tools_sdk import ToolsService, tool, AuthData
+from opal_tools_sdk.auth import requires_auth
+from pydantic import BaseModel
+from fastapi import FastAPI
+from typing import Optional
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+class CalendarParameters(BaseModel):
+    date: str
+    timezone: str = "UTC"
+
+# Single authentication requirement
+@requires_auth(provider="google", scope_bundle="calendar", required=True)
+@tool("get_calendar_events", "Gets calendar events for a date")
+async def get_calendar_events(parameters: CalendarParameters, auth_data: Optional[AuthData] = None):
+    # The auth_data parameter contains authentication information
+    if auth_data:
+        token = auth_data["credentials"]["access_token"]
+
+    # Use the token to make authenticated requests
+    # ...
+
+    return {"events": ["Meeting at 10:00", "Lunch at 12:00"]}
+
+# Multiple authentication requirements (tool can work with either provider)
+@requires_auth(provider="google", scope_bundle="calendar", required=True)
+@requires_auth(provider="microsoft", scope_bundle="outlook", required=True)
+@tool("get_calendar_availability", "Check calendar availability")
+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"]
+
+        if provider == "google":
+            # Use Google Calendar API
+            pass
+        elif provider == "microsoft":
+            # Use Microsoft Outlook API
+            pass
+
+    return {"available": True, "provider_used": provider}
+```
+
+### 2. Specifying auth requirements in the `@tool` decorator
+
+```python
+@tool(
+    "get_email",
+    "Gets emails from the user's inbox",
+    auth_requirements=[
+        {"provider": "google", "scope_bundle": "gmail", "required": True}
+    ]
+)
+async def get_email(parameters: EmailParameters, auth_data: Optional[AuthData] = None):
+    # Implementation...
+    return {"emails": ["Email 1", "Email 2"]}
+```
+
+## Island Components
+
+The SDK includes Island components for creating interactive UI responses that allow users to input data and trigger actions.
+
+### Weather Tool with Interactive Island
+
+```python
+from opal_tools_sdk import ToolsService, tool, IslandResponse, IslandConfig
+from pydantic import BaseModel
+from fastapi import FastAPI
+
+app = FastAPI()
+tools_service = ToolsService(app)
+
+class WeatherParameters(BaseModel):
+    location: str
+    units: str = "metric"
+
+@tool("get_weather", "Gets current weather for a location")
+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=[
+            IslandConfig.Field(
+                name="location",
+                label="Location",
+                type="string",
+                value=parameters.location
+            ),
+            IslandConfig.Field(
+                name="units",
+                label="Temperature Units",
+                type="string",
+                value=parameters.units,
+                options=["metric", "imperial", "kelvin"]
+            ),
+            IslandConfig.Field(
+                name="current_temp",
+                label="Current Temperature",
+                type="string",
+                value=f"{weather_data['temperature']}°{'C' if parameters.units == 'metric' else 'F'}"
+            )
+        ],
+        actions=[
+            IslandConfig.Action(
+                name="refresh_weather",
+                label="Refresh Weather",
+                type="button",
+                endpoint="/tools/get_weather",
+                operation="update"
+            )
+        ]
+    )
+    
+    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"`)
+- `value`: Current field value (optional)
+- `hidden`: Whether to hide from user (optional, default: False)
+- `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"`)
+- `endpoint`: API endpoint to call
+- `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
+
+## Type Definitions
+
+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.
+
+## Documentation
+
+See full documentation for more examples and configuration options.

optimizely_opal_opal_tools_sdk-0.1.10.dev0/opal_tools_sdk/__init__.py

@@ -0,0 +1,20 @@
+from .service import ToolsService
+from .decorators import tool
+from .auth import requires_auth
+from .logging import register_logger_factory
+from .models import AuthData, AuthRequirement, Credentials, Environment, IslandConfig, IslandResponse
+
+__version__ = "0.1.0"
+__all__ = [
+    "ToolsService",
+    "tool",
+    "requires_auth",
+    "register_logger_factory",
+    # Models
+    "AuthData",
+    "AuthRequirement",
+    "Credentials",
+    "Environment",
+    "IslandConfig",
+    "IslandResponse",
+]

{optimizely_opal_opal_tools_sdk-0.1.0.dev0 → optimizely_opal_opal_tools_sdk-0.1.10.dev0}/opal_tools_sdk/decorators.py

@@ -1,13 +1,14 @@
 import inspect
 import re
 import logging
-from typing import Callable, Any, List, Dict, Type, get_type_hints, Optional, Union
+from typing import Callable, Any, List, Dict, Type, get_origin, get_type_hints, Optional, Union
 from fastapi import APIRouter, Depends, Header, HTTPException
 from pydantic import BaseModel
 
 from .models import Parameter, ParameterType, AuthRequirement
+from .logging import get_logger
 
-logger = logging.getLogger("opal_tools_sdk")
+logger = get_logger(__name__)
 
 def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str, Any]]] = None):
     """Decorator to register a function as an Opal tool.
@@ -61,21 +62,48 @@ def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str,
                 else:
                     field_type = str
 
+                # Check if the field is Optional (Union with None)
+                # Optional[X] is equivalent to Union[X, None]
+                type_args = getattr(field_type, '__args__', ())
+                is_optional = get_origin(field_type) is Union and type(None) in type_args
+
+                # Extract the actual type from Optional[T]
+                if is_optional and type_args:
+                    # Get the non-None type from Union[T, None]
+                    field_type = next(
+                        (arg for arg in type_args if arg is not type(None)),
+                        field_type,
+                    )
+
                 # Map Python type to Parameter type
                 param_type = ParameterType.string
-                if field_type == int:
+                if field_type is int:
                     param_type = ParameterType.integer
-                elif field_type == float:
+                elif field_type is float:
                     param_type = ParameterType.number
-                elif field_type == bool:
+                elif field_type is bool:
                     param_type = ParameterType.boolean
-                elif field_type == list or field_type == List:
+                elif field_type is list or get_origin(field_type) is list:
                     param_type = ParameterType.list
-                elif field_type == dict or field_type == Dict:
+                elif field_type is dict or get_origin(field_type) is dict:
                     param_type = ParameterType.dictionary
 
                 # Determine if required
-                required = field_info.default is ... if hasattr(field_info, 'default') else True
+                field_info_extra = getattr(field_info, "json_schema_extra") or {}
+                if "required" in field_info_extra:
+                    required = field_info_extra["required"]
+                # If the field is typed as Optional, it's not required (check this FIRST)
+                elif is_optional:
+                    required = False
+                # Check for Pydantic v2 is_required() method
+                elif hasattr(field_info, 'is_required'):
+                    required = field_info.is_required()
+                # Fall back to checking if default is ... (Pydantic v1/v2 compatibility)
+                elif hasattr(field_info, 'default'):
+                    required = field_info.default is ...
+                else:
+                    # If no default attribute at all, assume required
+                    required = True
 
                 # Get description
                 description_text = ""
@@ -91,9 +119,9 @@ def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str,
                     required=required
                 ))
 
-                print(f"Registered parameter: {field_name} of type {param_type.value}, required: {required}")
+                logger.info(f"Registered parameter: {field_name} of type {param_type.value}, required: {required}")
         else:
-            print(f"Warning: No parameter model found for {name}")
+            logger.warning(f"Warning: No parameter model found for {name}")
 
         endpoint = f"/tools/{name}"
 
@@ -108,10 +136,10 @@ def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str,
                     required=auth_req.get("required", True)
                 ))
 
-        print(f"Registering tool {name} with endpoint {endpoint}")
+        logger.info(f"Registering tool {name} with endpoint {endpoint}")
 
         if not _registry.services:
-            print("No services registered in registry! Make sure to create ToolsService before decorating functions.")
+            logger.warning("No services registered in registry! Make sure to create ToolsService before decorating functions.")
 
         for service in _registry.services:
             service.register_tool(

optimizely_opal_opal_tools_sdk-0.1.10.dev0/opal_tools_sdk/logging.py

@@ -0,0 +1,37 @@
+import logging
+import sys
+from typing import Optional, Callable
+
+# Type alias for a logger factory function
+type LoggerFactory = Callable[[Optional[str]], logging.Logger]
+
+# Internal variable to hold a custom logger factory
+_custom_logger_factory: Optional[LoggerFactory] = None
+
+def register_logger_factory(factory: LoggerFactory):
+    """
+    Register a custom logger factory function. This function should accept a name (str or None)
+    and return a logger instance (e.g., structlog or standard logger).
+    """
+    global _custom_logger_factory
+    _custom_logger_factory = factory
+
+def get_logger(name: str = None) -> logging.Logger:
+    """
+    Returns a logger configured to output to the console, or uses a registered custom logger factory.
+    If no name is provided, uses the root logger.
+    """
+    if _custom_logger_factory is not None:
+        return _custom_logger_factory(name)
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        formatter = logging.Formatter(
+            fmt='%(asctime)s %(levelname)s [%(name)s] %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+    return logger