lightly-studio 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

lightly_studio/resolvers/caption_resolver.py

@@ -0,0 +1,80 @@
+"""Resolvers for caption."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from uuid import UUID
+
+from pydantic import BaseModel
+from sqlmodel import Session, col, func, select
+
+from lightly_studio.api.routes.api.validators import Paginated
+from lightly_studio.models.caption import CaptionCreate, CaptionTable
+
+
+class GetAllCaptionsResult(BaseModel):
+    """Result wrapper for caption listings."""
+
+    captions: Sequence[CaptionTable]
+    total_count: int
+    next_cursor: int | None = None
+
+
+def create_many(session: Session, captions: Sequence[CaptionCreate]) -> list[CaptionTable]:
+    """Create many captions in bulk.
+
+    Args:
+        session: Database session
+        captions: The captions to create
+
+    Returns:
+        The created captions
+    """
+    if not captions:
+        return []
+
+    db_captions = [CaptionTable.model_validate(caption) for caption in captions]
+    session.bulk_save_objects(db_captions)
+    session.commit()
+    return db_captions
+
+
+def get_all(
+    session: Session,
+    dataset_id: UUID,
+    pagination: Paginated | None = None,
+) -> GetAllCaptionsResult:
+    """Get all captions from the database.
+
+    Args:
+        session: Database session
+        dataset_id: dataset_id parameter to filter the query
+        pagination: Optional pagination parameters
+
+    Returns:
+        List of captions matching the filters, total number of captions, next cursor (pagination)
+    """
+    query = select(CaptionTable).order_by(
+        col(CaptionTable.created_at).asc(),
+        col(CaptionTable.caption_id).asc(),
+    )
+    count_query = select(func.count()).select_from(CaptionTable)
+
+    query = query.where(CaptionTable.dataset_id == dataset_id)
+    count_query = count_query.where(CaptionTable.dataset_id == dataset_id)
+
+    if pagination is not None:
+        query = query.offset(pagination.offset).limit(pagination.limit)
+
+    captions = session.exec(query).all()
+    total_count = session.exec(count_query).one()
+
+    next_cursor: int | None = None
+    if pagination and pagination.offset + pagination.limit < total_count:
+        next_cursor = pagination.offset + pagination.limit
+
+    return GetAllCaptionsResult(
+        captions=captions,
+        total_count=total_count,
+        next_cursor=next_cursor,
+    )

lightly_studio/resolvers/dataset_resolver.py

@@ -41,6 +41,9 @@ class ExportFilter(BaseModel):
 
 def create(session: Session, dataset: DatasetCreate) -> DatasetTable:
     """Create a new dataset in the database."""
+    existing = get_by_name(session=session, name=dataset.name)
+    if existing:
+        raise ValueError(f"Dataset with name '{dataset.name}' already exists.")
     db_dataset = DatasetTable.model_validate(dataset)
     session.add(db_dataset)
     session.commit()
@@ -69,12 +72,7 @@ def get_by_id(session: Session, dataset_id: UUID) -> DatasetTable | None:
 
 def get_by_name(session: Session, name: str) -> DatasetTable | None:
     """Retrieve a single dataset by name."""
-    datasets = session.exec(select(DatasetTable).where(DatasetTable.name == name)).all()
-    if len(datasets) == 0:
-        return None
-    if len(datasets) > 1:
-        raise ValueError(f"Cannot retrieve a dataset, found multiple with name '{name}'.")
-    return datasets[0]
+    return session.exec(select(DatasetTable).where(DatasetTable.name == name)).one_or_none()
 
 
 def update(session: Session, dataset_id: UUID, dataset_data: DatasetCreate) -> DatasetTable:
@@ -84,7 +82,6 @@ def update(session: Session, dataset_id: UUID, dataset_data: DatasetCreate) -> D
         raise ValueError(f"Dataset ID was not found '{dataset_id}'.")
 
     dataset.name = dataset_data.name
-    dataset.directory = dataset_data.directory
     dataset.updated_at = datetime.now(timezone.utc)
 
     session.commit()
@@ -232,10 +229,8 @@ def _build_export_query(  # noqa: C901
     raise ValueError("Invalid include or export filter combination.")
 
 
-# TODO: this fn should be moved to a "business logic" layer outside of the
-# resolvers and abstracted in to reusable components.
-# https://linear.app/lightly/issue/LIG-6196/figure-out-architecture-follow-up-changes-in-python-package
-# TODO: this should be abstracted to allow different export formats.
+# TODO(Michal, 10/2025): Consider moving the export logic to a separate service.
+# This is a legacy code from the initial implementation of the export feature.
 def export(
     session: Session,
     dataset_id: UUID,

lightly_studio/resolvers/metadata_resolver/__init__.py

@@ -1,14 +1,14 @@
 """Metadata resolver module."""
 
 from lightly_studio.resolvers.metadata_resolver.sample import (
-    bulk_set_metadata,
+    bulk_update_metadata,
     get_by_sample_id,
     get_value_for_sample,
     set_value_for_sample,
 )
 
 __all__ = [
-    "bulk_set_metadata",
+    "bulk_update_metadata",
     "get_by_sample_id",
     "get_value_for_sample",
     "set_value_for_sample",

lightly_studio/resolvers/metadata_resolver/sample/__init__.py

@@ -1,7 +1,7 @@
 """Resolvers for metadata operations."""
 
-from .bulk_set_metadata import (
-    bulk_set_metadata,
+from .bulk_update_metadata import (
+    bulk_update_metadata,
 )
 from .get_by_sample_id import (
     get_by_sample_id,
@@ -14,7 +14,7 @@ from .set_value_for_sample import (
 )
 
 __all__ = [
-    "bulk_set_metadata",
+    "bulk_update_metadata",
     "get_by_sample_id",
     "get_value_for_sample",
     "set_value_for_sample",

lightly_studio/resolvers/metadata_resolver/sample/bulk_update_metadata.py

@@ -0,0 +1,46 @@
+"""Resolver for operations for setting metadata."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from sqlmodel import Session, col, select
+
+from lightly_studio.models.metadata import SampleMetadataTable
+
+
+def bulk_update_metadata(
+    session: Session,
+    sample_metadata: list[tuple[UUID, dict[str, Any]]],
+) -> None:
+    """Bulk insert or update metadata for multiple samples.
+
+    If a sample does not have metadata, a new metadata row is created.
+    If a sample already has metadata, the new key-value pairs are merged with the existing metadata.
+
+    Args:
+        session: The database session.
+        sample_metadata: List of (sample_id, metadata_dict) tuples.
+    """
+    # TODO(Mihnea, 10/2025): Consider using SQLAlchemy's bulk operations
+    #  (Session.bulk_insert/update_mappings) if performance becomes a bottleneck.
+    if not sample_metadata:
+        return
+
+    # Get all existing metadata rows for the given sample IDs.
+    sample_ids = [s[0] for s in sample_metadata]
+    existing_metadata = session.exec(
+        select(SampleMetadataTable).where(col(SampleMetadataTable.sample_id).in_(sample_ids))
+    ).all()
+    sample_id_to_existing_metadata = {meta.sample_id: meta for meta in existing_metadata}
+
+    for sample_id, new_metadata in sample_metadata:
+        metadata = sample_id_to_existing_metadata.get(
+            sample_id, SampleMetadataTable(sample_id=sample_id)
+        )
+        for key, value in new_metadata.items():
+            metadata.set_value(key, value)
+        session.add(metadata)
+
+    session.commit()

