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

camel/toolkits/file_write_toolkit.py

@@ -146,23 +146,25 @@ class FileWriteToolkit(BaseToolkit):
         document.save(str(file_path))
         logger.debug(f"Wrote DOCX to {file_path} with default formatting")
 
-    @dependencies_required('pylatex', 'fpdf')
+    @dependencies_required('pylatex', 'pymupdf')
     def _write_pdf_file(
-        self, file_path: Path, content: str, use_latex: bool = False
+        self,
+        file_path: Path,
+        title: str,
+        content: str,
+        use_latex: bool = False,
     ) -> None:
         r"""Write text content to a PDF file with default formatting.
 
         Args:
             file_path (Path): The target file path.
+            title (str): The title of the document.
             content (str): The text content to write.
             use_latex (bool): Whether to use LaTeX for rendering. (requires
-                LaTeX toolchain). If False, uses FPDF for simpler PDF
+                LaTeX toolchain). If False, uses PyMuPDF for simpler PDF
                 generation. (default: :obj:`False`)
-
-        Raises:
-            RuntimeError: If the 'pylatex' or 'fpdf' library is not installed
-                when use_latex=True.
         """
+        # TODO: table generation need to be improved
         if use_latex:
             from pylatex import (
                 Command,
@@ -213,30 +215,105 @@ class FileWriteToolkit(BaseToolkit):
 
             logger.info(f"Wrote PDF (with LaTeX) to {file_path}")
         else:
-            from fpdf import FPDF
-
-            # Use default formatting values
-            font_family = 'Arial'
-            font_size = 12
-            font_style = ''
-            line_height = 10
-            margin = 10
-
-            pdf = FPDF()
-            pdf.set_margins(margin, margin, margin)
-
-            pdf.add_page()
-            pdf.set_font(font_family, style=font_style, size=font_size)
-
-            # Split content into paragraphs and add them
-            for para in content.split('\n'):
-                if para.strip():  # Skip empty paragraphs
-                    pdf.multi_cell(0, line_height, para)
+            import pymupdf
+
+            # Create a new PDF document
+            doc = pymupdf.open()
+
+            # Add a page
+            page = doc.new_page()
+
+            # Process the content
+            lines = content.strip().split('\n')
+            document_title = title
+
+            # Create a TextWriter for writing text to the page
+            text_writer = pymupdf.TextWriter(page.rect)
+
+            # Define fonts
+            normal_font = pymupdf.Font(
+                "helv"
+            )  # Standard font with multilingual support
+            bold_font = pymupdf.Font("helv")
+
+            # Start position for text
+            y_pos = 50
+            x_pos = 50
+
+            # Add title
+            text_writer.fill_textbox(
+                pymupdf.Rect(
+                    x_pos, y_pos, page.rect.width - x_pos, y_pos + 30
+                ),
+                document_title,
+                fontsize=16,
+            )
+            y_pos += 40
+
+            # Process content
+            for line in lines:
+                stripped_line = line.strip()
+
+                # Skip empty lines but add some space
+                if not stripped_line:
+                    y_pos += 10
+                    continue
+
+                # Handle headers
+                if stripped_line.startswith('## '):
+                    text_writer.fill_textbox(
+                        pymupdf.Rect(
+                            x_pos, y_pos, page.rect.width - x_pos, y_pos + 20
+                        ),
+                        stripped_line[3:].strip(),
+                        font=bold_font,
+                        fontsize=14,
+                    )
+                    y_pos += 25
+                elif stripped_line.startswith('# '):
+                    text_writer.fill_textbox(
+                        pymupdf.Rect(
+                            x_pos, y_pos, page.rect.width - x_pos, y_pos + 25
+                        ),
+                        stripped_line[2:].strip(),
+                        font=bold_font,
+                        fontsize=16,
+                    )
+                    y_pos += 30
+                # Handle horizontal rule
+                elif stripped_line == '---':
+                    page.draw_line(
+                        pymupdf.Point(x_pos, y_pos + 5),
+                        pymupdf.Point(page.rect.width - x_pos, y_pos + 5),
+                    )
+                    y_pos += 15
+                # Regular text
                 else:
-                    pdf.ln(line_height)  # Add empty line
-
-            pdf.output(str(file_path))
-            logger.debug(f"Wrote PDF to {file_path} with custom formatting")
+                    # Check if we need a new page
+                    if y_pos > page.rect.height - 50:
+                        text_writer.write_text(page)
+                        page = doc.new_page()
+                        text_writer = pymupdf.TextWriter(page.rect)
+                        y_pos = 50
+
+                    # Add text to the current page
+                    text_writer.fill_textbox(
+                        pymupdf.Rect(
+                            x_pos, y_pos, page.rect.width - x_pos, y_pos + 15
+                        ),
+                        stripped_line,
+                        font=normal_font,
+                    )
+                    y_pos += 15
+
+            # Write the accumulated text to the last page
+            text_writer.write_text(page)
+
+            # Save the PDF
+            doc.save(str(file_path))
+            doc.close()
+
+            logger.debug(f"Wrote PDF to {file_path} with PyMuPDF formatting")
 
     def _write_csv_file(
         self,
@@ -338,6 +415,7 @@ class FileWriteToolkit(BaseToolkit):
 
     def write_to_file(
         self,
+        title: str,
         content: Union[str, List[List[str]]],
         filename: str,
         encoding: Optional[str] = None,
@@ -351,6 +429,7 @@ class FileWriteToolkit(BaseToolkit):
         and HTML (.html, .htm).
 
         Args:
+            title (str): The title of the document.
             content (Union[str, List[List[str]]]): The content to write to the
                 file. Content format varies by file type:
                 - Text formats (txt, md, html, yaml): string
@@ -388,7 +467,7 @@ class FileWriteToolkit(BaseToolkit):
                 self._write_docx_file(file_path, str(content))
             elif extension == ".pdf":
                 self._write_pdf_file(
-                    file_path, str(content), use_latex=use_latex
+                    file_path, title, str(content), use_latex=use_latex
                 )
             elif extension == ".csv":
                 self._write_csv_file(

camel/toolkits/human_toolkit.py

@@ -22,7 +22,12 @@ logger = logging.getLogger(__name__)
 
 
 class HumanToolkit(BaseToolkit):
-    r"""A class representing a toolkit for human interaction."""
+    r"""A class representing a toolkit for human interaction.
+
+    Note:
+        This toolkit should be called to send a tidy message to the user to
+        keep them informed.
+    """
 
     def ask_human_via_console(self, question: str) -> str:
         r"""Use this tool to ask a question to the user when you are stuck,
@@ -48,21 +53,21 @@ class HumanToolkit(BaseToolkit):
         return reply
 
     def send_message_to_user(self, message: str) -> None:
-        r"""Use this tool to send a message to the user to keep them
-        informed about your progress, decisions, or actions.
-        This is a one-way communication channel from you to the user and does
-        not require a response. You should use it to:
-        - Announce what you are about to do
-        (e.g., "I will now search for papers on GUI Agents.")
-        - Report the result of an action
-        (e.g., "I have found 15 relevant papers.")
-        - State a decision
-        (e.g., "I will now analyze the top 10 papers.")
-        - Inform the user about your current state if you are performing a
-        task.
+        r"""Use this tool to send a tidy message to the user in one short
+        sentence.
+
+        This one-way tool keeps the user informed about your progress,
+        decisions, or actions. It does not require a response.
+        You should use it to:
+        - Announce what you are about to do (e.g., "I will now search for
+          papers on GUI Agents.").
+        - Report the result of an action (e.g., "I have found 15 relevant
+          papers.").
+        - State a decision (e.g., "I will now analyze the top 10 papers.").
+        - Give a status update during a long-running task.
 
         Args:
-            message (str): The message to send to the user.
+            message (str): The tidy and informative message for the user.
         """
         print(f"\nAgent Message:\n{message}")
         logger.info(f"\nAgent Message:\n{message}")

camel/toolkits/{non_visual_browser_toolkit → hybrid_browser_toolkit}/__init__.py

@@ -11,8 +11,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
-from .browser_non_visual_toolkit import BrowserNonVisualToolkit
+from .hybrid_browser_toolkit import HybridBrowserToolkit
 
 __all__ = [
-    "BrowserNonVisualToolkit",
+    "HybridBrowserToolkit",
 ]

camel/toolkits/{non_visual_browser_toolkit → hybrid_browser_toolkit}/actions.py

@@ -24,6 +24,7 @@ class ActionExecutor:
     # Configuration constants
     DEFAULT_TIMEOUT = 5000  # 5 seconds
     SHORT_TIMEOUT = 2000  # 2 seconds
+    MAX_SCROLL_AMOUNT = 5000  # Maximum scroll distance in pixels
 
     def __init__(self, page: "Page"):
         self.page = page
@@ -32,6 +33,7 @@ class ActionExecutor:
     # Public helpers
     # ------------------------------------------------------------------
     async def execute(self, action: Dict[str, Any]) -> str:
+        r"""Execute an action and return the result description."""
         if not action:
             return "No action to execute"
 
@@ -64,32 +66,46 @@ class ActionExecutor:
     # Internal handlers
     # ------------------------------------------------------------------
     async def _click(self, action: Dict[str, Any]) -> str:
+        r"""Handle click actions with multiple fallback strategies."""
         ref = action.get("ref")
         text = action.get("text")
         selector = action.get("selector")
         if not (ref or text or selector):
             return "Error: click requires ref/text/selector"
 
+        # Build strategies in priority order: ref > selector > text
         strategies = []
+        if ref:
+            strategies.append(f"[aria-ref='{ref}']")
         if selector:
             strategies.append(selector)
         if text:
             strategies.append(f'text="{text}"')
-        if ref:
-            strategies.append(f"[aria-ref='{ref}']")
 
+        # Strategy 1: Try Playwright force click for each selector
         for sel in strategies:
             try:
                 if await self.page.locator(sel).count() > 0:
                     await self.page.click(
-                        sel, timeout=self.SHORT_TIMEOUT, force=True
+                        sel, timeout=self.DEFAULT_TIMEOUT, force=True
                     )
-                    return f"Clicked element via {sel}"
+                    return f"Clicked element via force: {sel}"
             except Exception:
-                pass
-        return "Error: Could not click element"
+                continue
+
+        # Strategy 2: Try JavaScript click as fallback
+        for sel in strategies:
+            try:
+                await self.page.locator(sel).first.evaluate("el => el.click()")
+                await asyncio.sleep(0.1)  # Brief wait for effects
+                return f"Clicked element via JS: {sel}"
+            except Exception:
+                continue
+
+        return "Error: All click strategies failed"
 
     async def _type(self, action: Dict[str, Any]) -> str:
+        r"""Handle typing text into input fields."""
         ref = action.get("ref")
         selector = action.get("selector")
         text = action.get("text", "")
@@ -103,6 +119,7 @@ class ActionExecutor:
             return f"Type failed: {exc}"
 
     async def _select(self, action: Dict[str, Any]) -> str:
+        r"""Handle selecting options from dropdowns."""
         ref = action.get("ref")
         selector = action.get("selector")
         value = action.get("value", "")
@@ -118,8 +135,9 @@ class ActionExecutor:
             return f"Select failed: {exc}"
 
     async def _wait(self, action: Dict[str, Any]) -> str:
+        r"""Handle wait actions."""
         if "timeout" in action:
-            ms = action["timeout"]
+            ms = int(action["timeout"])
             await asyncio.sleep(ms / 1000)
             return f"Waited {ms}ms"
         if "selector" in action:
@@ -131,6 +149,7 @@ class ActionExecutor:
         return "Error: wait requires timeout/selector"
 
     async def _extract(self, action: Dict[str, Any]) -> str:
+        r"""Handle text extraction from elements."""
         ref = action.get("ref")
         if not ref:
             return "Error: extract requires ref"
@@ -140,6 +159,7 @@ class ActionExecutor:
         return f"Extracted: {txt[:100] if txt else 'None'}"
 
     async def _scroll(self, action: Dict[str, Any]) -> str:
+        r"""Handle page scrolling with safe parameter validation."""
         direction = action.get("direction", "down")
         amount = action.get("amount", 300)
 
@@ -151,18 +171,22 @@ class ActionExecutor:
             # Safely convert amount to integer and clamp to reasonable range
             amount_int = int(amount)
             amount_int = max(
-                -5000, min(5000, amount_int)
-            )  # Clamp between -5000 and 5000
+                -self.MAX_SCROLL_AMOUNT,
+                min(self.MAX_SCROLL_AMOUNT, amount_int),
+            )  # Clamp to MAX_SCROLL_AMOUNT range
         except (ValueError, TypeError):
             return "Error: amount must be a valid number"
 
         # Use safe evaluation with bound parameters
         scroll_offset = amount_int if direction == "down" else -amount_int
-        await self.page.evaluate(f"window.scrollBy(0, {scroll_offset})")
+        await self.page.evaluate(
+            "offset => window.scrollBy(0, offset)", scroll_offset
+        )
         await asyncio.sleep(0.5)
         return f"Scrolled {direction} by {abs(amount_int)}px"
 
     async def _enter(self, action: Dict[str, Any]) -> str:
+        r"""Handle Enter key press actions."""
         ref = action.get("ref")
         selector = action.get("selector")
         if ref:
@@ -175,16 +199,28 @@ class ActionExecutor:
 
     # utilities
     async def _wait_dom_stable(self) -> None:
+        r"""Wait for DOM to become stable before executing actions."""
         try:
+            # Wait for basic DOM content loading
             await self.page.wait_for_load_state(
                 'domcontentloaded', timeout=self.SHORT_TIMEOUT
             )
+
+            # Try to wait for network idle briefly
+            try:
+                await self.page.wait_for_load_state(
+                    'networkidle', timeout=self.SHORT_TIMEOUT
+                )
+            except Exception:
+                pass  # Network idle is optional
+
         except Exception:
-            pass
+            pass  # Don't fail if wait times out
 
     # static helpers
     @staticmethod
     def should_update_snapshot(action: Dict[str, Any]) -> bool:
+        r"""Determine if an action requires a snapshot update."""
         change_types = {
             "click",
             "type",

camel/toolkits/{non_visual_browser_toolkit → hybrid_browser_toolkit}/agent.py

@@ -12,24 +12,24 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import json
-import logging
 import re
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
+from camel.logger import get_logger
 from camel.models import BaseModelBackend, ModelFactory
 from camel.types import ModelPlatformType, ModelType
 
 from .actions import ActionExecutor
-from .nv_browser_session import NVBrowserSession
+from .browser_session import NVBrowserSession
 
 if TYPE_CHECKING:
     from camel.agents import ChatAgent
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class PlaywrightLLMAgent:
-    """High-level orchestration: snapshot ↔ LLM ↔ action executor."""
+    r"""High-level orchestration: snapshot ↔ LLM ↔ action executor."""
 
     # System prompt as class constant to avoid recreation
     SYSTEM_PROMPT = """
@@ -90,8 +90,8 @@ what was accomplished
         self.action_history: List[Dict[str, Any]] = []
         if model_backend is None:
             model_backend = ModelFactory.create(
-                model_platform=ModelPlatformType.OPENAI,
-                model_type=ModelType.GPT_4O_MINI,
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
                 model_config_dict={"temperature": 0, "top_p": 1},
             )
         self.model_backend = model_backend
@@ -99,16 +99,19 @@ what was accomplished
         self._chat_agent: Optional[ChatAgent] = None
 
     async def navigate(self, url: str) -> str:
+        r"""Navigate to a URL and return the snapshot."""
         try:
             # NVBrowserSession handles waits internally
             logger.debug("Navigated to URL: %s", url)
             await self._session.visit(url)
             return await self._session.get_snapshot(force_refresh=True)
         except Exception as exc:
-            return f"Error: could not navigate - {exc}"
+            error_msg = f"Error: could not navigate to {url} - {exc}"
+            logger.error(error_msg)
+            return error_msg
 
     def _get_chat_agent(self) -> "ChatAgent":
-        """Get or create the ChatAgent instance."""
+        r"""Get or create the ChatAgent instance."""
         from camel.agents import ChatAgent
 
         if self._chat_agent is None:
@@ -165,12 +168,16 @@ what was accomplished
         logger.warning(
             "Could not parse JSON from LLM response: %s", content[:200]
         )
+        return self._get_fallback_response("Parsing error")
+
+    def _get_fallback_response(self, error_msg: str) -> Dict[str, Any]:
+        r"""Generate a fallback response structure."""
         return {
-            "plan": ["Could not parse response"],
+            "plan": [f"Could not parse response: {error_msg}"],
             "action": {
                 "type": "finish",
                 "ref": None,
-                "summary": "Parsing error",
+                "summary": f"Parsing error: {error_msg}",
             },
         }
 
@@ -181,7 +188,7 @@ what was accomplished
         is_initial: bool,
         history: Optional[List[Dict[str, Any]]] = None,
     ) -> Dict[str, Any]:
-        """Call the LLM (via CAMEL ChatAgent) to get plan & next action."""
+        r"""Call the LLM (via CAMEL ChatAgent) to get plan & next action."""
         # Build user message
         if is_initial:
             user_content = f"Snapshot:\n{snapshot}\n\nTask: {prompt}"
@@ -208,6 +215,7 @@ what was accomplished
         return self._safe_parse_json(content)
 
     async def process_command(self, prompt: str, max_steps: int = 15):
+        r"""Process a command using LLM-guided browser automation."""
         # initial full snapshot
         full_snapshot = await self._session.get_snapshot()
         assert self._session.snapshot is not None
@@ -270,9 +278,11 @@ what was accomplished
         logger.info("Process completed with %d steps", steps)
 
     async def _run_action(self, action: Dict[str, Any]) -> str:
+        r"""Execute a single action and return the result."""
         if action.get("type") == "navigate":
             return await self.navigate(action.get("url", ""))
         return await self._session.exec_action(action)
 
     async def close(self):
+        r"""Clean up browser session and resources."""
         await self._session.close()

camel/toolkits/{non_visual_browser_toolkit/nv_browser_session.py → hybrid_browser_toolkit/browser_session.py}

@@ -57,13 +57,12 @@ class NVBrowserSession:
 
     def __new__(
         cls, *, headless: bool = True, user_data_dir: Optional[str] = None
-    ):
-        loop = asyncio.get_running_loop()
-        if loop not in cls._sessions:
-            instance = super().__new__(cls)
-            instance._initialized = False
-            cls._sessions[loop] = instance
-        return cls._sessions[loop]
+    ) -> "NVBrowserSession":
+        # Defer event loop lookup until we actually need it
+        # This allows creation outside of async context
+        instance = super().__new__(cls)
+        instance._initialized = False
+        return instance
 
     def __init__(
         self, *, headless: bool = True, user_data_dir: Optional[str] = None
@@ -90,6 +89,47 @@ class NVBrowserSession:
     # Browser lifecycle helpers
     # ------------------------------------------------------------------
     async def ensure_browser(self) -> None:
+        r"""Ensure browser is ready, implementing singleton pattern per event
+        loop.
+        """
+        # Check if we need to reuse or create a session for this event loop
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError as e:
+            raise RuntimeError(
+                "ensure_browser() must be called from within an async context"
+            ) from e
+
+        # Check if there's already a session for this loop
+        if loop in self._sessions and self._sessions[loop] is not self:
+            # Copy the existing session's browser resources
+            existing = self._sessions[loop]
+            # Wait for existing session to be fully initialized
+            async with existing._ensure_lock:
+                if (
+                    existing._initialized
+                    and existing._page is not None
+                    and existing._playwright is not None
+                ):
+                    try:
+                        # Verify the page is still responsive
+                        await existing._page.title()
+                        self._playwright = existing._playwright
+                        self._browser = existing._browser
+                        self._context = existing._context
+                        self._page = existing._page
+                        self.snapshot = existing.snapshot
+                        self.executor = existing.executor
+                        self._initialized = True
+                        return
+                    except Exception:
+                        # Existing session is broken, continue with new
+                        # initialization
+                        pass
+
+        # Register this instance for the current loop
+        self._sessions[loop] = self
+
         # Serialise initialisation to avoid race conditions where multiple
         # concurrent coroutine calls create multiple browser instances for
         # the same NVBrowserSession.
@@ -98,6 +138,7 @@ class NVBrowserSession:
 
     # Moved original logic to helper
     async def _ensure_browser_inner(self) -> None:
+        r"""Internal browser initialization logic."""
         from playwright.async_api import async_playwright
 
         if self._page is not None:
@@ -144,11 +185,23 @@ class NVBrowserSession:
         r"""Close all browser resources, ensuring cleanup even if some
         operations fail.
         """
-        # The close method will now only close the *current* event-loop's
-        # browser instance.  Use `close_all_sessions` for a full cleanup.
+        # Remove this session from the sessions dict and close resources
+        try:
+            loop = asyncio.get_running_loop()
+            if loop in self._sessions and self._sessions[loop] is self:
+                del self._sessions[loop]
+        except RuntimeError:
+            pass  # No running loop, that's okay
+
+        # Clean up any stale loop references
+        stale_loops = [loop for loop in self._sessions if loop.is_closed()]
+        for loop in stale_loops:
+            del self._sessions[loop]
+
         await self._close_session()
 
     async def _close_session(self) -> None:
+        r"""Internal session cleanup with comprehensive error handling."""
         errors: list[str] = []
 
         # Close context first (which closes pages)
@@ -204,6 +257,7 @@ class NVBrowserSession:
     # Convenience wrappers around common actions
     # ------------------------------------------------------------------
     async def visit(self, url: str) -> str:
+        r"""Navigate to a URL with proper error handling."""
         await self.ensure_browser()
         assert self._page is not None
 
@@ -233,7 +287,7 @@ class NVBrowserSession:
             force_refresh=force_refresh, diff_only=diff_only
         )
 
-    async def exec_action(self, action: dict[str, Any]) -> str:
+    async def exec_action(self, action: Dict[str, Any]) -> str:
         await self.ensure_browser()
         assert self.executor is not None
         return await self.executor.execute(action)