optimizely-opal.opal-tools-sdk 0.1.3.dev0__tar.gz → 0.1.5.dev0__tar.gz

optimizely_opal_opal_tools_sdk-0.1.5.dev0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: optimizely-opal.opal-tools-sdk
+Version: 0.1.5.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
+
+#### 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.5.dev0/README.md

@@ -0,0 +1,229 @@
+# 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
+
+#### 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.5.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.3.dev0 → optimizely_opal_opal_tools_sdk-0.1.5.dev0}/opal_tools_sdk/decorators.py

@@ -6,8 +6,9 @@ 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.
@@ -95,9 +96,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}"
 
@@ -112,10 +113,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.5.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

optimizely_opal_opal_tools_sdk-0.1.5.dev0/opal_tools_sdk/models.py

@@ -0,0 +1,126 @@
+from enum import Enum
+from typing import List, Dict, Any, Optional, Literal, TypedDict
+from dataclasses import dataclass
+
+from pydantic import BaseModel, Field
+
+
+class ParameterType(str, Enum):
+    """Types of parameters supported by Opal tools."""
+
+    string = "string"
+    integer = "integer"
+    number = "number"
+    boolean = "boolean"
+    list = "array"  # Changed to match main service expectation
+    dictionary = "object"  # Standard JSON schema type
+
+
+@dataclass
+class Parameter:
+    """Parameter definition for an Opal tool."""
+
+    name: str
+    param_type: ParameterType
+    description: str
+    required: bool
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for the discovery endpoint."""
+        return {"name": self.name, "type": self.param_type.value, "description": self.description, "required": self.required}
+
+
+@dataclass
+class AuthRequirement:
+    """Authentication requirements for an Opal tool."""
+
+    provider: str  # e.g., "google", "microsoft"
+    scope_bundle: str  # e.g., "calendar", "drive"
+    required: bool = True
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for the discovery endpoint."""
+        return {"provider": self.provider, "scope_bundle": self.scope_bundle, "required": self.required}
+
+
+class Credentials(TypedDict):
+    """AuthData credentials."""
+
+    access_token: str
+    org_sso_id: Optional[str]
+    customer_id: str
+    instance_id: str
+    product_sku: str
+
+
+class AuthData(TypedDict):
+    """Authentication data for an Opal tool."""
+
+    provider: str
+    credentials: Credentials
+
+
+class Environment(TypedDict):
+    """Execution environment for an Opal tool. Interactive will provide interaction islands, while headless will not."""
+
+    execution_mode: Literal["headless", "interactive"]
+
+
+@dataclass
+class Function:
+    """Function definition for an Opal tool."""
+
+    name: str
+    description: str
+    parameters: List[Parameter]
+    endpoint: str
+    auth_requirements: Optional[List[AuthRequirement]] = None
+    http_method: str = "POST"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for the discovery endpoint."""
+        result = {
+            "name": self.name,
+            "description": self.description,
+            "parameters": [p.to_dict() for p in self.parameters],
+            "endpoint": self.endpoint,
+            "http_method": self.http_method,
+        }
+
+        if self.auth_requirements:
+            result["auth_requirements"] = [auth.to_dict() for auth in self.auth_requirements]
+
+        return result
+
+
+# Interaction island related classes
+class IslandConfig(BaseModel):
+    class Field(BaseModel):
+        name: str
+        label: str
+        type: Literal["string", "boolean", "json"]
+        value: str = Field(default="")
+        hidden: bool = Field(default=False)
+        options: list[str] = Field(default=[])
+
+    class Action(BaseModel):
+        name: str
+        label: str
+        type: str
+        endpoint: str
+        operation: str = Field(default="create")
+
+    fields: list[Field]
+    actions: list[Action]
+
+
+class IslandResponse(BaseModel):
+    class ResponseConfig(BaseModel):
+        islands: list[IslandConfig]
+
+    type: Literal["island"]
+    config: ResponseConfig
+
+    @classmethod
+    def create(cls, islands: list[IslandConfig]):
+        return cls(type="island", config=cls.ResponseConfig(islands=islands))