superb-ai-onprem 0.6.3__py3-none-any.whl → 0.7.1__py3-none-any.whl

spb_onprem/data/params/data_list.py

@@ -4,53 +4,164 @@ from spb_onprem.data.enums import DataType, DataStatus
 from spb_onprem.exceptions import BadParameterError
 
 # === 기본 필터 ===
+
 class DateTimeRangeFilterOption(CustomBaseModel):
-    datetime_from: Optional[str] = Field(None, alias="from")
-    to: Optional[str] = None
-    equals: Optional[str] = None
+    """
+    날짜/시간 범위 필터 옵션
+    
+    사용 예시:
+        # 범위 필터
+        {"from": "2025-01-01T00:00:00Z", "to": "2025-12-31T23:59:59Z"}
+        
+        # 정확한 날짜
+        {"equals": "2025-09-17T10:00:00Z"}
+        
+        # 시작 날짜만
+        {"from": "2025-01-01T00:00:00Z"}
+    """
+    datetime_from: Optional[str] = Field(None, alias="from", description="시작 날짜/시간 (ISO 8601 형식)")
+    to: Optional[str] = Field(None, description="종료 날짜/시간 (ISO 8601 형식)")
+    equals: Optional[str] = Field(None, description="정확한 날짜/시간 (ISO 8601 형식)")
+
 
 class UserFilterOption(CustomBaseModel):
-    equals: Optional[str] = None
-    contains: Optional[str] = None
-    user_in: Optional[List[str]] = Field(None, alias="in")
-    exists: Optional[bool] = None
+    """
+    사용자 필터 옵션 (생성자, 수정자 등)
+    
+    사용 예시:
+        # 정확한 사용자
+        {"equals": "user@example.com"}
+        
+        # 부분 일치
+        {"contains": "admin"}
+        
+        # 여러 사용자 중 하나
+        {"in": ["user1@example.com", "user2@example.com"]}
+        
+        # 사용자 존재 여부
+        {"exists": True}
+    """
+    equals: Optional[str] = Field(None, description="정확한 사용자 이메일")
+    contains: Optional[str] = Field(None, description="사용자 이메일에 포함된 문자열")
+    user_in: Optional[List[str]] = Field(None, alias="in", description="사용자 이메일 목록 중 하나")
+    exists: Optional[bool] = Field(None, description="사용자 정보 존재 여부")
+
 
 class NumericRangeFilter(CustomBaseModel):
-    gt: Optional[float] = None
-    gte: Optional[float] = None
-    lt: Optional[float] = None
-    lte: Optional[float] = None
-    equals: Optional[float] = None
+    """
+    숫자 범위 필터
+    
+    사용 예시:
+        # 범위 필터
+        {"gte": 0.8, "lt": 1.0}  # 0.8 이상 1.0 미만
+        
+        # 정확한 값
+        {"equals": 5}
+        
+        # 단일 조건
+        {"gt": 10}  # 10보다 큰 값
+    """
+    gt: Optional[float] = Field(None, description="초과 (greater than)")
+    gte: Optional[float] = Field(None, description="이상 (greater than or equal)")
+    lt: Optional[float] = Field(None, description="미만 (less than)")
+    lte: Optional[float] = Field(None, description="이하 (less than or equal)")
+    equals: Optional[float] = Field(None, description="정확한 값")
+
 
 class GeoLocationFilter(CustomBaseModel):
-    latitude: float
-    longitude: float
-    radius_in_meters: float = Field(..., alias="radiusInMeters")
+    """
+    지리적 위치 필터 (위도, 경도, 반경)
+    
+    사용 예시:
+        {
+            "latitude": 37.5665,
+            "longitude": 126.9780,
+            "radiusInMeters": 1000
+        }
+    """
+    latitude: float = Field(..., description="위도 (-90 ~ 90)")
+    longitude: float = Field(..., description="경도 (-180 ~ 180)")
+    radius_in_meters: float = Field(..., alias="radiusInMeters", description="반경 (미터 단위)")
 
 # === Meta 필터 ===
+
 class NumberMetaFilter(CustomBaseModel):
