# 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.pagination import AsyncPager, SyncPager
from ...core.request_options import RequestOptions
from ...types.media_embedding_task import MediaEmbeddingTask
from .raw_client import AsyncRawTasksClient, RawTasksClient
from .types.tasks_create_request_video_embedding_scope_item import TasksCreateRequestVideoEmbeddingScopeItem
from .types.tasks_create_response import TasksCreateResponse
from .types.tasks_retrieve_request_embedding_option_item import TasksRetrieveRequestEmbeddingOptionItem
from .types.tasks_retrieve_response import TasksRetrieveResponse
from .types.tasks_status_response import TasksStatusResponse

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


class TasksClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawTasksClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        RawTasksClient
        """
        return self._raw_client

    def list(
        self,
        *,
        started_at: typing.Optional[str] = None,
        ended_at: typing.Optional[str] = None,
        status: typing.Optional[str] = None,
        page: typing.Optional[int] = None,
        page_limit: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SyncPager[MediaEmbeddingTask]:
        """
        <Note title="Note">
          This method will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.
        </Note>
        This method returns a list of the video embedding tasks in your account. The platform returns your video embedding tasks sorted by creation date, with the newest at the top of the list.

        <Note title="Notes">
        - Video embeddings are stored for seven days
        - When you invoke this method without specifying the `started_at` and `ended_at` parameters, the platform returns all the video embedding tasks created within the last seven days.
        </Note>

        Parameters
        ----------
        started_at : typing.Optional[str]
            Retrieve the embedding tasks that were created after the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").

        ended_at : typing.Optional[str]
            Retrieve the embedding tasks that were created before the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").

        status : typing.Optional[str]
            Filter the embedding tasks by their current status.

            **Values**: `processing`, `ready`, or `failed`.

        page : typing.Optional[int]
            A number that identifies the page to retrieve.

            **Default**: `1`.

        page_limit : typing.Optional[int]
            The number of items to return on each page.

            **Default**: `10`.
            **Max**: `50`.

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

        Returns
        -------
        SyncPager[MediaEmbeddingTask]
            A list of async embedding tasks has successfully been retrieved.

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

        client = TwelveLabs(
            api_key="YOUR_API_KEY",
        )
        response = client.embed.tasks.list(
            started_at="2024-03-01T00:00:00Z",
            ended_at="2024-03-01T00:00:00Z",
            status="processing",
            page=1,
            page_limit=10,
        )
        for item in response:
            yield item
        # alternatively, you can paginate page-by-page
        for page in response.iter_pages():
            yield page
        """
        return self._raw_client.list(
            started_at=started_at,
            ended_at=ended_at,
            status=status,
            page=page,
            page_limit=page_limit,
            request_options=request_options,
        )

    def create(
        self,
        *,
        model_name: str,
        video_file: typing.Optional[core.File] = OMIT,
        video_url: typing.Optional[str] = OMIT,
        video_start_offset_sec: typing.Optional[float] = OMIT,
        video_end_offset_sec: typing.Optional[float] = OMIT,
        video_clip_length: typing.Optional[float] = OMIT,
        video_embedding_scope: typing.Optional[typing.List[TasksCreateRequestVideoEmbeddingScopeItem]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> TasksCreateResponse:
        """
        
        <Note title="Note">
          This endpoint will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.
        </Note>
        
        This method creates a new video embedding task that uploads a video to the platform and creates one or multiple video embeddings.
        
        <Note title="Note">
        This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
        </Note>
        
        Upload options:
        - **Local file**: Use the `video_file` parameter
        - **Publicly accessible URL**: Use the `video_url` parameter.
        
        Specify at least one option. If both are provided, `video_url` takes precedence.
        
        Your video files must meet the [requirements](/v1.3/docs/concepts/models/marengo#video-file-requirements).
        This endpoint allows you to upload files up to 2 GB in size.  To upload larger files, use the [Multipart Upload API](/v1.3/api-reference/upload-content/multipart-uploads)
        
        <Note title="Notes">
        - The Marengo video understanding model generates embeddings for all modalities in the same latent space. This shared space enables any-to-any searches across different types of content.
        - Video embeddings are stored for seven days.
        </Note>
        
        Parameters
        ----------
        model_name : str
            The name of the model you want to use. The following models are available:
              - `marengo3.0`: Enhanced model with sports intelligence and extended content support.
        
        video_file : typing.Optional[core.File]
            See core.File for more documentation
        
        video_url : typing.Optional[str]
            Specify this parameter to upload a video from a publicly accessible URL.
        
        video_start_offset_sec : typing.Optional[float]
            The start offset in seconds from the beginning of the video where processing should begin. Specifying 0 means starting from the beginning of the video.
            
            **Default**: 0
            **Min**: 0
            **Max**: Duration of the video minus video_clip_length
        
        video_end_offset_sec : typing.Optional[float]
            The end offset in seconds from the beginning of the video where processing should stop.
            
            Ensure the following when you specify this parameter:
            - The end offset does not exceed the total duration of the video file.
            - The end offset is greater than the start offset.
            - You must set both the start and end offsets. Setting only one of these offsets is not permitted, resulting in an error.
            
            **Min**: video_start_offset + video_clip_length
            **Max**: Duration of the video file
        
        video_clip_length : typing.Optional[float]
            The desired duration in seconds for each clip for which the platform generates an embedding. Ensure that the clip length does not exceed the interval between the start and end offsets.
            
            **Default**: 6
            **Min**: 2
            **Max**: 10
        
        video_embedding_scope : typing.Optional[typing.List[TasksCreateRequestVideoEmbeddingScopeItem]]
            Defines the scope of video embedding generation. Valid values are the following:
            - `clip`: Creates embeddings for each video segment of `video_clip_length` seconds, from `video_start_offset_sec` to `video_end_offset_sec`.
            - `clip` and `video`: Creates embeddings for video segments and the entire video. Use the `video` scope for videos up to 10-30 seconds to maintain optimal performance.
            
            To create embeddings for segments and the entire video in the same request, include this parameter twice as shown below:
            
            ```json
            --form video_embedding_scope=clip \
            --form video_embedding_scope=video
            ```
            
            **Default**: `clip`
        
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.
        
        Returns
        -------
        TasksCreateResponse
            A video embedding task has successfully been created.
        
        Examples
        --------
        from twelvelabs import TwelveLabs
        
        client = TwelveLabs(
            api_key="YOUR_API_KEY",
        )
        client.embed.tasks.create(
            model_name="model_name",
        )
        """
        _response = self._raw_client.create(
            model_name=model_name,
            video_file=video_file,
            video_url=video_url,
            video_start_offset_sec=video_start_offset_sec,
            video_end_offset_sec=video_end_offset_sec,
            video_clip_length=video_clip_length,
            video_embedding_scope=video_embedding_scope,
            request_options=request_options,
        )
        return _response.data

    def status(self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> TasksStatusResponse:
        """
        <Note title="Note">
          This endpoint will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.
        </Note>
        This method retrieves the status of a video embedding task. Check the task status of a video embedding task to determine when you can retrieve the embedding.

        A task can have one of the following statuses:
        - `processing`: The platform is creating the embeddings.
        - `ready`:  Processing is complete. Retrieve the embeddings by invoking the [`GET`](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embeddings) method of the `/embed/tasks/{task_id} endpoint`.
        - `failed`: The task could not be completed, and the embeddings haven't been created.

        Parameters
        ----------
        task_id : str
            The unique identifier of your video embedding task.

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

        Returns
        -------
        TasksStatusResponse
            The status of your video embedding task has been retrieved.

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

        client = TwelveLabs(
            api_key="YOUR_API_KEY",
        )
        client.embed.tasks.status(
            task_id="663da73b31cdd0c1f638a8e6",
        )
        """
        _response = self._raw_client.status(task_id, request_options=request_options)
        return _response.data

    def retrieve(
        self,
        task_id: str,
        *,
        embedding_option: typing.Optional[
            typing.Union[
                TasksRetrieveRequestEmbeddingOptionItem, typing.Sequence[TasksRetrieveRequestEmbeddingOptionItem]
            ]
        ] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> TasksRetrieveResponse:
        """
        This method retrieves embeddings for a specific video embedding task. Ensure the task status is `ready` before invoking this method. Refer to the [Retrieve the status of a video embedding tasks](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embedding-task-status) page for instructions on checking the task status.

        Parameters
        ----------
        task_id : str
            The unique identifier of your video embedding task.

        embedding_option : typing.Optional[typing.Union[TasksRetrieveRequestEmbeddingOptionItem, typing.Sequence[TasksRetrieveRequestEmbeddingOptionItem]]]
            Specifies which types of embeddings to retrieve. Values: `visual`, `audio`, `transcription`. For details, see the [Embedding options](/v1.3/docs/concepts/modalities#embedding-options) section.

            <Note title="Note">
            The platform returns all available embeddings when you omit this parameter.
            </Note>

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

        Returns
        -------
        TasksRetrieveResponse
            Video embeddings have successfully been retrieved.

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

        client = TwelveLabs(
            api_key="YOUR_API_KEY",
        )
        client.embed.tasks.retrieve(
            task_id="663da73b31cdd0c1f638a8e6",
        )
        """
        _response = self._raw_client.retrieve(
            task_id, embedding_option=embedding_option, request_options=request_options
        )
        return _response.data


class AsyncTasksClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawTasksClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        AsyncRawTasksClient
        """
        return self._raw_client

    async def list(
        self,
        *,
        started_at: typing.Optional[str] = None,
        ended_at: typing.Optional[str] = None,
        status: typing.Optional[str] = None,
        page: typing.Optional[int] = None,
        page_limit: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncPager[MediaEmbeddingTask]:
        """
        <Note title="Note">
          This method will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.
        </Note>
        This method returns a list of the video embedding tasks in your account. The platform returns your video embedding tasks sorted by creation date, with the newest at the top of the list.

        <Note title="Notes">
        - Video embeddings are stored for seven days
        - When you invoke this method without specifying the `started_at` and `ended_at` parameters, the platform returns all the video embedding tasks created within the last seven days.
        </Note>

        Parameters
        ----------
        started_at : typing.Optional[str]
            Retrieve the embedding tasks that were created after the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").

        ended_at : typing.Optional[str]
            Retrieve the embedding tasks that were created before the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").

        status : typing.Optional[str]
            Filter the embedding tasks by their current status.

            **Values**: `processing`, `ready`, or `failed`.

        page : typing.Optional[int]
            A number that identifies the page to retrieve.

            **Default**: `1`.

        page_limit : typing.Optional[int]
            The number of items to return on each page.

            **Default**: `10`.
            **Max**: `50`.

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

        Returns
        -------
        AsyncPager[MediaEmbeddingTask]
            A list of async embedding tasks has successfully been retrieved.

        Examples
        --------
        import asyncio

        from twelvelabs import AsyncTwelveLabs

        client = AsyncTwelveLabs(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            response = await client.embed.tasks.list(
                started_at="2024-03-01T00:00:00Z",
                ended_at="2024-03-01T00:00:00Z",
                status="processing",
                page=1,
                page_limit=10,
            )
            async for item in response:
                yield item

            # alternatively, you can paginate page-by-page
            async for page in response.iter_pages():
                yield page


        asyncio.run(main())
        """
        return await self._raw_client.list(
            started_at=started_at,
            ended_at=ended_at,
            status=status,
            page=page,
            page_limit=page_limit,
            request_options=request_options,
        )

    async def create(
        self,
        *,
        model_name: str,
        video_file: typing.Optional[core.File] = OMIT,
        video_url: typing.Optional[str] = OMIT,
        video_start_offset_sec: typing.Optional[float] = OMIT,
        video_end_offset_sec: typing.Optional[float] = OMIT,
        video_clip_length: typing.Optional[float] = OMIT,
        video_embedding_scope: typing.Optional[typing.List[TasksCreateRequestVideoEmbeddingScopeItem]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> TasksCreateResponse:
        """
        
        <Note title="Note">
          This endpoint will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.
        </Note>
        
        This method creates a new video embedding task that uploads a video to the platform and creates one or multiple video embeddings.
        
        <Note title="Note">
        This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
        </Note>
        
        Upload options:
        - **Local file**: Use the `video_file` parameter
        - **Publicly accessible URL**: Use the `video_url` parameter.
        
        Specify at least one option. If both are provided, `video_url` takes precedence.
        
        Your video files must meet the [requirements](/v1.3/docs/concepts/models/marengo#video-file-requirements).
        This endpoint allows you to upload files up to 2 GB in size.  To upload larger files, use the [Multipart Upload API](/v1.3/api-reference/upload-content/multipart-uploads)
        
        <Note title="Notes">
        - The Marengo video understanding model generates embeddings for all modalities in the same latent space. This shared space enables any-to-any searches across different types of content.
        - Video embeddings are stored for seven days.
        </Note>
        
        Parameters
        ----------
        model_name : str
            The name of the model you want to use. The following models are available:
              - `marengo3.0`: Enhanced model with sports intelligence and extended content support.
        
        video_file : typing.Optional[core.File]
            See core.File for more documentation
        
        video_url : typing.Optional[str]
            Specify this parameter to upload a video from a publicly accessible URL.
        
        video_start_offset_sec : typing.Optional[float]
            The start offset in seconds from the beginning of the video where processing should begin. Specifying 0 means starting from the beginning of the video.
            
            **Default**: 0
            **Min**: 0
            **Max**: Duration of the video minus video_clip_length
        
        video_end_offset_sec : typing.Optional[float]
            The end offset in seconds from the beginning of the video where processing should stop.
            
            Ensure the following when you specify this parameter:
            - The end offset does not exceed the total duration of the video file.
            - The end offset is greater than the start offset.
            - You must set both the start and end offsets. Setting only one of these offsets is not permitted, resulting in an error.
            
            **Min**: video_start_offset + video_clip_length
            **Max**: Duration of the video file
        
        video_clip_length : typing.Optional[float]
            The desired duration in seconds for each clip for which the platform generates an embedding. Ensure that the clip length does not exceed the interval between the start and end offsets.
            
            **Default**: 6
            **Min**: 2
            **Max**: 10
        
        video_embedding_scope : typing.Optional[typing.List[TasksCreateRequestVideoEmbeddingScopeItem]]
            Defines the scope of video embedding generation. Valid values are the following:
            - `clip`: Creates embeddings for each video segment of `video_clip_length` seconds, from `video_start_offset_sec` to `video_end_offset_sec`.
            - `clip` and `video`: Creates embeddings for video segments and the entire video. Use the `video` scope for videos up to 10-30 seconds to maintain optimal performance.
            
            To create embeddings for segments and the entire video in the same request, include this parameter twice as shown below:
            
            ```json
            --form video_embedding_scope=clip \
            --form video_embedding_scope=video
            ```
            
            **Default**: `clip`
        
        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.
        
        Returns
        -------
        TasksCreateResponse
            A video embedding task has successfully been created.
        
        Examples
        --------
        import asyncio
        
        from twelvelabs import AsyncTwelveLabs
        
        client = AsyncTwelveLabs(
            api_key="YOUR_API_KEY",
        )
        
        
        async def main() -> None:
            await client.embed.tasks.create(
                model_name="model_name",
            )
        
        
        asyncio.run(main())
        """
        _response = await self._raw_client.create(
            model_name=model_name,
            video_file=video_file,
            video_url=video_url,
            video_start_offset_sec=video_start_offset_sec,
            video_end_offset_sec=video_end_offset_sec,
            video_clip_length=video_clip_length,
            video_embedding_scope=video_embedding_scope,
            request_options=request_options,
        )
        return _response.data

    async def status(
        self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> TasksStatusResponse:
        """
        <Note title="Note">
          This endpoint will be deprecated in a future version. Migrate to the [Embed API v2](/v1.3/api-reference/create-embeddings-v2) for continued support and access to new features.
        </Note>
        This method retrieves the status of a video embedding task. Check the task status of a video embedding task to determine when you can retrieve the embedding.

        A task can have one of the following statuses:
        - `processing`: The platform is creating the embeddings.
        - `ready`:  Processing is complete. Retrieve the embeddings by invoking the [`GET`](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embeddings) method of the `/embed/tasks/{task_id} endpoint`.
        - `failed`: The task could not be completed, and the embeddings haven't been created.

        Parameters
        ----------
        task_id : str
            The unique identifier of your video embedding task.

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

        Returns
        -------
        TasksStatusResponse
            The status of your video embedding task has been retrieved.

        Examples
        --------
        import asyncio

        from twelvelabs import AsyncTwelveLabs

        client = AsyncTwelveLabs(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.embed.tasks.status(
                task_id="663da73b31cdd0c1f638a8e6",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.status(task_id, request_options=request_options)
        return _response.data

    async def retrieve(
        self,
        task_id: str,
        *,
        embedding_option: typing.Optional[
            typing.Union[
                TasksRetrieveRequestEmbeddingOptionItem, typing.Sequence[TasksRetrieveRequestEmbeddingOptionItem]
            ]
        ] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> TasksRetrieveResponse:
        """
        This method retrieves embeddings for a specific video embedding task. Ensure the task status is `ready` before invoking this method. Refer to the [Retrieve the status of a video embedding tasks](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embedding-task-status) page for instructions on checking the task status.

        Parameters
        ----------
        task_id : str
            The unique identifier of your video embedding task.

        embedding_option : typing.Optional[typing.Union[TasksRetrieveRequestEmbeddingOptionItem, typing.Sequence[TasksRetrieveRequestEmbeddingOptionItem]]]
            Specifies which types of embeddings to retrieve. Values: `visual`, `audio`, `transcription`. For details, see the [Embedding options](/v1.3/docs/concepts/modalities#embedding-options) section.

            <Note title="Note">
            The platform returns all available embeddings when you omit this parameter.
            </Note>

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

        Returns
        -------
        TasksRetrieveResponse
            Video embeddings have successfully been retrieved.

        Examples
        --------
        import asyncio

        from twelvelabs import AsyncTwelveLabs

        client = AsyncTwelveLabs(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.embed.tasks.retrieve(
                task_id="663da73b31cdd0c1f638a8e6",
            )


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