usecortex-ai 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

usecortex_ai/embeddings/raw_client.py

@@ -38,28 +38,20 @@ class RawEmbeddingsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[EmbeddingsDeleteData]:
         """
-        Delete specific embedding chunks from indexed sources.
+        Delete embedding chunks by chunk ID.
 
-        This endpoint deletes specified embedding chunks from the Findr backend by sending
-        chunk IDs to the backend delete service.
-
-        Args:
-            request (EmbeddingsDeleteRequest): The delete request containing:
-                - chunk_ids (List[str]): List of chunk IDs to delete
-                - tenant_id (str): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-            api_details (dict): Authentication details obtained from API key validation
-
-        Returns:
-            EmbeddingsDeleteData: Success response with deletion details
+        Use this to remove specific chunks from your embeddings index when they are no longer valid or should not appear in results.
 
         Parameters
         ----------
         chunk_ids : typing.Sequence[str]
+            The chunk IDs of the source you want to delete
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -178,37 +170,31 @@ class RawEmbeddingsClient:
     def search(
         self,
         *,
-        embeddings: typing.Sequence[float],
         tenant_id: str,
+        embeddings: typing.Optional[typing.Sequence[float]] = OMIT,
         sub_tenant_id: typing.Optional[str] = OMIT,
         max_chunks: typing.Optional[int] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[EmbeddingsSearchData]:
         """
-        Search for similar embedding chunks using vector similarity.
+        Find similar chunks using an embedding vector.
 
-        This endpoint performs semantic search by sending an embedding vector to the Findr backend
-        and returns a list of the most similar chunk IDs based on vector similarity.
+        Use this to retrieve the most similar chunk IDs to a single query embedding.
 
-        Args:
-            request (EmbeddingsSearchRequest): The search request containing:
-                - embeddings (List[float]): Single embedding vector for similarity search
-                - tenant_id (str): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-                - max_chunks (int, optional): Maximum number of chunk IDs to return (default: 10)
-            api_details (dict): Authentication details obtained from API key validation
 
-        Returns:
-            EmbeddingsSearchData: List of chunk IDs with similarity scores
+        Expected outcome
+        - You receive the closest chunk IDs with optional similarity scores.
 
         Parameters
         ----------
-        embeddings : typing.Sequence[float]
-            Single embedding vector for search
-
         tenant_id : str
+            Unique identifier for the tenant/organization
+
+        embeddings : typing.Optional[typing.Sequence[float]]
+            The embedding vector for search
 
         sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id
 
         max_chunks : typing.Optional[int]
 
@@ -224,8 +210,8 @@ class RawEmbeddingsClient:
             "embeddings/search",
             method="POST",
             json={
-                "embeddings": embeddings,
                 "tenant_id": tenant_id,
+                "embeddings": embeddings,
                 "sub_tenant_id": sub_tenant_id,
                 "max_chunks": max_chunks,
             },
@@ -336,20 +322,20 @@ class RawEmbeddingsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[EmbeddingsGetData]:
         """
-        Get embeddings based on chunk IDs.
+        Retrieve embeddings for specific chunk IDs.
 
-        This endpoint returns embeddings for a list of chunk IDs.
-
-        Returns:
-            EmbeddingsGetData: Embeddings data for the requested chunk IDs
+        Use this when you already know the chunk IDs and need their corresponding embeddings.
 
         Parameters
         ----------
         chunk_ids : typing.Sequence[str]
+            The chunk IDs of the source you want to get embeddings for
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -469,16 +455,14 @@ class RawEmbeddingsClient:
         self, *, tenant_id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[EmbeddingsCreateCollectionData]:
         """
-        Create an embeddings collection for the given tenant in Findr.
-
-        sub_tenant_id is set to be the same as tenant_id as per requirements.
+        Create an embeddings collection for a tenant.
 
-        Returns:
-            EmbeddingsCreateCollectionData: Success response with collection details
+        Use this to initialize storage so you can index and query embeddings for the tenant.
 
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -602,28 +586,20 @@ class AsyncRawEmbeddingsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[EmbeddingsDeleteData]:
         """
-        Delete specific embedding chunks from indexed sources.
+        Delete embedding chunks by chunk ID.
 
-        This endpoint deletes specified embedding chunks from the Findr backend by sending
-        chunk IDs to the backend delete service.
-
-        Args:
-            request (EmbeddingsDeleteRequest): The delete request containing:
-                - chunk_ids (List[str]): List of chunk IDs to delete
-                - tenant_id (str): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-            api_details (dict): Authentication details obtained from API key validation
-
-        Returns:
-            EmbeddingsDeleteData: Success response with deletion details
+        Use this to remove specific chunks from your embeddings index when they are no longer valid or should not appear in results.
 
         Parameters
         ----------
         chunk_ids : typing.Sequence[str]
+            The chunk IDs of the source you want to delete
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -742,37 +718,31 @@ class AsyncRawEmbeddingsClient:
     async def search(
         self,
         *,
-        embeddings: typing.Sequence[float],
         tenant_id: str,
+        embeddings: typing.Optional[typing.Sequence[float]] = OMIT,
         sub_tenant_id: typing.Optional[str] = OMIT,
         max_chunks: typing.Optional[int] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[EmbeddingsSearchData]:
         """
