"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""

from .basesdk import BaseSDK
from duckyai import models, utils
from duckyai._hooks import HookContext
from duckyai.types import OptionalNullable, UNSET
from duckyai.utils import get_security_from_env
from typing import Any, Dict, Mapping, Optional


class Documents(BaseSDK):
    def index(
        self,
        *,
        index_name: str,
        content: str,
        doc_id: Optional[str] = None,
        title: Optional[str] = None,
        url: Optional[str] = None,
        metadata: Optional[Dict[str, Any]] = None,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ) -> models.DocumentIndexedResponse:
        r"""Index a document from text content

        Index a document into the specified index by providing the content as a JSON object.

        :param index_name: The name of the index to add the document to
        :param content: The text content of the document to be indexed
        :param doc_id: The ID of the document. If not provided, a unique document ID will be automatically generated by the server.
        :param title: Title of the document to be indexed
        :param url: URL associated with the document to be indexed
        :param metadata: Metadata associated with the document. Accepts key value pairs where the value can be a string, number, boolean, or list of strings.
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.IndexTextRequest(
            index_name=index_name,
            doc_id=doc_id,
            content=content,
            title=title,
            url=url,
            metadata=metadata,
        )

        req = self.build_request(
            method="POST",
            path="/v1/documents/index-text",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=True,
            request_has_path_params=False,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            get_serialized_body=lambda: utils.serialize_request_body(
                request, False, False, "json", models.IndexTextRequest
            ),
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = self.do_request(
            hook_ctx=HookContext(
                operation_id="indexText",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "202", "application/json"):
            return utils.unmarshal_json(http_res.text, models.DocumentIndexedResponse)
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = utils.stream_to_text(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = utils.stream_to_text(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    async def index_async(
        self,
        *,
        index_name: str,
        content: str,
        doc_id: Optional[str] = None,
        title: Optional[str] = None,
        url: Optional[str] = None,
        metadata: Optional[Dict[str, Any]] = None,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ) -> models.DocumentIndexedResponse:
        r"""Index a document from text content

        Index a document into the specified index by providing the content as a JSON object.

        :param index_name: The name of the index to add the document to
        :param content: The text content of the document to be indexed
        :param doc_id: The ID of the document. If not provided, a unique document ID will be automatically generated by the server.
        :param title: Title of the document to be indexed
        :param url: URL associated with the document to be indexed
        :param metadata: Metadata associated with the document. Accepts key value pairs where the value can be a string, number, boolean, or list of strings.
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.IndexTextRequest(
            index_name=index_name,
            doc_id=doc_id,
            content=content,
            title=title,
            url=url,
            metadata=metadata,
        )

        req = self.build_request_async(
            method="POST",
            path="/v1/documents/index-text",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=True,
            request_has_path_params=False,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            get_serialized_body=lambda: utils.serialize_request_body(
                request, False, False, "json", models.IndexTextRequest
            ),
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = await self.do_request_async(
            hook_ctx=HookContext(
                operation_id="indexText",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "202", "application/json"):
            return utils.unmarshal_json(http_res.text, models.DocumentIndexedResponse)
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = await utils.stream_to_text_async(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = await utils.stream_to_text_async(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    def delete(
        self,
        *,
        doc_id: str,
        index_name: str,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ):
        r"""Delete a document

        Delete a specific document by providing its unique identifier.

        :param doc_id: The unique ID of the document to delete
        :param index_name: The name of the index containing the document
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.DeleteDocumentRequest(
            doc_id=doc_id,
            index_name=index_name,
        )

        req = self.build_request(
            method="DELETE",
            path="/v1/documents/{doc_id}",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=False,
            request_has_path_params=True,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = self.do_request(
            hook_ctx=HookContext(
                operation_id="deleteDocument",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "202", "*"):
            return
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = utils.stream_to_text(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = utils.stream_to_text(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    async def delete_async(
        self,
        *,
        doc_id: str,
        index_name: str,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ):
        r"""Delete a document

        Delete a specific document by providing its unique identifier.

        :param doc_id: The unique ID of the document to delete
        :param index_name: The name of the index containing the document
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.DeleteDocumentRequest(
            doc_id=doc_id,
            index_name=index_name,
        )

        req = self.build_request_async(
            method="DELETE",
            path="/v1/documents/{doc_id}",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=False,
            request_has_path_params=True,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = await self.do_request_async(
            hook_ctx=HookContext(
                operation_id="deleteDocument",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "202", "*"):
            return
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = await utils.stream_to_text_async(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = await utils.stream_to_text_async(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    def get(
        self,
        *,
        doc_id: str,
        index_name: str,
        limit: Optional[int] = None,
        cursor: Optional[str] = None,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ) -> models.DocumentRetrievedResponse:
        r"""Get a document by ID with pagination

        Retrieve a specific document by providing the document ID, supporting pagination for large documents with multiple chunks.

        :param doc_id: The unique ID of the document to retrieve
        :param index_name: The name of the index containing the document
        :param limit: The maximum number of chunks to return in the response
        :param cursor: A cursor to fetch the next set of chunks if the document is paginated
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.GetDocumentRequest(
            doc_id=doc_id,
            index_name=index_name,
            limit=limit,
            cursor=cursor,
        )

        req = self.build_request(
            method="GET",
            path="/v1/documents/{doc_id}",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=False,
            request_has_path_params=True,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = self.do_request(
            hook_ctx=HookContext(
                operation_id="getDocument",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "200", "application/json"):
            return utils.unmarshal_json(http_res.text, models.DocumentRetrievedResponse)
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = utils.stream_to_text(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = utils.stream_to_text(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    async def get_async(
        self,
        *,
        doc_id: str,
        index_name: str,
        limit: Optional[int] = None,
        cursor: Optional[str] = None,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ) -> models.DocumentRetrievedResponse:
        r"""Get a document by ID with pagination

        Retrieve a specific document by providing the document ID, supporting pagination for large documents with multiple chunks.

        :param doc_id: The unique ID of the document to retrieve
        :param index_name: The name of the index containing the document
        :param limit: The maximum number of chunks to return in the response
        :param cursor: A cursor to fetch the next set of chunks if the document is paginated
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.GetDocumentRequest(
            doc_id=doc_id,
            index_name=index_name,
            limit=limit,
            cursor=cursor,
        )

        req = self.build_request_async(
            method="GET",
            path="/v1/documents/{doc_id}",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=False,
            request_has_path_params=True,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = await self.do_request_async(
            hook_ctx=HookContext(
                operation_id="getDocument",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "200", "application/json"):
            return utils.unmarshal_json(http_res.text, models.DocumentRetrievedResponse)
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = await utils.stream_to_text_async(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = await utils.stream_to_text_async(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    def retrieve(
        self,
        *,
        index_name: str,
        query: str,
        top_k: int,
        alpha: Optional[float] = None,
        rerank: Optional[bool] = None,
        metadata_filter: Optional[Dict[str, Any]] = None,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ) -> models.RetrieveDocumentsResponse:
        r"""Retrieve documents from an index

        Retrieve documents from an index using a query, top_k, and other parameters

        :param index_name: The name of the index to retrieve documents from
        :param query: The search query used for retrieving documents
        :param top_k: The number of documents to retrieve
        :param alpha: Between 0 and 1, configures balance between keyword and semantic retrieval
        :param rerank: Whether to rerank the results after retrieval
        :param metadata_filter: The filter object is used to specify query criteria for filtering results. Each key in the filter object represents a field name, and its value is a dictionary of comparison operators. Logical operators can be used within these dictionaries to combine multiple conditions.  - **Comparison Operators**:   - **`$eq`**: Checks if a field is equal to a specified value (string, number, or boolean).     - Simplified form: `\"field1\": \"value1\"` is equivalent to `\"field1\": {\"$eq\": \"value1\"}`.   - **`$ne`**: Checks if a field is not equal to a specified value (string, number, or boolean).   - **`$gt`**: Checks if a field is greater than a specified numeric value.   - **`$gte`**: Checks if a field is greater than or equal to a specified numeric value.   - **`$lt`**: Checks if a field is less than a specified numeric value.   - **`$lte`**: Checks if a field is less than or equal to a specified numeric value.   - **`$in`**: Checks if a field's value is within a specified list of values (strings, numbers).   - **`$nin`**: Checks if a field's value is not within a specified list of values (strings, numbers).  - **Logical Operators** (used within field-specific dictionaries):   - **`$and`**: An array of filter objects, all of which must evaluate to true.   - **`$or`**: An array of filter objects, at least one of which must evaluate to true.  Example: ```json {   \"field1\": \"value1\",  // Simplified equals check   \"field2\": {\"$gt\": 10},   \"field3\": {     \"$or\": [       {\"$in\": [\"value2\", \"value3\"]},       {\"$ne\": \"value4\"}     ]   } } ```
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.RetrieveDocumentsRequest(
            index_name=index_name,
            query=query,
            top_k=top_k,
            alpha=alpha,
            rerank=rerank,
            metadata_filter=metadata_filter,
        )

        req = self.build_request(
            method="POST",
            path="/v1/documents/retrieve",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=True,
            request_has_path_params=False,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            get_serialized_body=lambda: utils.serialize_request_body(
                request, False, False, "json", models.RetrieveDocumentsRequest
            ),
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = self.do_request(
            hook_ctx=HookContext(
                operation_id="retrieveDocuments",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "200", "application/json"):
            return utils.unmarshal_json(http_res.text, models.RetrieveDocumentsResponse)
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = utils.stream_to_text(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = utils.stream_to_text(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )

    async def retrieve_async(
        self,
        *,
        index_name: str,
        query: str,
        top_k: int,
        alpha: Optional[float] = None,
        rerank: Optional[bool] = None,
        metadata_filter: Optional[Dict[str, Any]] = None,
        retries: OptionalNullable[utils.RetryConfig] = UNSET,
        server_url: Optional[str] = None,
        timeout_ms: Optional[int] = None,
        http_headers: Optional[Mapping[str, str]] = None,
    ) -> models.RetrieveDocumentsResponse:
        r"""Retrieve documents from an index

        Retrieve documents from an index using a query, top_k, and other parameters

        :param index_name: The name of the index to retrieve documents from
        :param query: The search query used for retrieving documents
        :param top_k: The number of documents to retrieve
        :param alpha: Between 0 and 1, configures balance between keyword and semantic retrieval
        :param rerank: Whether to rerank the results after retrieval
        :param metadata_filter: The filter object is used to specify query criteria for filtering results. Each key in the filter object represents a field name, and its value is a dictionary of comparison operators. Logical operators can be used within these dictionaries to combine multiple conditions.  - **Comparison Operators**:   - **`$eq`**: Checks if a field is equal to a specified value (string, number, or boolean).     - Simplified form: `\"field1\": \"value1\"` is equivalent to `\"field1\": {\"$eq\": \"value1\"}`.   - **`$ne`**: Checks if a field is not equal to a specified value (string, number, or boolean).   - **`$gt`**: Checks if a field is greater than a specified numeric value.   - **`$gte`**: Checks if a field is greater than or equal to a specified numeric value.   - **`$lt`**: Checks if a field is less than a specified numeric value.   - **`$lte`**: Checks if a field is less than or equal to a specified numeric value.   - **`$in`**: Checks if a field's value is within a specified list of values (strings, numbers).   - **`$nin`**: Checks if a field's value is not within a specified list of values (strings, numbers).  - **Logical Operators** (used within field-specific dictionaries):   - **`$and`**: An array of filter objects, all of which must evaluate to true.   - **`$or`**: An array of filter objects, at least one of which must evaluate to true.  Example: ```json {   \"field1\": \"value1\",  // Simplified equals check   \"field2\": {\"$gt\": 10},   \"field3\": {     \"$or\": [       {\"$in\": [\"value2\", \"value3\"]},       {\"$ne\": \"value4\"}     ]   } } ```
        :param retries: Override the default retry configuration for this method
        :param server_url: Override the default server URL for this method
        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
        :param http_headers: Additional headers to set or replace on requests.
        """
        base_url = None
        url_variables = None
        if timeout_ms is None:
            timeout_ms = self.sdk_configuration.timeout_ms

        if server_url is not None:
            base_url = server_url

        request = models.RetrieveDocumentsRequest(
            index_name=index_name,
            query=query,
            top_k=top_k,
            alpha=alpha,
            rerank=rerank,
            metadata_filter=metadata_filter,
        )

        req = self.build_request_async(
            method="POST",
            path="/v1/documents/retrieve",
            base_url=base_url,
            url_variables=url_variables,
            request=request,
            request_body_required=True,
            request_has_path_params=False,
            request_has_query_params=True,
            user_agent_header="user-agent",
            accept_header_value="application/json",
            http_headers=http_headers,
            security=self.sdk_configuration.security,
            get_serialized_body=lambda: utils.serialize_request_body(
                request, False, False, "json", models.RetrieveDocumentsRequest
            ),
            timeout_ms=timeout_ms,
        )

        if retries == UNSET:
            if self.sdk_configuration.retry_config is not UNSET:
                retries = self.sdk_configuration.retry_config

        retry_config = None
        if isinstance(retries, utils.RetryConfig):
            retry_config = (retries, ["429", "500", "502", "503", "504"])

        http_res = await self.do_request_async(
            hook_ctx=HookContext(
                operation_id="retrieveDocuments",
                oauth2_scopes=[],
                security_source=get_security_from_env(
                    self.sdk_configuration.security, models.Security
                ),
            ),
            request=req,
            error_status_codes=["400", "404", "4XX", "5XX"],
            retry_config=retry_config,
        )

        data: Any = None
        if utils.match_response(http_res, "200", "application/json"):
            return utils.unmarshal_json(http_res.text, models.RetrieveDocumentsResponse)
        if utils.match_response(http_res, ["400", "404"], "application/json"):
            data = utils.unmarshal_json(http_res.text, models.ErrorResponseData)
            raise models.ErrorResponse(data=data)
        if utils.match_response(http_res, ["4XX", "5XX"], "*"):
            http_res_text = await utils.stream_to_text_async(http_res)
            raise models.APIError(
                "API error occurred", http_res.status_code, http_res_text, http_res
            )

        content_type = http_res.headers.get("Content-Type")
        http_res_text = await utils.stream_to_text_async(http_res)
        raise models.APIError(
            f"Unexpected response received (code: {http_res.status_code}, type: {content_type})",
            http_res.status_code,
            http_res_text,
            http_res,
        )
