utcp-socket 1.0.2__py3-none-any.whl

utcp_socket/__init__.py

@@ -0,0 +1,18 @@
+from utcp.plugins.discovery import register_communication_protocol, register_call_template
+from utcp_socket.tcp_communication_protocol import TCPTransport
+from utcp_socket.udp_communication_protocol import UDPTransport
+from utcp_socket.tcp_call_template import TCPProviderSerializer
+from utcp_socket.udp_call_template import UDPProviderSerializer
+
+
+def register() -> None:
+    # Register communication protocols
+    register_communication_protocol("tcp", TCPTransport())
+    register_communication_protocol("udp", UDPTransport())
+
+    # Register call templates and their serializers
+    register_call_template("tcp", TCPProviderSerializer())
+    register_call_template("udp", UDPProviderSerializer())
+
+
+__all__ = ["register"]

utcp_socket/tcp_call_template.py

@@ -0,0 +1,99 @@
+from utcp.data.call_template import CallTemplate
+from typing import Optional, Literal
+from pydantic import Field
+from utcp.interfaces.serializer import Serializer
+from utcp.exceptions import UtcpSerializerValidationError
+import traceback
+
+class TCPProvider(CallTemplate):
+    """Provider configuration for raw TCP socket tools.
+
+    Enables direct communication with TCP servers using custom protocols.
+    Supports flexible request formatting, response decoding, and multiple
+    framing strategies for message boundaries.
+
+    Request Data Handling:
+        - 'json' format: Arguments formatted as JSON object
+        - 'text' format: Template-based with UTCP_ARG_argname_UTCP_ARG placeholders
+
+    Response Data Handling:
+        - If response_byte_format is None: Returns raw bytes
+        - If response_byte_format is encoding string: Decodes bytes to text
+
+    TCP Stream Framing Options:
+        1. Length-prefix: Set framing_strategy='length_prefix' + length_prefix_bytes
+        2. Delimiter-based: Set framing_strategy='delimiter' + message_delimiter
+        3. Fixed-length: Set framing_strategy='fixed_length' + fixed_message_length
+        4. Stream-based: Set framing_strategy='stream' (reads until connection closes)
+
+    Attributes:
+        call_template_type: Always "tcp" for TCP providers.
+        host: The hostname or IP address of the TCP server.
+        port: The port number of the TCP server.
+        request_data_format: Format for request data ('json' or 'text').
+        request_data_template: Template string for 'text' format with placeholders.
+        response_byte_format: Encoding for response decoding (None for raw bytes).
+        framing_strategy: Method for detecting message boundaries.
+        length_prefix_bytes: Number of bytes for length prefix (1, 2, 4, or 8).
+        length_prefix_endian: Byte order for length prefix ('big' or 'little').
+        message_delimiter: Delimiter string for message boundaries.
+        fixed_message_length: Fixed length in bytes for each message.
+        max_response_size: Maximum bytes to read for stream-based framing.
+        timeout: Connection timeout in milliseconds.
+        auth: Always None - TCP providers don't support authentication.
+    """
+
+    call_template_type: Literal["tcp"] = "tcp"
+    host: str
+    port: int
+    request_data_format: Literal["json", "text"] = "json"
+    request_data_template: Optional[str] = None
+    response_byte_format: Optional[str] = Field(default="utf-8", description="Encoding to decode response bytes. If None, returns raw bytes.")
+    # TCP Framing Strategy
+    framing_strategy: Literal["length_prefix", "delimiter", "fixed_length", "stream"] = Field(
+        default="stream",
+        description="Strategy for framing TCP messages"
+    )
+    # Length-prefix framing options
+    length_prefix_bytes: Literal[1, 2, 4, 8] = Field(
+        default=4,
+        description="Number of bytes for length prefix (1, 2, 4, or 8). Used with 'length_prefix' framing."
+    )
+    length_prefix_endian: Literal["big", "little"] = Field(
+        default="big",
+        description="Byte order for length prefix. Used with 'length_prefix' framing."
+    )
+    # Delimiter-based framing options
+    message_delimiter: str = Field(
+        default='\x00',
+        description="Delimiter to detect end of TCP response (e.g., '\n', '\r\n', '\x00'). Used with 'delimiter' framing."
+    )
+    interpret_escape_sequences: bool = Field(
+        default=True,
+        description="If True, interpret Python-style escape sequences in message_delimiter (e.g., '\\n', '\\r\\n', '\\x00'). If False, use the delimiter literally as provided."
+    )
+    # Fixed-length framing options
+    fixed_message_length: Optional[int] = Field(
+        default=None,
+        description="Fixed length of each message in bytes. Used with 'fixed_length' framing."
+    )
+    # Stream-based options
+    max_response_size: int = Field(
+        default=65536,
+        description="Maximum bytes to read from TCP stream. Used with 'stream' framing."
+    )
+    timeout: int = 30000
+    auth: None = None
+
+
+class TCPProviderSerializer(Serializer[TCPProvider]):
+    def to_dict(self, obj: TCPProvider) -> dict:
+        return obj.model_dump()
+
+    def validate_dict(self, data: dict) -> TCPProvider:
+        try:
+            return TCPProvider.model_validate(data)
+        except Exception as e:
+            raise UtcpSerializerValidationError(
+                f"Invalid TCPProvider: {e}\n{traceback.format_exc()}"
+            )

