modelstudio-sdk 0.0.0.dev0__py3-none-any.whl

modelstudio/resources/dataset.py

@@ -0,0 +1,732 @@
+"""Dataset resource — top-level collection and per-dataset operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from modelstudio._polling import OperationPoller
+from modelstudio.models.annotations import (
+    AnnotationModel,
+    CreateAnnotationRequest,
+    DeleteAnnotationsResponse,
+    UpdateAnnotationRequest,
+)
+from modelstudio.models.categories import (
+    CancelSplitCategoryResponse,
+    CategoryListModel,
+    ConsolidateLabelsResponse,
+    MergeBySupercategoryResponse,
+    MergeCategoriesResponse,
+    MergeSourcesResponse,
+    RemoveCategoryResponse,
+    RenameCategoryResponse,
+    SplitCategoryResponse,
+)
+from modelstudio.models.common import PagedResponse
+from modelstudio.models.datasets import DatasetModel
+from modelstudio.models.deletion import DeletionCheckModel
+from modelstudio.models.exports import ExportCocoModel
+from modelstudio.models.few_shot import FewShotPreviewModel, FewShotRequest, FewShotResponseModel
+from modelstudio.models.filters import DatasetFilterRequest, DatasetFilterResponse
+from modelstudio.models.history import (
+    HistoryModel,
+    PreviewModel,
+    RewindResponse,
+    UndoRedoResponse,
+)
+from modelstudio.models.images import (
+    MarkSyntheticResponse,
+    RemoveEmptyImagesResponse,
+    SyntheticStatsModel,
+)
+from modelstudio.models.imports import (
+    ImportJobListModel,
+    ImportJobModel,
+    ImportJobQueuedModel,
+)
+from modelstudio.models.media import MediaJobActionModel, MediaJobStatusModel
+from modelstudio.models.merge import (
+    MergeAnalysisModel,
+    MergeDatasetRequest,
+    MergePreviewModel,
+    MergeResponseModel,
+)
+from modelstudio.models.metrics import BinnedModel, ClassDistributionModel, OverviewModel
+from modelstudio.models.oversample import (
+    OversampleAnalysisModel,
+    OversampleRequest,
+    OversampleResponseModel,
+)
+from modelstudio.models.splits import (
+    ClassAwareRedistributeResponse,
+    LeakageResponse,
+    RedistributeResponse,
+    SplitModel,
+)
+from modelstudio.models.validation import (
+    DuplicateCheckModel,
+    ResolveTemporalConflictResponse,
+    TemporalConflictModel,
+    ValidationResultsModel,
+)
+from modelstudio.resources.split import Split
+
+if TYPE_CHECKING:
+    from modelstudio._http import HttpTransport
+
+List = list  # alias to avoid shadowing by DatasetsCollection.list method
+
+
+class DatasetsCollection:
+    """Top-level dataset operations (list, create, merge).
+
+    Access via ``client.datasets``.
+    """
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._t = transport
+
+    def list(self) -> List[DatasetModel]:
+        """List all datasets."""
+        data = self._t.get("/api/v1/datasets")
+        return [DatasetModel.model_validate(item) for item in data]
+
+    def create(
+        self,
+        name: str,
+        dataset_type: str = "object_detection",
+        format: str = "coco",
+        description: str | None = None,
+    ) -> DatasetModel:
+        """Create a new dataset."""
+        body: dict[str, Any] = {
+            "name": name,
+            "dataset_type": dataset_type,
+            "format": format,
+        }
+        if description is not None:
+            body["description"] = description
+        data = self._t.post("/api/v1/datasets", json=body)
+        return DatasetModel.model_validate(data)
+
+    def merge_analyze(self, source_dataset_ids: List[str | UUID]) -> MergeAnalysisModel:
+        """Analyze category conflicts before merging datasets."""
+        data = self._t.post(
+            "/api/v1/datasets/merge/analyze",
+            json={"source_dataset_ids": [str(i) for i in source_dataset_ids]},
+        )
+        return MergeAnalysisModel.model_validate(data)
+
+    def merge_preview(self, request: MergeDatasetRequest) -> MergePreviewModel:
+        """Preview a dataset merge."""
+        data = self._t.post("/api/v1/datasets/merge/preview", json=request.model_dump())
+        return MergePreviewModel.model_validate(data)
+
+    def merge(self, request: MergeDatasetRequest) -> MergeResponseModel:
+        """Merge multiple datasets into a new one."""
+        data = self._t.post("/api/v1/datasets/merge", json=request.model_dump())
+        return MergeResponseModel.model_validate(data)
+
+
+class Dataset:
+    """Operations on a specific dataset.
+
+    Access via ``client.dataset("uuid")``.
+    """
+
+    def __init__(self, transport: HttpTransport, dataset_id: str) -> None:
+        self._t = transport
+        self._id = dataset_id
+        self._base = f"/api/v1/datasets/{dataset_id}"
+
+    def split(self, split_id: str | UUID) -> Split:
+        """Get a Split sub-resource for per-split operations."""
+        return Split(self._t, self._id, str(split_id))
+
+    # ── Lifecycle ─────────────────────────────────────────────────────
+
+    def can_delete(self) -> DeletionCheckModel:
+        """Check if this dataset can be safely deleted."""
+        data = self._t.get(f"{self._base}/can-delete")
+        return DeletionCheckModel.model_validate(data)
+
+    def delete(self) -> None:
+        """Delete this dataset."""
+        self._t.delete(self._base)
+
+    def clone(self, name: str, description: str | None = None) -> DatasetModel:
+        """Clone this dataset (async — returns immediately, poll clone_status)."""
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        data = self._t.post_accepted(f"{self._base}/clone", json=body)
+        return DatasetModel.model_validate(data)
+
+    def clone_status(self) -> dict[str, Any]:
+        """Get clone operation status."""
+        return self._t.get(f"{self._base}/clone/status")  # type: ignore[no-any-return]
+
+    def clone_poller(self, interval: float = 2.0, max_wait: float = 300.0) -> OperationPoller:
+        """Get a poller for the clone operation."""
+        return OperationPoller(
+            transport=self._t,
+            poll_url=f"{self._base}/clone/status",
+            terminal_statuses={"COMPLETED", "FAILED", "ERROR"},
+            interval=interval,
+            max_wait=max_wait,
+        )
+
+    def lock(self) -> None:
+        """Lock the dataset for finalization."""
+        self._t.post(f"{self._base}/finalize/lock")
+
+    def finalize(self) -> dict[str, Any]:
+        """Start finalization (async)."""
+        return self._t.post(f"{self._base}/finalize")  # type: ignore[no-any-return]
+
+    def finalize_status(self) -> dict[str, Any]:
+        """Get finalization status."""
+        return self._t.get(f"{self._base}/finalize/status")  # type: ignore[no-any-return]
+
+    def finalize_poller(
+        self, interval: float = 3.0, max_wait: float = 600.0
+    ) -> OperationPoller:
+        """Get a poller for the finalization operation."""
+        return OperationPoller(
+            transport=self._t,
+            poll_url=f"{self._base}/finalize/status",
+            terminal_statuses={"COMPLETED", "FAILED", "ERROR"},
+            interval=interval,
+            max_wait=max_wait,
+        )
+
+    # ── Splits ────────────────────────────────────────────────────────
+
+    def splits(self) -> list[SplitModel]:
+        """List all splits in this dataset."""
+        data = self._t.get(f"{self._base}/splits")
+        return [SplitModel.model_validate(item) for item in data]
+
+    def redistribute(
+        self, ratios: dict[str, float], seed: int | None = None
+    ) -> RedistributeResponse:
+        """Redistribute images across existing splits."""
+        body: dict[str, Any] = {"ratios": ratios}
+        if seed is not None:
+            body["seed"] = seed
+        data = self._t.post(f"{self._base}/splits/redistribute", json=body)
+        return RedistributeResponse.model_validate(data)
+
+    def class_aware_redistribute(
+        self,
+        ratios: dict[str, float],
+        seed: int | None = None,
+        mode: str | None = None,
+        prevent_tile_leakage: bool | None = None,
+        max_swap_iterations: int | None = None,
+        error_metric: str | None = None,
+    ) -> ClassAwareRedistributeResponse:
+        """Class-aware redistribution that balances class distributions across splits."""
+        body: dict[str, Any] = {"ratios": ratios}
+        if seed is not None:
+            body["seed"] = seed
+        if mode is not None:
+            body["mode"] = mode
+        if prevent_tile_leakage is not None:
+            body["prevent_tile_leakage"] = prevent_tile_leakage
+        if max_swap_iterations is not None:
+            body["max_swap_iterations"] = max_swap_iterations
+        if error_metric is not None:
+            body["error_metric"] = error_metric
+        data = self._t.post(f"{self._base}/splits/class-aware-redistribute", json=body)
+        return ClassAwareRedistributeResponse.model_validate(data)
+
+    def check_leakage(self, method: str = "image_hash") -> LeakageResponse:
+        """Check for data leakage between splits."""
+        data = self._t.post(f"{self._base}/splits/check-leakage", json={"method": method})
+        return LeakageResponse.model_validate(data)
+
+    # ── Import Jobs ───────────────────────────────────────────────────
+
+    def list_import_jobs(
+        self, status: str | None = None, include_log: bool = False
+    ) -> ImportJobListModel:
+        """List import jobs for this dataset."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if include_log:
+            params["includeLog"] = "true"
+        data = self._t.get(f"{self._base}/imports", params=params or None)
+        return ImportJobListModel.model_validate(data)
+
+    def get_import_job(self, job_id: str | UUID) -> ImportJobModel:
+        """Get details for a specific import job."""
+        data = self._t.get(f"{self._base}/imports/{job_id}")
+        return ImportJobModel.model_validate(data)
+
+    def cancel_import_job(self, job_id: str | UUID) -> ImportJobModel:
+        """Cancel a running import job."""
+        data = self._t.post(f"{self._base}/imports/{job_id}/cancel")
+        return ImportJobModel.model_validate(data)
+
+    def retry_import_job(self, job_id: str | UUID) -> ImportJobQueuedModel:
+        """Retry a failed import job."""
+        data = self._t.post_accepted(f"{self._base}/imports/{job_id}/retry")
+        return ImportJobQueuedModel.model_validate(data)
+
+    # ── Media Jobs ────────────────────────────────────────────────────
+
+    def media_status(self) -> MediaJobStatusModel:
+        """Get aggregate media processing status for this dataset."""
+        data = self._t.get(f"{self._base}/media/status")
+        return MediaJobStatusModel.model_validate(data)
+
+    def retry_media_job(self, job_id: str | UUID) -> MediaJobActionModel:
+        """Retry a single failed media job."""
+        data = self._t.post(f"{self._base}/media/jobs/{job_id}/retry")
+        return MediaJobActionModel.model_validate(data)
+
+    def cancel_media_job(self, job_id: str | UUID) -> MediaJobActionModel:
+        """Cancel a single media job."""
+        data = self._t.post(f"{self._base}/media/jobs/{job_id}/cancel")
+        return MediaJobActionModel.model_validate(data)
+
+    def retry_all_media_jobs(self) -> MediaJobActionModel:
+        """Retry all failed media jobs."""
+        data = self._t.post(f"{self._base}/media/jobs/retry-all")
+        return MediaJobActionModel.model_validate(data)
+
+    def cancel_queued_media_jobs(self) -> MediaJobActionModel:
+        """Cancel all queued media jobs."""
+        data = self._t.post(f"{self._base}/media/jobs/cancel-queued")
+        return MediaJobActionModel.model_validate(data)
+
+    # ── Categories ────────────────────────────────────────────────────
+
+    def categories(self, include_empty: bool = True) -> CategoryListModel:
+        """List all categories (dataset-wide)."""
+        params: dict[str, Any] | None = None
+        if not include_empty:
+            params = {"includeEmpty": "false"}
+        data = self._t.get(f"{self._base}/categories", params=params)
+        return CategoryListModel.model_validate(data)
+
+    def merge_categories(
+        self,
+        source_categories: list[int],
+        target_category: str,
+        target_supercategory: str | None = None,
+    ) -> MergeCategoriesResponse:
+        """Merge multiple categories into one."""
+        body: dict[str, Any] = {
+            "source_categories": source_categories,
+            "target_category": target_category,
+        }
+        if target_supercategory is not None:
+            body["target_supercategory"] = target_supercategory
+        data = self._t.post(f"{self._base}/categories/merge", json=body)
+        return MergeCategoriesResponse.model_validate(data)
+
+    def consolidate_labels(self, mapping: dict[str, str]) -> ConsolidateLabelsResponse:
+        """Apply a label consolidation mapping."""
+        data = self._t.post(f"{self._base}/categories/consolidate", json={"mapping": mapping})
+        return ConsolidateLabelsResponse.model_validate(data)
+
+    def rename_category(
+        self,
+        category_id: int,
+        new_name: str,
+        new_supercategory: str | None = None,
+    ) -> RenameCategoryResponse:
+        """Rename a category."""
+        body: dict[str, Any] = {"new_name": new_name}
+        if new_supercategory is not None:
+            body["new_supercategory"] = new_supercategory
+        data = self._t.put(f"{self._base}/categories/{category_id}/rename", json=body)
+        return RenameCategoryResponse.model_validate(data)
+
+    def remove_category(
+        self,
+        category_id: int,
+        action: str = "delete_annotations",
+        reassign_to: int | None = None,
+    ) -> RemoveCategoryResponse:
+        """Remove a category and its annotations.
+
+        Args:
+            category_id: The category to remove.
+            action: What to do with annotations — "delete_annotations" or "reassign".
+            reassign_to: Target category ID when action is "reassign".
+        """
+        params: dict[str, Any] = {"action": action}
+        if reassign_to is not None:
+            params["reassignTo"] = str(reassign_to)
+        data = self._t.delete(f"{self._base}/categories/{category_id}", params=params)
+        return RemoveCategoryResponse.model_validate(data)
+
+    def split_category(
+        self,
+        source_category_id: int,
+        target_categories: list[str],
+        supercategory: str | None = None,
+    ) -> SplitCategoryResponse:
+        """Split a category into multiple new categories."""
+        body: dict[str, Any] = {
+            "source_category_id": source_category_id,
+            "target_categories": target_categories,
+        }
+        if supercategory is not None:
+            body["supercategory"] = supercategory
+        data = self._t.post(f"{self._base}/categories/split", json=body)
+        return SplitCategoryResponse.model_validate(data)
+
+    def assign_split_category(
+        self, operation_id: str, assignments: dict[str, str]
+    ) -> Any:
+        """Assign annotations to new categories during a split operation."""
+        return self._t.post(
+            f"{self._base}/categories/split/assign",
+            json={"operation_id": operation_id, "assignments": assignments},
+        )
+
+    def cancel_split_category(self, operation_id: str) -> CancelSplitCategoryResponse:
+        """Cancel a category split operation."""
+        data = self._t.delete(f"{self._base}/categories/split/{operation_id}")
+        return CancelSplitCategoryResponse.model_validate(data)
+
+    def category_annotations(
+        self, category_id: int, limit: int = 100, offset: int = 0
+    ) -> list[dict[str, Any]]:
+        """Get annotations for a specific category."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        return self._t.get(  # type: ignore[no-any-return]
+            f"{self._base}/categories/{category_id}/annotations", params=params
+        )
+
+    def category_merge_sources(self, category_id: int) -> MergeSourcesResponse:
+        """Get merge history for a category."""
+        data = self._t.get(f"{self._base}/categories/{category_id}/merge-sources")
+        return MergeSourcesResponse.model_validate(data)
+
+    def merge_by_supercategory(
+        self, supercategory: str, target_category_name: str
+    ) -> MergeBySupercategoryResponse:
+        """Merge all categories with a given supercategory."""
+        data = self._t.post(
+            f"{self._base}/categories/merge-by-supercategory",
+            json={
+                "supercategory": supercategory,
+                "target_category_name": target_category_name,
+            },
+        )
+        return MergeBySupercategoryResponse.model_validate(data)
+
+    # ── Images ────────────────────────────────────────────────────────
+
+    def list_images(
+        self,
+        split_id: str | UUID | None = None,
+        page: int = 0,
+        size: int = 50,
+        sort_by: str | None = None,
+        sort_dir: str | None = None,
+        search: str | None = None,
+        include_facets: bool = False,
+        **filters: Any,
+    ) -> PagedResponse:
+        """List images in this dataset with pagination.
+
+        Returns a ``PagedResponse`` whose ``content`` contains image dicts.
+        Use ``images_df()`` for a DataFrame convenience wrapper.
+        """
+        params: dict[str, Any] = {"page": page, "size": size}
+        if split_id is not None:
+            params["splitId"] = str(split_id)
+        if sort_by is not None:
+            params["sortBy"] = sort_by
+        if sort_dir is not None:
+            params["sortDir"] = sort_dir
+        if search is not None:
+            params["search"] = search
+        if include_facets:
+            params["includeFacets"] = "true"
+        params.update(filters)
+        data = self._t.get(f"{self._base}/images", params=params)
+        return PagedResponse.model_validate(data)
+
+    def remove_empty_images(
+        self, split_id: str | UUID | None = None, dry_run: bool = False
+    ) -> RemoveEmptyImagesResponse:
+        """Remove images with no annotations."""
+        body: dict[str, Any] = {"dry_run": dry_run}
+        if split_id is not None:
+            body["split_id"] = str(split_id)
+        data = self._t.delete_with_body(f"{self._base}/images/empty", json=body)
+        return RemoveEmptyImagesResponse.model_validate(data)
+
+    def mark_synthetic(
+        self,
+        mode: str = "ALL",
+        mark_as_synthetic: bool = True,
+        image_ids: list[str | UUID] | None = None,
+        filename_pattern: str | None = None,
+    ) -> MarkSyntheticResponse:
+        """Mark images as synthetic or real."""
+        body: dict[str, Any] = {"mode": mode, "mark_as_synthetic": mark_as_synthetic}
+        if image_ids is not None:
+            body["image_ids"] = [str(i) for i in image_ids]
+        if filename_pattern is not None:
+            body["filename_pattern"] = filename_pattern
+        data = self._t.put(f"{self._base}/images/synthetic", json=body)
+        return MarkSyntheticResponse.model_validate(data)
+
+    def synthetic_stats(self) -> SyntheticStatsModel:
+        """Get synthetic vs real image statistics."""
+        data = self._t.get(f"{self._base}/images/synthetic/stats")
+        return SyntheticStatsModel.model_validate(data)
+
+    # ── Annotations ───────────────────────────────────────────────────
+
+    def list_annotations(
+        self,
+        split_id: str | UUID | None = None,
+        image_id: str | UUID | None = None,
+        page: int = 0,
+        size: int = 50,
+        sort_by: str | None = None,
+        sort_dir: str | None = None,
+        **filters: Any,
+    ) -> PagedResponse:
+        """List annotations in this dataset with pagination.
+
+        Returns a ``PagedResponse`` whose ``content`` contains annotation dicts.
+        Use ``annotations_df()`` for a DataFrame convenience wrapper.
+        """
+        params: dict[str, Any] = {"page": page, "size": size}
+        if split_id is not None:
+            params["splitId"] = str(split_id)
+        if image_id is not None:
+            params["imageId"] = str(image_id)
+        if sort_by is not None:
+            params["sortBy"] = sort_by
+        if sort_dir is not None:
+            params["sortDir"] = sort_dir
+        params.update(filters)
+        data = self._t.get(f"{self._base}/annotations", params=params)
+        return PagedResponse.model_validate(data)
+
+    def create_annotation(self, request: CreateAnnotationRequest) -> AnnotationModel:
+        """Create a single annotation."""
+        data = self._t.post(f"{self._base}/annotations", json=request.model_dump())
+        return AnnotationModel.model_validate(data)
+
+    def update_annotation(
+        self, annotation_id: int, request: UpdateAnnotationRequest
+    ) -> AnnotationModel:
+        """Update an annotation."""
+        data = self._t.put(
+            f"{self._base}/annotations/{annotation_id}",
+            json=request.model_dump(exclude_none=True),
+        )
+        return AnnotationModel.model_validate(data)
+
+    def delete_annotation(self, annotation_id: int) -> None:
+        """Delete a single annotation."""
+        self._t.delete(f"{self._base}/annotations/{annotation_id}")
+
+    def delete_annotations(
+        self,
+        annotation_ids: list[int] | None = None,
+        **kwargs: Any,
+    ) -> DeleteAnnotationsResponse:
+        """Delete annotations from this dataset."""
+        body: dict[str, Any] = {}
+        if annotation_ids is not None:
+            body["annotation_ids"] = annotation_ids
+        body.update(kwargs)
+        data = self._t.delete_with_body(f"{self._base}/annotations", json=body)
+        return DeleteAnnotationsResponse.model_validate(data)
+
+    def ingest_annotations(self, coco_json: dict[str, Any]) -> Any:
+        """Bulk ingest COCO annotations at dataset level."""
+        return self._t.post(f"{self._base}/annotations/ingest", json=coco_json)
+
+    # ── Validation / QA ───────────────────────────────────────────────
+
+    def validate(self) -> ValidationResultsModel:
+        """Run validation checks on this dataset."""
+        data = self._t.post(f"{self._base}/validate")
+        return ValidationResultsModel.model_validate(data)
+
+    def check_duplicates(
+        self, check_type: str = "image_hashes", hash_threshold: float = 0.95
+    ) -> DuplicateCheckModel:
+        """Check for duplicate images."""
+        data = self._t.post(
+            f"{self._base}/validate/duplicates",
+            json={"check_type": check_type, "hash_threshold": hash_threshold},
+        )
+        return DuplicateCheckModel.model_validate(data)
+
+    def detect_temporal_conflicts(self) -> TemporalConflictModel:
+        """Detect temporal annotation conflicts."""
+        data = self._t.post(f"{self._base}/qa/temporal-conflicts")
+        return TemporalConflictModel.model_validate(data)
+
+    def resolve_temporal_conflicts(
+        self, resolutions: list[dict[str, Any]]
+    ) -> ResolveTemporalConflictResponse:
+        """Resolve temporal conflicts."""
+        data = self._t.post(
+            f"{self._base}/qa/temporal-conflicts/resolve",
+            json={"resolutions": resolutions},
+        )
+        return ResolveTemporalConflictResponse.model_validate(data)
+
+    # ── Metrics ───────────────────────────────────────────────────────
+
+    def overview(self) -> OverviewModel:
+        """Get comprehensive dataset overview statistics."""
+        data = self._t.get(f"{self._base}/metrics/overview")
+        return OverviewModel.model_validate(data)
+
+    def class_distribution(self) -> ClassDistributionModel:
+        """Get class distribution across splits."""
+        data = self._t.get(f"{self._base}/metrics/class-distribution")
+        return ClassDistributionModel.model_validate(data)
+
+    def bbox_area(self, bins: int = 10) -> BinnedModel:
+        """Get bounding box area distribution."""
+        params: dict[str, Any] = {"bins": bins}
+        data = self._t.get(f"{self._base}/metrics/bbox-area", params=params)
+        return BinnedModel.model_validate(data)
+
+    # ── Few-Shot ──────────────────────────────────────────────────────
+
+    def few_shot_preview(self, request: FewShotRequest) -> FewShotPreviewModel:
+        """Preview few-shot dataset creation."""
+        data = self._t.post(f"{self._base}/few-shot/preview", json=request.model_dump())
+        return FewShotPreviewModel.model_validate(data)
+
+    def few_shot_create(self, request: FewShotRequest) -> FewShotResponseModel:
+        """Create a few-shot dataset."""
+        data = self._t.post(f"{self._base}/few-shot", json=request.model_dump())
+        return FewShotResponseModel.model_validate(data)
+
+    # ── Oversample ────────────────────────────────────────────────────
+
+    def oversample_analyze(self, request: OversampleRequest) -> OversampleAnalysisModel:
+        """Analyze oversampling potential."""
+        data = self._t.post(f"{self._base}/oversample/analyze", json=request.model_dump())
+        return OversampleAnalysisModel.model_validate(data)
+
+    def oversample_execute(self, request: OversampleRequest) -> OversampleResponseModel:
+        """Execute oversampling."""
+        data = self._t.post(f"{self._base}/oversample", json=request.model_dump())
+        return OversampleResponseModel.model_validate(data)
+
+    # ── Filter ────────────────────────────────────────────────────────
+
+    def filter(self, request: DatasetFilterRequest) -> DatasetFilterResponse:
+        """Apply filters to create a filtered dataset."""
+        data = self._t.post(f"{self._base}/filter", json=request.model_dump(exclude_none=True))
+        return DatasetFilterResponse.model_validate(data)
+
+    def filter_preview(self, request: DatasetFilterRequest) -> DatasetFilterResponse:
+        """Preview filter results without applying."""
+        req = request.model_copy(update={"dry_run": True})
+        data = self._t.post(
+            f"{self._base}/filter/preview", json=req.model_dump(exclude_none=True)
+        )
+        return DatasetFilterResponse.model_validate(data)
+
+    # ── Export ─────────────────────────────────────────────────────────
+
+    def export_coco(
+        self,
+        reindex_images: bool = True,
+        reindex_annotations: bool = True,
+        reindex_categories: bool = True,
+        starting_id: int = 1,
+    ) -> ExportCocoModel:
+        """Export entire dataset as COCO JSON."""
+        data = self._t.post(
+            f"{self._base}/export/coco",
+            json={
+                "reindex_images": reindex_images,
+                "reindex_annotations": reindex_annotations,
+                "reindex_categories": reindex_categories,
+                "starting_id": starting_id,
+            },
+        )
+        return ExportCocoModel.model_validate(data)
+
+    # ── History / Undo / Redo ─────────────────────────────────────────
+
+    def history(self) -> HistoryModel:
+        """Get dataset change history."""
+        data = self._t.get(f"{self._base}/history")
+        return HistoryModel.model_validate(data)
+
+    def preview_undo(self) -> PreviewModel:
+        """Preview what an undo operation would do."""
+        data = self._t.get(f"{self._base}/history/preview-undo")
+        return PreviewModel.model_validate(data)
+
+    def preview_redo(self) -> PreviewModel:
+        """Preview what a redo operation would do."""
+        data = self._t.get(f"{self._base}/history/preview-redo")
+        return PreviewModel.model_validate(data)
+
+    def undo(self) -> UndoRedoResponse:
+        """Undo the last operation."""
+        data = self._t.post(f"{self._base}/history/undo")
+        return UndoRedoResponse.model_validate(data)
+
+    def redo(self) -> UndoRedoResponse:
+        """Redo the last undone operation."""
+        data = self._t.post(f"{self._base}/history/redo")
+        return UndoRedoResponse.model_validate(data)
+
+    def rewind(self, target_change_id: str | UUID) -> RewindResponse:
+        """Rewind to a specific point in history."""
+        data = self._t.post(
+            f"{self._base}/history/rewind",
+            json={"target_change_id": str(target_change_id)},
+        )
+        return RewindResponse.model_validate(data)
+
+    # ── DataFrame helpers ─────────────────────────────────────────────
+
+    def categories_df(self) -> Any:
+        """Return categories as a pandas DataFrame."""
+        from modelstudio._pandas import to_dataframe
+
+        cat_list = self.categories()
+        return to_dataframe(cat_list.categories)
+
+    def class_distribution_df(self) -> Any:
+        """Return class distribution as a pandas DataFrame."""
+        from modelstudio._pandas import _get_pandas
+
+        pd = _get_pandas()
+        dist = self.class_distribution()
+        return pd.DataFrame(dist.classes)
+
+    def images_df(self, **kwargs: Any) -> Any:
+        """Return paginated images as a pandas DataFrame."""
+        from modelstudio._pandas import _get_pandas
+
+        pd = _get_pandas()
+        paged = self.list_images(**kwargs)
+        return pd.DataFrame(paged.content)
+
+    def annotations_df(self, **kwargs: Any) -> Any:
+        """Return paginated annotations as a pandas DataFrame."""
+        from modelstudio._pandas import _get_pandas
+
+        pd = _get_pandas()
+        paged = self.list_annotations(**kwargs)
+        return pd.DataFrame(paged.content)