opik 1.9.26__py3-none-any.whl → 1.9.41__py3-none-any.whl

opik/rest_api/datasets/client.py

@@ -14,6 +14,9 @@ from ..types.dataset_item_write import DatasetItemWrite
 from ..types.dataset_item_write_source import DatasetItemWriteSource
 from ..types.dataset_page_public import DatasetPagePublic
 from ..types.dataset_public import DatasetPublic
+from ..types.dataset_version_diff import DatasetVersionDiff
+from ..types.dataset_version_page_public import DatasetVersionPagePublic
+from ..types.dataset_version_public import DatasetVersionPublic
 from ..types.json_node import JsonNode
 from ..types.page_columns import PageColumns
 from ..types.project_stats_public import ProjectStatsPublic
@@ -789,6 +792,7 @@ class DatasetsClient:
         *,
         page: typing.Optional[int] = None,
         size: typing.Optional[int] = None,
+        version: typing.Optional[str] = None,
         filters: typing.Optional[str] = None,
         truncate: typing.Optional[bool] = None,
         request_options: typing.Optional[RequestOptions] = None,
@@ -804,6 +808,8 @@ class DatasetsClient:
 
         size : typing.Optional[int]
 
+        version : typing.Optional[str]
+
         filters : typing.Optional[str]
 
         truncate : typing.Optional[bool]