utcp_socket/tcp_communication_protocol.py

@@ -0,0 +1,434 @@
+"""
+Transmission Control Protocol (TCP) transport for UTCP client.
+
+This transport communicates with tools over TCP sockets.
+"""
+import asyncio
+import json
+import socket
+import struct
+import sys
+from typing import Dict, Any, List, Optional, Callable, Union
+
+from utcp.interfaces.communication_protocol import CommunicationProtocol
+from utcp_socket.tcp_call_template import TCPProvider, TCPProviderSerializer
+from utcp.data.tool import Tool
+from utcp.data.call_template import CallTemplate, CallTemplateSerializer
+from utcp.data.register_manual_response import RegisterManualResult
+from utcp.data.utcp_manual import UtcpManual
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(filename)s:%(lineno)d - %(message)s"
+)
+
+logger = logging.getLogger(__name__)
+
+class TCPTransport(CommunicationProtocol):
+    """Transport implementation for TCP-based tool providers.
+    
+    This transport communicates with tools over TCP sockets. It supports:
+    - Tool discovery via TCP messages
+    - Tool execution by sending TCP packets with arguments
+    - Multiple framing strategies: length-prefix, delimiter, fixed-length, and stream
+    - JSON and text-based request formatting
+    - Template-based argument substitution
+    - Configurable response byte format (text encoding or raw bytes)
+    - Connection management for each request
+    """
+    
+    def __init__(self, logger: Optional[Callable[[str], None]] = None):
+        """Initialize the TCP transport.
+        
+        Args:
+            logger: Optional logger function for debugging
+        """
+        self._log = logger or (lambda *args, **kwargs: None)
+    
+    def _log_info(self, message: str):
+        """Log informational messages."""
+        self._log(f"[TCPTransport] {message}")
+        
+    def _log_error(self, message: str):
+        """Log error messages."""
+        logger.error(f"[TCPTransport Error] {message}")
+    
+    def _format_tool_call_message(
+        self,
+        tool_args: Dict[str, Any],
+        provider: TCPProvider
+    ) -> str:
+        """Format a tool call message based on provider configuration.
+        
+        Args:
+            tool_args: Arguments for the tool call
+            provider: The TCPProvider with formatting configuration
+            
+        Returns:
+            Formatted message string
+        """
+        if provider.request_data_format == "json":
+            return json.dumps(tool_args)
+        elif provider.request_data_format == "text":
+            # Use template-based formatting
+            if provider.request_data_template is not None and provider.request_data_template != "":
+                message = provider.request_data_template
+                # Replace placeholders with argument values
+                for arg_name, arg_value in tool_args.items():
+                    placeholder = f"UTCP_ARG_{arg_name}_UTCP_ARG"
+                    if isinstance(arg_value, str):
+                        message = message.replace(placeholder, arg_value)
+                    else:
+                        message = message.replace(placeholder, json.dumps(arg_value))
+                return message
+            else:
+                # Fallback to simple key=value format
+                return " ".join([str(v) for k, v in tool_args.items()])
+        else:
+            # Default to JSON format
+            return json.dumps(tool_args)
+
+    def _ensure_tool_call_template(self, tool_data: Dict[str, Any], manual_call_template: TCPProvider) -> Dict[str, Any]:
+        """Normalize tool definition to include a valid 'tool_call_template'.
+        
+        - If 'tool_call_template' exists, validate it.
+        - Else if legacy 'tool_provider' exists, convert using TCPProviderSerializer.
+        - Else default to the provided manual_call_template.
+        """
+        normalized = dict(tool_data)
+        try:
+            if "tool_call_template" in normalized and normalized["tool_call_template"] is not None:
+                try:
+                    ctpl = CallTemplateSerializer().validate_dict(normalized["tool_call_template"])  # type: ignore
+                    normalized["tool_call_template"] = ctpl
+                except Exception:
+                    normalized["tool_call_template"] = manual_call_template
+            elif "tool_provider" in normalized and normalized["tool_provider"] is not None:
+                try:
+                    ctpl = TCPProviderSerializer().validate_dict(normalized["tool_provider"])  # type: ignore
+                    normalized.pop("tool_provider", None)
+                    normalized["tool_call_template"] = ctpl
+                except Exception:
+                    normalized.pop("tool_provider", None)
+                    normalized["tool_call_template"] = manual_call_template
+            else:
+                normalized["tool_call_template"] = manual_call_template
+        except Exception:
+            normalized["tool_call_template"] = manual_call_template
+        return normalized
+    
+    def _encode_message_with_framing(self, message: str, provider: TCPProvider) -> bytes:
+        """Encode message with appropriate TCP framing.
+        
+        Args:
+            message: Message to encode
+            provider: TCPProvider with framing configuration
+            
+        Returns:
+            Framed message bytes
+        """
+        message_bytes = message.encode('utf-8')
+        
+        if provider.framing_strategy == "length_prefix":
+            # Add length prefix before the message
+            length = len(message_bytes)
+            if provider.length_prefix_bytes == 1:
+                length_bytes = struct.pack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}B", length)
+            elif provider.length_prefix_bytes == 2:
+                length_bytes = struct.pack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}H", length)
+            elif provider.length_prefix_bytes == 4:
+                length_bytes = struct.pack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}I", length)
+            elif provider.length_prefix_bytes == 8:
+                length_bytes = struct.pack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}Q", length)
+            else:
+                raise ValueError(f"Invalid length_prefix_bytes: {provider.length_prefix_bytes}")
+            return length_bytes + message_bytes
+        
+        elif provider.framing_strategy == "delimiter":
+            # Add delimiter after the message
+            delimiter = provider.message_delimiter or "\x00"
+            if provider.interpret_escape_sequences:
+                # Handle escape sequences (e.g., "\n", "\r\n", "\x00")
+                delimiter = delimiter.encode('utf-8').decode('unicode_escape')
+                delimiter_bytes = delimiter.encode('utf-8')
+            else:
+                # Use delimiter literally as provided
+                delimiter_bytes = delimiter.encode('utf-8')
+            return message_bytes + delimiter_bytes
+        
+        elif provider.framing_strategy in ("fixed_length", "stream"):
+            # No additional framing needed
+            return message_bytes
+        
+        else:
+            raise ValueError(f"Unknown framing strategy: {provider.framing_strategy}")
+    
+    def _decode_response_with_framing(self, sock: socket.socket, provider: TCPProvider, timeout: float) -> bytes:
+        """Decode response based on TCP framing strategy.
+        
+        Args:
+            sock: Connected TCP socket
+            provider: TCPProvider with framing configuration
+            timeout: Read timeout in seconds
+            
+        Returns:
+            Response message bytes
+        """
+        sock.settimeout(timeout)
+        
+        if provider.framing_strategy == "length_prefix":
+            # Read length prefix first
+            length_bytes = sock.recv(provider.length_prefix_bytes)
+            if len(length_bytes) < provider.length_prefix_bytes:
+                raise Exception(f"Incomplete length prefix: got {len(length_bytes)} bytes, expected {provider.length_prefix_bytes}")
+            
+            # Unpack length
+            if provider.length_prefix_bytes == 1:
+                length = struct.unpack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}B", length_bytes)[0]
+            elif provider.length_prefix_bytes == 2:
+                length = struct.unpack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}H", length_bytes)[0]
+            elif provider.length_prefix_bytes == 4:
+                length = struct.unpack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}I", length_bytes)[0]
+            elif provider.length_prefix_bytes == 8:
+                length = struct.unpack(f"{'>' if provider.length_prefix_endian == 'big' else '<'}Q", length_bytes)[0]
+            else:
+                raise ValueError(f"Invalid length_prefix_bytes: {provider.length_prefix_bytes}")
+            
+            # Read the message data
+            response_data = b""
+            while len(response_data) < length:
+                chunk = sock.recv(length - len(response_data))
+                if not chunk:
+                    raise Exception("Connection closed while reading message")
+                response_data += chunk
+            
+            return response_data
+        
+        elif provider.framing_strategy == "delimiter":
+            # Read until delimiter is found
+            # Delimiter handling:
+            # The code supports both literal delimiters (e.g., "\\x00") and escape-sequence interpreted delimiters (e.g., "\x00")
+            # via the `interpret_escape_sequences` flag in TCPProvider. This ensures compatibility with both legacy and updated
+            # wire protocols. The delimiter is interpreted according to the flag, so no breaking change occurs unless the flag
+            # is set differently than expected by the server/client.
+            # Example:
+            #     If interpret_escape_sequences is True, "\\x00" becomes a null byte; if False, it remains four literal bytes.
+            #     delimiter = delimiter.encode('utf-8')
+            delimiter = provider.message_delimiter or "\x00"
+            if provider.interpret_escape_sequences:
+                delimiter_bytes = delimiter.encode('utf-8').decode('unicode_escape').encode('utf-8')
+            else:
+                delimiter_bytes = delimiter.encode('utf-8')
+            
+            response_data = b""
+            while True:
+                chunk = sock.recv(1)
+                if not chunk:
+                    raise Exception("Connection closed while reading message")
+                response_data += chunk
+                
+                # Check if we've received the delimiter
+                if response_data.endswith(delimiter_bytes):
+                    # Remove delimiter from response
+                    return response_data[:-len(delimiter_bytes)]
+        
+        elif provider.framing_strategy == "fixed_length":
+            # Read exactly fixed_message_length bytes
+            if provider.fixed_message_length is None:
+                raise ValueError("fixed_message_length must be set for fixed_length framing")
+            
+            response_data = b""
+            while len(response_data) < provider.fixed_message_length:
+                chunk = sock.recv(provider.fixed_message_length - len(response_data))
+                if not chunk:
+                    raise Exception("Connection closed while reading message")
+                response_data += chunk
+            
+            return response_data
+        
+        elif provider.framing_strategy == "stream":
+            # Read until connection closes or max_response_size is reached
+            response_data = b""
+            while len(response_data) < provider.max_response_size:
+                try:
+                    chunk = sock.recv(min(4096, provider.max_response_size - len(response_data)))
+                    if not chunk:
+                        # Connection closed
+                        break
+                    response_data += chunk
+                except socket.timeout:
+                    # Timeout reached
+                    break
+            
+            return response_data
+
+        else:
+            # Copilot AI (5 days ago):
+            # The else branch for unknown framing strategies was previously removed,
+            # which could cause silent fallthrough and confusing behavior. Add explicit
+            # validation to raise a descriptive error when an unsupported strategy is provided.
+            raise ValueError(f"Unknown framing strategy: {provider.framing_strategy!r}")
+        
+    async def _send_tcp_message(
+        self,
+        host: str,
+        port: int,
+        message: str,
+        provider: TCPProvider,
+        timeout: float = 30.0,
+        response_encoding: Optional[str] = "utf-8"
+    ) -> Union[str, bytes]:
+        """Send a TCP message and wait for response.
+        
+        Args:
+            host: Host to connect to
+            port: Port to connect to
+            message: Message to send
+            provider: TCPProvider with framing configuration
+            timeout: Timeout in seconds
+            response_encoding: Encoding to decode response bytes. If None, returns raw bytes.
+            
+        Returns:
+            Response message or raw bytes if encoding is None
+        """
+        loop = asyncio.get_event_loop()
+        
+        def _send_and_receive():
+            """Blocking function to send TCP message and receive response."""
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            try:
+                # Set connection timeout
+                sock.settimeout(timeout)
+                
+                # Connect to server
+                sock.connect((host, port))
+                
+                # Encode message with framing
+                framed_message = self._encode_message_with_framing(message, provider)
+                
+                # Send message
+                sock.sendall(framed_message)
+                
+                # Receive response based on framing strategy
+                response_bytes = self._decode_response_with_framing(sock, provider, timeout)
+                
+                return response_bytes
+                
+            except socket.timeout:
+                raise Exception(f"TCP connection timeout after {timeout} seconds")
+            except Exception as e:
+                raise Exception(f"TCP communication error: {e}")
+            finally:
+                sock.close()
+        
+        try:
+            # Run blocking socket operations in executor
+            response_bytes = await loop.run_in_executor(None, _send_and_receive)
+            
+            # Return based on encoding preference
+            if response_encoding is None:
+                return response_bytes
+            else:
+                try:
+                    return response_bytes.decode(response_encoding)
+                except UnicodeDecodeError as e:
+                    self._log_error(f"Failed to decode response with encoding '{response_encoding}': {e}")
+                    # Return raw bytes as fallback
+                    return response_bytes
+                    
+        except Exception as e:
+            self._log_error(f"Error in TCP communication: {e}")
+            raise
+
+    async def register_manual(self, caller, manual_call_template: CallTemplate) -> RegisterManualResult:
+        """Register a TCP manual and discover its tools."""
+        if not isinstance(manual_call_template, TCPProvider):
+            raise ValueError("TCPTransport can only be used with TCPProvider")
+        
+        self._log_info(f"Registering TCP provider '{manual_call_template.name}'")
+        
+        try:
+            discovery_message = json.dumps({"type": "utcp"})
+            response = await self._send_tcp_message(
+                manual_call_template.host,
+                manual_call_template.port,
+                discovery_message,
+                manual_call_template,
+                manual_call_template.timeout / 1000.0,
+                manual_call_template.response_byte_format
+            )
+            try:
+                response_str = response.decode('utf-8') if isinstance(response, bytes) else response
+                response_data = json.loads(response_str)
+                tools: List[Tool] = []
+                if isinstance(response_data, dict) and 'tools' in response_data:
+                    tools_data = response_data['tools']
+                    for tool_data in tools_data:
+                        try:
+                            normalized = self._ensure_tool_call_template(tool_data, manual_call_template)
+                            tools.append(Tool(**normalized))
+                        except Exception as e:
+                            self._log_error(f"Invalid tool definition in TCP provider '{manual_call_template.name}': {e}")
+                            continue
+                    self._log_info(f"Discovered {len(tools)} tools from TCP provider '{manual_call_template.name}'")
+                else:
+                    self._log_info(f"No tools found in TCP provider '{manual_call_template.name}' response")
+                manual = UtcpManual(utcp_version="1.0", manual_version="1.0", tools=tools)
+                return RegisterManualResult(
+                    manual_call_template=manual_call_template,
+                    manual=manual,
+                    success=True,
+                    errors=[]
+                )
+            except json.JSONDecodeError as e:
+                self._log_error(f"Invalid JSON response from TCP provider '{manual_call_template.name}': {e}")
+                return RegisterManualResult(
+                    manual_call_template=manual_call_template,
+                    manual=UtcpManual(utcp_version="1.0", manual_version="1.0", tools=[]),
+                    success=False,
+                    errors=[str(e)]
+                )
+        except Exception as e:
+            self._log_error(f"Error registering TCP provider '{manual_call_template.name}': {e}")
+            return RegisterManualResult(
+                manual_call_template=manual_call_template,
+                manual=UtcpManual(utcp_version="1.0", manual_version="1.0", tools=[]),
+                success=False,
+                errors=[str(e)]
+            )
+    
+    async def deregister_manual(self, caller, manual_call_template: CallTemplate) -> None:
+        """Deregister a TCP provider (no-op)."""
+        if not isinstance(manual_call_template, TCPProvider):
+            raise ValueError("TCPTransport can only be used with TCPProvider")
+        self._log_info(f"Deregistering TCP provider '{manual_call_template.name}' (no-op)")
+    
+    async def call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate):
+        async def _generator():
+            yield await self.call_tool(caller, tool_name, tool_args, tool_call_template)
+        return _generator()
+    
+    async def call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> Any:
+        """Call a TCP tool."""
+        if not isinstance(tool_call_template, TCPProvider):
+            raise ValueError("TCPTransport can only be used with TCPProvider")
+        
+        self._log_info(f"Calling TCP tool '{tool_name}' on provider '{tool_call_template.name}'")
+        
+        try:
+            tool_call_message = self._format_tool_call_message(tool_args, tool_call_template)
+            
+            response = await self._send_tcp_message(
+                tool_call_template.host,
+                tool_call_template.port,
+                tool_call_message,
+                tool_call_template,
+                tool_call_template.timeout / 1000.0,
+                tool_call_template.response_byte_format
+            )
+            return response
+                
+        except Exception as e:
+            self._log_error(f"Error calling TCP tool '{tool_name}': {e}")
+            raise

