utcp-cli 1.0.0__tar.gz

utcp_cli-1.0.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: utcp-cli
+Version: 1.0.0
+Summary: Universal Tool Calling Protocol (UTCP) client library for Python
+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: pyyaml>=6.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_cli-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "utcp-cli"
+version = "1.0.0"
+authors = [
+  { name = "UTCP Contributors" },
+]
+description = "Universal Tool Calling Protocol (UTCP) client library for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "utcp>=1.0"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MPL-2.0"
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "coverage",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://utcp.io"
+Source = "https://github.com/universal-tool-calling-protocol/python-utcp"
+Issues = "https://github.com/universal-tool-calling-protocol/python-utcp/issues"
+
+[project.entry-points."utcp.plugins"]
+cli = "utcp_cli:register"

utcp_cli-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

utcp_cli-1.0.0/src/utcp_cli/__init__.py

@@ -0,0 +1,13 @@
+from utcp.plugins.discovery import register_communication_protocol, register_call_template
+from utcp_cli.cli_communication_protocol import CliCommunicationProtocol
+from utcp_cli.cli_call_template import CliCallTemplate, CliCallTemplateSerializer
+
+def register():
+    register_communication_protocol("cli", CliCommunicationProtocol())
+    register_call_template("cli", CliCallTemplateSerializer())
+
+__all__ = [
+    "CliCommunicationProtocol",
+    "CliCallTemplate",
+    "CliCallTemplateSerializer",
+]

utcp_cli-1.0.0/src/utcp_cli/cli_call_template.py

@@ -0,0 +1,44 @@
+from typing import Optional, Dict, Literal
+from pydantic import Field
+
+from utcp.data.call_template import CallTemplate
+from utcp.interfaces.serializer import Serializer
+from utcp.exceptions import UtcpSerializerValidationError
+import traceback
+
+class CliCallTemplate(CallTemplate):
+    """Call template configuration for Command Line Interface tools.
+
+    Enables execution of command-line tools and programs as UTCP providers.
+    Supports environment variable injection and custom working directories.
+
+    Attributes:
+        call_template_type: Always "cli" for CLI providers.
+        command_name: The name or path of the command to execute.
+        env_vars: Optional environment variables to set during command execution.
+        working_dir: Optional custom working directory for command execution.
+        auth: Always None - CLI providers don't support authentication.
+    """
+
+    call_template_type: Literal["cli"] = "cli"
+    command_name: str
+    env_vars: Optional[Dict[str, str]] = Field(
+        default=None, description="Environment variables to set when executing the command"
+    )
+    working_dir: Optional[str] = Field(
+        default=None, description="Working directory for command execution"
+    )
+    auth: None = None
+
+
+class CliCallTemplateSerializer(Serializer[CliCallTemplate]):
+    """Serializer for CliCallTemplate."""
+
+    def to_dict(self, obj: CliCallTemplate) -> dict:
+        return obj.model_dump()
+
+    def validate_dict(self, obj: dict) -> CliCallTemplate:
+        try:
+            return CliCallTemplate.model_validate(obj)
+        except Exception as e:
+            raise UtcpSerializerValidationError("Invalid CliCallTemplate: " + traceback.format_exc()) from e

utcp_cli-1.0.0/src/utcp_cli/cli_communication_protocol.py