-    key: str
-    range: Optional[NumericRangeFilter] = None
+    """
+    숫자형 메타데이터 필터
+    
+    사용 예시:
+        {
+            "key": "confidence_score",
+            "range": {"gte": 0.8, "lt": 1.0}
+        }
+    """
+    key: str = Field(..., description="메타데이터 키 이름")
+    range: Optional[NumericRangeFilter] = Field(None, description="숫자 범위 조건")
 
 class KeywordMetaFilter(CustomBaseModel):
-    key: str
-    equals: Optional[str] = None
-    contains: Optional[str] = None
-    keyword_in: Optional[List[str]] = Field(None, alias="in")
+    """
+    키워드/텍스트형 메타데이터 필터
+    
+    사용 예시:
+        # 정확한 일치
+        {"key": "category", "equals": "vehicle"}
+        
+        # 부분 일치
+        {"key": "tags", "contains": "outdoor"}
+        
+        # 여러 값 중 하나
+        {"key": "status", "in": ["active", "pending"]}
+    """
+    key: str = Field(..., description="메타데이터 키 이름")
+    equals: Optional[str] = Field(None, description="정확한 값")
+    contains: Optional[str] = Field(None, description="포함된 문자열")
+    keyword_in: Optional[List[str]] = Field(None, alias="in", description="값 목록 중 하나")
+
 
 class DateMetaFilter(CustomBaseModel):
-    key: str
-    range: Optional[DateTimeRangeFilterOption] = None
+    """
+    날짜형 메타데이터 필터
+    
+    사용 예시:
+        {
+            "key": "capture_date",
+            "range": {
+                "from": "2025-01-01T00:00:00Z",
+                "to": "2025-06-30T23:59:59Z"
+            }
+        }
+    """
+    key: str = Field(..., description="메타데이터 키 이름")
+    range: Optional[DateTimeRangeFilterOption] = Field(None, description="날짜 범위 조건")
+
 
 class MiscMetaFilter(CustomBaseModel):
-    key: str
-    equals: str
+    """
+    기타 메타데이터 필터 (정확한 일치만 지원)
+    
+    사용 예시:
+        {"key": "custom_field", "equals": "specific_value"}
+    """
+    key: str = Field(..., description="메타데이터 키 이름")
+    equals: str = Field(..., description="정확한 값")
+
 
 class MetaFilter(CustomBaseModel):
-    num: Optional[List[NumberMetaFilter]] = None
-    keyword: Optional[List[KeywordMetaFilter]] = None
-    date: Optional[List[DateMetaFilter]] = None
-    misc: Optional[List[MiscMetaFilter]] = None
+    """
+    메타데이터 필터 컨테이너
+    
+    사용 예시:
+        {
+            "num": [{"key": "confidence", "range": {"gte": 0.8}}],
+            "keyword": [{"key": "category", "equals": "vehicle"}],
+            "date": [{"key": "capture_date", "range": {"from": "2025-01-01T00:00:00Z"}}],
+            "misc": [{"key": "custom", "equals": "value"}]
+        }
+    """
+    num: Optional[List[NumberMetaFilter]] = Field(None, description="숫자형 메타데이터 필터 목록")
+    keyword: Optional[List[KeywordMetaFilter]] = Field(None, description="키워드형 메타데이터 필터 목록")
+    date: Optional[List[DateMetaFilter]] = Field(None, description="날짜형 메타데이터 필터 목록")
+    misc: Optional[List[MiscMetaFilter]] = Field(None, description="기타 메타데이터 필터 목록")
 
 # === Count 필터 ===
 class CountFilter(CustomBaseModel):
@@ -79,20 +190,43 @@ class FrameFilterOptions(CustomBaseModel):
     counts: Optional[FrameCountsFilter] = None
 
 # === Data 필터 ===
+
 class DataFilterOptions(CustomBaseModel):
