camel-ai 0.2.73a4__py3-none-any.whl → 0.2.80a2__py3-none-any.whl

camel/memories/context_creators/score_based.py

@@ -11,41 +11,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
-from collections import defaultdict
-from typing import Dict, List, Optional, Tuple
 
-from pydantic import BaseModel
+from typing import List, Optional, Tuple
 
-from camel.logger import get_logger
 from camel.memories.base import BaseContextCreator
 from camel.memories.records import ContextRecord
-from camel.messages import FunctionCallingMessage, OpenAIMessage
+from camel.messages import OpenAIMessage
 from camel.types.enums import OpenAIBackendRole
 from camel.utils import BaseTokenCounter
 
-logger = get_logger(__name__)
-
-
-class _ContextUnit(BaseModel):
-    idx: int
-    record: ContextRecord
-    num_tokens: int
-
 
 class ScoreBasedContextCreator(BaseContextCreator):
-    r"""A default implementation of context creation strategy, which inherits
-    from :obj:`BaseContextCreator`.
-
-    This class provides a strategy to generate a conversational context from
-    a list of chat history records while ensuring the total token count of
-    the context does not exceed a specified limit. It prunes messages based
-    on their score if the total token count exceeds the limit.
+    r"""A context creation strategy that orders records chronologically.
 
     Args:
