lightly-studio 0.3.1__py3-none-any.whl

lightly_studio/api/routes/api/dataset_tag.py

@@ -0,0 +1,257 @@
+"""This module contains the API routes for managing tags."""
+
+from __future__ import annotations
+
+from typing import List
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
+from pydantic import BaseModel
+from sqlalchemy.exc import IntegrityError
+from sqlmodel import Field, Session
+from typing_extensions import Annotated
+
+from lightly_studio.api.db import get_session
+from lightly_studio.api.routes.api.dataset import get_and_validate_dataset_id
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_CONFLICT,
+    HTTP_STATUS_CREATED,
+    HTTP_STATUS_NOT_FOUND,
+)
+from lightly_studio.api.routes.api.validators import Paginated
+from lightly_studio.models.dataset import DatasetTable
+from lightly_studio.models.tag import (
+    TagCreate,
+    TagCreateBody,
+    TagTable,
+    TagUpdate,
+    TagUpdateBody,
+    TagView,
+)
+from lightly_studio.resolvers import tag_resolver
+
+tag_router = APIRouter()
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+@tag_router.post(
+    "/datasets/{dataset_id}/tags",
+    response_model=TagView,
+    status_code=HTTP_STATUS_CREATED,
+)
+def create_tag(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    body: TagCreateBody,
+) -> TagTable:
+    """Create a new tag in the database."""
+    dataset_id = dataset.dataset_id
+    try:
+        return tag_resolver.create(
+            session=session,
+            tag=TagCreate(**body.model_dump(exclude_unset=True), dataset_id=dataset_id),
+        )
+    except IntegrityError as e:
+        raise HTTPException(
+            status_code=HTTP_STATUS_CONFLICT,
+            detail=f"""
+                Tag with name {body.name} already exists
+                in the dataset {dataset_id}.
+            """,
+        ) from e
+
+
+@tag_router.get("/datasets/{dataset_id}/tags", response_model=List[TagView])
+def read_tags(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    paginated: Annotated[Paginated, Query()],
+) -> list[TagTable]:
+    """Retrieve a list of tags from the database."""
+    return tag_resolver.get_all_by_dataset_id(
+        session=session,
+        dataset_id=dataset.dataset_id,
+        offset=paginated.offset,
+        limit=paginated.limit,
+    )
+
+
+@tag_router.get("/datasets/{dataset_id}/tags/{tag_id}")
+def read_tag(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    tag_id: Annotated[UUID, Path(title="Tag Id")],
+) -> TagTable:
+    """Retrieve a single tag from the database."""
+    tag = tag_resolver.get_by_id(session=session, tag_id=tag_id)
+    if not tag:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"""
+            Tag with id {tag_id} for dataset {dataset.dataset_id} not found.
+            """,
+        )
+    return tag
+
+
+@tag_router.put("/datasets/{dataset_id}/tags/{tag_id}")
+def update_tag(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    tag_id: Annotated[UUID, Path(title="Tag Id")],
+    body: TagUpdateBody,
+) -> TagTable:
+    """Update an existing tag in the database."""
+    try:
+        tag = tag_resolver.update(
+            session=session,
+            tag_id=tag_id,
+            tag_data=TagUpdate(
+                **body.model_dump(exclude_unset=True),
+            ),
+        )
+        if not tag:
+            raise HTTPException(
+                status_code=HTTP_STATUS_NOT_FOUND,
+                detail=f"Tag with id {tag_id} not found.",
+            )
+    except IntegrityError as e:
+        raise HTTPException(
+            status_code=HTTP_STATUS_CONFLICT,
+            detail=f"""
+                Cannot update tag. Tag with name {body.name}
+                already exists in the dataset {dataset.dataset_id}.
+            """,
+        ) from e
+    return tag
+
+
+@tag_router.delete("/datasets/{dataset_id}/tags/{tag_id}")
+def delete_tag(
+    session: SessionDep,
+    tag_id: Annotated[UUID, Path(title="Tag Id")],
+) -> dict[str, str]:
+    """Delete a tag from the database."""
+    if not tag_resolver.delete(session=session, tag_id=tag_id):
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail="tag not found")
+    return {"status": "deleted"}
+
+
+class SampleIdsBody(BaseModel):
+    """body parameters for adding or removing thing_ids."""
+
+    sample_ids: list[UUID] | None = Field(None, description="sample ids to add/remove")
+
+
+@tag_router.post(
+    "/datasets/{dataset_id}/tags/{tag_id}/add/samples",
+    status_code=HTTP_STATUS_CREATED,
+)
+def add_sample_ids_to_tag_id(
+    session: SessionDep,
+    tag_id: UUID,
+    body: SampleIdsBody,
+) -> bool:
+    """Add sample_ids to a tag_id."""
+    tag = tag_resolver.get_by_id(session=session, tag_id=tag_id)
+    if not tag:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Tag {tag_id} not found, can't add sample_ids.",
+        )
+
+    sample_ids = body.sample_ids if body.sample_ids else []
+    tag_resolver.add_sample_ids_to_tag_id(session=session, tag_id=tag_id, sample_ids=sample_ids)
+    return True
+
+
+@tag_router.delete(
+    "/datasets/{dataset_id}/tags/{tag_id}/remove/samples",
+)
+def remove_thing_ids_to_tag_id(
+    session: SessionDep,
+    tag_id: UUID,
+    body: SampleIdsBody,
+) -> bool:
+    """Add thing_ids to a tag_id."""
+    tag = tag_resolver.get_by_id(session=session, tag_id=tag_id)
+    if not tag:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Tag {tag_id} not found, can't remove samples.",
+        )
+
+    sample_ids = body.sample_ids if body.sample_ids else []
+    tag_resolver.remove_sample_ids_from_tag_id(
+        session=session, tag_id=tag_id, sample_ids=sample_ids
+    )
+    return True
+
+
+class AnnotationIdsBody(BaseModel):
+    """body parameters for adding or removing annotation_ids."""
+
+    annotation_ids: list[UUID] | None = Field(None, description="annotation ids to add/remove")
+
+
+@tag_router.post(
+    "/datasets/{dataset_id}/tags/{tag_id}/add/annotations",
+    status_code=HTTP_STATUS_CREATED,
+)
+def add_annotation_ids_to_tag_id(
+    session: SessionDep,
+    tag_id: UUID,
+    body: AnnotationIdsBody,
+) -> bool:
+    """Add thing_ids to a tag_id."""
+    tag = tag_resolver.get_by_id(session=session, tag_id=tag_id)
+    if not tag:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Tag {tag_id} not found, can't add annotations.",
+        )
+
+    annotation_ids = body.annotation_ids if body.annotation_ids else []
+    tag_resolver.add_annotation_ids_to_tag_id(
+        session=session, tag_id=tag_id, annotation_ids=annotation_ids
+    )
+    return True
+
+
+@tag_router.delete(
+    "/datasets/{dataset_id}/tags/{tag_id}/remove/annotations",
+)
+def remove_annotation_ids_to_tag_id(
+    session: SessionDep,
+    tag_id: UUID,
+    body: AnnotationIdsBody,
+) -> bool:
+    """Add thing_ids to a tag_id."""
+    tag = tag_resolver.get_by_id(session=session, tag_id=tag_id)
+    if not tag:
+        raise HTTPException(
+            status_code=HTTP_STATUS_NOT_FOUND,
+            detail=f"Tag {tag_id} not found, can't remove annotations.",
+        )
+
+    annotation_ids = body.annotation_ids if body.annotation_ids else []
+    tag_resolver.remove_annotation_ids_from_tag_id(
+        session=session, tag_id=tag_id, annotation_ids=annotation_ids
+    )
+    return True

