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

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.corpus_key import CorpusKey
from ..types.field_query import FieldQuery
from ..types.metadata_query_response import MetadataQueryResponse
from .raw_client import AsyncRawMetadataClient, RawMetadataClient
from .types.metadata_query_request_level import MetadataQueryRequestLevel

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


class MetadataClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawMetadataClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawMetadataClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawMetadataClient
        """
        return self._raw_client

    def query_metadata(
        self,
        corpus_key: CorpusKey,
        *,
        queries: typing.Sequence[FieldQuery],
        request_timeout: typing.Optional[int] = None,
        request_timeout_millis: typing.Optional[int] = None,
        level: typing.Optional[MetadataQueryRequestLevel] = OMIT,
        metadata_filter: typing.Optional[str] = OMIT,
        limit: typing.Optional[int] = OMIT,
        offset: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> MetadataQueryResponse:
        """
        Query for documents in a specific corpus using fuzzy matching across specified metadata fields. The search first applies any exact metadata filters to narrow the results, then performs fuzzy matching on the remaining documents using the specified field queries.

        Parameters
        ----------
        corpus_key : CorpusKey
            The unique key identifying the corpus to search for metadata.

        queries : typing.Sequence[FieldQuery]
            List of field-specific queries to apply fuzzy matching.

        request_timeout : typing.Optional[int]
            The API will make a best effort to complete the request in the specified seconds or time out.

        request_timeout_millis : typing.Optional[int]
            The API will make a best effort to complete the request in the specified milliseconds or time out.

        level : typing.Optional[MetadataQueryRequestLevel]
            Whether to search document-level or part-level metadata. Document-level returns unique documents, part-level can return multiple parts from the same document.

        metadata_filter : typing.Optional[str]
            Optional filter expression to narrow down results before fuzzy matching is applied.
            This uses the same expression format as document listing filters and applies exact matching.

        limit : typing.Optional[int]
            Sets the maximum number of documents to return.

        offset : typing.Optional[int]
            Starting position for pagination.

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

        Returns
        -------
        MetadataQueryResponse
            List of matching documents with relevance scores and field-level match details.

        Examples
        --------
        from vectara import FieldQuery, Vectara

        client = Vectara(
            api_key="YOUR_API_KEY",
            client_id="YOUR_CLIENT_ID",
            client_secret="YOUR_CLIENT_SECRET",
        )
        client.metadata.query_metadata(
            corpus_key="my-corpus",
            queries=[
                FieldQuery(
                    field="title",
                    query="lease agreement",
                    weight=2.0,
                ),
                FieldQuery(
                    field="category",
                    query="contract",
                    weight=1.0,
                ),
            ],
        )
        """
        _response = self._raw_client.query_metadata(
            corpus_key,
            queries=queries,
            request_timeout=request_timeout,
            request_timeout_millis=request_timeout_millis,
            level=level,
            metadata_filter=metadata_filter,
            limit=limit,
            offset=offset,
            request_options=request_options,
        )
        return _response.data


class AsyncMetadataClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawMetadataClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawMetadataClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawMetadataClient
        """
        return self._raw_client

    async def query_metadata(
        self,
        corpus_key: CorpusKey,
        *,
        queries: typing.Sequence[FieldQuery],
        request_timeout: typing.Optional[int] = None,
        request_timeout_millis: typing.Optional[int] = None,
        level: typing.Optional[MetadataQueryRequestLevel] = OMIT,
        metadata_filter: typing.Optional[str] = OMIT,
        limit: typing.Optional[int] = OMIT,
        offset: typing.Optional[int] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> MetadataQueryResponse:
        """
        Query for documents in a specific corpus using fuzzy matching across specified metadata fields. The search first applies any exact metadata filters to narrow the results, then performs fuzzy matching on the remaining documents using the specified field queries.

        Parameters
        ----------
        corpus_key : CorpusKey
            The unique key identifying the corpus to search for metadata.

        queries : typing.Sequence[FieldQuery]
            List of field-specific queries to apply fuzzy matching.

        request_timeout : typing.Optional[int]
            The API will make a best effort to complete the request in the specified seconds or time out.

        request_timeout_millis : typing.Optional[int]
            The API will make a best effort to complete the request in the specified milliseconds or time out.

        level : typing.Optional[MetadataQueryRequestLevel]
            Whether to search document-level or part-level metadata. Document-level returns unique documents, part-level can return multiple parts from the same document.

        metadata_filter : typing.Optional[str]
            Optional filter expression to narrow down results before fuzzy matching is applied.
            This uses the same expression format as document listing filters and applies exact matching.

        limit : typing.Optional[int]
            Sets the maximum number of documents to return.

        offset : typing.Optional[int]
            Starting position for pagination.

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

        Returns
        -------
        MetadataQueryResponse
            List of matching documents with relevance scores and field-level match details.

        Examples
        --------
        import asyncio

        from vectara import AsyncVectara, FieldQuery

        client = AsyncVectara(
            api_key="YOUR_API_KEY",
            client_id="YOUR_CLIENT_ID",
            client_secret="YOUR_CLIENT_SECRET",
        )


        async def main() -> None:
            await client.metadata.query_metadata(
                corpus_key="my-corpus",
                queries=[
                    FieldQuery(
                        field="title",
                        query="lease agreement",
                        weight=2.0,
                    ),
                    FieldQuery(
                        field="category",
                        query="contract",
                        weight=1.0,
                    ),
                ],
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.query_metadata(
            corpus_key,
            queries=queries,
            request_timeout=request_timeout,
            request_timeout_millis=request_timeout_millis,
            level=level,
            metadata_filter=metadata_filter,
            limit=limit,
            offset=offset,
            request_options=request_options,
        )
        return _response.data
