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

modelstudio/models/metrics.py

@@ -0,0 +1,180 @@
+"""Metrics and statistics models (OverviewDto + 11 nested types)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class DescriptiveStats(BaseModel):
+    """Reusable descriptive statistics for any numeric distribution."""
+
+    count: int = 0
+    min: float = 0.0
+    max: float = 0.0
+    mean: float = 0.0
+    median: float = 0.0
+    mode: float | None = None
+    std_dev: float = 0.0
+    variance: float = 0.0
+    q1: float = 0.0
+    q3: float = 0.0
+    iqr: float = 0.0
+    p5: float = 0.0
+    p95: float = 0.0
+    skewness: float | None = None
+    outlier_count: int = 0
+
+
+class AspectRatioDistribution(BaseModel):
+    """Aspect ratio distribution for images."""
+
+    portrait: int = 0
+    landscape: int = 0
+    square: int = 0
+    min_ratio: float = 0.0
+    max_ratio: float = 0.0
+    avg_ratio: float = 0.0
+    median_ratio: float = 0.0
+
+
+class ImageDimensionStats(BaseModel):
+    """Image dimension statistics."""
+
+    min_width: int = 0
+    max_width: int = 0
+    avg_width: float = 0.0
+    median_width: float = 0.0
+    mode_width: int | None = None
+    std_dev_width: float = 0.0
+    q1_width: float = 0.0
+    q3_width: float = 0.0
+    p5_width: float = 0.0
+    p95_width: float = 0.0
+    outlier_count_width: int = 0
+    min_height: int = 0
+    max_height: int = 0
+    avg_height: float = 0.0
+    median_height: float = 0.0
+    mode_height: int | None = None
+    std_dev_height: float = 0.0
+    q1_height: float = 0.0
+    q3_height: float = 0.0
+    p5_height: float = 0.0
+    p95_height: float = 0.0
+    outlier_count_height: int = 0
+    aspect_ratio: AspectRatioDistribution | None = None
+
+
+class SyntheticBreakdown(BaseModel):
+    """Breakdown of real vs synthetic images."""
+
+    real_images: int = 0
+    synthetic_images: int = 0
+    synthetic_ratio: float = 0.0
+
+
+class AnnotationDistribution(BaseModel):
+    """Annotation count distribution across images."""
+
+    per_image_stats: DescriptiveStats | None = None
+    buckets: dict[str, int] = {}
+
+
+class CategoryStats(BaseModel):
+    """Per-category statistics with bbox dimension statistics."""
+
+    category_name: str | None = None
+    annotation_count: int = 0
+    bbox_width_stats: DescriptiveStats | None = None
+    bbox_height_stats: DescriptiveStats | None = None
+    bbox_area_stats: DescriptiveStats | None = None
+    zero_area_count: int = 0
+    out_of_bounds_count: int = 0
+    crowd_count: int = 0
+    ignored_count: int = 0
+    avg_coverage_percent: float = 0.0
+
+
+class SegmentationCategoryStats(BaseModel):
+    """Per-category pixel coverage stats for segmentation datasets."""
+
+    category_name: str | None = None
+    image_count: int = 0
+    total_pixel_count: int = 0
+    pixel_percentage: float = 0.0
+    avg_coverage_percent: float = 0.0
+    pixel_count_stats: DescriptiveStats | None = None
+    area_m2: float | None = None
+    avg_area_m2_per_image: float | None = None
+
+
+class DataQualityMetrics(BaseModel):
+    """Data quality metrics for a split."""
+
+    empty_image_count: int = 0
+    empty_image_percent: float = 0.0
+    crowd_annotation_count: int = 0
+    crowd_annotation_percent: float = 0.0
+    ignored_annotation_count: int = 0
+    ignored_annotation_percent: float = 0.0
+    annotations_with_segmentation: int = 0
+    annotations_with_keypoints: int = 0
+
+
+class ClassImbalance(BaseModel):
+    """Class imbalance information for a split."""
+
+    top_class_name: str | None = None
+    top_class_count: int = 0
+    top_class_share: float = 0.0
+    imbalance_score: float = 0.0
+
+
+class SplitStatistics(BaseModel):
+    """Complete statistics for a single split."""
+
+    image_count: int = 0
+    annotation_count: int = 0
+    category_count: int = 0
+    image_dimensions: ImageDimensionStats | None = None
+    images_by_format: dict[str, int] = {}
+    synthetic_breakdown: SyntheticBreakdown | None = None
+    annotation_distribution: AnnotationDistribution | None = None
+    per_category_stats: dict[str, CategoryStats] = {}
+    data_quality: DataQualityMetrics | None = None
+    class_imbalance: ClassImbalance | None = None
+    segmentation_category_stats: dict[str, SegmentationCategoryStats] | None = None
+
+
+class DatasetSummary(BaseModel):
+    """Dataset-level summary derived from per-split statistics."""
+
+    total_images: int = 0
+    total_annotations: int = 0
+    total_categories: int = 0
+    distinct_classes: int = 0
+
+
+class OverviewModel(BaseModel):
+    """Comprehensive dataset overview from GET /datasets/{id}/metrics/overview."""
+
+    summary: DatasetSummary | None = None
+    splits: dict[str, SplitStatistics] = {}
+    category_co_occurrence: dict[str, dict[str, int]] = {}
+
+
+class ClassDistributionModel(BaseModel):
+    """Response from GET /datasets/{id}/metrics/class-distribution."""
+
+    classes: list[dict[str, Any]] = []
+    totals: dict[str, Any] = {}
+
+
+class BinnedModel(BaseModel):
+    """Response from GET /datasets/{id}/metrics/bbox-area."""
+
+    bins: list[dict[str, Any]] = []
+    bin_type: str | None = None
+    image_area_norm: bool = False

modelstudio/models/oversample.py

@@ -0,0 +1,41 @@
+"""Oversample models."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class OversampleRequest(BaseModel):
+    """Request for POST /datasets/{id}/oversample."""
+
+    target_ratio: float
+    strategy: str = "PREFER_ANNOTATED"
+    seed: int | None = None
+    target_split_id: UUID | None = None
+
+
+class OversampleAnalysisModel(BaseModel):
+    """Response from POST /datasets/{id}/oversample/analyze."""
+
+    current_real_images: int = 0
+    current_synthetic_images: int = 0
+    current_ratio: float = 0.0
+    target_ratio: float = 0.0
+    oversample_target: int | str | None = None
+    images_to_duplicate: int = 0
+    selected_images: list[dict[str, Any]] = []
+
+
+class OversampleResponseModel(BaseModel):
+    """Response from POST /datasets/{id}/oversample."""
+
+    success: bool = False
+    message: str | None = None
+    images_duplicated: int = 0
+    annotations_duplicated: int = 0
+    new_real_count: int = 0
+    new_synthetic_count: int = 0
+    new_ratio: float = 0.0

