utcp 0.1.0__py3-none-any.whl

utcp/__init__.py

@@ -0,0 +1,42 @@
+"""
+Universal Tool Calling Protocol Core
+"""
+
+from utcp.shared.tool import (
+    Tool,
+    ToolInputOutputSchema,
+)
+
+from utcp.shared.provider import (
+    Provider,
+    HttpProvider,
+    CliProvider,
+    WebSocketProvider,
+    GRPCProvider,
+    GraphQLProvider,
+    TCPProvider,
+    UDPProvider,
+    StreamableHttpProvider,
+    SSEProvider,
+    WebRTCProvider,
+    MCPProvider,
+    TextProvider,
+)
+
+__all__ = [
+    "Tool",
+    "ToolInputOutputSchema",
+    "Provider",
+    "HttpProvider",
+    "CliProvider",
+    "WebSocketProvider",
+    "GRPCProvider",
+    "GraphQLProvider",
+    "TCPProvider",
+    "UDPProvider",
+    "StreamableHttpProvider",
+    "SSEProvider",
+    "WebRTCProvider",
+    "MCPProvider",
+    "TextProvider",
+]

utcp/client/client_transport_interface.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List
+from utcp.shared.provider import Provider
+from utcp.shared.tool import Tool
+
+class ClientTransportInterface(ABC):
+    @abstractmethod
+    async def register_tool_provider(self, manual_provider: Provider) -> List[Tool]:
+        pass
+
+    @abstractmethod
+    async def deregister_tool_provider(self, manual_provider: Provider) -> None:
+        pass
+
+    @abstractmethod
+    async def call_tool(self, tool_name: str, arguments: Dict[str, Any], tool_provider: Provider) -> Any:
+        pass

utcp/client/openapi_converter.py

