camel-ai 0.2.22__py3-none-any.whl → 0.2.23__py3-none-any.whl

camel/extractors/base.py

@@ -0,0 +1,263 @@
+# ========= 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 abc import ABC, abstractmethod
+from types import TracebackType
+from typing import Any, Dict, Optional, Type
+
+from typing_extensions import Self
+
+from camel.logger import get_logger
+from camel.utils import BatchProcessor
+
+logger = get_logger(__name__)
+
+
+class BaseExtractor(ABC):
+    r"""Base class for all response extractors.
+
+    An extractor takes the response and extracts the relevant parts,
+    converting them into a format that the verifier can handle.
+    Implements async context manager protocol for proper resource management.
+    """
+
+    def __init__(
+        self,
+        cache_templates: bool = True,
+        max_cache_size: int = 1000,
+        extraction_timeout: float = 30.0,
+        batch_size: int = 10,
+        monitoring_interval: float = 5.0,
+        cpu_threshold: float = 80.0,
+        memory_threshold: float = 85.0,
+        **kwargs,
+    ):
+        r"""Initialize the extractor.
+
+        Args:
+            cache_templates (bool): Whether to cache extraction templates.
+                (default: :obj:`True`)
+            max_cache_size (int): Maximum number of templates to cache.
+                (default: :obj:`1000`)
+            extraction_timeout (float): Maximum time for extraction in seconds.
+                (default: :obj:`30.0`)
+            batch_size (int): Size of batches for parallel extraction.
+                (default: :obj:`10`)
+            monitoring_interval (float): Interval in seconds between resource
+                checks. (default: :obj:`5.0`)
+            cpu_threshold (float): CPU usage percentage threshold for scaling
+                down. (default: :obj:`80.0`)
+            memory_threshold (float): Memory usage percentage threshold for
+                scaling down. (default: :obj:`85.0`)
+            **kwargs: Additional extractor parameters.
+
+        Raises:
+            ValueError: If invalid parameter values are provided
+        """
+        # Store all parameters in metadata dict for compatibility
+        self._metadata = {
+            'cache_templates': cache_templates,
+            'max_cache_size': max_cache_size,
+            'extraction_timeout': extraction_timeout,
+            'batch_size': batch_size,
+            'monitoring_interval': monitoring_interval,
+            'cpu_threshold': cpu_threshold,
+            'memory_threshold': memory_threshold,
+            **kwargs,
+        }
+
+        self._is_setup = False
+        self._cache: Dict[str, Any] = {}
+        self._batch_processor: Optional[BatchProcessor] = None
+
+        # Store configuration parameters
+        self._cache_templates = cache_templates
+        self._max_cache_size = max_cache_size
+        self._extraction_timeout = extraction_timeout
+        self._batch_size = batch_size
+        self._monitoring_interval = monitoring_interval
+        self._cpu_threshold = cpu_threshold
+        self._memory_threshold = memory_threshold
+
+    async def setup(self) -> None:
+        r"""Set up the extractor with necessary resources.
+
+        This method:
+        1. Initializes template cache if enabled
+        2. Sets up any parallel processing resources
+        3. Validates extraction patterns
+
+        Raises:
+            RuntimeError: If initialization fails
+        """
+        if self._is_setup:
+            logger.debug(f"{self.__class__.__name__} already initialized")
+            return
+
+        try:
+            # Initialize template cache if enabled
+            if self._cache_templates:
+                self._template_cache: Dict[str, Any] = {}
+
+            # Set up batch processing if needed
+            if self._batch_size > 1:
+                self._batch_processor = BatchProcessor(
+                    initial_batch_size=self._batch_size,
+                    monitoring_interval=self._monitoring_interval,
+                    cpu_threshold=self._cpu_threshold,
+                    memory_threshold=self._memory_threshold,
+                )
+
+            self._is_setup = True
+            logger.info(f"{self.__class__.__name__} initialized successfully")
+
+        except Exception as e:
+            error_msg = f"Error during {self.__class__.__name__} setup: {e}"
+            logger.error(error_msg)
+            await self.cleanup()
+            raise RuntimeError(error_msg) from e
+
+    async def cleanup(self) -> None:
+        r"""Clean up extractor resources.
+
+        This method handles cleanup of resources and resets the extractor
+        state.
+        It ensures:
+        1. All resources are properly released
+        2. Template cache is cleared
+        3. Parallel processing resources are shutdown
+        4. State is reset to initial
+        5. Cleanup happens even if errors occur
+
+        Raises:
+            RuntimeError: If cleanup fails (after resetting initialization
+                state).
+        """
+        if not self._is_setup:
+            logger.debug(
+                f"{self.__class__.__name__} not initialized, skipping cleanup"
+            )
+            return
+
+        errors = []
+        try:
+            # Clear template cache
+            if hasattr(self, '_template_cache'):
+                try:
+                    self._template_cache.clear()
+                except Exception as e:
+                    errors.append(f"Failed to clear template cache: {e}")
+
+            # Shutdown parallel processing
+            if self._batch_processor is not None:
+                try:
+                    # Get final performance metrics before cleanup
+                    metrics = self._batch_processor.get_performance_metrics()
+                    logger.info(f"Batch processor final metrics: {metrics}")
+                except Exception as e:
+                    errors.append(
+                        f"Failed to get batch processor metrics: {e}"
+                    )
+
+            # Preserve init config in metadata
+            self._metadata = {
+                'cache_templates': self._cache_templates,
+                'max_cache_size': self._max_cache_size,
+                'extraction_timeout': self._extraction_timeout,
+                'batch_size': self._batch_size,
+            }
+
+            if not errors:
+                logger.info(
+                    f"{self.__class__.__name__} cleaned up successfully"
+                )
+
+        except Exception as e:
+            errors.append(f"Unexpected error during cleanup: {e}")
+
+        finally:
+            # Always mark as uninitialized, even if cleanup fails
+            self._is_setup = False
+            self._batch_processor = None
+
+        if errors:
+            error_msg = (
+                f"Errors during {self.__class__.__name__} cleanup: "
+                f"{'; '.join(errors)}"
+            )
+            logger.error(error_msg)
+            raise RuntimeError(error_msg)
+
+    async def __aenter__(self) -> Self:
+        r"""Async context manager entry.
+
+        Returns:
+            Self reference for context manager usage.
+        """
+        await self.setup()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        r"""Async context manager exit.
+
+        Args:
+            exc_type (Optional[Type[BaseException]]): Exception type if an
+                error occurred.
+            exc_val (Optional[BaseException]): Exception value if an error
+                occurred.
+            exc_tb (Optional[TracebackType]): Exception traceback if an error
+                occurred.
+        """
+        await self.cleanup()
+
+    @abstractmethod
+    async def extract(
+        self, response: str, context: Optional[Dict[str, Any]] = None
+    ) -> str:
+        r"""Extract relevant parts from a response.
+
+        Extracts:
+        1. Final answer or output
+        2. Chain of thought reasoning steps
+        3. Difficulty assessment
+
+        Args:
+            response (str): Raw response from agent generation.
+            context (Optional[Dict[str, Any]]): Optional context for
+            extraction like:
+                - final_answer
+                - rationale
+                - complexity
+
+        Returns:
+            str: Extracted content string.
+
+        Raises:
+            ValueError: If response is empty or invalid.
+            NotImplementedError: If no implementation is provided.
+            RuntimeError: If extractor is not initialized.
+        """
+        if not self._is_setup:
+            raise RuntimeError(
+                f"{self.__class__.__name__} must be initialized "
+                "before extraction"
+            )
+        if not response or not response.strip():
+            raise ValueError("Empty or whitespace-only response")
+        raise NotImplementedError("Subclasses must implement extract()")

