camel-ai 0.2.62__tar.gz → 0.2.65__tar.gz

{camel_ai-0.2.62 → camel_ai-0.2.65}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: camel-ai
-Version: 0.2.62
+Version: 0.2.65
 Summary: Communicative Agents for AI Society Study
 Project-URL: Homepage, https://www.camel-ai.org/
 Project-URL: Repository, https://github.com/camel-ai/camel
@@ -21,7 +21,6 @@ Requires-Dist: psutil<6,>=5.9.8
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: tiktoken<0.8,>=0.7.0
 Provides-Extra: all
-Requires-Dist: accelerate<0.27,>=0.26.0; extra == 'all'
 Requires-Dist: aci-sdk>=1.0.0b1; extra == 'all'
 Requires-Dist: agentops<0.4,>=0.3.21; extra == 'all'
 Requires-Dist: aiosqlite<0.21,>=0.20.0; extra == 'all'
@@ -53,6 +52,7 @@ Requires-Dist: fastapi>=0.115.11; extra == 'all'
 Requires-Dist: ffmpeg-python<0.3,>=0.2.0; extra == 'all'
 Requires-Dist: firecrawl-py<2,>=1.0.0; extra == 'all'
 Requires-Dist: fish-audio-sdk<2025,>=2024.12.5; extra == 'all'
+Requires-Dist: flask>=2.0; extra == 'all'
 Requires-Dist: fpdf>=1.7.2; extra == 'all'
 Requires-Dist: google-api-python-client==2.166.0; extra == 'all'
 Requires-Dist: google-auth-httplib2==0.2.0; extra == 'all'
@@ -66,6 +66,7 @@ Requires-Dist: ibm-watsonx-ai>=1.3.11; extra == 'all'
 Requires-Dist: imageio[pyav]<3,>=2.34.2; extra == 'all'
 Requires-Dist: ipykernel<7,>=6.0.0; extra == 'all'
 Requires-Dist: jupyter-client<9,>=8.6.2; extra == 'all'
+Requires-Dist: langfuse>=2.60.5; extra == 'all'
 Requires-Dist: linkup-sdk<0.3,>=0.2.1; extra == 'all'
 Requires-Dist: litellm<2,>=1.38.1; extra == 'all'
 Requires-Dist: markitdown==0.1.1; extra == 'all'
@@ -82,9 +83,7 @@ Requires-Dist: newspaper3k<0.3,>=0.2.8; extra == 'all'
 Requires-Dist: notion-client<3,>=2.2.1; extra == 'all'
 Requires-Dist: numpy<=2.2,>=1.2; extra == 'all'
 Requires-Dist: openapi-spec-validator<0.8,>=0.7.1; extra == 'all'
-Requires-Dist: opencv-python<5,>=4; extra == 'all'
 Requires-Dist: openpyxl>=3.1.5; extra == 'all'
-Requires-Dist: outlines<0.2,>=0.1.7; extra == 'all'
 Requires-Dist: pandas<2,>=1.5.3; extra == 'all'
 Requires-Dist: pandasai<3,>=2.3.0; extra == 'all'
 Requires-Dist: playwright>=1.50.0; extra == 'all'
@@ -114,7 +113,6 @@ Requires-Dist: rouge<2,>=1.0.1; extra == 'all'
 Requires-Dist: scenedetect>=0.6.5.2; extra == 'all'
 Requires-Dist: scholarly[tor]==1.7.11; extra == 'all'
 Requires-Dist: scrapegraph-py<2,>=1.12.0; extra == 'all'
-Requires-Dist: sentence-transformers<4,>=3.0.1; extra == 'all'
 Requires-Dist: sentencepiece<0.3,>=0.2; extra == 'all'
 Requires-Dist: slack-bolt<2,>=1.20.1; extra == 'all'
 Requires-Dist: slack-sdk<4,>=3.27.2; extra == 'all'
