camel-ai 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

camel/models/base_model.py

@@ -12,7 +12,7 @@
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
 
 from openai import Stream
 
@@ -27,17 +27,23 @@ class BaseModelBackend(ABC):
     """
 
     def __init__(
-        self, model_type: ModelType, model_config_dict: Dict[str, Any]
+        self,
+        model_type: ModelType,
+        model_config_dict: Dict[str, Any],
+        api_key: Optional[str] = None,
     ) -> None:
         r"""Constructor for the model backend.
 
         Args:
             model_type (ModelType): Model for which a backend is created.
             model_config_dict (Dict[str, Any]): A config dictionary.
+            api_key (Optional[str]): The API key for authenticating with the
+                LLM service.
         """
         self.model_type = model_type
 
         self.model_config_dict = model_config_dict
+        self._api_key = api_key
         self.check_model_config()
 
     @property

camel/models/model_factory.py

@@ -11,7 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from camel.models.anthropic_model import AnthropicModel
 from camel.models.base_model import BaseModelBackend
@@ -30,7 +30,9 @@ class ModelFactory:
 
     @staticmethod
     def create(
-        model_type: ModelType, model_config_dict: Dict
+        model_type: ModelType,
+        model_config_dict: Dict,
+        api_key: Optional[str] = None,
     ) -> BaseModelBackend:
         r"""Creates an instance of `BaseModelBackend` of the specified type.
 
@@ -38,6 +40,8 @@ class ModelFactory:
             model_type (ModelType): Model for which a backend is created.
             model_config_dict (Dict): A dictionary that will be fed into
                 the backend constructor.
+            api_key (Optional[str]): The API key for authenticating with the
+                LLM service.
 
         Raises:
             ValueError: If there is not backend for the model.
@@ -57,5 +61,5 @@ class ModelFactory:
         else:
             raise ValueError(f"Unknown model type `{model_type}` is input")
 
-        inst = model_class(model_type, model_config_dict)
+        inst = model_class(model_type, model_config_dict, api_key)
         return inst

camel/models/openai_audio_models.py