lightly_studio/api/routes/api/exceptions.py

@@ -0,0 +1,96 @@
+"""This module contains the FastAPI app configuration."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import ResponseValidationError
+from fastapi.responses import JSONResponse
+from sqlalchemy.exc import DataError, IntegrityError, OperationalError
+
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_BAD_REQUEST,
+    HTTP_STATUS_CONFLICT,
+    HTTP_STATUS_INTERNAL_SERVER_ERROR,
+)
+
+# Set up logger for error handling
+logger = logging.getLogger("lightly_studio.api.exceptions")
+
+
+def _log_error_details(
+    exc: Exception,
+    status_code: int,
+) -> None:
+    """Log detailed error information with request context."""
+    # Log the error with different levels based on status code
+    logger.error(f"Server Error {status_code}: {exc}")
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register exception handlers for the FastAPI app."""
+
+    @app.exception_handler(IntegrityError)
+    async def _integrity_error_handler(_request: Request, _exc: IntegrityError) -> JSONResponse:
+        """Handle database integrity errors."""
+        _log_error_details(
+            exc=_exc,
+            status_code=HTTP_STATUS_CONFLICT,
+        )
+
+        return JSONResponse(
+            status_code=HTTP_STATUS_CONFLICT,
+            content={"error": _exc.statement or "Database constraint violated."},
+        )
+
+    @app.exception_handler(OperationalError)
+    async def _operational_error_handler(_request: Request, _exc: OperationalError) -> JSONResponse:
+        """Handle database operational errors."""
+        _log_error_details(
+            exc=_exc,
+            status_code=HTTP_STATUS_INTERNAL_SERVER_ERROR,
+        )
+        return JSONResponse(
+            status_code=HTTP_STATUS_INTERNAL_SERVER_ERROR,
+            content={"error": _exc.statement or "Database operation failed."},
+        )
+
+    @app.exception_handler(DataError)
+    async def _data_error_handler(_request: Request, _exc: DataError) -> JSONResponse:
+        """Handle database data errors."""
+        _log_error_details(
+            exc=_exc,
+            status_code=HTTP_STATUS_BAD_REQUEST,
+        )
+        return JSONResponse(
+            status_code=HTTP_STATUS_BAD_REQUEST,
+            content={"error": _exc.statement or "Invalid response."},
+        )
+
+    @app.exception_handler(ResponseValidationError)
+    async def _data_validation_error_handler(
+        _request: Request, _exc: ResponseValidationError
+    ) -> JSONResponse:
+        """Handle database data errors."""
+        error_details = _exc.errors()
+        if error_details:
+            detail = error_details[0].get("msg", "Invalid data provided.")
+        else:
+            detail = "Invalid data provided."
+
+        _log_error_details(
+            exc=_exc,
+            status_code=HTTP_STATUS_BAD_REQUEST,
+        )
+
+        return JSONResponse(status_code=HTTP_STATUS_BAD_REQUEST, content={"error": detail})
+
+    @app.exception_handler(ValueError)
+    async def _value_error_handler(_request: Request, _exc: ValueError) -> JSONResponse:
+        """Handle value errors."""
+        _log_error_details(
+            exc=_exc,
+            status_code=HTTP_STATUS_INTERNAL_SERVER_ERROR,
+        )
+        return JSONResponse(status_code=HTTP_STATUS_BAD_REQUEST, content={"error": str(_exc)})

