camel-ai 0.2.9__py3-none-any.whl → 0.2.11__py3-none-any.whl

camel/messages/conversion/__init__.py

@@ -0,0 +1,31 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from .alpaca import AlpacaItem
+from .conversation_models import (
+    ShareGPTConversation,
+    ShareGPTMessage,
+    ToolCall,
+    ToolResponse,
+)
+from .sharegpt import HermesFunctionFormatter
+
+__all__ = [
+    'ShareGPTMessage',
+    'ShareGPTConversation',
+    'HermesFunctionFormatter',
+    'AlpacaItem',
+    'ToolCall',
+    'ToolResponse',
+]

camel/messages/conversion/alpaca.py

@@ -0,0 +1,122 @@
+# ========= 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 re
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class AlpacaItem(BaseModel):
+    r"""Represents an instruction-response item in the Alpaca format.
+
+    Appropripate for both cases where input field is empty, or populated.
+    Provides parsing from string format using the class method from_string().
+
+    Args:
+        instruction (str): The instruction/question/prompt
+        input (str): Input context or examples (put empty string if none)
+        output (str): The response/answer to the instruction
+    """
+
+    instruction: str = Field(description="The instruction/question/prompt")
+    input: str = Field(
+        description="Optional context or input for the task."
+        " For example, when the instruction is \"Summarize the "
+        "following article\", the input is the article."
+    )
+    output: str = Field(description="The response/answer to the instruction")
+
+    @field_validator('instruction', 'output')
+    def no_section_markers(cls, value: str) -> str:
+        r"""Ensures fields don't contain section markers like '###
+        Response:'
+        """
+        if (
+            '### Response' in value
+            or '### Instruction' in value
+            or '### Input' in value
+        ):
+            raise ValueError("Field cannot contain section markers")
+        return value.strip()
+
+    @classmethod
+    def from_string(cls, text: str) -> "AlpacaItem":
+        r"""Creates an AlpacaItem from a formatted string.
+
+        Args:
+            text: String in either of these formats:
+                 With input:
+                 ### Instruction:
+                 {instruction}
+                 ### Input:
+                 {input}
+                 ### Response:
+                 {response}
+
+                 Without input:
+                 ### Instruction:
+                 {instruction}
+                 ### Response:
+                 {response}
+
+        Returns:
+            AlpacaItem: Parsed instance
+
+        Raises:
+            ValueError: text doesn't match expected format or sections missing
+        """
+        # Strip and standardize newlines
+        text = text.strip().replace('\r\n', '\n')
+
+        # Try to extract sections using regex
+        instruction_match = re.search(
+            r'###\s*Instruction:\s*\n(.+?)(?=\n###|\Z)', text, re.DOTALL
+        )
+        input_match = re.search(
+            r'###\s*Input:\s*\n(.+?)(?=\n###|\Z)', text, re.DOTALL
+        )
+        response_match = re.search(
+            r'###\s*Response:\s*\n(.+?)(?=\n###|\Z)', text, re.DOTALL
+        )
+
+        if not instruction_match or not response_match:
+            raise ValueError(
+                "Text must contain '### Instruction:'"
+                " and '### Response:' sections"
+            )
+
+        return cls(
+            instruction=instruction_match.group(1).strip(),
+            input=input_match.group(1).strip() if input_match else "",
+            output=response_match.group(1).strip(),
+        )
+
+    def to_string(self) -> str:
+        r"""Converts the AlpacaItem to its string representation.
+
+        Returns:
+            str: Formatted string representation with sections markers
+        """
+        return "\n".join(
+            [
+                "### Instruction:",
+                self.instruction,
+                "",
+                "### Input:",
+                self.input,
+                "",
+                "### Response:",
+                self.output,
+            ]
+        )

camel/messages/conversion/conversation_models.py

