### Clone and Start Development Environment

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Clone the repository and start the development environment. This includes installing dependencies, building the application, and starting an example script.

```bash
git clone git@github.com:lightly-ai/lightly_studio.git
cd lightly_studio/lightly_studio
make start
```

--------------------------------

### Local Postgres Setup

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/MIGRATIONS.md

Starts a local PostgreSQL database required for autogenerating and checking migrations.

```bash
cd lightly_studio
make start-postgres
```

--------------------------------

### Start Backend Server

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Start the backend server for the LightlyStudio application. This command should be run from the backend directory.

```bash
cd lightly_studio
make start
```

--------------------------------

### Install lightly-studio

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/src/lightly_studio/examples/example_notebook.ipynb

Install the lightly-studio library using pip. This is the first step before using any of its features.

```python
!pip install lightly-studio
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Start the frontend development server using npm. This command should be run from the lightly_studio_view directory after configuring .env.local.

```bash
npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio_view/README.md

Start the SvelteKit development server. The `--open` flag will automatically open the application in a new browser tab.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Install LightlyStudio

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

Install the LightlyStudio package using pip. This command is used for setting up the tool on your local machine.

```shell
pip install lightly-studio
```

--------------------------------

### Run a Python Example Script

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Execute a Python example script from the lightly_studio directory. This is useful for testing specific functionalities or demonstrating features.

```bash
cd lightly_studio
uv run src/lightly_studio/examples/example.py
```

--------------------------------

### Start E2E Environment for Video Testing

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Start the end-to-end testing environment specifically configured for video-related tests. This ensures the correct setup for video processing.

```bash
make -C lightly_studio start-e2e-with-videos
```

--------------------------------

### Register and Run Operator Plugin

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Example of how to register a custom operator plugin and start the Lightly Studio GUI. This code snippet shows the necessary imports and the registration process.

```python
import lightly_studio as ls
from lightly_studio.plugins.operator_registry import operator_registry
from lightly_studio.utils import download_example_dataset
from greeting_operator import GreetingOperator

dataset_path = download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.create()
dataset.add_images_from_path(path=f"{dataset_path}/coco_subset_128_images/images")

# Register the operator to make it available to the application
operator_registry.register(GreetingOperator())

ls.start_gui()
```

--------------------------------

### Install LightlyStudio on Windows

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/index.md

Installs LightlyStudio using pip after setting up a Python virtual environment. Ensure Python 3.9-3.14 is installed.

```powershell
# 1. Create and activate a virtual environment (Recommended)
python -m venv venv
.\venv\Scripts\activate

# 2. Install LightlyStudio
pip install lightly_studio
```

--------------------------------

### Clone Example Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Clone the example dataset repository into the backend subdirectory. This provides sample data for development and testing.

```bash
cd lightly_studio
git clone https://github.com/lightly-ai/dataset_examples
```

--------------------------------

### Copy Environment Example File

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Copy the example environment file to a new file named .env. This is the first step in configuring environment variables for the project.

```shell
cd lightly_studio
cp .env.example .env
```

--------------------------------

### Start Lightly Studio GUI from Python

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/video_dataset.md

Starts the Lightly Studio GUI programmatically from a Python script. This is an alternative to launching it via the command line.

```python
import lightly

ls = lightly.api.Lightly("YOUR_LIGHTLY_API_TOKEN")
ls.start_gui()
```

--------------------------------

### Install Cloud Storage Dependencies

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/cloud_storage.md

Install the lightly-studio package with cloud storage support to enable integrations with S3, GCS, and Azure.

```shell
pip install "lightly-studio[cloud-storage]"
```

--------------------------------

### Install LightlyStudio on Linux/macOS

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/index.md

Installs LightlyStudio using pip after setting up a Python virtual environment. Ensure Python 3.9-3.14 is installed.

```shell
# 1. Create and activate a virtual environment (Recommended)
python3 -m venv venv
source venv/bin/activate

# 2. Install LightlyStudio
pip install lightly_studio
```

--------------------------------

### Register and run auto-labeling operator

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

This Python script demonstrates how to set up and run an auto-labeling operator for object detection using Lightly Studio. It includes downloading an example dataset, creating an image dataset, registering the custom operator, and starting the GUI.

