autobyteus 1.2.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

autobyteus/tools/search/client.py

@@ -0,0 +1,24 @@
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SearchClient:
+    """
+    A client that uses a configured search strategy to perform searches.
+    This acts as the 'Context' in the Strategy pattern.
+    """
+    def __init__(self, strategy: 'SearchStrategy'):
+        if not strategy:
+            raise ValueError("SearchClient must be initialized with a valid SearchStrategy.")
+        self._strategy = strategy
+        logger.debug(f"SearchClient initialized with strategy: {type(strategy).__name__}")
+
+    async def search(self, query: str, num_results: int) -> str:
+        """
+        Delegates the search operation to the configured strategy.
+        """
+        return await self._strategy.search(query, num_results)

autobyteus/tools/search/factory.py

@@ -0,0 +1,81 @@
+import os
+import logging
+from typing import Optional
+
+from autobyteus.utils.singleton import SingletonMeta
+from .providers import SearchProvider
+from .client import SearchClient
+from .serper_strategy import SerperSearchStrategy
+from .serpapi_strategy import SerpApiSearchStrategy
+from .google_cse_strategy import GoogleCSESearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SearchClientFactory(metaclass=SingletonMeta):
+    """
+    Factory for creating a SearchClient with the appropriate strategy
+    based on environment variable configuration.
+    """
+    _instance: Optional[SearchClient] = None
+
+    def create_search_client(self) -> SearchClient:
+        """
+        Creates and returns a singleton instance of the SearchClient, configured
+        with the appropriate search strategy.
+        """
+        if self._instance:
+            return self._instance
+
+        provider_name = os.getenv("DEFAULT_SEARCH_PROVIDER", "").lower()
+        
+        serper_key = os.getenv("SERPER_API_KEY")
+        serpapi_key = os.getenv("SERPAPI_API_KEY")
+        google_api_key = os.getenv("GOOGLE_CSE_API_KEY")
+        google_cse_id = os.getenv("GOOGLE_CSE_ID")
+        
+        is_serper_configured = bool(serper_key)
+        is_serpapi_configured = bool(serpapi_key)
+        is_google_cse_configured = bool(google_api_key and google_cse_id)
+        
+        strategy = None
+
+        if provider_name == SearchProvider.GOOGLE_CSE:
+            if is_google_cse_configured:
+                logger.info("DEFAULT_SEARCH_PROVIDER is 'google_cse', using Google CSE strategy.")
+                strategy = GoogleCSESearchStrategy()
+            else:
+                raise ValueError("DEFAULT_SEARCH_PROVIDER is 'google_cse', but Google CSE is not configured. "
+                                 "Set GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID.")
+
+        elif provider_name == SearchProvider.SERPAPI:
+            if is_serpapi_configured:
+                logger.info("DEFAULT_SEARCH_PROVIDER is 'serpapi', using SerpApi strategy.")
+                strategy = SerpApiSearchStrategy()
+            else:
+                raise ValueError("DEFAULT_SEARCH_PROVIDER is 'serpapi', but SerpApi is not configured. "
+                                 "Set SERPAPI_API_KEY.")
+        
+        # Default to Serper if explicitly set, or if not set and Serper is available.
+        # This handles the case where multiple providers are configured but no provider is specified.
+        elif provider_name == SearchProvider.SERPER or is_serper_configured:
+            if is_serper_configured:
+                logger.info("Using Serper search strategy (either as default or as first fallback).")
+                strategy = SerperSearchStrategy()
+            else:
+                # This branch is only taken if provider_name is 'serper' but it's not configured.
+                raise ValueError("DEFAULT_SEARCH_PROVIDER is 'serper', but Serper is not configured. Set SERPER_API_KEY.")
+
+        elif is_serpapi_configured:
+            logger.info("Serper not configured, falling back to available SerpApi strategy.")
+            strategy = SerpApiSearchStrategy()
+
+        elif is_google_cse_configured:
+            logger.info("Neither Serper nor SerpApi are configured, falling back to available Google CSE strategy.")
+            strategy = GoogleCSESearchStrategy()
+        
+        else:
+            raise ValueError("No search provider is configured. Please set either SERPER_API_KEY, SERPAPI_API_KEY, "
+                             "or both GOOGLE_CSE_API_KEY and GOOGLE_CSE_ID environment variables.")
+
+        self._instance = SearchClient(strategy=strategy)
+        return self._instance