-        Search for similar embedding chunks using vector similarity.
+        Find similar chunks using an embedding vector.
 
-        This endpoint performs semantic search by sending an embedding vector to the Findr backend
-        and returns a list of the most similar chunk IDs based on vector similarity.
+        Use this to retrieve the most similar chunk IDs to a single query embedding.
 
-        Args:
-            request (EmbeddingsSearchRequest): The search request containing:
-                - embeddings (List[float]): Single embedding vector for similarity search
-                - tenant_id (str): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-                - max_chunks (int, optional): Maximum number of chunk IDs to return (default: 10)
-            api_details (dict): Authentication details obtained from API key validation
 
-        Returns:
-            EmbeddingsSearchData: List of chunk IDs with similarity scores
+        Expected outcome
+        - You receive the closest chunk IDs with optional similarity scores.
 
         Parameters
         ----------
-        embeddings : typing.Sequence[float]
-            Single embedding vector for search
-
         tenant_id : str
+            Unique identifier for the tenant/organization
+
+        embeddings : typing.Optional[typing.Sequence[float]]
+            The embedding vector for search
 
         sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id
 
         max_chunks : typing.Optional[int]
 
@@ -788,8 +758,8 @@ class AsyncRawEmbeddingsClient:
             "embeddings/search",
             method="POST",
             json={
-                "embeddings": embeddings,
                 "tenant_id": tenant_id,
+                "embeddings": embeddings,
                 "sub_tenant_id": sub_tenant_id,
                 "max_chunks": max_chunks,
             },
@@ -900,20 +870,20 @@ class AsyncRawEmbeddingsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[EmbeddingsGetData]:
         """
-        Get embeddings based on chunk IDs.
+        Retrieve embeddings for specific chunk IDs.
 
-        This endpoint returns embeddings for a list of chunk IDs.
-
-        Returns:
-            EmbeddingsGetData: Embeddings data for the requested chunk IDs
+        Use this when you already know the chunk IDs and need their corresponding embeddings.
 
         Parameters
         ----------
         chunk_ids : typing.Sequence[str]
+            The chunk IDs of the source you want to get embeddings for
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         sub_tenant_id : typing.Optional[str]
+            Optional sub-tenant identifier for organizing data within a tenant. If not provided, defaults to tenant_id
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -1033,16 +1003,14 @@ class AsyncRawEmbeddingsClient:
         self, *, tenant_id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[EmbeddingsCreateCollectionData]:
         """
-        Create an embeddings collection for the given tenant in Findr.
-
-        sub_tenant_id is set to be the same as tenant_id as per requirements.
+        Create an embeddings collection for a tenant.
 
-        Returns:
-            EmbeddingsCreateCollectionData: Success response with collection details
+        Use this to initialize storage so you can index and query embeddings for the tenant.
 
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

usecortex_ai/fetch/client.py

@@ -40,14 +40,19 @@ class FetchClient:
         Parameters
         ----------
         file_id : str
+            Unique identifier for the file to fetch
 
         file_type : str
+            Type of file (e.g., 'app', 'file', or other)
 
         tenant_id : str
+            Tenant identifier for multi-tenancy
 
         return_content : typing.Optional[bool]
+            Whether to return the file content along with the URL
 
         sub_tenant_id : typing.Optional[str]
+            Sub-tenant identifier, defaults to tenant_id if not provided
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -104,14 +109,19 @@ class AsyncFetchClient:
         Parameters
         ----------
         file_id : str
+            Unique identifier for the file to fetch
 
         file_type : str
+            Type of file (e.g., 'app', 'file', or other)
 
         tenant_id : str
+            Tenant identifier for multi-tenancy
 
         return_content : typing.Optional[bool]
+            Whether to return the file content along with the URL
 
         sub_tenant_id : typing.Optional[str]
+            Sub-tenant identifier, defaults to tenant_id if not provided
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

usecortex_ai/fetch/raw_client.py

@@ -40,14 +40,19 @@ class RawFetchClient:
         Parameters
         ----------
         file_id : str
+            Unique identifier for the file to fetch
 
         file_type : str
+            Type of file (e.g., 'app', 'file', or other)
 
         tenant_id : str
+            Tenant identifier for multi-tenancy
 
         return_content : typing.Optional[bool]
+            Whether to return the file content along with the URL
 
         sub_tenant_id : typing.Optional[str]
+            Sub-tenant identifier, defaults to tenant_id if not provided
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -184,14 +189,19 @@ class AsyncRawFetchClient:
         Parameters
         ----------
         file_id : str
+            Unique identifier for the file to fetch
 
         file_type : str
+            Type of file (e.g., 'app', 'file', or other)
 
         tenant_id : str
+            Tenant identifier for multi-tenancy
 
         return_content : typing.Optional[bool]
+            Whether to return the file content along with the URL
 
         sub_tenant_id : typing.Optional[str]
+            Sub-tenant identifier, defaults to tenant_id if not provided
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.