@@ -0,0 +1,301 @@
+import json
+from typing import Any, Dict, List, Optional, Tuple
+import sys
+from utcp.shared.tool import Tool, ToolInputOutputSchema
+from utcp.shared.utcp_manual import UtcpManual
+from urllib.parse import urlparse
+
+from utcp.shared.provider import HttpProvider
+from utcp.shared.auth import Auth, ApiKeyAuth, BasicAuth, OAuth2Auth
+
+
+class OpenApiConverter:
+    """Converts an OpenAPI JSON specification into a UtcpManual."""
+
+    def __init__(self, openapi_spec: Dict[str, Any], spec_url: Optional[str] = None, provider_name: Optional[str] = None):
+        self.spec = openapi_spec
+        self.spec_url = spec_url
+        # If provider_name is None then get the first word in spec.info.title
+        if provider_name is None:
+            title = openapi_spec.get("info", {}).get("title", "openapi_provider")
+            # Replace characters that are invalid for identifiers
+            invalid_chars = " -.,!?'\"\\/()[]{}#@$%^&*+=~`|;:<>"
+            self.provider_name = ''.join('_' if c in invalid_chars else c for c in title)
+        else:
+            self.provider_name = provider_name
+
+    def convert(self) -> UtcpManual:
+        """Parses the OpenAPI specification and returns a UtcpManual."""
+        tools = []
+        servers = self.spec.get("servers")
+        if servers:
+            base_url = servers[0].get("url", "/")
+        elif self.spec_url:
+            parsed_url = urlparse(self.spec_url)
+            base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+        else:
+            # Fallback if no server info and no spec URL is provided
+            base_url = "/"
+            print("No server info or spec URL provided. Using fallback base URL: ", base_url, file=sys.stderr)
+
+        for path, path_item in self.spec.get("paths", {}).items():
+            for method, operation in path_item.items():
+                if method.lower() in ['get', 'post', 'put', 'delete', 'patch']:
+                    tool = self._create_tool(path, method, operation, base_url)
+                    if tool:
+                        tools.append(tool)
+
+        return UtcpManual(tools=tools)
+
+    def _resolve_ref(self, ref: str) -> Dict[str, Any]:
+        """Resolves a local JSON reference."""
+        if not ref.startswith('#/'):
+            raise ValueError(f"External or non-local references are not supported: {ref}")
+        
+        parts = ref[2:].split('/')
+        node = self.spec
+        for part in parts:
+            try:
+                node = node[part]
+            except (KeyError, TypeError):
+                raise ValueError(f"Reference not found: {ref}")
+        return node
+
+    def _resolve_schema(self, schema: Dict[str, Any]) -> Dict[str, Any]:
+        """Recursively resolves all $refs in a schema object."""
+        if isinstance(schema, dict):
+            if "$ref" in schema:
+                resolved_ref = self._resolve_ref(schema["$ref"])
+                # The resolved reference could itself contain refs, so we recurse
+                return self._resolve_schema(resolved_ref)
+            
+            # Resolve refs in nested properties
+            new_schema = {}
+            for key, value in schema.items():
+                new_schema[key] = self._resolve_schema(value)
+            return new_schema
+        
+        if isinstance(schema, list):
+            return [self._resolve_schema(item) for item in schema]
+
+        return schema
+
+    def _extract_auth(self, operation: Dict[str, Any]) -> Optional[Auth]:
+        """Extracts authentication information from OpenAPI operation and global security schemes."""
+        # First check for operation-level security requirements
+        security_requirements = operation.get("security", [])
+        
+        # If no operation-level security, check global security requirements
+        if not security_requirements:
+            security_requirements = self.spec.get("security", [])
+        
+        # If no security requirements, return None
+        if not security_requirements:
+            return None
+        
+        # Get security schemes - support both OpenAPI 2.0 and 3.0
+        security_schemes = self._get_security_schemes()
+        
+        # Process the first security requirement (most common case)
+        # Each security requirement is a dict with scheme name as key
+        for security_req in security_requirements:
+            for scheme_name, scopes in security_req.items():
+                if scheme_name in security_schemes:
+                    scheme = security_schemes[scheme_name]
+                    return self._create_auth_from_scheme(scheme, scheme_name)
+        
+        return None
+    
+    def _get_security_schemes(self) -> Dict[str, Any]:
+        """Gets security schemes supporting both OpenAPI 2.0 and 3.0."""
+        # OpenAPI 3.0 format
+        if "components" in self.spec:
+            return self.spec.get("components", {}).get("securitySchemes", {})
+        
+        # OpenAPI 2.0 format
+        return self.spec.get("securityDefinitions", {})
+    
+    def _create_auth_from_scheme(self, scheme: Dict[str, Any], scheme_name: str) -> Optional[Auth]:
+        """Creates an Auth object from an OpenAPI security scheme."""
+        scheme_type = scheme.get("type", "").lower()
+
+        if scheme_type == "apikey":
+            # For API key auth, use the parameter name from the OpenAPI spec
+            location = scheme.get("in", "header")  # Default to header if not specified
+            param_name = scheme.get("name", "Authorization")  # Default name
+            return ApiKeyAuth(
+                api_key=f"${{{self.provider_name.upper()}_API_KEY}}",  # Placeholder for environment variable
+                var_name=param_name,
+                location=location
+            )
+        
+        elif scheme_type == "basic":
+            # OpenAPI 2.0 format: type: basic
+            return BasicAuth(
+                username=f"${{{self.provider_name.upper()}_USERNAME}}",
+                password=f"${{{self.provider_name.upper()}_PASSWORD}}"
+            )
+        
+        elif scheme_type == "http":
+            # OpenAPI 3.0 format: type: http with scheme
+            http_scheme = scheme.get("scheme", "").lower()
+            if http_scheme == "basic":
+                # For basic auth, use conventional environment variable names
+                return BasicAuth(
+                    username=f"${{{self.provider_name.upper()}_USERNAME}}",
+                    password=f"${{{self.provider_name.upper()}_PASSWORD}}"
+                )
+            elif http_scheme == "bearer":
+                # Treat bearer tokens as API keys
+                return ApiKeyAuth(
+                    api_key=f"Bearer ${{{self.provider_name.upper()}_API_KEY}}",
+                    var_name="Authorization",
+                    location="header"
+                )
+        
+        elif scheme_type == "oauth2":
+            # Handle both OpenAPI 2.0 and 3.0 OAuth2 formats
+            flows = scheme.get("flows", {})
+            
+            # OpenAPI 3.0 format
+            if flows:
+                for flow_type, flow_config in flows.items():
+                    # Support both old and new flow names
+                    if flow_type in ["authorizationCode", "accessCode", "clientCredentials", "application"]:
+                        token_url = flow_config.get("tokenUrl")
+                        if token_url:
+                            return OAuth2Auth(
+                                token_url=token_url,
+                                client_id=f"${{{self.provider_name.upper()}_CLIENT_ID}}",
+                                client_secret=f"${{{self.provider_name.upper()}_CLIENT_SECRET}}",
+                                scope=" ".join(flow_config.get("scopes", {}).keys()) or None
+                            )
+            
+            # OpenAPI 2.0 format (flows directly in scheme)
+            else:
+                flow_type = scheme.get("flow", "")
+                token_url = scheme.get("tokenUrl")
+                if token_url and flow_type in ["accessCode", "application", "clientCredentials"]:
+                    return OAuth2Auth(
+                        token_url=token_url,
+                        client_id=f"${{{self.provider_name.upper()}_CLIENT_ID}}",
+                        client_secret=f"${{{self.provider_name.upper()}_CLIENT_SECRET}}",
+                        scope=" ".join(scheme.get("scopes", {}).keys()) or None
+                    )
+        
+        return None
+
+    def _create_tool(self, path: str, method: str, operation: Dict[str, Any], base_url: str) -> Optional[Tool]:
+        """Creates a Tool object from an OpenAPI operation."""
+        operation_id = operation.get("operationId")
+        if not operation_id:
+            return None
+
+        description = operation.get("summary") or operation.get("description", "")
+        tags = operation.get("tags", [])
+
+        inputs, header_fields, body_field = self._extract_inputs(operation)
+        outputs = self._extract_outputs(operation)
+        auth = self._extract_auth(operation)
+
+        provider_name = self.spec.get("info", {}).get("title", "openapi_provider")
+
+        # Combine base URL and path, ensuring no double slashes
+        full_url = base_url.rstrip('/') + '/' + path.lstrip('/')
+
+        provider = HttpProvider(
+            name=provider_name,
+            provider_type="http",
+            http_method=method.upper(),
+            url=full_url,
+            body_field=body_field if body_field else None,
+            header_fields=header_fields if header_fields else None,
+            auth=auth
+        )
+
+        return Tool(
+            name=operation_id,
+            description=description,
+            inputs=inputs,
+            outputs=outputs,
+            tags=tags,
+            tool_provider=provider
+        )
+
+    def _extract_inputs(self, operation: Dict[str, Any]) -> Tuple[ToolInputOutputSchema, List[str], Optional[str]]:
+        """Extracts input schema, header fields, and body field from an OpenAPI operation."""
+        properties = {}
+        required = []
+        header_fields = []
+        body_field = None
+
+        # Handle parameters (query, header, path, cookie)
+        for param in operation.get("parameters", []):
+            param = self._resolve_schema(param)
+            param_name = param.get("name")
+            if not param_name:
+                continue
+
+            if param.get("in") == "header":
+                header_fields.append(param_name)
+
+            schema = self._resolve_schema(param.get("schema", {}))
+            properties[param_name] = {
+                "type": schema.get("type", "string"),
+                "description": param.get("description", ""),
+                **schema
+            }
+            if param.get("required"):
+                required.append(param_name)
+
+        # Handle request body
+        request_body = operation.get("requestBody")
+        if request_body:
+            resolved_body = self._resolve_schema(request_body)
+            content = resolved_body.get("content", {})
+            json_schema = content.get("application/json", {}).get("schema")
+            if json_schema:
+                # Add a single 'body' field to represent the request body
+                body_field = "body"
+                properties[body_field] = {
+                    "description": resolved_body.get("description", "Request body"),
+                    **self._resolve_schema(json_schema)
+                }
+                if resolved_body.get("required"):
+                    required.append(body_field)
+
+        schema = ToolInputOutputSchema(properties=properties, required=required if required else None)
+        return schema, header_fields, body_field
+
+    def _extract_outputs(self, operation: Dict[str, Any]) -> ToolInputOutputSchema:
+        """Extracts the output schema from an OpenAPI operation, resolving refs."""
+        success_response = operation.get("responses", {}).get("200") or operation.get("responses", {}).get("201")
+        if not success_response:
+            return ToolInputOutputSchema()
+
+        resolved_response = self._resolve_schema(success_response)
+        content = resolved_response.get("content", {})
+        json_schema = content.get("application/json", {}).get("schema")
+
+        if not json_schema:
+            return ToolInputOutputSchema()
+
+        resolved_json_schema = self._resolve_schema(json_schema)
+        schema_args = {
+            "type": resolved_json_schema.get("type", "object"),
+            "properties": resolved_json_schema.get("properties", {}),
+            "required": resolved_json_schema.get("required"),
+            "description": resolved_json_schema.get("description"),
+            "title": resolved_json_schema.get("title"),
+        }
+        
+        # Handle array item types
+        if schema_args["type"] == "array" and "items" in resolved_json_schema:
+            schema_args["items"] = resolved_json_schema.get("items")
+            
+        # Handle additional schema attributes
+        for attr in ["enum", "minimum", "maximum", "format"]:
+            if attr in resolved_json_schema:
+                schema_args[attr] = resolved_json_schema.get(attr)
+                
+        return ToolInputOutputSchema(**schema_args)