@@ -124,7 +122,6 @@ Requires-Dist: sympy<2,>=1.13.3; extra == 'all'
 Requires-Dist: tabulate>=0.9.0; extra == 'all'
 Requires-Dist: tavily-python<0.6,>=0.5.0; extra == 'all'
 Requires-Dist: textblob<0.18,>=0.17.1; extra == 'all'
-Requires-Dist: torch; extra == 'all'
 Requires-Dist: transformers<5,>=4; extra == 'all'
 Requires-Dist: tree-sitter-python<0.24,>=0.23.6; extra == 'all'
 Requires-Dist: tree-sitter<0.24,>=0.23.2; extra == 'all'
@@ -136,6 +133,7 @@ Requires-Dist: types-requests<3,>=2.31.0; extra == 'all'
 Requires-Dist: types-setuptools<70,>=69.2.0; extra == 'all'
 Requires-Dist: types-tqdm<5,>=4.66.0; extra == 'all'
 Requires-Dist: unstructured==0.16.20; extra == 'all'
+Requires-Dist: weaviate-client>=4.15.0; extra == 'all'
 Requires-Dist: wikipedia<2,>=1; extra == 'all'
 Requires-Dist: wolframalpha<6,>=5.0.0; extra == 'all'
 Requires-Dist: xls2xlsx>=0.2.0; extra == 'all'
@@ -160,6 +158,7 @@ Requires-Dist: rouge<2,>=1.0.1; extra == 'data-tools'
 Requires-Dist: stripe<12,>=11.3.0; extra == 'data-tools'
 Requires-Dist: textblob<0.18,>=0.17.1; extra == 'data-tools'
 Provides-Extra: dev
+Requires-Dist: flask>=2.0; extra == 'dev'
 Requires-Dist: gradio<4,>=3; extra == 'dev'
 Requires-Dist: mock<6,>=5; extra == 'dev'
 Requires-Dist: mypy<2,>=1.5.1; extra == 'dev'
@@ -184,6 +183,7 @@ Requires-Dist: docker<8,>=7.1.0; extra == 'dev-tools'
 Requires-Dist: e2b-code-interpreter<2,>=1.0.3; extra == 'dev-tools'
 Requires-Dist: ipykernel<7,>=6.0.0; extra == 'dev-tools'
 Requires-Dist: jupyter-client<9,>=8.6.2; extra == 'dev-tools'
+Requires-Dist: langfuse>=2.60.5; extra == 'dev-tools'
 Requires-Dist: mcp>=1.3.0; extra == 'dev-tools'
 Requires-Dist: tree-sitter-python<0.24,>=0.23.6; extra == 'dev-tools'
 Requires-Dist: tree-sitter<0.24,>=0.23.2; extra == 'dev-tools'
@@ -215,13 +215,11 @@ Requires-Dist: tabulate>=0.9.0; extra == 'document-tools'
 Requires-Dist: unstructured==0.16.20; extra == 'document-tools'
 Requires-Dist: xls2xlsx>=0.2.0; extra == 'document-tools'
 Provides-Extra: huggingface
-Requires-Dist: accelerate<0.27,>=0.26.0; extra == 'huggingface'
 Requires-Dist: datasets<4,>=3; extra == 'huggingface'
 Requires-Dist: diffusers<0.26,>=0.25.0; extra == 'huggingface'
-Requires-Dist: opencv-python<5,>=4; extra == 'huggingface'
+Requires-Dist: huggingface-hub; extra == 'huggingface'
 Requires-Dist: sentencepiece<0.3,>=0.2; extra == 'huggingface'
 Requires-Dist: soundfile<0.14,>=0.13; extra == 'huggingface'
-Requires-Dist: torch; extra == 'huggingface'
 Requires-Dist: transformers<5,>=4; extra == 'huggingface'
 Provides-Extra: media-tools
 Requires-Dist: ffmpeg-python<0.3,>=0.2.0; extra == 'media-tools'