-    id_in: Optional[List[str]] = Field(None, alias="idIn")
-    slice_id_in: Optional[List[str]] = Field(None, alias="sliceIdIn")
-    key_contains: Optional[str] = Field(None, alias="keyContains")
-    key_matches: Optional[str] = Field(None, alias="keyMatches")
-    sub_type_contains: Optional[str] = Field(None, alias="subTypeContains")
-    sub_type_matches: Optional[str] = Field(None, alias="subTypeMatches")
-    type_in: Optional[List[str]] = Field(None, alias="typeIn")
-    created_at: Optional[DateTimeRangeFilterOption] = Field(None, alias="createdAt")
-    updated_at: Optional[DateTimeRangeFilterOption] = Field(None, alias="updatedAt")
-    created_by: Optional[UserFilterOption] = Field(None, alias="createdBy")
-    updated_by: Optional[UserFilterOption] = Field(None, alias="updatedBy")
-    meta: Optional[MetaFilter] = None
-    assigned_to_user: Optional[str] = Field(None, alias="assignedToUser")
+    """
+    데이터 필터링 옵션 (기본 데이터 속성 필터)
+    
+    사용 예시:
+        DataFilterOptions(
+            type_in=["IMAGE", "VIDEO"],
+            key_contains="sample_",
+            created_at={"from": "2025-01-01T00:00:00Z"},
+            meta={"keyword": [{"key": "category", "equals": "vehicle"}]}
+        )
+    """
+    # ID 및 키 필터
+    id_in: Optional[List[str]] = Field(None, alias="idIn", description="특정 데이터 ID 목록 중 하나")
+    slice_id_in: Optional[List[str]] = Field(None, alias="sliceIdIn", description="특정 슬라이스 ID 목록에 속한 데이터")
+    
+    # 키 패턴 필터
+    key_contains: Optional[str] = Field(None, alias="keyContains", description="키에 포함된 문자열")
+    key_matches: Optional[str] = Field(None, alias="keyMatches", description="키와 매칭되는 정규식 패턴")
+    
+    # 타입 필터
+    sub_type_contains: Optional[str] = Field(None, alias="subTypeContains", description="서브타입에 포함된 문자열")
+    sub_type_matches: Optional[str] = Field(None, alias="subTypeMatches", description="서브타입과 매칭되는 정규식 패턴")
+    type_in: Optional[List[str]] = Field(None, alias="typeIn", description="데이터 타입 목록 중 하나 (IMAGE, VIDEO 등)")
+    
+    # 날짜 필터
+    created_at: Optional[DateTimeRangeFilterOption] = Field(None, alias="createdAt", description="생성일 범위")
+    updated_at: Optional[DateTimeRangeFilterOption] = Field(None, alias="updatedAt", description="수정일 범위")
+    
+    # 사용자 필터
+    created_by: Optional[UserFilterOption] = Field(None, alias="createdBy", description="생성자 필터")
+    updated_by: Optional[UserFilterOption] = Field(None, alias="updatedBy", description="수정자 필터")
+    
+    # 메타데이터 및 기타
+    meta: Optional[MetaFilter] = Field(None, description="커스텀 메타데이터 필터")
+    assigned_to_user: Optional[str] = Field(None, alias="assignedToUser", description="할당된 사용자")
 
 class DataSliceStatusFilterOption(CustomBaseModel):
     status_in: Optional[List[str]] = Field(None, alias="in")
@@ -148,10 +282,67 @@ class DataFilter(CustomBaseModel):
 
 
 class DataListFilter(CustomBaseModel):