autobyteus/tools/search/google_cse_strategy.py

@@ -0,0 +1,68 @@
+import os
+import logging
+import aiohttp
+from typing import Dict, Any, Optional
+
+from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class GoogleCSESearchStrategy(SearchStrategy):
+    """
+    A search strategy that uses the official Google Custom Search Engine (CSE) API.
+    """
+    API_URL = "https://www.googleapis.com/customsearch/v1"
+
+    def __init__(self):
+        self.api_key: Optional[str] = os.getenv("GOOGLE_CSE_API_KEY")
+        self.cse_id: Optional[str] = os.getenv("GOOGLE_CSE_ID")
+        if not self.api_key or not self.cse_id:
+            raise ValueError(
+                "GoogleCSESearchStrategy requires both 'GOOGLE_CSE_API_KEY' and 'GOOGLE_CSE_ID' environment variables to be set."
+            )
+        logger.debug("GoogleCSESearchStrategy initialized.")
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from Google CSE API into a clean string for an LLM."""
+        if "items" not in data or not data["items"]:
+            return "No relevant information found for the query via Google CSE."
+
+        results = data["items"]
+        results_str = "\n".join(
+            f"{i+1}. {result.get('title', 'No Title')}\n"
+            f"   Link: {result.get('link', 'No Link')}\n"
+            f"   Snippet: {result.get('snippet', 'No Snippet')}"
+            for i, result in enumerate(results)
+        )
+        
+        return f"Search Results:\n{results_str}"
+
+    async def search(self, query: str, num_results: int) -> str:
+        logger.info(f"Executing search with Google CSE strategy for query: '{query}'")
+        
+        params = {
+            'key': self.api_key,
+            'cx': self.cse_id,
+            'q': query,
+            'num': num_results
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(self.API_URL, params=params) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"Google CSE API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"Google CSE API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during Google CSE API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred during Google CSE search: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in Google CSE strategy: {e}", exc_info=True)
+            raise

autobyteus/tools/search/providers.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+class SearchProvider(str, Enum):
+    """Enumerates the supported search providers."""
+    SERPER = "serper"
+    GOOGLE_CSE = "google_cse"
+    SERPAPI = "serpapi"
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/tools/search/serpapi_strategy.py

@@ -0,0 +1,65 @@
+import os
+import logging
+import aiohttp
+from typing import Dict, Any, Optional
+
+from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SerpApiSearchStrategy(SearchStrategy):
+    """
+    A search strategy that uses the SerpApi.com API.
+    """
+    API_URL = "https://serpapi.com/search.json"
+
+    def __init__(self):
+        self.api_key: Optional[str] = os.getenv("SERPAPI_API_KEY")
+        if not self.api_key:
+            raise ValueError("SerpApiSearchStrategy requires the 'SERPAPI_API_KEY' environment variable to be set.")
+        logger.debug("SerpApiSearchStrategy initialized.")
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from SerpApi into a clean string for an LLM."""
+        if "organic_results" not in data or not data["organic_results"]:
+            return "No relevant information found for the query via SerpApi."
+
+        results = data["organic_results"]
+        results_str = "\n".join(
+            f"{i+1}. {result.get('title', 'No Title')}\n"
+            f"   Link: {result.get('link', 'No Link')}\n"
+            f"   Snippet: {result.get('snippet', 'No Snippet')}"
+            for i, result in enumerate(results)
+        )
+        
+        return f"Search Results:\n{results_str}"
+
+    async def search(self, query: str, num_results: int) -> str:
+        logger.info(f"Executing search with SerpApi strategy for query: '{query}'")
+        
+        params = {
+            'api_key': self.api_key,
+            'engine': 'google',
+            'q': query,
+            'num': num_results
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(self.API_URL, params=params) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"SerpApi API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"SerpApi API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during SerpApi API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred during SerpApi search: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in SerpApi strategy: {e}", exc_info=True)
+            raise

autobyteus/tools/search/serper_strategy.py

@@ -0,0 +1,87 @@
+import os
+import json
+import logging
+import aiohttp
+from typing import Dict, Any, Optional
+
+from .base_strategy import SearchStrategy
+
+logger = logging.getLogger(__name__)
+
+class SerperSearchStrategy(SearchStrategy):
+    """
+    A search strategy that uses the Serper.dev API.
+    """
+    API_URL = "https://google.serper.dev/search"
+
+    def __init__(self):
+        self.api_key: Optional[str] = os.getenv("SERPER_API_KEY")
+        if not self.api_key:
+            raise ValueError("SerperSearchStrategy requires the 'SERPER_API_KEY' environment variable to be set.")
+        logger.debug("SerperSearchStrategy initialized.")
+
+    def _format_results(self, data: Dict[str, Any]) -> str:
+        """Formats the JSON response from Serper into a clean string for an LLM."""
+        summary_parts = []
+        
+        # 1. Answer Box (most important for direct questions)
+        if "answerBox" in data:
+            answer_box = data["answerBox"]
+            title = answer_box.get("title", "")
+            snippet = answer_box.get("snippet") or answer_box.get("answer")
+            summary_parts.append(f"Direct Answer for '{title}':\n{snippet}")
+
+        # 2. Knowledge Graph (for entity information)
+        if "knowledgeGraph" in data:
+            kg = data["knowledgeGraph"]
+            title = kg.get("title", "")
+            description = kg.get("description")
+            summary_parts.append(f"Summary for '{title}':\n{description}")
+
+        # 3. Organic Results (the main search links)
+        if "organic" in data and data["organic"]:
+            organic_results = data["organic"]
+            results_str = "\n".join(
+                f"{i+1}. {result.get('title', 'No Title')}\n"
+                f"   Link: {result.get('link', 'No Link')}\n"
+                f"   Snippet: {result.get('snippet', 'No Snippet')}"
+                for i, result in enumerate(organic_results)
+            )
+            summary_parts.append(f"Search Results:\n{results_str}")
+        
+        if not summary_parts:
+            return "No relevant information found for the query via Serper."
+
+        return "\n\n---\n\n".join(summary_parts)
+
+    async def search(self, query: str, num_results: int) -> str:
+        logger.info(f"Executing search with Serper strategy for query: '{query}'")
+        
+        headers = {
+            'X-API-KEY': self.api_key,
+            'Content-Type': 'application/json'
+        }
+        payload = json.dumps({
+            "q": query,
+            "num": num_results
+        })
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(self.API_URL, headers=headers, data=payload) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        return self._format_results(data)
+                    else:
+                        error_text = await response.text()
+                        logger.error(
+                            f"Serper API returned a non-200 status code: {response.status}. "
+                            f"Response: {error_text}"
+                        )
+                        raise RuntimeError(f"Serper API request failed with status {response.status}: {error_text}")
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error during Serper API call: {e}", exc_info=True)
+            raise RuntimeError(f"A network error occurred during Serper search: {e}")
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in Serper strategy: {e}", exc_info=True)
+            raise

autobyteus/tools/search_tool.py

@@ -0,0 +1,83 @@
+import logging
+from typing import Optional, TYPE_CHECKING
+
+from autobyteus.tools.base_tool import BaseTool
+from autobyteus.tools.tool_config import ToolConfig
+from autobyteus.utils.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.tools.search import SearchClientFactory, SearchClient
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+
+class Search(BaseTool):
+    """
+    Performs a web search using a configurable backend provider (e.g., Serper.dev, Google CSE).
+    Returns a structured summary of the results.
+    Configuration is managed via environment variables (see SearchClientFactory for details).
+    """
+    CATEGORY = ToolCategory.WEB
+
+    def __init__(self, config: Optional[ToolConfig] = None):
+        super().__init__(config=config)
+        try:
+            factory = SearchClientFactory()
+            self.search_client: SearchClient = factory.create_search_client()
+        except ValueError as e:
+            logger.error(f"Failed to initialize search_web tool: {e}", exc_info=True)
+            # Re-raise to prevent tool from being used in a misconfigured state.
+            raise RuntimeError(
+                "Could not initialize Search tool. Please check your search provider configuration. "
+                f"Error: {e}"
+            )
+            logger.debug("search_web tool initialized with a configured search client.")
+    
+    @classmethod
+    def get_name(cls) -> str:
+        return "search_web"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return (
+            "Searches the web for a given query using the configured search provider. "
+            "Returns a concise, structured summary of search results, including direct answers (if available) and top organic links."
+        )
+
+    @classmethod
+    def get_argument_schema(cls) -> Optional[ParameterSchema]:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="query",
+            param_type=ParameterType.STRING,
+            description="The search query string.",
+            required=True
+        ))
+        schema.add_parameter(ParameterDefinition(
+            name="num_results",
+            param_type=ParameterType.INTEGER,
+            description="The number of organic search results to return.",
+            required=False,
+            default_value=5,
+            min_value=1,
+            max_value=10
+        ))
+        return schema
+
+    @classmethod
+    def get_config_schema(cls) -> Optional[ParameterSchema]:
+        # Configuration is now handled by the factory via environment variables,
+        # so this tool no longer has instance-specific configuration.
+        return None
+
+    async def _execute(self, context: 'AgentContext', query: str, num_results: int = 5) -> str:
+        logger.info(f"Executing search_web for agent {context.agent_id} with query: '{query}'")
+        
+        try:
+            return await self.search_client.search(query=query, num_results=num_results)
+        except Exception as e:
+            logger.error(f"An unexpected error occurred in search_web execution: {e}", exc_info=True)
+            # Re-raise to ensure the agent is aware of the failure.
+            raise