```python
import lightly_studio as ls
from lightly_studio.plugins.operator_registry import operator_registry
from lightly_studio.utils import download_example_dataset
from lightly_train_auto_label_od_operator import LightlyTrainAutoLabelingODOperator

dataset_path = download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.create()
dataset.add_images_from_path(path=f"{dataset_path}/coco_subset_128_images/images")

# Register the operator to make it available to the application
operator_registry.register(LightlyTrainAutoLabelingODOperator())

ls.start_gui()
```

--------------------------------

### Download and Load Example Dataset for Object Detection

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/image_dataset.md

Downloads an example dataset and loads it into an ImageDataset object for object detection tasks. Assumes images are in a subfolder relative to the dataset path.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.create()
dataset.add_samples_from_lightly(
    input_folder=f"{dataset_path}/coco_subset_128_images/predictions",
)
```

--------------------------------

### Install LightlyStudio Plugin using uv

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Installs a specified LightlyStudio plugin using the 'uv' package manager. Replace <plugin_name> with the actual plugin folder name.

```bash
uv pip install "git+https://github.com/lightly-ai/lightly-studio-plugins.git#subdirectory=plugins/<plugin_name>/"
```

--------------------------------

### Start Lightly Studio GUI in Background for Notebooks

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

Starts the Lightly Studio GUI in the background, suitable for use in notebooks. Use '0.0.0.0' for the host when running in environments like Colab to ensure accessibility.

```python
import lightly_studio as ls

dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")
dataset = ls.ImageDataset.load_or_create()
dataset.add_images_from_path(path=f"{dataset_path}/coco_subset_128_images/images")

# Colab needs 0.0.0.0 to expose the port.
server = ls.start_gui_background(host="0.0.0.0")

```

--------------------------------

### Project Structure Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/frontend.md

Illustrates the canonical directory layout for components and libraries, including component logic files, tests, stories, helper files, and hooks with barrel exports.

```tree
src/
  components/
    AuthForm/
      AuthForm.svelte
      AuthForm.test.ts
      AuthForm.stories.svelte       # if needed
    UserDashboard/
      UserDashboard.svelte
      UserDashboard.test.ts
      UserDashboard.helpers.ts       # if needed
      UserProfile/                   # subcomponent
        UserProfile.svelte
        UserProfile.test.ts
  lib/
    hooks/
      index.ts                       # barrel exports
      useAuth/
        useAuth.ts
        useAuth.test.ts
      useData/
        useData.ts
        useData.test.ts
```

--------------------------------

### Install LightlyStudio Plugin using pip

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Installs a specified LightlyStudio plugin using the 'pip' package manager. Replace <plugin_name> with the actual plugin folder name.

```bash
pip install "git+https://github.com/lightly-ai/lightly-studio-plugins.git#subdirectory=plugins/<plugin_name>/"
```

--------------------------------

### Copy Frontend Environment File

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Copy the example environment file to .env.local in the frontend directory. This is necessary for configuring frontend-specific environment variables.

```bash
cd lightly_studio_view
cp .env .env.local
```

--------------------------------

### Start Lightly Studio GUI in Background

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/notebooks.md

Starts the Lightly Studio GUI in the background, allowing notebook execution to continue. Use '0.0.0.0' for host in Colab to expose the port.

```python
# Colab needs 0.0.0.0 to expose the port.
server = ls.start_gui_background(host="0.0.0.0")
```

--------------------------------

### Start E2E Environment for Image Testing

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Start the end-to-end testing environment for image-related tests. This prepares the system for running Playwright tests.

```bash
make -C lightly_studio start-e2e
```

--------------------------------

### Start with a Fresh Database

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/reuse_datasets.md

Wipe an existing database and start over by passing `cleanup_existing=True`. This permanently deletes the current DuckDB file and its contents.

```python
import lightly_studio as ls

