lightly-studio 0.3.4__tar.gz → 0.4.1__tar.gz

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/.gitignore

@@ -16,3 +16,6 @@ datasets
 
 # Generated API schema
 openapi.json
+
+# docs build
+/docs/site

lightly_studio-0.4.1/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: lightly-studio
+Version: 0.4.1
+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>

lightly_studio-0.4.1/USAGE.md

@@ -0,0 +1,36 @@
+<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>

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lightly-studio"
-version = "0.3.4"
+version = "0.4.1"
 description = "LightlyStudio is a lightweight, fast, and easy-to-use data exploration tool for data scientists and engineers."
 readme = "USAGE.md"
 requires-python = ">=3.8,<3.13"
@@ -44,7 +44,7 @@ dependencies = [
     #   lightly-mundig==$version
     # Then lock the version. The uv.lock file is updated accordingly.
     # uv lock --upgrade-package lightly-mundig==$version
-    "lightly-mundig==0.1.4",
+    "lightly-mundig==0.1.7",
     "pyarrow>=17.0.0",
 ]
 
@@ -75,6 +75,15 @@ dev = [
     "pytest-xdist>=3.6.1",
 ]
 
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.4.0",
+    "mkdocs-git-revision-date-localized-plugin>=1.2.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mkdocstrings-python>=1.8.0",
+    "pymdown-extensions>=10.0.0",
+]
+
 
 [tool.mypy]
 strict = true
@@ -132,3 +141,8 @@ explicit = true
 artifacts = [
     "src/lightly_studio/**/*",
 ]
+
+[tool.ruff]
+extend-exclude = [
+    "docs",
+]

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/__init__.py

@@ -5,7 +5,6 @@ from lightly_studio.core.dataset import Dataset
 from lightly_studio.core.start_gui import start_gui
 
 # TODO (Jonas 08/25): This will be removed as soon as the new interface is used in the examples
-from lightly_studio.dataset.loader import DatasetLoader
 from lightly_studio.models.annotation.annotation_base import AnnotationType
 
-__all__ = ["AnnotationType", "Dataset", "DatasetLoader", "start_gui"]
+__all__ = ["AnnotationType", "Dataset", "start_gui"]

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/api/db_tables.py

@@ -27,3 +27,6 @@ from lightly_studio.models.settings import (
 from lightly_studio.models.tag import (
     TagTable,  # noqa: F401, required for SQLModel to work properly
 )
+from lightly_studio.models.two_dim_embedding import (
+    TwoDimEmbeddingTable,  # noqa: F401, required for SQLModel to work properly
+)

lightly_studio-0.4.1/src/lightly_studio/api/features.py

@@ -0,0 +1,5 @@
+"""Global list of the active features."""
+
+from __future__ import annotations
+
+lightly_studio_active_features: list[str] = []

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/api/routes/api/dataset.py

@@ -19,6 +19,7 @@ from lightly_studio.models.dataset import (
     DatasetCreate,
     DatasetTable,
     DatasetView,
+    DatasetViewWithCount,
 )
 from lightly_studio.resolvers import dataset_resolver
 from lightly_studio.resolvers.dataset_resolver import (
@@ -64,16 +65,17 @@ def read_datasets(
     return dataset_resolver.get_all(session=session, offset=paginated.offset, limit=paginated.limit)
 
 
-@dataset_router.get("/datasets/{dataset_id}")
+@dataset_router.get("/datasets/{dataset_id}", response_model=DatasetViewWithCount)
 def read_dataset(
+    session: SessionDep,
     dataset: Annotated[
         DatasetTable,
         Path(title="Dataset Id"),
         Depends(get_and_validate_dataset_id),
     ],
-) -> DatasetTable:
+) -> DatasetViewWithCount:
     """Retrieve a single dataset from the database."""
-    return dataset
+    return dataset_resolver.get_dataset_details(session=session, dataset=dataset)
 
 
 @dataset_router.put("/datasets/{dataset_id}")

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/api/routes/api/dataset_tag.py

@@ -164,6 +164,11 @@ class SampleIdsBody(BaseModel):
 )
 def add_sample_ids_to_tag_id(
     session: SessionDep,
+    # dataset_id is needed for the generator
+    dataset_id: Annotated[  # noqa: ARG001
+        UUID,
+        Path(title="Dataset Id", description="The ID of the dataset"),
+    ],
     tag_id: UUID,
     body: SampleIdsBody,
 ) -> bool:
@@ -215,6 +220,11 @@ class AnnotationIdsBody(BaseModel):
 )
 def add_annotation_ids_to_tag_id(
     session: SessionDep,
+    # dataset_id is needed for the generator
+    dataset_id: Annotated[  # noqa: ARG001
+        UUID,
+        Path(title="Dataset Id", description="The ID of the dataset"),
+    ],
     tag_id: UUID,
     body: AnnotationIdsBody,
 ) -> bool:

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/api/routes/api/embeddings2d.py

