lightly-studio 0.4.6__py3-none-any.whl

lightly_studio/api/routes/api/operator.py

@@ -0,0 +1,75 @@
+"""API routes for operators."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from lightly_studio.api.routes.api.status import HTTP_STATUS_NOT_FOUND
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.plugins.base_operator import OperatorResult
+from lightly_studio.plugins.operator_registry import RegisteredOperatorMetadata, operator_registry
+from lightly_studio.plugins.parameter import BaseParameter
+
+operator_router = APIRouter(prefix="/operators", tags=["operators"])
+
+
+class ExecuteOperatorRequest(BaseModel):
+    """Request model for executing an operator."""
+
+    parameters: dict[str, Any]
+
+
+@operator_router.get("")
+def get_operators() -> list[RegisteredOperatorMetadata]:
+    """Get all registered operators (id, name)."""
+    return operator_registry.get_all_metadata()
+
+
+@operator_router.get("/{operator_id}/parameters")
+def get_operator_parameters(operator_id: str) -> list[BaseParameter]:
+    """Get the parameters for a registered operator."""
+    operator = operator_registry.get_by_id(operator_id=operator_id)
+    if operator is None:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Operator '{operator_id}' not found",
+        )
+    return operator.parameters
+
+
+@operator_router.post("/datasets/{dataset_id}/{operator_id}/execute", response_model=OperatorResult)
+def execute_operator(
+    operator_id: str,
+    dataset_id: UUID,
+    request: ExecuteOperatorRequest,
+    session: SessionDep,
+) -> OperatorResult:
+    """Execute an operator with the provided parameters.
+
+    Args:
+        operator_id: The ID of the operator to execute.
+        dataset_id: The ID of the dataset to operate on.
+        request: The execution request containing parameters.
+        session: Database session.
+
+    Returns:
+        The execution result.
+    """
+    # Get the operator
+    operator = operator_registry.get_by_id(operator_id=operator_id)
+    if operator is None:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Operator '{operator_id}' not found",
+        )
+
+    # Execute the operator
+    return operator.execute(
+        session=session,
+        dataset_id=dataset_id,
+        parameters=request.parameters,
+    )

lightly_studio/api/routes/api/sample.py

@@ -0,0 +1,103 @@
+"""This module contains the API routes for managing samples."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_CREATED,
+    HTTP_STATUS_NOT_FOUND,
+)
+from lightly_studio.api.routes.api.validators import Paginated, PaginatedWithCursor
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.sample import SampleViewsWithCount
+from lightly_studio.resolvers import (
+    sample_resolver,
+    tag_resolver,
+)
+from lightly_studio.resolvers.sample_resolver.get_filtered_samples import SamplesWithCount
+from lightly_studio.resolvers.sample_resolver.sample_filter import SampleFilter
+
+sample_router = APIRouter(tags=["sample"])
+
+
+class ReadSamplesRequest(BaseModel):
+    """Request body for reading samples."""
+
+    filters: SampleFilter = Field(description="Filter parameters for samples")
+
+
+@sample_router.post("/samples/list", response_model=SampleViewsWithCount)
+def read_samples(
+    session: SessionDep,
+    body: ReadSamplesRequest,
+    pagination: Annotated[PaginatedWithCursor, Depends()],
+) -> SamplesWithCount:
+    """Retrieve a list of samples from the database with optional filtering.
+
+    Args:
+        session: The database session.
+        body: Optional request body containing filters.
+        pagination: Pagination parameters (cursor and limit).
+
+    Returns:
+        A list of filtered samples.
+    """
+    if body.filters.dataset_id is None:
+        raise ValueError("Dataset ID must be provided in filters.")
+    return sample_resolver.get_filtered_samples(
+        session=session,
+        filters=body.filters,
+        pagination=Paginated(offset=pagination.offset, limit=pagination.limit),
+    )
+
+
+@sample_router.post(
+    "/datasets/{dataset_id}/samples/{sample_id}/tag/{tag_id}",
+    status_code=HTTP_STATUS_CREATED,
+)
+def add_tag_to_sample(
+    session: SessionDep,
+    sample_id: UUID,
+    # TODO(Michal, 10/2025): Remove unused dataset_id.
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],  # noqa: ARG001
+    tag_id: UUID,
+) -> bool:
+    """Add sample to a tag."""
+    sample = sample_resolver.get_by_id(session=session, sample_id=sample_id)
+    if not sample:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Sample {sample_id} not found",
+        )
+
+    if not tag_resolver.add_tag_to_sample(session=session, tag_id=tag_id, sample=sample):
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail=f"Tag {tag_id} not found")
+
+    return True
+
+
+@sample_router.delete("/datasets/{dataset_id}/samples/{sample_id}/tag/{tag_id}")
+def remove_tag_from_sample(
+    session: SessionDep,
+    tag_id: UUID,
+    # TODO(Michal, 10/2025): Remove unused dataset_id.
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],  # noqa: ARG001
+    sample_id: UUID,
+) -> bool:
+    """Remove sample from a tag."""
+    sample = sample_resolver.get_by_id(session=session, sample_id=sample_id)
+    if not sample:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Sample {sample_id} not found",
+        )
+
+    if not tag_resolver.remove_tag_from_sample(session=session, tag_id=tag_id, sample=sample):
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail=f"Tag {tag_id} not found")
+
+    return True

