usecortex-ai 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

usecortex_ai/user_memory/client.py

@@ -4,8 +4,16 @@ import typing
 
 from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
 from ..core.request_options import RequestOptions
+from ..types.add_user_memory_response import AddUserMemoryResponse
+from ..types.delete_user_memory_response import DeleteUserMemoryResponse
+from ..types.generate_user_memory_response import GenerateUserMemoryResponse
+from ..types.list_user_memories_response import ListUserMemoriesResponse
+from ..types.retrieve_user_memory_response import RetrieveUserMemoryResponse
 from .raw_client import AsyncRawUserMemoryClient, RawUserMemoryClient
 
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
 
 class UserMemoryClient:
     def __init__(self, *, client_wrapper: SyncClientWrapper):
@@ -23,21 +31,35 @@ class UserMemoryClient:
         return self._raw_client
 
     def list_user_memories(
-        self, *, tenant_id: str, sub_tenant_id: str, request_options: typing.Optional[RequestOptions] = None
-    ) -> typing.Optional[typing.Any]:
+        self,
+        *,
+        tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> ListUserMemoriesResponse:
         """
+        Retrieve all stored user memories for your tenant.
+
+        This endpoint returns a comprehensive list of all user memories that have been stored,
+        whether they were added manually or generated through AI. User memories help personalize
+        your experience by storing context, preferences, and important information.
+
+        You can optionally specify a sub-tenant to filter memories within that specific scope.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        ListUserMemoriesResponse
             Successful Response
 
         Examples
@@ -45,7 +67,7 @@ class UserMemoryClient:
         from usecortex-ai import CortexAI
 
         client = CortexAI(token="YOUR_TOKEN", )
-        client.user_memory.list_user_memories(tenant_id='tenant_id', sub_tenant_id='sub_tenant_id', )
+        client.user_memory.list_user_memories(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', )
         """
         _response = self._raw_client.list_user_memories(
             tenant_id=tenant_id, sub_tenant_id=sub_tenant_id, request_options=request_options
@@ -57,24 +79,35 @@ class UserMemoryClient:
         *,
         tenant_id: str,
         memory_id: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> DeleteUserMemoryResponse:
         """
+        Permanently remove a specific user memory from storage.
+
+        This endpoint allows you to delete a user memory by its unique identifier.
+        Once deleted, the memory cannot be recovered, so use this operation carefully.
+
+        The memory will be removed from your tenant's storage and will no longer
+        appear in search results or memory listings.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         memory_id : str
+            Unique identifier of the memory to delete
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        DeleteUserMemoryResponse
             Successful Response
 
         Examples
@@ -82,7 +115,7 @@ class UserMemoryClient:
         from usecortex-ai import CortexAI
 
         client = CortexAI(token="YOUR_TOKEN", )
-        client.user_memory.delete_user_memory(tenant_id='tenant_id', memory_id='memory_id', sub_tenant_id='sub_tenant_id', )
+        client.user_memory.delete_user_memory(tenant_id='tenant_1234', memory_id='memory_1234', sub_tenant_id='sub_tenant_4567', )
         """
         _response = self._raw_client.delete_user_memory(
             tenant_id=tenant_id, memory_id=memory_id, sub_tenant_id=sub_tenant_id, request_options=request_options
@@ -94,27 +127,44 @@ class UserMemoryClient:
         *,
         tenant_id: str,
         query: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         max_count: typing.Optional[int] = None,
+        user_name: typing.Optional[str] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> RetrieveUserMemoryResponse:
         """
+        Find relevant user memories using semantic search.
+
+        This endpoint performs a semantic search across all your stored user memories
+        to find the most relevant ones based on your query. The results are ranked by
+        similarity score, with the most relevant memories returned first.
+
+        Use this to recall past preferences, context, or information that might be
+        relevant to your current task or query.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         query : str
+            Search query to find relevant user memories
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         max_count : typing.Optional[int]
+            Maximum number of memories to return (default: 5)
+
+        user_name : typing.Optional[str]
+            User's name to enhance personalisation
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        RetrieveUserMemoryResponse
             Successful Response
 
         Examples
@@ -122,13 +172,14 @@ class UserMemoryClient:
         from usecortex-ai import CortexAI
 
         client = CortexAI(token="YOUR_TOKEN", )
-        client.user_memory.retrieve_user_memory(tenant_id='tenant_id', query='query', sub_tenant_id='sub_tenant_id', )
+        client.user_memory.retrieve_user_memory(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', max_count=5, query='Which mode does user prefer', )
         """
         _response = self._raw_client.retrieve_user_memory(
             tenant_id=tenant_id,
             query=query,
             sub_tenant_id=sub_tenant_id,
             max_count=max_count,
+            user_name=user_name,
             request_options=request_options,
         )
         return _response.data
@@ -137,28 +188,41 @@ class UserMemoryClient:
         self,
         *,
         tenant_id: str,
-        user_query: str,
+        user_message: str,
         user_name: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> GenerateUserMemoryResponse:
         """
+        Generate AI-powered user memories from your query and context.
+
+        This endpoint uses artificial intelligence to create personalized memories
+        based on your query and user context. The AI analyzes your input and generates
+        relevant, contextual memories that can help improve future interactions.
+
+        Generated memories are automatically stored and can be retrieved through
+        the standard memory search endpoints.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
-        user_query : str
+        user_message : str
+            Your query or context for AI memory generation
 
         user_name : str
+            Your name to personalize the generated memories
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        GenerateUserMemoryResponse
             Successful Response
 
         Examples
@@ -166,11 +230,11 @@ class UserMemoryClient:
         from usecortex-ai import CortexAI
 
         client = CortexAI(token="YOUR_TOKEN", )
-        client.user_memory.generate_user_memory(tenant_id='tenant_id', user_query='user_query', user_name='user_name', sub_tenant_id='sub_tenant_id', )
+        client.user_memory.generate_user_memory(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', user_message='I prefer detailed technical explanations and works in the Pacific timezone', user_name='John Doe', )
         """
         _response = self._raw_client.generate_user_memory(
             tenant_id=tenant_id,
-            user_query=user_query,
+            user_message=user_message,
             user_name=user_name,
             sub_tenant_id=sub_tenant_id,
             request_options=request_options,
@@ -182,24 +246,36 @@ class UserMemoryClient:
         *,
         tenant_id: str,
         user_memory: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> AddUserMemoryResponse:
         """
+        Store a new user memory for future reference.
+
+        This endpoint allows you to manually add a memory that will be stored and
+        can be retrieved later through memory search. Use this to save important
+        preferences, context, or information that you want the system to remember.
+
+        The stored memory will be indexed and available for semantic search, making
+        it accessible when relevant to future queries or interactions.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         user_memory : str
+            The memory content to store for future reference
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        AddUserMemoryResponse
             Successful Response
 
         Examples
@@ -207,7 +283,7 @@ class UserMemoryClient:
         from usecortex-ai import CortexAI
 
         client = CortexAI(token="YOUR_TOKEN", )
-        client.user_memory.add_user_memory(tenant_id='tenant_id', user_memory='user_memory', sub_tenant_id='sub_tenant_id', )
+        client.user_memory.add_user_memory(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', user_memory='I prefer detailed technical explanations and works in the Pacific timezone', )
         """
         _response = self._raw_client.add_user_memory(
             tenant_id=tenant_id, user_memory=user_memory, sub_tenant_id=sub_tenant_id, request_options=request_options
@@ -231,21 +307,35 @@ class AsyncUserMemoryClient:
         return self._raw_client
 
     async def list_user_memories(
-        self, *, tenant_id: str, sub_tenant_id: str, request_options: typing.Optional[RequestOptions] = None
-    ) -> typing.Optional[typing.Any]:
+        self,
+        *,
+        tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> ListUserMemoriesResponse:
         """
+        Retrieve all stored user memories for your tenant.
+
+        This endpoint returns a comprehensive list of all user memories that have been stored,
+        whether they were added manually or generated through AI. User memories help personalize
+        your experience by storing context, preferences, and important information.
+
+        You can optionally specify a sub-tenant to filter memories within that specific scope.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        ListUserMemoriesResponse
             Successful Response
 
         Examples
@@ -256,7 +346,7 @@ class AsyncUserMemoryClient:
 
         client = AsyncCortexAI(token="YOUR_TOKEN", )
         async def main() -> None:
-            await client.user_memory.list_user_memories(tenant_id='tenant_id', sub_tenant_id='sub_tenant_id', )
+            await client.user_memory.list_user_memories(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', )
         asyncio.run(main())
         """
         _response = await self._raw_client.list_user_memories(
@@ -269,24 +359,35 @@ class AsyncUserMemoryClient:
         *,
         tenant_id: str,
         memory_id: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> DeleteUserMemoryResponse:
         """
+        Permanently remove a specific user memory from storage.
+
+        This endpoint allows you to delete a user memory by its unique identifier.
+        Once deleted, the memory cannot be recovered, so use this operation carefully.
+
+        The memory will be removed from your tenant's storage and will no longer
+        appear in search results or memory listings.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         memory_id : str
+            Unique identifier of the memory to delete
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        DeleteUserMemoryResponse
             Successful Response
 
         Examples
@@ -297,7 +398,7 @@ class AsyncUserMemoryClient:
 
         client = AsyncCortexAI(token="YOUR_TOKEN", )
         async def main() -> None:
-            await client.user_memory.delete_user_memory(tenant_id='tenant_id', memory_id='memory_id', sub_tenant_id='sub_tenant_id', )
+            await client.user_memory.delete_user_memory(tenant_id='tenant_1234', memory_id='memory_1234', sub_tenant_id='sub_tenant_4567', )
         asyncio.run(main())
         """
         _response = await self._raw_client.delete_user_memory(
@@ -310,27 +411,44 @@ class AsyncUserMemoryClient:
         *,
         tenant_id: str,
         query: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         max_count: typing.Optional[int] = None,
+        user_name: typing.Optional[str] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> RetrieveUserMemoryResponse:
         """
+        Find relevant user memories using semantic search.
+
+        This endpoint performs a semantic search across all your stored user memories
+        to find the most relevant ones based on your query. The results are ranked by
+        similarity score, with the most relevant memories returned first.
+
+        Use this to recall past preferences, context, or information that might be
+        relevant to your current task or query.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         query : str
+            Search query to find relevant user memories
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         max_count : typing.Optional[int]
+            Maximum number of memories to return (default: 5)
+
+        user_name : typing.Optional[str]
+            User's name to enhance personalisation
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        RetrieveUserMemoryResponse
             Successful Response
 
         Examples
@@ -341,7 +459,7 @@ class AsyncUserMemoryClient:
 
         client = AsyncCortexAI(token="YOUR_TOKEN", )
         async def main() -> None:
-            await client.user_memory.retrieve_user_memory(tenant_id='tenant_id', query='query', sub_tenant_id='sub_tenant_id', )
+            await client.user_memory.retrieve_user_memory(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', max_count=5, query='Which mode does user prefer', )
         asyncio.run(main())
         """
         _response = await self._raw_client.retrieve_user_memory(
@@ -349,6 +467,7 @@ class AsyncUserMemoryClient:
             query=query,
             sub_tenant_id=sub_tenant_id,
             max_count=max_count,
+            user_name=user_name,
             request_options=request_options,
         )
         return _response.data
@@ -357,28 +476,41 @@ class AsyncUserMemoryClient:
         self,
         *,
         tenant_id: str,
-        user_query: str,
+        user_message: str,
         user_name: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> GenerateUserMemoryResponse:
         """
+        Generate AI-powered user memories from your query and context.
+
+        This endpoint uses artificial intelligence to create personalized memories
+        based on your query and user context. The AI analyzes your input and generates
+        relevant, contextual memories that can help improve future interactions.
+
+        Generated memories are automatically stored and can be retrieved through
+        the standard memory search endpoints.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
-        user_query : str
+        user_message : str
+            Your query or context for AI memory generation
 
         user_name : str
+            Your name to personalize the generated memories
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        GenerateUserMemoryResponse
             Successful Response
 
         Examples
@@ -389,12 +521,12 @@ class AsyncUserMemoryClient:
 
         client = AsyncCortexAI(token="YOUR_TOKEN", )
         async def main() -> None:
-            await client.user_memory.generate_user_memory(tenant_id='tenant_id', user_query='user_query', user_name='user_name', sub_tenant_id='sub_tenant_id', )
+            await client.user_memory.generate_user_memory(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', user_message='I prefer detailed technical explanations and works in the Pacific timezone', user_name='John Doe', )
         asyncio.run(main())
         """
         _response = await self._raw_client.generate_user_memory(
             tenant_id=tenant_id,
-            user_query=user_query,
+            user_message=user_message,
             user_name=user_name,
             sub_tenant_id=sub_tenant_id,
             request_options=request_options,
@@ -406,24 +538,36 @@ class AsyncUserMemoryClient:
         *,
         tenant_id: str,
         user_memory: str,
-        sub_tenant_id: str,
+        sub_tenant_id: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> typing.Optional[typing.Any]:
+    ) -> AddUserMemoryResponse:
         """
+        Store a new user memory for future reference.
+
+        This endpoint allows you to manually add a memory that will be stored and
+        can be retrieved later through memory search. Use this to save important
+        preferences, context, or information that you want the system to remember.
+
+        The stored memory will be indexed and available for semantic search, making
+        it accessible when relevant to future queries or interactions.
+
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         user_memory : str
+            The memory content to store for future reference
 
-        sub_tenant_id : str
+        sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.Optional[typing.Any]
+        AddUserMemoryResponse
             Successful Response
 
         Examples
@@ -434,7 +578,7 @@ class AsyncUserMemoryClient:
 
         client = AsyncCortexAI(token="YOUR_TOKEN", )
         async def main() -> None:
-            await client.user_memory.add_user_memory(tenant_id='tenant_id', user_memory='user_memory', sub_tenant_id='sub_tenant_id', )
+            await client.user_memory.add_user_memory(tenant_id='tenant_1234', sub_tenant_id='sub_tenant_4567', user_memory='I prefer detailed technical explanations and works in the Pacific timezone', )
         asyncio.run(main())
         """
         _response = await self._raw_client.add_user_memory(