lightly_studio/api/routes/api/features.py

@@ -0,0 +1,17 @@
+"""This module contains the API routes for active features."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from lightly_studio.api.features import lightly_studio_active_features
+
+__all__ = ["features_router", "lightly_studio_active_features"]
+
+features_router = APIRouter()
+
+
+@features_router.get("/features")
+def get_features() -> list[str]:
+    """Get the list of active features in the LightlyStudio app."""
+    return lightly_studio_active_features

lightly_studio/api/routes/api/metadata.py

@@ -0,0 +1,37 @@
+"""This module contains the API routes for managing datasets."""
+
+from __future__ import annotations
+
+from typing import List
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Path
+from sqlmodel import Session
+from typing_extensions import Annotated
+
+from lightly_studio.api.db import get_session
+from lightly_studio.models.metadata import MetadataInfoView
+from lightly_studio.resolvers.metadata_resolver.sample.get_metadata_info import (
+    get_all_metadata_keys_and_schema,
+)
+
+metadata_router = APIRouter(prefix="/datasets/{dataset_id}", tags=["metadata"])
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+@metadata_router.get("/metadata/info", response_model=List[MetadataInfoView])
+def get_metadata_info(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+) -> list[MetadataInfoView]:
+    """Get all metadata keys and their schema for a dataset.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset.
+
+    Returns:
+        List of metadata info objects with name, type, and optionally min/max values
+        for numerical metadata types.
+    """
+    return get_all_metadata_keys_and_schema(session=session, dataset_id=dataset_id)

lightly_studio/api/routes/api/metrics.py

@@ -0,0 +1,80 @@
+"""This module contains the API routes for computing detection metrics."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlmodel import Session
+from typing_extensions import Annotated
+
+from lightly_studio.api.db import get_session
+from lightly_studio.metrics.detection.map import (
+    DetectionMetricsMAP,
+    calculate_map_metric,
+)
+from lightly_studio.resolvers import (
+    annotation_label_resolver,
+    annotation_resolver,
+)
+from lightly_studio.resolvers.annotations.annotations_filter import (
+    AnnotationsFilter,
+)
+
+metrics_router = APIRouter()
+
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+class DetectionMetricsMAPRequest(BaseModel):
+    """Request for computing the MAP detection metric."""
+
+    dataset_id: UUID
+    ground_truth_task_id: UUID
+    prediction_task_id: UUID
+    tag_id: UUID | None = None
+
+
+@metrics_router.post("/metrics/compute/detection/map", response_model=DetectionMetricsMAP)
+def compute_detection_map(
+    request_body: DetectionMetricsMAPRequest,
+    session: SessionDep,
+) -> DetectionMetricsMAP:
+    """Compute the MAP detection metric."""
+    ground_truth_annotations = annotation_resolver.get_all(
+        session=session,
+        filters=AnnotationsFilter(
+            dataset_ids=[request_body.dataset_id],
+            annotation_task_ids=[request_body.ground_truth_task_id],
+            sample_tag_ids=[request_body.tag_id] if request_body.tag_id else None,
+        ),
+    ).annotations
+    prediction_annotations = annotation_resolver.get_all(
+        session=session,
+        filters=AnnotationsFilter(
+            dataset_ids=[request_body.dataset_id],
+            annotation_task_ids=[request_body.prediction_task_id],
+            sample_tag_ids=[request_body.tag_id] if request_body.tag_id else None,
+        ),
+    ).annotations
+
+    metrics_result = calculate_map_metric(
+        pred_annotations=prediction_annotations,
+        gt_annotations=ground_truth_annotations,
+    )
+
+    # Rename per-class metrics to use label names
+    raw_map_pc = metrics_result.map_per_class
+    if raw_map_pc:
+        id2name = annotation_label_resolver.names_by_ids(
+            session=session, ids=[UUID(k) for k in raw_map_pc]
+        )
+        metrics_result.map_per_class = {id2name.get(k, k): v for k, v in raw_map_pc.items()}
+    raw_mar100_pc = metrics_result.mar_100_per_class
+    if raw_mar100_pc:
+        id2name = annotation_label_resolver.names_by_ids(
+            session=session, ids=[UUID(k) for k in raw_mar100_pc]
+        )
+        metrics_result.mar_100_per_class = {id2name.get(k, k): v for k, v in raw_mar100_pc.items()}
+    return metrics_result

