camel-ai 0.2.75a6__py3-none-any.whl → 0.2.76a0__py3-none-any.whl

camel/toolkits/code_execution.py

@@ -18,6 +18,7 @@ from camel.interpreters import (
     E2BInterpreter,
     InternalPythonInterpreter,
     JupyterKernelInterpreter,
+    MicrosandboxInterpreter,
     SubprocessInterpreter,
 )
 from camel.logger import get_logger
@@ -43,18 +44,31 @@ class CodeExecutionToolkit(BaseToolkit):
             (default: :obj:`None`)
         require_confirm (bool): Whether to require confirmation before
             executing code. (default: :obj:`False`)
+        timeout (Optional[float]): General timeout for toolkit operations.
+            (default: :obj:`None`)
+        microsandbox_config (Optional[dict]): Configuration for microsandbox
+            interpreter. Available keys: 'server_url', 'api_key',
+            'namespace', 'sandbox_name', 'timeout'.
+            If None, uses default configuration. (default: :obj:`None`)
     """
 
     def __init__(
         self,
         sandbox: Literal[
-            "internal_python", "jupyter", "docker", "subprocess", "e2b"
+            "internal_python",
+            "jupyter",
+            "docker",
+            "subprocess",
+            "e2b",
+            "microsandbox",
         ] = "subprocess",
         verbose: bool = False,
         unsafe_mode: bool = False,
         import_white_list: Optional[List[str]] = None,
         require_confirm: bool = False,
         timeout: Optional[float] = None,
+        # Microsandbox configuration dictionary
+        microsandbox_config: Optional[dict] = None,
     ) -> None:
         super().__init__(timeout=timeout)
         self.verbose = verbose
@@ -68,6 +82,7 @@ class CodeExecutionToolkit(BaseToolkit):
             DockerInterpreter,
             SubprocessInterpreter,
             E2BInterpreter,
+            MicrosandboxInterpreter,
         ]
 
         if sandbox == "internal_python":
@@ -95,6 +110,18 @@ class CodeExecutionToolkit(BaseToolkit):
             )
         elif sandbox == "e2b":
             self.interpreter = E2BInterpreter(require_confirm=require_confirm)
+        elif sandbox == "microsandbox":
+            # Extract parameters with proper types for microsandbox
+            config = microsandbox_config or {}
+
+            self.interpreter = MicrosandboxInterpreter(
+                require_confirm=require_confirm,
+                server_url=config.get("server_url"),
+                api_key=config.get("api_key"),
+                namespace=config.get("namespace", "default"),
+                sandbox_name=config.get("sandbox_name"),
+                timeout=config.get("timeout", 30),
+            )
         else:
             raise RuntimeError(
                 f"The sandbox type `{sandbox}` is not supported."

camel/toolkits/function_tool.py

@@ -156,7 +156,12 @@ def get_openai_tool_schema(func: Callable) -> Dict[str, Any]:
         if (name := param.arg_name) in parameters_dict["properties"] and (
             description := param.description
         ):
-            parameters_dict["properties"][name]["description"] = description
+            # OpenAI does not allow descriptions on properties that use $ref.
+            # To avoid schema errors, we only add the description if "$ref" is
+            # not present.
+            prop = parameters_dict["properties"][name]
+            if "$ref" not in prop:
+                prop["description"] = description
 
     short_description = docstring.short_description or ""
     long_description = docstring.long_description or ""

camel/toolkits/hybrid_browser_toolkit/config_loader.py

@@ -44,6 +44,9 @@ class BrowserConfig:
     connect_over_cdp: bool = False
     cdp_url: Optional[str] = None
 
+    # Full visual mode configuration
+    full_visual_mode: bool = False
+
 
 @dataclass
 class ToolkitConfig:
@@ -51,6 +54,7 @@ class ToolkitConfig:
 
     cache_dir: str = "tmp/"
     browser_log_to_file: bool = False
+    log_dir: Optional[str] = None
     session_id: Optional[str] = None
     enabled_tools: Optional[list] = None
 
@@ -116,6 +120,8 @@ class ConfigLoader:
                 toolkit_kwargs["session_id"] = value
             elif key == "enabledTools":
                 toolkit_kwargs["enabled_tools"] = value
+            elif key == "fullVisualMode":
+                browser_kwargs["full_visual_mode"] = value
 
         browser_config = BrowserConfig(**browser_kwargs)
         toolkit_config = ToolkitConfig(**toolkit_kwargs)
@@ -142,10 +148,12 @@ class ConfigLoader:
             "screenshotTimeout": self.browser_config.screenshot_timeout,
             "pageStabilityTimeout": self.browser_config.page_stability_timeout,
             "browser_log_to_file": self.toolkit_config.browser_log_to_file,
+            "log_dir": self.toolkit_config.log_dir,
             "session_id": self.toolkit_config.session_id,
             "viewport_limit": self.browser_config.viewport_limit,
             "connectOverCdp": self.browser_config.connect_over_cdp,
             "cdpUrl": self.browser_config.cdp_url,
+            "fullVisualMode": self.browser_config.full_visual_mode,
         }
 
     def get_timeout_config(self) -> Dict[str, Optional[int]]:

camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit.py

@@ -38,6 +38,7 @@ class HybridBrowserToolkit(BaseToolkit):
         cache_dir: str = "tmp/",
         enabled_tools: Optional[List[str]] = None,
         browser_log_to_file: bool = False,
+        log_dir: Optional[str] = None,
         session_id: Optional[str] = None,
         default_start_url: str = "https://google.com/",
         default_timeout: Optional[int] = None,
@@ -50,6 +51,7 @@ class HybridBrowserToolkit(BaseToolkit):
         viewport_limit: bool = False,
         connect_over_cdp: bool = False,
         cdp_url: Optional[str] = None,
+        full_visual_mode: bool = False,
         **kwargs: Any,
     ) -> Any:
         r"""Create a HybridBrowserToolkit instance with the specified mode.