@@ -5,19 +5,16 @@ from __future__ import annotations
 import io
 from uuid import UUID
 
-import numpy as np
 import pyarrow as pa
 from fastapi import APIRouter, HTTPException, Response
-from numpy.typing import NDArray
 from pyarrow import ipc
 from pydantic import BaseModel, Field
-from sklearn.manifold import TSNE
 from sqlmodel import select
 
 from lightly_studio.db_manager import SessionDep
 from lightly_studio.models.dataset import DatasetTable
 from lightly_studio.models.embedding_model import EmbeddingModelTable
-from lightly_studio.resolvers import sample_embedding_resolver, sample_resolver
+from lightly_studio.resolvers import sample_resolver, twodim_embedding_resolver
 from lightly_studio.resolvers.samples_filter import SampleFilter
 
 embeddings2d_router = APIRouter()
@@ -32,8 +29,8 @@ class GetEmbeddings2DRequest(BaseModel):
     )
 
 
-@embeddings2d_router.post("/embeddings2d/tsne")
-def get_embeddings2d__tsne(
+@embeddings2d_router.post("/embeddings2d/default")
+def get_2d_embeddings(
     session: SessionDep,
     body: GetEmbeddings2DRequest | None = None,
 ) -> Response:
@@ -52,17 +49,12 @@ def get_embeddings2d__tsne(
     if embedding_model is None:
         raise HTTPException(status_code=404, detail="No embedding model configured.")
 
-    embeddings = sample_embedding_resolver.get_all_by_dataset_id(
+    x_array, y_array, sample_ids = twodim_embedding_resolver.get_twodim_embeddings(
         session=session,
         dataset_id=dataset.dataset_id,
         embedding_model_id=embedding_model.embedding_model_id,
     )
 
-    embedding_values = np.asarray([e.embedding for e in embeddings], dtype=np.float32)
-    embedding_values_tsne = _calculate_tsne_embeddings(embedding_values)
-    x = embedding_values_tsne[:, 0]
-    y = embedding_values_tsne[:, 1]
-
     matching_sample_ids: set[UUID] | None = None
     filters = body.filters if body else None
     if filters:
@@ -73,20 +65,15 @@ def get_embeddings2d__tsne(
         )
         matching_sample_ids = {sample.sample_id for sample in matching_samples_result.samples}
 
-    sample_ids = [embedding.sample_id for embedding in embeddings]
     if matching_sample_ids is None:
         fulfils_filter = [1] * len(sample_ids)
     else:
         fulfils_filter = [1 if sample_id in matching_sample_ids else 0 for sample_id in sample_ids]
 
-    # TODO(Malte, 09/2025): Save the 2D-embeddings in the database to avoid recomputing
-    # them on every request.
-
-    # TODO(Malte, 09/2025): Include a sample identifier in the returned payload.
     table = pa.table(
         {
-            "x": pa.array(x, type=pa.float32()),
-            "y": pa.array(y, type=pa.float32()),
+            "x": pa.array(x_array, type=pa.float32()),
+            "y": pa.array(y_array, type=pa.float32()),
             "fulfils_filter": pa.array(fulfils_filter, type=pa.uint8()),
             "sample_id": pa.array([str(sample_id) for sample_id in sample_ids], type=pa.string()),
         }
@@ -106,31 +93,3 @@ def get_embeddings2d__tsne(
             "X-Content-Type-Options": "nosniff",
         },
     )
-
-
-def _calculate_tsne_embeddings(embedding_values: NDArray[np.float32]) -> NDArray[np.float32]:
-    # TODO(Malte, 10/2025): Switch to a better and faster projection method than
-    # scikit-learn's TSNE.
-    # See https://linear.app/lightly/issue/LIG-7678/embedding-plot-investigate-fasterandbetter-2d-computation-options
-    n_samples = embedding_values.shape[0]
-    # For 0, 1 or 2 samples we hard-code deterministic coordinates.
-    if n_samples == 0:
-        return np.zeros((0, 2), dtype=np.float32)
-    if n_samples == 1:
-        return np.asarray([[0.0, 0.0]], dtype=np.float32)
-    if n_samples == 2:  # noqa: PLR2004
-        return np.asarray([[0.0, 0.0], [1.0, 1.0]], dtype=np.float32)
-
-    # Copied from lightly-core:
-    # https://github.com/lightly-ai/lightly-core/blob/b738952516e916eba42fdd28498491ff18df5c1e/appv2/packages/queueworker/src/jobs/embeddings2d/function-source/main.py#L179-L186
-    embeddings_2d: NDArray[np.float32] = TSNE(
-        init="pca",  # changed in https://github.com/scikit-learn/scikit-learn/issues/18018
-        learning_rate="auto",  # changed in https://github.com/scikit-learn/scikit-learn/issues/18018
-        n_components=2,
-        # Perplexity must be _less_ than the number of entries. 30 is the default value.
-        # https://scikit-learn.org/stable/modules/generated/sklearn.manifold.TSNE.html
-        perplexity=min(30.0, float(n_samples - 1)),
-        # Make the computation deterministic.
-        random_state=0,
-    ).fit_transform(embedding_values)
-    return embeddings_2d

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/core/dataset.py

@@ -38,6 +38,7 @@ from lightly_studio.models.sample import SampleTable
 from lightly_studio.resolvers import (
     dataset_resolver,
     embedding_model_resolver,
+    sample_embedding_resolver,
     sample_resolver,
     tag_resolver,
 )
@@ -53,7 +54,40 @@ _SliceType = slice  # to avoid shadowing built-in slice in type annotations
 class Dataset:
     """A LightlyStudio Dataset.
 
-    Keeps a reference to the underlying DatasetTable.
+    It can be created or loaded using one of the static methods:
+    ```python
+    dataset = Dataset.create()
+    dataset = Dataset.load()
+    dataset = Dataset.load_or_create()
+    ```
+
+    Samples can be added to the dataset using various methods:
+    ```python
+    dataset.add_samples_from_path(...)
+    dataset.add_samples_from_yolo(...)
+    dataset.add_samples_from_coco(...)
+    dataset.add_samples_from_coco_caption(...)
+    dataset.add_samples_from_labelformat(...)
+    ```
+
+    The dataset samples can be queried directly by iterating over it or slicing it:
+    ```python
+    dataset = Dataset.load("my_dataset")
+    first_ten_samples = dataset[:10]
+    for sample in dataset:
+        print(sample.file_name)
+        sample.metadata["new_key"] = "new_value"
+    ```
+
+    For filtering or ordering samples first, use the query interface:
+    ```python
+    from lightly_studio.core.dataset_query.sample_field import SampleField
+
+    dataset = Dataset.load("my_dataset")
+    query = dataset.match(SampleField.width > 10).order_by(SampleField.file_name)
+    for sample in query:
+        ...
+    ```
     """
 
     def __init__(self, dataset: DatasetTable) -> None:
@@ -84,7 +118,10 @@ class Dataset:
         dataset = dataset_resolver.get_by_name(session=db_manager.persistent_session(), name=name)
         if dataset is None:
             raise ValueError(f"Dataset with name '{name}' not found.")
-
+        # If we have embeddings in the database enable the FSC and embedding search features.
+        _enable_embedding_features_if_available(
+            session=db_manager.persistent_session(), dataset_id=dataset.dataset_id
+        )
         return Dataset(dataset=dataset)
 
     @staticmethod
@@ -97,6 +134,10 @@ class Dataset:
         if dataset is None:
             return Dataset.create(name=name)
 
+        # If we have embeddings in the database enable the FSC and embedding search features.
+        _enable_embedding_features_if_available(
+            session=db_manager.persistent_session(), dataset_id=dataset.dataset_id
+        )
         return Dataset(dataset=dataset)
 
     def __iter__(self) -> Iterator[Sample]:
@@ -500,6 +541,9 @@ def _generate_embeddings(session: Session, dataset_id: UUID, sample_ids: list[UU
     # Mark the embedding search feature as enabled.
     if "embeddingSearchEnabled" not in features.lightly_studio_active_features:
         features.lightly_studio_active_features.append("embeddingSearchEnabled")
+    # Mark the FSC feature as enabled.
+    if "fewShotClassifierEnabled" not in features.lightly_studio_active_features:
+        features.lightly_studio_active_features.append("fewShotClassifierEnabled")
 
 
 def _resolve_yolo_splits(data_yaml: Path, input_split: str | None) -> list[str]:
@@ -520,3 +564,46 @@ def _resolve_yolo_splits(data_yaml: Path, input_split: str | None) -> list[str]:
     if not splits:
         raise ValueError(f"No splits found in config file '{data_yaml}'")
     return splits
+
+
+def _are_embeddings_available(session: Session, dataset_id: UUID) -> bool:
+    """Check if there are any embeddings available for the given dataset.
+
+    Args:
+        session: Database session for resolver operations.
+        dataset_id: The ID of the dataset to check for embeddings.
+
+    Returns:
+        True if embeddings exist for the dataset, False otherwise.
+    """
+    embedding_manager = EmbeddingManagerProvider.get_embedding_manager()
+    model_id = embedding_manager.load_or_get_default_model(
+        session=session,
+        dataset_id=dataset_id,
+    )
+    if model_id is None:
+        # No default embedding model loaded for this dataset.
+        return False
+
+    return (
+        len(
+            sample_embedding_resolver.get_all_by_dataset_id(
+                session=session, dataset_id=dataset_id, embedding_model_id=model_id
+            )
+        )
+        > 0
+    )
+
+
+def _enable_embedding_features_if_available(session: Session, dataset_id: UUID) -> None:
+    """Enable embedding-related features if embeddings are available in the DB.
+
+    Args:
+        session: Database session for resolver operations.
+        dataset_id: The ID of the dataset to check for embeddings.
+    """
+    if _are_embeddings_available(session=session, dataset_id=dataset_id):
+        if "embeddingSearchEnabled" not in features.lightly_studio_active_features:
+            features.lightly_studio_active_features.append("embeddingSearchEnabled")
+        if "fewShotClassifierEnabled" not in features.lightly_studio_active_features:
+            features.lightly_studio_active_features.append("fewShotClassifierEnabled")

lightly_studio-0.4.1/src/lightly_studio/core/dataset_query/__init__.py

@@ -0,0 +1,14 @@
+from .boolean_expression import AND, NOT, OR
+from .dataset_query import DatasetQuery
+from .order_by import OrderByExpression, OrderByField
+from .sample_field import SampleField
+
+__all__ = [
+    "AND",
+    "NOT",
+    "OR",
+    "DatasetQuery",
+    "OrderByExpression",
+    "OrderByField",
+    "SampleField",
+]

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/core/dataset_query/dataset_query.py

@@ -1,4 +1,4 @@
-"""Matching functionality for filtering database samples based on field conditions."""
+"""Dataset query utilities for filtering, ordering, and slicing samples."""
 
 from __future__ import annotations
 
@@ -20,7 +20,103 @@ _SliceType = slice  # to avoid shadowing built-in slice in type annotations
 
 
 class DatasetQuery:
-    """Class for executing querying on a dataset."""
+    """Class for executing a query on a dataset.
+
+    # Filtering, ordering, and slicing samples in a dataset
+    Allows filtering, ordering, and slicing of samples in a dataset.
+    This class can be accessed via calling `.query()` on a Dataset instance.
+    ```python
+    dataset : Dataset = ...
+    query = dataset.query()
+    ```
+    The `match()`, `order_by()`, and `slice()` methods can be chained in this order.
+    You can also access the methods directly on the Dataset instance:
+    ```python
+    dataset.match(...) # shorthand for dataset.query().match(...)
+    ```
+
+    The object is converted to a SQL query that is lazily evaluated when iterating over
+    it or converting it to a list.
+
+    ## match() - Filtering samples
+    Filtering is done via the `match()` method.
+    ```python
+    from lightly_studio.core.dataset_query import SampleField
+
+    query_1 = dataset.query().match(SampleField.width > 100)
+    query_2 = dataset.query().match(SampleField.tags.contains('cat'))
+    ```
+    AND and OR operators are available for combining multiple conditions.
+    ```python
+    from lightly_studio.core.dataset_query import SampleField, AND, OR
+
+    query = dataset.query().match(
+        AND(
+            SampleField.height < 200,
+            OR(
+                SampleField.file_name == 'image.png',
+                SampleField.file_name == 'image2.png',
+            )
+        )
+    )
+    ```
+
+    ## order_by() - Ordering samples
+    The results can be ordered by using `order_by()`. For tie-breaking, multiple fields
+    can be provided. The first field has the highest priority. The default is
+    ascending order. To order in descending order, use `OrderByField(...).desc()`.
+    ```python
+    from lightly_studio.core.dataset_query import OrderByField, SampleField
+    query = query.order_by(
+        OrderByField(SampleField.width),
+        OrderByField(SampleField.file_name).desc()
+    )
+    ```
+
+    ## slice() - Slicing samples
+    Slicing can be applied via `slice()` or bracket notation.
+    ```python
+    query = query.slice(offset=10, limit=20)
+    query = query[10:30]  # equivalent to slice(offset=10, limit=20)
+    ```
+
+    # Usage of the filtered, ordered and sliced query
+
+    ## Iterating and converting to list
+    Finally, the query can be executed by iterating over it or converting to a list.
+    ```python
+    for sample in query:
+        print(sample.file_name)
+    samples = query.to_list()
+    ```
+    The samples returned are instances of the `Sample` class. They are writable, and
+    changes to them will be persisted to the database.
+
+    ## Adding tags to matching samples
+    The filtered set can also be used to add a tag to all matching samples.
+    ```python
+    query.add_tag('my_tag')
+    ```
+
+    ## Selecting a subset of samples using smart selection
+    A Selection interface can be created from the current query results. It will only
+    select the samples matching the current query at the time of calling selection().
+    ```python
+    # Choosing 100 diverse samples from the 'cat' tag.
+    # Save them under the tag name "diverse_cats".
+    selection = dataset.query().match(
+        SampleField.tags.contains('cat')
+    ).selection()
+    selection.diverse(100, "diverse_cats")
+    ```
+
+    ## Exporting the query results
+    An export interface can be created from the current query results.
+    ```python
+    export = dataset.query().match(...).export()
+    export.to_coco_object_detections('/path/to/coco.json')
+    ```
+    """
 
     def __init__(self, dataset: DatasetTable, session: Session) -> None:
         """Initialize with dataset and database session.

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/core/dataset_query/sample_field.py

@@ -16,8 +16,17 @@ from lightly_studio.models.sample import SampleTable
 class SampleField:
     """Providing access to predefined sample fields for queries.
 
-    This class provides static instances of different field types that can be
-    used to build database queries on sample properties.
+    It is used for the `query.match(...)` and `query.order_by(...)` methods of the
+    `DatasetQuery` class.
+
+    ```python
+    from lightly_studio.core.dataset_query import DatasetQuery, SampleField, OrderByField
+
+    query = dataset.query()
+    query.match(SampleField.tags.contains("cat"))
+    query.order_by(OrderByField(SampleField.file_path_abs))
+    samples = query.to_list()
+    ```
     """
 
     file_name = StringField(col(SampleTable.file_name))

{lightly_studio-0.3.4 → lightly_studio-0.4.1}/src/lightly_studio/core/sample.py

@@ -50,7 +50,39 @@ class DBField(Generic[T]):
 
 
 class Sample:
-    """Interface to a dataset sample."""
+    """Interface to a dataset sample.
+
+    It is usually returned by a query to the dataset.
+    ```python
+    for sample in dataset:
+        ...
+    ```
+
+    Many properties of the sample are directly accessible as attributes of this class.
+    ```python
+    print(f"Sample file name: {sample.file_name}")
+    print(f"Sample file path: {sample.file_path_abs}")
+    print(f"Sample width: {sample.width}")
+    print(f"Sample height: {sample.height}")
+    ```
+    Note that some attributes like the `sample_id` are technically writable, but changing
+    them is not recommended and may lead to inconsistent states.
+
+    Access sample's metadata via the `metadata` property, which
+    provides a dictionary-like interface to get and set metadata key-value pairs.
+    ```python
+    some_value = sample.metadata["some_key"]
+    sample.metadata["another_key"] = "new_value"
+    ```
+
+    Access sample's tags via the `tags` property.
+    ```python
+    sample.tags = ["tag1", "tag2"]  # Replace all tags
+    print(f"Current tags: {sample.tags}")
+    sample.add_tag("tag_3")
+    sample.remove_tag("tag_1")
+    ```
+    """
 
     file_name = DBField(col(SampleTable.file_name))
     width = DBField(col(SampleTable.width))