lightly_studio/api/routes/api/sample.py

@@ -0,0 +1,196 @@
+"""This module contains the API routes for managing samples."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Query
+from pydantic import BaseModel, Field
+from sqlmodel import Session
+from typing_extensions import Annotated
+
+from lightly_studio.api.db import get_session
+from lightly_studio.api.routes.api.dataset import get_and_validate_dataset_id
+from lightly_studio.api.routes.api.status import (
+    HTTP_STATUS_CREATED,
+    HTTP_STATUS_NOT_FOUND,
+)
+from lightly_studio.api.routes.api.validators import Paginated
+from lightly_studio.models.dataset import DatasetTable
+from lightly_studio.models.sample import (
+    SampleCreate,
+    SampleTable,
+    SampleView,
+    SampleViewsWithCount,
+)
+from lightly_studio.resolvers import (
+    sample_resolver,
+    tag_resolver,
+)
+from lightly_studio.resolvers.samples_filter import (
+    SampleFilter,
+)
+
+samples_router = APIRouter(prefix="/datasets/{dataset_id}", tags=["samples"])
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+@samples_router.post("/samples", response_model=SampleView)
+def create_sample(
+    session: SessionDep,
+    input_sample: SampleCreate,
+) -> SampleTable:
+    """Create a new sample in the database."""
+    return sample_resolver.create(session=session, sample=input_sample)
+
+
+class ReadSamplesRequest(BaseModel):
+    """Request body for reading samples with text embedding."""
+
+    filters: SampleFilter | None = Field(None, description="Filter parameters for samples")
+    text_embedding: list[float] | None = Field(None, description="Text embedding to search for")
+    sample_ids: list[UUID] | None = Field(None, description="The list of requested sample IDs")
+    pagination: Paginated | None = Field(
+        None, description="Pagination parameters for offset and limit"
+    )
+
+
+@samples_router.post("/samples/list", response_model=SampleViewsWithCount)
+def read_samples(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id")],
+    body: ReadSamplesRequest,
+) -> SampleViewsWithCount:
+    """Retrieve a list of samples from the database with optional filtering.
+
+    Args:
+        session: The database session.
+        dataset_id: The ID of the dataset to filter samples by.
+        body: Optional request body containing text embedding.
+
+    Returns:
+        A list of filtered samples.
+    """
+    result = sample_resolver.get_all_by_dataset_id(
+        session=session,
+        dataset_id=dataset_id,
+        # TODO(Michal, 06/2025): Pass the Paginated object directly.
+        offset=body.pagination.offset if body.pagination else 0,
+        limit=body.pagination.limit if body.pagination else 10,
+        filters=body.filters,
+        text_embedding=body.text_embedding,
+        sample_ids=body.sample_ids,
+    )
+
+    return SampleViewsWithCount(
+        data=result.samples,
+        total_count=result.total_count,
+    )
+
+
+@samples_router.get("/samples/dimensions")
+def get_sample_dimensions(
+    session: SessionDep,
+    dataset: Annotated[
+        DatasetTable,
+        Path(title="Dataset Id"),
+        Depends(get_and_validate_dataset_id),
+    ],
+    annotation_label_ids: Annotated[list[UUID] | None, Query()] = None,
+) -> dict[str, int]:
+    """Get min and max dimensions of samples in a dataset."""
+    return sample_resolver.get_dimension_bounds(
+        session=session,
+        dataset_id=dataset.dataset_id,
+        annotation_label_ids=annotation_label_ids,
+    )
+
+
+@samples_router.get("/samples/{sample_id}", response_model=SampleView)
+def read_sample(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],
+    sample_id: Annotated[UUID, Path(title="Sample Id")],
+) -> SampleTable:
+    """Retrieve a single sample from the database."""
+    sample = sample_resolver.get_by_id(session=session, dataset_id=dataset_id, sample_id=sample_id)
+    if not sample:
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail="Sample not found")
+    return sample
+
+
+@samples_router.put("/samples/{sample_id}")
+def update_sample(
+    session: SessionDep,
+    sample_id: Annotated[UUID, Path(title="Sample Id")],
+    sample_input: SampleCreate,
+) -> SampleTable:
+    """Update an existing sample in the database."""
+    sample = sample_resolver.update(session=session, sample_id=sample_id, sample_data=sample_input)
+    if not sample:
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail="Sample not found")
+    return sample
+
+
+@samples_router.delete("/samples/{sample_id}")
+def delete_sample(
+    session: SessionDep,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],
+    sample_id: Annotated[UUID, Path(title="Sample Id")],
+) -> dict[str, str]:
+    """Delete a sample from the database."""
+    if not sample_resolver.delete(session=session, dataset_id=dataset_id, sample_id=sample_id):
+        raise HTTPException(status_code=HTTP_STATUS_NOT_FOUND, detail="Sample not found")
+    return {"status": "deleted"}
+
+
+@samples_router.post(
+    "/samples/{sample_id}/tag/{tag_id}",
+    status_code=HTTP_STATUS_CREATED,
+)
+def add_tag_to_sample(
+    session: SessionDep,
+    sample_id: UUID,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],
+    tag_id: UUID,
+) -> bool:
+    """Add sample to a tag."""
+    sample = sample_resolver.get_by_id(session=session, dataset_id=dataset_id, 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
+
+
+@samples_router.delete("/samples/{sample_id}/tag/{tag_id}")
+def remove_tag_from_sample(
+    session: SessionDep,
+    tag_id: UUID,
+    dataset_id: Annotated[UUID, Path(title="Dataset Id", description="The ID of the dataset")],
+    sample_id: UUID,
+) -> bool:
+    """Remove sample from a tag."""
+    sample = sample_resolver.get_by_id(session=session, dataset_id=dataset_id, 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
+
+
+class SampleAdjacentsParams(BaseModel):
+    """Parameters for getting adjacent samples."""
+
+    filters: SampleFilter | None = None
+    text_embedding: list[float] | None = None