cheshirecat-python-sdk 1.2.1__py3-none-any.whl → 1.8.4__py3-none-any.whl

cheshirecat_python_sdk/endpoints/memory.py

@@ -1,19 +1,18 @@
 from typing import Dict, Any
+import json
 
-from cheshirecat_python_sdk.enums import Collection, Role
 from cheshirecat_python_sdk.endpoints.base import AbstractEndpoint
 from cheshirecat_python_sdk.models.api.memories import (
     CollectionsOutput,
     CollectionPointsDestroyOutput,
-    ConversationHistoryOutput,
-    ConversationHistoryDeleteOutput,
     MemoryRecallOutput,
     MemoryPointOutput,
     MemoryPointDeleteOutput,
     MemoryPointsDeleteByMetadataOutput,
     MemoryPointsOutput,
 )
-from cheshirecat_python_sdk.models.dtos import Why, MemoryPoint
+from cheshirecat_python_sdk.models.api.nested.memories import CollectionsItem
+from cheshirecat_python_sdk.models.dtos import Why, MemoryPoint, FilterSource
 
 
 class MemoryEndpoint(AbstractEndpoint):
@@ -23,180 +22,110 @@ class MemoryEndpoint(AbstractEndpoint):
 
     # Memory Collections API
 
-    def get_memory_collections(self, agent_id: str | None = None) -> CollectionsOutput:
+    def get_memory_collections(self, agent_id: str) -> CollectionsOutput:
         """
-        This endpoint returns the collections of memory points, either for the agent identified by the agentId parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations).
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
+        This endpoint returns the collections of memory points.
+        :param agent_id: The agent ID.
         :return: CollectionsOutput, a list of collections of memory points.
         """
         return self.get(
             self.format_url("/collections"),
-            CollectionsOutput,
             agent_id,
+            output_class=CollectionsOutput,
         )
 
-    def delete_all_memory_collection_points(self, agent_id: str | None = None) -> CollectionPointsDestroyOutput:
+    def delete_all_memory_collection_points(self, agent_id: str) -> CollectionPointsDestroyOutput:
         """
-        This endpoint deletes all memory points in all collections for the agent identified by the agentId parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations).
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
+        This endpoint deletes all memory points in all collections for the agent identified by the agentId parameter.
+        :param agent_id: The agent ID.
         :return: CollectionPointsDestroyOutput, a message indicating the number of memory points deleted.
         """
         return self.delete(
             self.format_url("/collections"),
-            CollectionPointsDestroyOutput,
             agent_id,
+            output_class=CollectionPointsDestroyOutput,
         )
 
     def delete_all_single_memory_collection_points(
-        self, collection: Collection, agent_id: str | None = None
+        self, collection: str, agent_id: str
     ) -> CollectionPointsDestroyOutput:
         """
-        This method deletes all the points in a single collection of memory, either for the agent identified by the
-        agentId parameter (for multi-agent installations) or for the default agent (for single-agent installations).
+        This method deletes all the points in a single collection of memory.
         :param collection: The collection to delete.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
+        :param agent_id: The agent ID.
         :return: CollectionPointsDestroyOutput, a message indicating the number of memory points deleted.
         """
         return self.delete(
             self.format_url(f"/collections/{collection}"),
-            CollectionPointsDestroyOutput,
             agent_id,
+            output_class=CollectionPointsDestroyOutput,
         )
 
-    # END Memory Collections API
-
-    # Memory Conversation History API
-
-    def get_conversation_history(
-        self, agent_id: str | None = None, user_id: str | None = None
-    ) -> ConversationHistoryOutput:
-        """
-        This endpoint returns the conversation history, either for the agent identified by the agent_id parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations). If the user_id
-        parameter is provided, the conversation history is filtered by the user ID.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
-        :param user_id: The user ID to filter the conversation history.
-        :return: ConversationHistoryOutput, a list of conversation history entries.
-        """
-        return self.get(
-            self.format_url("/conversation_history"),
-            ConversationHistoryOutput,
-            agent_id,
-            user_id,
-        )
-
-    def delete_conversation_history(
-        self, agent_id: str | None = None, user_id: str | None = None
-    ) -> ConversationHistoryDeleteOutput:
+    def post_memory_collections(self, collection_id: str, agent_id: str) -> CollectionsItem:
         """
-        This endpoint deletes the conversation history, either for the agent identified by the agent_id parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations). If the user_id
-        parameter is provided, the conversation history is filtered by the user ID.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
-        :param user_id: The user ID to filter the conversation history.
-        :return: ConversationHistoryDeleteOutput, a message indicating the number of conversation history entries deleted.
+        This endpoint returns the collections of memory points.
+        :param collection_id: The ID of the collection to create.
+        :param agent_id: The agent ID.
+        :return: CollectionsItem, the collection created.
         """
