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

usecortex_ai/search/raw_client.py

@@ -52,41 +52,60 @@ class RawSearchClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[typing.Optional[typing.Any]]:
         """
+        Ask a question to your uploaded knowledge base and let Cortex AI answer it.
+
         Parameters
         ----------
         question : str
+            The question to be answered
 
         session_id : str
+            Unique identifier for the conversation session. Keep it same when the current question refers to a previous answer or question
 
         tenant_id : str
+            Identifier for the tenant/organization
 
         context_list : typing.Optional[typing.Sequence[str]]
+            List of context strings to provide additional information
 
         search_modes : typing.Optional[typing.Sequence[str]]
+            List of search modes to use for finding relevant information
 
         sub_tenant_id : typing.Optional[str]
+            Identifier for sub-tenant within the tenant
 
         highlight_chunks : typing.Optional[bool]
+            Whether to return text chunks in the response along with final LLM generated answer
 
         stream : typing.Optional[bool]
+            Whether to stream the response
 
         search_alpha : typing.Optional[float]
+            Closer to 0.0 means a exact keyword search will be performed, closer to 1.0 means semantics of the search will be considered. In most cases, you wont have to toggle it yourself.
 
         recency_bias : typing.Optional[float]
+            Bias towards more recent information (0.0 to 1.0)
 
         ai_generation : typing.Optional[bool]
+            Whether to use AI for generating responses
 
         top_n : typing.Optional[int]
+            Number of top results to return
 
         user_name : typing.Optional[str]
+            Name of the user making the request. This helps LLM to know the user's name if semantics around the username are involved in query. Its generally a good practice to include it possible.
 
         user_instructions : typing.Optional[str]
+            Custom instructions for the AI response to add to our proprietary prompt. This can be used to provide additional context or instructions for the LLM to follow so that the answers are tailored towards your application style
 
         multi_step_reasoning : typing.Optional[bool]
+            Enable advanced multi-step reasoning for complex queries. When enabled, the AI will automatically break down complex questions into multiple research steps to provide more comprehensive and accurate answers.
 
         auto_agent_routing : typing.Optional[bool]
+            Enable intelligent agent routing to automatically select the most suitable AI agent for your specific query type. Different agents are optimized for various use cases like social media, code, conversations, general knowledge, etc.
 
         metadata : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
+            Additional metadata for the request
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -227,45 +246,37 @@ class RawSearchClient:
         max_chunks: typing.Optional[int] = OMIT,
         alpha: typing.Optional[Alpha] = OMIT,
         recency_bias: typing.Optional[float] = OMIT,
-        num_related_chunks: typing.Optional[int] = OMIT,
+        personalise_search: typing.Optional[bool] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[typing.List[SearchChunk]]:
         """
-        Search for content within indexed sources using semantic and keyword search capabilities.
-
-        This endpoint performs a search query against the Findr backend, allowing users to retrieve
-        relevant content chunks from their indexed documents and sources. The search can be customized
-        with various parameters to control the number of results and search behavior.
-
-        Args:
-            request (SearchRequest): The search request containing:
-                - query (str): Search query string to find relevant content
-                - tenant_id (str, optional): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-                - max_chunks (int, optional): Maximum number of content chunks to return
-                - alpha (Union[float, str], optional): Search algorithm parameter for result ranking (default: 0.8). Can be float-type (0.0-1.0) or 'auto' for dynamic selection
-                - recency_bias (float, optional): Bias towards more recent content (default: 0.5)
-                - num_related_chunks (int, optional): Number of related chunks to return (default: 0)
-            api_details (dict): Authentication details obtained from API key validation
-
-        Returns:
-            SearchData: Success response with search results
+        Search for relevant content within your indexed sources.
+
+        This API returns the chunks related to the query you make. We use neural (embedding) search to give you the most relevant chunks.
+        Results are ranked by relevance and can be customized with parameters like result limits and recency preferences.
 
         Parameters
         ----------
         query : str
+            Search terms to find relevant content
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         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_chunks : typing.Optional[int]
+            Maximum number of results to return
 
         alpha : typing.Optional[Alpha]
+            Search ranking algorithm parameter (0.0-1.0 or 'auto')
 
         recency_bias : typing.Optional[float]