@@ -72,6 +74,8 @@ class HybridBrowserToolkit(BaseToolkit):
                 Defaults to None.
             browser_log_to_file (bool): Whether to log browser actions to
                 file. Defaults to False.
+            log_dir (Optional[str]): Custom directory path for log files.
+                If None, defaults to "browser_log". Defaults to None.
             session_id (Optional[str]): Session identifier. Defaults to None.
             default_start_url (str): Default URL to start with. Defaults
                 to "https://google.com/".
@@ -98,6 +102,11 @@ class HybridBrowserToolkit(BaseToolkit):
             cdp_url (Optional[str]): WebSocket endpoint URL for CDP
                 connection. Required when connect_over_cdp is True.
                 Defaults to None. (Only supported in TypeScript mode)
+            full_visual_mode (bool): When True, browser actions like click,
+                browser_open, visit_page, etc. will return 'full visual mode'
+                as snapshot instead of actual page content. The
+                browser_get_page_snapshot method will still return the actual
+                snapshot. Defaults to False.
             **kwargs: Additional keyword arguments passed to the
                 implementation.
 
@@ -117,6 +126,7 @@ class HybridBrowserToolkit(BaseToolkit):
                 cache_dir=cache_dir,
                 enabled_tools=enabled_tools,
                 browser_log_to_file=browser_log_to_file,
+                log_dir=log_dir,
                 session_id=session_id,
                 default_start_url=default_start_url,
                 default_timeout=default_timeout,
@@ -129,6 +139,7 @@ class HybridBrowserToolkit(BaseToolkit):
                 viewport_limit=viewport_limit,
                 connect_over_cdp=connect_over_cdp,
                 cdp_url=cdp_url,
+                full_visual_mode=full_visual_mode,
                 **kwargs,
             )
         elif mode == "python":
@@ -160,6 +171,7 @@ class HybridBrowserToolkit(BaseToolkit):
                 cache_dir=cache_dir,
                 enabled_tools=enabled_tools,
                 browser_log_to_file=browser_log_to_file,
