clap-agents 0.1.1__py3-none-any.whl

clap/__init__.py

@@ -0,0 +1,57 @@
+# --- Example content for src/clap/__init__.py ---
+
+# Import key classes/functions from submodules to make them accessible at the top level
+
+# Multi-agent pattern
+from .multiagent_pattern.agent import Agent
+from .multiagent_pattern.team import Team
+
+# ReAct pattern
+from .react_pattern.react_agent import ReactAgent
+
+# Tool pattern
+from .tool_pattern.tool import tool, Tool
+from .tool_pattern.tool_agent import ToolAgent
+
+# LLM Services (Interface and implementations)
+from .llm_services.base import LLMServiceInterface, StandardizedLLMResponse, LLMToolCall
+from .llm_services.groq_service import GroqService
+from .llm_services.google_openai_compat_service import GoogleOpenAICompatService
+
+from .mcp_client.client import MCPClientManager, SseServerConfig 
+
+
+from .tools.web_search import duckduckgo_search
+from .tools.web_crawler import scrape_url, extract_text_by_query
+from .tools.email_tools import send_email, fetch_recent_emails
+
+__all__ = [
+    # Core classes
+    "Agent",
+    "Team",
+    "ReactAgent",
+    "ToolAgent",
+    "Tool",
+    "tool", # The decorator
+
+    # LLM Services
+    "LLMServiceInterface",
+    "StandardizedLLMResponse",
+    "LLMToolCall",
+    "GroqService",
+    "GoogleOpenAICompatService",
+
+    # MCP Client
+    "MCPClientManager",
+    "SseServerConfig", # Expose config type
+
+    # Selected Tools (example)
+    "duckduckgo_search",
+    # Add others from .tools if desired as part of the core offering
+]
+
+# You might also want to define a package-level version variable here
+# (though often handled by build tools or version files)
+# __version__ = "0.1.0"
+
+# --- End of src/clap/__init__.py ---

clap/llm_services/base.py

@@ -0,0 +1,68 @@
+
+import abc
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+
+
+@dataclass
+class LLMToolCall:
+    """Represents a tool call requested by the LLM."""
+    id: str # The unique ID for this specific tool call instance
+    function_name: str
+    function_arguments_json_str: str
+
+@dataclass
+class StandardizedLLMResponse:
+    """A consistent format for LLM responses passed back to the agent."""
+    text_content: Optional[str] = None
+    tool_calls: List[LLMToolCall] = field(default_factory=list)
+
+
+class LLMServiceInterface(abc.ABC):
+    """
+    Abstract Base Class defining the interface for interacting with different LLM backends.
+    Concrete implementations (e.g., for Groq, Google GenAI) will inherit from this.
+    """
+
+    @abc.abstractmethod
+    async def get_llm_response(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: str = "auto",
+        # Optional: Add other common configuration parameters if needed later
+        # temperature: Optional[float] = None,
+        # max_tokens: Optional[int] = None,
+    ) -> StandardizedLLMResponse:
+        """
+        Sends messages to the configured LLM backend and returns a standardized response.
+
+        Args:
+            model: The specific model identifier for the backend.
+            messages: The chat history in a list of dictionaries format
+                      (e.g., [{'role': 'user', 'content': 'Hello'}]).
+                      Implementations will need to translate this if their
+                      native API uses a different format.
+            tools: A list of tool schemas available for the LLM to use,
+                   formatted according to the OpenAI/Groq standard
+                   `{"type": "function", "function": {...}}`.
+                   Implementations will need to translate this if their
+                   native API uses a different format.
+            tool_choice: How the LLM should use tools (e.g., "auto", "none").
+
+        Returns:
+            A StandardizedLLMResponse object containing the text content and/or
+            tool calls requested by the LLM.
+
+        Raises:
+            Exception: Can raise exceptions if the API call fails.
+        """
+        pass
+
+    # Optional: Add other common methods if needed, e.g., for embedding generation
+    # @abc.abstractmethod
+    # async def get_embedding(self, text: str, model: str) -> List[float]:
+    #     pass
+

clap/llm_services/google_openai_compat_service.py