utcp/client/tool_repositories/in_mem_tool_repository.py

@@ -0,0 +1,47 @@
+from typing import List, Dict, Tuple, Optional
+from utcp.shared.provider import Provider
+from utcp.shared.tool import Tool
+from utcp.client.tool_repository import ToolRepository
+
+class InMemToolRepository(ToolRepository):
+    tools: List[Tool] = []
+    tool_per_provider: Dict[str, Tuple[Provider, List[Tool]]] = {}
+
+    async def save_provider_with_tools(self, provider: Provider, tools: List[Tool]) -> None:
+        self.tools.extend(tools)
+        self.tool_per_provider[provider.name] = (provider, tools)
+
+    async def remove_provider(self, provider_name: str) -> None:
+        if provider_name not in self.tool_per_provider:
+            raise ValueError(f"Provider '{provider_name}' not found")
+        tools_to_remove = self.tool_per_provider[provider_name][1]
+        self.tools = [tool for tool in self.tools if tool not in tools_to_remove]
+        self.tool_per_provider.pop(provider_name, None)
+
+    async def remove_tool(self, tool_name: str) -> None:
+        provider_name = tool_name.split(".")[0]
+        if provider_name not in self.tool_per_provider:
+            raise ValueError(f"Provider '{provider_name}' not found")
+        new_tools = [tool for tool in self.tools if tool.name != tool_name]
+        if len(new_tools) == len(self.tools):
+            raise ValueError(f"Tool '{tool_name}' not found")
+        self.tools = new_tools
+        self.tool_per_provider[provider_name][1] = [tool for tool in self.tool_per_provider[provider_name][1] if tool.name != tool_name]
+
+    async def get_tool(self, tool_name: str) -> Optional[Tool]:
+        for tool in self.tools:
+            if tool.name == tool_name:
+                return tool
+        return None
+
+    async def get_tools(self) -> List[Tool]:
+        return self.tools
+
+    async def get_tools_by_provider(self, provider_name: str) -> Optional[List[Tool]]:
+        return self.tool_per_provider.get(provider_name, (None, None))[1]
+
+    async def get_provider(self, provider_name: str) -> Optional[Provider]:
+        return self.tool_per_provider.get(provider_name, (None, None))[0]
+
+    async def get_providers(self) -> List[Provider]:
+        return [provider for provider, _ in self.tool_per_provider.values()]