+                log_dir=log_dir,
                 session_id=session_id,
                 default_start_url=default_start_url,
                 default_timeout=default_timeout,

camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit_ts.py

@@ -86,6 +86,7 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
         cache_dir: str = "tmp/",
         enabled_tools: Optional[List[str]] = None,
         browser_log_to_file: bool = False,
+        log_dir: Optional[str] = None,
         session_id: Optional[str] = None,
         default_start_url: str = "https://google.com/",
         default_timeout: Optional[int] = None,
@@ -98,6 +99,7 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
         viewport_limit: bool = False,
         connect_over_cdp: bool = False,
         cdp_url: Optional[str] = None,
+        full_visual_mode: bool = False,
     ) -> None:
         r"""Initialize the HybridBrowserToolkit.
 
@@ -115,6 +117,8 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
             Defaults to None.
             browser_log_to_file (bool): Whether to log browser actions to
             file. Defaults to False.
+            log_dir (Optional[str]): Custom directory path for log files.
+            If None, defaults to "browser_log". Defaults to None.
             session_id (Optional[str]): Session identifier. Defaults to None.
             default_start_url (str): Default URL to start with. Defaults
             to "https://google.com/".
@@ -143,6 +147,9 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
             cdp_url (Optional[str]): WebSocket endpoint URL for CDP
             connection (e.g., 'ws://localhost:9222/devtools/browser/...').
             Required when connect_over_cdp is True. Defaults to None.
+            full_visual_mode (bool): When True, browser actions like click,
+            browser_open, visit_page, etc. will not return snapshots.
+            Defaults to False.
         """
         super().__init__()
         RegisteredAgentToolkit.__init__(self)
@@ -163,10 +170,12 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
             viewport_limit=viewport_limit,
             cache_dir=cache_dir,
             browser_log_to_file=browser_log_to_file,
+            log_dir=log_dir,
             session_id=session_id,
             enabled_tools=enabled_tools,
             connect_over_cdp=connect_over_cdp,
             cdp_url=cdp_url,
+            full_visual_mode=full_visual_mode,
         )
 
         # Legacy attribute access for backward compatibility
@@ -182,6 +191,7 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
         self._default_start_url = browser_config.default_start_url
         self._session_id = toolkit_config.session_id or "default"
         self._viewport_limit = browser_config.viewport_limit
+        self._full_visual_mode = browser_config.full_visual_mode
 
         # Store timeout configuration for backward compatibility
         self._default_timeout = browser_config.default_timeout
@@ -648,22 +658,29 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
 
             # Add tab information
             tab_info = await ws_wrapper.get_tab_info()