@@ -0,0 +1,178 @@
+# ========= 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 json
+from typing import Any, Dict, List, Literal
+
+from pydantic import (
+    BaseModel,
+    Field,
+    RootModel,
+    field_validator,
+    model_validator,
+)
+
+
+class ShareGPTMessage(BaseModel):
+    r"""A single message in ShareGPT format with enhanced validation"""
+
+    from_: Literal["human", "gpt", "system", "tool"] = Field(
+        alias="from", description="The role of the message sender"
+    )
+    value: str = Field(
+        min_length=0,
+        max_length=100000,
+        description="The content of the message",
+    )
+
+    model_config = {
+        "populate_by_name": True,
+        "extra": "forbid",
+        "json_schema_extra": {
+            "examples": [
+                {"from": "human", "value": "What's the weather like today?"}
+            ]
+        },
+    }
+
+
+class ShareGPTConversation(RootModel):
+    r"""A full conversation in ShareGPT format with validation"""
+
+    root: List[ShareGPTMessage]
+
+    @model_validator(mode='after')
+    def validate_conversation_flow(self) -> 'ShareGPTConversation':
+        r"""Validate the conversation follows logical message order"""
+        messages = self.root
+
+        if not messages:
+            raise ValueError("Conversation cannot be empty")
+
+        if messages[0].from_ not in ("system", "human"):
+            raise ValueError(
+                "Conversation must start with either system or human message"
+            )
+
+        # Validate message sequence
+        for i in range(1, len(messages)):
+            curr, prev = messages[i], messages[i - 1]
+
+            if curr.from_ == "tool":
+                if prev.from_ != "gpt" or "<tool_call>" not in prev.value:
+                    raise ValueError(
+                        f"Tool response at position {i} "
+                        f"must follow an gpt message with a tool call"
+                    )
+
+            if curr.from_ == "gpt" and prev.from_ not in (
+                "human",
+                "tool",
+            ):
+                raise ValueError(
+                    f"Assistant message at position {i} "
+                    f"must follow a human or tool message"
+                )
+
+        return self
+
+    def model_dump(self, **kwargs):
+        return self.root
+
+    def __iter__(self):
+        return iter(self.root)
+
+
+class ToolCall(BaseModel):
+    r"""Represents a single tool/function call with validation"""
+
+    name: str = Field(
+        min_length=1,
+        max_length=256,
+        description="The name of the tool to call",
+    )
+    arguments: Dict[str, Any] = Field(
+        description="The arguments to pass to the tool"
+    )
+
+    @field_validator('arguments')
+    @classmethod
+    def validate_arguments(cls, v: Dict[str, Any]) -> Dict[str, Any]:
+        r"""Validate argument structure and content"""
+
+        # Try to serialize arguments to ensure they're JSON-compatible
+        try:
+            json.dumps(v)
+        except (TypeError, ValueError):
+            raise ValueError("Arguments must be JSON-serializable")
+
+        return v
+
+    model_config = {
+        "extra": "forbid",
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "name": "get_weather",
+                    "arguments": {"city": "London", "units": "celsius"},
+                }
+            ]
+        },
+    }
+
+
+class ToolResponse(BaseModel):
+    r"""Represents a tool/function response with validation. This is a
+    base class and default implementation for tool responses, for the purpose
+    of converting between different formats.
+    """
+
+    name: str = Field(
+        min_length=1,
+        max_length=256,
+        description="The name of the tool that was called",
+    )
+    content: Any = Field(
+        description="The response content from the tool."
+        " Must be JSON serializable literal or object"
+    )
+
+    @field_validator('content')
+    @classmethod
+    def validate_content(cls, v: Dict[str, Any]) -> Dict[str, Any]:
+        r"""Validate response content structure"""
+
+        # Ensure content is JSON-serializable
+        try:
+            json.dumps(v)
+        except (TypeError, ValueError):
+            raise ValueError("Response content must be JSON-serializable")
+
+        return v
+
+    model_config = {
+        "extra": "forbid",
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "name": "get_weather",
+                    "content": {
+                        "temperature": 20,
+                        "conditions": "sunny",
+                        "humidity": 65,
+                    },
+                }
+            ]
+        },
+    }

camel/messages/conversion/sharegpt/__init__.py

@@ -0,0 +1,20 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+
+from .hermes import HermesFunctionFormatter
+
+__all__ = [
+    'HermesFunctionFormatter',
+]

camel/messages/conversion/sharegpt/function_call_formatter.py