utcp/client/tool_repository.py

@@ -0,0 +1,101 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional
+from utcp.shared.provider import Provider
+from utcp.shared.tool import Tool
+
+class ToolRepository(ABC):
+    @abstractmethod
+    async def save_provider_with_tools(self, provider: Provider, tools: List[Tool]) -> None:
+        """
+        Save a provider and its tools in the repository.
+
+        Args:
+            provider: The provider to save.
+            tools: The tools associated with the provider.
+        """
+        pass
+
+    @abstractmethod
+    async def remove_provider(self, provider_name: str) -> None:
+        """
+        Remove a provider and its tools from the repository.
+
+        Args:
+            provider_name: The name of the provider to remove.
+
+        Raises:
+            ValueError: If the provider is not found.
+        """
+        pass
+
+    @abstractmethod
+    async def remove_tool(self, tool_name: str) -> None:
+        """
+        Remove a tool from the repository.
+
+        Args:
+            tool_name: The name of the tool to remove.
+
+        Raises:
+            ValueError: If the tool is not found.
+        """
+        pass
+
+    @abstractmethod
+    async def get_tool(self, tool_name: str) -> Optional[Tool]:
+        """
+        Get a tool from the repository.
+
+        Args:
+            tool_name: The name of the tool to retrieve.
+
+        Returns:
+            The tool if found, otherwise None.
+        """
+        pass
+
+    @abstractmethod
+    async def get_tools(self) -> List[Tool]:
+        """
+        Get all tools from the repository.
+
+        Returns:
+            A list of tools.
+        """
+        pass
+    
+    @abstractmethod
+    async def get_tools_by_provider(self, provider_name: str) -> Optional[List[Tool]]:
+        """
+        Get tools associated with a specific provider.
+
+        Args:
+            provider_name: The name of the provider.
+
+        Returns:
+            A list of tools associated with the provider, or None if the provider is not found.
+        """
+        pass
+
+    @abstractmethod
+    async def get_provider(self, provider_name: str) -> Optional[Provider]:
+        """
+        Get a provider from the repository.
+
+        Args:
+            provider_name: The name of the provider to retrieve.
+
+        Returns:
+            The provider if found, otherwise None.
+        """
+        pass
+
+    @abstractmethod
+    async def get_providers(self) -> List[Provider]:
+        """
+        Get all providers from the repository.
+
+        Returns:
+            A list of providers.
+        """
+        pass