@@ -0,0 +1,122 @@
+# --- START OF agentic_patterns/llm_services/google_openai_compat_service.py ---
+
+import os
+import json
+import uuid 
+from typing import Any, Dict, List, Optional
+
+# Import the OpenAI library
+try:
+    from openai import AsyncOpenAI, OpenAIError
+except ImportError:
+    raise ImportError("OpenAI SDK not found. Please install it using: pip install openai")
+
+from colorama import Fore
+
+# Import the base interface and response structures
+from .base import LLMServiceInterface, StandardizedLLMResponse, LLMToolCall
+
+# Google's OpenAI-compatible endpoint
+GOOGLE_COMPAT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+
+class GoogleOpenAICompatService(LLMServiceInterface):
+    """
+    LLM Service implementation using the OpenAI SDK configured for Google's
+    Generative Language API (Gemini models via compatibility layer).
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = GOOGLE_COMPAT_BASE_URL):
+        """
+        Initializes the service using the OpenAI client pointed at Google's endpoint.
+
+        Args:
+            api_key: Optional Google API key. If None, uses GOOGLE_API_KEY env var.
+            base_url: The base URL for the Google compatibility endpoint.
+        """
+        effective_key = api_key or os.getenv("GOOGLE_API_KEY")
+        if not effective_key:
+            raise ValueError("Google API Key not provided or found in environment variables (GOOGLE_API_KEY).")
+
+        try:
+            self.client = AsyncOpenAI(
+                api_key=effective_key,
+                base_url=base_url,
+            )
+        except Exception as e:
+            print(f"{Fore.RED}Failed to initialize OpenAI client for Google: {e}{Fore.RESET}")
+            raise
+
+    async def get_llm_response(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: str = "auto",
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+    ) -> StandardizedLLMResponse:
+        """
+        Sends messages via the OpenAI SDK (to Google's endpoint) and returns a standardized response.
+
+        Args:
+            model: The Google model identifier (e.g., "gemini-1.5-flash").
+            messages: Chat history in the OpenAI dictionary format.
+            tools: Tool schemas in the OpenAI function format.
+            tool_choice: Tool choice setting ("auto", "none", etc.).
+            temperature: Sampling temperature.
+            max_tokens: Max output tokens.
+
+        Returns:
+            A StandardizedLLMResponse object.
+
+        Raises:
+            OpenAIError: If the API call fails.
+            Exception: For other unexpected errors.
+        """
+        try:
+            api_kwargs = {
+                "messages": messages,
+                "model": model,
+                "tool_choice": tool_choice if tools else None,
+                "tools": tools if tools else None,
+            }
+            if temperature is not None: api_kwargs["temperature"] = temperature
+            if max_tokens is not None: api_kwargs["max_tokens"] = max_tokens
+            api_kwargs = {k: v for k, v in api_kwargs.items() if v is not None}
+
+
+            response = await self.client.chat.completions.create(**api_kwargs)
+
+            message = response.choices[0].message
+            text_content = message.content
+            tool_calls: List[LLMToolCall] = []
+
+            if message.tool_calls:
+                for tc in message.tool_calls:
+                    tool_call_id = getattr(tc, 'id', None)
+                    if not tool_call_id:
+                        tool_call_id = f"compat_call_{uuid.uuid4().hex[:6]}" # Use uuid here
+                        print(f"{Fore.YELLOW}Warning: Tool call from Google compat layer missing ID. Generated fallback: {tool_call_id}{Fore.RESET}")
+
+                    if tc.function:
+                        tool_calls.append(
+                            LLMToolCall(
+                                id=tool_call_id,
+                                function_name=tc.function.name,
+                                function_arguments_json_str=tc.function.arguments
+                            )
+                        )
+
+            return StandardizedLLMResponse(
+                text_content=text_content,
+                tool_calls=tool_calls
+            )
+
+        except OpenAIError as e:
+            print(f"{Fore.RED}Google (via OpenAI Compat Layer) API Error: {e}{Fore.RESET}")
+            raise
+        except Exception as e:
+            print(f"{Fore.RED}Error calling Google (via OpenAI Compat Layer) LLM API: {e}{Fore.RESET}")
+            raise
+
+# --- END OF agentic_patterns/llm_services/google_openai_compat_service.py ---

clap/llm_services/groq_service.py

@@ -0,0 +1,100 @@
+# --- START OF agentic_patterns/llm_services/groq_service.py ---
+
+from typing import Any, Dict, List, Optional
+
+from groq import AsyncGroq, GroqError # Import AsyncGroq and potential errors
+from colorama import Fore # For error printing
+
+# Import the base interface and response structures
+from .base import LLMServiceInterface, StandardizedLLMResponse, LLMToolCall
+
+class GroqService(LLMServiceInterface):
+    """LLM Service implementation for the Groq API."""
+
+    def __init__(self, client: Optional[AsyncGroq] = None):
+        """
+        Initializes the Groq service.
+
+        Args:
+            client: An optional pre-configured AsyncGroq client.
+                    If None, a new client will be created using environment variables.
+        """
+        self.client = client or AsyncGroq()
+        # Add any other Groq-specific initialization here if needed
+
+    async def get_llm_response(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: str = "auto",
+        # Add other relevant Groq parameters if desired, e.g., temperature, max_tokens
+        # temperature: Optional[float] = None,
+        # max_tokens: Optional[int] = None,
+    ) -> StandardizedLLMResponse:
+        """
+        Sends messages to the Groq API and returns a standardized response.
+
+        Args:
+            model: The Groq model identifier (e.g., "llama-3.3-70b-versatile").
+            messages: Chat history in the OpenAI/Groq dictionary format.
+            tools: Tool schemas in the OpenAI/Groq function format.
+            tool_choice: Tool choice setting ("auto", "none", etc.).
+
+        Returns:
+            A StandardizedLLMResponse object.
+
+        Raises:
+            GroqError: If the API call fails.
+            Exception: For other unexpected errors.
+        """
+        try:
+            api_kwargs = {
+                "messages": messages,
+                "model": model,
+                # Pass other parameters if added to method signature
+                # "temperature": temperature,
+                # "max_tokens": max_tokens,
+            }
+            if tools:
+                api_kwargs["tools"] = tools
+                api_kwargs["tool_choice"] = tool_choice
+
+            # Call the Groq API asynchronously using the correct method name
+            response = await self.client.chat.completions.create(**api_kwargs)
+
+            # Process the response
+            message = response.choices[0].message
+            text_content = message.content
+            tool_calls: List[LLMToolCall] = []
+
+            if message.tool_calls:
+                for tc in message.tool_calls:
+                    if tc.function: # Check if function attribute exists
+                        tool_calls.append(
+                            LLMToolCall(
+                                id=tc.id,
+                                function_name=tc.function.name,
+                                function_arguments_json_str=tc.function.arguments
+                            )
+                        )
+
+            # Return the standardized response
+            return StandardizedLLMResponse(
+                text_content=text_content,
+                tool_calls=tool_calls
+            )
+
+        except GroqError as e:
+            # Catch specific Groq errors for potentially better handling
+            print(f"{Fore.RED}Groq API Error: {e}{Fore.RESET}")
+            # Re-raise or handle as needed, maybe return an error response?
+            # For now, re-raise to signal failure clearly
+            raise
+        except Exception as e:
+            print(f"{Fore.RED}Error calling Groq LLM API: {e}{Fore.RESET}")
+            # Depending on desired behavior, could return a StandardizedLLMResponse
+            # with error info in text_content, or re-raise. Re-raising is cleaner.
+            raise
+
+# --- END OF agentic_patterns/llm_services/groq_service.py ---

clap/mcp_client/client.py

@@ -0,0 +1,208 @@
+# --- START OF agentic_patterns/mcp_client/client.py (SSE Version) ---
+
+import asyncio
+import json
+from contextlib import AsyncExitStack
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, HttpUrl # Import HttpUrl
+
+# Imports from MCP SDK
+from mcp import ClientSession, types
+# Import sse_client instead of stdio_client
+from mcp.client.sse import sse_client
+# For logging/coloring output
+from colorama import Fore
+
+# Configuration model for a single SSE server
+class SseServerConfig(BaseModel):
+    """Configuration for connecting to an MCP server via SSE."""
+    # Expecting a URL like http://host:port (base URL)
+    # The sse_client will likely append the standard /sse path
+    url: HttpUrl = Field(description="The base URL of the MCP SSE server.")
+    # Optional headers if needed for authentication etc.
+    headers: Optional[Dict[str, str]] = Field(default=None, description="Optional headers for the connection.")
+
+# Manager class focused on SSE
+class MCPClientManager:
+    """
+    Manages connections and interactions with multiple MCP servers via SSE.
+
+    Handles connecting, disconnecting, listing tools, and calling tools on
+    configured MCP servers accessible over HTTP/S.
+    """
+
+    def __init__(self, server_configs: Dict[str, SseServerConfig]):
+        """
+        Initializes the manager with SSE server configurations.
+
+        Args:
+            server_configs: A dictionary where keys are logical server names
+                            and values are SseServerConfig objects.
+        """
+        if not isinstance(server_configs, dict):
+             raise TypeError("server_configs must be a dictionary.")
+        self.server_configs = server_configs
+        self.sessions: Dict[str, ClientSession] = {}
+        self.exit_stacks: Dict[str, AsyncExitStack] = {}
+        self._connect_locks: Dict[str, asyncio.Lock] = {
+             name: asyncio.Lock() for name in server_configs
+        }
+        self._manager_lock = asyncio.Lock() # General lock for manager state
+
+    async def _ensure_connected(self, server_name: str):
+        """
+        Ensures a connection via SSE to the specified server is active.
+
+        Args:
+            server_name: The logical name of the server to connect to.
+
+        Raises:
+            ValueError: If the server configuration is not found or URL is invalid.
+            RuntimeError: If connection or initialization fails.
+        """
+        if server_name in self.sessions:
+            return
+
+        connect_lock = self._connect_locks.get(server_name)
+        if not connect_lock:
+             raise ValueError(f"Configuration or lock for server '{server_name}' not found.")
+
+        async with connect_lock:
+            if server_name in self.sessions:
+                return
+
+            config = self.server_configs.get(server_name)
+            if not config:
+                raise ValueError(f"Configuration for server '{server_name}' not found.")
+
+            print(f"{Fore.YELLOW}Attempting to connect to MCP server via SSE: {server_name} at {config.url}{Fore.RESET}")
+
+            # Construct the specific SSE endpoint URL (often /sse)
+            # Assuming the base URL is provided in config.url
+            sse_url = str(config.url).rstrip('/') + "/sse" # Standard convention
+
+            exit_stack = AsyncExitStack()
+            try:
+                # Establish SSE transport
+                # Pass headers if provided in config
+                sse_transport = await exit_stack.enter_async_context(
+                    sse_client(url=sse_url, headers=config.headers)
+                )
+                read_stream, write_stream = sse_transport
+
+                # Establish MCP session
+                session = await exit_stack.enter_async_context(
+                    ClientSession(read_stream, write_stream)
+                )
+
+                # Initialize session
+                await session.initialize()
+
+                async with self._manager_lock:
+                    self.sessions[server_name] = session
+                    self.exit_stacks[server_name] = exit_stack
+                print(f"{Fore.GREEN}Successfully connected to MCP server via SSE: {server_name}{Fore.RESET}")
+
+            except Exception as e:
+                await exit_stack.aclose()
+                print(f"{Fore.RED}Failed to connect to MCP server '{server_name}' via SSE: {e}{Fore.RESET}")
+                raise RuntimeError(f"SSE connection to '{server_name}' failed.") from e
+
+    async def disconnect(self, server_name: str):
+        """
+        Disconnects from a specific server and cleans up resources.
+
+        Args:
+            server_name: The logical name of the server to disconnect from.
+        """
+        async with self._manager_lock:
+             if server_name in self.sessions:
+                 print(f"{Fore.YELLOW}Disconnecting from MCP server: {server_name}...{Fore.RESET}")
+                 exit_stack = self.exit_stacks.pop(server_name)
+                 del self.sessions[server_name]
+                 await exit_stack.aclose()
+                 print(f"{Fore.GREEN}Disconnected from MCP server: {server_name}{Fore.RESET}")
+
+    async def disconnect_all(self):
+        """Disconnects from all currently connected servers."""
+        server_names = list(self.sessions.keys())
+        print(f"{Fore.YELLOW}Disconnecting from all servers: {server_names}{Fore.RESET}")
+        # Use asyncio.gather for concurrent disconnection
+        tasks = [self.disconnect(name) for name in server_names]
+        await asyncio.gather(*tasks, return_exceptions=True) # Handle errors during disconnect
+        print(f"{Fore.GREEN}Finished disconnecting all servers.{Fore.RESET}")
+
+    async def list_remote_tools(self, server_name: str) -> List[types.Tool]:
+        """
+        Lists tools available on a specific connected SSE server.
+
+        Args:
+            server_name: The logical name of the server.
+
+        Returns:
+            A list of mcp.types.Tool objects provided by the server.
+        """
+        await self._ensure_connected(server_name)
+        session = self.sessions.get(server_name)
+        if not session:
+             raise RuntimeError(f"Failed to get session for '{server_name}' after ensuring connection.")
+
+        try:
+            print(f"{Fore.CYAN}Listing tools for server: {server_name}...{Fore.RESET}")
+            tool_list_result = await session.list_tools()
+            print(f"{Fore.CYAN}Found {len(tool_list_result.tools)} tools on {server_name}.{Fore.RESET}")
+            return tool_list_result.tools
+        except Exception as e:
+            print(f"{Fore.RED}Error listing tools for server '{server_name}': {e}{Fore.RESET}")
+            raise RuntimeError(f"Failed to list tools for '{server_name}'.") from e
+
+    async def call_remote_tool(
+        self, server_name: str, tool_name: str, arguments: Dict[str, Any]
+    ) -> str:
+        """
+        Calls a tool on a specific connected SSE server.
+
+        Args:
+            server_name: The logical name of the server.
+            tool_name: The name of the tool to call.
+            arguments: A dictionary of arguments for the tool.
+
+        Returns:
+            A string representation of the tool's result content.
+        """
+        await self._ensure_connected(server_name)
+        session = self.sessions.get(server_name)
+        if not session:
+             raise RuntimeError(f"Failed to get session for '{server_name}' after ensuring connection.")
+
+        print(f"{Fore.CYAN}Calling remote tool '{tool_name}' on server '{server_name}' with args: {arguments}{Fore.RESET}")
+        try:
+             result: types.CallToolResult = await session.call_tool(tool_name, arguments)
+
+             if result.isError:
+                 error_content = result.content[0] if result.content else None
+                 error_text = getattr(error_content, 'text', 'Unknown tool error')
+                 print(f"{Fore.RED}MCP Tool '{tool_name}' on server '{server_name}' returned an error: {error_text}{Fore.RESET}")
+                 raise RuntimeError(f"Tool call error on {server_name}.{tool_name}: {error_text}")
+             else:
+                  response_parts = []
+                  for content_item in result.content:
+                      if isinstance(content_item, types.TextContent):
+                          response_parts.append(content_item.text)
+                      # Add handling for other content types if needed later
+                      elif isinstance(content_item, types.ImageContent):
+                           response_parts.append(f"[Image Content Received: {content_item.mimeType}]")
+                      elif isinstance(content_item, types.EmbeddedResource):
+                           response_parts.append(f"[Embedded Resource Received: {content_item.resource.uri}]")
+                      else:
+                           response_parts.append(f"[Unsupported content type: {getattr(content_item, 'type', 'unknown')}]")
+                  combined_response = "\n".join(response_parts)
+                  print(f"{Fore.GREEN}Tool '{tool_name}' result from '{server_name}': {combined_response[:100]}...{Fore.RESET}")
+                  return combined_response
+
+        except Exception as e:
+             print(f"{Fore.RED}Error calling tool '{tool_name}' on server '{server_name}': {e}{Fore.RESET}")
+             raise RuntimeError(f"Failed to call tool '{tool_name}' on '{server_name}'.") from e
+
+# --- END OF agentic_patterns/mcp_client/client.py (SSE Version) ---