@@ -0,0 +1,49 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+
+from camel.messages.conversion import (
+    ToolCall,
+    ToolResponse,
+)
+
+CallT = TypeVar('CallT', bound=ToolCall, covariant=True)
+ResponseT = TypeVar('ResponseT', bound=ToolResponse, covariant=True)
+
+
+class FunctionCallFormatter(ABC, Generic[CallT, ResponseT]):
+    r"""Abstract base class for function calling formats"""
+
+    @abstractmethod
+    def extract_tool_calls(self, message: str) -> List[CallT]:
+        r"""Extract function call info from a message string"""
+        pass
+
+    @abstractmethod
+    def extract_tool_response(self, message: str) -> Optional[ResponseT]:
+        r"""Extract function response info from a message string"""
+        pass
+
+    @abstractmethod
+    def format_tool_call(
+        self, content: str, func_name: str, args: Dict[str, Any]
+    ) -> str:
+        r"""Format a function call into a message string"""
+        pass
+
+    @abstractmethod
+    def format_tool_response(self, func_name: str, result: Any) -> str:
+        r"""Format a function response into a message string"""
+        pass

camel/messages/conversion/sharegpt/hermes/__init__.py

@@ -0,0 +1,19 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from .hermes_function_formatter import HermesFunctionFormatter
+
+__all__ = [
+    'HermesFunctionFormatter',
+]

camel/messages/conversion/sharegpt/hermes/hermes_function_formatter.py

@@ -0,0 +1,128 @@
+# ========= 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 json
+import re
+from typing import Any, Dict, List, Optional
+
+from camel.messages.conversion import (
+    ToolCall,
+    ToolResponse,
+)
+from camel.messages.conversion.sharegpt.function_call_formatter import (
+    FunctionCallFormatter,
+)
+
+
+class HermesToolResponse(ToolResponse):
+    r"""Represents a single tool/function call with validation"""
+
+    pass
+
+
+class HermesToolCall(ToolCall):
+    r"""Represents a single tool/function call with validation"""
+
+    pass
+
+
+class HermesFunctionFormatter(
+    FunctionCallFormatter[HermesToolCall, HermesToolResponse]
+):
+    r"""Hermes-style function calling format implementation with validation"""
+
+    def extract_tool_calls(self, message: str) -> List[HermesToolCall]:
+        r"""Extracts all tool calls from the provided message string.
+
+        Args:
+            message (str): The input message string containing potential tool
+                calls.
+
+        Returns:
+            List[HermesToolCall]: A list of parsed HermesToolCall objects.
+        """
+        tool_calls = []
+        pattern = r"<tool_call>\s*({.*?})\s*</tool_call>"
+        matches = re.finditer(pattern, message, re.DOTALL)
+
+        for match in matches:
+            try:
+                call_dict = json.loads(match.group(1).replace("'", '"'))
+                tool_calls.append(HermesToolCall.model_validate(call_dict))
+            except Exception as e:
+                print(f"Warning: Failed to parse tool call: {e}")
+                continue
+
+        return tool_calls
+
+    def extract_tool_response(
+        self, message: str
+    ) -> Optional[HermesToolResponse]:
+        r"""Extracts a single tool response from the provided message string.
+
+        Args:
+            message (str): The input message string containing a potential
+                tool response.
+
+        Returns:
+            Optional[HermesToolResponse]: A parsed HermesToolResponse object,
+                or None if no valid response is found.
+        """
+        pattern = r"<tool_response>\s*({.*?})\s*</tool_response>"
+        match = re.search(pattern, message, re.DOTALL)
+
+        if match:
+            try:
+                response_json = match.group(1)
+                response_dict = json.loads(response_json.replace("'", '"'))
+                return HermesToolResponse.model_validate(response_dict)
+            except Exception as e:
+                print(f"Warning: Failed to parse tool response: {e}")
+                return None
+        return None
+
+    def format_tool_call(
+        self, content: str, func_name: str, args: Dict[str, Any]
+    ) -> str:
+        r"""Formats a tool call message with the given content, function name,
+        and arguments.
+
+        Args:
+            content (str): The content or message to be included in the tool
+                call.
+            func_name (str): The name of the function being called.
+            args (Dict[str, Any]): A dictionary of arguments to be passed to
+                the function.
+
+        Returns:
+            str: A formatted string representing the tool call in Hermes
+                format.
+        """
+        tool_call_dict = {"name": func_name, "arguments": args}
+        return f"{content}\n<tool_call>\n{tool_call_dict}\n</tool_call>"
+
+    def format_tool_response(self, func_name: str, result: Any) -> str:
+        r"""Formats a tool response message with the given function name and
+        result.
+
+        Args:
+            func_name (str): The name of the function whose result is being
+                returned.
+            result (Any): The result to be included in the tool response.
+
+        Returns:
+            str: A formatted string representing the tool response in Hermes
+                format.
+        """
+        response_dict = {"name": func_name, "content": result}
+        return f"<tool_response>\n{response_dict}\n</tool_response>"

