optimizely-opal.opal-tools-sdk 0.1.0.dev0__py3-none-any.whl

opal_tools_sdk/__init__.py

@@ -0,0 +1,6 @@
+from .service import ToolsService
+from .decorators import tool
+from .auth import requires_auth
+
+__version__ = "0.1.0"
+__all__ = ["ToolsService", "tool", "requires_auth"]

opal_tools_sdk/_registry.py

@@ -0,0 +1,3 @@
+"""Internal registry for ToolsService instances."""
+
+services = []

opal_tools_sdk/auth.py

@@ -0,0 +1,42 @@
+from typing import Callable, Dict, Any, Optional, List
+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.
+
+    Args:
+        provider: Authentication provider (e.g., "google", "microsoft")
+        scope_bundle: Scope bundle required (e.g., "calendar", "drive")
+        required: Whether authentication is mandatory (default: True)
+
+    Returns:
+        Decorator function
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        async def wrapper(*args, authorization: Optional[str] = Header(None), **kwargs):
+            if required and not authorization:
+                raise HTTPException(status_code=401, detail="Authentication required")
+
+            # The Tools Management Service will provide the appropriate token
+            # in the Authorization header
+            return await func(*args, authorization=authorization, **kwargs)
+
+        # Store auth requirements in function metadata
+        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__ = []
+
+        # Add this auth requirement to the list
+        wrapper.__auth_requirements__.append(auth_req)
+
+        return wrapper
+
+    return decorator

opal_tools_sdk/decorators.py

@@ -0,0 +1,128 @@
+import inspect
+import re
+import logging
+from typing import Callable, Any, List, Dict, Type, get_type_hints, Optional, Union
+from fastapi import APIRouter, Depends, Header, HTTPException
+from pydantic import BaseModel
+
+from .models import Parameter, ParameterType, AuthRequirement
+
+logger = logging.getLogger("opal_tools_sdk")
+
+def tool(name: str, description: str, auth_requirements: Optional[List[Dict[str, Any]]] = None):
+    """Decorator to register a function as an Opal tool.
+
+    Args:
+        name: Name of the tool
+        description: Description of the tool
+        auth_requirements: Authentication requirements (optional)
+            Format: [{"provider": "oauth_provider", "scope_bundle": "permissions_scope", "required": True}, ...]
+            Example: [{"provider": "google", "scope_bundle": "calendar", "required": True}]
+
+    Returns:
+        Decorator function
+
+    Note:
+        If your tool requires authentication, define your handler function with two parameters:
+        async def my_tool(parameters: ParametersModel, auth_data: Optional[Dict] = None):
+            ...
+    """
+    def decorator(func: Callable):
+        # Get the ToolsService instance from the global registry
+        from . import _registry
+
+        # Extract parameters from function signature
+        sig = inspect.signature(func)
+        type_hints = get_type_hints(func)
+
+        parameters: List[Parameter] = []
+        param_model = None
+
+        # Look for a parameter that is a pydantic model (for parameters)
+        for param_name, param in sig.parameters.items():
+            if param_name in type_hints:
+                param_type = type_hints[param_name]
+                if hasattr(param_type, '__fields__') or hasattr(param_type, 'model_fields'):  # Pydantic v1 or v2
+                    param_model = param_type
+                    break
+
+        # If we found a pydantic model, extract parameters
+        if param_model:
+            model_fields = getattr(param_model, 'model_fields', getattr(param_model, '__fields__', {}))
+            for field_name, field in model_fields.items():
+                # Get field metadata
+                field_info = field.field_info if hasattr(field, 'field_info') else field
+
+                # Determine type
+                if hasattr(field, 'outer_type_'):
+                    field_type = field.outer_type_
+                elif hasattr(field, 'annotation'):
+                    field_type = field.annotation
+                else:
+                    field_type = str
+
+                # Map Python type to Parameter type
+                param_type = ParameterType.string
+                if field_type == int:
+                    param_type = ParameterType.integer
+                elif field_type == float:
+                    param_type = ParameterType.number
+                elif field_type == bool:
+                    param_type = ParameterType.boolean
+                elif field_type == list or field_type == List:
+                    param_type = ParameterType.list
+                elif field_type == dict or field_type == Dict:
+                    param_type = ParameterType.dictionary
+
+                # Determine if required
+                required = field_info.default is ... if hasattr(field_info, 'default') else True
+
+                # Get description
+                description_text = ""
+                if hasattr(field_info, 'description'):
+                    description_text = field_info.description
+                elif hasattr(field, 'description'):
+                    description_text = field.description
+
+                parameters.append(Parameter(
+                    name=field_name,
+                    param_type=param_type,
+                    description=description_text,
+                    required=required
+                ))
+
+                print(f"Registered parameter: {field_name} of type {param_type.value}, required: {required}")
+        else:
+            print(f"Warning: No parameter model found for {name}")
+
+        endpoint = f"/tools/{name}"
+
+        # Register the tool with the service
+        auth_req_list = None
+        if auth_requirements:
+            auth_req_list = []
+            for auth_req in auth_requirements:
+                auth_req_list.append(AuthRequirement(
+                    provider=auth_req.get("provider", ""),
+                    scope_bundle=auth_req.get("scope_bundle", ""),
+                    required=auth_req.get("required", True)
+                ))
+
+        print(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.")
+
+        for service in _registry.services:
+            service.register_tool(
+                name=name,
+                description=description,
+                handler=func,
+                parameters=parameters,
+                endpoint=endpoint,
+                auth_requirements=auth_req_list
+            )
+
+        return func
+
+    return decorator

opal_tools_sdk/models.py

@@ -0,0 +1,69 @@
+from enum import Enum
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass
+
+class ParameterType(str, Enum):
+    """Types of parameters supported by Opal tools."""
+    string = "string"
+    integer = "integer"
+    number = "number"
+    boolean = "boolean"
+    list = "list"  # 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
+        }
+
+@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