@@ -823,7 +829,13 @@ class DatasetsClient:
         client.datasets.get_dataset_items(id='id', )
         """
         _response = self._raw_client.get_dataset_items(
-            id, page=page, size=size, filters=filters, truncate=truncate, request_options=request_options
+            id,
+            page=page,
+            size=size,
+            version=version,
+            filters=filters,
+            truncate=truncate,
+            request_options=request_options,
         )
         return _response.data
 
@@ -897,6 +909,251 @@ class DatasetsClient:
         ) as r:
             yield from r.data
 
+    def compare_dataset_versions(
+        self, id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DatasetVersionDiff:
+        """
+        Compare the latest committed dataset version with the current draft state. This endpoint provides insights into changes made since the last version was committed. The comparison calculates additions, modifications, deletions, and unchanged items between the latest version snapshot and current draft.
+
+        Parameters
+        ----------
+        id : str
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionDiff
+            Diff computed successfully
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.compare_dataset_versions(id='id', )
+        """
+        _response = self._raw_client.compare_dataset_versions(id, request_options=request_options)
+        return _response.data
+
+    def create_version_tag(
+        self, version_hash: str, id: str, *, tag: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> None:
+        """
+        Add a tag to a specific dataset version for easy reference (e.g., 'baseline', 'v1.0', 'production')
+
+        Parameters
+        ----------
+        version_hash : str
+
+        id : str
+
+        tag : str
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.create_version_tag(version_hash='versionHash', id='id', tag='tag', )
+        """
+        _response = self._raw_client.create_version_tag(version_hash, id, tag=tag, request_options=request_options)
+        return _response.data
+
+    def list_dataset_versions(
+        self,
+        id: str,
+        *,
+        page: typing.Optional[int] = None,
+        size: typing.Optional[int] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DatasetVersionPagePublic:
+        """
+        Get paginated list of versions for a dataset, ordered by creation time (newest first)
+
+        Parameters
+        ----------
+        id : str
+
+        page : typing.Optional[int]
+
+        size : typing.Optional[int]
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionPagePublic
+            Dataset versions
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.list_dataset_versions(id='id', )
+        """
+        _response = self._raw_client.list_dataset_versions(id, page=page, size=size, request_options=request_options)
+        return _response.data
+
+    def create_dataset_version(
+        self,
+        id: str,
+        *,
+        tags: typing.Optional[typing.Sequence[str]] = OMIT,
+        change_description: typing.Optional[str] = OMIT,
+        metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> None:
+        """
+        Create a new immutable version of the dataset by snapshotting the current state
+
+        Parameters
+        ----------
+        id : str
+
+        tags : typing.Optional[typing.Sequence[str]]
+            Optional list of tags for this version
+
+        change_description : typing.Optional[str]
+            Optional description of changes in this version
+
+        metadata : typing.Optional[typing.Dict[str, str]]
+            Optional user-defined metadata
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.create_dataset_version(id='id', )
+        """
+        _response = self._raw_client.create_dataset_version(
+            id, tags=tags, change_description=change_description, metadata=metadata, request_options=request_options
+        )
+        return _response.data
+
+    def delete_version_tag(
+        self, version_hash: str, tag: str, id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> None:
+        """
+        Remove a tag from a dataset version. The version itself is not deleted, only the tag reference.
+
+        Parameters
+        ----------
+        version_hash : str
+
+        tag : str
+
+        id : str
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.delete_version_tag(version_hash='versionHash', tag='tag', id='id', )
+        """
+        _response = self._raw_client.delete_version_tag(version_hash, tag, id, request_options=request_options)
+        return _response.data
+
+    def restore_dataset_version(
+        self, id: str, *, version_ref: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> DatasetVersionPublic:
+        """
+        Restores the dataset to a previous version state. All draft items are replaced with items from the specified version. If the version is not the latest, a new version snapshot is created. If the version is the latest, only draft items are replaced (revert functionality).
+
+        Parameters
+        ----------
+        id : str
+
+        version_ref : str
+            Version hash or tag to restore from
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionPublic
+            Version restored successfully
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.restore_dataset_version(id='id', version_ref='version_ref', )
+        """
+        _response = self._raw_client.restore_dataset_version(
+            id, version_ref=version_ref, request_options=request_options
+        )
+        return _response.data
+
+    def update_dataset_version(
+        self,
+        version_hash: str,
+        id: str,
+        *,
+        change_description: typing.Optional[str] = OMIT,
+        tags_to_add: typing.Optional[typing.Sequence[str]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DatasetVersionPublic:
+        """
+        Update a dataset version's change_description and/or add new tags
+
+        Parameters
+        ----------
+        version_hash : str
+
+        id : str
+
+        change_description : typing.Optional[str]
+            Optional description of changes in this version
+
+        tags_to_add : typing.Optional[typing.Sequence[str]]
+            Optional list of tags to add to this version
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionPublic
+            Version updated successfully
+
+        Examples
+        --------
+        from Opik import OpikApi
+        client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        client.datasets.update_dataset_version(version_hash='versionHash', id='id', )
+        """
+        _response = self._raw_client.update_dataset_version(
+            version_hash,
+            id,
+            change_description=change_description,
+            tags_to_add=tags_to_add,
+            request_options=request_options,
+        )
+        return _response.data
+
 
 class AsyncDatasetsClient:
     def __init__(self, *, client_wrapper: AsyncClientWrapper):
@@ -1721,6 +1978,7 @@ class AsyncDatasetsClient:
         *,
         page: typing.Optional[int] = None,
         size: typing.Optional[int] = None,
+        version: typing.Optional[str] = None,
         filters: typing.Optional[str] = None,
         truncate: typing.Optional[bool] = None,
         request_options: typing.Optional[RequestOptions] = None,
@@ -1736,6 +1994,8 @@ class AsyncDatasetsClient:
 
         size : typing.Optional[int]
 
+        version : typing.Optional[str]
+
         filters : typing.Optional[str]
 
         truncate : typing.Optional[bool]
@@ -1758,7 +2018,13 @@ class AsyncDatasetsClient:
         asyncio.run(main())
         """
         _response = await self._raw_client.get_dataset_items(
-            id, page=page, size=size, filters=filters, truncate=truncate, request_options=request_options
+            id,
+            page=page,
+            size=size,
+            version=version,
+            filters=filters,
+            truncate=truncate,
+            request_options=request_options,
         )
         return _response.data
 
@@ -1835,3 +2101,273 @@ class AsyncDatasetsClient:
         ) as r:
             async for data in r.data:
                 yield data