-    must_filter: Optional[DataFilterOptions] = Field(None, alias="must")
-    not_filter: Optional[DataFilterOptions] = Field(None, alias="not")
-    slice: Optional[DataSliceFilter] = Field(None, alias="slice")
-    frames: Optional[List[FrameFilter]] = Field(None, alias="frames")
+    """
+    데이터 리스트 필터 - 메인 필터 클래스
+    
+    논리 연산자를 사용한 복합 필터링을 지원합니다:
+    - must_filter: AND 조건 (모든 조건이 참이어야 함)
+    - not_filter: NOT 조건 (모든 조건이 거짓이어야 함)
+    - slice: 특정 슬라이스 내에서 필터링
+    - frames: 프레임 레벨 필터링 (비디오 데이터용)
+    
+    사용 예시:
+        # 기본 필터
+        DataListFilter(
+            must_filter=DataFilterOptions(
+                type_in=["IMAGE"],
+                key_contains="sample_"
+            )
+        )
+        
+        # 복합 필터 (AND + NOT)
+        DataListFilter(
+            must_filter=DataFilterOptions(type_in=["IMAGE"]),
+            not_filter=DataFilterOptions(key_contains="test_")
+        )
+        
+        # 슬라이스 특정 필터
+        DataListFilter(
+            slice={
+                "id": "slice-123",
+                "must": {"status": {"in": ["LABELED"]}}
+            }
+        )
+        
+        # Dictionary에서 생성 (alias 사용 필수)
+        filter_dict = {
+            "must": {
+                "typeIn": ["IMAGE"],
+                "keyContains": "sample_"
+            }
+        }
+        filter = DataListFilter.model_validate(filter_dict)
+    """
+    must_filter: Optional[DataFilterOptions] = Field(
+        None, 
+        alias="must", 
+        description="AND 조건 - 모든 조건이 참이어야 함"
+    )
+    not_filter: Optional[DataFilterOptions] = Field(
+        None, 
+        alias="not", 
+        description="NOT 조건 - 모든 조건이 거짓이어야 함"
+    )
+    slice: Optional[DataSliceFilter] = Field(
+        None, 
+        alias="slice", 
+        description="슬라이스별 필터링"
+    )
+    frames: Optional[List[FrameFilter]] = Field(
+        None, 
+        alias="frames", 
+        description="프레임 레벨 필터 목록 (비디오 데이터용)"
+    )
 
 
 def get_data_id_list_params(
@@ -169,13 +360,13 @@ def get_data_id_list_params(
         length (Optional[int], optional): The length of the data list. Defaults to 50.
 
     Raises:
-        BadParameterError: The maximum length is 200.
+        BadParameterError: The maximum length is 50.
 
     Returns:
         dict: The variables for the dataIdList query.
     """
-    if length > 200:
-        raise BadParameterError("The maximum length is 200.")
+    if length > 50:
+        raise BadParameterError("The maximum length is 50.")
     return {
         "dataset_id": dataset_id,
         "filter": data_filter.model_dump(by_alias=True, exclude_unset=True) if data_filter else None,

spb_onprem/data/params/update_data.py

@@ -28,10 +28,9 @@ def update_params(
 
     Args:
         dataset_id (str): The dataset ID of the data.
-        id (str): The ID of the data.
+        data_id (str): The ID of the data.
         key (str): The key of the data.
         meta (List[DataMeta]): The meta of the data.
-        system_meta (List[DataMeta]): The system meta of the data.
     """
     variables = {
         "datasetId": dataset_id,
@@ -46,11 +45,11 @@ def update_params(
             raise ValueError("meta must be a list of DataMeta or None.")
         variables["meta"] = [
             {
-                "key": meta.key,
-                "type": meta.type.value,
-                "value": meta.value,
+                "key": meta_item.key,
+                "type": meta_item.type.value,
+                "value": meta_item.value,
             }
-            for meta in meta
+            for meta_item in meta
         ] if meta is not None else None
 
     return variables

spb_onprem/data/params/update_data_slice.py

@@ -1,11 +1,18 @@
-from typing import Any
+from typing import Any, Optional, Union
+from spb_onprem.base_types import (
+    Undefined,
+    UndefinedType,
+)
 
 
 def update_data_slice_params(
     dataset_id: str,
     data_id: str,
     slice_id: str,
-    meta: Any,
+    meta: Union[
+        Optional[dict],
+        UndefinedType
+    ] = Undefined,
 ):
     """Make the variables for the updateDataSlice query.
 
@@ -13,11 +20,15 @@ def update_data_slice_params(
         dataset_id (str): The dataset ID of the data.
         data_id (str): The ID of the data.
         slice_id (str): The slice ID.
-        meta (Any): The meta of the data slice.
+        meta (dict): The meta of the data slice.
     """
-    return {
+    params = {
         "dataset_id": dataset_id,
         "data_id": data_id,
         "slice_id": slice_id,
-        "meta": meta,
-    } 
+    }
+    
+    if meta is not Undefined:
+        params["meta"] = meta
+
+    return params

spb_onprem/data/queries.py

@@ -97,6 +97,25 @@ class Schemas:
                     }
                     meta
                 }
+                comments {
+                    id
+                    category
+                    comment
+                    status
+                    replies {
+                        id
+                        comment
+                        createdAt
+                        createdBy
+                        updatedAt
+                        updatedBy
+                    }
+                    meta
+                    updatedAt
+                    updatedBy
+                    createdAt
+                    createdBy
+                }
                 meta
             }
             meta

spb_onprem/data/service.py

@@ -19,6 +19,7 @@ from .entities import (
     AnnotationVersion,
     Prediction,
     Frame,
+    DataMeta,
 )
 from .enums import (
     DataStatus,
@@ -195,7 +196,7 @@ class DataService(BaseService):
             UndefinedType,
         ] = Undefined,
         meta: Union[
-            List[dict],
+            List[DataMeta],
             UndefinedType,
         ] = Undefined,
     ):