opal_tools_sdk/service.py

@@ -0,0 +1,171 @@
+from typing import Dict, List, Any, Callable, Type, Optional, get_type_hints
+import inspect
+import logging
+from fastapi import FastAPI, APIRouter, Depends, Header, HTTPException, Request
+from fastapi.routing import APIRoute
+from pydantic import BaseModel, create_model
+
+from .models import Function, Parameter, ParameterType, AuthRequirement
+from . import _registry
+
+logger = logging.getLogger("opal_tools_sdk")
+
+class ToolsService:
+    """Main class for managing Opal tools."""
+
+    def __init__(self, app: FastAPI):
+        """Initialize the tools service.
+
+        Args:
+            app: FastAPI application to attach routes to
+        """
+        self.app = app
+        self.router = APIRouter()
+        self.functions: List[Function] = []
+        self._init_routes()
+
+        # Register in the global registry
+        _registry.services.append(self)
+
+        # Debug existing routes
+        @app.get("/debug-routes")
+        async def debug_routes():
+            routes = []
+            for route in app.routes:
+                if isinstance(route, APIRoute):
+                    routes.append({
+                        "path": route.path,
+                        "name": route.name,
+                        "methods": route.methods
+                    })
+            return {"routes": routes}
+
+    def _init_routes(self) -> None:
+        """Initialize the discovery endpoint."""
+        @self.router.get("/discovery")
+        async def discovery() -> Dict[str, Any]:
+            """Return the discovery information for this tools service."""
+            return {"functions": [f.to_dict() for f in self.functions]}
+
+        # Include router in app
+        self.app.include_router(self.router)
+
+    def _extract_auth_requirements(self, handler: Callable) -> List[AuthRequirement]:
+        """Extract auth requirements from a handler function decorated with @requires_auth.
+
+        Args:
+            handler: The handler function
+
+        Returns:
+            List of AuthRequirement objects
+        """
+        auth_requirements = []
+
+        # Check if the function is wrapped with @requires_auth
+        if hasattr(handler, "__auth_requirements__"):
+            # Auth requirements should always be a list
+            if isinstance(handler.__auth_requirements__, list):
+                for req in handler.__auth_requirements__:
+                    auth_requirements.append(AuthRequirement(
+                        provider=req.get("provider", ""),
+                        scope_bundle=req.get("scope_bundle", ""),
+                        required=req.get("required", True)
+                    ))
+
+        return auth_requirements
+
+    def register_tool(self,
+                     name: str,
+                     description: str,
+                     handler: Callable,
+                     parameters: List[Parameter],
+                     endpoint: str,
+                     auth_requirements: Optional[List[AuthRequirement]] = None) -> None:
+        """Register a tool function.
+
+        Args:
+            name: Name of the tool
+            description: Description of the tool
+            handler: Function that implements the tool
+            parameters: List of parameters for the tool
+            endpoint: API endpoint for the tool
+            auth_requirements: List of authentication requirements (optional)
+        """
+        print(f"Registering tool: {name} with endpoint: {endpoint}")
+
+        # Extract auth requirements from handler if decorated with @requires_auth
+        handler_auth_requirements = self._extract_auth_requirements(handler)
+
+        # If auth_requirements is explicitly provided, it takes precedence
+        # Otherwise, use the requirements extracted from the handler
+        final_auth_requirements = auth_requirements if auth_requirements else handler_auth_requirements
+
+        function = Function(
+            name=name,
+            description=description,
+            parameters=parameters,
+            endpoint=endpoint,
+            auth_requirements=final_auth_requirements
+        )
+
+        self.functions.append(function)
+
+        # Create a direct route with the app for better control
+        @self.app.post(endpoint)
+        async def tool_endpoint(request: Request):
+            try:
+                # Parse JSON body
+                body = await request.json()
+                print(f"Received request for {endpoint} with body: {body}")
+
+                # Parameters should be in the "parameters" key according to the spec
+                # This matches how the tools-mgmt-service calls tools
+                if "parameters" in body:
+                    params = body["parameters"]
+                else:
+                    # For backward compatibility with direct test calls
+                    print(f"Warning: 'parameters' key not found in request body. Using body directly.")
+                    params = body
+
+                # Extract auth data if available
+                auth_data = body.get("auth")
+                if auth_data:
+                    print(f"Auth data provided for provider: {auth_data.get('provider', 'unknown')}")
+
+                print(f"Extracted parameters: {params}")
+
+                # Get the parameter model from handler's signature
+                sig = inspect.signature(handler)
+                param_name = list(sig.parameters.keys())[0]
+                param_type = get_type_hints(handler).get(param_name)
+
+                # Check signature to see if it accepts auth data
+                accepts_auth = len(sig.parameters) > 1
+
+                if param_type:
+                    # Create instance of param model
+                    model_instance = param_type(**params)
+                    if accepts_auth:
+                        # Call with auth data if the handler accepts it
+                        result = await handler(model_instance, auth_data)
+                    else:
+                        # Call without auth data
+                        result = await handler(model_instance)
+                else:
+                    # Fall back if type hints not available
+                    if accepts_auth:
+                        result = await handler(BaseModel(**params), auth_data)
+                    else:
+                        result = await handler(BaseModel(**params))
+
+                print(f"Tool {name} returned: {result}")
+                return result
+            except Exception as e:
+                import traceback
+                print(f"Error in tool {name}: {str(e)}")
+                print(traceback.format_exc())
+                raise HTTPException(status_code=500, detail=str(e))
+
+        # Update the route function name and docstring
+        tool_endpoint.__name__ = f"tool_{name}"
+        tool_endpoint.__doc__ = description

optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: optimizely-opal.opal-tools-sdk
+Version: 0.1.0.dev0
+Summary: SDK for creating Opal-compatible tools services
+Home-page: https://github.com/optimizely/opal-tools-sdk
+Author: Optimizely
+Author-email: opal-team@optimizely.com
+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
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: httpx>=0.24.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,10 @@
+opal_tools_sdk/__init__.py,sha256=Eu141xM3QVq1O_BLGZS9m_asU1b_KaOApFtwvaYll6E,170
+opal_tools_sdk/_registry.py,sha256=YE3eD4kcS09QDe4RccBYAzXPo9znEU7fblrsB-g3o-Y,67
+opal_tools_sdk/auth.py,sha256=9aMiZv6n6_iu7hQA0sKg4hgNr5DzYFFuP0SWUoZf_Vw,1520
+opal_tools_sdk/decorators.py,sha256=a_CJcA11RW8eAt2xRGXZane_HvTZqR7wfhn-6WFgjOY,5057
+opal_tools_sdk/models.py,sha256=fa2hhnZ2GTz6xqhGTNyqyIQj_rBE1UFQxsJ4KfApCiU,2123
+opal_tools_sdk/service.py,sha256=tVaQKFpTX778UUWoczlM2WHSiUXqdYtYSKgTdqTH1Z0,6756
+optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/METADATA,sha256=EoIwGaRzuaWjMlPwej56DdeTW6IcYtJDjttLigMu9ts,748
+optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/top_level.txt,sha256=nCJ5PxF0rgoV6yNJvvuUaZPx4D3EWkl7gpu-6xafH1E,15
+optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/RECORD,,

optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.3.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

optimizely_opal_opal_tools_sdk-0.1.0.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+opal_tools_sdk