-        return self.delete(
-            self.format_url("/conversation_history"),
-            ConversationHistoryDeleteOutput,
-            agent_id,
-            user_id,
-        )
-
-    def post_conversation_history(
-        self,
-        who: Role,
-        text: str,
-        image: str | bytes | None = None,
-        why: Why | None = None,
-        agent_id: str | None = None,
-        user_id: str | None = None
-    ) -> ConversationHistoryOutput:
-        """
-        This endpoint creates a new element in the conversation history, either for the agent identified by the agent_id
-        parameter (for multi-agent installations) or for the default agent (for single-agent installations). If the
-        user_id parameter is provided, the conversation history is added to the user ID.
-        :param who: The role of the user in the conversation.
-        :param text: The text of the conversation history entry.
-        :param image: The image of the conversation history entry.
-        :param why: The reason for the conversation history entry.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
-        :param user_id: The user ID to filter the conversation history.
-        :return: ConversationHistoryOutput, the conversation history entry created.
-        """
-        payload = {
-            "who": who.value,
-            "text": text,
-        }
-        if image:
-            payload["image"] = image
-        if why:
-            payload["why"] = why.model_dump()
-
         return self.post_json(
-            self.format_url("/conversation_history"),
-            ConversationHistoryOutput,
-            payload,
+            self.format_url(f"/collections/{collection_id}"),
             agent_id,
-            user_id,
+            output_class=CollectionsItem,
         )
 
-    # END Memory Conversation History API
+    # END Memory Collections API
 
     # Memory Points API
 
     def get_memory_recall(
         self,
         text: str,
+        agent_id: str,
+        user_id: str,
         k: int | None = None,
         metadata: Dict[str, Any] | None = None,
-        agent_id: str | None = None,
-        user_id: str | None = None,
+        chat_id: str | None = None,
     ) -> MemoryRecallOutput:
         """
-        This endpoint retrieves memory points based on the input text, either for the agent identified by the agent_id
-        parameter (for multi-agent installations) or for the default agent (for single-agent installations). The text
-        parameter is the input text for which the memory points are retrieved. The k parameter is the number of memory
-        points to retrieve.
-        If the user_id parameter is provided, the memory points are filtered by the user ID.
+        This endpoint retrieves memory points based on the input text. The text parameter is the input text for which
+        the memory points are retrieved. The k parameter is the number of memory points to retrieve.
         :param text: The input text for which the memory points are retrieved.
+        :param agent_id: The agent ID.
+        :param user_id: The user ID to filter the memory points.
         :param k: The number of memory points to retrieve.
         :param metadata: The metadata to filter the memory points.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
-        :param user_id: The user ID to filter the memory points.
+        :param chat_id: The chat id, optional
         :return: MemoryRecallOutput, a list of memory points retrieved.
         """
         query = {"text": text}
         if k:
-            query["k"] = k
+            query["k"] = k  # type: ignore
         if metadata:
-            query["metadata"] = metadata
+            query["metadata"] = json.dumps(metadata)  # type: ignore
 
         return self.get(
             self.format_url("/recall"),
-            MemoryRecallOutput,
             agent_id,
-            user_id,
-            query,
+            output_class=MemoryRecallOutput,
+            user_id=user_id,
+            query=query,
+            chat_id=chat_id,
         )
 
     def post_memory_point(
         self,
-        collection: Collection,
+        collection: str,
+        agent_id: str,
+        user_id: str,
         memory_point: MemoryPoint,
-        agent_id: str | None = None,
-        user_id: str | None = None,
     ) -> MemoryPointOutput:
         """
-        This method posts a memory point, either for the agent identified by the agent_id parameter (for multi-agent
-        installations) or for the default agent (for single-agent installations).
-        If the user_id parameter is provided, the memory point is associated with the user ID.
+        This method posts a memory point.
         :param collection: The collection to post the memory point.
-        :param memory_point: The memory point to post.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
+        :param agent_id: The agent ID.
         :param user_id: The user ID to associate with the memory point.
+        :param memory_point: The memory point to post.
         :return: MemoryPointOutput, the memory point posted.
         """
         if user_id and not memory_point.metadata.get("source"):