camel/memories/agent_memories.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
+import warnings
 from typing import List, Optional
 
 from camel.memories.base import AgentMemory, BaseContextCreator
@@ -49,7 +50,17 @@ class ChatHistoryMemory(AgentMemory):
         self._chat_history_block = ChatHistoryBlock(storage=storage)
 
     def retrieve(self) -> List[ContextRecord]:
-        return self._chat_history_block.retrieve(self._window_size)
+        records = self._chat_history_block.retrieve(self._window_size)
+        if self._window_size is not None and len(records) == self._window_size:
+            warnings.warn(
+                f"Chat history window size limit ({self._window_size}) "
+                f"reached. Some earlier messages will not be included in "
+                f"the context. Consider increasing window_size if you need "
+                f"a longer context.",
+                UserWarning,
+                stacklevel=2,
+            )
+        return records
 
     def write_records(self, records: List[MemoryRecord]) -> None:
         self._chat_history_block.write_records(records)
@@ -103,6 +114,10 @@ class VectorDBMemory(AgentMemory):
     def get_context_creator(self) -> BaseContextCreator:
         return self._context_creator
 
+    def clear(self) -> None:
+        r"""Removes all records from the vector database memory."""
+        self._vectordb_block.clear()
+
 
 class LongtermAgentMemory(AgentMemory):
     r"""An implementation of the :obj:`AgentMemory` abstract base class for

camel/memories/blocks/chat_history_block.py

@@ -85,13 +85,21 @@ class ChatHistoryBlock(MemoryBlock):
             if record.role_at_backend == OpenAIBackendRole.SYSTEM:
                 # System messages are always kept.
                 output_records.append(
-                    ContextRecord(memory_record=record, score=1.0)
+                    ContextRecord(
+                        memory_record=record,
+                        score=1.0,
+                        timestamp=record.timestamp,
+                    )
                 )
             else:
                 # Other messages' score drops down gradually
                 score *= self.keep_rate
                 output_records.append(
-                    ContextRecord(memory_record=record, score=score)
+                    ContextRecord(
+                        memory_record=record,
+                        score=score,
+                        timestamp=record.timestamp,
+                    )
                 )
 
         output_records.reverse()

camel/memories/blocks/vectordb_block.py

@@ -74,6 +74,7 @@ class VectorDBBlock(MemoryBlock):
             ContextRecord(
                 memory_record=MemoryRecord.from_dict(result.record.payload),
                 score=result.similarity,
+                timestamp=result.record.payload['timestamp'],
             )
             for result in results
             if result.record.payload is not None

camel/memories/context_creators/score_based.py

@@ -15,11 +15,14 @@ from typing import List, Tuple
 
 from pydantic import BaseModel
 
+from camel.logger import get_logger
 from camel.memories.base import BaseContextCreator
 from camel.memories.records import ContextRecord
 from camel.messages import OpenAIMessage
 from camel.utils import BaseTokenCounter
 
+logger = get_logger(__name__)
+
 
 class _ContextUnit(BaseModel):
     idx: int
@@ -101,18 +104,30 @@ class ScoreBasedContextCreator(BaseContextCreator):
         # If not exceed token limit, simply return
         total_tokens = sum([unit.num_tokens for unit in context_units])
         if total_tokens <= self.token_limit:
+            context_units = sorted(
+                context_units,
+                key=lambda unit: (unit.record.timestamp, unit.record.score),
+            )
             return self._create_output(context_units)
 
+        # Log warning about token limit being exceeded
+        logger.warning(
+            f"Token limit reached ({total_tokens} > {self.token_limit}). "
+            f"Some messages will be pruned from memory to meet the limit."
+        )
+
         # Sort by score
         context_units = sorted(
-            context_units, key=lambda unit: unit.record.score
+            context_units,
+            key=lambda unit: (unit.record.timestamp, unit.record.score),
         )
 
         # Remove the least score messages until total token number is smaller
         # than token limit
         truncate_idx = None
         for i, unit in enumerate(context_units):
-            if unit.record.score == 1:
+            if i == len(context_units) - 1:
+                # If we reach the end of the list and still exceed the token
                 raise RuntimeError(
                     "Cannot create context: exceed token limit.", total_tokens
                 )
@@ -135,7 +150,9 @@ class ScoreBasedContextCreator(BaseContextCreator):
         for output, specifically a list of OpenAIMessages and an integer
         representing the total token count.
         """