-        token_counter (BaseTokenCounter): An instance responsible for counting
-            tokens in a message.
-        token_limit (int): The maximum number of tokens allowed in the
-            generated context.
+        token_counter (BaseTokenCounter): Token counter instance used to
+            compute the combined token count of the returned messages.
+        token_limit (int): Retained for API compatibility. No longer used to
+            filter records.
     """
 
     def __init__(
@@ -66,376 +49,34 @@ class ScoreBasedContextCreator(BaseContextCreator):
         self,
         records: List[ContextRecord],
     ) -> Tuple[List[OpenAIMessage], int]:
-        r"""Constructs conversation context from chat history while respecting
-        token limits.
-
-        Key strategies:
-        1. System message is always prioritized and preserved
-        2. Truncation removes low-score messages first
-        3. Final output maintains chronological order and in history memory,
-           the score of each message decreases according to keep_rate. The
-           newer the message, the higher the score.
-        4. Tool calls and their responses are kept together to maintain
-           API compatibility
-
-        Args:
-            records (List[ContextRecord]): List of context records with scores
-                and timestamps.
-
-        Returns:
-            Tuple[List[OpenAIMessage], int]:
-            - Ordered list of OpenAI messages
-            - Total token count of the final context
-
-        Raises:
-            RuntimeError: If system message alone exceeds token limit
-        """
-        # ======================
-        # 1. System Message Handling
-        # ======================
-        system_unit, regular_units = self._extract_system_message(records)
-        system_tokens = system_unit.num_tokens if system_unit else 0
+        """Returns messages sorted by timestamp and their total token count."""
 
-        # Check early if system message alone exceeds token limit
-        if system_tokens > self.token_limit:
-            raise RuntimeError(
-                f"System message alone exceeds token limit"
-                f": {system_tokens} > {self.token_limit}",
-                system_tokens,
-            )
+        system_record: Optional[ContextRecord] = None
+        remaining_records: List[ContextRecord] = []
 
-        # ======================
-        # 2. Deduplication & Initial Processing
-        # ======================
-        seen_uuids = set()
-        if system_unit:
-            seen_uuids.add(system_unit.record.memory_record.uuid)
-
-        # Process non-system messages with deduplication
-        for idx, record in enumerate(records):
+        for record in records:
             if (
-                record.memory_record.role_at_backend
+                system_record is None
+                and record.memory_record.role_at_backend
                 == OpenAIBackendRole.SYSTEM
             ):
+                system_record = record
                 continue
-            if record.memory_record.uuid in seen_uuids:
-                continue
-            seen_uuids.add(record.memory_record.uuid)
-
-            token_count = self.token_counter.count_tokens_from_messages(
-                [record.memory_record.to_openai_message()]
-            )
-            regular_units.append(
-                _ContextUnit(
-                    idx=idx,
-                    record=record,
-                    num_tokens=token_count,
-                )
-            )
-
-        # ======================
-        # 3. Tool Call Relationship Mapping
-        # ======================
-        tool_call_groups = self._group_tool_calls_and_responses(regular_units)
-
-        # ======================
-        # 4. Token Calculation
-        # ======================
-        total_tokens = system_tokens + sum(u.num_tokens for u in regular_units)
-
-        # ======================
-        # 5. Early Return if Within Limit
-        # ======================
-        if total_tokens <= self.token_limit:
-            sorted_units = sorted(
-                regular_units, key=self._conversation_sort_key
-            )
-            return self._assemble_output(sorted_units, system_unit)
-
-        # ======================
-        # 6. Truncation Logic with Tool Call Awareness
-        # ======================
-        remaining_units = self._truncate_with_tool_call_awareness(
-            regular_units, tool_call_groups, system_tokens
-        )
-
-        # Log only after truncation is actually performed so that both
-        # the original and the final token counts are visible.
-        tokens_after = system_tokens + sum(
-            u.num_tokens for u in remaining_units
-        )
-        logger.warning(
-            "Context truncation performed: "
-            f"before={total_tokens}, after={tokens_after}, "
-            f"limit={self.token_limit}"
-        )
-
-        # ======================
-        # 7. Output Assembly
-        # ======================
-
-        # In case system message is the only message in memory when sorted
-        # units are empty, raise an error
-        if system_unit and len(remaining_units) == 0 and len(records) > 1:
-            raise RuntimeError(
-                "System message and current message exceeds token limit ",
-                total_tokens,
-            )
-
-        # Sort remaining units chronologically
-        final_units = sorted(remaining_units, key=self._conversation_sort_key)
-        return self._assemble_output(final_units, system_unit)
-
-    def _group_tool_calls_and_responses(
-        self, units: List[_ContextUnit]
-    ) -> Dict[str, List[_ContextUnit]]:
-        r"""Groups tool calls with their corresponding responses based on
-        `tool_call_id`.
-
-        This improved logic robustly gathers all messages (assistant requests
-        and tool responses, including chunks) that share a `tool_call_id`.
-
-        Args:
-            units (List[_ContextUnit]): List of context units to analyze.
-
-        Returns:
-            Dict[str, List[_ContextUnit]]: Mapping from `tool_call_id` to a
-                list of related units.
-        """
-        tool_call_groups: Dict[str, List[_ContextUnit]] = defaultdict(list)
-
-        for unit in units:
-            # FunctionCallingMessage stores tool_call_id.
-            message = unit.record.memory_record.message
-            tool_call_id = getattr(message, 'tool_call_id', None)
-
-            if tool_call_id:
-                tool_call_groups[tool_call_id].append(unit)
-
-        # Filter out empty or incomplete groups if necessary,
-        # though defaultdict and getattr handle this gracefully.
-        return dict(tool_call_groups)
-
-    def _truncate_with_tool_call_awareness(
-        self,
-        regular_units: List[_ContextUnit],
-        tool_call_groups: Dict[str, List[_ContextUnit]],
-        system_tokens: int,
-    ) -> List[_ContextUnit]:
-        r"""Truncates messages while preserving tool call-response pairs.
-        This method implements a more sophisticated truncation strategy:
-        1. It treats tool call groups (request + responses) and standalone
-           messages as individual items to be included.
-        2. It sorts all items by score and greedily adds them to the context.
-        3. **Partial Truncation**: If a complete tool group is too large to
-        fit,it attempts to add the request message and as many of the most
-        recent response chunks as the token budget allows.
-
-        Args:
-            regular_units (List[_ContextUnit]): All regular message units.
-            tool_call_groups (Dict[str, List[_ContextUnit]]): Grouped tool
-                calls.
-            system_tokens (int): Tokens used by the system message.
-
-        Returns:
-            List[_ContextUnit]: A list of units that fit within the token
-                limit.
-        """
-
-        # Create a set for quick lookup of units belonging to any tool call
-        tool_call_unit_ids = {
-            unit.record.memory_record.uuid
-            for group in tool_call_groups.values()
-            for unit in group
-        }
-
-        # Separate standalone units from tool call groups
-        standalone_units = [
-            u
-            for u in regular_units
-            if u.record.memory_record.uuid not in tool_call_unit_ids
-        ]
-
-        # Prepare all items (standalone units and groups) for sorting
-        all_potential_items: List[Dict] = []
-        for unit in standalone_units:
-            all_potential_items.append(
-                {
-                    "type": "standalone",
-                    "score": unit.record.score,
-                    "timestamp": unit.record.timestamp,
-                    "tokens": unit.num_tokens,
-                    "item": unit,
-                }
-            )
-        for group in tool_call_groups.values():
-            all_potential_items.append(
-                {
-                    "type": "group",
-                    "score": max(u.record.score for u in group),
-                    "timestamp": max(u.record.timestamp for u in group),
-                    "tokens": sum(u.num_tokens for u in group),
-                    "item": group,
-                }
-            )
-
-        # Sort all potential items by score (high to low), then timestamp
-        all_potential_items.sort(key=lambda x: (-x["score"], -x["timestamp"]))
-
-        remaining_units: List[_ContextUnit] = []
-        current_tokens = system_tokens
-
-        for item_dict in all_potential_items:
-            item_type = item_dict["type"]
-            item = item_dict["item"]
-            item_tokens = item_dict["tokens"]
-
-            if current_tokens + item_tokens <= self.token_limit:
-                # The whole item (standalone or group) fits, so add it
-                if item_type == "standalone":
-                    remaining_units.append(item)
-                else:  # item_type == "group"
-                    remaining_units.extend(item)
-                current_tokens += item_tokens
-
-            elif item_type == "group":
-                # The group does not fit completely; try partial inclusion.
-                request_unit: Optional[_ContextUnit] = None
-                response_units: List[_ContextUnit] = []
-
-                for unit in item:
-                    # Assistant msg with `args` is the request
-                    if (
-                        isinstance(
-                            unit.record.memory_record.message,
-                            FunctionCallingMessage,
-                        )
-                        and unit.record.memory_record.message.args is not None
-                    ):
-                        request_unit = unit
-                    else:
-                        response_units.append(unit)
-
-                # A group must have a request to be considered for inclusion.
-                if request_unit is None:
-                    continue
-
-                # Check if we can at least fit the request.
-                if (
-                    current_tokens + request_unit.num_tokens
-                    <= self.token_limit
-                ):
-                    units_to_add = [request_unit]
-                    tokens_to_add = request_unit.num_tokens
-
-                    # Sort responses by timestamp to add newest chunks first
-                    response_units.sort(
-                        key=lambda u: u.record.timestamp, reverse=True
-                    )
+            remaining_records.append(record)
 
-                    for resp_unit in response_units:
-                        if (
-                            current_tokens
-                            + tokens_to_add
-                            + resp_unit.num_tokens
-                            <= self.token_limit
-                        ):
-                            units_to_add.append(resp_unit)
-                            tokens_to_add += resp_unit.num_tokens
+        remaining_records.sort(key=lambda record: record.timestamp)
 
-                    # A request must be followed by at least one response
-                    if len(units_to_add) > 1:
-                        remaining_units.extend(units_to_add)
-                        current_tokens += tokens_to_add
+        messages: List[OpenAIMessage] = []
+        if system_record is not None:
+            messages.append(system_record.memory_record.to_openai_message())
 
-        return remaining_units
-
-    def _extract_system_message(
-        self, records: List[ContextRecord]
-    ) -> Tuple[Optional[_ContextUnit], List[_ContextUnit]]:
-        r"""Extracts the system message from records and validates it.
-
-        Args:
-            records (List[ContextRecord]): List of context records
-                representing conversation history.
-
-        Returns:
-            Tuple[Optional[_ContextUnit], List[_ContextUnit]]: containing:
-            - The system message as a `_ContextUnit`, if valid; otherwise,
-                `None`.
-            - An empty list, serving as the initial container for regular
-                messages.
-        """
-        if not records:
-            return None, []
-
-        first_record = records[0]
-        if (
-            first_record.memory_record.role_at_backend
-            != OpenAIBackendRole.SYSTEM
-        ):
-            return None, []
-
-        message = first_record.memory_record.to_openai_message()
-        tokens = self.token_counter.count_tokens_from_messages([message])
-        system_message_unit = _ContextUnit(
-            idx=0,
-            record=first_record,
-            num_tokens=tokens,
+        messages.extend(
+            record.memory_record.to_openai_message()
+            for record in remaining_records
         )
-        return system_message_unit, []
-
-    def _conversation_sort_key(
-        self, unit: _ContextUnit
-    ) -> Tuple[float, float]:
-        r"""Defines the sorting key for assembling the final output.
-
-        Sorting priority:
-        - Primary: Sort by timestamp in ascending order (chronological order).
-        - Secondary: Sort by score in descending order (higher scores first
-            when timestamps are equal).
-
-        Args:
-            unit (_ContextUnit): A `_ContextUnit` representing a conversation
-                record.
-
-        Returns:
-            Tuple[float, float]:
-            - Timestamp for chronological sorting.
-            - Negative score for descending order sorting.
-        """
-        return (unit.record.timestamp, -unit.record.score)
-
-    def _assemble_output(
-        self,
-        context_units: List[_ContextUnit],
-        system_unit: Optional[_ContextUnit],
-    ) -> Tuple[List[OpenAIMessage], int]:
-        r"""Assembles final message list with proper ordering and token count.
-
-        Args:
-            context_units (List[_ContextUnit]): Sorted list of regular message
-                units.
-            system_unit (Optional[_ContextUnit]): System message unit (if
-                present).
-
-        Returns:
-            Tuple[List[OpenAIMessage], int]: Tuple of (ordered messages, total
-                tokens)
-        """
-        messages = []
-        total_tokens = 0
-
-        # Add system message first if present
-        if system_unit:
-            messages.append(
-                system_unit.record.memory_record.to_openai_message()
-            )
-            total_tokens += system_unit.num_tokens
 
-        # Add sorted regular messages
-        for unit in context_units:
-            messages.append(unit.record.memory_record.to_openai_message())
-            total_tokens += unit.num_tokens
+        if not messages:
+            return [], 0
 
+        total_tokens = self.token_counter.count_tokens_from_messages(messages)
         return messages, total_tokens

camel/memories/records.py

@@ -15,8 +15,8 @@
 # Enables postponed evaluation of annotations (for string-based type hints)
 from __future__ import annotations
 
+import inspect
 import time
-from dataclasses import asdict
 from typing import Any, ClassVar, Dict
 from uuid import UUID, uuid4
 
@@ -63,6 +63,20 @@ class MemoryRecord(BaseModel):
         "FunctionCallingMessage": FunctionCallingMessage,
     }
 
+    # Cache for constructor parameters (performance optimization)
+    _constructor_params_cache: ClassVar[Dict[str, set]] = {}
+
+    @classmethod
+    def _get_constructor_params(cls, message_cls) -> set:
+        """Get constructor parameters for a message class with caching."""
+        cls_name = message_cls.__name__
+        if cls_name not in cls._constructor_params_cache:
+            sig = inspect.signature(message_cls.__init__)
+            cls._constructor_params_cache[cls_name] = set(
+                sig.parameters.keys()
+            ) - {'self'}
+        return cls._constructor_params_cache[cls_name]
+
     @classmethod
     def from_dict(cls, record_dict: Dict[str, Any]) -> "MemoryRecord":
         r"""Reconstruct a :obj:`MemoryRecord` from the input dict.