@@ -0,0 +1,251 @@
+# =========== Copyright 2023 @ 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 @ CAMEL-AI.org. All Rights Reserved. ===========
+import os
+from typing import Any, List, Optional, Union
+
+from openai import OpenAI, _legacy_response
+
+from camel.types import AudioModelType, VoiceType
+
+
+class OpenAIAudioModels:
+    r"""Provides access to OpenAI's Text-to-Speech (TTS) and Speech_to_Text
+    (STT) models."""
+
+    def __init__(
+        self,
+    ) -> None:
+        r"""Initialize an instance of OpenAI."""
+        url = os.environ.get('OPENAI_API_BASE_URL')
+        self._client = OpenAI(timeout=120, max_retries=3, base_url=url)
+
+    def text_to_speech(
+        self,
+        input: str,
+        model_type: AudioModelType = AudioModelType.TTS_1,
+        voice: VoiceType = VoiceType.ALLOY,
+        storage_path: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Union[
+        List[_legacy_response.HttpxBinaryResponseContent],
+        _legacy_response.HttpxBinaryResponseContent,
+    ]:
+        r"""Convert text to speech using OpenAI's TTS model. This method
+        converts the given input text to speech using the specified model and
+        voice.
+
+        Args:
+            input (str): The text to be converted to speech.
+            model_type (AudioModelType, optional): The TTS model to use.
+                Defaults to `AudioModelType.TTS_1`.
+            voice (VoiceType, optional): The voice to be used for generating
+                speech. Defaults to `VoiceType.ALLOY`.
+            storage_path (str, optional): The local path to store the
+                generated speech file if provided, defaults to `None`.
+            **kwargs (Any): Extra kwargs passed to the TTS API.
+
+        Returns:
+            Union[List[_legacy_response.HttpxBinaryResponseContent],
+                _legacy_response.HttpxBinaryResponseContent]: List of response
+                content object from OpenAI if input charaters more than 4096,
+                single response content if input charaters less than 4096.
+
+        Raises:
+            Exception: If there's an error during the TTS API call.
+        """
+        try:
+            # Model only support at most 4096 characters one time.
+            max_chunk_size = 4095
+            audio_chunks = []
+            chunk_index = 0
+            if len(input) > max_chunk_size:
+                while input:
+                    if len(input) <= max_chunk_size:
+                        chunk = input
+                        input = ''
+                    else:
+                        # Find the nearest period before the chunk size limit
+                        while input[max_chunk_size - 1] != '.':
+                            max_chunk_size -= 1
+
+                        chunk = input[:max_chunk_size]
+                        input = input[max_chunk_size:].lstrip()
+
+                    response = self._client.audio.speech.create(
+                        model=model_type.value,
+                        voice=voice.value,
+                        input=chunk,
+                        **kwargs,
+                    )
+                    if storage_path:
+                        try:
+                            # Create a new storage path for each chunk
+                            file_name, file_extension = os.path.splitext(
+                                storage_path
+                            )
+                            new_storage_path = (
+                                f"{file_name}_{chunk_index}{file_extension}"
+                            )
+                            response.write_to_file(new_storage_path)
+                            chunk_index += 1
+                        except Exception as e:
+                            raise Exception(
+                                "Error during writing the file"
+                            ) from e
+
+                    audio_chunks.append(response)
+                return audio_chunks
+
+            else:
+                response = self._client.audio.speech.create(
+                    model=model_type.value,
+                    voice=voice.value,
+                    input=input,
+                    **kwargs,
+                )
+
+            if storage_path:
+                try:
+                    response.write_to_file(storage_path)
+                except Exception as e:
+                    raise Exception("Error during write the file") from e
+
+            return response
+
+        except Exception as e:
+            raise Exception("Error during TTS API call") from e
+
+    def _split_audio(
+        self, audio_file_path: str, chunk_size_mb: int = 24
+    ) -> list:
+        r"""Split the audio file into smaller chunks. Since the Whisper API
+        only supports files that are less than 25 MB.
+
+        Args:
+            audio_file_path (str): Path to the input audio file.
+            chunk_size_mb (int, optional): Size of each chunk in megabytes.
+                Defaults to `24`.
+
+        Returns:
+            list: List of paths to the split audio files.
+        """
+        from pydub import AudioSegment
+
+        audio = AudioSegment.from_file(audio_file_path)
+        audio_format = os.path.splitext(audio_file_path)[1][1:].lower()
+
+        # Calculate chunk size in bytes
+        chunk_size_bytes = chunk_size_mb * 1024 * 1024
+
+        # Number of chunks needed
+        num_chunks = os.path.getsize(audio_file_path) // chunk_size_bytes + 1
+
+        # Create a directory to store the chunks
+        output_dir = os.path.splitext(audio_file_path)[0] + "_chunks"
+        os.makedirs(output_dir, exist_ok=True)
+
+        # Get audio chunk len in milliseconds
+        chunk_size_milliseconds = len(audio) // (num_chunks)
+
+        # Split the audio into chunks
+        split_files = []
+        for i in range(num_chunks):
+            start = i * chunk_size_milliseconds
+            end = (i + 1) * chunk_size_milliseconds
+            if i + 1 == num_chunks:
+                chunk = audio[start:]
+            else:
+                chunk = audio[start:end]
+            # Create new chunk path
+            chunk_path = os.path.join(output_dir, f"chunk_{i}.{audio_format}")
+            chunk.export(chunk_path, format=audio_format)
+            split_files.append(chunk_path)
+        return split_files
+
+    def speech_to_text(
+        self,
+        audio_file_path: str,
+        translate_into_english: bool = False,
+        **kwargs: Any,
+    ) -> str:
+        r"""Convert speech audio to text.
+
+        Args:
+            audio_file_path (str): The audio file path, supporting one of
+                these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or
+                webm.
+            translate_into_english (bool, optional): Whether to translate the
+                speech into English. Defaults to `False`.
+            **kwargs (Any): Extra keyword arguments passed to the
+                Speech-to-Text (STT) API.
+
+        Returns:
+            str: The output text.
+
+        Raises:
+            ValueError: If the audio file format is not supported.
+            Exception: If there's an error during the STT API call.
+        """
+        supported_formats = [
+            "flac",
+            "mp3",
+            "mp4",
+            "mpeg",
+            "mpga",
+            "m4a",
+            "ogg",
+            "wav",
+            "webm",
+        ]
+        file_format = audio_file_path.split(".")[-1].lower()
+
+        if file_format not in supported_formats:
+            raise ValueError(f"Unsupported audio file format: {file_format}")
+        try:
+            if os.path.getsize(audio_file_path) > 24 * 1024 * 1024:
+                # Split audio into chunks
+                audio_chunks = self._split_audio(audio_file_path)
+                texts = []
+                for chunk_path in audio_chunks:
+                    audio_data = open(chunk_path, "rb")
+                    if translate_into_english:
+                        translation = self._client.audio.translations.create(
+                            model="whisper-1", file=audio_data, **kwargs
+                        )
+                        texts.append(translation.text)
+                    else:
+                        transcription = (
+                            self._client.audio.transcriptions.create(
+                                model="whisper-1", file=audio_data, **kwargs
+                            )
+                        )
+                        texts.append(transcription.text)
+                    os.remove(chunk_path)  # Delete temporary chunk file
+                return " ".join(texts)
+            else:
+                # Process the entire audio file
+                audio_data = open(audio_file_path, "rb")
+
+                if translate_into_english:
+                    translation = self._client.audio.translations.create(
+                        model="whisper-1", file=audio_data, **kwargs
+                    )
+                    return translation.text
+                else:
+                    transcription = self._client.audio.transcriptions.create(
+                        model="whisper-1", file=audio_data, **kwargs
+                    )
+                    return transcription.text
+        except Exception as e:
+            raise Exception("Error during STT API call") from e

camel/models/openai_model.py

@@ -16,7 +16,7 @@ from typing import Any, Dict, List, Optional, Union
 
 from openai import OpenAI, Stream
 
-from camel.configs import OPENAI_API_PARAMS_WITH_FUNCTIONS
+from camel.configs import OPENAI_API_PARAMS
 from camel.messages import OpenAIMessage
 from camel.models import BaseModelBackend
 from camel.types import ChatCompletion, ChatCompletionChunk, ModelType
@@ -27,7 +27,10 @@ class OpenAIModel(BaseModelBackend):
     r"""OpenAI API in a unified BaseModelBackend interface."""
 
     def __init__(
-        self, model_type: ModelType, model_config_dict: Dict[str, Any]
+        self,
+        model_type: ModelType,
+        model_config_dict: Dict[str, Any],
+        api_key: Optional[str] = None,
     ) -> None:
         r"""Constructor for OpenAI backend.
 
@@ -36,10 +39,15 @@ class OpenAIModel(BaseModelBackend):
                 one of GPT_* series.
             model_config_dict (Dict[str, Any]): A dictionary that will
                 be fed into openai.ChatCompletion.create().
+            api_key (Optional[str]): The API key for authenticating with the
+                OpenAI service. (default: :obj:`None`)
         """
         super().__init__(model_type, model_config_dict)
         url = os.environ.get('OPENAI_API_BASE_URL', None)
-        self._client = OpenAI(timeout=60, max_retries=3, base_url=url)
+        self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        self._client = OpenAI(
+            timeout=60, max_retries=3, base_url=url, api_key=self._api_key
+        )
         self._token_counter: Optional[BaseTokenCounter] = None
 
     @property
@@ -86,7 +94,7 @@ class OpenAIModel(BaseModelBackend):
                 unexpected arguments to OpenAI API.
         """
         for param in self.model_config_dict:
-            if param not in OPENAI_API_PARAMS_WITH_FUNCTIONS:
+            if param not in OPENAI_API_PARAMS:
                 raise ValueError(
                     f"Unexpected argument `{param}` is "
                     "input into OpenAI model backend."

camel/models/stub_model.py

@@ -50,11 +50,15 @@ class StubModel(BaseModelBackend):
     model_type = ModelType.STUB
 
     def __init__(
-        self, model_type: ModelType, model_config_dict: Dict[str, Any]
+        self,
+        model_type: ModelType,
+        model_config_dict: Dict[str, Any],
+        api_key: Optional[str] = None,
     ) -> None:
         r"""All arguments are unused for the dummy model."""
         super().__init__(model_type, model_config_dict)
         self._token_counter: Optional[BaseTokenCounter] = None
+        self._api_key = api_key
 
     @property
     def token_counter(self) -> BaseTokenCounter:

camel/retrievers/__init__.py

@@ -14,6 +14,7 @@
 from .auto_retriever import AutoRetriever
 from .base import BaseRetriever
 from .bm25_retriever import BM25Retriever
+from .cohere_rerank_retriever import CohereRerankRetriever
 from .vector_retriever import VectorRetriever
 
 __all__ = [
@@ -21,4 +22,5 @@ __all__ = [
     'VectorRetriever',
     'AutoRetriever',
     'BM25Retriever',
+    'CohereRerankRetriever',
 ]

camel/retrievers/auto_retriever.py

@@ -63,7 +63,8 @@ class AutoRetriever:
         self,
         collection_name: Optional[str] = None,
     ) -> BaseVectorStorage:
-        r"""Sets up and returns a vector storage instance with specified parameters.
+        r"""Sets up and returns a vector storage instance with specified
+        parameters.
 
         Args:
             collection_name (Optional[str]): Name of the collection in the
@@ -195,7 +196,8 @@ class AutoRetriever:
         similarity_threshold: float = DEFAULT_SIMILARITY_THRESHOLD,
         return_detailed_info: bool = False,
     ) -> str:
-        r"""Executes the automatic vector retriever process using vector storage.
+        r"""Executes the automatic vector retriever process using vector
+        storage.
 
         Args:
             query (str): Query string for information retriever.
@@ -233,9 +235,7 @@ class AutoRetriever:
 
         vr = VectorRetriever()
 
-        retrieved_infos = ""
-        retrieved_infos_text = ""
-
+        all_retrieved_info = []
         for content_input_path in content_input_paths:
             # Generate a valid collection name
             collection_name = self._collection_name_generator(
@@ -278,42 +278,53 @@ class AutoRetriever:
                     # Clear the vector storage
                     vector_storage_instance.clear()
                     # Process and store the content to the vector storage
-                    vr.process(content_input_path, vector_storage_instance)
+                    vr = VectorRetriever(
+                        storage=vector_storage_instance,
+                        similarity_threshold=similarity_threshold,
+                    )
+                    vr.process(content_input_path)
+                else:
+                    vr = VectorRetriever(
+                        storage=vector_storage_instance,
+                        similarity_threshold=similarity_threshold,
+                    )
                 # Retrieve info by given query from the vector storage
-                retrieved_info = vr.query(
-                    query, vector_storage_instance, top_k, similarity_threshold
-                )
-                # Reorganize the retrieved info with original query
-                for info in retrieved_info:
-                    retrieved_infos += "\n" + str(info)
-                    retrieved_infos_text += "\n" + str(info['text'])
-                output = (
-                    "Original Query:"
-                    + "\n"
-                    + "{"
-                    + query
-                    + "}"
-                    + "\n"
-                    + "Retrieved Context:"
-                    + retrieved_infos
-                )
-                output_text = (
-                    "Original Query:"
-                    + "\n"
-                    + "{"
-                    + query
-                    + "}"
-                    + "\n"
-                    + "Retrieved Context:"
-                    + retrieved_infos_text
-                )
-
+                retrieved_info = vr.query(query, top_k)
+                all_retrieved_info.extend(retrieved_info)
             except Exception as e:
                 raise RuntimeError(
                     f"Error in auto vector retriever processing: {e!s}"
                 ) from e
 
+        # Split records into those with and without a 'similarity_score'
+        # Records with 'similarity_score' lower than 'similarity_threshold'
+        # will not have a 'similarity_score' in the output content
+        with_score = [
+            info for info in all_retrieved_info if 'similarity score' in info
+        ]
+        without_score = [
+            info
+            for info in all_retrieved_info
+            if 'similarity score' not in info
+        ]
+        # Sort only the list with scores
+        with_score_sorted = sorted(
+            with_score, key=lambda x: x['similarity score'], reverse=True
+        )
+        # Merge back the sorted scored items with the non-scored items
+        all_retrieved_info_sorted = with_score_sorted + without_score
+        # Select the 'top_k' results
+        all_retrieved_info = all_retrieved_info_sorted[:top_k]
+
+        retrieved_infos = "\n".join(str(info) for info in all_retrieved_info)
+        retrieved_infos_text = "\n".join(
+            info['text'] for info in all_retrieved_info if 'text' in info
+        )
+
+        detailed_info = f"Original Query:\n{{ {query} }}\nRetrieved Context:\n{retrieved_infos}"
+        text_info = f"Original Query:\n{{ {query} }}\nRetrieved Context:\n{retrieved_infos_text}"
+
         if return_detailed_info:
-            return output
+            return detailed_info
         else:
-            return output_text
+            return text_info

camel/retrievers/base.py

@@ -12,53 +12,58 @@
 # limitations under the License.
 # =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List
+from typing import Any, Callable
 
 DEFAULT_TOP_K_RESULTS = 1
 
 
-class BaseRetriever(ABC):
-    r"""Abstract base class for implementing various types of information
-    retrievers.
+def _query_unimplemented(self, *input: Any) -> None:
+    r"""Defines the query behavior performed at every call.
+
+    Query the results. Subclasses should implement this
+        method according to their specific needs.
+
+    It should be overridden by all subclasses.
+
+    .. note::
+        Although the recipe for forward pass needs to be defined within
+        this function, one should call the :class:`BaseRetriever` instance
+        afterwards instead of this since the former takes care of running the
+        registered hooks while the latter silently ignores them.
     """
+    raise NotImplementedError(
+        f"Retriever [{type(self).__name__}] is missing the required \"query\" function"
+    )
 
-    @abstractmethod
-    def __init__(self) -> None:
-        pass
 
-    @abstractmethod
-    def process(
-        self,
-        content_input_path: str,
-        chunk_type: str = "chunk_by_title",
-        **kwargs: Any,
-    ) -> None:
-        r"""Processes content from a file or URL, divides it into chunks by
+def _process_unimplemented(self, *input: Any) -> None:
+    r"""Defines the process behavior performed at every call.
+
+    Processes content from a file or URL, divides it into chunks by
         using `Unstructured IO`,then stored internally. This method must be
         called before executing queries with the retriever.
 
-        Args:
-            content_input_path (str): File path or URL of the content to be
-                processed.
-            chunk_type (str): Type of chunking going to apply. Defaults to
-                "chunk_by_title".
-            **kwargs (Any): Additional keyword arguments for content parsing.
-        """
-        pass
+    Should be overridden by all subclasses.
 
-    @abstractmethod
-    def query(
-        self, query: str, top_k: int = DEFAULT_TOP_K_RESULTS, **kwargs: Any
-    ) -> List[Dict[str, Any]]:
-        r"""Query the results. Subclasses should implement this
-        method according to their specific needs.
+    .. note::
+        Although the recipe for forward pass needs to be defined within
+        this function, one should call the :class:`BaseRetriever` instance
+        afterwards instead of this since the former takes care of running the
+        registered hooks while the latter silently ignores them.
+    """
+    raise NotImplementedError(
+        f"Retriever [{type(self).__name__}] is missing the required \"process\" function"
+    )
+
+
+class BaseRetriever(ABC):
+    r"""Abstract base class for implementing various types of information
+    retrievers.
+    """
 
-        Args:
-            query (str): Query string for information retriever.
-            top_k (int, optional): The number of top results to return during
-                retriever. Must be a positive integer. Defaults to
-                `DEFAULT_TOP_K_RESULTS`.
-            **kwargs (Any): Flexible keyword arguments for additional
-                parameters, like `similarity_threshold`.
-        """
+    @abstractmethod
+    def __init__(self) -> None:
         pass
+
+    process: Callable[..., Any] = _process_unimplemented
+    query: Callable[..., Any] = _query_unimplemented