clap-agents 0.1.1__py3-none-any.whl

clap/tool_pattern/tool.py

@@ -0,0 +1,229 @@
+
+import json
+import inspect
+import functools # Import functools
+from typing import Callable, Any
+import anyio
+import jsonschema
+
+
+def get_fn_signature(fn: Callable) -> dict:
+    """
+    Generates the signature (schema) for a given function in JSON Schema format.
+
+    Args:
+        fn (Callable): The function whose signature needs to be extracted.
+
+    Returns:
+        dict: A dictionary representing the function's schema.
+    """
+    
+    type_mapping = {
+        "int": "integer",
+        "str": "string",
+        "bool": "boolean",
+        "float": "number",
+        "list": "array", # Basic support for lists
+        "dict": "object", # Basic support for dicts
+    }
+
+    parameters = {"type": "object", "properties": {}, "required": []}
+    sig = inspect.signature(fn)
+
+    for name, type_hint in fn.__annotations__.items():
+        if name == "return":
+            continue
+        param_type_name = getattr(type_hint, "__name__", str(type_hint))
+        schema_type = type_mapping.get(param_type_name, "string")
+
+        parameters["properties"][name] = {"type": schema_type}
+        
+        if sig.parameters[name].default is inspect.Parameter.empty:
+            parameters["required"].append(name)
+
+    if not parameters["required"]:
+        del parameters["required"]
+
+    fn_schema: dict = {
+        "type": "function",
+        "function": {
+            "name": fn.__name__,
+            "description": fn.__doc__,
+            "parameters": parameters,
+        }
+    }
+
+    return fn_schema
+
+
+def validate_arguments(tool_call_args: dict, tool_schema: dict) -> dict:
+    """
+    Validates and converts arguments in the input dictionary based on the tool's JSON schema.
+    NOTE: This is a simplified validator. For production, use a robust JSON Schema validator.
+
+    Args:
+        tool_call_args (dict): The arguments provided for the tool call (usually strings from LLM).
+        tool_schema (dict): The JSON schema for the tool's parameters.
+
+    Returns:
+        dict: The arguments dictionary with values converted to the correct types if possible.
+
+    Raises:
+        ValueError: If conversion fails for a required argument.
+    """
+    properties = tool_schema.get("function", {}).get("parameters", {}).get("properties", {})
+    validated_args = {}
+
+    type_mapping = {
+        "integer": int,
+        "string": str,
+        "boolean": bool,
+        "number": float,
+        "array": list, 
+        "object": dict 
+    }
+
+    for arg_name, arg_value in tool_call_args.items():
+        prop_schema = properties.get(arg_name)
+        if not prop_schema:
+            # Argument not defined in schema, potentially skip or warn
+            print(f"Warning: Argument '{arg_name}' not found in tool schema.")
+            validated_args[arg_name] = arg_value # Pass through unknown args for now
+            continue
+
+        expected_type_name = prop_schema.get("type")
+        expected_type = type_mapping.get(expected_type_name)
+
+        if expected_type:
+            try:
+                if not isinstance(arg_value, expected_type):
+                    if expected_type is bool and isinstance(arg_value, str):
+                         if arg_value.lower() in ['true', '1', 'yes']:
+                             validated_args[arg_name] = True
+                         elif arg_value.lower() in ['false', '0', 'no']:
+                              validated_args[arg_name] = False
+                         else:
+                              raise ValueError(f"Cannot convert string '{arg_value}' to boolean.")
+                    # Basic handling for array/object assuming JSON string
+                    elif expected_type in [list, dict] and isinstance(arg_value, str):
+                        try:
+                            validated_args[arg_name] = json.loads(arg_value)
+                            if not isinstance(validated_args[arg_name], expected_type):
+                                raise ValueError(f"Decoded JSON for '{arg_name}' is not the expected type '{expected_type_name}'.")
+                        except json.JSONDecodeError:
+                             raise ValueError(f"Argument '{arg_name}' with value '{arg_value}' is not valid JSON for type '{expected_type_name}'.")
+                    else:
+                        validated_args[arg_name] = expected_type(arg_value)
+                else:
+                    # Type is already correct
+                    validated_args[arg_name] = arg_value
+            except (ValueError, TypeError) as e:
+                raise ValueError(f"Error converting argument '{arg_name}' with value '{arg_value}' to type '{expected_type_name}': {e}")
+        else:
+             # Unknown type in schema, pass through
+            validated_args[arg_name] = arg_value
+
+    # Check for missing required arguments (optional, depends on strictness)
+    # required_args = tool_schema.get("function", {}).get("parameters", {}).get("required", [])
+    # for req_arg in required_args:
+    #     if req_arg not in validated_args:
+    #         raise ValueError(f"Missing required argument: '{req_arg}'")
+
+
+    return validated_args
+
+class Tool:
+    """
+    A class representing a tool that wraps a callable and its schema.
+    Handles both synchronous and asynchronous functions.
+
+    Attributes:
+        name (str): The name of the tool (function).
+        fn (Callable): The function that the tool represents (can be sync or async).
+        fn_schema (dict): Dictionary representing the function's schema in JSON Schema format.
+        fn_signature (str): JSON string representation of the function's signature (legacy, kept for potential compatibility).
+    """
+
+    def __init__(self, name: str, fn: Callable, fn_schema: dict):
+        self.name = name
+        self.fn = fn
+        self.fn_schema = fn_schema
+        self.fn_signature = json.dumps(fn_schema)
+
+    def __str__(self):
+        return json.dumps(self.fn_schema, indent=2)
+
+    async def run(self, **kwargs) -> Any:
+        """
+        Executes the tool (function) with provided arguments asynchronously.
+        Validates arguments against the tool's JSON schema before execution.
+        Handles both sync and async tool functions appropriately.
+
+        Args:
+            **kwargs: Keyword arguments provided for the tool call.
+
+        Returns:
+            The result of the function call, or an error string.
+        """
+        parameter_schema = self.fn_schema.get("function", {}).get("parameters", {})
+
+        # --- Use jsonschema for validation ---
+        try:
+            # Validate the incoming arguments against the parameter schema
+            # Note: jsonschema validates, it doesn't coerce types like the old function
+            jsonschema.validate(instance=kwargs, schema=parameter_schema)
+            # If validation passes, kwargs are structurally correct according to schema
+
+            # Type Coercion/Conversion might still be needed depending on self.fn
+            # If self.fn uses Pydantic models or type hints, it might handle coercion.
+            # Or, you could apply specific conversions based on schema after validation if needed.
+            # For now, assume self.fn or Pydantic handles coercion post-validation.
+            validated_kwargs = kwargs # Use original kwargs after validation passes
+
+        except jsonschema.ValidationError as e:
+            print(f"Argument validation failed for tool {self.name}: {e.message}")
+            return f"Error: Invalid arguments provided - {e.message}"
+        except Exception as e: # Catch other potential validation setup errors
+             print(f"An unexpected error occurred during argument validation for tool {self.name}: {e}")
+             return f"Error: Argument validation failed."
+        # --- End jsonschema validation ---
+
+        # --- Execute the function (sync or async) ---
+        try:
+            if inspect.iscoroutinefunction(self.fn):
+                return await self.fn(**validated_kwargs)
+            else:
+                func_with_args = functools.partial(self.fn, **validated_kwargs)
+                return await anyio.to_thread.run_sync(func_with_args)
+        except Exception as e:
+             # Catch errors during the actual tool execution
+             print(f"Error executing tool {self.name}: {e}")
+             # Consider logging traceback here
+             return f"Error executing tool: {e}"
+
+
+
+def tool(fn: Callable):
+    """
+    A decorator that wraps a function (sync or async) into a Tool object,
+    including its JSON schema.
+
+    Args:
+        fn (Callable): The function to be wrapped.
+
+    Returns:
+        Tool: A Tool object containing the function, its name, and its schema.
+    """
+
+    def wrapper():
+        fn_schema = get_fn_signature(fn)
+        if not fn_schema or 'function' not in fn_schema or 'name' not in fn_schema['function']:
+             raise ValueError(f"Could not generate valid schema for function {fn.__name__}")
+        return Tool(
+            name=fn_schema["function"]["name"],
+            fn=fn,
+            fn_schema=fn_schema
+        )
+
+    return wrapper()
+