utcp_socket/udp_call_template.py

@@ -0,0 +1,56 @@
+from utcp.data.call_template import CallTemplate
+from typing import Optional, Literal
+from pydantic import Field
+from utcp.interfaces.serializer import Serializer
+from utcp.exceptions import UtcpSerializerValidationError
+import traceback
+
+class UDPProvider(CallTemplate):
+    """Provider configuration for UDP (User Datagram Protocol) socket tools.
+
+    Enables communication with UDP servers using the connectionless UDP protocol.
+    Supports flexible request formatting, response decoding, and multi-datagram
+    response handling.
+
+    Request Data Handling:
+        - 'json' format: Arguments formatted as JSON object
+        - 'text' format: Template-based with UTCP_ARG_argname_UTCP_ARG placeholders
+
+    Response Data Handling:
+        - If response_byte_format is None: Returns raw bytes
+        - If response_byte_format is encoding string: Decodes bytes to text
+
+    Attributes:
+        call_template_type: Always "udp" for UDP providers.
+        host: The hostname or IP address of the UDP server.
+        port: The port number of the UDP server.
+        number_of_response_datagrams: Expected number of response datagrams (0 for no response).
+        request_data_format: Format for request data ('json' or 'text').
+        request_data_template: Template string for 'text' format with placeholders.
+        response_byte_format: Encoding for response decoding (None for raw bytes).
+        timeout: Request timeout in milliseconds.
+        auth: Always None - UDP providers don't support authentication.
+    """
+
+    call_template_type: Literal["udp"] = "udp"
+    host: str
+    port: int
+    number_of_response_datagrams: int = 1
+    request_data_format: Literal["json", "text"] = "json"
+    request_data_template: Optional[str] = None
+    response_byte_format: Optional[str] = Field(default="utf-8", description="Encoding to decode response bytes. If None, returns raw bytes.")
+    timeout: int = 30000
+    auth: None = None
+
+
+class UDPProviderSerializer(Serializer[UDPProvider]):
+    def to_dict(self, obj: UDPProvider) -> dict:
+        return obj.model_dump()
+
+    def validate_dict(self, data: dict) -> UDPProvider:
+        try:
+            return UDPProvider.model_validate(data)
+        except Exception as e:
+            raise UtcpSerializerValidationError(
+                f"Invalid UDPProvider: {e}\n{traceback.format_exc()}"
+            )

