clap-agents 0.1.1__py3-none-any.whl

clap/tools/email_tools.py

@@ -0,0 +1,230 @@
+# --- START OF agentic_patterns/tools/email_tools.py ---
+
+import os
+import smtplib
+import imaplib
+import email
+import json # For potential result formatting
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from email.mime.base import MIMEBase
+from email import encoders
+from email.header import decode_header
+from dotenv import load_dotenv
+import anyio 
+import functools 
+import requests
+from typing import Optional
+
+from clap.tool_pattern.tool import tool
+
+load_dotenv()
+
+SMTP_HOST = "smtp.gmail.com"
+SMTP_PORT = 587
+IMAP_HOST = "imap.gmail.com"
+SMTP_USERNAME = os.getenv("SMTP_USERNAME")
+SMTP_PASSWORD = os.getenv("SMTP_PASSWORD")
+
+
+def _send_email_sync(recipient: str, subject: str, body: str, attachment_path: Optional[str] = None) -> str:
+    """Synchronous helper to send email."""
+    if not SMTP_USERNAME or not SMTP_PASSWORD:
+        return "Error: SMTP username or password not configured in environment."
+    try:
+        msg = MIMEMultipart()
+        msg["From"] = SMTP_USERNAME
+        msg["To"] = recipient
+        msg["Subject"] = subject
+        msg.attach(MIMEText(body, "plain"))
+        if attachment_path and os.path.exists(attachment_path):
+            with open(attachment_path, "rb") as attachment:
+                part = MIMEBase("application", "octet-stream")
+                part.set_payload(attachment.read())
+            encoders.encode_base64(part)
+            part.add_header("Content-Disposition", f"attachment; filename={os.path.basename(attachment_path)}")
+            msg.attach(part)
+        # Use context manager for SMTP connection
+        with smtplib.SMTP(SMTP_HOST, SMTP_PORT) as server:
+            server.starttls()
+            server.login(SMTP_USERNAME, SMTP_PASSWORD)
+            server.sendmail(SMTP_USERNAME, recipient, msg.as_string())
+        # Clean up downloaded attachment if it was temporary
+        if attachment_path and attachment_path.startswith("temp_attachments"):
+            try: os.remove(attachment_path)
+            except OSError: pass # Ignore if deletion fails
+        return "Email sent successfully."
+    except Exception as e:
+        return f"Failed to send email: {e}"
+
+def _download_attachment_sync(attachment_url: str, attachment_filename: str) -> str:
+    """Synchronous helper to download an attachment."""
+    temp_dir = "temp_attachments" # Consider using tempfile module for more robustness
+    os.makedirs(temp_dir, exist_ok=True)
+    file_path = os.path.join(temp_dir, attachment_filename)
+    # Use streaming for potentially large files
+    with requests.get(attachment_url, stream=True) as r:
+        r.raise_for_status()
+        with open(file_path, "wb") as f:
+            for chunk in r.iter_content(chunk_size=8192):
+                f.write(chunk)
+    return file_path
+
+def _get_pre_staged_attachment_sync(attachment_name: str) -> Optional[str]:
+    """Synchronous helper to get a pre-staged attachment."""
+    attachment_dir = "available_attachments" # User needs to create this folder
+    file_path = os.path.join(attachment_dir, attachment_name)
+    return file_path if os.path.exists(file_path) else None
+
+def _fetch_emails_sync(folder: str, limit: int) -> str:
+    """Synchronous helper to fetch emails."""
+    if not SMTP_USERNAME or not SMTP_PASSWORD:
+        return "Error: Email username or password not configured in environment."
+    emails_data = []
+    try:
+        mail = imaplib.IMAP4_SSL(IMAP_HOST)
+        mail.login(SMTP_USERNAME, SMTP_PASSWORD)
+        status, messages = mail.select(folder)
+        if status != 'OK':
+            mail.logout()
+            return f"Error selecting folder '{folder}': {messages}"
+
+        result, data = mail.search(None, "ALL")
+        if status != 'OK' or not data or not data[0]:
+            mail.logout()
+            return f"No emails found in folder '{folder}'."
+
+        email_ids = data[0].split()
+        # Fetch in reverse order up to the limit
+        ids_to_fetch = email_ids[-(limit):]
+
+        for email_id_bytes in reversed(ids_to_fetch):
+            status, msg_data = mail.fetch(email_id_bytes, "(RFC822)")
+            if status == 'OK':
+                for response_part in msg_data:
+                    if isinstance(response_part, tuple):
+                        msg = email.message_from_bytes(response_part[1])
+                        subject, encoding = decode_header(msg["Subject"])[0]
+                        if isinstance(subject, bytes):
+                            subject = subject.decode(encoding or "utf-8")
+                        from_ = msg.get("From", "")
+                        date_ = msg.get("Date", "")
+                        # Basic snippet extraction (first text part)
+                        snippet = ""
+                        if msg.is_multipart():
+                            for part in msg.walk():
+                                ctype = part.get_content_type()
+                                cdisp = str(part.get("Content-Disposition"))
+                                if ctype == "text/plain" and "attachment" not in cdisp:
+                                    try:
+                                        body = part.get_payload(decode=True)
+                                        snippet = body.decode(part.get_content_charset() or 'utf-8')
+                                        snippet = " ".join(snippet.splitlines()) # Remove newlines
+                                        snippet = snippet[:150] + "..." # Truncate
+                                        break
+                                    except Exception:
+                                        snippet = "[Could not decode body]"
+                                        break
+                        else:
+                            try:
+                                body = msg.get_payload(decode=True)
+                                snippet = body.decode(msg.get_content_charset() or 'utf-8')
+                                snippet = " ".join(snippet.splitlines())
+                                snippet = snippet[:150] + "..."
+                            except Exception:
+                                snippet = "[Could not decode body]"
+
+                        emails_data.append({
+                            "id": email_id_bytes.decode(),
+                            "from": from_,
+                            "subject": subject,
+                            "date": date_,
+                            "snippet": snippet
+                        })
+            if len(emails_data) >= limit: # Should not exceed limit due to slicing, but safety check
+                 break
+
+        mail.logout()
+
+        if not emails_data:
+            return f"No emails found in folder '{folder}'."
+
+        # Format result (maybe JSON is better for agents?)
+        result_text = f"Recent emails from {folder} (up to {limit}):\n\n"
+        for i, email_data in enumerate(emails_data, 1):
+            result_text += f"{i}. From: {email_data['from']}\n"
+            result_text += f"   Subject: {email_data['subject']}\n"
+            result_text += f"   Date: {email_data['date']}\n"
+            result_text += f"   Snippet: {email_data['snippet']}\n\n"
+            # result_text += f"   ID: {email_data['id']}\n\n" # ID might not be useful for LLM
+        return result_text.strip()
+    except Exception as e:
+        return f"Failed to fetch emails: {e}"
+
+# --- Asynchronous Tool Wrappers ---
+
+@tool
+async def send_email(recipient: str, subject: str, body: str,
+                     attachment_path: Optional[str] = None,
+                     attachment_url: Optional[str] = None,
+                     attachment_name: Optional[str] = None) -> str:
+    """
+    Sends an email using configured Gmail account. Can handle attachments via local path, URL, or pre-staged name.
+
+    Args:
+        recipient: The email address to send the email to.
+        subject: The email subject.
+        body: The email body text.
+        attachment_path: Optional direct file path for an attachment.
+        attachment_url: Optional URL from which to download an attachment (requires attachment_name).
+        attachment_name: Optional filename for the attachment (used with URL or pre-staged).
+
+    Returns:
+        Success or error message string.
+    """
+    final_attachment_path = attachment_path
+    if attachment_url and attachment_name:
+        try:
+            # Run synchronous download in thread
+            print(f"[Email Tool] Downloading attachment from {attachment_url}...")
+            final_attachment_path = await anyio.to_thread.run_sync(
+                _download_attachment_sync, attachment_url, attachment_name
+            )
+            print(f"[Email Tool] Attachment downloaded to {final_attachment_path}")
+        except Exception as e:
+            return f"Failed to download attachment from URL: {e}"
+    elif attachment_name:
+        try:
+            # Run synchronous file check in thread
+            print(f"[Email Tool] Checking for pre-staged attachment: {attachment_name}...")
+            final_attachment_path = await anyio.to_thread.run_sync(
+                _get_pre_staged_attachment_sync, attachment_name
+            )
+            if not final_attachment_path:
+                return f"Error: Attachment '{attachment_name}' not found in pre-staged directory 'available_attachments'."
+            print(f"[Email Tool] Using pre-staged attachment: {final_attachment_path}")
+        except Exception as e:
+             return f"Error accessing pre-staged attachment: {e}"
+
+    # Run synchronous email sending in thread
+    print(f"[Email Tool] Sending email to {recipient}...")
+    return await anyio.to_thread.run_sync(
+        _send_email_sync, recipient, subject, body, final_attachment_path
+    )
+
+@tool
+async def fetch_recent_emails(folder: str = "INBOX", limit: int = 5) -> str:
+    """
+    Fetches subject, sender, date, and a snippet of recent emails (up to limit) from a specified folder.
+
+    Args:
+        folder: The email folder to fetch from (default: "INBOX"). Common options: "INBOX", "Sent", "Drafts", "[Gmail]/Spam", "[Gmail]/Trash".
+        limit: Maximum number of emails to fetch (default: 5).
+
+    Returns:
+        A formatted string containing details of the recent emails or an error message.
+    """
+    # Run synchronous IMAP fetching in thread
+    print(f"[Email Tool] Fetching up to {limit} emails from folder '{folder}'...")
+    return await anyio.to_thread.run_sync(_fetch_emails_sync, folder, limit)
+