@@ -258,9 +256,7 @@ Requires-Dist: mcp-simple-arxiv==0.2.2; extra == 'owl'
 Requires-Dist: newspaper3k<0.3,>=0.2.8; extra == 'owl'
 Requires-Dist: numpy<=2.2,>=1.2; extra == 'owl'
 Requires-Dist: openapi-spec-validator<0.8,>=0.7.1; extra == 'owl'
-Requires-Dist: opencv-python<5,>=4; extra == 'owl'
 Requires-Dist: openpyxl>=3.1.5; extra == 'owl'
-Requires-Dist: outlines<0.2,>=0.1.7; extra == 'owl'
 Requires-Dist: pandas<2,>=1.5.3; extra == 'owl'
 Requires-Dist: pandasai<3,>=2.3.0; extra == 'owl'
 Requires-Dist: playwright>=1.50.0; extra == 'owl'
@@ -301,8 +297,8 @@ Requires-Dist: pyobvector>=0.1.18; extra == 'rag'
 Requires-Dist: pytidb-experimental==0.0.1.dev4; extra == 'rag'
 Requires-Dist: qdrant-client<2,>=1.9.0; extra == 'rag'
 Requires-Dist: rank-bm25<0.3,>=0.2.2; extra == 'rag'
-Requires-Dist: sentence-transformers<4,>=3.0.1; extra == 'rag'
 Requires-Dist: unstructured==0.16.20; extra == 'rag'
+Requires-Dist: weaviate-client>=4.15.0; extra == 'rag'
 Provides-Extra: research-tools
 Requires-Dist: arxiv2text<0.2,>=0.1.14; extra == 'research-tools'
 Requires-Dist: arxiv<3,>=2.1.3; extra == 'research-tools'
@@ -320,6 +316,7 @@ Requires-Dist: pyobvector>=0.1.18; extra == 'storage'
 Requires-Dist: pytidb-experimental==0.0.1.dev4; extra == 'storage'
 Requires-Dist: qdrant-client<2,>=1.9.0; extra == 'storage'
 Requires-Dist: redis<6,>=5.0.6; extra == 'storage'
+Requires-Dist: weaviate-client>=4.15.0; extra == 'storage'
 Provides-Extra: test
 Requires-Dist: mock<6,>=5; extra == 'test'
 Requires-Dist: pytest-asyncio<0.24,>=0.23.0; extra == 'test'

{camel_ai-0.2.62 → camel_ai-0.2.65}/camel/__init__.py

@@ -14,7 +14,7 @@
 
 from camel.logger import disable_logging, enable_logging, set_log_level
 