@@ -0,0 +1,482 @@
+"""Command Line Interface (CLI) transport for UTCP client.
+
+This module provides the CLI transport implementation that enables UTCP clients
+to interact with command-line tools and processes. It handles tool discovery
+through startup commands, tool execution with proper argument formatting,
+and output processing with JSON parsing capabilities.
+
+Key Features:
+    - Asynchronous command execution with timeout handling
+    - Tool discovery via startup commands that output UTCP manuals
+    - Flexible argument formatting for command-line flags
+    - Environment variable support for authentication and configuration
+    - JSON output parsing with fallback to raw text
+    - Cross-platform command parsing (Windows/Unix)
+    - Working directory control for command execution
+
+Security:
+    - Command execution is isolated through subprocess
+    - Environment variables can be controlled per provider
+    - Working directory can be restricted
+"""
+import asyncio
+import json
+import os
+import shlex
+from typing import Dict, Any, List, Optional, Callable, AsyncGenerator
+
+from utcp.interfaces.communication_protocol import CommunicationProtocol
+from utcp.data.call_template import CallTemplate, CallTemplateSerializer
+from utcp.data.tool import Tool
+from utcp.data.utcp_manual import UtcpManual, UtcpManualSerializer
+from utcp.data.register_manual_response import RegisterManualResult
+from utcp_cli.cli_call_template import CliCallTemplate, CliCallTemplateSerializer
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class CliCommunicationProtocol(CommunicationProtocol):
+    """Transport implementation for CLI-based tool providers.
+
+    Handles communication with command-line tools by executing processes
+    and managing their input/output. Supports both tool discovery and
+    execution phases with comprehensive error handling and timeout management.
+
+    Features:
+        - Asynchronous subprocess execution with proper cleanup
+        - Tool discovery through startup commands returning UTCP manuals
+        - Flexible argument formatting for various CLI conventions
+        - Environment variable injection for authentication
+        - JSON output parsing with graceful fallback to text
+        - Cross-platform command parsing and execution
+        - Configurable working directories and timeouts
+        - Process lifecycle management with proper termination
+
+    Architecture:
+        CLI tools are discovered by executing the provider's command_name
+        and parsing the output for UTCP manual JSON. Tool calls execute
+        the same command with formatted arguments and return processed output.
+
+    Attributes:
+        _log: Logger function for debugging and error reporting.
+    """
+    
+    def __init__(self):
+        """Initialize the CLI transport."""
+    
+    def _log_info(self, message: str):
+        """Log informational messages."""
+        logger.info(f"[CliCommunicationProtocol] {message}")
+        
+    def _log_error(self, message: str):
+        """Log error messages."""
+        logger.error(f"[CliCommunicationProtocol Error] {message}")
+    
+    def _prepare_environment(self, provider: CliCallTemplate) -> Dict[str, str]:
+        """Prepare environment variables for command execution.
+        
+        Args:
+            provider: The CLI provider
+            
+        Returns:
+            Environment variables dictionary
+        """
+        import os
+        env = os.environ.copy()
+        
+        # Add custom environment variables if provided
+        if provider.env_vars:
+            env.update(provider.env_vars)
+        
+        return env
+    
+    async def _execute_command(
+        self,
+        command: List[str],
+        env: Dict[str, str],
+        timeout: float = 30.0,
+        input_data: Optional[str] = None,
+        working_dir: Optional[str] = None
+    ) -> tuple[str, str, int]:
+        """Execute a command asynchronously.
+
+        Args:
+            command: Command and arguments to execute
+            env: Environment variables
+            timeout: Timeout in seconds
+            input_data: Optional input data to pass to the command
+            working_dir: Working directory for command execution
+            
+        Returns:
+            Tuple of (stdout, stderr, return_code)
+        """
+        process = None
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+                cwd=working_dir,
+                stdin=asyncio.subprocess.PIPE if input_data else None
+            )
+            
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                process.communicate(input=input_data.encode('utf-8') if input_data else None),
+                timeout=timeout
+            )
+            
+            stdout = stdout_bytes.decode('utf-8', errors='replace')
+            stderr = stderr_bytes.decode('utf-8', errors='replace')
+            
+            return stdout, stderr, process.returncode or 0
+            
+        except asyncio.TimeoutError:
+            # Kill the process if it times out
+            if process:
+                try:
+                    process.kill()
+                    await process.wait()
+                except ProcessLookupError:
+                    pass  # Process already terminated
+            self._log_error(f"Command timed out after {timeout} seconds: {' '.join(command)}")
+            raise
+        except Exception as e:
+            # Ensure process is cleaned up on any error
+            if process:
+                try:
+                    process.kill()
+                    await process.wait()
+                except ProcessLookupError:
+                    pass  # Process already terminated
+            self._log_error(f"Error executing command {' '.join(command)}: {e}")
+            raise
+    
+    async def register_manual(self, caller, manual_call_template: CallTemplate) -> RegisterManualResult:
+        """Register a CLI manual and discover its tools.
+        
+        Executes the call template's command_name and looks for a UTCP manual JSON in the output.
+        """
+        if not isinstance(manual_call_template, CliCallTemplate):
+            raise ValueError("CliCommunicationProtocol can only be used with CliCallTemplate")
+
+        if not manual_call_template.command_name:
+            raise ValueError(f"CliCallTemplate '{manual_call_template.name}' must have command_name set")
+
+        self._log_info(
+            f"Registering CLI manual '{manual_call_template.name}' with command '{manual_call_template.command_name}'"
+        )
+
+        try:
+            env = self._prepare_environment(manual_call_template)
+            # Parse command string into proper arguments
+            # Use posix=False on Windows, posix=True on Unix-like systems
+            command = shlex.split(manual_call_template.command_name, posix=(os.name != 'nt'))
+
+            self._log_info(f"Executing command for tool discovery: {' '.join(command)}")
+
+            stdout, stderr, return_code = await self._execute_command(
+                command,
+                env,
+                timeout=30.0,
+                working_dir=manual_call_template.working_dir,
+            )
+
+            # Get output based on exit code
+            output = stdout if return_code == 0 else stderr
+
+            if not output.strip():
+                self._log_info(
+                    f"No output from command '{manual_call_template.command_name}'"
+                )
+                return RegisterManualResult(
+                    success=False,
+                    manual_call_template=manual_call_template,
+                    manual=UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=[]),
+                    errors=[
+                        f"No output from discovery command for CLI provider '{manual_call_template.name}'"
+                    ],
+                )
+
+            # Try to parse UTCPManual from the output
+            utcp_manual = self._extract_utcp_manual_from_output(
+                output, manual_call_template.name
+            )
+
+            if utcp_manual is None:
+                error_msg = (
+                    f"Could not parse UTCP manual from CLI provider '{manual_call_template.name}' output"
+                )
+                self._log_error(error_msg)
+                return RegisterManualResult(
+                    success=False,
+                    manual_call_template=manual_call_template,
+                    manual=UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=[]),
+                    errors=[error_msg],
+                )
+
+            self._log_info(
+                f"Discovered {len(utcp_manual.tools)} tools from CLI provider '{manual_call_template.name}'"
+            )
+            return RegisterManualResult(
+                success=True,
+                manual_call_template=manual_call_template,
+                manual=utcp_manual,
+                errors=[],
+            )
+
+        except Exception as e:
+            error_msg = f"Error discovering tools from CLI provider '{manual_call_template.name}': {e}"
+            self._log_error(error_msg)
+            return RegisterManualResult(
+                success=False,
+                manual_call_template=manual_call_template,
+                manual=UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=[]),
+                errors=[error_msg],
+            )
+    
+    async def deregister_manual(self, caller, manual_call_template: CallTemplate) -> None:
+        """Deregister a CLI manual (no-op)."""
+        if isinstance(manual_call_template, CliCallTemplate):
+            self._log_info(
+                f"Deregistering CLI manual '{manual_call_template.name}' (no-op)"
+            )
+    
+    def _format_arguments(self, tool_args: Dict[str, Any]) -> List[str]:
+        """Format arguments for command-line execution.
+        
+        Converts a dictionary of arguments into command-line flags and values.
+        
+        Args:
+            tool_args: Dictionary of argument names and values
+            
+        Returns:
+            List of command-line arguments
+        """
+        args = []
+        for key, value in tool_args.items():
+            if isinstance(value, bool):
+                if value:
+                    args.append(f"--{key}")
+            elif isinstance(value, (list, tuple)):
+                for item in value:
+                    args.extend([f"--{key}", str(item)])
+            else:
+                args.extend([f"--{key}", str(value)])
+        return args
+    
+    def _extract_utcp_manual_from_output(self, output: str, provider_name: str) -> Optional[UtcpManual]:
+        """Extract a UTCP manual from command output.
+        
+        Tries to parse the output as a UTCP manual. If it instead looks like a list of tools,
+        wraps them in a basic UtcpManual structure.
+        """
+        # Try to parse the entire output as JSON first
+        try:
+            data = json.loads(output.strip())
+            if isinstance(data, dict) and "utcp_version" in data and "tools" in data:
+                try:
+                    return UtcpManualSerializer().validate_dict(data)
+                except Exception as e:
+                    self._log_error(
+                        f"Invalid UTCP manual format from provider '{provider_name}': {e}"
+                    )
+                    # Fallback: try to parse tools from possibly-legacy structure
+                    tools = self._parse_tool_data(data, provider_name)
+                    if tools:
+                        return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=tools)
+                    return None
+            # Fallback: try to parse as tools
+            tools = self._parse_tool_data(data, provider_name)
+            if tools:
+                return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=tools)
+        except json.JSONDecodeError:
+            pass
+
+        # Look for JSON objects within the output text and aggregate tools
+        aggregated_tools: List[Tool] = []
+        lines = output.split('\n')
+        for line in lines:
+            line = line.strip()
+            if line.startswith('{') and line.endswith('}'):
+                try:
+                    data = json.loads(line)
+                    # If a full manual is found in a line, return it immediately
+                    if isinstance(data, dict) and "utcp_version" in data and "tools" in data:
+                        try:
+                            return UtcpManualSerializer().validate_dict(data)
+                        except Exception as e:
+                            self._log_error(
+                                f"Invalid UTCP manual format from provider '{provider_name}': {e}"
+                            )
+                            # Fallback: try to parse tools from possibly-legacy structure
+                            tools = self._parse_tool_data(data, provider_name)
+                            if tools:
+                                return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=tools)
+                            return None
+                    found_tools = self._parse_tool_data(data, provider_name)
+                    aggregated_tools.extend(found_tools)
+                except json.JSONDecodeError:
+                    continue
+
+        if aggregated_tools:
+            return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=aggregated_tools)
+
+        return None
+    
+    def _build_tool_from_dict(self, tool_data: Any, provider_name: str) -> Optional[Tool]:
+        """Build a Tool object from a dictionary, supporting legacy keys.
+        
+        This maps legacy 'tool_provider' into the new 'tool_call_template'
+        using the appropriate call template serializers.
+        """
+        try:
+            if isinstance(tool_data, dict):
+                # If already new-style and call template is a dict, validate it
+                if "tool_call_template" in tool_data and isinstance(tool_data["tool_call_template"], dict):
+                    td = dict(tool_data)
+                    td["tool_call_template"] = CallTemplateSerializer().validate_dict(td["tool_call_template"])
+                    return Tool(**td)
+                
+                # Legacy style: 'tool_provider'
+                if "tool_provider" in tool_data and isinstance(tool_data["tool_provider"], dict):
+                    provider = tool_data["tool_provider"]
+                    provider_type = provider.get("provider_type") or provider.get("type")
+                    # Normalize to call template dict
+                    call_template_dict = {k: v for k, v in provider.items() if k != "provider_type"}
+                    call_template_dict["type"] = provider_type
+                    
+                    # Validate based on type
+                    if provider_type == "cli":
+                        call_template = CliCallTemplateSerializer().validate_dict(call_template_dict)
+                    else:
+                        call_template = CallTemplateSerializer().validate_dict(call_template_dict)
+                    
+                    td = dict(tool_data)
+                    td.pop("tool_provider", None)
+                    td["tool_call_template"] = call_template
+                    return Tool(**td)
+                
+                # Already a Tool-like dict with correct fields
+                return Tool(**tool_data)
+        except Exception as e:
+            self._log_error(f"Invalid tool definition from provider '{provider_name}': {e}")
+            return None
+        return None
+    
+    def _parse_tool_data(self, data: Any, provider_name: str) -> List[Tool]:
+        """Parse tool data from JSON.
+        
+        Supports both the new format (with 'tool_call_template') and the
+        legacy format (with 'tool_provider').
+        
+        Args:
+            data: JSON data to parse
+            provider_name: Name of the provider for logging
+            
+        Returns:
+            List of tools parsed from the data
+        """
+        tools: List[Tool] = []
+        if isinstance(data, dict):
+            if 'tools' in data and isinstance(data['tools'], list):
+                for item in data['tools']:
+                    built = self._build_tool_from_dict(item, provider_name)
+                    if built is not None:
+                        tools.append(built)
+                return tools
+            elif 'name' in data and 'description' in data:
+                built = self._build_tool_from_dict(data, provider_name)
+                return [built] if built is not None else []
+        elif isinstance(data, list):
+            for item in data:
+                built = self._build_tool_from_dict(item, provider_name)
+                if built is not None:
+                    tools.append(built)
+            return tools
+        
+        return tools
+    
+    async def call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> Any:
+        """Call a CLI tool.
+        
+        Executes the command specified by provider.command_name with the provided arguments.
+        
+        Args:
+            caller: The UTCP client that is calling this method.
+            tool_name: Name of the tool to call
+            tool_args: Arguments for the tool call
+            tool_call_template: The CliCallTemplate for the tool
+            
+        Returns:
+            The output from the command execution based on exit code:
+            - If exit code is 0: stdout (parsed as JSON if possible, otherwise raw string)
+            - If exit code is not 0: stderr
+            
+        Raises:
+            ValueError: If provider is not a CliProvider or command_name is not set
+        """
+        if not isinstance(tool_call_template, CliCallTemplate):
+            raise ValueError("CliCommunicationProtocol can only be used with CliCallTemplate")
+        
+        if not tool_call_template.command_name:
+            raise ValueError(f"CliCallTemplate '{tool_call_template.name}' must have command_name set")
+        
+        # Build the command
+        # Parse command string into proper arguments
+        # Use posix=False on Windows, posix=True on Unix-like systems
+        command = shlex.split(tool_call_template.command_name, posix=(os.name != 'nt'))
+        
+        # Add formatted arguments
+        if tool_args:
+            command.extend(self._format_arguments(tool_args))
+        
+        self._log_info(f"Executing CLI tool '{tool_name}': {' '.join(command)}")
+        
+        try:
+            env = self._prepare_environment(tool_call_template)
+            
+            stdout, stderr, return_code = await self._execute_command(
+                command,
+                env,
+                timeout=60.0,  # Longer timeout for tool execution
+                working_dir=tool_call_template.working_dir
+            )
+            
+            # Get output based on exit code
+            if return_code == 0:
+                output = stdout
+                self._log_info(f"CLI tool '{tool_name}' executed successfully (exit code 0)")
+            else:
+                output = stderr
+                self._log_info(f"CLI tool '{tool_name}' exited with code {return_code}, returning stderr")
+            
+            # Try to parse output as JSON, fall back to raw string
+            if output.strip():
+                try:
+                    result = json.loads(output)
+                    self._log_info(f"Returning JSON output from CLI tool '{tool_name}'")
+                    return result
+                except json.JSONDecodeError:
+                    # Return raw string output
+                    self._log_info(f"Returning text output from CLI tool '{tool_name}'")
+                    return output.strip()
+            else:
+                self._log_info(f"CLI tool '{tool_name}' produced no output")
+                return ""
+            
+        except Exception as e:
+            self._log_error(f"Error executing CLI tool '{tool_name}': {e}")
+            raise
+
+    async def call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> AsyncGenerator[Any, None]:
+        """Streaming calls are not supported for CLI protocol."""
+        raise NotImplementedError("Streaming is not supported by the CLI communication protocol.")
+    
+    async def close(self) -> None:
+        """Close the transport.
+        
+        This is a no-op for CLI transports since they don't maintain connections.
+        """
+        self._log_info("Closing CLI transport (no-op)")