+            Preference for newer content (0.0 = no bias, 1.0 = strong recency preference)
 
-        num_related_chunks : typing.Optional[int]
+        personalise_search : typing.Optional[bool]
+            Enable personalized search results based on user preferences
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -285,7 +296,7 @@ class RawSearchClient:
                 "max_chunks": max_chunks,
                 "alpha": convert_and_respect_annotation_metadata(object_=alpha, annotation=Alpha, direction="write"),
                 "recency_bias": recency_bias,
-                "num_related_chunks": num_related_chunks,
+                "personalise_search": personalise_search,
             },
             headers={
                 "content-type": "application/json",
@@ -396,36 +407,27 @@ class RawSearchClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[typing.List[SearchChunk]]:
         """
-        Full text search endpoint for Cortex customers.
-        Performs full text search with configurable operators for precise text matching against the Findr backend.
-
-        This endpoint performs a full text search query against the Findr backend, allowing users to retrieve
-        relevant content chunks from their indexed documents and sources using BM25-based text matching.
-        The search can be customized with various operators to control the matching behavior.
-
-        Args:
-            request (FullTextSearchRequest): The full text search request containing:
-                - query (str): Search query string to find relevant content
-                - tenant_id (str): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-                - operator (BM25OperatorType, optional): Full text search operator type (OR or AND). Defaults to OR
-                - max_chunks (int, optional): Maximum number of content chunks to return (1-1001, defaults to 25)
-            api_details (dict): Authentication details obtained from API key validation
+        Perform full text search for exact matches within your indexed sources.
 
-        Returns:
-            FullTextSearchData: Success response with full text search results
+        Use this endpoint to find content chunks using BM25-based text matching with configurable operators.
+        Choose between 'OR' and 'AND' operators to control how search terms are combined for precise text matching.
 
         Parameters
         ----------
         query : str
+            Search terms to find in your content
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         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.
 
         operator : typing.Optional[Bm25OperatorType]
+            How to combine search terms (OR or AND)
 
         max_chunks : typing.Optional[int]
+            Maximum number of results to return
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -571,41 +573,60 @@ class AsyncRawSearchClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[typing.Optional[typing.Any]]:
         """
+        Ask a question to your uploaded knowledge base and let Cortex AI answer it.
+
         Parameters
         ----------
         question : str
+            The question to be answered
 
         session_id : str
+            Unique identifier for the conversation session. Keep it same when the current question refers to a previous answer or question
 
         tenant_id : str
+            Identifier for the tenant/organization
 
         context_list : typing.Optional[typing.Sequence[str]]
+            List of context strings to provide additional information
 
         search_modes : typing.Optional[typing.Sequence[str]]
+            List of search modes to use for finding relevant information
 
         sub_tenant_id : typing.Optional[str]
+            Identifier for sub-tenant within the tenant
 
         highlight_chunks : typing.Optional[bool]
+            Whether to return text chunks in the response along with final LLM generated answer
 
         stream : typing.Optional[bool]
+            Whether to stream the response
 
         search_alpha : typing.Optional[float]
+            Closer to 0.0 means a exact keyword search will be performed, closer to 1.0 means semantics of the search will be considered. In most cases, you wont have to toggle it yourself.
 
         recency_bias : typing.Optional[float]
+            Bias towards more recent information (0.0 to 1.0)
 
         ai_generation : typing.Optional[bool]
+            Whether to use AI for generating responses
 
         top_n : typing.Optional[int]
+            Number of top results to return
 
         user_name : typing.Optional[str]
+            Name of the user making the request. This helps LLM to know the user's name if semantics around the username are involved in query. Its generally a good practice to include it possible.
 
         user_instructions : typing.Optional[str]
+            Custom instructions for the AI response to add to our proprietary prompt. This can be used to provide additional context or instructions for the LLM to follow so that the answers are tailored towards your application style
 
         multi_step_reasoning : typing.Optional[bool]
+            Enable advanced multi-step reasoning for complex queries. When enabled, the AI will automatically break down complex questions into multiple research steps to provide more comprehensive and accurate answers.
 
         auto_agent_routing : typing.Optional[bool]
+            Enable intelligent agent routing to automatically select the most suitable AI agent for your specific query type. Different agents are optimized for various use cases like social media, code, conversations, general knowledge, etc.
 
         metadata : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
+            Additional metadata for the request
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -746,45 +767,37 @@ class AsyncRawSearchClient:
         max_chunks: typing.Optional[int] = OMIT,
         alpha: typing.Optional[Alpha] = OMIT,
         recency_bias: typing.Optional[float] = OMIT,
-        num_related_chunks: typing.Optional[int] = OMIT,
+        personalise_search: typing.Optional[bool] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[typing.List[SearchChunk]]:
         """
-        Search for content within indexed sources using semantic and keyword search capabilities.
-
-        This endpoint performs a search query against the Findr backend, allowing users to retrieve
-        relevant content chunks from their indexed documents and sources. The search can be customized
-        with various parameters to control the number of results and search behavior.
-
-        Args:
-            request (SearchRequest): The search request containing:
-                - query (str): Search query string to find relevant content
-                - tenant_id (str, optional): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-                - max_chunks (int, optional): Maximum number of content chunks to return
-                - alpha (Union[float, str], optional): Search algorithm parameter for result ranking (default: 0.8). Can be float-type (0.0-1.0) or 'auto' for dynamic selection
-                - recency_bias (float, optional): Bias towards more recent content (default: 0.5)
-                - num_related_chunks (int, optional): Number of related chunks to return (default: 0)
-            api_details (dict): Authentication details obtained from API key validation
-
-        Returns:
-            SearchData: Success response with search results
+        Search for relevant content within your indexed sources.
+
+        This API returns the chunks related to the query you make. We use neural (embedding) search to give you the most relevant chunks.
+        Results are ranked by relevance and can be customized with parameters like result limits and recency preferences.
 
         Parameters
         ----------
         query : str
+            Search terms to find relevant content
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         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_chunks : typing.Optional[int]
+            Maximum number of results to return
 
         alpha : typing.Optional[Alpha]
+            Search ranking algorithm parameter (0.0-1.0 or 'auto')
 
         recency_bias : typing.Optional[float]
+            Preference for newer content (0.0 = no bias, 1.0 = strong recency preference)
 
-        num_related_chunks : typing.Optional[int]
+        personalise_search : typing.Optional[bool]
+            Enable personalized search results based on user preferences
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -804,7 +817,7 @@ class AsyncRawSearchClient:
                 "max_chunks": max_chunks,
                 "alpha": convert_and_respect_annotation_metadata(object_=alpha, annotation=Alpha, direction="write"),
                 "recency_bias": recency_bias,
-                "num_related_chunks": num_related_chunks,
+                "personalise_search": personalise_search,
             },
             headers={
                 "content-type": "application/json",
@@ -915,36 +928,27 @@ class AsyncRawSearchClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[typing.List[SearchChunk]]:
         """
-        Full text search endpoint for Cortex customers.
-        Performs full text search with configurable operators for precise text matching against the Findr backend.
-
-        This endpoint performs a full text search query against the Findr backend, allowing users to retrieve
-        relevant content chunks from their indexed documents and sources using BM25-based text matching.
-        The search can be customized with various operators to control the matching behavior.
-
-        Args:
-            request (FullTextSearchRequest): The full text search request containing:
-                - query (str): Search query string to find relevant content
-                - tenant_id (str): Tenant identifier for multi-tenancy
-                - sub_tenant_id (str, optional): Sub-tenant identifier, defaults to tenant_id
-                - operator (BM25OperatorType, optional): Full text search operator type (OR or AND). Defaults to OR
-                - max_chunks (int, optional): Maximum number of content chunks to return (1-1001, defaults to 25)
-            api_details (dict): Authentication details obtained from API key validation
+        Perform full text search for exact matches within your indexed sources.
 
-        Returns:
-            FullTextSearchData: Success response with full text search results
+        Use this endpoint to find content chunks using BM25-based text matching with configurable operators.
+        Choose between 'OR' and 'AND' operators to control how search terms are combined for precise text matching.
 
         Parameters
         ----------
         query : str
+            Search terms to find in your content
 
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         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.
 
         operator : typing.Optional[Bm25OperatorType]
+            How to combine search terms (OR or AND)
 
         max_chunks : typing.Optional[int]
+            Maximum number of results to return
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

usecortex_ai/sources/client.py

@@ -5,7 +5,6 @@ import typing
 from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
 from ..core.request_options import RequestOptions
 from ..types.list_sources_response import ListSourcesResponse
-from ..types.sub_tenant_ids_data import SubTenantIdsData
 from .raw_client import AsyncRawSourcesClient, RawSourcesClient
 
 # this is used as the default value for optional parameters
@@ -31,49 +30,27 @@ class SourcesClient:
         self,
         *,
         tenant_id: str,
-        sub_tenant_id: typing.Optional[str] = None,
+        source_ids: typing.Sequence[str],
+        sub_tenant_id: typing.Optional[str] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ListSourcesResponse:
         """
-        Parameters
-        ----------
-        tenant_id : str
+        Retrieve specific sources by their IDs.
 
-        sub_tenant_id : typing.Optional[str]
-
-        request_options : typing.Optional[RequestOptions]
-            Request-specific configuration.
-
-        Returns
-        -------
-        ListSourcesResponse
-            Successful Response
-
-        Examples
-        --------
-        from usecortex-ai import CortexAI
+        Use this endpoint to fetch one or more sources by providing their unique identifiers. This is useful when you need detailed information about specific documents or content you've previously uploaded.
 
-        client = CortexAI(token="YOUR_TOKEN", )
-        client.sources.get_all(tenant_id='tenant_id', )
-        """
-        _response = self._raw_client.get_all(
-            tenant_id=tenant_id, sub_tenant_id=sub_tenant_id, request_options=request_options
-        )
-        return _response.data
+        Provide the source IDs in the request body along with your tenant information to get the exact sources you need.
 
-    def get_by_ids(
-        self,
-        *,
-        tenant_id: str,
-        source_ids: typing.Sequence[str],
-        request_options: typing.Optional[RequestOptions] = None,
-    ) -> ListSourcesResponse:
-        """
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         source_ids : typing.Sequence[str]
+            List of source IDs to fetch
+
+        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.
@@ -88,52 +65,13 @@ class SourcesClient:
         from usecortex-ai import CortexAI
 
         client = CortexAI(token="YOUR_TOKEN", )
-        client.sources.get_by_ids(tenant_id='tenant_id', source_ids=['source_ids'], )
+        client.sources.get_all(tenant_id='tenant_1234', source_ids=['CortexDoc1234', 'CortexDoc4567'], )
         """
-        _response = self._raw_client.get_by_ids(
-            tenant_id=tenant_id, source_ids=source_ids, request_options=request_options
+        _response = self._raw_client.get_all(
+            tenant_id=tenant_id, source_ids=source_ids, sub_tenant_id=sub_tenant_id, request_options=request_options
         )
         return _response.data
 
-    def get_sub_tenant_ids(
-        self, *, tenant_id: str, request_options: typing.Optional[RequestOptions] = None
-    ) -> SubTenantIdsData:
-        """
-        Get all sub-tenant IDs (tenant IDs) contained within a specific Weaviate collection.
-        Fetches the tenant IDs directly from Weaviate using default cluster credentials.
-
-        Args:
-            tenant_id: The tenant ID to fetch sub-tenant IDs for
-            api_details: Authentication dependency
-
-        Returns:
-            SubTenantIdsData: Contains collection_name, sub_tenant_ids list, count, and success message
-
-        Example:
-            GET /list/sub_tenant_ids?tenant_id=my_tenant_123
-
-        Parameters
-        ----------
-        tenant_id : str
-
-        request_options : typing.Optional[RequestOptions]
-            Request-specific configuration.
-
-        Returns
-        -------
-        SubTenantIdsData
-            Successful Response
-
-        Examples
-        --------
-        from usecortex-ai import CortexAI
-
-        client = CortexAI(token="YOUR_TOKEN", )
-        client.sources.get_sub_tenant_ids(tenant_id='tenant_id', )
-        """
-        _response = self._raw_client.get_sub_tenant_ids(tenant_id=tenant_id, request_options=request_options)
-        return _response.data
-
 
 class AsyncSourcesClient:
     def __init__(self, *, client_wrapper: AsyncClientWrapper):
@@ -154,53 +92,27 @@ class AsyncSourcesClient:
         self,
         *,
         tenant_id: str,
-        sub_tenant_id: typing.Optional[str] = None,
+        source_ids: typing.Sequence[str],
+        sub_tenant_id: typing.Optional[str] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ListSourcesResponse:
         """
-        Parameters
-        ----------
-        tenant_id : str
+        Retrieve specific sources by their IDs.
 
-        sub_tenant_id : typing.Optional[str]
-
-        request_options : typing.Optional[RequestOptions]
-            Request-specific configuration.
-
-        Returns
-        -------
-        ListSourcesResponse
-            Successful Response
-
-        Examples
-        --------
-        import asyncio
-
-        from usecortex-ai import AsyncCortexAI
+        Use this endpoint to fetch one or more sources by providing their unique identifiers. This is useful when you need detailed information about specific documents or content you've previously uploaded.
 
-        client = AsyncCortexAI(token="YOUR_TOKEN", )
-        async def main() -> None:
-            await client.sources.get_all(tenant_id='tenant_id', )
-        asyncio.run(main())
-        """
-        _response = await self._raw_client.get_all(
-            tenant_id=tenant_id, sub_tenant_id=sub_tenant_id, request_options=request_options
-        )
-        return _response.data
+        Provide the source IDs in the request body along with your tenant information to get the exact sources you need.
 
-    async def get_by_ids(
-        self,
-        *,
-        tenant_id: str,
-        source_ids: typing.Sequence[str],
-        request_options: typing.Optional[RequestOptions] = None,
-    ) -> ListSourcesResponse:
-        """
         Parameters
         ----------
         tenant_id : str
+            Unique identifier for the tenant/organization
 
         source_ids : typing.Sequence[str]
+            List of source IDs to fetch
+
+        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.
@@ -218,53 +130,10 @@ class AsyncSourcesClient:
 
         client = AsyncCortexAI(token="YOUR_TOKEN", )
         async def main() -> None:
-            await client.sources.get_by_ids(tenant_id='tenant_id', source_ids=['source_ids'], )
+            await client.sources.get_all(tenant_id='tenant_1234', source_ids=['CortexDoc1234', 'CortexDoc4567'], )
         asyncio.run(main())
         """
-        _response = await self._raw_client.get_by_ids(
-            tenant_id=tenant_id, source_ids=source_ids, request_options=request_options
+        _response = await self._raw_client.get_all(
+            tenant_id=tenant_id, source_ids=source_ids, sub_tenant_id=sub_tenant_id, request_options=request_options
         )
         return _response.data
-
-    async def get_sub_tenant_ids(
-        self, *, tenant_id: str, request_options: typing.Optional[RequestOptions] = None
-    ) -> SubTenantIdsData:
-        """
-        Get all sub-tenant IDs (tenant IDs) contained within a specific Weaviate collection.
-        Fetches the tenant IDs directly from Weaviate using default cluster credentials.
-
-        Args:
-            tenant_id: The tenant ID to fetch sub-tenant IDs for
-            api_details: Authentication dependency
-
-        Returns:
-            SubTenantIdsData: Contains collection_name, sub_tenant_ids list, count, and success message
-
-        Example:
-            GET /list/sub_tenant_ids?tenant_id=my_tenant_123
-
-        Parameters
-        ----------
-        tenant_id : str
-
-        request_options : typing.Optional[RequestOptions]
-            Request-specific configuration.
-
-        Returns
-        -------
-        SubTenantIdsData
-            Successful Response
-
-        Examples
-        --------
-        import asyncio
-
-        from usecortex-ai import AsyncCortexAI
-
-        client = AsyncCortexAI(token="YOUR_TOKEN", )
-        async def main() -> None:
-            await client.sources.get_sub_tenant_ids(tenant_id='tenant_id', )
-        asyncio.run(main())
-        """
-        _response = await self._raw_client.get_sub_tenant_ids(tenant_id=tenant_id, request_options=request_options)
-        return _response.data