camel-ai 0.2.71a1__py3-none-any.whl → 0.2.71a3__py3-none-any.whl

camel/services/agent_openapi_server.py

@@ -0,0 +1,380 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+
+from typing import Any, Dict, List, Optional, Type, Union
+
+from fastapi import APIRouter, FastAPI, HTTPException
+from pydantic import BaseModel
+
+from camel.agents.chat_agent import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import ModelFactory
+from camel.toolkits import FunctionTool
+from camel.types import RoleType
+
+
+class InitRequest(BaseModel):
+    r"""Request schema for initializing a ChatAgent via the OpenAPI server.
+
+    Defines the configuration used to create a new agent, including the model,
+    system message, tool names, and generation parameters.
+
+    Args:
+        model_type (Optional[str]): The model type to use. Should match a key
+            supported by the model manager, e.g., "gpt-4o-mini".
+            (default: :obj:`"gpt-4o-mini"`)
+        model_platform (Optional[str]): The model platform to use.
+            (default: :obj:`"openai"`)
+        tools_names (Optional[List[str]]): A list of tool names to load from
+            the tool registry. These tools will be available to the agent.
+            (default: :obj:`None`)
+        external_tools (Optional[List[Dict[str, Any]]]): Tool definitions
+            provided directly as dictionaries, bypassing the registry.
+            Currently not supported. (default: :obj:`None`)
+        agent_id (str): The unique identifier for the agent. Must be provided
+            explicitly to support multi-agent routing and control.
+        system_message (Optional[str]): The system prompt for the agent,
+            describing its behavior or role. (default: :obj:`None`)
+        message_window_size (Optional[int]): The number of recent messages to
+            retain in memory for context. (default: :obj:`None`)
+        token_limit (Optional[int]): The token budget for contextual memory.
+            (default: :obj:`None`)
+        output_language (Optional[str]): Preferred output language for the
+            agent's replies. (default: :obj:`None`)
+        max_iteration (Optional[int]): Maximum number of model
+            calling iterations allowed per step. If `None` (default), there's
+            no explicit limit. If `1`, it performs a single model call. If `N
+            > 1`, it allows up to N model calls. (default: :obj:`None`)
+    """
+
+    model_type: Optional[str] = "gpt-4o-mini"
+    model_platform: Optional[str] = "openai"
+
+    tools_names: Optional[List[str]] = None
+    external_tools: Optional[List[Dict[str, Any]]] = None
+
+    agent_id: str  # Required: explicitly set agent_id to
+    # support future multi-agent and permission control
+
+    system_message: Optional[str] = None
+    message_window_size: Optional[int] = None
+    token_limit: Optional[int] = None
+    output_language: Optional[str] = None
+    max_iteration: Optional[int] = None  # Changed from Optional[bool] = False
+
+
+class StepRequest(BaseModel):
+    r"""Request schema for sending a user message to a ChatAgent.
+
+    Supports plain text input or structured message dictionaries, with an
+    optional response format for controlling output structure.
+
+    Args:
+        input_message (Union[str, Dict[str, Any]]): The user message to send.
+            Can be a plain string or a message dict with role, content, etc.
+        response_format (Optional[str]): Optional format name that maps to a
+            registered response schema. Not currently in use.
+            (default: :obj:`None`)
+    """
+
+    input_message: Union[str, Dict[str, Any]]
+    response_format: Optional[str] = None  # reserved, not used yet
+
+
+class ChatAgentOpenAPIServer:
+    r"""A FastAPI server wrapper for managing ChatAgents via OpenAPI routes.
+
+    This server exposes a versioned REST API for interacting with CAMEL
+    agents, supporting initialization, message passing, memory inspection,
+    and optional tool usage. It supports multi-agent use cases by mapping
+    unique agent IDs to active ChatAgent instances.
+
+    Typical usage includes initializing agents with system prompts and tools,
+    exchanging messages using /step or /astep endpoints, and inspecting agent
+    memory with /history.
+
+    Supports pluggable tool and response format registries for customizing
+    agent behavior or output schemas.
+    """
+
+    def __init__(
+        self,
+        tool_registry: Optional[Dict[str, List[FunctionTool]]] = None,
+        response_format_registry: Optional[Dict[str, Type[BaseModel]]] = None,
+    ):
+        r"""Initializes the OpenAPI server for managing ChatAgents.
+
+        Sets up internal agent storage, tool and response format registries,
+        and prepares versioned API routes.
+
+        Args:
+            tool_registry (Optional[Dict[str, List[FunctionTool]]]): A mapping
+                from tool names to lists of FunctionTool instances available
+                to agents via the "tools_names" field. If not provided, an
+                empty registry is used. (default: :obj:`None`)
+            response_format_registry (Optional[Dict[str, Type[BaseModel]]]):
+                A mapping from format names to Pydantic output schemas for
+                structured response parsing. Used for controlling the format
+                of step results. (default: :obj:`None`)
+        """
+
+        # Initialize FastAPI app and agent
+        self.app = FastAPI(title="CAMEL OpenAPI-compatible Server")
+        self.agents: Dict[str, ChatAgent] = {}
+        self.tool_registry = tool_registry or {}
+        self.response_format_registry = response_format_registry or {}
+        self._setup_routes()
+
+    def _parse_input_message_for_step(
+        self, raw: Union[str, dict]
+    ) -> BaseMessage:
+        r"""Parses raw input into a BaseMessage object.
+
+        Args:
+            raw (str or dict): User input as plain text or dict.
+
+        Returns:
+            BaseMessage: Parsed input message.
+        """
+        if isinstance(raw, str):
+            return BaseMessage.make_user_message(role_name="User", content=raw)
+        elif isinstance(raw, dict):
+            if isinstance(raw.get("role_type"), str):
+                raw["role_type"] = RoleType(raw["role_type"].lower())
+            return BaseMessage(**raw)
+        raise HTTPException(
+            status_code=400, detail="Unsupported input format."
+        )
+
+    def _resolve_response_format_for_step(
+        self, name: Optional[str]
+    ) -> Optional[Type[BaseModel]]:
+        r"""Resolves the response format by name.
+
+        Args:
+            name (str or None): Optional format name.
+
+        Returns:
+            Optional[Type[BaseModel]]: Response schema class.
+        """
+        if name is None:
+            return None
+        if name not in self.response_format_registry:
+            raise HTTPException(
+                status_code=400, detail=f"Unknown response_format: {name}"
+            )
+        return self.response_format_registry[name]
+
+    def _setup_routes(self):
+        r"""Registers OpenAPI endpoints for agent creation and interaction.
+
+        This includes routes for initializing agents (/init), sending
+        messages (/step and /astep), resetting agent memory (/reset), and
+        retrieving conversation history (/history). All routes are added
+        under the /v1/agents namespace.
+        """
+
+        router = APIRouter(prefix="/v1/agents")
+
+        @router.post("/init")
+        def init_agent(request: InitRequest):
+            r"""Initializes a ChatAgent instance with a model,
+            system message, and optional tools.
+
+            Args:
+                request (InitRequest): The agent config including
+                    model, tools, system message, and agent ID.
+
+            Returns:
+                dict: A message with the agent ID and status.
+            """
+
+            agent_id = request.agent_id
+            if agent_id in self.agents:
+                return {
+                    "agent_id": agent_id,
+                    "message": "Agent already exists.",
+                }
+
+            model_type = request.model_type
+            model_platform = request.model_platform
+
+            model = ModelFactory.create(
+                model_platform=model_platform,  # type: ignore[arg-type]
+                model_type=model_type,  # type: ignore[arg-type]
+            )
+
+            # tools lookup
+            tools = []
+            if request.tools_names:
+                for name in request.tools_names:
+                    if name in self.tool_registry:
+                        tools.extend(self.tool_registry[name])
+                    else:
+                        raise HTTPException(
+                            status_code=400,
+                            detail=f"Tool '{name}' " f"not found in registry",
+                        )
+
+            # system message
+            system_message = request.system_message
+
+            agent = ChatAgent(
+                model=model,
+                tools=tools,  # type: ignore[arg-type]
+                external_tools=request.external_tools,  # type: ignore[arg-type]
+                system_message=system_message,
+                message_window_size=request.message_window_size,
+                token_limit=request.token_limit,
+                output_language=request.output_language,
+                max_iteration=request.max_iteration,
+                agent_id=agent_id,
+            )
+
+            self.agents[agent_id] = agent
+            return {"agent_id": agent_id, "message": "Agent initialized."}
+
+        @router.post("/astep/{agent_id}")
+        async def astep_agent(agent_id: str, request: StepRequest):
+            r"""Runs one async step of agent response.
+
+            Args:
+                agent_id (str): The ID of the target agent.
+                request (StepRequest): The input message.
+
+            Returns:
+                dict: The model response in serialized form.
+            """
+
+            if agent_id not in self.agents:
+                raise HTTPException(status_code=404, detail="Agent not found.")
+
+            agent = self.agents[agent_id]
+            input_message = self._parse_input_message_for_step(
+                request.input_message
+            )
+            format_cls = self._resolve_response_format_for_step(
+                request.response_format
+            )
+
+            try:
+                response = await agent.astep(
+                    input_message=input_message, response_format=format_cls
+                )
+                return response.model_dump()
+            except Exception as e:
+                raise HTTPException(
+                    status_code=500,
+                    detail=f"Unexpected error during async step: {e!s}",
+                )
+
+        @router.get("/list_agent_ids")
+        def list_agent_ids():
+            r"""Returns a list of all active agent IDs.
+
+            Returns:
+                dict: A dictionary containing all registered agent IDs.
+            """
+            return {"agent_ids": list(self.agents.keys())}
+
+        @router.post("/delete/{agent_id}")
+        def delete_agent(agent_id: str):
+            r"""Deletes an agent from the server.
+
+            Args:
+                agent_id (str): The ID of the agent to delete.
+
+            Returns:
+                dict: A confirmation message upon successful deletion.
+            """
+            if agent_id not in self.agents:
+                raise HTTPException(status_code=404, detail="Agent not found.")
+
+            del self.agents[agent_id]
+            return {"message": f"Agent {agent_id} deleted."}
+
+        @router.post("/step/{agent_id}")
+        def step_agent(agent_id: str, request: StepRequest):
+            r"""Runs one step of synchronous agent response.
+
+            Args:
+                agent_id (str): The ID of the target agent.
+                request (StepRequest): The input message.
+
+            Returns:
+                dict: The model response in serialized form.
+            """
+            if agent_id not in self.agents:
+                raise HTTPException(status_code=404, detail="Agent not found.")
+
+            agent = self.agents[agent_id]
+            input_message = self._parse_input_message_for_step(
+                request.input_message
+            )
+            format_cls = self._resolve_response_format_for_step(
+                request.response_format
+            )
+            try:
+                response = agent.step(
+                    input_message=input_message, response_format=format_cls
+                )
+                return response.model_dump()
+            except Exception as e:
+                raise HTTPException(
+                    status_code=500,
+                    detail=f"Unexpected error during step: {e!s}",
+                )
+
+        @router.post("/reset/{agent_id}")
+        def reset_agent(agent_id: str):
+            r"""Clears memory for a specific agent.
+
+            Args:
+                agent_id (str): The ID of the agent to reset.
+
+            Returns:
+                dict: A message confirming reset success.
+            """
+            if agent_id not in self.agents:
+                raise HTTPException(status_code=404, detail="Agent not found.")
+            self.agents[agent_id].reset()
+            return {"message": f"Agent {agent_id} reset."}
+
+        @router.get("/history/{agent_id}")
+        def get_agent_chat_history(agent_id: str):
+            r"""Returns the chat history of an agent.
+
+            Args:
+                agent_id (str): The ID of the agent to query.
+
+            Returns:
+                list: The list of conversation messages.
+            """
+            if agent_id not in self.agents:
+                raise HTTPException(
+                    status_code=404, detail=f"Agent {agent_id} not found."
+                )
+            return self.agents[agent_id].chat_history
+
+        # Register all routes to the main FastAPI app
+        self.app.include_router(router)
+
+    def get_app(self) -> FastAPI:
+        r"""Returns the FastAPI app instance.
+
+        Returns:
+            FastAPI: The wrapped application object.
+        """
+        return self.app