utcp_socket/udp_communication_protocol.py

@@ -0,0 +1,337 @@
+"""
+User Datagram Protocol (UDP) transport for UTCP client.
+
+This transport communicates with tools over UDP sockets.
+"""
+import asyncio
+import json
+import socket
+import traceback
+from typing import Dict, Any, List, Optional, Callable, Union
+
+from utcp.interfaces.communication_protocol import CommunicationProtocol
+from utcp_socket.udp_call_template import UDPProvider, UDPProviderSerializer
+from utcp.data.tool import Tool
+from utcp.data.call_template import CallTemplate, CallTemplateSerializer
+from utcp.data.register_manual_response import RegisterManualResult
+from utcp.data.utcp_manual import UtcpManual
+from utcp.exceptions import UtcpSerializerValidationError
+import logging
+
+logger = logging.getLogger(__name__)
+
+class UDPTransport(CommunicationProtocol):
+    """Transport implementation for UDP-based tool providers.
+    
+    This transport communicates with tools over UDP sockets. It supports:
+    - Tool discovery via UDP messages
+    - Tool execution by sending UDP packets with arguments
+    - Multiple response datagrams handling
+    - JSON and text-based request formatting
+    - Template-based argument substitution
+    - Configurable response byte format (text encoding or raw bytes)
+    - Stateless operation (no persistent connections)
+    """
+    
+    def __init__(self, logger: Optional[Callable[[str], None]] = None):
+        """Initialize the UDP transport.
+        
+        Args:
+            logger: Optional logger function for debugging
+        """
+        self._log = logger or (lambda *args, **kwargs: None)
+        # UDP is stateless, so no connections to manage
+    
+    def _log_info(self, message: str):
+        """Log informational messages."""
+        self._log(f"[UDPTransport] {message}")
+        
+    def _log_error(self, message: str):
+        """Log error messages."""
+        logger.error(f"[UDPTransport Error] {message}")
+    
+    def _format_tool_call_message(
+        self,
+        tool_args: Dict[str, Any],
+        provider: UDPProvider
+    ) -> str:
+        """Format a tool call message based on provider configuration.
+        
+        Args:
+            tool_args: Arguments for the tool call
+            provider: The UDPProvider with formatting configuration
+            
+        Returns:
+            Formatted message string
+        """
+        if provider.request_data_format == "json":
+            return json.dumps(tool_args)
+        elif provider.request_data_format == "text":
+            # Use template-based formatting
+            if provider.request_data_template is not None and provider.request_data_template != "":
+                message = provider.request_data_template
+                # Replace placeholders with argument values
+                for arg_name, arg_value in tool_args.items():
+                    placeholder = f"UTCP_ARG_{arg_name}_UTCP_ARG"
+                    if isinstance(arg_value, str):
+                        message = message.replace(placeholder, arg_value)
+                    else:
+                        message = message.replace(placeholder, json.dumps(arg_value))
+                return message
+            else:
+                # Fallback to simple key=value format
+                return " ".join([str(v) for k, v in tool_args.items()])
+        else:
+            # Default to JSON format
+            return json.dumps(tool_args)
+
+    def _ensure_tool_call_template(self, tool_data: Dict[str, Any], manual_call_template: UDPProvider) -> Dict[str, Any]:
+        """Normalize tool definition to include a valid 'tool_call_template'.
+        
+        - If 'tool_call_template' exists, validate it.
+        - Else if legacy 'tool_provider' exists, convert using UDPProviderSerializer.
+        - Else default to the provided manual_call_template.
+        """
+        normalized = dict(tool_data)
+        try:
+            if "tool_call_template" in normalized and normalized["tool_call_template"] is not None:
+                # Validate via generic CallTemplate serializer (type-dispatched)
+                try:
+                    ctpl = CallTemplateSerializer().validate_dict(normalized["tool_call_template"])  # type: ignore
+                    normalized["tool_call_template"] = ctpl
+                except (UtcpSerializerValidationError, ValueError) as e:
+                    # Fallback to manual template if validation fails, but log details
+                    logger.exception("Failed to validate existing tool_call_template; falling back to manual template")
+                    normalized["tool_call_template"] = manual_call_template
+            elif "tool_provider" in normalized and normalized["tool_provider"] is not None:
+                # Convert legacy provider -> call template
+                try:
+                    ctpl = UDPProviderSerializer().validate_dict(normalized["tool_provider"])  # type: ignore
+                    normalized.pop("tool_provider", None)
+                    normalized["tool_call_template"] = ctpl
+                except UtcpSerializerValidationError as e:
+                    logger.exception("Failed to convert legacy tool_provider to call template; falling back to manual template")
+                    normalized.pop("tool_provider", None)
+                    normalized["tool_call_template"] = manual_call_template
+            else:
+                normalized["tool_call_template"] = manual_call_template
+        except Exception:
+            # Any unexpected error during normalization should be logged
+            logger.exception("Unexpected error normalizing tool definition; falling back to manual template")
+            normalized["tool_call_template"] = manual_call_template
+        return normalized
+    
+    async def _send_udp_message(
+        self,
+        host: str,
+        port: int,
+        message: str,
+        timeout: float = 30.0,
+        num_response_datagrams: int = 1,
+        response_encoding: Optional[str] = "utf-8"
+    ) -> Union[str, bytes]:
+        """Send a UDP message and wait for response(s).
+        
+        Args:
+            host: Host to send message to
+            port: Port to send message to
+            message: Message to send
+            timeout: Timeout in seconds
+            num_response_datagrams: Number of response datagrams to receive
+            response_encoding: Encoding to decode response bytes. If None, returns raw bytes.
+            
+        Returns:
+            Response message (concatenated if multiple datagrams) or raw bytes if encoding is None
+        """
+        if num_response_datagrams == 0:
+            # No response expected - just send and return
+            await self._send_udp_no_response(host, port, message)
+            return b"" if response_encoding is None else ""
+        
+        # Use simple socket approach with executor for Windows compatibility
+        loop = asyncio.get_event_loop()
+        
+        def _send_and_receive():
+            """Blocking function to send UDP message and receive responses."""
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            try:
+                # Resolve host to IP for comparison
+                try:
+                    resolved_host_ip = socket.gethostbyname(host)
+                except socket.gaierror:
+                    resolved_host_ip = host  # Fallback to original if resolution fails
+                
+                # Send message
+                message_bytes = message.encode('utf-8')
+                sock.sendto(message_bytes, (host, port))
+                
+                # Collect responses
+                response_bytes_list = []
+                
+                for i in range(max(1, num_response_datagrams)):
+                    try:
+                        # Use shorter timeout for subsequent datagrams
+                        current_timeout = timeout if i == 0 else 1.0
+                        
+                        # Set socket timeout
+                        sock.settimeout(current_timeout)
+                        
+                        # Receive response
+                        data, addr = sock.recvfrom(65535)
+                        
+                        # Verify it's from the expected host (compare with resolved IP)
+                        if addr[0] == host or addr[0] == resolved_host_ip:
+                            response_bytes_list.append(data)
+                        else:
+                            # Got response from wrong host, don't count it
+                            continue
+                            
+                    except socket.timeout:
+                        if i == 0:
+                            # First datagram timed out
+                            raise TimeoutError(f"UDP request timed out after {timeout} seconds")
+                        else:
+                            # Subsequent datagrams timed out, but we have some data
+                            break
+                
+                return response_bytes_list
+                
+            finally:
+                sock.close()
+        
+        try:
+            # Run blocking socket operations in executor
+            response_bytes_list = await loop.run_in_executor(None, _send_and_receive)
+            
+            # Concatenate response bytes
+            combined_bytes = b''.join(response_bytes_list)
+            
+            # Return based on encoding preference
+            if response_encoding is None:
+                return combined_bytes
+            else:
+                try:
+                    return combined_bytes.decode(response_encoding)
+                except UnicodeDecodeError as e:
+                    self._log_error(f"Failed to decode response with encoding '{response_encoding}': {e}")
+                    # Return raw bytes as fallback
+                    return combined_bytes
+                    
+        except TimeoutError as e:
+            self._log_error(traceback.format_exc())
+            raise asyncio.TimeoutError(traceback.format_exc())
+        except Exception as e:
+            self._log_error(f"Error sending UDP message: {traceback.format_exc()}")
+            raise
+    
+    async def _send_udp_no_response(self, host: str, port: int, message: str) -> None:
+        """Send a UDP message without expecting a response."""
+        def _send_only():
+            """Blocking function to send UDP message only."""
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            try:
+                message_bytes = message.encode('utf-8')
+                sock.sendto(message_bytes, (host, port))
+            finally:
+                sock.close()
+        
+        try:
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, _send_only)
+        except Exception as e:
+            self._log_error(f"Error sending UDP message (no response): {traceback.format_exc()}")
+            raise
+    
+    async def register_manual(self, caller, manual_call_template: CallTemplate) -> RegisterManualResult:
+        """Register a UDP manual and discover its tools."""
+        if not isinstance(manual_call_template, UDPProvider):
+            raise ValueError("UDPTransport can only be used with UDPProvider")
+        
+        self._log_info(f"Registering UDP provider '{manual_call_template.name}' at {manual_call_template.host}:{manual_call_template.port}")
+        
+        try:
+            discovery_message = json.dumps({"type": "utcp"})
+            response = await self._send_udp_message(
+                manual_call_template.host,
+                manual_call_template.port,
+                discovery_message,
+                manual_call_template.timeout / 1000.0,
+                manual_call_template.number_of_response_datagrams,
+                manual_call_template.response_byte_format
+            )
+            try:
+                response_str = response.decode('utf-8') if isinstance(response, bytes) else response
+                response_data = json.loads(response_str)
+                tools: List[Tool] = []
+                if isinstance(response_data, dict) and 'tools' in response_data:
+                    tools_data = response_data['tools']
+                    for tool_data in tools_data:
+                        try:
+                            normalized = self._ensure_tool_call_template(tool_data, manual_call_template)
+                            tool = Tool(**normalized)
+                            tools.append(tool)
+                        except Exception:
+                            self._log_error(f"Invalid tool definition in UDP provider '{manual_call_template.name}': {traceback.format_exc()}")
+                            continue
+                    self._log_info(f"Discovered {len(tools)} tools from UDP provider '{manual_call_template.name}'")
+                else:
+                    self._log_info(f"No tools found in UDP provider '{manual_call_template.name}' response")
+                manual = UtcpManual(utcp_version="1.0", manual_version="1.0", tools=tools)
+                return RegisterManualResult(
+                    manual_call_template=manual_call_template,
+                    manual=manual,
+                    success=True,
+                    errors=[]
+                )
+            except json.JSONDecodeError as e:
+                self._log_error(f"Invalid JSON response from UDP provider '{manual_call_template.name}': {traceback.format_exc()}")
+                manual = UtcpManual(utcp_version="1.0", manual_version="1.0", tools=[])
+                return RegisterManualResult(
+                    manual_call_template=manual_call_template,
+                    manual=manual,
+                    success=False,
+                    errors=[str(e)]
+                )
+        except Exception as e:
+            self._log_error(f"Error registering UDP provider '{manual_call_template.name}': {traceback.format_exc()}")
+            manual = UtcpManual(utcp_version="1.0", manual_version="1.0", tools=[])
+            return RegisterManualResult(
+                manual_call_template=manual_call_template,
+                manual=manual,
+                success=False,
+                errors=[str(e)]
+            )
+    
+    async def deregister_manual(self, caller, manual_call_template: CallTemplate) -> None:
+        if not isinstance(manual_call_template, UDPProvider):
+            raise ValueError("UDPTransport can only be used with UDPProvider")
+        self._log_info(f"Deregistering UDP provider '{manual_call_template.name}' (no-op)")
+    
+    async def call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> Any:
+        if not isinstance(tool_call_template, UDPProvider):
+            raise ValueError("UDPTransport can only be used with UDPProvider")
+        self._log_info(f"Calling UDP tool '{tool_name}' on provider '{tool_call_template.name}'")
+        try:
+            tool_call_message = self._format_tool_call_message(tool_args, tool_call_template)
+            response = await self._send_udp_message(
+                tool_call_template.host,
+                tool_call_template.port,
+                tool_call_message,
+                tool_call_template.timeout / 1000.0,
+                tool_call_template.number_of_response_datagrams,
+                tool_call_template.response_byte_format
+            )
+            return response
+        except Exception as e:
+            self._log_error(f"Error calling UDP tool '{tool_name}': {traceback.format_exc()}")
+            raise
+
+    # Copilot AI (5 days ago):
+    # The call_tool_streaming method wraps a generator function but doesn't use the async def syntax for the method itself.
+    # While this works, it's inconsistent with the other implementation in tcp_communication_protocol.py (lines 384-387) which properly uses async def with an inner generator.
+    # For consistency and clarity, this should also use async def directly:
+    #
+    # async def call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate):
+    #     yield await self.call_tool(caller, tool_name, tool_args, tool_call_template)
+    async def call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate):
+        yield await self.call_tool(caller, tool_name, tool_args, tool_call_template)