+
+    async def compare_dataset_versions(
+        self, id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DatasetVersionDiff:
+        """
+        Compare the latest committed dataset version with the current draft state. This endpoint provides insights into changes made since the last version was committed. The comparison calculates additions, modifications, deletions, and unchanged items between the latest version snapshot and current draft.
+
+        Parameters
+        ----------
+        id : str
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionDiff
+            Diff computed successfully
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.compare_dataset_versions(id='id', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.compare_dataset_versions(id, request_options=request_options)
+        return _response.data
+
+    async def create_version_tag(
+        self, version_hash: str, id: str, *, tag: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> None:
+        """
+        Add a tag to a specific dataset version for easy reference (e.g., 'baseline', 'v1.0', 'production')
+
+        Parameters
+        ----------
+        version_hash : str
+
+        id : str
+
+        tag : str
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.create_version_tag(version_hash='versionHash', id='id', tag='tag', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create_version_tag(
+            version_hash, id, tag=tag, request_options=request_options
+        )
+        return _response.data
+
+    async def list_dataset_versions(
+        self,
+        id: str,
+        *,
+        page: typing.Optional[int] = None,
+        size: typing.Optional[int] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DatasetVersionPagePublic:
+        """
+        Get paginated list of versions for a dataset, ordered by creation time (newest first)
+
+        Parameters
+        ----------
+        id : str
+
+        page : typing.Optional[int]
+
+        size : typing.Optional[int]
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionPagePublic
+            Dataset versions
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.list_dataset_versions(id='id', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.list_dataset_versions(
+            id, page=page, size=size, request_options=request_options
+        )
+        return _response.data
+
+    async def create_dataset_version(
+        self,
+        id: str,
+        *,
+        tags: typing.Optional[typing.Sequence[str]] = OMIT,
+        change_description: typing.Optional[str] = OMIT,
+        metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> None:
+        """
+        Create a new immutable version of the dataset by snapshotting the current state
+
+        Parameters
+        ----------
+        id : str
+
+        tags : typing.Optional[typing.Sequence[str]]
+            Optional list of tags for this version
+
+        change_description : typing.Optional[str]
+            Optional description of changes in this version
+
+        metadata : typing.Optional[typing.Dict[str, str]]
+            Optional user-defined metadata
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.create_dataset_version(id='id', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create_dataset_version(
+            id, tags=tags, change_description=change_description, metadata=metadata, request_options=request_options
+        )
+        return _response.data
+
+    async def delete_version_tag(
+        self, version_hash: str, tag: str, id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> None:
+        """
+        Remove a tag from a dataset version. The version itself is not deleted, only the tag reference.
+
+        Parameters
+        ----------
+        version_hash : str
+
+        tag : str
+
+        id : str
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.delete_version_tag(version_hash='versionHash', tag='tag', id='id', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.delete_version_tag(version_hash, tag, id, request_options=request_options)
+        return _response.data
+
+    async def restore_dataset_version(
+        self, id: str, *, version_ref: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> DatasetVersionPublic:
+        """
+        Restores the dataset to a previous version state. All draft items are replaced with items from the specified version. If the version is not the latest, a new version snapshot is created. If the version is the latest, only draft items are replaced (revert functionality).
+
+        Parameters
+        ----------
+        id : str
+
+        version_ref : str
+            Version hash or tag to restore from
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionPublic
+            Version restored successfully
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.restore_dataset_version(id='id', version_ref='version_ref', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.restore_dataset_version(
+            id, version_ref=version_ref, request_options=request_options
+        )
+        return _response.data
+
+    async def update_dataset_version(
+        self,
+        version_hash: str,
+        id: str,
+        *,
+        change_description: typing.Optional[str] = OMIT,
+        tags_to_add: typing.Optional[typing.Sequence[str]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DatasetVersionPublic:
+        """
+        Update a dataset version's change_description and/or add new tags
+
+        Parameters
+        ----------
+        version_hash : str
+
+        id : str
+
+        change_description : typing.Optional[str]
+            Optional description of changes in this version
+
+        tags_to_add : typing.Optional[typing.Sequence[str]]
+            Optional list of tags to add to this version
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DatasetVersionPublic
+            Version updated successfully
+
+        Examples
+        --------
+        from Opik import AsyncOpikApi
+        import asyncio
+        client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", )
+        async def main() -> None:
+            await client.datasets.update_dataset_version(version_hash='versionHash', id='id', )
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.update_dataset_version(
+            version_hash,
+            id,
+            change_description=change_description,
+            tags_to_add=tags_to_add,
+            request_options=request_options,
+        )
+        return _response.data