-        context_units = sorted(context_units, key=lambda unit: unit.idx)
+        context_units = sorted(
+            context_units, key=lambda unit: unit.record.timestamp
+        )
         return [
             unit.record.memory_record.to_openai_message()
             for unit in context_units

camel/memories/records.py

@@ -13,6 +13,7 @@
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 
 from dataclasses import asdict
+from datetime import datetime, timezone
 from typing import Any, ClassVar, Dict
 from uuid import UUID, uuid4
 
@@ -37,6 +38,7 @@ class MemoryRecord(BaseModel):
         extra_info (Dict[str, str], optional): A dictionary of additional
             key-value pairs that provide more information. If not given, it
             will be an empty `Dict`.
+        timestamp (float, optional): The timestamp when the record was created.
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -45,6 +47,9 @@ class MemoryRecord(BaseModel):
     role_at_backend: OpenAIBackendRole
     uuid: UUID = Field(default_factory=uuid4)
     extra_info: Dict[str, str] = Field(default_factory=dict)
+    timestamp: float = Field(
+        default_factory=lambda: datetime.now(timezone.utc).timestamp()
+    )
 
     _MESSAGE_TYPES: ClassVar[dict] = {
         "BaseMessage": BaseMessage,
@@ -67,6 +72,7 @@ class MemoryRecord(BaseModel):
             message=reconstructed_message,
             role_at_backend=record_dict["role_at_backend"],
             extra_info=record_dict["extra_info"],
+            timestamp=record_dict["timestamp"],
         )
 
     def to_dict(self) -> Dict[str, Any]:
@@ -81,6 +87,7 @@ class MemoryRecord(BaseModel):
             },
             "role_at_backend": self.role_at_backend,
             "extra_info": self.extra_info,