camel/societies/workforce/single_agent_worker.py

@@ -43,8 +43,6 @@ class AgentPool:
             (default: :obj:`10`)
         auto_scale (bool): Whether to automatically scale the pool size.
             (default: :obj:`True`)
-        scale_factor (float): Factor by which to scale the pool when needed.
-            (default: :obj:`1.5`)
         idle_timeout (float): Time in seconds after which idle agents are
             removed. (default: :obj:`180.0`)
     """
@@ -55,13 +53,11 @@ class AgentPool:
         initial_size: int = 1,
         max_size: int = 10,
         auto_scale: bool = True,
-        scale_factor: float = 1.5,
         idle_timeout: float = 180.0,  # 3 minutes
     ):
         self.base_agent = base_agent
         self.max_size = max_size
         self.auto_scale = auto_scale
-        self.scale_factor = scale_factor
         self.idle_timeout = idle_timeout
 
         # Pool management
@@ -332,7 +328,7 @@ class SingleAgentWorker(Worker):
         # Store the actual token usage for this specific task
         task.additional_info["token_usage"] = {"total_tokens": total_tokens}
 
-        print(f"======\n{Fore.GREEN}Reply from {self}:{Fore.RESET}")
+        print(f"======\n{Fore.GREEN}Response from {self}:{Fore.RESET}")
 
         try:
             result_dict = json.loads(response.msg.content)

camel/societies/workforce/workforce.py

@@ -395,6 +395,40 @@ class Workforce(BaseNode):
                 "better context continuity during task handoffs."
             )
 
+        # ------------------------------------------------------------------
+        # Helper for propagating pause control to externally supplied agents
+        # ------------------------------------------------------------------
+
+    def _attach_pause_event_to_agent(self, agent: ChatAgent) -> None:
+        r"""Ensure the given ChatAgent shares this workforce's pause_event.
+
+        If the agent already has a different pause_event we overwrite it and
+        emit a debug log (it is unlikely an agent needs multiple independent
+        pause controls once managed by this workforce)."""
+        try:
+            existing_pause_event = getattr(agent, "pause_event", None)
+            if existing_pause_event is not self._pause_event:
+                if existing_pause_event is not None:
+                    logger.debug(
+                        f"Overriding pause_event for agent {agent.agent_id} "
+                        f"(had different pause_event: "
+                        f"{id(existing_pause_event)} "
+                        f"-> {id(self._pause_event)})"
+                    )
+                agent.pause_event = self._pause_event
+        except AttributeError:
+            # Should not happen, but guard against unexpected objects
+            logger.warning(
+                f"Cannot attach pause_event to object {type(agent)} - "
+                f"missing pause_event attribute"
+            )
+
+    def _ensure_pause_event_in_kwargs(self, kwargs: Optional[Dict]) -> Dict:
+        r"""Insert pause_event into kwargs dict for ChatAgent construction."""
+        new_kwargs = dict(kwargs) if kwargs else {}
+        new_kwargs.setdefault("pause_event", self._pause_event)
+        return new_kwargs
+
     def __repr__(self):
         return (
             f"Workforce {self.node_id} ({self.description}) - "
@@ -1138,6 +1172,9 @@ class Workforce(BaseNode):
         Returns:
             Workforce: The workforce node itself.
         """
