camel-ai 0.2.76a0__py3-none-any.whl → 0.2.76a2__py3-none-any.whl

camel/utils/context_utils.py

@@ -0,0 +1,395 @@
+# ========= 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 os
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from camel.logger import get_logger
+
+if TYPE_CHECKING:
+    from camel.agents import ChatAgent
+    from camel.memories.records import MemoryRecord
+
+logger = get_logger(__name__)
+
+
+class ContextUtility:
+    r"""Utility class for context management and file operations.
+
+    This utility provides generic functionality for managing context files,
+    markdown generation, and session management that can be used by
+    context-related features.
+
+    Key features:
+    - Session-based directory management
+    - Generic markdown file operations
+    - Text-based search through files
+    - File metadata handling
+    - Agent memory record retrieval
+    """
+
+    def __init__(self, working_directory: Optional[str] = None):
+        r"""Initialize the ContextUtility.
+
+        Args:
+            working_directory (str, optional): The directory path where files
+                will be stored. If not provided, a default directory will be
+                used.
+        """
+        self.working_directory_param = working_directory
+        self._setup_storage(working_directory)
+
+    def _setup_storage(self, working_directory: Optional[str]) -> None:
+        r"""Initialize session-specific storage paths and create directory
+        structure for context file management."""
+        self.session_id = self._generate_session_id()
+
+        if working_directory:
+            self.working_directory = Path(working_directory).resolve()
+        else:
+            camel_workdir = os.environ.get("CAMEL_WORKDIR")
+            if camel_workdir:
+                self.working_directory = Path(camel_workdir) / "context_files"
+            else:
+                self.working_directory = Path("context_files")
+
+        # Create session-specific directory
+        self.working_directory = self.working_directory / self.session_id
+        self.working_directory.mkdir(parents=True, exist_ok=True)
+
+    def _generate_session_id(self) -> str:
+        r"""Create timestamp-based unique identifier for isolating
+        current session files from other sessions."""
+        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S_%f')
+        return f"session_{timestamp}"
+
+    # ========= GENERIC FILE MANAGEMENT METHODS =========
+
+    def _create_or_update_note(self, note_name: str, content: str) -> str:
+        r"""Write content to markdown file, creating new file or
+        overwriting existing one with UTF-8 encoding.
+
+        Args:
+            note_name (str): Name of the note (without .md extension).
+            content (str): Content to write to the note.
+
+        Returns:
+            str: Success message.
+        """
+        try:
+            file_path = self.working_directory / f"{note_name}.md"
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+            return f"Note '{note_name}.md' created successfully"
+        except Exception as e:
+            logger.error(f"Error creating note {note_name}: {e}")
+            return f"Error creating note: {e}"
+
+    def save_markdown_file(
+        self,
+        filename: str,
+        content: str,
+        title: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        r"""Generic method to save any markdown content to a file.
+
+        Args:
+            filename (str): Name without .md extension.
+            content (str): Main content to save.
+            title (str, optional): Title for the markdown file.
+            metadata (Dict, optional): Additional metadata to include.
+
+        Returns:
+            str: Success message or error message.
+        """
+        try:
+            markdown_content = ""
+
+            # Add title if provided
+            if title:
+                markdown_content += f"# {title}\n\n"
+
+            # Add metadata section if provided
+            if metadata:
+                markdown_content += "## Metadata\n\n"
+                for key, value in metadata.items():
+                    markdown_content += f"- {key}: {value}\n"
+                markdown_content += "\n"
+
+            # Add main content
+            markdown_content += content
+
+            self._create_or_update_note(filename, markdown_content)
+            logger.info(
+                f"Markdown file saved to "
+                f"{self.working_directory / f'{filename}.md'}"
+            )
+            return f"Markdown file '{filename}.md' saved successfully"
+
+        except Exception as e:
+            logger.error(f"Error saving markdown file {filename}: {e}")
+            return f"Error saving markdown file: {e}"
+
+    def load_markdown_file(self, filename: str) -> str:
+        r"""Generic method to load any markdown file.
+
+        Args:
+            filename (str): Name without .md extension.
+
+        Returns:
+            str: File content or empty string if not found.
+        """
+        try:
+            file_path = self.working_directory / f"{filename}.md"
+            if file_path.exists():
+                return file_path.read_text(encoding="utf-8")
+            return ""
+        except Exception as e:
+            logger.error(f"Error loading markdown file {filename}: {e}")
+            return ""
+
+    def file_exists(self, filename: str) -> bool:
+        r"""Verify presence of markdown file in current session directory.
+
+        Args:
+            filename (str): Name without .md extension.
+
+        Returns:
+            bool: True if file exists, False otherwise.
+        """
+        file_path = self.working_directory / f"{filename}.md"
+        return file_path.exists()
+
+    def list_markdown_files(self) -> List[str]:
+        r"""Discover all markdown files in current session directory
+        and return their base names for reference.
+
+        Returns:
+            List[str]: List of filenames without .md extension.
+        """
+        try:
+            md_files = list(self.working_directory.glob("*.md"))
+            return [f.stem for f in md_files]
+        except Exception as e:
+            logger.error(f"Error listing markdown files: {e}")
+            return []
+
+    # ========= GENERIC AGENT MEMORY METHODS =========
+
+    def get_agent_memory_records(
+        self, agent: "ChatAgent"
+    ) -> List["MemoryRecord"]:
+        r"""Retrieve conversation history from agent's memory system.
+
+        Args:
+            agent (ChatAgent): The agent to extract memory records from.
+
+        Returns:
+            List[MemoryRecord]: List of memory records from the agent.
+        """
+        try:
+            context_records = agent.memory.retrieve()
+            return [cr.memory_record for cr in context_records]
+        except Exception as e:
+            logger.error(f"Error extracting memory records: {e}")
+            return []
+
+    def format_memory_as_conversation(
+        self, memory_records: List["MemoryRecord"]
+    ) -> str:
+        r"""Transform structured memory records into human-readable
+        conversation format with role labels and message content.
+
+        Args:
+            memory_records (List[MemoryRecord]): Memory records to format.
+
+        Returns:
+            str: Formatted conversation text.
+        """
+        conversation_lines = []
+
+        for record in memory_records:
+            role = (
+                record.role_at_backend.value
+                if hasattr(record.role_at_backend, 'value')
+                else str(record.role_at_backend)
+            )
+            content = record.message.content
+            conversation_lines.append(f"{role}: {content}")
+
+        return "\n".join(conversation_lines)
+
+    # ========= SESSION MANAGEMENT METHODS =========
+
+    def create_session_directory(
+        self, base_dir: Optional[str] = None, session_id: Optional[str] = None
+    ) -> Path:
+        r"""Create a session-specific directory.
+
+        Args:
+            base_dir (str, optional): Base directory. If None, uses current
+                working directory.
+            session_id (str, optional): Custom session ID. If None, generates
+                new one.
+
+        Returns:
+            Path: The created session directory path.
+        """
+        if session_id is None:
+            session_id = self._generate_session_id()
+
+        if base_dir:
+            base_path = Path(base_dir).resolve()
+        else:
+            base_path = self.working_directory.parent
+
+        session_dir = base_path / session_id
+        session_dir.mkdir(parents=True, exist_ok=True)
+        return session_dir
+
+    def get_session_metadata(self) -> Dict[str, Any]:
+        r"""Collect comprehensive session information including identifiers,
+        timestamps, and directory paths for tracking and reference.
+
+        Returns:
+            Dict[str, Any]: Session metadata including ID, timestamp,
+                directory.
+        """
+        return {
+            'session_id': self.session_id,
+            'working_directory': str(self.working_directory),
+            'created_at': datetime.now().isoformat(),
+            'base_directory': str(self.working_directory.parent),
+        }
+
+    def list_sessions(self, base_dir: Optional[str] = None) -> List[str]:
+        r"""Discover all available session directories for browsing
+        historical conversations and context files.
+
+        Args:
+            base_dir (str, optional): Base directory to search. If None, uses
+                parent of working directory.
+
+        Returns:
+            List[str]: List of session directory names.
+        """
+        try:
+            if base_dir:
+                search_dir = Path(base_dir)
+            else:
+                search_dir = self.working_directory.parent
+
+            session_dirs = [
+                d.name
+                for d in search_dir.iterdir()
+                if d.is_dir() and d.name.startswith('session_')
+            ]
+            return sorted(session_dirs)
+        except Exception as e:
+            logger.error(f"Error listing sessions: {e}")
+            return []
+
+    # ========= GENERIC SEARCH METHODS =========
+
+    def search_in_file(
+        self, file_path: Path, keywords: List[str], top_k: int = 4
+    ) -> str:
+        r"""Perform keyword-based search through file sections,
+        ranking results by keyword frequency and returning top matches.
+
+        Args:
+            file_path (Path): Path to the file to search.
+            keywords (List[str]): Keywords to search for.
+            top_k (int): Maximum number of results to return.
+
+        Returns:
+            str: Formatted search results.
+        """
+        results: List[Dict[str, Any]] = []
+        keyword_terms = [keyword.lower() for keyword in keywords]
+
+        try:
+            if not file_path.exists():
+                return ""
+
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+
+            # Split content into sections (assuming ### headers)
+            sections = content.split('### ')[1:]  # Skip the header part
+
+            for i, section in enumerate(sections):
+                if not section.strip():
+                    continue
+
+                section_lower = section.lower()
+
+                # count how many keywords appear in this section
+                keyword_matches = sum(
+                    1 for keyword in keyword_terms if keyword in section_lower
+                )
+
+                if keyword_matches > 0:
+                    results.append(
+                        {
+                            'content': f"### {section.strip()}",
+                            'keyword_count': keyword_matches,
+                            'section_num': i + 1,
+                        }
+                    )
+
+        except Exception as e:
+            logger.warning(f"Error reading file {file_path}: {e}")
+            return ""
+
+        # sort by keyword count and limit results
+        results.sort(key=lambda x: x['keyword_count'], reverse=True)
+        results = results[:top_k]
+
+        if not results:
+            return ""
+
+        # format results
+        formatted_sections = []
+        for result in results:
+            formatted_sections.append(
+                f"Section {result['section_num']} "
+                f"(keyword matches: {result['keyword_count']}):\n"
+                f"{result['content']}\n"
+            )
+
+        return "\n---\n".join(formatted_sections)
+
+    # ========= UTILITY METHODS =========
+
+    def get_working_directory(self) -> Path:
+        r"""Retrieve the session-specific directory path where
+        all context files are stored.
+
+        Returns:
+            Path: The working directory path.
+        """
+        return self.working_directory
+
+    def get_session_id(self) -> str:
+        r"""Retrieve the unique identifier for the current session
+        used for file organization and tracking.
+
+        Returns:
+            str: The session ID.
+        """
+        return self.session_id

{camel_ai-0.2.76a0.dist-info → camel_ai-0.2.76a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: camel-ai
-Version: 0.2.76a0
+Version: 0.2.76a2
 Summary: Communicative Agents for AI Society Study
 Project-URL: Homepage, https://www.camel-ai.org/
 Project-URL: Repository, https://github.com/camel-ai/camel
@@ -57,6 +57,7 @@ Requires-Dist: flask>=2.0; extra == 'all'
 Requires-Dist: google-api-python-client==2.166.0; extra == 'all'
 Requires-Dist: google-auth-httplib2==0.2.0; extra == 'all'
 Requires-Dist: google-auth-oauthlib==1.2.1; extra == 'all'
+Requires-Dist: google-cloud-aiplatform>=1.111.0; extra == 'all'
 Requires-Dist: google-cloud-storage<3,>=2.18.0; extra == 'all'
 Requires-Dist: google-genai>=1.13.0; extra == 'all'
 Requires-Dist: googlemaps<5,>=4.10.0; extra == 'all'
@@ -447,12 +448,52 @@ Join us ([*Discord*](https://discord.camel-ai.org/) or [*WeChat*](https://ghli.o
 </div>
 
 <div align="center">
-    <img src="docs/images/star.gif" alt="Star" width="186" height="60">
+    <img src="docs/images/stars.gif" alt="Star">
   </a>
 </div>
 
 <br>
 
+<details>
+<summary><kbd>Table of contents</kbd></summary>
+
+<br/>
+
+- [CAMEL Framework Design Principles](#camel-framework-design-principles)
+- [Why Use CAMEL for Your Research?](#why-use-camel-for-your-research)
+- [What Can You Build With CAMEL?](#what-can-you-build-with-camel)
+  - [Data Generation](#1-data-generation)
+  - [Task Automation](#2-task-automation)
+  - [World Simulation](#3-world-simulation)
+- [Quick Start](#quick-start)
+  - [Starting with ChatAgent](#starting-with-chatagent)
+  - [Seeking Help](#seeking-help)
+- [Tech Stack](#tech-stack)
+- [Research](#research)
+- [Synthetic Datasets](#synthetic-datasets)
+- [Cookbooks (Usecases)](#cookbooks-usecases)
+  - [Basic Concepts](#1-basic-concepts)
+  - [Advanced Features](#2-advanced-features)
+  - [Model Training & Data Generation](#3-model-training--data-generation)
+  - [Multi-Agent Systems & Applications](#4-multi-agent-systems--applications)
+  - [Data Processing](#5-data-processing)
+- [Real-World Usecases](#real-world-usecases)
+- [🧱 Built with CAMEL (Real-world Producs & Research)](#-built-with-camel-real-world-producs--research)
+  - [Research Projects](#research-projects)
+  - [Product Projects](#product-projects)
+- [🗓️ Events](#️-events)
+- [Contributing to CAMEL](#contributing-to-camel)
+- [Community & Contact](#community--contact)
+- [Citation](#citation)
+- [Acknowledgment](#acknowledgment)
+- [License](#license)
+
+####
+
+<br/>
+
+</details>
+
 
 ## CAMEL Framework Design Principles
 
@@ -686,6 +727,18 @@ We believe that studying these agents on a large scale offers valuable insights
 
 **Explore our research projects:**
 
+<div align="center">
+  <a href="https://github.com/camel-ai/owl">
+    <img src="docs/images/owl.png" alt="OWL">
+  </a>
+</div>
+
+<div align="center">
+  <a href="https://oasis.camel-ai.org/">
+    <img src="docs/images/oasis.png" alt="OASIS">
+  </a>
+</div>
+
 <div align="center">
   <a href="https://crab.camel-ai.org/">
     <img src="docs/images/crab.png" alt="CRAB">
@@ -693,14 +746,14 @@ We believe that studying these agents on a large scale offers valuable insights
 </div>
 
 <div align="center">
-  <a href="https://agent-trust.camel-ai.org/">
-    <img src="docs/images/agent_trust.png" alt="Agent Trust">
+  <a href="https://github.com/camel-ai/loong">
+    <img src="docs/images/loong.png" alt="Loong">
   </a>
 </div>
 
 <div align="center">
-  <a href="https://oasis.camel-ai.org/">
-    <img src="docs/images/oasis.png" alt="OASIS">
+  <a href="https://agent-trust.camel-ai.org/">
+    <img src="docs/images/agent_trust.png" alt="Agent Trust">
   </a>
 </div>
 
@@ -834,6 +887,31 @@ Real-world usecases demonstrating how CAMEL’s multi-agent framework enables re
 
 <br>
 
+## 🧱 Built with CAMEL (Real-world Producs & Research)
+<div align="left">
+  <a href="https://www.camel-ai.org/">
+    <img src="docs/images/built_with_CAMEL.png" alt="Built with CAMEL" height="40px">
+  </a>
+</div>
+
+### Research Projects
+
+| Name | Description |
+|:---|:---|
+| **[ChatDev](https://github.com/OpenBMB/ChatDev/tree/main/camel)** | Communicative Agents for software Development |
+| **[Paper2Poster](https://github.com/Paper2Poster/Paper2Poster)** | Multimodal poster automation from scientific papers |
+
+### Product Projects
+
+| Name | Description |
+|:---|:---|
+| **[Eigent](https://www.eigent.ai/)** | The World First Multi-agent Workforce |
+| **[EigentBot](https://bot.eigent.ai/)** | One EigentBot,
+Every Code Answer |
+| **[Matrix](https://matrix.eigent.ai/)** | Social Media Simulation |
+| **[AI Geometric](https://www.linkedin.com/posts/aigeometric_ai-interviewpreparation-careerdevelopment-activity-7261428422516555776-MtaK/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAChHluEB9xRwkjiJ6VSAzqM2Y-U4NI2sKGY)** | AI-powered interview copilot |
+| **[Log10](https://github.com/log10-io/log10/blob/main/src/log10/agents/camel.py)** | AI accuracy, delivered |
+
 
 ## 🗓️ Events