lightly_studio/resolvers/sample_resolver.py

@@ -109,6 +109,7 @@ def get_all_by_dataset_id(  # noqa: PLR0913
                 joinedload(AnnotationBaseTable.instance_segmentation_details),
                 joinedload(AnnotationBaseTable.semantic_segmentation_details),
             ),
+            selectinload(SampleTable.captions),
             selectinload(SampleTable.tags),
             # Ignore type checker error below as it's a false positive caused by TYPE_CHECKING.
             joinedload(SampleTable.metadata_dict),  # type: ignore[arg-type]

lightly_studio/resolvers/samples_filter.py

@@ -33,20 +33,15 @@ class SampleFilter(BaseModel):
     annotation_label_ids: Optional[List[UUID]] = None
     tag_ids: Optional[List[UUID]] = None
     metadata_filters: Optional[List[MetadataFilter]] = None
+    sample_ids: Optional[List[UUID]] = None
 
     def apply(self, query: QueryType) -> QueryType:
         """Apply the filters to the given query."""
+        if self.sample_ids:
+            query = query.where(col(SampleTable.sample_id).in_(self.sample_ids))
+
         # Apply dimension-based filters to the query.
-        if self.width:
-            if self.width.min is not None:
-                query = query.where(SampleTable.width >= self.width.min)
-            if self.width.max is not None:
-                query = query.where(SampleTable.width <= self.width.max)
-        if self.height:
-            if self.height.min is not None:
-                query = query.where(SampleTable.height >= self.height.min)
-            if self.height.max is not None:
-                query = query.where(SampleTable.height <= self.height.max)
+        query = self._apply_dimension_filters(query)
 
         # Apply annotation label filters to the query.
         if self.annotation_label_ids:
@@ -79,3 +74,16 @@ class SampleFilter(BaseModel):
                 metadata_join_condition=SampleMetadataTable.sample_id == SampleTable.sample_id,
             )
         return query
+
+    def _apply_dimension_filters(self, query: QueryType) -> QueryType:
+        if self.width:
+            if self.width.min is not None:
+                query = query.where(SampleTable.width >= self.width.min)
+            if self.width.max is not None:
+                query = query.where(SampleTable.width <= self.width.max)
+        if self.height:
+            if self.height.min is not None:
+                query = query.where(SampleTable.height >= self.height.min)
+            if self.height.max is not None:
+                query = query.where(SampleTable.height <= self.height.max)
+        return query

lightly_studio/resolvers/settings_resolver.py

@@ -52,6 +52,9 @@ def set_settings(session: Session, settings: SettingView) -> SettingView:
     # Update show annotation text labels
     current_settings.show_annotation_text_labels = settings.show_annotation_text_labels
 
+    # Update sample filename visibility
+    current_settings.show_sample_filenames = settings.show_sample_filenames
+
     session.commit()
     session.refresh(current_settings)
 

lightly_studio/resolvers/twodim_embedding_resolver.py

@@ -0,0 +1,29 @@
+"""Handler for getting 2D embeddings from high-dimensional embeddings."""
+
+from __future__ import annotations
+
+from lightly_mundig import TwoDimEmbedding  # type: ignore[import-untyped]
+
+from lightly_studio.dataset.env import LIGHTLY_STUDIO_LICENSE_KEY
+
+
+# TODO(Malte, 10/2025): Add the get_twodim_embeddings function here that handles the
+# caching in the DB and calls _calculate_2d_embeddings when needed.
+def _calculate_2d_embeddings(embedding_values: list[list[float]]) -> list[tuple[float, float]]:
+    n_samples = len(embedding_values)
+    # For 0, 1 or 2 samples we hard-code deterministic coordinates.
+    if n_samples == 0:
+        return []
+    if n_samples == 1:
+        return [(0.0, 0.0)]
+    if n_samples == 2:  # noqa: PLR2004
+        return [(0.0, 0.0), (1.0, 1.0)]
+
+    license_key = LIGHTLY_STUDIO_LICENSE_KEY
+    if license_key is None:
+        raise ValueError(
+            "LIGHTLY_STUDIO_LICENSE_KEY environment variable is not set. "
+            "Please set it to your LightlyStudio license key."
+        )
+    embedding_calculator = TwoDimEmbedding(embedding_values, license_key)
+    return embedding_calculator.calculate_2d_embedding()  # type: ignore[no-any-return]

lightly_studio/selection/__init__.py

@@ -0,0 +1 @@
+"""Selection package."""

lightly_studio/selection/mundig.py

@@ -81,6 +81,47 @@ class Mundig:
         self._check_consistent_input_size(weights_ndarray.shape[0])
         self.mundig.add_weighting_strategy(weights=weights_ndarray, strength=strength)
 