lightly_studio/api/routes/api/selection.py

@@ -0,0 +1,87 @@
+"""This module contains the API routes for managing selections."""
+
+from __future__ import annotations
+
+from typing import Union
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api.dataset import get_and_validate_dataset_id
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.dataset import DatasetTable
+from lightly_studio.resolvers import image_resolver
+from lightly_studio.selection.select_via_db import select_via_database
+from lightly_studio.selection.selection_config import (
+    EmbeddingDiversityStrategy,
+    MetadataWeightingStrategy,
+    SelectionConfig,
+)
+
+selection_router = APIRouter()
+
+Strategy = Annotated[
+    Union[EmbeddingDiversityStrategy, MetadataWeightingStrategy],
+    Field(discriminator="strategy_name"),
+]
+
+
+class SelectionRequest(BaseModel):
+    """Request model for selection."""
+
+    n_samples_to_select: int = Field(gt=0, description="Number of samples to select")
+    selection_result_tag_name: str = Field(min_length=1, description="Name for the result tag")
+    strategies: list[Strategy]
+
+
+@selection_router.post(
+    "/datasets/{dataset_id}/selection",
+    status_code=204,
+    response_model=None,
+)
+def create_combination_selection(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Depends(get_and_validate_dataset_id),
+    ],
+    request: SelectionRequest,
+) -> None:
+    """Create a combination selection on the dataset.
+
+    This endpoint performs combination selection using embeddings and metadata.
+    The selected samples are tagged with the specified tag name.
+
+    Args:
+        session: Database session dependency.
+        dataset: Dataset to perform selection on.
+        request: Selection parameters including sample count and tag name.
+
+    Returns:
+        None (204 No Content on success).
+
+    Raises:
+        HTTPException: 400 if selection fails due to invalid parameters or other errors.
+    """
+    # Get all samples in dataset as input for selection.
+    all_samples_result = image_resolver.get_all_by_dataset_id(
+        session=session, dataset_id=dataset.dataset_id
+    )
+    input_sample_ids = [sample.sample_id for sample in all_samples_result.samples]
+    # Validate we have enough samples to select from.
+    if len(input_sample_ids) < request.n_samples_to_select:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Dataset has only {len(input_sample_ids)} samples, "
+            f"cannot select {request.n_samples_to_select}",
+        )
+    # Create SelectionConfig with diversity strategy.
+    config = SelectionConfig(
+        dataset_id=dataset.dataset_id,
+        n_samples_to_select=request.n_samples_to_select,
+        selection_result_tag_name=request.selection_result_tag_name,
+        strategies=request.strategies,
+    )
+    # Perform selection via database.
+    select_via_database(session=session, config=config, input_sample_ids=input_sample_ids)

lightly_studio/api/routes/api/settings.py

@@ -0,0 +1,41 @@
+"""This module contains the API routes for user settings."""
+
+from fastapi import APIRouter
+
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.settings import SettingView
+from lightly_studio.resolvers import settings_resolver
+
+settings_router = APIRouter(tags=["settings"])
+
+
+@settings_router.get("/settings")
+def get_settings(
+    session: SessionDep,
+) -> SettingView:
+    """Get the current settings.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        The current settings.
+    """
+    return settings_resolver.get_settings(session=session)
+
+
+@settings_router.post("/settings")
+def set_settings(
+    settings: SettingView,
+    session: SessionDep,
+) -> SettingView:
+    """Update user settings.
+
+    Args:
+        settings: New settings to apply.
+        session: Database session.
+
+    Returns:
+        Updated settings.
+    """
+    return settings_resolver.set_settings(session=session, settings=settings)

lightly_studio/api/routes/api/status.py

@@ -0,0 +1,19 @@
+"""HTTP status codes for use in tests and responses."""
+
+HTTP_STATUS_OK = 200
+HTTP_STATUS_CREATED = 201
+HTTP_STATUS_ACCEPTED = 202
+HTTP_STATUS_NO_CONTENT = 204
+
+HTTP_STATUS_BAD_REQUEST = 400
+HTTP_STATUS_UNAUTHORIZED = 401
+HTTP_STATUS_FORBIDDEN = 403
+HTTP_STATUS_NOT_FOUND = 404
+HTTP_STATUS_CONFLICT = 409
+HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415
+HTTP_STATUS_UNPROCESSABLE_ENTITY = 422
+
+HTTP_STATUS_INTERNAL_SERVER_ERROR = 500
+HTTP_STATUS_NOT_IMPLEMENTED = 501
+HTTP_STATUS_BAD_GATEWAY = 502
+HTTP_STATUS_SERVICE_UNAVAILABLE = 503