clap/tools/web_crawler.py

@@ -0,0 +1,82 @@
+
+import asyncio
+import json
+import os
+from dotenv import load_dotenv
+
+from clap.tool_pattern.tool import tool
+
+try:
+    from crawl4ai import AsyncWebCrawler
+except ImportError:
+    raise ImportError("crawl4ai library not found. Please install it using: pip install crawl4ai")
+
+load_dotenv()
+
+@tool
+async def scrape_url(url: str) -> str:
+    """
+    Scrape a webpage and return its raw markdown content.
+
+    Args:
+        url: The URL of the webpage to scrape.
+
+    Returns:
+        The webpage content in markdown format or an error message.
+    """
+    try:
+        async with AsyncWebCrawler() as crawler:
+            result = await crawler.arun(url=url)
+            return result.markdown.raw_markdown if result.markdown else "No content found"
+    except Exception as e:
+        return f"Error scraping URL '{url}': {str(e)}"
+
+@tool
+async def extract_text_by_query(url: str, query: str, context_size: int = 300) -> str:
+    """
+    Extract relevant text snippets containing a query from a webpage's markdown content.
+
+    Args:
+        url: The URL of the webpage to search.
+        query: The search query (case-insensitive) to look for.
+        context_size: Number of characters around the match to include.
+
+    Returns:
+        Relevant text snippets containing the query or a message indicating no matches/content.
+    """
+    try:
+        markdown_content = await scrape_url.run(url=url)
+
+        if not markdown_content or markdown_content == "No content found" or markdown_content.startswith("Error"):
+            # Pass through the error message from scrape_url if it failed
+            return markdown_content if markdown_content.startswith("Error") else f"Could not retrieve content from URL: {url}"
+
+        lower_query = query.lower()
+        lower_content = markdown_content.lower()
+        matches = []
+        start_index = 0
+
+        while len(matches) < 5: # Limit matches
+            pos = lower_content.find(lower_query, start_index)
+            if pos == -1:
+                break
+
+            start = max(0, pos - context_size)
+            end = min(len(markdown_content), pos + len(lower_query) + context_size)
+            context_snippet = markdown_content[start:end]
+            prefix = "..." if start > 0 else ""
+            suffix = "..." if end < len(markdown_content) else ""
+            matches.append(f"{prefix}{context_snippet}{suffix}")
+
+            start_index = pos + len(lower_query)
+
+        if matches:
+            result_text = "\n\n---\n\n".join([f"Match {i+1}:\n{match}" for i, match in enumerate(matches)])
+            return f"Found {len(matches)} matches for '{query}' on the page:\n\n{result_text}"
+        else:
+            return f"No matches found for '{query}' on the page."
+
+    except Exception as e:
+        # Catch potential errors during the find/string manipulation logic
+        return f"Error processing content from '{url}' for query '{query}': {str(e)}"
+