ls.db_manager.connect(db_file="/data/lightly_studio.db", cleanup_existing=True)
```

--------------------------------

### Run Deep Copy Benchmark (Generate and Copy)

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/tests/benchmarks/README.md

Start PostgreSQL, generate a synthetic dataset, and then perform a deep copy using the benchmark script.

```bash
make start-postgres
uv run tests/benchmarks/deep_copy_benchmark.py --generate 250000
make stop-postgres
```

--------------------------------

### Install BBox Auto Propagation Nano Tracker Plugin

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Installs the BBox auto propagation nano tracker plugin from the lightly-studio-plugins repository. This plugin propagates bounding box annotations across video frames.

```bash
pip install git+https://github.com/lightly-ai/lightly-studio-plugins.git#subdirectory=plugins/bbox_auto_propagation_nano_tracker/
```

--------------------------------

### Connect and Load Dataset from S3

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/enterprise/cloud_storage/index.md

Connect to LightlyStudio and load or create an image dataset from an S3 path. Ensure the 'cloud-storage' extra is installed for the Python client.

```python
import lightly_studio as ls

ls.connect()

dataset = ls.ImageDataset.load_or_create("s3_dataset")
dataset.add_images_from_path(path="s3://my-bucket/images/")
```

--------------------------------

### Load Example COCO Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/src/lightly_studio/examples/example_notebook.ipynb

Download and load an example COCO dataset. This snippet shows how to download a dataset and add samples from a COCO annotations file.

```python
# Load example COCO dataset
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")
dataset = ls.ImageDataset.load_or_create()
dataset.add_samples_from_coco(
    annotations_json=f"{dataset_path}/coco_subset_128_images/instances_train2017.json",
    images_path=f"{dataset_path}/coco_subset_128_images/images",
)
```

--------------------------------

### Install LightlyTrain Object Detection Inference Plugin

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Installs the LightlyTrain object detection inference plugin for auto-labeling. It can use built-in LightlyTrain models or a local checkpoint.

```bash
pip install git+https://github.com/lightly-ai/lightly-studio-plugins.git#subdirectory=plugins/lightly_train_object_detection_inference/
```

--------------------------------

### Index Folder of Videos for Curation and Labeling

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

Initializes a VideoDataset, adds all videos from a specified path, and starts the Lightly Studio GUI for curation and labeling. The dataset is loaded or created locally.

```python
import lightly_studio as ls

dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.VideoDataset.load_or_create()
dataset.add_videos_from_path(path=f"{dataset_path}/youtube_vis_50_videos/train/videos")

ls.start_gui()

```

--------------------------------

### Install SAM3 Segmentation Plugin

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Installs the SAM3 Segmentation plugin, which segments instances based on text prompts in images. Requires Hugging Face access to facebook/sam3.

```bash
pip install git+https://github.com/lightly-ai/lightly-studio-plugins.git#subdirectory=plugins/sam3_segmentation/
```

--------------------------------

### Install SAM3 Segmentation Plugin

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

Install the SAM3 segmentation plugin using pip. Ensure you have the necessary prerequisites and model access as outlined in the plugin's README.

```bash
pip install "git+https://github.com/lightly-ai/lightly-studio-plugins.git#subdirectory=plugins/sam3_segmentation/"
```

--------------------------------

### Load Videos from S3

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/cloud_storage.md

Example of loading videos from an S3 bucket into a Lightly Studio VideoDataset. Ensure your cloud credentials are configured.

```python
import lightly_studio as ls

dataset = ls.VideoDataset.load_or_create(name="s3_video_dataset")
dataset.add_videos_from_path(path="s3://my-bucket/videos/")

ls.start_gui()
```

--------------------------------

### GUI Query Examples

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/search_and_filter.md

Filter images based on dimensions, tags, or annotations using an SQL-like query language in the GUI.

```mysql
# Images that are at least 640 pixels wide or 400 pixels tall
width >= 640 OR height >= 400
```

```mysql
# Images which do not have the tag "reviewed"
NOT "reviewed" IN tags
```

```mysql
# Images with a "car" segmentation mask that is less than 100 pixels wide
segmentation_mask(class_name = "car" AND width < 100)
```

--------------------------------

### Hello World Operator Plugin Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/plugins.md

A basic 'Hello World' operator plugin demonstrating how to define an operator with a string parameter and a simple execution logic. This operator greets the user with a customizable message.

```python
from dataclasses import dataclass