+            "timestamp": self.timestamp,
         }
 
     def to_openai_message(self) -> OpenAIMessage:
@@ -93,3 +100,6 @@ class ContextRecord(BaseModel):
 
     memory_record: MemoryRecord
     score: float
+    timestamp: float = Field(
+        default_factory=lambda: datetime.now(timezone.utc).timestamp()
+    )

camel/messages/base.py

@@ -15,7 +15,7 @@ import base64
 import io
 import re
 from dataclasses import dataclass
-from typing import Any, Dict, List, Literal, Optional, Tuple, Type, Union
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union
 
 import numpy as np
 from PIL import Image
@@ -72,7 +72,7 @@ class BaseMessage:
     image_list: Optional[List[Image.Image]] = None
     image_detail: Literal["auto", "low", "high"] = "auto"
     video_detail: Literal["auto", "low", "high"] = "low"
-    parsed: Optional[Union[Type[BaseModel], dict]] = None
+    parsed: Optional[Union[BaseModel, dict]] = None
 
     @classmethod
     def make_user_message(
@@ -416,8 +416,8 @@ class BaseMessage:
         Returns:
             OpenAIUserMessage: The converted :obj:`OpenAIUserMessage` object.
         """
-        hybird_content: List[Any] = []
-        hybird_content.append(
+        hybrid_content: List[Any] = []
+        hybrid_content.append(
             {
                 "type": "text",
                 "text": self.content,
@@ -445,7 +445,7 @@ class BaseMessage:
                         "utf-8"
                     )
                 image_prefix = f"data:image/{image_type};base64,"
-                hybird_content.append(
+                hybrid_content.append(
                     {
                         "type": "image_url",
                         "image_url": {
@@ -504,12 +504,12 @@ class BaseMessage:
                     },
                 }
 
-                hybird_content.append(item)
+                hybrid_content.append(item)
 
-        if len(hybird_content) > 1:
+        if len(hybrid_content) > 1:
             return {
                 "role": "user",
-                "content": hybird_content,
+                "content": hybrid_content,
             }
         # This return just for str message
         else:

camel/models/__init__.py

@@ -14,6 +14,7 @@
 from .aiml_model import AIMLModel
 from .anthropic_model import AnthropicModel
 from .azure_openai_model import AzureOpenAIModel
+from .base_audio_model import BaseAudioModel
 from .base_model import BaseModelBackend
 from .cohere_model import CohereModel
 from .deepseek_model import DeepSeekModel
@@ -74,4 +75,5 @@ __all__ = [
     'InternLMModel',
     'MoonshotModel',
     'AIMLModel',
+    'BaseAudioModel',
 ]

camel/models/_utils.py

@@ -0,0 +1,57 @@
+# ========= 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. =========
+import textwrap
+from typing import Optional, Type
+
+from pydantic import BaseModel
+
+from camel.messages import OpenAIMessage
+
+
+def try_modify_message_with_format(
+    message: OpenAIMessage,
+    response_format: Optional[Type[BaseModel]],
+) -> None:
+    r"""Modifies the content of the message to include the instruction of using
+    the response format.
+
+    The message will not be modified in the following cases:
+    - response_format is None
+    - message content is not a string
+    - message role is assistant
+
+    Args:
+        response_format (Optional[Type[BaseModel]]): The Pydantic model class.
+        message (OpenAIMessage): The message to be modified.
+    """
+    if response_format is None:
+        return
+
+    if not isinstance(message["content"], str):
+        return
+
+    if message["role"] == "assistant":
+        return
+
+    json_schema = response_format.model_json_schema()
+    updated_prompt = textwrap.dedent(
+        f"""\
+        {message["content"]}
+        
+        Please generate a JSON response adhering to the following JSON schema:
+        {json_schema}
+        Make sure the JSON response is valid and matches the EXACT structure defined in the schema. Your result should ONLY be a valid json object, WITHOUT ANY OTHER TEXT OR COMMENTS.
+        """  # noqa: E501
+    )
+    message["content"] = updated_prompt

camel/models/aiml_model.py

@@ -12,12 +12,14 @@
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 import os
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Type, Union
 
-from openai import OpenAI, Stream
+from openai import AsyncOpenAI, AsyncStream, OpenAI, Stream
+from pydantic import BaseModel
 
 from camel.configs import AIML_API_PARAMS, AIMLConfig
 from camel.messages import OpenAIMessage
+from camel.models._utils import try_modify_message_with_format
 from camel.models.base_model import BaseModelBackend
 from camel.types import (
     ChatCompletion,
@@ -52,11 +54,7 @@ class AIMLModel(BaseModelBackend):
             (default: :obj:`None`)
     """
 
-    @api_keys_required(
-        [
-            ("api_key", 'AIML_API_KEY'),
-        ]
-    )
+    @api_keys_required([("api_key", "AIML_API_KEY")])
     def __init__(
         self,
         model_type: Union[ModelType, str],
@@ -81,12 +79,34 @@ class AIMLModel(BaseModelBackend):
             api_key=self._api_key,
             base_url=self._url,
         )
+        self._async_client = AsyncOpenAI(
+            timeout=180,
+            max_retries=3,
+            api_key=self._api_key,
+            base_url=self._url,
+        )
 
-    def run(
+    def _prepare_request(
+        self,
+        messages: List[OpenAIMessage],
+        response_format: Optional[Type[BaseModel]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        request_config = self.model_config_dict.copy()
+        if tools:
+            request_config["tools"] = tools
+        if response_format:
+            # AIML API does not natively support response format
+            try_modify_message_with_format(messages[-1], response_format)
+        return request_config
+
+    def _run(
         self,
         messages: List[OpenAIMessage],
+        response_format: Optional[Type[BaseModel]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
     ) -> Union[ChatCompletion, Stream[ChatCompletionChunk]]:
-        r"""Runs inference of OpenAI chat completion.
+        r"""Runs inference of AIML chat completion.
 
         Args:
             messages (List[OpenAIMessage]): Message list with the chat history
@@ -97,15 +117,26 @@ class AIMLModel(BaseModelBackend):
                 `ChatCompletion` in the non-stream mode, or
                 `Stream[ChatCompletionChunk]` in the stream mode.
         """
-        # Process model configuration parameters
-        model_config = self.model_config_dict.copy()
-
-        # Handle special case for tools parameter
-        if model_config.get('tools') is None:
-            model_config['tools'] = []
+        request_config = self._prepare_request(
+            messages, response_format, tools
+        )
 
         response = self._client.chat.completions.create(
-            messages=messages, model=self.model_type, **model_config
+            messages=messages, model=self.model_type, **request_config
+        )
+        return response
+
+    async def _arun(
+        self,
+        messages: List[OpenAIMessage],
+        response_format: Optional[Type[BaseModel]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+    ) -> Union[ChatCompletion, AsyncStream[ChatCompletionChunk]]:
+        request_config = self._prepare_request(
+            messages, response_format, tools
+        )
+        response = await self._async_client.chat.completions.create(
+            messages=messages, model=self.model_type, **request_config
         )
         return response
 
@@ -144,4 +175,4 @@ class AIMLModel(BaseModelBackend):
         Returns:
             bool: Whether the model is in stream mode.
         """
-        return self.model_config_dict.get('stream', False)
+        return self.model_config_dict.get("stream", False)