utcp_socket-1.0.2.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: utcp-socket
+Version: 1.0.2
+Summary: UTCP communication protocol plugin for TCP and UDP protocols. (Work in progress)
+Author: UTCP Contributors
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://utcp.io
+Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
+Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: utcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# UTCP Socket Plugin (UDP/TCP)
+
+This plugin adds UDP and TCP communication protocols to UTCP 1.0.
+
+## Running Tests
+
+Prerequisites:
+- Python 3.10+
+- `pip`
+- (Optional) a virtual environment
+
+1) Install core and the socket plugin in editable mode with dev extras:
+
+```bash
+pip install -e "./core[dev]"
+pip install -e ./plugins/communication_protocols/socket[dev]
+```
+
+2) Run the socket plugin tests:
+
+```bash
+python -m pytest plugins/communication_protocols/socket/tests -v
+```
+
+3) Run a single test or filter by keyword:
+
+```bash
+# One file
+python -m pytest plugins/communication_protocols/socket/tests/test_tcp_communication_protocol.py -v
+
+# Filter by keyword (e.g., delimiter framing)
+python -m pytest plugins/communication_protocols/socket/tests -k delimiter -q
+```
+
+4) Optional end-to-end sanity check (mock UDP/TCP servers):
+
+```bash
+python scripts/socket_sanity.py
+```
+
+Notes:
+- On Windows, your firewall may prompt the first time tests open UDP/TCP sockets; allow access or run as admin if needed.
+- Tests use `pytest-asyncio`. The dev extras installed above provide required dependencies.
+- Streaming is single-chunk by design, consistent with HTTP/Text transports. Multi-chunk streaming can be added later behind provider configuration.