autobyteus/tools/timer.py

@@ -48,6 +48,10 @@ class Timer(BaseTool, EventEmitter):
         self._task: Optional[asyncio.Task] = None
         logger.debug(f"Timer initialized with duration: {self.duration}s, interval: {self.interval}s")
 
+    @classmethod
+    def get_name(cls) -> str:
+        return "start_timer"
+
     @classmethod
     def get_description(cls) -> str:
         return "Sets and runs a timer. Emits TIMER_UPDATE events with remaining time at specified intervals."

autobyteus/tools/tool_meta.py

@@ -35,26 +35,8 @@ class ToolMeta(ABCMeta):
                  logger.error(f"Tool class {name} ({tool_name}) must return a valid string from get_description(). Skipping registration.")
                  return
 
-            argument_schema: ParameterSchema = None 
-            try:
-                argument_schema = cls.get_argument_schema() 
-                if argument_schema is not None and not isinstance(argument_schema, ParameterSchema): 
-                    logger.error(f"Tool class {name} ({tool_name}) get_argument_schema() must return a ParameterSchema or None. Got {type(argument_schema)}. Skipping registration.")
-                    return
-            except Exception as e:
-                logger.error(f"Tool class {name} ({tool_name}) failed to provide argument_schema via get_argument_schema(): {e}. Skipping registration.", exc_info=True)
-                return
+            # Note: We do not call the schema methods here. We pass them as providers.
             