camel/messages/func_message.py

@@ -1,25 +1,34 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= 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,
+# 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. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 from dataclasses import dataclass
 from typing import Any, Dict, Optional
 
 from camel.messages import (
     BaseMessage,
+    HermesFunctionFormatter,
     OpenAIAssistantMessage,
     OpenAIFunctionMessage,
     OpenAIMessage,
 )
+from camel.messages.conversion import (
+    ShareGPTMessage,
+    ToolCall,
+    ToolResponse,
+)
+from camel.messages.conversion.sharegpt.function_call_formatter import (
+    FunctionCallFormatter,
+)
 from camel.types import OpenAIBackendRole
 
 
@@ -61,6 +70,43 @@ class FunctionCallingMessage(BaseMessage):
         else:
             raise ValueError(f"Unsupported role: {role_at_backend}.")
 
+    def to_sharegpt(
+        self,
+        function_format: Optional[
+            FunctionCallFormatter[ToolCall, ToolResponse]
+        ] = None,
+    ) -> ShareGPTMessage:
+        r"""Convert FunctionCallingMessage to ShareGPT message.
+
+        Args:
+            function_format (FunctionCallFormatter[ToolCall, ToolResponse],
+                optional): The function formatter to use. Defaults to None.
+        """
+
+        if function_format is None:
+            function_format = HermesFunctionFormatter()
+        # The role of the message is an unreliable indicator of whether
+        # it is a function call or response, so use result
+        if self.result is None:
+            # This is a function call
+            # TODO: split the incoming types to be more specific
+            #  and remove the type ignores
+            content = function_format.format_tool_call(
+                self.content or "",  # type: ignore[arg-type]
+                self.func_name,  # type: ignore[arg-type]
+                self.args,  # type: ignore[arg-type]
+            )
+            return ShareGPTMessage(from_="gpt", value=content)  # type: ignore[call-arg]
+        else:
+            # This is a function response
+            # TODO: Allow for more flexible setting of tool role,
+            #  optionally to be the same as assistant messages
+            content = function_format.format_tool_response(
+                self.func_name,  # type: ignore[arg-type]
+                self.result,  # type: ignore[arg-type]
+            )
+            return ShareGPTMessage(from_="tool", value=content)  # type: ignore[call-arg]
+
     def to_openai_assistant_message(self) -> OpenAIAssistantMessage:
         r"""Converts the message to an :obj:`OpenAIAssistantMessage` object.
 

camel/models/__init__.py

@@ -1,25 +1,29 @@
-# =========== Copyright 2023 @ CAMEL-AI.org. All Rights Reserved. ===========
-# Licensed under the Apache License, Version 2.0 (the “License”);
+# ========= 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,
+# 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. ===========
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
 from .anthropic_model import AnthropicModel
 from .azure_openai_model import AzureOpenAIModel
 from .base_model import BaseModelBackend
+from .cohere_model import CohereModel
+from .deepseek_model import DeepSeekModel
 from .gemini_model import GeminiModel
 from .groq_model import GroqModel
 from .litellm_model import LiteLLMModel
 from .mistral_model import MistralModel
 from .model_factory import ModelFactory
+from .model_manager import ModelManager, ModelProcessingError
 from .nemotron_model import NemotronModel
+from .nvidia_model import NvidiaModel
 from .ollama_model import OllamaModel
 from .openai_audio_models import OpenAIAudioModels
 from .openai_compatible_model import OpenAICompatibleModel
@@ -42,10 +46,13 @@ __all__ = [
     'GroqModel',
     'StubModel',
     'ZhipuAIModel',
+    'CohereModel',
     'ModelFactory',
+    'ModelManager',
     'LiteLLMModel',
     'OpenAIAudioModels',
     'NemotronModel',
+    'NvidiaModel',
     'OllamaModel',
     'VLLMModel',
     'GeminiModel',
@@ -55,4 +62,6 @@ __all__ = [
     'TogetherAIModel',
     'YiModel',
     'QwenModel',
+    'ModelProcessingError',
+    'DeepSeekModel',
 ]