+    def add_class_balancing(
+        self,
+        class_distributions: Iterable[Iterable[float]],
+        target: Iterable[float],
+        strength: float = 1.0,
+    ) -> None:
+        """Add a class balancing strategy.
+
+        This strategy aims to select a subset of samples such that the
+        distribution of classes in the subset is close to the target
+        distribution.
+
+        Args:
+            class_distributions:
+                First dimension is over all samples, second one is the distribution per sample over
+                the classes.
+            target:
+                The desired target distribution for the classes in the selected subset of samples.
+                The length of the target must match the number of classes in the class
+                distributions.
+            strength:
+                The strength of the balancing strategy.
+        """
+        # Convert to ndarray with float32 dtype if not already
+        if isinstance(class_distributions, np.ndarray) and class_distributions.dtype == np.float32:
+            class_distributions_nparray = class_distributions
+        else:
+            class_distributions_nparray = np.array(class_distributions, dtype=np.float32)
+        self._check_consistent_input_size(class_distributions_nparray.shape[0])
+        target_nparray = np.array(target, dtype=np.float32)
+        if class_distributions_nparray.shape[1] != target_nparray.shape[0]:
+            raise ValueError(
+                f"The length of 'target' {target_nparray.shape[0]} doesn't match the width of "
+                f"'class_distributions': {class_distributions_nparray.shape[0]}"
+            )
+        self.mundig.add_balancing_strategy(
+            class_distributions=class_distributions_nparray,
+            target=target_nparray,
+            strength=strength,
+        )
+
     def _check_consistent_input_size(self, n_input_samples_strategy: int) -> None:
         """Assert that input samples count is consistent across strategies.
 

lightly_studio/type_definitions.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 from typing import TypeVar, Union
+from uuid import UUID
 
 from sqlmodel.sql.expression import SelectOfScalar
 
@@ -14,6 +15,7 @@ QueryType = TypeVar(
     SelectOfScalar[AnnotationBaseTable],
     SelectOfScalar[SampleTable],
     SelectOfScalar[int],
+    SelectOfScalar[UUID],
 )
 
 PathLike = Union[str, Path]

lightly_studio-0.4.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: lightly-studio
+Version: 0.4.0
+Summary: LightlyStudio is a lightweight, fast, and easy-to-use data exploration tool for data scientists and engineers.
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.8
+Requires-Dist: annotated-types==0.7.0
+Requires-Dist: duckdb-engine<0.17,>=0.15.0
+Requires-Dist: duckdb<1.3,>=1.2.2
+Requires-Dist: environs<12.0.0
+Requires-Dist: eval-type-backport>=0.2.2
+Requires-Dist: fastapi>=0.115.5
+Requires-Dist: faster-coco-eval>=1.6.5
+Requires-Dist: fsspec>=2023.1.0
+Requires-Dist: labelformat>=0.1.7
+Requires-Dist: lightly-mundig==0.1.7
+Requires-Dist: open-clip-torch>=2.20.0
+Requires-Dist: pyarrow>=17.0.0
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: scikit-learn==1.3.2
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: typing-extensions>=4.12.2
+Requires-Dist: uvicorn>=0.32.1
+Requires-Dist: xxhash>=3.5.0
+Provides-Extra: cloud-storage
+Requires-Dist: adlfs>=2023.1.0; extra == 'cloud-storage'
+Requires-Dist: gcsfs>=2023.1.0; extra == 'cloud-storage'
+Requires-Dist: s3fs>=2023.1.0; extra == 'cloud-storage'
+Provides-Extra: lightly-edge
+Requires-Dist: lightly-edge-sdk>=1.0.1b2; extra == 'lightly-edge'
+Requires-Dist: opencv-python; extra == 'lightly-edge'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://lightly.ai/lightly-studio"> 
+    <img src="https://cdn.prod.website-files.com/62cd5ce03261cba217188442/66dac501a8e9a90495970876_Logo%20dark-short-p-800.png" height="50" alt="LightlyStudio logo" />
+  </a>
+</p>
+<p align="center"><strong>Curate, Annotate, and Manage Your Data in LightlyStudio.</strong></p>
+<p align="center">
+  <a href="https://pypi.org/project/lightly-studio">
+    <img src="https://img.shields.io/pypi/pyversions/lightly-studio" alt="PyPI python" />
+  </a>
+  <a href="https://pypi.org/project/lightly-studio">
+    <img src="https://badge.fury.io/py/lightly-studio.svg" alt="PyPI version" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License" />
+  </a>
+  <a href="https://docs.lightly.ai/studio">
+    <img src="https://img.shields.io/badge/Docs-blue" alt="Docs" />
+  </a>
+</p>
+
+---
+
+# Welcome to LightlyStudio!
+
+We at **[Lightly](https://lightly.ai)** created **[LightlyStudio](https://www.lightly.ai/lightly-studio)**, an open-source tool designed to unify your data workflows from curation, annotation and management in a single tool. Since we're big fans of Rust we used it to speed things up. You can work with COCO and ImageNet on a Macbook Pro with M1 and 16GB of memory!
+
+Explore [LightlyStudio on GitHub](https://github.com/lightly-ai/lightly-studio).
+
+Learn more in our [documentation](https://docs.lightly.ai/studio).
+
+<p align="center">
+  <img alt="LightlyStudio Overview" src="https://storage.googleapis.com/lightly-public/studio/studio_overview.gif" width="70%">
+  <br/>
+  <em>Curate, Annotate, and Manage Your Data in LightlyStudio.</em>
+</p>