@@ -206,28 +135,26 @@ class MemoryEndpoint(AbstractEndpoint):
 
         return self.post_json(
             self.format_url(f"/collections/{collection}/points"),
-            MemoryPointOutput,
-            memory_point.model_dump(),
             agent_id,
+            output_class=MemoryPointOutput,
+            payload=memory_point.model_dump(),
         )
 
     def put_memory_point(
         self,
-        collection: Collection,
+        collection: str,
+        agent_id: str,
+        user_id: str,
         memory_point: MemoryPoint,
         point_id: str,
-        agent_id: str | None = None,
-        user_id: str | None = None,
     ) -> MemoryPointOutput:
         """
-        This method puts a memory point, either for the agent identified by the agent_id parameter (for multi-agent
-        installations) or for the default agent (for single-agent installations).
-        If the user_id parameter is provided, the memory point is associated with the user ID.
+        This method puts a memory point, for the agent identified by the agent_id parameter.
         :param collection: The collection to put the memory point.
+        :param agent_id: The agent ID.
+        :param user_id: The user ID to associate with the memory point.
         :param memory_point: The memory point to put.
         :param point_id: The ID of the memory point to put.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
-        :param user_id: The user ID to associate with the memory point.
         :return: MemoryPointOutput, the memory point put.
         """
         if user_id and not memory_point.metadata.get("source"):
@@ -237,68 +164,67 @@ class MemoryEndpoint(AbstractEndpoint):
 
         return self.put(
             self.format_url(f"/collections/{collection}/points/{point_id}"),
-            MemoryPointOutput,
-            memory_point.model_dump(),
             agent_id,
+            output_class=MemoryPointOutput,
+            payload=memory_point.model_dump(),
         )
 
     def delete_memory_point(
         self,
-        collection: Collection,
+        collection: str,
+        agent_id: str,
         point_id: str,
-        agent_id: str | None = None,
     ) -> MemoryPointDeleteOutput:
         """
-        This endpoint deletes a memory point, either for the agent identified by the agent_id parameter (for multi-agent
-        installations) or for the default agent (for single-agent installations).
+        This endpoint deletes a memory point.
         :param collection: The collection to delete the memory point.
+        :param agent_id: The agent ID.
         :param point_id: The ID of the memory point to delete.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
         :return: MemoryPointDeleteOutput, a message indicating the memory point deleted.
         """
         return self.delete(
             self.format_url(f"/collections/{collection}/points/{point_id}"),
-            MemoryPointDeleteOutput,
             agent_id,
+            output_class=MemoryPointDeleteOutput,
         )
 
     def delete_memory_points_by_metadata(
         self,
-        collection: Collection,
+        collection: str,
+        agent_id: str,
         metadata: Dict[str, Any] | None = None,
-        agent_id: str | None = None,
     ) -> MemoryPointsDeleteByMetadataOutput:
         """
-        This endpoint deletes memory points based on the metadata, either for the agent identified by the agent_id
-        parameter (for multi-agent installations) or for the default agent (for single-agent installations). The
-        metadata parameter is a dictionary of key-value pairs that the memory points must match.
+        This endpoint deletes memory points based on the metadata. The metadata parameter is a dictionary of key-value
+        pairs that the memory points must match.
         :param collection: The collection to delete the memory points.
+        :param agent_id: The agent ID.
         :param metadata: The metadata to filter the memory points.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
         :return: MemoryPointsDeleteByMetadataOutput, a message indicating the number of memory points deleted.
         """
         return self.delete(
             self.format_url(f"/collections/{collection}/points"),
-            MemoryPointsDeleteByMetadataOutput,
             agent_id,
+            output_class=MemoryPointsDeleteByMetadataOutput,
             payload=metadata,
         )
 
     def get_memory_points(
         self,
-        collection: Collection,
+        collection: str,
+        agent_id: str,
         limit: int | None = None,
         offset: int | None = None,
-        agent_id: str | None = None,
+        metadata: Dict[str, Any] | None = None,
     ) -> MemoryPointsOutput:
         """
-        This endpoint retrieves memory points, either for the agent identified by the agent_id parameter (for
-        multi-agent installations) or for the default agent (for single-agent installations). The limit parameter is the
-        maximum number of memory points to retrieve. The offset parameter is the number of memory points to skip.
+        This endpoint retrieves memory points. The limit parameter is the maximum number of memory points to retrieve.
+        The offset parameter is the number of memory points to skip.
         :param collection: The collection to retrieve the memory points.
+        :param agent_id: The agent ID.
         :param limit: The maximum number of memory points to retrieve.
         :param offset: The number of memory points to skip.
-        :param agent_id: The agent ID for multi-agent installations. If not provided, the default agent is used.
+        :param metadata: The metadata to filter the memory points.
         :return: MemoryPointsOutput, a list of memory points retrieved.
         """
         query = {}