clap/tools/web_search.py

@@ -0,0 +1,24 @@
+import os
+from duckduckgo_search import DDGS
+from ..tool_pattern.tool import tool
+
+
+
+@tool
+def duckduckgo_search(query: str, num_results: int = 5) -> str:
+    """Performs a web search using the DuckDuckGo Search API."""
+    try:
+        with DDGS() as ddgs:
+            results = ddgs.text(keywords=query, max_results=num_results)
+            if results:
+                results_str = f"DuckDuckGo search results for '{query}':\n"
+                for i, result in enumerate(results):
+                    title = result.get('title', 'No Title')
+                    snippet = result.get('body', 'No Snippet')
+                    url = result.get('href', 'No URL')
+                    results_str += f"{i+1}. {title}\n   URL: {url}\n   Snippet: {snippet}\n\n"
+                return results_str.strip()
+            else:
+                return f"No DuckDuckGo results found for '{query}'."
+    except Exception as e:
+        return f"Error during DuckDuckGo web search for '{query}': {e}"

clap/utils/completions.py

@@ -0,0 +1,173 @@
+
+
+import asyncio 
+from typing import Optional, List, Dict, Any 
+# Assuming Groq client and specific API response types might be needed
+# from groq import Groq # Already imported elsewhere, ensure available
+# from groq.types.chat.chat_completion import ChatCompletion # Example type hint
+# from groq.types.chat.chat_completion_message import ChatCompletionMessage # Example type hint
+from groq import AsyncGroq
+
+
+GroqClient = Any
+ChatCompletionMessage = Any
+
+
+async def completions_create(
+    client: AsyncGroq,
+    messages: List[Dict[str, Any]], # Use more specific types if available
+    model: str,
+    tools: Optional[List[Dict[str, Any]]] = None, # Added tools parameter
+    tool_choice: str = "auto" # Added tool_choice parameter ("auto", "none", or {"type": "function", "function": {"name": "my_function"}})
+) -> ChatCompletionMessage: # Changed return type
+    """
+    Sends an asynchronous request to the client's completions endpoint, supporting tool use.
+
+    Args:
+        client: The API client object (e.g., Groq) supporting async operations.
+        messages: A list of message objects for the chat history.
+        model: The model to use.
+        tools: A list of tool schemas the model can use.
+        tool_choice: Controls how the model uses tools.
+
+    Returns:
+        The message object from the API response, which might contain content or tool calls.
+    """
+    try:
+        # Prepare arguments, only include tools/tool_choice if tools are provided
+        api_kwargs = {
+            "messages": messages,
+            "model": model,
+        }
+        if tools:
+            api_kwargs["tools"] = tools
+            api_kwargs["tool_choice"] = tool_choice
+
+        # Changed .acreate to .create based on Groq async documentation
+        response = await client.chat.completions.create(**api_kwargs)
+        # Return the entire message object from the first choice
+        return response.choices[0].message
+    except Exception as e:
+        # Handle potential API errors
+        print(f"Error calling LLM API asynchronously: {e}")
+        # Return a custom message or re-raise depending on desired error handling
+        # Returning a placeholder error message object might be useful
+        class ErrorMessage:
+             content = f"Error communicating with LLM: {e}"
+             tool_calls = None
+             role = "assistant"
+        return ErrorMessage()
+
+
+def build_prompt_structure(
+    role: str,
+    content: Optional[str] = None, # Content is optional now
+    tag: str = "",
+    tool_calls: Optional[List[Dict[str, Any]]] = None, # Added for assistant messages
+    tool_call_id: Optional[str] = None # Added for tool messages
+) -> dict:
+    """
+    Builds a structured message dictionary for the chat API.
+
+    Args:
+        role: The role ('system', 'user', 'assistant', 'tool').
+        content: The text content of the message (required for user, system, tool roles).
+        tag: An optional tag to wrap the content (legacy, consider removing).
+        tool_calls: A list of tool calls requested by the assistant.
+        tool_call_id: The ID of the tool call this message is a response to (for role 'tool').
+
+    Returns:
+        A dictionary representing the structured message.
+    """
+    message: Dict[str, Any] = {"role": role}
+    if content is not None:
+        if tag: # Apply legacy tag if provided
+             content = f"<{tag}>{content}</{tag}>"
+        message["content"] = content
+
+    # Add tool_calls if provided (only for assistant role)
+    if role == "assistant" and tool_calls:
+        message["tool_calls"] = tool_calls
+
+    # Add tool_call_id if provided (only for tool role)
+    if role == "tool" and tool_call_id:
+        message["tool_call_id"] = tool_call_id
+        if content is None: # Tool role requires content
+             raise ValueError("Content is required for role 'tool'.")
+
+    # Basic validation
+    if role == "tool" and not tool_call_id:
+         raise ValueError("tool_call_id is required for role 'tool'.")
+    if role != "assistant" and tool_calls:
+         raise ValueError("tool_calls can only be added to 'assistant' role messages.")
+
+    return message
+
+
+def update_chat_history(
+    history: list,
+    message: ChatCompletionMessage | Dict[str, Any] # Accept API message object or manually created dict
+    ):
+    """
+    Updates the chat history by appending a message object or a manually created message dict.
+
+    Args:
+        history (list): The list representing the current chat history.
+        message: The message object from the API response or a dict created by build_prompt_structure.
+    """
+    # If it's an API message object, convert it to the expected dict format
+    if hasattr(message, "role"): # Basic check if it looks like an API message object
+        msg_dict = {"role": message.role}
+        if hasattr(message, "content") and message.content is not None:
+            msg_dict["content"] = message.content
+        if hasattr(message, "tool_calls") and message.tool_calls:
+             # Assuming message.tool_calls is already in the correct list[dict] format
+            msg_dict["tool_calls"] = message.tool_calls
+        # Add other relevant fields if needed
+        history.append(msg_dict)
+    elif isinstance(message, dict) and "role" in message:
+        # If it's already a dictionary (e.g., from build_prompt_structure)
+        history.append(message)
+    else:
+        raise TypeError("Invalid message type provided to update_chat_history.")
+
+
+class ChatHistory(list):
+    def __init__(self, messages: Optional[List[Dict[str, Any]]] = None, total_length: int = -1): # Type hint messages
+        if messages is None:
+            messages = []
+        super().__init__(messages)
+        self.total_length = total_length # Note: total_length logic might need adjustment for tool calls/responses
+
+    def append(self, msg: Dict[str, Any]): # Expecting message dictionaries now
+        if not isinstance(msg, dict) or "role" not in msg:
+            raise TypeError("ChatHistory can only append message dictionaries with a 'role'.")
+
+        # Simple length check, might need refinement based on token count or message types
+        if self.total_length > 0 and len(self) == self.total_length:
+            self.pop(0) # Remove the oldest message (index 0)
+        super().append(msg)
+
+
+class FixedFirstChatHistory(ChatHistory):
+    def __init__(self, messages: Optional[List[Dict[str, Any]]] = None, total_length: int = -1):
+        super().__init__(messages, total_length)
+
+    def append(self, msg: Dict[str, Any]):
+        if not isinstance(msg, dict) or "role" not in msg:
+            raise TypeError("ChatHistory can only append message dictionaries with a 'role'.")
+
+        # Keep the first message (system prompt) fixed
+        if self.total_length > 0 and len(self) == self.total_length:
+            if len(self) > 1: # Ensure there's more than just the system prompt to remove
+                 self.pop(1) # Remove the second oldest message (index 1)
+            else:
+                 # Cannot append if length is 1 and fixed
+                 print("Warning: Cannot append to FixedFirstChatHistory of size 1.")
+                 return
+        # Only call super().append if there's space or an item was removed
+        if self.total_length <= 0 or len(self) < self.total_length:
+             super().append(msg)
+
+
+# --- END OF ASYNC MODIFIED completions.py ---