utcp/client/tool_search_strategies/tag_search.py

@@ -0,0 +1,67 @@
+from utcp.client.tool_search_strategy import ToolSearchStrategy
+from typing import List, Dict, Tuple
+from utcp.shared.tool import Tool
+from utcp.client.tool_repository import ToolRepository
+import re
+import asyncio
+
+class TagSearchStrategy(ToolSearchStrategy):
+
+    def __init__(self, tool_repository: ToolRepository, description_weight: float = 0.3):
+        self.tool_repository = tool_repository
+        # Weight for description words vs explicit tags (explicit tags have weight of 1.0)
+        self.description_weight = description_weight
+
+    async def search_tools(self, query: str, limit: int = 10) -> List[Tool]:
+        """
+        Return tools ordered by tag occurrences in the query.
+        
+        Uses both explicit tags and words from tool descriptions (with less weight).
+        
+        Args:
+            query: The search query string
+            limit: Maximum number of tools to return
+            
+        Returns:
+            List of tools ordered by relevance to the query
+        """
+        # Normalize query to lowercase and split into words
+        query_lower = query.lower()
+        # Extract words from the query, filtering out non-word characters
+        query_words = set(re.findall(r'\w+', query_lower))
+        
+        # Get all tools (using asyncio to run the coroutine)
+        tools = await self.tool_repository.get_tools()
+        
+        # Calculate scores for each tool
+        tool_scores: List[Tuple[Tool, float]] = []
+        
+        for tool in tools:
+            score = 0.0
+            
+            # Score from explicit tags (weight 1.0)
+            for tag in tool.tags:
+                tag_lower = tag.lower()
+                # Check if the tag appears in the query
+                if tag_lower in query_lower:
+                    score += 1.0
+                # Also check if the tag words match query words
+                tag_words = set(re.findall(r'\w+', tag_lower))
+                for word in tag_words:
+                    if word in query_words:
+                        score += self.description_weight  # Partial match for tag words
+            
+            # Score from description (with lower weight)
+            if tool.description:
+                description_words = set(re.findall(r'\w+', tool.description.lower()))
+                for word in description_words:
+                    if word in query_words and len(word) > 2:  # Only consider words with length > 2
+                        score += self.description_weight
+            
+            tool_scores.append((tool, score))
+        
+        # Sort tools by score in descending order
+        sorted_tools = [tool for tool, score in sorted(tool_scores, key=lambda x: x[1], reverse=True)]
+        
+        # Return up to 'limit' tools
+        return sorted_tools[:limit]

utcp/client/tool_search_strategy.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+from typing import List
+from utcp.shared.tool import Tool
+
+class ToolSearchStrategy(ABC):
+    @abstractmethod
+    async def search_tools(self, query: str, limit: int = 10) -> List[Tool]:
+        """
+        Search for tools relevant to the query.
+
+        Args:
+            query: The search query.
+            limit: The maximum number of tools to return. 0 for no limit.
+
+        Returns:
+            A list of tools that match the search query.
+        """
+        pass