utcp_cli-1.0.0/src/utcp_cli.egg-info/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: utcp-cli
+Version: 1.0.0
+Summary: Universal Tool Calling Protocol (UTCP) client library for Python
+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: pyyaml>=6.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_cli-1.0.0/src/utcp_cli.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+pyproject.toml
+src/utcp_cli/__init__.py
+src/utcp_cli/cli_call_template.py
+src/utcp_cli/cli_communication_protocol.py
+src/utcp_cli.egg-info/PKG-INFO
+src/utcp_cli.egg-info/SOURCES.txt
+src/utcp_cli.egg-info/dependency_links.txt
+src/utcp_cli.egg-info/entry_points.txt
+src/utcp_cli.egg-info/requires.txt
+src/utcp_cli.egg-info/top_level.txt
+tests/test_cli_communication_protocol.py

utcp_cli-1.0.0/src/utcp_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

utcp_cli-1.0.0/src/utcp_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[utcp.plugins]
+cli = utcp_cli:register

utcp_cli-1.0.0/src/utcp_cli.egg-info/requires.txt

@@ -0,0 +1,11 @@
+pydantic>=2.0
+pyyaml>=6.0
+utcp>=1.0
+
+[dev]
+build
+pytest
+pytest-asyncio
+pytest-cov
+coverage
+twine

