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

import typing

from .. import core
from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.search_results import SearchResults
from .raw_client import AsyncRawSearchClient, RawSearchClient
from .types.search_create_request_group_by import SearchCreateRequestGroupBy
from .types.search_create_request_operator import SearchCreateRequestOperator
from .types.search_create_request_query_media_type import SearchCreateRequestQueryMediaType
from .types.search_create_request_search_options_item import SearchCreateRequestSearchOptionsItem
from .types.search_create_request_transcription_options_item import SearchCreateRequestTranscriptionOptionsItem
from .types.search_retrieve_response import SearchRetrieveResponse

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


class SearchClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawSearchClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        RawSearchClient
        """
        return self._raw_client

    def create(
        self,
        *,
        index_id: str,
        search_options: typing.List[SearchCreateRequestSearchOptionsItem],
        query_media_type: typing.Optional[SearchCreateRequestQueryMediaType] = OMIT,
        query_media_url: typing.Optional[str] = OMIT,
        query_media_file: typing.Optional[core.File] = OMIT,
        query_text: typing.Optional[str] = OMIT,
        transcription_options: typing.Optional[typing.List[SearchCreateRequestTranscriptionOptionsItem]] = OMIT,
        group_by: typing.Optional[SearchCreateRequestGroupBy] = OMIT,
        operator: typing.Optional[SearchCreateRequestOperator] = OMIT,
        page_limit: typing.Optional[int] = OMIT,
        filter: typing.Optional[str] = OMIT,
        include_user_metadata: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SearchResults:
        """
        Use this endpoint to search for relevant matches in an index using text, media, or a combination of both as your query.
        
        **Text queries**:
        - Use the `query_text` parameter to specify your query.
        
        **Media queries**:
        - Set the `query_media_type` parameter to the corresponding media type (example: `image`).
        - Provide up to 10 images by specifying the following parameters multiple times:
          - `query_media_url`: Publicly accessible URL of your media file.
          - `query_media_file`: Local media file.
        **Composed text and media queries**:
        - Use the `query_text` parameter for your text query.
        - Set `query_media_type` to `image`.
        - Provide up to 10 images by specifying the `query_media_url` and `query_media_file` parameters multiple times.
        
        **Entity search** (beta):
        - To find a specific person in your videos, enclose the unique identifier of the entity you want to find in the `query_text` parameter.
        
        <Note title="Notes">
        - When using images in your search queries (either as media queries or in composed searches), ensure your image files meet the [requirements](/v1.3/docs/concepts/models/marengo#image-file-requirements).
        - This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
        </Note>
        
        Parameters
        ----------
        index_id : str
            The unique identifier of the index to search.
        
        search_options : typing.List[SearchCreateRequestSearchOptionsItem]
            Specifies the modalities the video understanding model uses to find relevant information.
            
            Available options:
            - `visual`: Searches visual content.
            - `audio`: Searches non-speech audio.
            - `transcription`: Spoken words
            
            <Note title="Note">
            - You can specify multiple search options in conjunction with the [`operator`](/v1.3/api-reference/any-to-video-search/make-search-request#request.body.operator.operator) parameter described below to broaden or narrow your search. For example, to search using both visual and non-speech audio content, include this parameter two times in the request as shown below:
              ```JSON
              --form search_options=visual \
              --form search_options=audio \
              --form search_options=transcription \
              ```
            </Note>
            
            For guidance, see the [Search options](/v1.3/docs/concepts/modalities#search-options) section.
        
        query_media_type : typing.Optional[SearchCreateRequestQueryMediaType]
            The type of media you wish to use. This parameter is required for media queries. For example, to perform an image-based search, set this parameter to `image`. Use `query_text` together with this parameter when you want to perform a composed image+text search.
        
        query_media_url : typing.Optional[str]
            The publicly accessible URL of a media file to use as a query. This parameter is required for media queries if `query_media_file` is not provided.
            
            You can provide up to 10 images by specifying this parameter multiple times (Marengo 3.0 only):
            ```
            --form query_media_url=https://example.com/image1.jpg \
            --form query_media_url=https://example.com/image2.jpg
            ```
        
        query_media_file : typing.Optional[core.File]
            See core.File for more documentation
        
        query_text : typing.Optional[str]
            The text query to search for. This parameter is required for text queries. Note that the platform supports full natural language-based search. You can use this parameter together with `query_media_type` and `query_media_url` or `query_media_file` to perform a composed image+text search.
            
            If you're using the Entity Search feature to search for specific persons in your video content, you must enclose the unique identifier of your entity between the `<@` and `>` markers. For example, to search for an entity with the ID `entity123`, use `<@entity123> is walking` as your query.
            
            
            Marengo supports up to 500 tokens per query.
        
        transcription_options : typing.Optional[typing.List[SearchCreateRequestTranscriptionOptionsItem]]
            Specifies how the platform matches your text query with the words spoken in the video. This parameter applies only when the `search_options` parameter contains the `transcription` value.
            
            Available options:
            - `lexical`: Exact word matching
            - `semantic`: Meaning-based matching
            
            For details on when to use each option, see the [Transcription options](/v1.3/docs/concepts/modalities#transcription-options) section.
            
            **Default**: `["lexical", "semantic"]`.
        
        group_by : typing.Optional[SearchCreateRequestGroupBy]
            Use this parameter to group or ungroup items in a response. It can take one of the following values:
            - `video`:  The platform will group the matching video clips in the response by video.
            - `clip`: The matching video clips in the response will not be grouped.
            
            **Default:** `clip`
        
        operator : typing.Optional[SearchCreateRequestOperator]
            Combines multiple search options using `or` or `and`. Use `and` to find segments matching all search options. Use `or` to find segments matching any search option. For detailed guidance on using this parameter, see the [Combine multiple modalities](/v1.3/docs/concepts/modalities#combine-multiple-modalities) section.
            
            **Default**: `or`.
        
        page_limit : typing.Optional[int]
            The number of items to return on each page. When grouping by video, this parameter represents the number of videos per page. Otherwise, it represents the maximum number of video clips per page.
            
            **Max**: `50`.
        
        filter : typing.Optional[str]
            Specifies a stringified JSON object to filter your search results. Supports both system-generated metadata (example: video ID, duration) and user-defined metadata.
            
            **Syntax for filtering**
            
            The following table describes the supported data types, operators, and filter syntax:
            
            | Data type | Operator | Description | Syntax |
            |:----------|:---------|:------------|:-------|
            | String | `=` | Matches results equal to the specified value. | `{"field": "value"}`
            | Array of strings | `=` | Matches results with any value in the specified array. Supported only for `id`. | `{"id": ["value1", "value2"]}` |
            | Numeric (integer, float) | `=`, `lte`, `gte` | Matches results equal to or within a range of the specified value. | `{"field": number}` or `{"field": { "gte": number, "lte": number }}` |
            | Boolean | `=` | Matches results equal to the specified boolean value. | `{"field": true}` or `{"field": false}`. |
            
            <br/>
            **System-generated metadata**
            
            The table below describes the system-generated metadata available for filtering your  search results:
            
            | Field name | Description | Type | Example |
            |:-----------|:------------|:-----|:--------|
            | `id` | Filters by specific video IDs. | Array of strings | `{"id": ["67cec9caf45d9b64a58340fc", "67cec9baf45d9b64a58340fa"]}`. |
            | `duration` | Filters based on the duration of the video containing the segment that matches your query. | Number or object with `gte` and `lte` | `{"duration": 600}` or `{"duration": { "gte": 600, "lte": 800 }}` |
            | `width` | Filters by video width (in pixels). | Number or object with `gte` and `lte` | `{"width": 1920}` or `{"width": { "gte": 1280, "lte": 1920}}` |
            | `height` | Filters by video height (in pixels). | Number or object with `gte` and `lte`. | `{"height": 1080}` or `{"height": { "gte": 720, "lte": 1080 }}`. |
            | `size` | Filters by video size (in bytes) | Number or object with `gte` and `lte`. | `{"size": 1048576}` or `{"size": { "gte": 1048576, "lte": 5242880}}` |
            | `filename` | Filters by the exact file name. | String | `{"filename": "Animal Encounters part 1"}` |
            
            <br/>
            **User-defined metadata**
            
            To filter by user-defined metadata:
            1. Add metadata to your video by calling the [`PUT`](/v1.3/api-reference/videos/update) method of the `/indexes/:index-id/videos/:video-id` endpoint
            2. Reference the custom field in your filter object. For example, to filter videos where a custom field named `needsReview` of type boolean is `true`, use `{"needs_review": true}`.
            
            For more details and examples, see the [Filter search results](/v1.3/docs/guides/search/filtering) page.
        
        include_user_metadata : typing.Optional[bool]
            Specifies whether to include user-defined metadata in the search results.
        
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.
        
        Returns
        -------
        SearchResults
            Successfully performed a search request.
        
        Examples
        --------
        from twelvelabs import TwelveLabs
        
        client = TwelveLabs(
            api_key="YOUR_API_KEY",
        )
        client.search.create(
            index_id="index_id",
            search_options=["visual"],
        )
        """
        _response = self._raw_client.create(
            index_id=index_id,
            search_options=search_options,
            query_media_type=query_media_type,
            query_media_url=query_media_url,
            query_media_file=query_media_file,
            query_text=query_text,
            transcription_options=transcription_options,
            group_by=group_by,
            operator=operator,
            page_limit=page_limit,
            filter=filter,
            include_user_metadata=include_user_metadata,
            request_options=request_options,
        )
        return _response.data

    def retrieve(
        self,
        page_token: str,
        *,
        include_user_metadata: typing.Optional[bool] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SearchRetrieveResponse:
        """
        Use this endpoint to retrieve a specific page of search results.

        <Note title="Note">
        When you use pagination, you will not be charged for retrieving subsequent pages of results.
        </Note>

        Parameters
        ----------
        page_token : str
            A token that identifies the page to retrieve.

        include_user_metadata : typing.Optional[bool]
            Specifies whether to include user-defined metadata in the search results.

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

        Returns
        -------
        SearchRetrieveResponse
            Successfully retrieved the specified page of search results.

        Examples
        --------
        from twelvelabs import TwelveLabs

        client = TwelveLabs(
            api_key="YOUR_API_KEY",
        )
        client.search.retrieve(
            page_token="1234567890",
            include_user_metadata=True,
        )
        """
        _response = self._raw_client.retrieve(
            page_token, include_user_metadata=include_user_metadata, request_options=request_options
        )
        return _response.data


class AsyncSearchClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawSearchClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        AsyncRawSearchClient
        """
        return self._raw_client

    async def create(
        self,
        *,
        index_id: str,
        search_options: typing.List[SearchCreateRequestSearchOptionsItem],
        query_media_type: typing.Optional[SearchCreateRequestQueryMediaType] = OMIT,
        query_media_url: typing.Optional[str] = OMIT,
        query_media_file: typing.Optional[core.File] = OMIT,
        query_text: typing.Optional[str] = OMIT,
        transcription_options: typing.Optional[typing.List[SearchCreateRequestTranscriptionOptionsItem]] = OMIT,
        group_by: typing.Optional[SearchCreateRequestGroupBy] = OMIT,
        operator: typing.Optional[SearchCreateRequestOperator] = OMIT,
        page_limit: typing.Optional[int] = OMIT,
        filter: typing.Optional[str] = OMIT,
        include_user_metadata: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SearchResults:
        """
        Use this endpoint to search for relevant matches in an index using text, media, or a combination of both as your query.
        
        **Text queries**:
        - Use the `query_text` parameter to specify your query.
        
        **Media queries**:
        - Set the `query_media_type` parameter to the corresponding media type (example: `image`).
        - Provide up to 10 images by specifying the following parameters multiple times:
          - `query_media_url`: Publicly accessible URL of your media file.
          - `query_media_file`: Local media file.
        **Composed text and media queries**:
        - Use the `query_text` parameter for your text query.
        - Set `query_media_type` to `image`.
        - Provide up to 10 images by specifying the `query_media_url` and `query_media_file` parameters multiple times.
        
        **Entity search** (beta):
        - To find a specific person in your videos, enclose the unique identifier of the entity you want to find in the `query_text` parameter.
        
        <Note title="Notes">
        - When using images in your search queries (either as media queries or in composed searches), ensure your image files meet the [requirements](/v1.3/docs/concepts/models/marengo#image-file-requirements).
        - This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
        </Note>
        
        Parameters
        ----------
        index_id : str
            The unique identifier of the index to search.
        
        search_options : typing.List[SearchCreateRequestSearchOptionsItem]
            Specifies the modalities the video understanding model uses to find relevant information.
            
            Available options:
            - `visual`: Searches visual content.
            - `audio`: Searches non-speech audio.
            - `transcription`: Spoken words
            
            <Note title="Note">
            - You can specify multiple search options in conjunction with the [`operator`](/v1.3/api-reference/any-to-video-search/make-search-request#request.body.operator.operator) parameter described below to broaden or narrow your search. For example, to search using both visual and non-speech audio content, include this parameter two times in the request as shown below:
              ```JSON
              --form search_options=visual \
              --form search_options=audio \
              --form search_options=transcription \
              ```
            </Note>
            
            For guidance, see the [Search options](/v1.3/docs/concepts/modalities#search-options) section.
        
        query_media_type : typing.Optional[SearchCreateRequestQueryMediaType]
            The type of media you wish to use. This parameter is required for media queries. For example, to perform an image-based search, set this parameter to `image`. Use `query_text` together with this parameter when you want to perform a composed image+text search.
        
        query_media_url : typing.Optional[str]
            The publicly accessible URL of a media file to use as a query. This parameter is required for media queries if `query_media_file` is not provided.
            
            You can provide up to 10 images by specifying this parameter multiple times (Marengo 3.0 only):
            ```
            --form query_media_url=https://example.com/image1.jpg \
            --form query_media_url=https://example.com/image2.jpg
            ```
        
        query_media_file : typing.Optional[core.File]
            See core.File for more documentation
        
        query_text : typing.Optional[str]
            The text query to search for. This parameter is required for text queries. Note that the platform supports full natural language-based search. You can use this parameter together with `query_media_type` and `query_media_url` or `query_media_file` to perform a composed image+text search.
            
            If you're using the Entity Search feature to search for specific persons in your video content, you must enclose the unique identifier of your entity between the `<@` and `>` markers. For example, to search for an entity with the ID `entity123`, use `<@entity123> is walking` as your query.
            
            
            Marengo supports up to 500 tokens per query.
        
        transcription_options : typing.Optional[typing.List[SearchCreateRequestTranscriptionOptionsItem]]
            Specifies how the platform matches your text query with the words spoken in the video. This parameter applies only when the `search_options` parameter contains the `transcription` value.
            
            Available options:
            - `lexical`: Exact word matching
            - `semantic`: Meaning-based matching
            
            For details on when to use each option, see the [Transcription options](/v1.3/docs/concepts/modalities#transcription-options) section.
            
            **Default**: `["lexical", "semantic"]`.
        
        group_by : typing.Optional[SearchCreateRequestGroupBy]
            Use this parameter to group or ungroup items in a response. It can take one of the following values:
            - `video`:  The platform will group the matching video clips in the response by video.
            - `clip`: The matching video clips in the response will not be grouped.
            
            **Default:** `clip`
        
        operator : typing.Optional[SearchCreateRequestOperator]
            Combines multiple search options using `or` or `and`. Use `and` to find segments matching all search options. Use `or` to find segments matching any search option. For detailed guidance on using this parameter, see the [Combine multiple modalities](/v1.3/docs/concepts/modalities#combine-multiple-modalities) section.
            
            **Default**: `or`.
        
        page_limit : typing.Optional[int]
            The number of items to return on each page. When grouping by video, this parameter represents the number of videos per page. Otherwise, it represents the maximum number of video clips per page.
            
            **Max**: `50`.
        
        filter : typing.Optional[str]
            Specifies a stringified JSON object to filter your search results. Supports both system-generated metadata (example: video ID, duration) and user-defined metadata.
            
            **Syntax for filtering**
            
            The following table describes the supported data types, operators, and filter syntax:
            
            | Data type | Operator | Description | Syntax |
            |:----------|:---------|:------------|:-------|
            | String | `=` | Matches results equal to the specified value. | `{"field": "value"}`
            | Array of strings | `=` | Matches results with any value in the specified array. Supported only for `id`. | `{"id": ["value1", "value2"]}` |
            | Numeric (integer, float) | `=`, `lte`, `gte` | Matches results equal to or within a range of the specified value. | `{"field": number}` or `{"field": { "gte": number, "lte": number }}` |
            | Boolean | `=` | Matches results equal to the specified boolean value. | `{"field": true}` or `{"field": false}`. |
            
            <br/>
            **System-generated metadata**
            
            The table below describes the system-generated metadata available for filtering your  search results:
            
            | Field name | Description | Type | Example |
            |:-----------|:------------|:-----|:--------|
            | `id` | Filters by specific video IDs. | Array of strings | `{"id": ["67cec9caf45d9b64a58340fc", "67cec9baf45d9b64a58340fa"]}`. |
            | `duration` | Filters based on the duration of the video containing the segment that matches your query. | Number or object with `gte` and `lte` | `{"duration": 600}` or `{"duration": { "gte": 600, "lte": 800 }}` |
            | `width` | Filters by video width (in pixels). | Number or object with `gte` and `lte` | `{"width": 1920}` or `{"width": { "gte": 1280, "lte": 1920}}` |
            | `height` | Filters by video height (in pixels). | Number or object with `gte` and `lte`. | `{"height": 1080}` or `{"height": { "gte": 720, "lte": 1080 }}`. |
            | `size` | Filters by video size (in bytes) | Number or object with `gte` and `lte`. | `{"size": 1048576}` or `{"size": { "gte": 1048576, "lte": 5242880}}` |
            | `filename` | Filters by the exact file name. | String | `{"filename": "Animal Encounters part 1"}` |
            
            <br/>
            **User-defined metadata**
            
            To filter by user-defined metadata:
            1. Add metadata to your video by calling the [`PUT`](/v1.3/api-reference/videos/update) method of the `/indexes/:index-id/videos/:video-id` endpoint
            2. Reference the custom field in your filter object. For example, to filter videos where a custom field named `needsReview` of type boolean is `true`, use `{"needs_review": true}`.
            
            For more details and examples, see the [Filter search results](/v1.3/docs/guides/search/filtering) page.
        
        include_user_metadata : typing.Optional[bool]
            Specifies whether to include user-defined metadata in the search results.
        
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.
        
        Returns
        -------
        SearchResults
            Successfully performed a search request.
        
        Examples
        --------
        import asyncio
        
        from twelvelabs import AsyncTwelveLabs
        
        client = AsyncTwelveLabs(
            api_key="YOUR_API_KEY",
        )
        
        
        async def main() -> None:
            await client.search.create(
                index_id="index_id",
                search_options=["visual"],
            )
        
        
        asyncio.run(main())
        """
        _response = await self._raw_client.create(
            index_id=index_id,
            search_options=search_options,
            query_media_type=query_media_type,
            query_media_url=query_media_url,
            query_media_file=query_media_file,
            query_text=query_text,
            transcription_options=transcription_options,
            group_by=group_by,
            operator=operator,
            page_limit=page_limit,
            filter=filter,
            include_user_metadata=include_user_metadata,
            request_options=request_options,
        )
        return _response.data

    async def retrieve(
        self,
        page_token: str,
        *,
        include_user_metadata: typing.Optional[bool] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SearchRetrieveResponse:
        """
        Use this endpoint to retrieve a specific page of search results.

        <Note title="Note">
        When you use pagination, you will not be charged for retrieving subsequent pages of results.
        </Note>

        Parameters
        ----------
        page_token : str
            A token that identifies the page to retrieve.

        include_user_metadata : typing.Optional[bool]
            Specifies whether to include user-defined metadata in the search results.

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

        Returns
        -------
        SearchRetrieveResponse
            Successfully retrieved the specified page of search results.

        Examples
        --------
        import asyncio

        from twelvelabs import AsyncTwelveLabs

        client = AsyncTwelveLabs(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.search.retrieve(
                page_token="1234567890",
                include_user_metadata=True,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.retrieve(
            page_token, include_user_metadata=include_user_metadata, request_options=request_options
        )
        return _response.data
