camel-ai 0.2.79a0__py3-none-any.whl → 0.2.79a1__py3-none-any.whl

camel/memories/agent_memories.py

@@ -129,6 +129,16 @@ class ChatHistoryMemory(AgentMemory):
         # Save the modified records back to storage
         self._chat_history_block.storage.save(record_dicts)
 
+    def pop_records(self, count: int) -> List[MemoryRecord]:
+        r"""Removes the most recent records from chat history memory."""
+        return self._chat_history_block.pop_records(count)
+
+    def remove_records_by_indices(
+        self, indices: List[int]
+    ) -> List[MemoryRecord]:
+        r"""Removes records at specified indices from chat history memory."""
+        return self._chat_history_block.remove_records_by_indices(indices)
+
 
 class VectorDBMemory(AgentMemory):
     r"""An agent memory wrapper of :obj:`VectorDBBlock`. This memory queries
@@ -193,6 +203,20 @@ class VectorDBMemory(AgentMemory):
         r"""Removes all records from the vector database memory."""
         self._vectordb_block.clear()
 
+    def pop_records(self, count: int) -> List[MemoryRecord]:
+        r"""Rolling back is unsupported for vector database memory."""
+        raise NotImplementedError(
+            "VectorDBMemory does not support removing historical records."
+        )
+
+    def remove_records_by_indices(
+        self, indices: List[int]
+    ) -> List[MemoryRecord]:
+        r"""Removing by indices is unsupported for vector database memory."""
+        raise NotImplementedError(
+            "VectorDBMemory does not support removing records by indices."
+        )
+
 
 class LongtermAgentMemory(AgentMemory):
     r"""An implementation of the :obj:`AgentMemory` abstract base class for
@@ -277,3 +301,13 @@ class LongtermAgentMemory(AgentMemory):
         r"""Removes all records from the memory."""
         self.chat_history_block.clear()
         self.vector_db_block.clear()
+
+    def pop_records(self, count: int) -> List[MemoryRecord]:
+        r"""Removes recent chat history records while leaving vector memory."""
+        return self.chat_history_block.pop_records(count)
+
+    def remove_records_by_indices(
+        self, indices: List[int]
+    ) -> List[MemoryRecord]:
+        r"""Removes records at specified indices from chat history."""
+        return self.chat_history_block.remove_records_by_indices(indices)

camel/memories/base.py

@@ -45,6 +45,32 @@ class MemoryBlock(ABC):
         """
         self.write_records([record])
 
+    def pop_records(self, count: int) -> List[MemoryRecord]:
+        r"""Removes records from the memory and returns the removed records.
+
+        Args:
+            count (int): Number of records to remove.
+
+        Returns:
+            List[MemoryRecord]: The records that were removed from the memory
+                in their original order.
+        """
+        raise NotImplementedError
+
+    def remove_records_by_indices(
+        self, indices: List[int]
+    ) -> List[MemoryRecord]:
+        r"""Removes records at specified indices from the memory.
+
+        Args:
+            indices (List[int]): List of indices to remove. Indices should be
+                valid positions in the current record list.
+
+        Returns:
+            List[MemoryRecord]: The removed records in their original order.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     def clear(self) -> None:
         r"""Clears all messages from the memory."""

camel/memories/blocks/chat_history_block.py

@@ -167,3 +167,118 @@ class ChatHistoryBlock(MemoryBlock):
     def clear(self) -> None:
         r"""Clears all chat messages from the memory."""
         self.storage.clear()
+
+    def pop_records(self, count: int) -> List[MemoryRecord]:
+        r"""Removes the most recent records from the memory.
+
+        Args:
+            count (int): Number of records to remove from the end of the
+                conversation history. A value of 0 results in no changes.
+
+        Returns:
+            List[MemoryRecord]: The removed records in chronological order.
+        """
+        if not isinstance(count, int):
+            raise TypeError("`count` must be an integer.")
+        if count < 0:
+            raise ValueError("`count` must be non-negative.")
+        if count == 0:
+            return []
+
+        record_dicts = self.storage.load()
+        if not record_dicts:
+            return []
+
+        # Preserve initial system/developer instruction if present.
+        protected_prefix = (
+            1
+            if (
+                record_dicts
+                and record_dicts[0]['role_at_backend']
+                in {
+                    OpenAIBackendRole.SYSTEM.value,
+                    OpenAIBackendRole.DEVELOPER.value,
+                }
+            )
+            else 0
+        )
+
+        removable_count = max(len(record_dicts) - protected_prefix, 0)
+        if removable_count == 0:
+            return []
+
+        pop_count = min(count, removable_count)
+        split_index = len(record_dicts) - pop_count
+
+        popped_dicts = record_dicts[split_index:]
+        remaining_dicts = record_dicts[:split_index]
+
+        self.storage.clear()
+        if remaining_dicts:
+            self.storage.save(remaining_dicts)
+
+        return [MemoryRecord.from_dict(record) for record in popped_dicts]
+
+    def remove_records_by_indices(
+        self, indices: List[int]
+    ) -> List[MemoryRecord]:
+        r"""Removes records at specified indices from the memory.
+
+        Args:
+            indices (List[int]): List of indices to remove. Indices are
+                positions in the current record list (0-based).
+                System/developer messages at index 0 are protected and will
+                not be removed.
+
+        Returns:
+            List[MemoryRecord]: The removed records in their original order.
+        """
+        if not indices:
+            return []
+
+        record_dicts = self.storage.load()
+        if not record_dicts:
+            return []
+
+        # Preserve initial system/developer instruction if present.
+        protected_prefix = (
+            1
+            if (
+                record_dicts
+                and record_dicts[0]['role_at_backend']
+                in {
+                    OpenAIBackendRole.SYSTEM.value,
+                    OpenAIBackendRole.DEVELOPER.value,
+                }
+            )
+            else 0
+        )
+
+        # Filter out protected indices and invalid ones
+        valid_indices = sorted(
+            {
+                idx
+                for idx in indices
+                if idx >= protected_prefix and idx < len(record_dicts)
+            }
+        )
+
+        if not valid_indices:
+            return []
+
+        # Extract records to remove (in original order)
+        removed_records = [record_dicts[idx] for idx in valid_indices]
+
+        # Build remaining records by excluding removed indices
+        remaining_dicts = [
+            record
+            for idx, record in enumerate(record_dicts)
+            if idx not in valid_indices
+        ]
+
+        # Save back to storage
+        self.storage.clear()
+        if remaining_dicts:
+            self.storage.save(remaining_dicts)
+
+        return [MemoryRecord.from_dict(record) for record in removed_records]

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/messages/base.py

@@ -178,6 +178,32 @@ class BaseMessage:
             OpenAIVisionDetailType(video_detail).value,
         )
 
+    @classmethod
+    def make_system_message(
+        cls,
+        content: str,
+        role_name: str = "System",
+        meta_dict: Optional[Dict[str, str]] = None,
+    ) -> "BaseMessage":
+        r"""Create a new system message.
+
+        Args:
+            content (str): The content of the system message.
+            role_name (str): The name of the system role.
+                (default: :obj:`"System"`)
+            meta_dict (Optional[Dict[str, str]]): Additional metadata
+                dictionary for the message.
+
+        Returns:
+            BaseMessage: The new system message.
+        """
+        return cls(
+            role_name,
+            RoleType.SYSTEM,
+            meta_dict,
+            content,
+        )
+
     def create_new_instance(self, content: str) -> "BaseMessage":
         r"""Create a new instance of the :obj:`BaseMessage` with updated
         content.