@@ -205,7 +206,7 @@ class DataService(BaseService):
             dataset_id (str): The dataset id.
             data_id (str): The data id.
             key (Union[str, UndefinedType], optional): The key of the data. Defaults to Undefined.
-            meta (Union[List[dict], UndefinedType], optional): The meta data. Defaults to Undefined.
+            meta (Union[List[DataMeta], UndefinedType], optional): The meta data. Defaults to Undefined.
 
         Returns:
             Data: The updated data.
@@ -715,7 +716,10 @@ class DataService(BaseService):
         dataset_id: str,
         data_id: str,
         slice_id: str,
-        meta: dict,
+        meta: Union[
+            Optional[dict],
+            UndefinedType
+        ] = Undefined,
     ):
         """Update the metadata of a data slice.
 
@@ -734,8 +738,6 @@ class DataService(BaseService):
             raise BadParameterError("data_id is required.")
         if slice_id is None:
             raise BadParameterError("slice_id is required.")
-        if meta is None:
-            raise BadParameterError("meta is required.")
         
         response = self.request_gql(
             Queries.UPDATE_DATA_SLICE,

spb_onprem/datasets/entities/dataset.py

@@ -4,11 +4,17 @@ from spb_onprem.data.entities.data import Data
 
 
 class Dataset(CustomBaseModel):
-    id: Optional[str] = Field(None)
-    name: Optional[str] = Field(None)
-    description: Optional[str] = Field(None)
+    """
+    데이터셋 엔터티
+    
+    데이터를 그룹화하고 관리하는 컨테이너입니다.
+    프로젝트별, 도메인별로 데이터를 조직화하는 데 사용됩니다.
+    """
+    id: Optional[str] = Field(None, description="데이터셋 고유 식별자")
+    name: Optional[str] = Field(None, description="데이터셋 이름")
+    description: Optional[str] = Field(None, description="데이터셋 설명")
 
-    created_at: Optional[str] = Field(None, alias="createdAt")
-    updated_at: Optional[str] = Field(None, alias="updatedAt")
-    created_by: Optional[str] = Field(None, alias="createdBy")
-    updated_by: Optional[str] = Field(None, alias="updatedBy")
+    created_at: Optional[str] = Field(None, alias="createdAt", description="생성일시 (ISO 8601)")
+    updated_at: Optional[str] = Field(None, alias="updatedAt", description="수정일시 (ISO 8601)")
+    created_by: Optional[str] = Field(None, alias="createdBy", description="생성자")
+    updated_by: Optional[str] = Field(None, alias="updatedBy", description="수정자")

spb_onprem/entities.py

@@ -7,7 +7,10 @@ from .data.entities import (
     DataMeta,
     DataSlice,
     Frame,
+    Comment,
+    Reply,
 )
+from .data.entities.comment import CommentStatus
 from .datasets.entities import Dataset
 from .slices.entities import Slice
 from .data.enums import (
@@ -47,6 +50,8 @@ __all__ = [
     "Frame",
     "PredictionSet",
     "Model",
+    "Comment",
+    "Reply",
 
     # Enums
     "DataType",
@@ -57,4 +62,5 @@ __all__ = [
     "ActivityStatus",
     "ActivitySchema",
     "SchemaType",
+    "CommentStatus",
 ] 

spb_onprem/exports/entities/export.py

@@ -5,23 +5,26 @@ from spb_onprem.data.params import DataListFilter
 
 class Export(CustomBaseModel):
     """