-            result.update(
-                {
-                    "tabs": tab_info,
-                    "current_tab": next(
-                        (
-                            i
-                            for i, tab in enumerate(tab_info)
-                            if tab.get("is_current")
-                        ),
-                        0,
+
+            response = {
+                "result": result.get("result", ""),
+                "snapshot": result.get("snapshot", ""),
+                "tabs": tab_info,
+                "current_tab": next(
+                    (
+                        i
+                        for i, tab in enumerate(tab_info)
+                        if tab.get("is_current")
                     ),
-                    "total_tabs": len(tab_info),
-                }
-            )
+                    0,
+                ),
+                "total_tabs": len(tab_info),
+            }
 
-            return result
+            if "newTabId" in result:
+                response["newTabId"] = result["newTabId"]
+
+            if "timing" in result:
+                response["timing"] = result["timing"]
+
+            return response
         except Exception as e:
             logger.error(f"Failed to click element: {e}")
             return {
@@ -1377,6 +1394,8 @@ class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
             screenshot_timeout=self._screenshot_timeout,
             page_stability_timeout=self._page_stability_timeout,
             dom_content_loaded_timeout=self._dom_content_loaded_timeout,
+            viewport_limit=self._viewport_limit,
+            full_visual_mode=self._full_visual_mode,
         )
 
     def get_tools(self) -> List[FunctionTool]:

camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts

@@ -59,14 +59,30 @@ export class HybridBrowserSession {
       const contexts = this.browser.contexts();
       if (contexts.length > 0) {
         this.context = contexts[0];
+        
+        // Apply stealth headers to existing context if configured
+        // Note: userAgent cannot be changed on an existing context
+        if (stealthConfig.enabled) {
+          if (stealthConfig.extraHTTPHeaders) {
+            await this.context.setExtraHTTPHeaders(stealthConfig.extraHTTPHeaders);
+          }
+          if (stealthConfig.userAgent) {
+            console.warn('[HybridBrowserSession] Cannot apply userAgent to existing context. Consider creating a new context if userAgent customization is required.');
+          }
+        }
       } else {
         const contextOptions: any = {
           viewport: browserConfig.viewport
         };
         
-        // Apply stealth headers if configured
-        if (stealthConfig.enabled && stealthConfig.extraHTTPHeaders) {
-          contextOptions.extraHTTPHeaders = stealthConfig.extraHTTPHeaders;
+        // Apply stealth headers and UA if configured
+        if (stealthConfig.enabled) {
+          if (stealthConfig.extraHTTPHeaders) {
+            contextOptions.extraHTTPHeaders = stealthConfig.extraHTTPHeaders;
+          }
+          if (stealthConfig.userAgent) {
+            contextOptions.userAgent = stealthConfig.userAgent;
+          }
         }
         
         this.context = await this.browser.newContext(contextOptions);
@@ -105,13 +121,18 @@ export class HybridBrowserSession {
       if (stealthConfig.enabled) {
         launchOptions.args = stealthConfig.args || [];
         
-        // Apply stealth user agent if configured
+        // Apply stealth user agent/headers if configured
         if (stealthConfig.userAgent) {
           launchOptions.userAgent = stealthConfig.userAgent;
         }
+        if (stealthConfig.extraHTTPHeaders) {
+          launchOptions.extraHTTPHeaders = stealthConfig.extraHTTPHeaders;
+        }
       }
 
       if (browserConfig.userDataDir) {
+        // Ensure viewport is honored in persistent context
+        launchOptions.viewport = browserConfig.viewport;
         this.context = await chromium.launchPersistentContext(
           browserConfig.userDataDir,
           launchOptions
@@ -129,9 +150,14 @@ export class HybridBrowserSession {
           viewport: browserConfig.viewport
         };
         
-        // Apply stealth headers if configured
-        if (stealthConfig.enabled && stealthConfig.extraHTTPHeaders) {
-          contextOptions.extraHTTPHeaders = stealthConfig.extraHTTPHeaders;
+        // Apply stealth headers and UA if configured
+        if (stealthConfig.enabled) {
+          if (stealthConfig.extraHTTPHeaders) {
+            contextOptions.extraHTTPHeaders = stealthConfig.extraHTTPHeaders;
+          }
+          if (stealthConfig.userAgent) {
+            contextOptions.userAgent = stealthConfig.userAgent;
+          }
         }
         
         this.context = await this.browser.newContext(contextOptions);
@@ -173,26 +199,10 @@ export class HybridBrowserSession {
 
   async getCurrentPage(): Promise<Page> {
     if (!this.currentTabId || !this.pages.has(this.currentTabId)) {
-      // In CDP mode, try to create a new page if none exists
+      // In CDP mode, we cannot create new pages
       const browserConfig = this.configLoader.getBrowserConfig();
-      if (browserConfig.connectOverCdp && this.context) {
-        console.log('[CDP] No active page found, attempting to create new page...');
-        try {
-          const newPage = await this.context.newPage();
-          const newTabId = this.generateTabId();
-          this.registerNewPage(newTabId, newPage);
-          this.currentTabId = newTabId;
-          
-          // Set page timeouts
-          newPage.setDefaultNavigationTimeout(browserConfig.navigationTimeout);
-          newPage.setDefaultTimeout(browserConfig.navigationTimeout);
-          
-          console.log(`[CDP] Created new page with tab ID: ${newTabId}`);
-          return newPage;
-        } catch (error) {
-          console.error('[CDP] Failed to create new page:', error);
-          throw new Error('No active page available and failed to create new page in CDP mode');
-        }
+      if (browserConfig.connectOverCdp) {
+        throw new Error('No active page available in CDP mode; frontend must pre-create blank tabs.');
       }
       throw new Error('No active page available');
     }
@@ -235,6 +245,36 @@ export class HybridBrowserSession {
     return this.getSnapshotForAINative(includeCoordinates, viewportLimit);
   }
 
+  private parseElementFromSnapshot(snapshotText: string, ref: string): { role?: string; text?: string } {
+    const lines = snapshotText.split('\n');
+    for (const line of lines) {
+      if (line.includes(`[ref=${ref}]`)) {
+        const typeMatch = line.match(/^\s*-?\s*([\w-]+)/);
+        const role = typeMatch ? typeMatch[1] : undefined;
+        const textMatch = line.match(/"([^"]*)"/);
+        const text = textMatch ? textMatch[1] : undefined;
+        return { role, text };
+      }
+    }
+    return {};
+  }
+
+  private buildSnapshotIndex(snapshotText: string): Map<string, { role?: string; text?: string }> {
+    const index = new Map<string, { role?: string; text?: string }>();
+    const refRe = /\[ref=([^\]]+)\]/i;
+    for (const line of snapshotText.split('\n')) {
+      const m = line.match(refRe);
+      if (!m) continue;
+      const ref = m[1];
+      const roleMatch = line.match(/^\s*-?\s*([a-z0-9_-]+)/i);
+      const role = roleMatch ? roleMatch[1].toLowerCase() : undefined;
+      const textMatch = line.match(/"([^"]*)"/);
+      const text = textMatch ? textMatch[1] : undefined;
+      index.set(ref, { role, text });
+    }
+    return index;
+  }
+
   private async getSnapshotForAINative(includeCoordinates = false, viewportLimit = false): Promise<SnapshotResult & { timing: DetailedTiming }> {
     const startTime = Date.now();
     const page = await this.getCurrentPage();
@@ -257,6 +297,17 @@ export class HybridBrowserSession {
       const mappingStart = Date.now();
       const playwrightMapping: Record<string, any> = {};
       
+      // Parse element info in a single pass
+      const snapshotIndex = this.buildSnapshotIndex(snapshotText);
+      for (const ref of refs) {
+        const elementInfo = snapshotIndex.get(ref) || {};
+        playwrightMapping[ref] = {
+          ref,
+          role: elementInfo.role || 'unknown',
+          text: elementInfo.text || '',
+        };
+      }
+      
       if (includeCoordinates) {
         // Get coordinates for each ref using aria-ref selector
         for (const ref of refs) {
@@ -270,8 +321,9 @@ export class HybridBrowserSession {
               const boundingBox = await element.boundingBox();
               
               if (boundingBox) {
+                // Add coordinates to existing element info
                 playwrightMapping[ref] = {
-                  ref,
+                  ...playwrightMapping[ref],
                   coordinates: {
                     x: Math.round(boundingBox.x),
                     y: Math.round(boundingBox.y),
@@ -388,7 +440,6 @@ export class HybridBrowserSession {
       
       if (shouldOpenNewTab) {
         //  Handle new tab opening
-        
         // If it's a link that doesn't naturally open in new tab, force it
         if (isNavigableLink && !naturallyOpensNewTab) {
           await element.evaluate((el, blankTarget) => {
@@ -803,6 +854,55 @@ export class HybridBrowserSession {
     }
   }
 
+  /**
+   * Wait for DOM to stop changing for a specified duration
+   */
+  private async waitForDOMStability(page: Page, maxWaitTime: number = 500): Promise<void> {
+    const startTime = Date.now();
+    const stabilityThreshold = 100; // Consider stable if no changes for 100ms
+    let lastChangeTime = Date.now();
+    
+    try {
+      // Monitor DOM changes
+      await page.evaluate(() => {
+        let changeCount = 0;
+        (window as any).__domStabilityCheck = { changeCount: 0, lastChange: Date.now() };
+        
+        const observer = new MutationObserver(() => {
+          (window as any).__domStabilityCheck.changeCount++;
+          (window as any).__domStabilityCheck.lastChange = Date.now();
+        });
+        
+        observer.observe(document.body, { 
+          childList: true, 
+          subtree: true,
+          attributes: true,
+          characterData: true
+        });
+        
+        (window as any).__domStabilityObserver = observer;
+      });
+      
+      // Wait until no changes for stabilityThreshold or timeout
+      await page.waitForFunction(
+        (threshold) => {
+          const check = (window as any).__domStabilityCheck;
+          return check && (Date.now() - check.lastChange) > threshold;
+        },
+        stabilityThreshold,
+        { timeout: Math.max(0, maxWaitTime) }
+      ).catch(() => {});
+    } finally {
+      // Cleanup
+      await page.evaluate(() => {
+        const observer = (window as any).__domStabilityObserver;
+        if (observer) observer.disconnect();
+        delete (window as any).__domStabilityObserver;
+        delete (window as any).__domStabilityCheck;
+      }).catch(() => {});
+    }
+  }
+
   private async waitForPageStability(page: Page): Promise<{ domContentLoadedTime: number; networkIdleTime: number }> {
     let domContentLoadedTime = 0;
     let networkIdleTime = 0;
@@ -1132,12 +1232,12 @@ export class HybridBrowserSession {
     const filtered: Record<string, SnapshotElement> = {};
     
     
-    // Apply viewport filtering with scroll position adjustment
-    const browserConfig = this.configLoader.getBrowserConfig();
-    const adjustedScrollPos = {
-      x: scrollPos.x * browserConfig.scrollPositionScale,
-      y: scrollPos.y * browserConfig.scrollPositionScale
-    };
+    // Apply viewport filtering
+    // boundingBox() returns viewport-relative coordinates, so we don't need to add scroll offsets
+    const viewportLeft = 0;
+    const viewportTop = 0;
+    const viewportRight = viewport.width;
+    const viewportBottom = viewport.height;
     
     for (const [ref, element] of Object.entries(elements)) {
       // If element has no coordinates, include it (fallback)
@@ -1148,14 +1248,9 @@ export class HybridBrowserSession {
       
       const { x, y, width, height } = element.coordinates;
       
-      // Calculate viewport bounds using adjusted scroll position
-      const viewportLeft = adjustedScrollPos.x;
-      const viewportTop = adjustedScrollPos.y;
-      const viewportRight = adjustedScrollPos.x + viewport.width;
-      const viewportBottom = adjustedScrollPos.y + viewport.height;
-      
       // Check if element is visible in current viewport
       // Element is visible if it overlaps with viewport bounds
+      // Since boundingBox() coords are viewport-relative, we compare directly
       const isVisible = (
         x < viewportRight &&              // Left edge is before viewport right
         y < viewportBottom &&             // Top edge is before viewport bottom  

camel/toolkits/hybrid_browser_toolkit/ts/src/config-loader.ts

@@ -79,6 +79,7 @@ export interface WebSocketConfig {
   browser_log_to_file: boolean;
   session_id?: string;
   viewport_limit: boolean;
+  fullVisualMode?: boolean;
 }
 
 // Default stealth configuration
@@ -212,6 +213,7 @@ export class ConfigLoader {
     if (config.browser_log_to_file !== undefined) wsConfig.browser_log_to_file = config.browser_log_to_file;
     if (config.session_id !== undefined) wsConfig.session_id = config.session_id;
     if (config.viewport_limit !== undefined) wsConfig.viewport_limit = config.viewport_limit;
+    if (config.fullVisualMode !== undefined) wsConfig.fullVisualMode = config.fullVisualMode;
     
     // CDP connection options
     if (config.connectOverCdp !== undefined) browserConfig.connectOverCdp = config.connectOverCdp;