@@ -306,12 +232,41 @@ class MemoryEndpoint(AbstractEndpoint):
             query["limit"] = limit
         if offset is not None:
             query["offset"] = offset
+        if metadata:
+            query["metadata"] = json.dumps(metadata)  # type: ignore
 
         return self.get(
             self.format_url(f"/collections/{collection}/points"),
-            MemoryPointsOutput,
             agent_id,
+            output_class=MemoryPointsOutput,
             query=query,
         )
 
+    def has_source(self, agent_id: str, filter_source: FilterSource, chat_id: str | None = None) -> bool:
+        """
+        Checks if the given filter source exists for a specified agent.
+
+        This method determines whether a specific source, defined by the given filter_source, is associated with the
+        provided agent in the memory database.
+        It optionally considers a specific chat ID when filtering the data. The result indicates the existence of such a
+        source.
+
+        Args:
+            agent_id: Unique identifier of the agent for which the check is performed.
+            filter_source: FilterSource object that defines the source or hash to check.
+            chat_id: An optional chat identifier to narrow the scope of the check. If not provided, the check will
+                operate in a broader context.
+
+        Returns:
+            A boolean value indicating whether the specified filter source exists in the agent's memory database.
+        """
+        metadata = {"source": filter_source.source} if filter_source.source else {"hash": filter_source.hash}
+        if chat_id:
+            metadata["chat_id"] = chat_id
+
+        collection_name = "declarative" if chat_id is None else "episodic"
+        points = self.get_memory_points(collection_name, agent_id, metadata=metadata)
+
+        return len(points.points) > 0
+
     # END Memory Points API

cheshirecat_python_sdk/endpoints/message.py

@@ -2,43 +2,59 @@ from typing import Callable
 import json
 
 from cheshirecat_python_sdk.endpoints.base import AbstractEndpoint
-from cheshirecat_python_sdk.models.api.messages import MessageOutput
+from cheshirecat_python_sdk.models.api.messages import ChatOutput
 from cheshirecat_python_sdk.models.dtos import Message
 from cheshirecat_python_sdk.utils import deserialize
 
 
 class MessageEndpoint(AbstractEndpoint):
     def send_http_message(
-        self, message: Message, agent_id: str | None = None, user_id: str | None = None
-    ) -> MessageOutput:
+        self,
+        message: Message,
+        agent_id: str,
+        user_id: str,
+        chat_id: str | None = None,
+    ) -> ChatOutput:
         """
         This endpoint sends a message to the agent identified by the agentId parameter. The message is sent via HTTP.
         :param message: Message object, the message to send
-        :param agent_id: the agent id, if None the message is sent to the default agent
-        :param user_id: the user id, if None the message is considered as sent by the default user
+        :param agent_id: the agent id
+        :param user_id: the user id
+        :param chat_id: the chat id (optional)
+        :return: ChatOutput object
         """
-        return self.post_json('/message', MessageOutput, message.model_dump(), agent_id, user_id)
+        return self.post_json(
+            '/message',
+            agent_id,
+            output_class=ChatOutput,
+            payload=message.model_dump(),
+            user_id=user_id,
+            chat_id=chat_id,
+        )
 
     async def send_websocket_message(
         self,
         message: Message,
-        agent_id: str | None = None,
-        user_id: str | None = None,
+        agent_id: str,
+        user_id: str,
+        chat_id: str | None = None,
         callback: Callable[[str], None] | None = None
-    ) -> MessageOutput:
+    ) -> ChatOutput:
         """
         This endpoint sends a message to the agent identified by the agentId parameter. The message is sent via WebSocket.
         :param message: Message object, the message to send
-        :param agent_id: the agent id, if None the message is sent to the default agent
-        :param user_id: the user id, if None the message is considered as sent by the default user
+        :param agent_id: the agent id
+        :param user_id: the user id
+        :param chat_id: the chat id
         :param callback: callable, a callback function that will be called for each message received
+        :return: ChatOutput object
         """
         try:
             json_data = json.dumps(message.model_dump())
         except Exception:
             raise RuntimeError("Error encoding message")
 
-        client = await self.get_ws_client(agent_id, user_id)
+        client = await self.get_ws_client(agent_id, user_id, chat_id)
 
         try:
             await client.send(json_data)
@@ -58,4 +74,4 @@ class MessageEndpoint(AbstractEndpoint):
             raise Exception(f"WebSocket error: {str(e)}")
 
         await client.close()
-        return deserialize(json.loads(response), MessageOutput)
+        return deserialize(json.loads(response), ChatOutput)