+        # Ensure the worker agent shares this workforce's pause control
+        self._attach_pause_event_to_agent(worker)
+
         worker_node = SingleAgentWorker(
             description=description,
             worker=worker,
@@ -1184,6 +1221,18 @@ class Workforce(BaseNode):
         Returns:
             Workforce: The workforce node itself.
         """
+        # Ensure provided kwargs carry pause_event so that internally created
+        # ChatAgents (assistant/user/summarizer) inherit it.
+        assistant_agent_kwargs = self._ensure_pause_event_in_kwargs(
+            assistant_agent_kwargs
+        )
+        user_agent_kwargs = self._ensure_pause_event_in_kwargs(
+            user_agent_kwargs
+        )
+        summarize_agent_kwargs = self._ensure_pause_event_in_kwargs(
+            summarize_agent_kwargs
+        )
+
         worker_node = RolePlayingWorker(
             description=description,
             assistant_role_name=assistant_role_name,
@@ -1212,6 +1261,9 @@ class Workforce(BaseNode):
         Returns:
             Workforce: The workforce node itself.
         """
+        # Align child workforce's pause_event with this one for unified
+        # control of worker agents only.
+        workforce._pause_event = self._pause_event
         self._children.append(workforce)
         return self
 
@@ -1245,14 +1297,17 @@ class Workforce(BaseNode):
         # Handle asyncio.Event in a thread-safe way
         if self._loop and not self._loop.is_closed():
             # If we have a loop, use it to set the event safely
-            asyncio.run_coroutine_threadsafe(
-                self._async_reset(), self._loop
-            ).result()
-        else:
             try:
-                self._reset_task = asyncio.create_task(self._async_reset())
-            except RuntimeError:
-                asyncio.run(self._async_reset())
+                asyncio.run_coroutine_threadsafe(
+                    self._async_reset(), self._loop
+                ).result()
+            except RuntimeError as e:
+                logger.warning(f"Failed to reset via existing loop: {e}")
+                # Fallback to direct event manipulation
+                self._pause_event.set()
+        else:
+            # No active loop, directly set the event
+            self._pause_event.set()
 
         if hasattr(self, 'metrics_logger') and self.metrics_logger is not None:
             self.metrics_logger.reset_task_data()
@@ -1656,7 +1711,12 @@ class Workforce(BaseNode):
                 model_config_dict={"temperature": 0},
             )
 