-__version__ = '0.2.62'
+__version__ = '0.2.65'
 
 __all__ = [
     '__version__',

{camel_ai-0.2.62 → camel_ai-0.2.65}/camel/agents/chat_agent.py

@@ -19,7 +19,6 @@ import textwrap
 import threading
 import uuid
 from collections import defaultdict
-from datetime import datetime
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
@@ -79,6 +78,7 @@ from camel.utils import (
     get_model_encoding,
     model_from_json_schema,
 )
+from camel.utils.commons import dependencies_required
 
 if TYPE_CHECKING:
     from camel.terminators import ResponseTerminator
@@ -96,6 +96,15 @@ try:
 except (ImportError, AttributeError):
     from camel.utils import track_agent
 
+# Langfuse decorator setting
+if os.environ.get("LANGFUSE_ENABLED", "False").lower() == "true":
+    try:
+        from langfuse.decorators import observe
+    except ImportError:
+        from camel.utils import observe
+else:
+    from camel.utils import observe
+
 
 SIMPLE_FORMAT_PROMPT = TextPrompt(
     textwrap.dedent(
@@ -151,8 +160,10 @@ class ChatAgent(BaseAgent):
             (default: :obj:`None`)
         scheduling_strategy (str): name of function that defines how to select
             the next model in ModelManager. (default: :str:`round_robin`)
-        single_iteration (bool): Whether to let the agent perform only one
-            model calling at each step. (default: :obj:`False`)
+        max_iteration (Optional[int], optional): 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`)
         agent_id (str, optional): The ID of the agent. If not provided, a
             random UUID will be generated. (default: :obj:`None`)
         stop_event (Optional[threading.Event], optional): Event to signal
@@ -188,7 +199,7 @@ class ChatAgent(BaseAgent):
         ] = None,
         response_terminators: Optional[List[ResponseTerminator]] = None,
         scheduling_strategy: str = "round_robin",
-        single_iteration: bool = False,
+        max_iteration: Optional[int] = None,
         agent_id: Optional[str] = None,
         stop_event: Optional[threading.Event] = None,
     ) -> None:
@@ -204,7 +215,7 @@ class ChatAgent(BaseAgent):
         self.model_type = self.model_backend.model_type
 
         # Assign unique ID
-        self.agent_id = agent_id if agent_id else str(uuid.uuid4())[:6]
+        self.agent_id = agent_id if agent_id else str(uuid.uuid4())
 
         # Set up memory
         context_creator = ScoreBasedContextCreator(
@@ -263,7 +274,7 @@ class ChatAgent(BaseAgent):
         # Set up other properties
         self.terminated = False
         self.response_terminators = response_terminators or []
-        self.single_iteration = single_iteration
+        self.max_iteration = max_iteration
         self.stop_event = stop_event
 
     def reset(self):
@@ -509,7 +520,7 @@ class ChatAgent(BaseAgent):
                 memory record. If None, current timestamp will be used.
                 (default: :obj:`None`)
         """
-        from datetime import timezone
+        import time
 
         self.memory.write_record(
             MemoryRecord(
@@ -517,7 +528,7 @@ class ChatAgent(BaseAgent):
                 role_at_backend=role,
                 timestamp=timestamp
                 if timestamp is not None
-                else datetime.now(timezone.utc).timestamp(),
+                else time.time_ns() / 1_000_000_000,  # Nanosecond precision
                 agent_id=self.agent_id,
             )
         )
@@ -731,6 +742,7 @@ class ChatAgent(BaseAgent):
             message.content = response.output_messages[0].content
             self._try_format_message(message, response_format)
 
+    @observe()
     def step(
         self,
         input_message: Union[BaseMessage, str],
@@ -753,6 +765,14 @@ class ChatAgent(BaseAgent):
                 flag, and session information.
         """
 
+        # Set Langfuse session_id using agent_id for trace grouping
+        try:
+            from camel.utils.langfuse import set_current_agent_session_id
+
+            set_current_agent_session_id(self.agent_id)
+        except ImportError:
+            pass  # Langfuse not available
+
         # Convert input message to BaseMessage if necessary
         if isinstance(input_message, str):
             input_message = BaseMessage.make_user_message(
@@ -771,6 +791,7 @@ class ChatAgent(BaseAgent):
 
         # Initialize token usage tracker
         step_token_usage = self._create_token_usage_tracker()
+        iteration_count = 0
 
         while True:
             try:
@@ -787,6 +808,7 @@ class ChatAgent(BaseAgent):
                 response_format,
                 self._get_full_tool_schemas(),
             )
+            iteration_count += 1
 
             # Accumulate API token usage
             self._update_token_usage_tracker(
@@ -821,7 +843,10 @@ class ChatAgent(BaseAgent):
                 if external_tool_call_requests:
                     break
 
-                if self.single_iteration:
+                if (
+                    self.max_iteration is not None
+                    and iteration_count >= self.max_iteration
+                ):
                     break
 
                 # If we're still here, continue the loop
@@ -847,6 +872,7 @@ class ChatAgent(BaseAgent):
         openai_messages, _ = self.memory.get_context()
         return openai_messages
 
+    @observe()
     async def astep(
         self,
         input_message: Union[BaseMessage, str],
@@ -873,6 +899,13 @@ class ChatAgent(BaseAgent):
                 a boolean indicating whether the chat session has terminated,
                 and information about the chat session.
         """
+        try:
+            from camel.utils.langfuse import set_current_agent_session_id
+
+            set_current_agent_session_id(self.agent_id)
+        except ImportError:
+            pass  # Langfuse not available
+
         if isinstance(input_message, str):
             input_message = BaseMessage.make_user_message(
                 role_name="User", content=input_message
@@ -888,6 +921,7 @@ class ChatAgent(BaseAgent):
 
         # Initialize token usage tracker
         step_token_usage = self._create_token_usage_tracker()
+        iteration_count = 0
         while True:
             try:
                 openai_messages, num_tokens = self.memory.get_context()
@@ -903,6 +937,7 @@ class ChatAgent(BaseAgent):
                 response_format,
                 self._get_full_tool_schemas(),
             )
+            iteration_count += 1
 
             # Terminate Agent if stop_event is set
             if self.stop_event and self.stop_event.is_set():
@@ -933,7 +968,10 @@ class ChatAgent(BaseAgent):
                 if external_tool_call_requests:
                     break
 
-                if self.single_iteration:
+                if (
+                    self.max_iteration is not None
+                    and iteration_count >= self.max_iteration
+                ):
                     break
 
                 # If we're still here, continue the loop
@@ -1331,6 +1369,13 @@ class ChatAgent(BaseAgent):
         """
         output_messages: List[BaseMessage] = []
         for choice in response.choices:
+            # Skip messages with no meaningful content
+            if (
+                choice.message.content is None
+                or choice.message.content.strip() == ""
+            ) and not choice.message.tool_calls:
+                continue
+
             meta_dict = {}
             if logprobs_info := handle_logprobs(choice):
                 meta_dict["logprobs_info"] = logprobs_info
@@ -1560,8 +1605,32 @@ class ChatAgent(BaseAgent):
         args = tool_call_request.args
         tool_call_id = tool_call_request.tool_call_id
         tool = self._internal_tools[func_name]
+        import asyncio
+
         try:
-            result = await tool.async_call(**args)
+            # Try different invocation paths in order of preference
+            if hasattr(tool, 'func') and hasattr(tool.func, 'async_call'):
+                # Case: FunctionTool wrapping an MCP tool
+                result = await tool.func.async_call(**args)
+
+            elif hasattr(tool, 'async_call') and callable(tool.async_call):
+                # Case: tool itself has async_call
+                result = await tool.async_call(**args)
+
+            elif hasattr(tool, 'func') and asyncio.iscoroutinefunction(
+                tool.func
+            ):
+                # Case: tool wraps a direct async function
+                result = await tool.func(**args)
+
+            elif asyncio.iscoroutinefunction(tool):
+                # Case: tool is itself a coroutine function
+                result = await tool(**args)
+
+            else:
+                # Fallback: synchronous call
+                result = tool(**args)
+
         except Exception as e:
             # Capture the error message to prevent framework crash
             error_msg = f"Error executing async tool '{func_name}': {e!s}"
@@ -1599,17 +1668,24 @@ class ChatAgent(BaseAgent):
             tool_call_id=tool_call_id,
         )
 
-        # Use slightly different timestamps to ensure correct ordering
+        # Use precise timestamps to ensure correct ordering
         # This ensures the assistant message (tool call) always appears before
         # the function message (tool result) in the conversation context
-        current_time = datetime.now().timestamp()
+        # Use time.time_ns() for nanosecond precision to avoid collisions
+        import time
+
+        current_time_ns = time.time_ns()
+        base_timestamp = current_time_ns / 1_000_000_000  # Convert to seconds
+
         self.update_memory(
-            assist_msg, OpenAIBackendRole.ASSISTANT, timestamp=current_time
+            assist_msg, OpenAIBackendRole.ASSISTANT, timestamp=base_timestamp
         )
+
+        # Add minimal increment to ensure function message comes after
         self.update_memory(
             func_msg,
             OpenAIBackendRole.FUNCTION,
-            timestamp=current_time + 0.001,
+            timestamp=base_timestamp + 1e-6,
         )
 
         # Record information about this tool call
@@ -1690,7 +1766,7 @@ class ChatAgent(BaseAgent):
             ],
             response_terminators=self.response_terminators,
             scheduling_strategy=self.model_backend.scheduling_strategy.__name__,
-            single_iteration=self.single_iteration,
+            max_iteration=self.max_iteration,
             stop_event=self.stop_event,
         )
 
@@ -1714,6 +1790,7 @@ class ChatAgent(BaseAgent):
             f"ChatAgent({self.role_name}, {self.role_type}, {self.model_type})"
         )
 
+    @dependencies_required("mcp")
     def to_mcp(
         self,
         name: str = "CAMEL-ChatAgent",
@@ -1740,13 +1817,7 @@ class ChatAgent(BaseAgent):
         Returns:
             FastMCP: An MCP server instance that can be run.
         """
-        try:
-            from mcp.server.fastmcp import FastMCP
-        except ImportError:
-            raise ImportError(
-                "The 'mcp' package is required to use the to_mcp method. "
-                "Install it with 'pip install mcp'."
-            )
+        from mcp.server.fastmcp import FastMCP
 
         # Combine dependencies
         all_dependencies = ["camel-ai[all]"]
@@ -1837,7 +1908,7 @@ class ChatAgent(BaseAgent):
                     "description": tool.get_function_description() or "",
                     "parameters": [
                         {"name": param_name, "type": str(param_type)}
-                        for param_name, param_type in tool.get_parameters().items()  # noqa: E501
+                        for param_name, param_type in tool.parameters.items()
                     ],
                 }
             return tool_info

{camel_ai-0.2.62 → camel_ai-0.2.65}/camel/agents/mcp_agent.py

@@ -125,6 +125,7 @@ class MCPAgent(ChatAgent):
         local_config_path: Optional[str] = None,
         tools: Optional[List[Union[FunctionTool, Callable]]] = None,
         function_calling_available: bool = True,
+        strict: bool = False,
         **kwargs,
     ):
         if model is None:
@@ -144,6 +145,7 @@ class MCPAgent(ChatAgent):
 
         self.local_config = local_config
         self.function_calling_available = function_calling_available
+        self.strict = strict
 
         if function_calling_available:
             sys_msg_content = "You are a helpful assistant, and you prefer "
@@ -177,7 +179,7 @@ class MCPAgent(ChatAgent):
         if self.local_config:
             config_dict.update(self.local_config)
 
-        return MCPToolkit(config_dict=config_dict)
+        return MCPToolkit(config_dict=config_dict, strict=self.strict)
 
     def add_registry(self, registry_config: BaseMCPRegistryConfig) -> None:
         r"""Add a new registry configuration to the agent.
@@ -211,6 +213,7 @@ class MCPAgent(ChatAgent):
         ] = None,
         model: Optional[BaseModelBackend] = None,
         function_calling_available: bool = False,
+        strict: bool = False,
         **kwargs,
     ) -> "MCPAgent":
         r"""Create and connect an MCPAgent instance.
@@ -276,6 +279,7 @@ class MCPAgent(ChatAgent):
             registry_configs=final_registry_configs,
             model=model,
             function_calling_available=function_calling_available,
+            strict=strict,
             **kwargs,
         )
 

camel_ai-0.2.65/camel/benchmarks/mock_website/README.md

@@ -0,0 +1,96 @@
+# Mock Website Benchmarks for Web Agent Testing
+
+This project provides a framework for testing web agents against various mock websites. It features a central dispatcher (`mock_web.py`) that manages different test environments, each simulating a specific type of website (e.g., an e-commerce site). The initial example project is an Amazon-like shopping website.
+
+## Core Concepts
+
+*   **Dispatcher (`mock_web.py`):** The single entry point for running any benchmark. It handles:
+    *   Downloading necessary web assets (HTML templates, CSS, JS) for a specific project from Hugging Face (https://huggingface.co/datasets/camel-ai/mock_websites).
+    *   Reading the task configuration from `task.json`.
+    *   Launching the project's dedicated Flask web server as a background process.
+    *   Monitoring the server for task completion via API polling.
+    *   Reporting the final results (success status, number of operations) and shutting down the server.
+*   **Projects (e.g., `shopping_mall/`):** Each project is a self-contained Flask application representing a unique website.
+*   **Task Configuration (`task.json`):** A central JSON file that defines the environment and the goal for the agent.
+
+## Example Project: `shopping_mall`
+
+The included `shopping_mall` project simulates an e-commerce website with the following features:
+*   **Product Display:** View a list of products with images, descriptions, ratings, and prices.
+*   **Product Detail Pages:** Click on a product to see its dedicated detail page.
+*   **Shopping Cart:** Add products, view the cart, and manage its contents.
+*   **API-Driven:** The backend provides API endpoints for all state-changing actions.
+
+## Setup and Usage
+
+1.  **Install Dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+    This will install `Flask`, `huggingface-hub`, `requests`, and other necessary packages.
+
+2.  **Configure the Task:**
+    Edit the `task.json` file to define the products available on the website and the agent's goal. The structure is as follows:
+    ```json
+    {
+        "products": [
+            {
+                "id": 1,
+                "name": "Gaming Laptop",
+                "price": 1200,
+                "image": "assets/img/products/laptop.jpg",
+                "category": "Electronics",
+                "rating": 4.5,
+                "description": "High-performance gaming laptop with latest specs."
+            }
+        ],
+        "ground_truth_cart": [
+            {
+                "id": 1,
+                "quantity": 1
+            }
+        ]
+    }
+    ```
+    *   `products`: A list of all product objects available in the environment.
+    *   `ground_truth_cart`: A list of items that defines the target state of the shopping cart for the task to be considered complete.
+
+3.  **Running the Benchmark:**
+    Use the `mock_web.py` dispatcher to run a project.
+    ```bash
+    python mock_web.py --project shopping_mall
+    ```
+    *   `--project`: Specifies which mock website project to run (default: `shopping_mall`).
+    *   `--port`: Specifies the port to run the server on (default: `5001`).
+
+    The dispatcher will start the server and begin polling for task completion. You or your agent can then interact with the website at `http://127.0.0.1:5001/`. Once the conditions defined in `ground_truth_cart` are met, the dispatcher will automatically detect it, report the results, and shut down. You can also stop it early by pressing `Ctrl+C`.
+
+## Logging
+
+*   `dispatcher.log`: High-level log from the dispatcher, showing setup, status, and final results.
+*   `shopping_mall/app.log`: Detailed internal log from the Flask application for the `shopping_mall` project.
+
+## Project Structure
+
+```
+.
+├── mock_web.py                # Main dispatcher for running benchmarks
+├── task.json                  # Task configuration file
+├── requirements.txt           # Python dependencies
+├── shopping_mall/             # Example project: shopping_mall
+│   └── app.py                 # Flask application for this project
+├── dispatcher.log             # (Generated at runtime)
+└── README.md                  # This file
+```
+The dispatcher will automatically download project-specific `templates` and `static` folders from Hugging Face Hub and place them inside the corresponding project directory at runtime.
+
+## TODO: Automated Question Generation Module
+
+A planned future module for this project is the development of an automated question generation system. This system would analyze the current state of the web application environment (e.g., visible elements, available products, cart status) and generate relevant questions or tasks for a web agent to solve. 
+
+This could involve:
+*   Identifying interactable elements and their states.
+*   Understanding the current context (e.g., on product page, in cart).
+*   Formulating natural language questions or goal descriptions based on this context (e.g., "Find a product under $50 in the Electronics category and add it to the cart," or "What is the current subtotal of the cart after adding two units of item X?").
+
+