clap/utils/extraction.py

@@ -0,0 +1,42 @@
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class TagContentResult:
+    """
+    A data class to represent the result of extracting tag content.
+
+    Attributes:
+        content (List[str]): A list of strings containing the content found between the specified tags.
+        found (bool): A flag indicating whether any content was found for the given tag.
+    """
+
+    content: list[str]
+    found: bool
+
+
+def extract_tag_content(text: str, tag: str) -> TagContentResult:
+    """
+    Extracts all content enclosed by specified tags (e.g., <thought>, <response>, etc.).
+
+    Parameters:
+        text (str): The input string containing multiple potential tags.
+        tag (str): The name of the tag to search for (e.g., 'thought', 'response').
+
+    Returns:
+        dict: A dictionary with the following keys:
+            - 'content' (list): A list of strings containing the content found between the specified tags.
+            - 'found' (bool): A flag indicating whether any content was found for the given tag.
+    """
+    # Build the regex pattern dynamically to find multiple occurrences of the tag
+    tag_pattern = rf"<{tag}>(.*?)</{tag}>"
+
+    # Use findall to capture all content between the specified tag
+    matched_contents = re.findall(tag_pattern, text, re.DOTALL)
+
+    # Return the dataclass instance with the result
+    return TagContentResult(
+        content=[content.strip() for content in matched_contents],
+        found=bool(matched_contents),
+    )

clap/utils/logging.py

@@ -0,0 +1,28 @@
+import time
+
+from colorama import Fore
+from colorama import Style
+
+
+def fancy_print(message: str) -> None:
+    """
+    Displays a fancy print message.
+
+    Args:
+        message (str): The message to display.
+    """
+    print(Style.BRIGHT + Fore.CYAN + f"\n{'=' * 50}")
+    print(Fore.MAGENTA + f"{message}")
+    print(Style.BRIGHT + Fore.CYAN + f"{'=' * 50}\n")
+    time.sleep(0.5)
+
+
+def fancy_step_tracker(step: int, total_steps: int) -> None:
+    """
+    Displays a fancy step tracker for each iteration of the generation-reflection loop.
+
+    Args:
+        step (int): The current step in the loop.
+        total_steps (int): The total number of steps in the loop.
+    """
+    fancy_print(f"STEP {step + 1}/{total_steps}")