lightly_studio/api/routes/api/text_embedding.py

@@ -0,0 +1,50 @@
+"""This module contains the API routes for managing text embedding."""
+
+from __future__ import annotations
+
+from typing import List
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_INTERNAL_SERVER_ERROR,
+)
+from lightly_studio.dataset.embedding_manager import (
+    EmbeddingManager,
+    EmbeddingManagerProvider,
+    TextEmbedQuery,
+)
+
+text_embedding_router = APIRouter()
+# Define a type alias for the EmbeddingManager dependency
+EmbeddingManagerDep = Annotated[
+    EmbeddingManager,
+    Depends(lambda: EmbeddingManagerProvider.get_embedding_manager()),
+]
+
+
+@text_embedding_router.get("/text_embedding/for_dataset/{dataset_id}", response_model=List[float])
+def embed_text(
+    embedding_manager: EmbeddingManagerDep,
+    dataset_id: Annotated[UUID, Path(title="The ID of the dataset for which to embed.")],
+    query_text: str = Query(..., description="The text to embed."),
+    embedding_model_id: Annotated[
+        UUID | None,
+        Query(..., description="The ID of the embedding model to use."),
+    ] = None,
+) -> list[float]:
+    """Retrieve embeddings for the input text."""
+    try:
+        text_embeddings = embedding_manager.embed_text(
+            dataset_id=dataset_id,
+            text_query=TextEmbedQuery(text=query_text, embedding_model_id=embedding_model_id),
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=HTTP_STATUS_INTERNAL_SERVER_ERROR,
+            detail=f"{exc}",
+        ) from None
+
+    return text_embeddings

lightly_studio/api/routes/api/validators.py

@@ -0,0 +1,17 @@
+"""General LightlyStudio API models."""
+
+from pydantic import BaseModel, Field
+
+
+class Paginated(BaseModel):
+    """Paginated query parameters."""
+
+    offset: int = Field(0, ge=0, description="Offset for pagination")
+    limit: int = Field(100, gt=0, le=100, description="Limit for pagination")
+
+
+class PaginatedWithCursor(BaseModel):
+    """Paginated query parameters."""
+
+    offset: int = Field(0, ge=0, description="Offset for pagination", alias="cursor")
+    limit: int = Field(100, gt=0, le=100, description="Limit for pagination")

lightly_studio/api/routes/api/video.py

@@ -0,0 +1,133 @@
+"""API routes for dataset videos."""
+
+from typing import List, Optional
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Path
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from lightly_studio.api.routes.api.validators import Paginated, PaginatedWithCursor
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models.video import VideoFieldsBoundsView, VideoView, VideoViewsWithCount
+from lightly_studio.resolvers import video_resolver
+from lightly_studio.resolvers.video_resolver.count_video_frame_annotations_by_video_dataset import (
+    CountAnnotationsView,
+)
+from lightly_studio.resolvers.video_resolver.video_count_annotations_filter import (
+    VideoCountAnnotationsFilter,
+)
+from lightly_studio.resolvers.video_resolver.video_filter import VideoFilter
+
+video_router = APIRouter(prefix="/datasets/{dataset_id}/video", tags=["video"])
+
+
+class VideoFieldsBoundsBody(BaseModel):
+    """The body to retrieve the fields bounds."""
+
+    annotations_frames_labels_id: Optional[List[UUID]] = None
+
+
+class ReadVideosRequest(BaseModel):
+    """Request body for reading videos."""
+
+    filter: Optional[VideoFilter] = Field(None, description="Filter parameters for videos")
+    text_embedding: Optional[List[float]] = Field(None, description="Text embedding to search for")
+
+
+class ReadVideoCountAnnotationsRequest(BaseModel):
+    """Request body for reading video annotations counter."""
+
+    filter: Optional[VideoCountAnnotationsFilter] = Field(
+        None, description="Filter parameters for video annotations counter"
+    )
+
+
+@video_router.post("/annotations/count", response_model=List[CountAnnotationsView])
+def count_video_frame_annotations_by_video_dataset(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+    body: ReadVideoCountAnnotationsRequest,
+) -> List[CountAnnotationsView]:
+    """Retrieve a list of annotations along with total count and filtered count.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset to retrieve videos for.
+        body: The body containing filters.
+
+    Returns:
+        A list of annotations and counters.
+    """
+    return video_resolver.count_video_frame_annotations_by_video_dataset(
+        session=session,
+        dataset_id=dataset_id,
+        filters=body.filter,
+    )
+
+
+@video_router.post("/", response_model=VideoViewsWithCount)
+def get_all_videos(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+    pagination: Annotated[PaginatedWithCursor, Depends()],
+    body: ReadVideosRequest,
+) -> VideoViewsWithCount:
+    """Retrieve a list of all videos for a given dataset ID with pagination.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset to retrieve videos for.
+        pagination: Pagination parameters including offset and limit.
+        body: The body containing filters.
+
+    Returns:
+        A list of videos along with the total count.
+    """
+    return video_resolver.get_all_by_dataset_id(
+        session=session,
+        dataset_id=dataset_id,
+        pagination=Paginated(offset=pagination.offset, limit=pagination.limit),
+        filters=body.filter,
+        text_embedding=body.text_embedding,
+    )
+
+
+@video_router.get("/{sample_id}", response_model=VideoView)
+def get_video_by_id(
+    session: SessionDep,
+    sample_id: Annotated[UUID, Path(title="Sample ID")],
+) -> Optional[VideoView]:
+    """Retrieve a video for a given dataset ID by its ID.
+
+    Args:
+        session: The database session.
+        sample_id: The ID of the video to retrieve.
+
+    Returns:
+        A video object.
+    """
+    return video_resolver.get_view_by_id(session=session, sample_id=sample_id)
+
+
+@video_router.post("/bounds", response_model=Optional[VideoFieldsBoundsView])
+def get_fields_bounds(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+    body: VideoFieldsBoundsBody,
+) -> Optional[VideoFieldsBoundsView]:
+    """Retrieve the fields bounds for a given dataset ID by its ID.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset to retrieve videos bounds.
+        body: The body containg the filters.
+
+    Returns:
+        A video fields bounds object.
+    """
+    return video_resolver.get_table_fields_bounds(
+        dataset_id=dataset_id,
+        session=session,
+        annotations_frames_labels_id=body.annotations_frames_labels_id,
+    )