utcp_socket-1.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+utcp_socket/__init__.py,sha256=KEFMWm3BXEiCtw60ICqwMvzzNMsSlLbc1BxtvSnFsiI,742
+utcp_socket/tcp_call_template.py,sha256=8DdoLO3eIskWdIqF0Y-zhaWoD1uPFRN2VZq6h88bdlc,4600
+utcp_socket/tcp_communication_protocol.py,sha256=jcg6WwSQGnOaMAZuIS3_17UqvgCLGC31bNMWUeP_s_c,20481
+utcp_socket/udp_call_template.py,sha256=ibXMAGb9qTeLkqhmTi3PDrnqxwB5bTH-l-Ut43_6j_A,2419
+utcp_socket/udp_communication_protocol.py,sha256=j2IuqMsX8TrJzySyp1FtAozA5aCUTv8VbL7cFrlfowQ,16592
+utcp_socket-1.0.2.dist-info/METADATA,sha256=N4DAeOgjJn8hv369NGdJo7Cx3w4Jty3u5WB6OapKs2I,2290
+utcp_socket-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+utcp_socket-1.0.2.dist-info/entry_points.txt,sha256=Y2Q2PwwL-B6ODwaWEohMtrpipKvRBg3AYgE-s6Toalk,45
+utcp_socket-1.0.2.dist-info/top_level.txt,sha256=Tys91lBOENWnB_K59d1xKKwJgaB5UZRx8BITQ5szn4I,12
+utcp_socket-1.0.2.dist-info/RECORD,,

utcp_socket-1.0.2.dist-info/WHEEL

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

utcp_socket-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[utcp.plugins]
+socket = utcp_socket:register

utcp_socket-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+utcp_socket