-    The export entity.
+    익스포트 엔터티
+    
+    데이터와 어노테이션을 외부 시스템에서 사용할 수 있는 형태로 
+    내보내기 작업을 정의합니다. 다양한 포맷(COCO, YOLO, Custom)을 지원합니다.
     """
-    id: str = Field(..., alias="id")
-    dataset_id: str = Field(..., alias="datasetId")
+    id: str = Field(..., alias="id", description="익스포트 고유 식별자")
+    dataset_id: str = Field(..., alias="datasetId", description="상위 데이터셋 ID")
     
-    name: Optional[str] = Field(None, alias="name")
-    data_filter: Optional[DataListFilter] = Field(None, alias="dataFilter")
-    location: Optional[str] = Field(None, alias="location")
+    name: Optional[str] = Field(None, alias="name", description="익스포트 작업 이름")
+    data_filter: Optional[DataListFilter] = Field(None, alias="dataFilter", description="내보낼 데이터 필터 조건")
+    location: Optional[str] = Field(None, alias="location", description="익스포트 파일 저장 위치")
     
-    data_count: Optional[int] = Field(None, alias="dataCount")
-    annotation_count: Optional[int] = Field(None, alias="annotationCount")
-    frame_count: Optional[int] = Field(None, alias="frameCount")
+    data_count: Optional[int] = Field(None, alias="dataCount", description="내보낸 데이터 개수")
+    annotation_count: Optional[int] = Field(None, alias="annotationCount", description="내보낸 어노테이션 개수")
+    frame_count: Optional[int] = Field(None, alias="frameCount", description="내보낸 프레임 개수")
     
-    meta: Optional[dict] = Field(None, alias="meta")
+    meta: Optional[dict] = Field(None, alias="meta", description="익스포트 메타데이터 (포맷, 옵션 등)")
     
-    created_at: Optional[str] = Field(None, alias="createdAt")
-    created_by: Optional[str] = Field(None, alias="createdBy")
-    updated_at: Optional[str] = Field(None, alias="updatedAt")
-    updated_by: Optional[str] = Field(None, alias="updatedBy")
-    completed_at: Optional[str] = Field(None, alias="completedAt") 
+    created_at: Optional[str] = Field(None, alias="createdAt", description="생성일시 (ISO 8601)")
+    created_by: Optional[str] = Field(None, alias="createdBy", description="생성자")
+    updated_at: Optional[str] = Field(None, alias="updatedAt", description="수정일시 (ISO 8601)")
+    updated_by: Optional[str] = Field(None, alias="updatedBy", description="수정자")
+    completed_at: Optional[str] = Field(None, alias="completedAt", description="완료일시 (ISO 8601)") 

spb_onprem/slices/entities/slice.py

@@ -4,14 +4,17 @@ from spb_onprem.base_model import CustomBaseModel, Field
 
 class Slice(CustomBaseModel):
     """
-    THE SLICE.
+    슬라이스 엔터티
+    
+    데이터셋 내에서 특정 조건으로 필터링된 데이터 그룹입니다.
+    프로젝트 단계별, 작업자별, 품질별로 데이터를 분류하고 관리하는 데 사용됩니다.
     """
-    id: Optional[str] = None
-    dataset_id: Optional[str] = Field(None, alias="datasetId")
-    name: Optional[str] = None
-    description: Optional[str] = None
-    is_pinned: Optional[bool] = Field(None, alias="isPinned")
-    created_at: Optional[str] = Field(None, alias="createdAt")
-    created_by: Optional[str] = Field(None, alias="createdBy")
-    updated_at: Optional[str] = Field(None, alias="updatedAt")
-    updated_by: Optional[str] = Field(None, alias="updatedBy")
+    id: Optional[str] = Field(None, description="슬라이스 고유 식별자")
+    dataset_id: Optional[str] = Field(None, alias="datasetId", description="상위 데이터셋 ID")
+    name: Optional[str] = Field(None, description="슬라이스 이름")
+    description: Optional[str] = Field(None, description="슬라이스 설명")
+    is_pinned: Optional[bool] = Field(None, alias="isPinned", description="즐겨찾기 고정 여부")
+    created_at: Optional[str] = Field(None, alias="createdAt", description="생성일시 (ISO 8601)")
+    created_by: Optional[str] = Field(None, alias="createdBy", description="생성자")
+    updated_at: Optional[str] = Field(None, alias="updatedAt", description="수정일시 (ISO 8601)")
+    updated_by: Optional[str] = Field(None, alias="updatedBy", description="수정자")