-            instantiation_config_schema: ParameterSchema = None 
-            if hasattr(cls, 'get_config_schema'):
-                try:
-                    instantiation_config_schema = cls.get_config_schema()
-                    if instantiation_config_schema is not None and not isinstance(instantiation_config_schema, ParameterSchema): 
-                        logger.warning(f"Tool class {name} ({tool_name}) get_config_schema() returned non-ParameterSchema type: {type(instantiation_config_schema)}. Treating as no config schema.")
-                        instantiation_config_schema = None
-                except Exception as e:
-                    logger.warning(f"Tool class {name} ({tool_name}) has get_config_schema() but it failed: {e}. Assuming no instantiation config.")
-
             # Get category from class attribute, defaulting to "General"
             category_str = getattr(cls, 'CATEGORY', ToolCategory.GENERAL)
             
@@ -64,16 +46,14 @@ class ToolMeta(ABCMeta):
                 description=general_description, 
                 tool_class=cls,
                 custom_factory=None,
-                argument_schema=argument_schema,
-                config_schema=instantiation_config_schema,
+                argument_schema_provider=cls.get_argument_schema,
+                config_schema_provider=cls.get_config_schema,
                 origin=ToolOrigin.LOCAL,
                 category=category_str
             )
             default_tool_registry.register_tool(definition)
             
