# This file was auto-generated by Fern from our API Definition.

import typing
from ..core.client_wrapper import SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.retriever import Retriever
from ..core.pydantic_utilities import parse_obj_as
from ..errors.unprocessable_entity_error import UnprocessableEntityError
from ..types.http_validation_error import HttpValidationError
from json.decoder import JSONDecodeError
from ..core.api_error import ApiError
from ..types.retriever_pipeline import RetrieverPipeline
from ..core.serialization import convert_and_respect_annotation_metadata
from ..core.jsonable_encoder import jsonable_encoder
from ..types.composite_retrieval_mode import CompositeRetrievalMode
from ..types.composite_retrieval_result import CompositeRetrievalResult
from ..core.client_wrapper import AsyncClientWrapper

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class RetrieversClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._client_wrapper = client_wrapper

    def list_retrievers(
        self,
        *,
        name: typing.Optional[str] = None,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.List[Retriever]:
        """
        List Retrievers for a project.

        Parameters
        ----------
        name : typing.Optional[str]

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[Retriever]
            Successful Response

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.list_retrievers()
        """
        _response = self._client_wrapper.httpx_client.request(
            "api/v1/retrievers",
            method="GET",
            params={
                "name": name,
                "project_id": project_id,
                "organization_id": organization_id,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    typing.List[Retriever],
                    parse_obj_as(
                        type_=typing.List[Retriever],  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def create_retriever(
        self,
        *,
        name: str,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        pipelines: typing.Optional[typing.Sequence[RetrieverPipeline]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Create a new Retriever.

        Parameters
        ----------
        name : str
            A name for the retriever tool. Will default to the pipeline name if not provided.

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        pipelines : typing.Optional[typing.Sequence[RetrieverPipeline]]
            The pipelines this retriever uses.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.create_retriever(
            name="name",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            "api/v1/retrievers",
            method="POST",
            params={
                "project_id": project_id,
                "organization_id": organization_id,
            },
            json={
                "name": name,
                "pipelines": convert_and_respect_annotation_metadata(
                    object_=pipelines, annotation=typing.Sequence[RetrieverPipeline], direction="write"
                ),
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def upsert_retriever(
        self,
        *,
        name: str,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        pipelines: typing.Optional[typing.Sequence[RetrieverPipeline]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Upsert a new Retriever.

        Parameters
        ----------
        name : str
            A name for the retriever tool. Will default to the pipeline name if not provided.

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        pipelines : typing.Optional[typing.Sequence[RetrieverPipeline]]
            The pipelines this retriever uses.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.upsert_retriever(
            name="name",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            "api/v1/retrievers",
            method="PUT",
            params={
                "project_id": project_id,
                "organization_id": organization_id,
            },
            json={
                "name": name,
                "pipelines": convert_and_respect_annotation_metadata(
                    object_=pipelines, annotation=typing.Sequence[RetrieverPipeline], direction="write"
                ),
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def get_retriever(
        self,
        retriever_id: str,
        *,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Get a Retriever by ID.

        Parameters
        ----------
        retriever_id : str

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.get_retriever(
            retriever_id="retriever_id",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}",
            method="GET",
            params={
                "project_id": project_id,
                "organization_id": organization_id,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def update_retriever(
        self,
        retriever_id: str,
        *,
        name: typing.Optional[str] = OMIT,
        pipelines: typing.Optional[typing.Sequence[RetrieverPipeline]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Update an existing Retriever.

        Parameters
        ----------
        retriever_id : str

        name : typing.Optional[str]
            A name for the retriever.

        pipelines : typing.Optional[typing.Sequence[RetrieverPipeline]]
            The pipelines this retriever uses.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.update_retriever(
            retriever_id="retriever_id",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}",
            method="PUT",
            json={
                "name": name,
                "pipelines": convert_and_respect_annotation_metadata(
                    object_=pipelines, annotation=typing.Sequence[RetrieverPipeline], direction="write"
                ),
            },
            headers={
                "content-type": "application/json",
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def delete_retriever(self, retriever_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Delete a Retriever by ID.

        Parameters
        ----------
        retriever_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.delete_retriever(
            retriever_id="retriever_id",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}",
            method="DELETE",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    def retrieve(
        self,
        retriever_id: str,
        *,
        query: str,
        mode: typing.Optional[CompositeRetrievalMode] = OMIT,
        rerank_top_n: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CompositeRetrievalResult:
        """
        Retrieve data using a Retriever.

        Parameters
        ----------
        retriever_id : str

        query : str
            The query to retrieve against.

        mode : typing.Optional[CompositeRetrievalMode]
            The mode of composite retrieval.

        rerank_top_n : typing.Optional[int]
            The number of nodes to retrieve after reranking over retrieved nodes from all retrieval tools.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CompositeRetrievalResult
            Successful Response

        Examples
        --------
        from llama_index import LlamaCloud

        client = LlamaCloud(
            token="YOUR_TOKEN",
        )
        client.retrievers.retrieve(
            retriever_id="retriever_id",
            query="query",
        )
        """
        _response = self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}/retrieve",
            method="POST",
            json={
                "mode": mode,
                "rerank_top_n": rerank_top_n,
                "query": query,
            },
            headers={
                "content-type": "application/json",
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    CompositeRetrievalResult,
                    parse_obj_as(
                        type_=CompositeRetrievalResult,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)


class AsyncRetrieversClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._client_wrapper = client_wrapper

    async def list_retrievers(
        self,
        *,
        name: typing.Optional[str] = None,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.List[Retriever]:
        """
        List Retrievers for a project.

        Parameters
        ----------
        name : typing.Optional[str]

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        typing.List[Retriever]
            Successful Response

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.list_retrievers()


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            "api/v1/retrievers",
            method="GET",
            params={
                "name": name,
                "project_id": project_id,
                "organization_id": organization_id,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    typing.List[Retriever],
                    parse_obj_as(
                        type_=typing.List[Retriever],  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def create_retriever(
        self,
        *,
        name: str,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        pipelines: typing.Optional[typing.Sequence[RetrieverPipeline]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Create a new Retriever.

        Parameters
        ----------
        name : str
            A name for the retriever tool. Will default to the pipeline name if not provided.

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        pipelines : typing.Optional[typing.Sequence[RetrieverPipeline]]
            The pipelines this retriever uses.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.create_retriever(
                name="name",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            "api/v1/retrievers",
            method="POST",
            params={
                "project_id": project_id,
                "organization_id": organization_id,
            },
            json={
                "name": name,
                "pipelines": convert_and_respect_annotation_metadata(
                    object_=pipelines, annotation=typing.Sequence[RetrieverPipeline], direction="write"
                ),
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def upsert_retriever(
        self,
        *,
        name: str,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        pipelines: typing.Optional[typing.Sequence[RetrieverPipeline]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Upsert a new Retriever.

        Parameters
        ----------
        name : str
            A name for the retriever tool. Will default to the pipeline name if not provided.

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        pipelines : typing.Optional[typing.Sequence[RetrieverPipeline]]
            The pipelines this retriever uses.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.upsert_retriever(
                name="name",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            "api/v1/retrievers",
            method="PUT",
            params={
                "project_id": project_id,
                "organization_id": organization_id,
            },
            json={
                "name": name,
                "pipelines": convert_and_respect_annotation_metadata(
                    object_=pipelines, annotation=typing.Sequence[RetrieverPipeline], direction="write"
                ),
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def get_retriever(
        self,
        retriever_id: str,
        *,
        project_id: typing.Optional[str] = None,
        organization_id: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Get a Retriever by ID.

        Parameters
        ----------
        retriever_id : str

        project_id : typing.Optional[str]

        organization_id : typing.Optional[str]

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.get_retriever(
                retriever_id="retriever_id",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}",
            method="GET",
            params={
                "project_id": project_id,
                "organization_id": organization_id,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def update_retriever(
        self,
        retriever_id: str,
        *,
        name: typing.Optional[str] = OMIT,
        pipelines: typing.Optional[typing.Sequence[RetrieverPipeline]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> Retriever:
        """
        Update an existing Retriever.

        Parameters
        ----------
        retriever_id : str

        name : typing.Optional[str]
            A name for the retriever.

        pipelines : typing.Optional[typing.Sequence[RetrieverPipeline]]
            The pipelines this retriever uses.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        Retriever
            Successful Response

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.update_retriever(
                retriever_id="retriever_id",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}",
            method="PUT",
            json={
                "name": name,
                "pipelines": convert_and_respect_annotation_metadata(
                    object_=pipelines, annotation=typing.Sequence[RetrieverPipeline], direction="write"
                ),
            },
            headers={
                "content-type": "application/json",
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    Retriever,
                    parse_obj_as(
                        type_=Retriever,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def delete_retriever(
        self, retriever_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> None:
        """
        Delete a Retriever by ID.

        Parameters
        ----------
        retriever_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.delete_retriever(
                retriever_id="retriever_id",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}",
            method="DELETE",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                return
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)

    async def retrieve(
        self,
        retriever_id: str,
        *,
        query: str,
        mode: typing.Optional[CompositeRetrievalMode] = OMIT,
        rerank_top_n: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> CompositeRetrievalResult:
        """
        Retrieve data using a Retriever.

        Parameters
        ----------
        retriever_id : str

        query : str
            The query to retrieve against.

        mode : typing.Optional[CompositeRetrievalMode]
            The mode of composite retrieval.

        rerank_top_n : typing.Optional[int]
            The number of nodes to retrieve after reranking over retrieved nodes from all retrieval tools.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        CompositeRetrievalResult
            Successful Response

        Examples
        --------
        import asyncio

        from llama_index import AsyncLlamaCloud

        client = AsyncLlamaCloud(
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.retrievers.retrieve(
                retriever_id="retriever_id",
                query="query",
            )


        asyncio.run(main())
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"api/v1/retrievers/{jsonable_encoder(retriever_id)}/retrieve",
            method="POST",
            json={
                "mode": mode,
                "rerank_top_n": rerank_top_n,
                "query": query,
            },
            headers={
                "content-type": "application/json",
            },
            request_options=request_options,
            omit=OMIT,
        )
        try:
            if 200 <= _response.status_code < 300:
                return typing.cast(
                    CompositeRetrievalResult,
                    parse_obj_as(
                        type_=CompositeRetrievalResult,  # type: ignore
                        object_=_response.json(),
                    ),
                )
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    typing.cast(
                        HttpValidationError,
                        parse_obj_as(
                            type_=HttpValidationError,  # type: ignore
                            object_=_response.json(),
                        ),
                    )
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, body=_response.text)
        raise ApiError(status_code=_response.status_code, body=_response_json)