modelstudio/models/splits.py

@@ -0,0 +1,112 @@
+"""Split-related models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class SplitModel(BaseModel):
+    """Represents a dataset split."""
+
+    split_id: UUID
+    split_type: str | None = None
+    tao_id: UUID | None = None
+    name: str | None = None
+    description: str | None = None
+    created_on: datetime | None = None
+    locked: bool = False
+    uploaded: bool = False
+    import_status: str | None = None
+    import_progress: int | None = None
+    import_error: str | None = None
+    import_started_at: datetime | None = None
+    import_finished_at: datetime | None = None
+    import_source: str | None = None
+
+
+class CreateSplitsResponse(BaseModel):
+    """Response from POST /datasets/{id}/splits/create."""
+
+    success: bool
+    message: str | None = None
+    splits: list[SplitModel] = []
+    summary: dict[str, Any] | None = None
+
+
+class RedistributeResponse(BaseModel):
+    """Response from POST /datasets/{id}/splits/redistribute."""
+
+    previous_distribution: dict[str, Any] | None = None
+    new_distribution: dict[str, Any] | None = None
+
+
+class SmartRedistributeResponse(BaseModel):
+    """Response from POST /datasets/{id}/splits/smart-redistribute."""
+
+    previous_distribution: dict[str, Any] | None = None
+    new_distribution: dict[str, Any] | None = None
+    class_distribution_error: dict[str, Any] | None = None
+    iterations_used: int | None = None
+    converged: bool | None = None
+
+
+class LeakageResponse(BaseModel):
+    """Response from POST /datasets/{id}/splits/check-leakage."""
+
+    has_leakage: bool = False
+    leakage_count: int = 0
+    method: str | None = None
+    leakages: list[dict[str, Any]] = []
+    summary: dict[str, Any] | None = None
+
+
+# ── Class-aware redistribute (replaces smart-redistribute) ───────────────
+
+
+class SplitStats(BaseModel):
+    """Per-split statistics in a class-aware redistribute response."""
+
+    image_count: int = 0
+    annotation_count: int = 0
+    ratio: float = 0.0
+
+
+class ClassError(BaseModel):
+    """Per-class distribution error."""
+
+    category_name: str | None = None
+    target_ratio: float = 0.0
+    actual_ratio: float = 0.0
+    error: float = 0.0
+
+
+class DistributionError(BaseModel):
+    """Per-split distribution error breakdown."""
+
+    split_name: str | None = None
+    mean_error: float = 0.0
+    max_error: float = 0.0
+    class_errors: list[ClassError] = []
+
+
+class AlgorithmStats(BaseModel):
+    """Algorithm statistics from class-aware redistribution."""
+
+    iterations_used: int = 0
+    converged: bool = False
+    final_error: float = 0.0
+    elapsed_ms: int | None = None
+
+
+class ClassAwareRedistributeResponse(BaseModel):
+    """Response from POST /datasets/{id}/splits/class-aware-redistribute."""
+
+    previous_distribution: dict[str, Any] | None = None
+    new_distribution: dict[str, Any] | None = None
+    split_stats: dict[str, SplitStats] | None = None
+    distribution_errors: list[DistributionError] = []
+    algorithm_stats: AlgorithmStats | None = None

modelstudio/models/validation.py

@@ -0,0 +1,89 @@
+"""Validation and QA models."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class DuplicateItem(BaseModel):
+    """A single image in a duplicate group."""
+
+    image_id: UUID | None = None
+    file_name: str | None = None
+    split_name: str | None = None
+    hash: str | None = None
+    uri: str | None = None
+
+
+class DuplicateGroup(BaseModel):
+    """A group of duplicate images."""
+
+    group_id: int = 0
+    duplicate_type: str | None = None
+    similarity: float = 0.0
+    items: list[DuplicateItem] = []
+
+
+class DuplicateCheckModel(BaseModel):
+    """Response from POST /datasets/{id}/validate/duplicates."""
+
+    has_duplicates: bool = False
+    duplicate_group_count: int = 0
+    total_duplicate_images: int = 0
+    check_type: str | None = None
+    hash_threshold: float = 0.95
+    duplicate_groups: list[DuplicateGroup] = []
+    summary: dict[str, Any] = {}
+
+
+class ConflictAnnotation(BaseModel):
+    """Annotation in a temporal conflict cluster."""
+
+    split_id: UUID | None = None
+    annotation_id: int = 0
+    image_id: UUID | None = None
+    image_file_name: str | None = None
+    category_name: str | None = None
+    category_id: int = 0
+    bbox: list[float] = []
+    capture_timestamp: str | None = None
+    is_outlier: bool = False
+
+
+class ConflictCluster(BaseModel):
+    """A temporal conflict cluster."""
+
+    cluster_id: int = 0
+    tile_id: str | None = None
+    annotations: list[ConflictAnnotation] = []
+    distinct_categories: int = 0
+    suggested_category: str | None = None
+    confidence: float = 0.0
+
+
+class TemporalConflictModel(BaseModel):
+    """Response from POST /datasets/{id}/qa/temporal-conflicts."""
+
+    has_conflicts: bool = False
+    clusters: list[ConflictCluster] = []
+
+
+class ResolveTemporalConflictResponse(BaseModel):
+    """Response from POST /datasets/{id}/qa/temporal-conflicts/resolve."""
+
+    success: bool = False
+    message: str | None = None
+    dataset_id: str | None = None
+    clusters_resolved: int = 0
+    annotations_updated: int = 0
+
+
+class ValidationResultsModel(BaseModel):
+    """Generic validation results."""
+
+    valid: bool = True
+    errors: list[dict[str, Any]] = []
+    warnings: list[dict[str, Any]] = []

modelstudio/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource objects that map to API endpoints."""