clap/tool_pattern/tool_agent.py

@@ -0,0 +1,241 @@
+# --- START OF ASYNC MODIFIED tool_agent.py (Init Fix) ---
+
+import json
+import asyncio
+from typing import List, Dict, Any, Optional
+
+from colorama import Fore
+from dotenv import load_dotenv
+from groq import AsyncGroq
+
+from clap.tool_pattern.tool import Tool
+from clap.mcp_client.client import MCPClientManager
+from clap.utils.completions import build_prompt_structure
+from clap.utils.completions import ChatHistory
+from clap.utils.completions import completions_create
+from clap.utils.completions import update_chat_history
+from mcp import types as mcp_types
+
+load_dotenv()
+
+NATIVE_TOOL_SYSTEM_PROMPT = """
+You are a helpful assistant. Use the available tools (local or remote) if necessary to answer the user's request.
+If you use a tool, you will be given the results, and then you should provide the final response to the user based on those results.
+If no tool is needed, answer directly.
+"""
+
+class ToolAgent:
+    """
+    A simple agent that uses native tool calling asynchronously to answer user queries.
+    Supports both local Python tools and remote MCP tools via an MCPClientManager.
+    It makes one attempt to call tools if needed, processes the results,
+    and then generates a final response.
+    """
+
+    def __init__(
+        self,
+        tools: Optional[Tool | List[Tool]] = None,
+        mcp_manager: Optional[MCPClientManager] = None,
+        mcp_server_names: Optional[List[str]] = None,
+        model: str = "llama-3.3-70b-versatile",
+        system_prompt: str = NATIVE_TOOL_SYSTEM_PROMPT,
+    ) -> None:
+        self.client = AsyncGroq()
+        self.model = model
+        self.system_prompt = system_prompt
+
+        if tools is None:
+            self.local_tools = []
+        elif isinstance(tools, list):
+            self.local_tools = tools
+        else:
+            self.local_tools = [tools]
+
+        self.local_tools_dict = {tool.name: tool for tool in self.local_tools}
+        self.local_tool_schemas = [tool.fn_schema for tool in self.local_tools]
+
+        self.mcp_manager = mcp_manager
+        self.mcp_server_names = mcp_server_names or []
+        self.remote_tools_dict: Dict[str, mcp_types.Tool] = {}
+        self.remote_tool_server_map: Dict[str, str] = {}
+
+
+    async def _get_combined_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Fetches remote tools and combines their schemas with local ones."""
+        all_schemas = list(self.local_tool_schemas) # Start with local schemas
+        self.remote_tools_dict = {} # Reset remote tools for this run
+        self.remote_tool_server_map = {}
+
+        if self.mcp_manager and self.mcp_server_names:
+            fetch_tasks = [
+                self.mcp_manager.list_remote_tools(name)
+                for name in self.mcp_server_names
+            ]
+            results = await asyncio.gather(*fetch_tasks, return_exceptions=True)
+
+            for server_name, result in zip(self.mcp_server_names, results):
+                if isinstance(result, Exception):
+                    print(f"{Fore.RED}Error listing tools from MCP server '{server_name}': {result}{Fore.RESET}")
+                    continue
+
+                if isinstance(result, list):
+                    for tool in result:
+                        if isinstance(tool, mcp_types.Tool):
+                           if tool.name in self.local_tools_dict:
+                               print(f"{Fore.YELLOW}Warning: Remote tool '{tool.name}' from server '{server_name}' conflicts with local tool. Local tool will be used.{Fore.RESET}")
+                               continue
+                           if tool.name in self.remote_tools_dict:
+                               print(f"{Fore.YELLOW}Warning: Remote tool '{tool.name}' from server '{server_name}' conflicts with another remote tool from server '{self.remote_tool_server_map[tool.name]}'. Skipping duplicate.{Fore.RESET}")
+                               continue
+
+                           self.remote_tools_dict[tool.name] = tool
+                           self.remote_tool_server_map[tool.name] = server_name
+
+                           translated_schema = {
+                               "type": "function",
+                               "function": {
+                                   "name": tool.name,
+                                   "description": tool.description or "",
+                                   "parameters": tool.inputSchema
+                               }
+                           }
+                           all_schemas.append(translated_schema)
+                        else:
+                             print(f"{Fore.YELLOW}Warning: Received non-Tool object from {server_name}: {type(tool)}{Fore.RESET}")
+
+        print(f"{Fore.BLUE}Total tools available to LLM: {len(all_schemas)}{Fore.RESET}")
+        return all_schemas
+
+    async def process_tool_calls(self, tool_calls: List[Any]) -> List[Dict[str, Any]]:
+        """
+        Processes tool calls requested by the LLM asynchronously, dispatches execution
+        to local or remote tools, and collects results formatted as 'tool' role messages.
+        """
+        observation_messages = []
+        if not isinstance(tool_calls, list):
+             print(f"{Fore.RED}Error: Expected a list of tool_calls, got {type(tool_calls)}{Fore.RESET}")
+             return observation_messages
+
+        tasks = [self._execute_single_tool_call(tc) for tc in tool_calls]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for result in results:
+             if isinstance(result, dict):
+                  if len(result) == 1:
+                      tool_call_id, result_str = list(result.items())[0]
+                      observation_messages.append(
+                           build_prompt_structure(role="tool", content=result_str, tool_call_id=tool_call_id)
+                      )
+                  else:
+                       print(f"{Fore.RED}Error: Unexpected result format from tool execution: {result}{Fore.RESET}")
+             elif isinstance(result, Exception):
+                  print(f"{Fore.RED}Error during concurrent tool execution: {result}{Fore.RESET}")
+             else:
+                  print(f"{Fore.RED}Error: Unexpected item in tool execution results: {result}{Fore.RESET}")
+
+        return observation_messages
+
+    async def _execute_single_tool_call(self, tool_call: Any) -> Dict[str, Any]:
+        """Helper to execute a single tool call (local or remote)."""
+        tool_call_id = getattr(tool_call, 'id', 'error_no_id')
+        function_call = getattr(tool_call, 'function', None)
+        tool_name = getattr(function_call, 'name', 'error_unknown_name')
+        result_str = f"Error: Processing failed for tool call '{tool_name}' (id: {tool_call_id})."
+
+        try:
+            if not function_call:
+                 raise ValueError("Invalid tool_call object structure: missing 'function'.")
+
+            arguments_str = getattr(function_call, 'arguments', '{}')
+            arguments = json.loads(arguments_str)
+
+            if tool_name in self.local_tools_dict:
+                tool = self.local_tools_dict[tool_name]
+                print(f"{Fore.GREEN}\nExecuting Local Tool: {tool_name}{Fore.RESET}")
+                print(f"Tool call ID: {tool_call_id}")
+                print(f"Arguments: {arguments}")
+                result = await tool.run(**arguments)
+            elif tool_name in self.remote_tool_server_map and self.mcp_manager:
+                server_name = self.remote_tool_server_map[tool_name]
+                print(f"{Fore.CYAN}\nExecuting Remote MCP Tool: {tool_name} on {server_name}{Fore.RESET}")
+                print(f"Tool call ID: {tool_call_id}")
+                print(f"Arguments: {arguments}")
+                result = await self.mcp_manager.call_remote_tool(server_name, tool_name, arguments)
+            else:
+                print(f"{Fore.RED}Error: Tool '{tool_name}' not found locally or in known remote servers.{Fore.RESET}")
+                result_str = f"Error: Tool '{tool_name}' is not available."
+                return {tool_call_id: result_str}
+
+            if not isinstance(result, (str, int, float, bool, list, dict, type(None))):
+                result_str = str(result)
+            else:
+                try: result_str = json.dumps(result)
+                except TypeError: result_str = str(result)
+            print(f"{Fore.GREEN}Tool '{tool_name}' result: {result_str[:100]}...{Fore.RESET}")
+
+        except json.JSONDecodeError:
+            print(f"{Fore.RED}Error: Could not decode arguments for tool {tool_name}: {arguments_str}{Fore.RESET}")
+            result_str = f"Error: Invalid arguments JSON provided for {tool_name}"
+        except Exception as e:
+             print(f"{Fore.RED}Error processing or running tool {tool_name} (id: {tool_call_id}): {e}{Fore.RESET}")
+             result_str = f"Error executing tool {tool_name}: {e}"
+
+        return {tool_call_id: result_str}
+
+    async def run(
+        self,
+        user_msg: str,
+    ) -> str:
+        """
+        Handles the asynchronous interaction: user message -> LLM (tool decision) ->
+        execute tools (local or remote) -> LLM (final response).
+        """
+        combined_tool_schemas = await self._get_combined_tool_schemas()
+
+        initial_user_message = build_prompt_structure(role="user", content=user_msg)
+        chat_history = ChatHistory(
+            [
+                build_prompt_structure(role="system", content=self.system_prompt),
+                initial_user_message,
+            ]
+        )
+
+        print(f"{Fore.CYAN}\n--- Calling LLM for Tool Decision ---{Fore.RESET}")
+        assistant_message_1 = await completions_create(
+            self.client,
+            messages=list(chat_history),
+            model=self.model,
+            tools=combined_tool_schemas,
+            tool_choice="auto"
+        )
+
+        update_chat_history(chat_history, assistant_message_1)
+
+        final_response = "Agent encountered an issue."
+
+        if hasattr(assistant_message_1, 'tool_calls') and assistant_message_1.tool_calls:
+            print(f"{Fore.YELLOW}\nAssistant requests tool calls:{Fore.RESET}")
+            observation_messages = await self.process_tool_calls(assistant_message_1.tool_calls)
+            print(f"{Fore.BLUE}\nObservations prepared for LLM: {observation_messages}{Fore.RESET}")
+
+            for obs_msg in observation_messages:
+                update_chat_history(chat_history, obs_msg)
+
+            print(f"{Fore.CYAN}\n--- Calling LLM for Final Response ---{Fore.RESET}")
+            assistant_message_2 = await completions_create(
+                self.client,
+                messages=list(chat_history),
+                model=self.model,
+            )
+            final_response = str(assistant_message_2.content) if assistant_message_2.content else "Agent did not provide a final response after using tools."
+
+        elif assistant_message_1.content is not None:
+            print(f"{Fore.CYAN}\nAssistant provided direct response (no tools used):{Fore.RESET}")
+            final_response = assistant_message_1.content
+        else:
+            print(f"{Fore.RED}Error: Assistant message has neither content nor tool calls.{Fore.RESET}")
+            final_response = "Error: Received an unexpected empty response from the assistant."
+
+        print(f"{Fore.GREEN}\nFinal Response:\n{final_response}{Fore.RESET}")
+        return final_response
+

clap/tools/__init__.py

@@ -0,0 +1,13 @@
+
+from .web_search import duckduckgo_search
+from .web_crawler import scrape_url, extract_text_by_query # Removed smart_extract
+from .email_tools import send_email, fetch_recent_emails
+
+__all__ = [
+    "duckduckgo_search",
+    "scrape_url",
+    "extract_text_by_query",
+    "send_email",
+    "fetch_recent_emails",
+]
+