from lightly_studio.plugins.base_operator import BaseOperator, OperatorResult
from lightly_studio.plugins.operator_context import OperatorScope
from lightly_studio.plugins.parameter import StringParameter


@dataclass
class GreetingOperator(BaseOperator):
    name: str = "GreetingOperator"
    description: str = "This operator greet you"

    @property
    def parameters(self):
        return [
            StringParameter(
                name="name",
                required=True,
                default="beautiful and smart person",
                description="your name"
            ),
        ]
    
    @property
    def supported_scopes(self) -> list[OperatorScope]:
        """Return the list of scopes this operator can be triggered from."""
        return [OperatorScope.ROOT]
    
    def execute(self, *, session, context, parameters):
        your_name = parameters.get("name", "")
        return OperatorResult(success=True, message=f"Hello {your_name}!")
```

--------------------------------

### Load Video Folder Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/index.md

This snippet shows how to load a dataset from a folder of videos. It downloads example data and populates the dataset with video files. Use this when your dataset consists of video files.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

# Create a dataset and populate it with videos.
dataset = ls.VideoDataset.load_or_create()
dataset.add_videos_from_path(path=f"{dataset_path}/youtube_vis_50_videos/train/videos")

# Start the UI server.
ls.start_gui()
```

--------------------------------

### Load or Create Dataset and Add Images

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

Reopens an existing dataset or creates a new one using `load_or_create`. New images are added from specified directories, and the GUI is started.

```python
import lightly_studio as ls

dataset = ls.ImageDataset.load_or_create(name="my-dataset")

# Only new samples are added by `add_images_from_path`
for image_dir in IMAGE_DIRS:
    dataset.add_images_from_path(path=image_dir)

ls.start_gui()
```

--------------------------------

### Load Images from S3

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/cloud_storage.md

Example of loading images from an S3 bucket into a Lightly Studio ImageDataset. Ensure your cloud credentials are configured.

```python
import lightly_studio as ls

dataset = ls.ImageDataset.load_or_create(name="s3_dataset")
dataset.add_images_from_path(path="s3://my-bucket/images/")

ls.start_gui()
```

--------------------------------

### Python Google Style Docstring Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/python.md

Implement Google-style docstrings for functions and methods, including a summary line, detailed explanation, argument descriptions, return value descriptions, and raised exceptions.

```python
def foo(bar: int) -> str:
    """Summary of function here.

    Longer function information...

    Args:
        bar: Description of the argument `bar`.

    Returns:
        Description of the return value.

    Raises:
        ValueError: Description of the error that may be raised.
    """
```

--------------------------------

### Index Folder of Images for Curation and Labeling

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

Initializes an ImageDataset, adds all images from a specified path, and starts the Lightly Studio GUI for curation and labeling. The dataset is loaded or created locally.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

# Index the images, create embeddings, and store everything in the local database.
dataset = ls.ImageDataset.load_or_create()
dataset.add_images_from_path(
    path=f"{dataset_path}/coco_subset_128_images/images",
)

# Start the UI server on localhost:8001.
# Pass `host` and `port` parameters to customize it.
ls.start_gui()