lightly_studio/api/routes/healthz.py

@@ -0,0 +1,13 @@
+"""This module contains the API routes for managing datasets."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+health_router = APIRouter()
+
+
+@health_router.get("/healthz", include_in_schema=False)
+def health_check() -> dict[str, str]:
+    """Health check endpoint to verify the service is running."""
+    return {"status": "healthy"}

lightly_studio/api/routes/images.py

@@ -0,0 +1,104 @@
+"""Image serving endpoint that supports local files."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Generator
+
+import fsspec
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from lightly_studio.api.routes.api import status
+from lightly_studio.db_manager import SessionDep
+from lightly_studio.models import image
+
+app_router = APIRouter()
+
+
+@app_router.get("/sample/{sample_id}")
+async def serve_image_by_sample_id(
+    sample_id: str,
+    session: SessionDep,
+) -> StreamingResponse:
+    """Serve an image by sample ID.
+
+    Args:
+        sample_id: The ID of the sample.
+        session: Database session.
+
+    Returns:
+        StreamingResponse with the image data.
+
+    Raises:
+        HTTPException: If the sample is not found or the file is not accessible.
+    """
+    # Retrieve the sample from the database.
+    sample_record = session.get(image.ImageTable, sample_id)
+    if not sample_record:
+        raise HTTPException(
+            status_code=status.HTTP_STATUS_NOT_FOUND,
+            detail=f"Sample not found: {sample_id}",
+        )
+
+    file_path = sample_record.file_path_abs
+
+    try:
+        # Open the file.
+        fs, fs_path = fsspec.core.url_to_fs(file_path)
+        content = fs.cat_file(fs_path)
+
+        # Determine content type based on file extension.
+        content_type = _get_content_type(file_path)
+
+        # Create a streaming response.
+        def generate() -> Generator[bytes, None, None]:
+            yield content
+
+        return StreamingResponse(
+            generate(),
+            media_type=content_type,
+            headers={
+                # Cache for 1 hour
+                "Cache-Control": "public, max-age=3600",
+                "Content-Length": str(len(content)),
+            },
+        )
+
+    except FileNotFoundError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_STATUS_NOT_FOUND,
+            detail=f"File not found: {file_path}",
+        ) from exc
+    except OSError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_STATUS_NOT_FOUND,
+            detail=f"Error accessing file {file_path}: {exc.strerror}",
+        ) from exc
+
+
+def _get_content_type(file_path: str) -> str:
+    """Get the appropriate content type for a file based on its extension.
+
+    Args:
+        file_path: Path to the file.
+
+    Returns:
+        MIME type string.
+    """
+    ext = os.path.splitext(file_path)[1].lower()
+
+    content_types = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+        ".tiff": "image/tiff",
+        ".mov": "video/quicktime",
+        ".mp4": "video/mp4",
+        ".avi": "video/x-msvideo",
+    }
+
+    return content_types.get(ext, "application/octet-stream")