cheshirecat_python_sdk/endpoints/plugins.py

@@ -8,77 +8,82 @@ class PluginsEndpoint(AbstractEndpoint):
         super().__init__(client)
         self.prefix = "/plugins"
 
-    def get_available_plugins(
-        self, plugin_name: str | None = None, agent_id: str | None = None
-    ) -> PluginCollectionOutput:
+    def get_available_plugins(self, agent_id: str, plugin_name: str | None = None) -> PluginCollectionOutput:
         """
-        This endpoint returns the available plugins, either for the agent identified by the agent_id parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations).
-        :param plugin_name: The name of the plugin to get
+        This endpoint returns the available plugins.
         :param agent_id: The id of the agent
+        :param plugin_name: The name of the plugin to get
         :return: PluginCollectionOutput, the available plugins
         """
         return self.get(
             self.prefix,
-            PluginCollectionOutput,
             agent_id,
+            output_class=PluginCollectionOutput,
             query={"query": plugin_name} if plugin_name else {},
         )
 
-    def put_toggle_plugin(self, plugin_id: str, agent_id: str | None = None) -> PluginToggleOutput:
+    def put_toggle_plugin(self, plugin_id: str, agent_id: str) -> PluginToggleOutput:
         """
-        This endpoint toggles a plugin, either for the agent identified by the agent_id parameter (for multi-agent
-        installations) or for the default agent (for single-agent installations).
+        This endpoint toggles a plugin, for the agent identified by the agent_id parameter.
         :param plugin_id: The id of the plugin to toggle
         :param agent_id: The id of the agent
         :return: PluginToggleOutput, the toggled plugin
         """
         return self.put(
             self.format_url(f"/toggle/{plugin_id}"),
-            PluginToggleOutput,
-            {},
             agent_id,
+            output_class=PluginToggleOutput,
         )
 
-    def get_plugins_settings(self, agent_id: str | None = None) -> PluginsSettingsOutput:
+    def get_plugins_settings(self, agent_id: str) -> PluginsSettingsOutput:
         """
-        This endpoint retrieves the plugins settings, either for the agent identified by the agent_id parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations).
+        This endpoint retrieves the plugins settings.
         :param agent_id: The id of the agent
         :return: PluginsSettingsOutput, the plugins settings
         """
         return self.get(
             self.format_url("/settings"),
-            PluginsSettingsOutput,
             agent_id,
+            output_class=PluginsSettingsOutput,
         )
 
-    def get_plugin_settings(self, plugin_id: str, agent_id: str | None = None) -> PluginSettingsOutput:
+    def get_plugin_settings(self, plugin_id: str, agent_id: str) -> PluginSettingsOutput:
         """
-        This endpoint retrieves the plugin settings, either for the agent identified by the agent_id parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations).
+        This endpoint retrieves the plugin settings.
         :param plugin_id: The id of the plugin
         :param agent_id: The id of the agent
         :return: PluginSettingsOutput, the plugin settings
         """
         return self.get(
             self.format_url(f"/settings/{plugin_id}"),
-            PluginSettingsOutput,
             agent_id,
+            output_class=PluginSettingsOutput,
         )
 
-    def put_plugin_settings(self, plugin_id: str, values: dict, agent_id: str | None = None) -> PluginSettingsOutput:
+    def put_plugin_settings(self, plugin_id: str, agent_id: str, values: dict) -> PluginSettingsOutput:
         """
-        This endpoint updates the plugin settings, either for the agent identified by the agent_id parameter
-        (for multi-agent installations) or for the default agent (for single-agent installations).
+        This endpoint updates the plugin settings.
         :param plugin_id: The id of the plugin
-        :param values: The values to update
         :param agent_id: The id of the agent
+        :param values: The values to update
         :return: PluginSettingsOutput, the updated plugin settings
         """
         return self.put(
             self.format_url(f"/settings/{plugin_id}"),
-            PluginSettingsOutput,
-            values,
             agent_id,
+            output_class=PluginSettingsOutput,
+            payload=values,
+        )
+
+    def post_plugin_reset_settings(self, plugin_id: str, agent_id: str) -> PluginSettingsOutput:
+        """
+        This endpoint resets the plugin settings to the factory values
+        :param plugin_id: The id of the plugin
+        :param agent_id: The id of the agent
+        :return: PluginSettingsOutput, the plugin settings after reset
+        """
+        return self.post_json(
+            self.format_url(f"/settings/{plugin_id}"),
+            agent_id,
+            output_class=PluginSettingsOutput,
         )