```

--------------------------------

### Create Dataset from COCO Data

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/notebooks.md

Downloads an example dataset and creates an ImageDataset, adding samples from a COCO annotations file and associated images.

```python
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")
dataset = ls.ImageDataset.load_or_create()
dataset.add_samples_from_coco(
    annotations_json=f"{dataset_path}/coco_subset_128_images/instances_train2017.json",
    images_path=f"{dataset_path}/coco_subset_128_images/images",
)
```

--------------------------------

### Class Docstring Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/python.md

Document class functionality and public attributes. Include a summary and longer description, along with an 'Attributes' section for clarity.

```python
class SampleClass:
    """Summary of class here.

    Longer class information...

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    name: str
    """An example docstring."""

```

--------------------------------

### Load Image Folder Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/index.md

This snippet demonstrates loading a dataset from a folder of images. It downloads example data and indexes the images into the dataset. Use this for simple image collections without specific annotation formats.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

# Indexes the dataset, creates embeddings and stores everything in the database.
dataset = ls.ImageDataset.load_or_create()
dataset.add_images_from_path(
    path=f"{dataset_path}/coco_subset_128_images/images",
)

# Start the UI server on localhost port 8001.
# Pass `host` and `port` parameters to customize.
ls.start_gui()
```

--------------------------------

### Build Documentation

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Build the project documentation. Navigate to the docs folder and run the make command to generate documentation files.

```bash
make docs
```

--------------------------------

### Complex LQL Query: Reviewed Samples with Object Detection

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/lightly_query_language.md

This example demonstrates a complex query to find large, reviewed images that also contain a specific object detection. It combines multiple conditions using AND.

```mysql
# Large reviewed sample with a matching object detection
height > 400 AND width >= 640
AND "reviewed" IN tags
AND object_detection(class_name = "cat" AND width > 80 AND height > 80)
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Serve the built documentation locally for preview. This allows you to view the documentation as it would appear online.

```bash
make serve
```

--------------------------------

### Configure .env File for Lightly Studio

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/enterprise/connect.md

Create a `.env` file in your working directory and paste your copied `LIGHTLY_STUDIO_API_URL` and `LIGHTLY_STUDIO_TOKEN` values. Lightly Studio reads this file automatically.

```shell
LIGHTLY_STUDIO_API_URL="http://your-server:8100"
LIGHTLY_STUDIO_TOKEN="eyJhbGciOiJIUzI1NiIs..."
```

--------------------------------

### Run GUI Benchmark with Enterprise Backend

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/tests/benchmarks/README.md

Connect to a remote enterprise instance for the GUI benchmark. Ensure the environment variables `LIGHTLY_STUDIO_API_URL` and `LIGHTLY_STUDIO_TOKEN` are set correctly.

```bash
export LIGHTLY_STUDIO_API_URL="http://<enterprise-host>:8400"
export LIGHTLY_STUDIO_TOKEN="<token-from-the-enterprise-GUI>"
uv run tests/benchmarks/gui_benchmark.py --num-images 10000 --backend enterprise
```

--------------------------------

### Run Tag Assignment Benchmark (PostgreSQL)

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/tests/benchmarks/README.md

Set up PostgreSQL, run the tag assignment benchmark against it, and then stop PostgreSQL.

```bash
make start-postgres
uv run tests/benchmarks/tag_assignment_benchmark.py --postgres
make stop-postgres
```

--------------------------------

### Open GUI from CLI (Default Location)

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/reuse_datasets.md

Open the Lightly Studio GUI from the command line when the `lightly_studio.db` file is in the current directory.

```shell
lightly-studio gui
```

--------------------------------

### Open GUI from CLI (Specific DB File)

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/reuse_datasets.md

Open the Lightly Studio GUI from the command line and specify the path to the DuckDB file using the `--db-file` argument.

```shell
lightly-studio gui --db-file /data/lightly_studio.db
```

--------------------------------

### Svelte Unit Test Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/frontend.md

Example of a basic Svelte unit test using testing-library/svelte. Ensure tests focus on user-visible outcomes and avoid implementation details.

```typescript
import { render, screen } from "@testing-library/svelte";
import MyComponent from "./MyComponent.svelte";

describe("MyComponent", () => {
  it("renders the title", () => {
    render(MyComponent, { props: { title: "Hello World" } });
    expect(screen.getByText("Hello World")).toBeInTheDocument();
  });
});
```

--------------------------------

### Connect to Lightly Studio Enterprise and Load Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/enterprise/connect.md

Connect to your Lightly Studio Enterprise instance by calling `ls.connect()`. This function automatically reads credentials from a `.env` file or environment variables. After connecting, you can load and interact with datasets as usual, with all operations directed to the enterprise database.

```python
import lightly_studio as ls

# Reads LIGHTLY_STUDIO_API_URL and LIGHTLY_STUDIO_TOKEN from .env
ls.connect()

# From here on, the API works exactly as in the open-source version,
# but data is stored in the shared enterprise database.
dataset = ls.ImageDataset.load("my_dataset")
for sample in list(dataset)[:3]:
    print(f"{sample.file_name} has {len(sample.annotations)} annotations")
```

--------------------------------

### Storybook Story Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/frontend.md

Use this simplified syntax for Storybook stories, omitting explicit snippet children for text content.

```typescript
<Story name="H1" args={{ variant: 'h1' }}>
    Heading 1 - Large Page Title
</Story>
```

--------------------------------

### RLE Mask Format Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/annotations.md

Illustrates the Run-Length Encoding (RLE) format expected for segmentation masks when not using binary masks.

```plaintext
Example 2x4 mask:
```
[[0, 1, 1, 0],
 [1, 1, 1, 1]]
```

Flattened:
```
[0, 1, 1, 0, 1, 1, 1, 1]
```

Encoded:
```
[1, 2, 1, 4]
```
```

--------------------------------

### Build Production Version

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio_view/README.md

Create a production-ready build of the SvelteKit application. This command optimizes the code for deployment.

```bash
npm run build
```

--------------------------------

### Pytest Mocking Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/python.md

Use `MockerFixture` for mocking in tests. Patch objects and use `assert_called_once_with` for verification. `MagicMock` can also be used.

```python
from pytest_mock import MockerFixture

def test_foo(mocker: MockerFixture):
    mock_bar = mocker.patch.object(mymodule, "bar", return_value=42)
    mock_bar.assert_called_once_with(...)

    mock_obj = mocker.MagicMock()

```

--------------------------------

### Index Raw Videos from Local Storage

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/enterprise/local_storage.md

Load or create a video dataset and add videos from a specified local path. The path must be absolute and accessible by Lightly Studio.

```python
import lightly_studio as ls

ls.connect()

dataset = ls.VideoDataset.load_or_create("dataset_b")
dataset.add_videos_from_path(path="/mnt/datasets/dataset_b/videos")
```

--------------------------------

### Run GUI Benchmark with Project Path

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/tests/benchmarks/README.md

Execute the GUI benchmark script specifying the project path. This ensures the script runs within the correct context, especially when executed from the repository root.

```bash
uv run --project lightly_studio lightly_studio/tests/benchmarks/gui_benchmark.py
```

--------------------------------

### COCO Caption JSON Structure

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/captions.md

Example structure of a COCO caption JSON file, including image information and annotation details with captions.

```json
{
  "images": [
    {"id": 1, "file_name": "cat.jpg", "width": 640, "height": 480}
  ],
  "annotations": [
    {"id": 1, "image_id": 1, "caption": "A cat on a mat"},
    {"id": 2, "image_id": 1, "caption": "Tabby cat resting indoors"}
  ]
}
```

--------------------------------

### Run GUI Benchmark with PostgreSQL

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/tests/benchmarks/README.md

Execute the GUI benchmark using a PostgreSQL backend. Ensure PostgreSQL is running and accessible before executing this command.

```bash
make start-postgres
uv run tests/benchmarks/gui_benchmark.py --num-images 10000 --backend postgres
make stop-postgres
```

--------------------------------

### Load a Video Dataset from a Database

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/video_dataset.md

Load an existing video dataset directly from the Lightly Studio database to skip re-indexing and embedding. Use `load_or_create()` to ensure the dataset exists.

```python
import lightly_studio as ls

# Load an existing dataset from the database.
dataset = ls.VideoDataset.load()

# A helper method that creates a dataset only if it does not exist yet.
dataset = ls.VideoDataset.load_or_create()
```

--------------------------------

### Load an Image Dataset from a Database

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/image_dataset.md

Loads an existing Image Dataset from the Lightly Studio database. Use `load_or_create()` to create the dataset if it doesn't exist.

```python
import lightly_studio as ls

# Load an existing dataset from the database.
dataset = ls.ImageDataset.load()

# A helper method that creates a dataset only if it does not exist yet.
dataset = ls.ImageDataset.load_or_create()
```

--------------------------------

### Run Embedding I/O Benchmark with PostgreSQL

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/tests/benchmarks/README.md

Benchmark the embedding I/O operations against PostgreSQL (pgvector). Ensure PostgreSQL is started before running the benchmark and stopped afterward.

```bash
make start-postgres
uv run tests/benchmarks/embedding_io_benchmark.py --postgres
make stop-postgres
```

--------------------------------

### Import Lightly Studio

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/src/lightly_studio/examples/example_notebook.ipynb

Import the necessary libraries from lightly-studio. This includes the main library and utility functions.

```python
# Import
import lightly_studio as ls
from lightly_studio.utils import download_example_dataset
```

--------------------------------

### Backend Request Flow

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/backend.md

Illustrates the typical request path within the backend, starting from a FastAPI route and potentially involving services and resolvers before interacting with the database.

```text
FastAPI route -> optional service -> resolver(s) -> SQLModel / database
```

--------------------------------

### Connect to Lightly Studio Enterprise Explicitly

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/enterprise/connect.md

Pass the `api_url` and `token` directly to the `ls.connect()` function. Explicit parameters take precedence over environment variables.

```python
import lightly_studio as ls

ls.connect(
    api_url="http://your-server:8100",
    token="eyJhbGciOiJIUzI1NiIs...",
)
```

--------------------------------

### Index YOLO Dataset for Lightly Studio

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

This script indexes a YOLO dataset, loading images and annotations into Lightly Studio. It then starts the Lightly Studio GUI for exploration.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.load_or_create()
dataset.add_samples_from_yolo(
    data_yaml=f"{dataset_path}/road_signs_yolo/data.yaml",
)

ls.start_gui()

```

--------------------------------

### Access Image Data and Properties

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/image_dataset.md

Provides examples of accessing various properties of an ImageSample object, including file name, dimensions, tags, captions, metadata, and annotations.

```python
# Grab one sample
image = next(iter(dataset))

# Image properties
print(image.file_name)
print(image.file_path_abs)
print(image.width)
print(image.height)

# Tags
image.tags = ["tag1", "tag2"]
image.add_tag("needs_review")
image.remove_tag("needs_review")
print(image.tags)

# Captions
image.captions = ["Caption 1", "Caption 2"]
image.add_caption("Caption 3")
print(image.captions)

# Metadata
image.metadata["my_key"] = "my_value"
print(image.metadata["my_key"])

# Annotations
from lightly_studio.core.annotation import CreateObjectDetection
image.add_annotation(
    CreateObjectDetection(
        class_name="dog",
        x=10,
        y=20,
        width=30,
        height=40,
        confidence=0.9,
    )
)
for annotation in image.annotations:
    print(annotation.class_name)
```

--------------------------------

### Create and Add Images to Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/README.md

Demonstrates creating a new dataset and adding images from various sources, including cloud storage (S3, GCS) and local folders. Existing datasets can also be loaded.

```python
import lightly_studio as ls

# Different loading options:
dataset = ls.ImageDataset.create()

# You can load data also from cloud storage
dataset.add_images_from_path(path="s3://my-bucket/path/to/images/")

# And at any given time you can append more data (even across sources)
dataset.add_images_from_path(path="gcs://my-bucket-2/path/to/more-images/")
dataset.add_images_from_path(path="local-folder/some-data-not-in-the-cloud-yet")

# Load existing .db file
dataset = ls.ImageDataset.load()
```

--------------------------------

### Store-based Counter Hook Example

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/frontend.md

Demonstrates creating a reusable Svelte store-based hook for managing a counter's state. Use this pattern for simple, reusable state logic.

```typescript
// useCounter.ts
import { writable } from 'svelte/store';

const count = writable<number>(0);

export function useCounter() {
  function increment() {
    count.update((c) => c + 1);
  }

  function resetCount() {
    count.set(0);
  }

  return { count, increment, resetCount };
}
```

```svelte
// Counter.svelte
<script lang="ts">
  import { useCounter } from './useCounter';
  const { count, increment } = useCounter();
</script>

<button onclick={() => increment()}>Count: {$count}</button>
```

--------------------------------

### Calculate and Add Metadata from Images

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/metadata.md

Demonstrates iterating through a dataset, opening each image, calculating derived statistics like luminance and color channel ratios, and then updating the dataset metadata in a single bulk operation. Uses tqdm for progress indication.

```python
import lightly_studio as ls
import tqdm
from PIL import Image, ImageStat

dataset = ls.ImageDataset.load()

sample_metadata = []
for sample in tqdm.tqdm(dataset):
    with Image.open(sample.file_path_abs) as img:
        rgb = img.convert("RGB")
        channel_sums = ImageStat.Stat(rgb).sum  # [sum_R, sum_G, sum_B]
        luminance = ImageStat.Stat(rgb.convert("L")).mean[0]

    total = sum(channel_sums) or 1  # avoid divide-by-zero on fully black images
    sample_metadata.append(
        (
            sample.sample_id,
            {
                "luminance": luminance,
                "red_ratio": channel_sums[0] / total,
                "green_ratio": channel_sums[1] / total,
                "blue_ratio": channel_sums[2] / total,
            },
        )
    )

dataset.update_metadata(sample_metadata)
```

--------------------------------

### Run All Tests with Makefile

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Execute all configured tests for the project using the Makefile. This is a convenient way to run both backend and frontend tests.

```bash
make test
```

--------------------------------

### Import Lightly Studio and Utilities

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/dataset_setup/notebooks.md

Imports the necessary Lightly Studio library and utility functions for dataset operations.

```python
import lightly_studio as ls
from lightly_studio.utils import download_example_dataset
```

--------------------------------

### Complex LQL Query: Combining Annotation Functions

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/concepts_and_tools/lightly_query_language.md

This example demonstrates a nested query that combines classification and multiple annotation functions (object_detection and segmentation_mask) using OR logic for the annotation results.

```mysql
# Nested query combining multiple annotation functions
"reviewed" IN tags
AND classification(class_name = "urban-scene")
AND (
    object_detection(class_name = "person" AND height >= 120)
    OR segmentation_mask(class_name = "road" AND width > 300)
)
```

--------------------------------

### Python Test Class Structure

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/python.md

Demonstrates a typical structure for a Python test class using a common testing framework. It includes examples of basic test methods and methods designed to test specific scenarios or special cases.

```python
class TestMyClass:
    def test_init(self): ...
    def test_init__some_special_case(self): ...
    def test_foo(self): ...
    
    def test_{method_name_underscores_stripped}{__special_case} | ''
    
class TestInternalClass:
    def test_helper_method(self): ...
    def test_helper_method__my_special_case(self): ...
        
def test_bar(): ...
def test_helper_func(): ...
```

--------------------------------

### Run E2E Tests for Videos

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Execute end-to-end tests for video functionality. Navigate to the frontend directory and run the video test command.

```bash
cd lightly_studio_view
npm run test:e2e-videos
```

--------------------------------

### Python Assertion Example for Standard Deviation

Source: https://github.com/lightly-ai/lightly-studio/blob/main/ai_guidelines/python.md

Use assertions to document expected values or invariants, particularly in private functions where calling code ensures preconditions. Avoid assertions for user input validation; use exceptions instead.

```python
def get_metrics(values: list[float]) -> Something:
    ...
    if len(values) < 2:
        std = 0 # Or an Error is raised.
    else:
        std = _get_std(values)
    ...

def _get_std(sequence: Sequence[float]) -> float:
    """Gets the standard deviation of a sequence

    Args:
        sequence:
            The sequence to get the std of.
            Must have a length >= 2.

    Returns:
            The standard deviation of a sequence.

    """

    assert len(sequence) >= 2
    return np.std(sequence)
```

--------------------------------

### Load YOLO Object Detection Dataset

Source: https://github.com/lightly-ai/lightly-studio/blob/main/lightly_studio/docs/docs/index.md

This snippet shows how to load a YOLO object detection dataset. It downloads example data, creates an ImageDataset, and adds samples using a YOLO data YAML file. Use this for datasets formatted for YOLO.

```python
import lightly_studio as ls

# Download the example dataset (will be skipped if it already exists)
dataset_path = ls.utils.download_example_dataset(download_dir="dataset_examples")

dataset = ls.ImageDataset.load_or_create()
dataset.add_samples_from_yolo(
    data_yaml=f"{dataset_path}/road_signs_yolo/data.yaml",
)

ls.start_gui()
```

--------------------------------

### Format Code with Makefile

Source: https://github.com/lightly-ai/lightly-studio/blob/main/CONTRIBUTING.md

Format the project's code according to the defined style guidelines using the Makefile. This ensures code consistency across the project.

```bash
make format
```