@@ -70,14 +84,78 @@ class MemoryRecord(BaseModel):
         Args:
             record_dict(Dict[str, Any]): A dict generated by :meth:`to_dict`.
         """
+        from camel.types import OpenAIBackendRole, RoleType
+
         message_cls = cls._MESSAGE_TYPES[record_dict["message"]["__class__"]]
-        kwargs: Dict = record_dict["message"].copy()
-        kwargs.pop("__class__")
-        reconstructed_message = message_cls(**kwargs)
+        data = record_dict["message"].copy()
+        data.pop("__class__")
+
+        # Convert role_type string to enum
+        if "role_type" in data and isinstance(data["role_type"], str):
+            data["role_type"] = RoleType(data["role_type"])
+
+        # Deserialize image_list from base64 strings/URLs back to PIL Images/
+        # URLs
+        if "image_list" in data and data["image_list"] is not None:
+            import base64
+            from io import BytesIO
+
+            from PIL import Image
+
+            image_objects = []
+            for img_item in data["image_list"]:
+                if isinstance(img_item, dict):
+                    # New format with type indicator
+                    if img_item["type"] == "url":
+                        # URL string, keep as-is
+                        image_objects.append(img_item["data"])
+                    else:  # type == "base64"
+                        # Base64 encoded image, convert to PIL Image
+                        img_bytes = base64.b64decode(img_item["data"])
+                        img = Image.open(BytesIO(img_bytes))
+                        # Restore the format attribute if it was saved
+                        if "format" in img_item:
+                            img.format = img_item["format"]
+                        image_objects.append(img)
+                else:
+                    # Legacy format: assume it's a base64 string
+                    img_bytes = base64.b64decode(img_item)
+                    img = Image.open(BytesIO(img_bytes))
+                    image_objects.append(img)
+            data["image_list"] = image_objects
+
+        # Deserialize video_bytes from base64 string
+        if "video_bytes" in data and data["video_bytes"] is not None:
+            import base64
+
+            data["video_bytes"] = base64.b64decode(data["video_bytes"])
+
+        # Get valid constructor parameters (cached)
+        valid_params = cls._get_constructor_params(message_cls)
+
+        # Separate constructor args from extra fields
+        kwargs = {k: v for k, v in data.items() if k in valid_params}
+        extra_fields = {k: v for k, v in data.items() if k not in valid_params}
+
+        # Handle meta_dict properly: merge existing meta_dict with extra fields
+        existing_meta = kwargs.get("meta_dict", {}) or {}
+        if extra_fields:
+            # Extra fields take precedence, but preserve existing meta_dict
+            # structure
+            merged_meta = {**existing_meta, **extra_fields}
+            kwargs["meta_dict"] = merged_meta
+        elif not existing_meta:
+            kwargs["meta_dict"] = None
+
+        # Convert role_at_backend
+        role_at_backend = record_dict["role_at_backend"]
+        if isinstance(role_at_backend, str):
+            role_at_backend = OpenAIBackendRole(role_at_backend)
+
         return cls(
             uuid=UUID(record_dict["uuid"]),
-            message=reconstructed_message,
-            role_at_backend=record_dict["role_at_backend"],
+            message=message_cls(**kwargs),
+            role_at_backend=role_at_backend,
             extra_info=record_dict["extra_info"],
             timestamp=record_dict["timestamp"],
             agent_id=record_dict["agent_id"],
@@ -91,9 +169,11 @@ class MemoryRecord(BaseModel):
             "uuid": str(self.uuid),
             "message": {
                 "__class__": self.message.__class__.__name__,
-                **asdict(self.message),
+                **self.message.to_dict(),
             },
-            "role_at_backend": self.role_at_backend,
+            "role_at_backend": self.role_at_backend.value
+            if hasattr(self.role_at_backend, "value")
+            else self.role_at_backend,
             "extra_info": self.extra_info,
             "timestamp": self.timestamp,
             "agent_id": self.agent_id,