-            return ChatAgent(worker_sys_msg, model=model, tools=function_list)  # type: ignore[arg-type]
+            return ChatAgent(
+                worker_sys_msg,
+                model=model,
+                tools=function_list,  # type: ignore[arg-type]
+                pause_event=self._pause_event,
+            )
 
     async def _get_returned_task(self) -> Optional[Task]:
         r"""Get the task that's published by this node and just get returned

camel/tasks/task.py

@@ -56,7 +56,7 @@ class TaskValidationMode(Enum):
 def validate_task_content(
     content: str,
     task_id: str = "unknown",
-    min_length: int = 5,
+    min_length: int = 1,
     mode: TaskValidationMode = TaskValidationMode.INPUT,
     check_failure_patterns: bool = True,
 ) -> bool:
@@ -69,7 +69,7 @@ def validate_task_content(
         task_id (str): Task ID for logging purposes.
             (default: :obj:`"unknown"`)
         min_length (int): Minimum content length after stripping whitespace.
-            (default: :obj:`5`)
+            (default: :obj:`1`)
         mode (TaskValidationMode): Validation mode - INPUT for task content,
             OUTPUT for task results. (default: :obj:`TaskValidationMode.INPUT`)
         check_failure_patterns (bool): Whether to check for failure indicators

camel/toolkits/__init__.py

@@ -77,7 +77,7 @@ from .aci_toolkit import ACIToolkit
 from .playwright_mcp_toolkit import PlaywrightMCPToolkit
 from .wolfram_alpha_toolkit import WolframAlphaToolkit
 from .task_planning_toolkit import TaskPlanningToolkit
-from .non_visual_browser_toolkit import BrowserNonVisualToolkit
+from .hybrid_browser_toolkit import HybridBrowserToolkit
 from .edgeone_pages_mcp_toolkit import EdgeOnePagesMCPToolkit
 from .google_drive_mcp_toolkit import GoogleDriveMCPToolkit
 from .craw4ai_toolkit import Crawl4AIToolkit
@@ -146,7 +146,7 @@ __all__ = [
     'WolframAlphaToolkit',
     'BohriumToolkit',
     'TaskPlanningToolkit',
-    'BrowserNonVisualToolkit',
+    'HybridBrowserToolkit',
     'EdgeOnePagesMCPToolkit',
     'GoogleDriveMCPToolkit',
     'Crawl4AIToolkit',

camel/toolkits/craw4ai_toolkit.py

@@ -31,6 +31,16 @@ class Crawl4AIToolkit(BaseToolkit):
         timeout: Optional[float] = None,
     ):
         super().__init__(timeout=timeout)
+        self._client = None
+
+    async def _get_client(self):
+        r"""Get or create the AsyncWebCrawler client."""
+        if self._client is None:
+            from crawl4ai import AsyncWebCrawler
+
+            self._client = AsyncWebCrawler()
+            await self._client.__aenter__()
+        return self._client
 
     async def scrape(self, url: str) -> str:
         r"""Scrapes a webpage and returns its content.
@@ -47,19 +57,29 @@ class Crawl4AIToolkit(BaseToolkit):
             str: The scraped content of the webpage as a string. If the
                 scraping fails, it will return an error message.
         """
-        from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
+        from crawl4ai import CrawlerRunConfig
 
         try:
-            async with AsyncWebCrawler() as client:
-                config = CrawlerRunConfig(
-                    only_text=True,
-                )
-                content = await client.arun(url, crawler_config=config)
-                return str(content.markdown) if content.markdown else ""
+            client = await self._get_client()
+            config = CrawlerRunConfig(
+                only_text=True,
+            )
+            content = await client.arun(url, crawler_config=config)
+            return str(content.markdown) if content.markdown else ""
         except Exception as e:
             logger.error(f"Error scraping {url}: {e}")
             return f"Error scraping {url}: {e}"
 
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit - cleanup the client."""
+        if self._client is not None:
+            await self._client.__aexit__(exc_type, exc_val, exc_tb)
+            self._client = None
+
     def get_tools(self) -> List[FunctionTool]:
         r"""Returns a list of FunctionTool objects representing the
         functions in the toolkit.