-            arg_schema_info = f"args: {len(argument_schema) if argument_schema else '0'}"
-            config_info = f"inst_config: {len(instantiation_config_schema) if instantiation_config_schema else '0'}"
-            logger.info(f"Auto-registered tool: '{tool_name}' from class {name} ({arg_schema_info}, {config_info})")
+            logger.info(f"Auto-registered tool: '{tool_name}' from class {name}")
 
         except AttributeError as e:
              logger.error(f"Tool class {name} is missing a required method ({e}). Skipping registration.")

autobyteus/workflow/bootstrap_steps/coordinator_prompt_preparation_step.py

@@ -91,7 +91,7 @@ class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
 
             prompt_parts.append(tools_section)
                 
-            final_instruction = "### Your Task\nAnalyze the user's request, formulate a plan, and use the `SendMessageTo` tool to delegate tasks to your team. Address team members by their unique ID as listed under 'Your Team'."
+            final_instruction = "### Your Task\nAnalyze the user's request, formulate a plan, and use the `send_message_to` tool to delegate tasks to your team. Address team members by their unique ID as listed under 'Your Team'."
             prompt_parts.append(final_instruction)
         else:
             role_and_goal = (
@@ -105,4 +105,3 @@ class CoordinatorPromptPreparationStep(BaseWorkflowBootstrapStep):
             prompt_parts.append(final_instruction)
 
         return "\n\n".join(prompt_parts)
-

{autobyteus-1.2.0.dist-info → autobyteus-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autobyteus
-Version: 1.2.0
+Version: 1.2.1
 Summary: Multi-Agent framework
 Home-page: https://github.com/AutoByteus/autobyteus
 Author: Ryan Zheng
@@ -99,11 +99,11 @@ Launch and monitor your agent teams with our built-in Textual-based TUI.
 -   **Hierarchical View**: See the structure of your team, including sub-teams and their agents.
 -   **Real-Time Status**: Agent and team statuses are updated live, showing you who is idle, thinking, or executing a tool.
 -   **Detailed Logs**: Select any agent to view a detailed, streaming log of their thoughts, actions, and tool interactions.
--   **Live Task Board**: Watch your team's `TaskBoard` update in real-time as the coordinator publishes a plan and agents complete their tasks.
+-   **Live Task Plan**: Watch your team's `TaskPlan` update in real-time as the coordinator publishes a plan and agents complete their tasks.
 
-| TUI - Detailed Agent Log | TUI - Task Board with Completed Task |
+| TUI - Detailed Agent Log | TUI - Task Plan with Completed Task |
 | :---: | :---: |
-| ![Autobyteus Agent Log](docs/images/image_4.png) | ![Autobyteus Task Board](docs/images/image_3.png) |
+| ![Autobyteus Agent Log](docs/images/image_4.png) | ![Autobyteus Task Plan](docs/images/image_3.png) |
 
 #### 🏗️ Fluent Team Building
 Define complex agent and team structures with an intuitive, fluent API. The `AgentTeamBuilder` makes composing your team simple and readable.
@@ -130,7 +130,7 @@ Autobyteus intelligently handles tool communication with LLMs while giving you f
 #### 📈 Flexible Communication Protocols
 Choose the collaboration pattern that best fits your use case with configurable `TaskNotificationMode`s.
 -   **`AGENT_MANUAL_NOTIFICATION` (Default)**: A traditional approach where a coordinator agent is responsible for creating a plan and then explicitly notifying other agents to begin their work via messages.
--   **`SYSTEM_EVENT_DRIVEN`**: A more automated approach where the coordinator's only job is to publish a plan to the `TaskBoard`. The framework then monitors the board and automatically notifies agents when their tasks become unblocked, enabling parallel execution and reducing coordinator overhead.
+-   **`SYSTEM_EVENT_DRIVEN`**: A more automated approach where the coordinator's only job is to publish a plan to the `TaskPlan`. The framework then monitors the board and automatically notifies agents when their tasks become unblocked, enabling parallel execution and reducing coordinator overhead.
 
 ## Requirements