utcp_cli-1.0.0/src/utcp_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+utcp_cli

utcp_cli-1.0.0/tests/test_cli_communication_protocol.py

@@ -0,0 +1,591 @@
+"""
+Tests for the CLI transport interface.
+"""
+import asyncio
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Dict, List
+
+import pytest
+import pytest_asyncio
+
+from utcp_cli.cli_communication_protocol import CliCommunicationProtocol
+from utcp_cli.cli_call_template import CliCallTemplate
+
+
+@pytest_asyncio.fixture
+async def transport() -> CliCommunicationProtocol:
+    """Provides a clean CliCommunicationProtocol instance."""
+    t = CliCommunicationProtocol()
+    yield t
+    # Optional cleanup if close() exists
+    if hasattr(t, "close") and asyncio.iscoroutinefunction(getattr(t, "close")):
+        await t.close()
+
+
+@pytest_asyncio.fixture
+def mock_cli_script():
+    """Create a mock CLI script that can be executed for testing."""
+    script_content = '''#!/usr/bin/env python3
+import sys
+import json
+import os
+
+def main():
+    # Check for tool discovery mode (no arguments)
+    if len(sys.argv) == 1:
+        # Return UTCP manual
+        tools_data = {
+            "version": "1.0.0",
+            "name": "Mock CLI Tools",
+            "description": "Mock CLI tools for testing",
+            "tools": [
+                {
+                    "name": "echo",
+                    "description": "Echo back the input",
+                    "inputs": {
+                        "properties": {
+                            "message": {"type": "string"}
+                        },
+                        "required": ["message"]
+                    },
+                    "outputs": {
+                        "properties": {
+                            "result": {"type": "string"}
+                        }
+                    },
+                    "tags": ["utility"],
+                    "tool_provider": {
+                        "provider_type": "cli",
+                        "name": "mock_cli_provider",
+                        "command_name": sys.argv[0]
+                    }
+                },
+                {
+                    "name": "math",
+                    "description": "Perform math operations",
+                    "inputs": {
+                        "properties": {
+                            "operation": {"type": "string", "enum": ["add", "subtract"]},
+                            "a": {"type": "number"},
+                            "b": {"type": "number"}
+                        },
+                        "required": ["operation", "a", "b"]
+                    },
+                    "outputs": {
+                        "properties": {
+                            "result": {"type": "number"}
+                        }
+                    },
+                    "tags": ["math"],
+                    "tool_provider": {
+                        "provider_type": "cli",
+                        "name": "mock_cli_provider",
+                        "command_name": sys.argv[0]
+                    }
+                }
+            ]
+        }
+        print(json.dumps(tools_data))
+        return
+    
+    # Check for environment variables
+    if "--check-env" in sys.argv:
+        env_info = {}
+        # Check for specific test environment variables
+        test_vars = ['MY_API_KEY', 'TEST_VAR', 'CUSTOM_CONFIG']
+        for var in test_vars:
+            if var in os.environ:
+                env_info[var] = os.environ[var]
+        print(json.dumps(env_info))
+        return
+    
+    # Handle tool execution
+    args = sys.argv[1:]
+    
+    # Parse arguments
+    parsed_args = {}
+    i = 0
+    while i < len(args):
+        if args[i].startswith('--'):
+            key = args[i][2:]
+            if i + 1 < len(args) and not args[i + 1].startswith('--'):
+                value = args[i + 1]
+                # Try to parse as number
+                try:
+                    if '.' in value:
+                        value = float(value)
+                    else:
+                        value = int(value)
+                except ValueError:
+                    pass  # Keep as string
+                parsed_args[key] = value
+                i += 2
+            else:
+                parsed_args[key] = True
+                i += 1
+        else:
+            i += 1
+    
+    # Simple tool implementations
+    if "message" in parsed_args:
+        # Echo tool
+        result = {"result": f"Echo: {parsed_args['message']}"}
+        print(json.dumps(result))
+    elif "operation" in parsed_args and "a" in parsed_args and "b" in parsed_args:
+        # Math tool
+        a = parsed_args["a"]
+        b = parsed_args["b"]
+        op = parsed_args["operation"]
+        
+        if op == "add":
+            result = {"result": a + b}
+        elif op == "subtract":
+            result = {"result": a - b}
+        else:
+            print(f"Unknown operation: {op}", file=sys.stderr)
+            sys.exit(1)
+        
+        print(json.dumps(result))
+    elif "error" in parsed_args:
+        # Error simulation
+        print(f"Simulated error: {parsed_args['error']}", file=sys.stderr)
+        sys.exit(1)
+    else:
+        print("Unknown command or missing arguments", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()
+'''
+    
+    # Create temporary script file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+        f.write(script_content)
+        script_path = f.name
+    
+    # Make it executable on Unix systems
+    try:
+        os.chmod(script_path, 0o755)
+    except Exception:
+        pass  # Windows doesn't use executable permissions
+    
+    yield script_path
+    
+    # Cleanup
+    try:
+        os.unlink(script_path)
+    except Exception:
+        pass
+
+
+@pytest_asyncio.fixture
+def python_executable():
+    """Get the Python executable path."""
+    return sys.executable
+
+
+@pytest.mark.asyncio
+async def test_register_provider_discovers_tools(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test that registering a provider discovers tools from command output."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+    )
+    
+    result = await transport.register_manual(None, call_template)
+    
+    assert result is not None and result.manual is not None
+    tools = result.manual.tools
+    assert len(tools) == 2
+    assert tools[0].name == "echo"
+    assert tools[0].description == "Echo back the input"
+    assert tools[0].tags == ["utility"]
+    
+    assert tools[1].name == "math"
+    assert tools[1].description == "Perform math operations"
+    assert tools[1].tags == ["math"]
+
+
+@pytest.mark.asyncio
+async def test_register_provider_missing_command_name(transport: CliCommunicationProtocol):
+    """Test that registering a provider with empty command_name raises an error."""
+    call_template = CliCallTemplate(
+        command_name=""  # Empty string instead of missing field
+    )
+    
+    with pytest.raises(ValueError):
+        await transport.register_manual(None, call_template)
+
+
+@pytest.mark.asyncio
+async def test_register_provider_wrong_type(transport: CliCommunicationProtocol):
+    """Test that registering a non-CLI call template raises an error."""
+    class DummyTemplate:
+        type = "http"
+        command_name = "echo"
+    
+    with pytest.raises(ValueError):
+        await transport.register_manual(None, DummyTemplate())
+
+
+@pytest.mark.asyncio
+async def test_call_tool_json_output(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test calling a tool that returns JSON output."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+    )
+    
+    result = await transport.call_tool(None, "echo", {"message": "Hello World"}, call_template)
+    
+    assert isinstance(result, dict)
+    assert result["result"] == "Echo: Hello World"
+
+
+@pytest.mark.asyncio
+async def test_call_tool_math_operation(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test calling a math tool with numeric arguments."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+    )
+    
+    result = await transport.call_tool(None, "math", {"operation": "add", "a": 5, "b": 3}, call_template)
+    
+    assert isinstance(result, dict)
+    assert result["result"] == 8
+
+
+@pytest.mark.asyncio
+async def test_call_tool_error_handling(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test calling a tool that exits with an error returns stderr."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+    )
+    
+    # This should trigger an error in the mock script
+    result = await transport.call_tool(None, "error_tool", {"error": "test error"}, call_template)
+    
+    # Should return stderr content since exit code != 0
+    assert isinstance(result, str)
+    assert "Simulated error: test error" in result
+
+
+@pytest.mark.asyncio
+async def test_call_tool_missing_command_name(transport: CliCommunicationProtocol):
+    """Test calling a tool with empty command_name raises an error."""
+    call_template = CliCallTemplate(
+        command_name=""  # Empty string instead of missing field
+    )
+    
+    with pytest.raises(ValueError):
+        await transport.call_tool(None, "some_tool", {}, call_template)
+
+
+@pytest.mark.asyncio
+async def test_call_tool_wrong_provider_type(transport: CliCommunicationProtocol):
+    """Test calling a tool with wrong provider type."""
+    class DummyTemplate:
+        type = "http"
+        command_name = "echo"
+    
+    with pytest.raises(ValueError):
+        await transport.call_tool(None, "some_tool", {}, DummyTemplate())
+
+
+@pytest.mark.asyncio
+async def test_environment_variables(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test that custom environment variables are properly set."""
+    env_vars = {
+        "MY_API_KEY": "test-api-key-123",
+        "TEST_VAR": "test-value",
+        "CUSTOM_CONFIG": "config-data"
+    }
+    
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}",
+        env_vars=env_vars
+    )
+    
+    # Call the env check endpoint
+    result = await transport.call_tool(None, "check_env", {"check-env": True}, call_template)
+    
+    assert isinstance(result, dict)
+    assert result["MY_API_KEY"] == "test-api-key-123"
+    assert result["TEST_VAR"] == "test-value"
+    assert result["CUSTOM_CONFIG"] == "config-data"
+
+
+@pytest.mark.asyncio
+async def test_no_environment_variables(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test that no environment variables are set when env_vars is None."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+        # env_vars=None by default
+    )
+    
+    # Call the env check endpoint
+    result = await transport.call_tool(None, "check_env", {"check-env": True}, call_template)
+    
+    assert isinstance(result, dict)
+    # Should be empty since no custom env vars were set
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_working_directory(transport: CliCommunicationProtocol, mock_cli_script, python_executable, tmp_path):
+    """Test that working directory is properly set during command execution."""
+    # Create a test file in a specific directory
+    test_dir = tmp_path / "test_working_dir"
+    test_dir.mkdir()
+    test_file = test_dir / "current_dir.txt"
+    
+    # Create a mock script that writes the current working directory to a file
+    script_content = '''
+import os
+import sys
+
+if "--write-cwd" in sys.argv:
+    with open("current_dir.txt", "w") as f:
+        f.write(os.getcwd())
+    print("{\'status\': \'written\'}".replace("\'", '"'))
+else:
+    print("{\'error\': \'unknown command\'}".replace("\'", '"'))
+'''
+    
+    working_dir_script = tmp_path / "working_dir_script.py"
+    working_dir_script.write_text(script_content)
+    
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {working_dir_script}",
+        working_dir=str(test_dir)
+    )
+    
+    # Call the tool which should write the current directory to a file
+    result = await transport.call_tool(None, "write_cwd", {"write-cwd": True}, call_template)
+    
+    # Verify the result
+    assert isinstance(result, dict)
+    assert result["status"] == "written"
+    
+    # Verify the file was created in the working directory and contains the correct path
+    assert test_file.exists()
+    written_cwd = test_file.read_text().strip()
+    
+    # The written current working directory should be the test directory
+    assert os.path.abspath(written_cwd) == os.path.abspath(str(test_dir))
+
+
+@pytest.mark.asyncio
+async def test_no_working_directory(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test that commands work normally when no working directory is specified."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+        # working_dir=None by default
+    )
+    
+    # This should work normally - calling the echo tool
+    result = await transport.call_tool(None, "echo", {"message": "test"}, call_template)
+    
+    assert isinstance(result, dict)
+    assert result["result"] == "Echo: test"
+
+
+@pytest.mark.asyncio
+async def test_env_vars_and_working_dir_combined(transport: CliCommunicationProtocol, python_executable, tmp_path):
+    """Test that both environment variables and working directory work together."""
+    # Create a test directory
+    test_dir = tmp_path / "combined_test_dir"
+    test_dir.mkdir()
+    
+    # Create a script that checks both environment variable and writes current directory
+    script_content = '''
+import os
+import sys
+import json
+
+if "--combined-test" in sys.argv:
+    result = {
+        "current_dir": os.getcwd(),
+        "test_env_var": os.environ.get("TEST_COMBINED_VAR", "not_found"),
+        "status": "success"
+    }
+    print(json.dumps(result))
+else:
+    print(json.dumps({"error": "unknown command"}))
+'''
+    
+    combined_script = tmp_path / "combined_test_script.py"
+    combined_script.write_text(script_content)
+    
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {combined_script}",
+        env_vars={"TEST_COMBINED_VAR": "test_value_123"},
+        working_dir=str(test_dir)
+    )
+    
+    # Call the tool
+    result = await transport.call_tool(None, "combined_test", {"combined-test": True}, call_template)
+    
+    # Verify both environment variable and working directory are set correctly
+    assert isinstance(result, dict)
+    assert result["status"] == "success"
+    assert result["test_env_var"] == "test_value_123"
+    assert os.path.abspath(result["current_dir"]) == os.path.abspath(str(test_dir))
+
+
+@pytest.mark.asyncio
+async def test_argument_formatting():
+    """Test that arguments are properly formatted for command line."""
+    transport = CliCommunicationProtocol()
+    
+    # Test various argument types
+    args = {
+        "string_arg": "hello",
+        "number_arg": 42,
+        "float_arg": 3.14,
+        "bool_true": True,
+        "bool_false": False,
+        "list_arg": ["item1", "item2"]
+    }
+    
+    formatted = transport._format_arguments(args)
+    
+    # Check that arguments are properly formatted
+    assert "--string_arg" in formatted
+    assert "hello" in formatted
+    assert "--number_arg" in formatted
+    assert "42" in formatted
+    assert "--float_arg" in formatted
+    assert "3.14" in formatted
+    assert "--bool_true" in formatted
+    assert "--bool_false" not in formatted  # False booleans should not appear
+    assert "--list_arg" in formatted
+    assert "item1" in formatted
+    assert "item2" in formatted
+
+
+@pytest.mark.asyncio
+async def test_json_extraction_from_output():
+    """Test extracting JSON from various output formats."""
+    transport = CliCommunicationProtocol()
+    
+    # Test complete JSON output
+    output1 = '{"tools": [{"name": "test", "description": "Test tool", "tool_provider": {"provider_type": "cli", "name": "test_provider", "command_name": "test"}}]}'
+    manual1 = transport._extract_utcp_manual_from_output(output1, "test_provider")
+    assert manual1 is not None
+    assert len(manual1.tools) == 1
+    assert manual1.tools[0].name == "test"
+    
+    # Test JSON within text output
+    output2 = '''
+    Starting CLI tool...
+    {"tools": [{"name": "embedded", "description": "Embedded tool", "tool_provider": {"provider_type": "cli", "name": "test_provider", "command_name": "test"}}]}
+    Process completed.
+    '''
+    manual2 = transport._extract_utcp_manual_from_output(output2, "test_provider")
+    assert manual2 is not None
+    assert len(manual2.tools) == 1
+    assert manual2.tools[0].name == "embedded"
+    
+    # Test single tool definition
+    output3 = '{"name": "single", "description": "Single tool", "tool_provider": {"provider_type": "cli", "name": "test_provider", "command_name": "test"}}'
+    manual3 = transport._extract_utcp_manual_from_output(output3, "test_provider")
+    assert manual3 is not None
+    assert len(manual3.tools) == 1
+    assert manual3.tools[0].name == "single"
+    
+    # Test no valid JSON
+    output4 = "No JSON here, just plain text"
+    manual4 = transport._extract_utcp_manual_from_output(output4, "test_provider")
+    assert manual4 is None
+
+
+@pytest.mark.asyncio
+async def test_deregister_provider(transport: CliCommunicationProtocol, mock_cli_script, python_executable):
+    """Test deregistering a CLI provider."""
+    call_template = CliCallTemplate(
+        command_name=f"{python_executable} {mock_cli_script}"
+    )
+    
+    # Register and then deregister (should not raise any errors)
+    await transport.register_manual(None, call_template)
+    await transport.deregister_manual(None, call_template)
+
+
+@pytest.mark.asyncio
+async def test_close_transport(transport: CliCommunicationProtocol):
+    """Test closing the transport."""
+    # Should not raise any errors (only if close() is implemented)
+    if hasattr(transport, "close") and asyncio.iscoroutinefunction(getattr(transport, "close")):
+        await transport.close()
+
+
+@pytest.mark.asyncio
+async def test_command_execution_timeout(python_executable, tmp_path):
+    """Test that command execution respects timeout."""
+    transport = CliCommunicationProtocol()
+    
+    # Create a Python script that sleeps for a long time
+    sleep_script_content = '''
+import time
+import sys
+
+if "--sleep" in sys.argv:
+    time.sleep(10)  # Sleep for 10 seconds
+    print("This should not be printed due to timeout")
+else:
+    print("Unknown command")
+    sys.exit(1)
+'''
+    
+    sleep_script = tmp_path / "sleep_script.py"
+    sleep_script.write_text(sleep_script_content)
+    
+    try:
+        command = [python_executable, str(sleep_script), "--sleep"]
+        env = os.environ.copy()
+        
+        with pytest.raises(asyncio.TimeoutError):  # Should raise TimeoutError
+            await transport._execute_command(command, env, timeout=1.0, working_dir=str(tmp_path))
+            
+    except Exception as e:
+        # If the specific timeout doesn't work, just ensure some exception is raised
+        # and it's related to timing out
+        assert "timeout" in str(e).lower() or isinstance(e, asyncio.TimeoutError)
+
+
+@pytest.mark.asyncio
+async def test_mixed_output_formats(transport: CliCommunicationProtocol, python_executable):
+    """Test handling of mixed output formats (text and JSON)."""
+    # Create a simple script that outputs mixed content
+    script_content = '''
+import sys
+print("Starting tool execution...")
+print('{"result": "success", "value": 42}')
+print("Tool execution completed.")
+'''
+    
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+        f.write(script_content)
+        script_path = f.name
+    
+    try:
+        call_template = CliCallTemplate(
+            command_name=f"{python_executable} {script_path}"
+        )
+        
+        result = await transport.call_tool(None, "mixed_tool", {}, call_template)
+        
+        # Should return the JSON part since command succeeds (exit code 0)
+        # But the output contains both text and JSON
+        assert isinstance(result, str)  # Will be text since full output isn't valid JSON
+        assert "Starting tool execution..." in result
+        assert '{"result": "success", "value": 42}' in result
+        
+    finally:
+        try:
+            os.unlink(script_path)
+        except Exception:
+            pass