Skip to content

CLAUDE.md

Latest commit

 

History

History
124 lines (95 loc) · 5.95 KB

CLAUDE.md

File metadata and controls

124 lines (95 loc) · 5.95 KB
Raw

CLAUDE.md

Guidance for AI assistants working in this repo. For full contributor etiquette (issues, PR process, forking), see CONTRIBUTING.md; for maintainer-only tasks, see MAINTAINING.md.

Project overview

lightly (lightly-ssl) is a self-supervised learning (SSL) library for computer vision, built on PyTorch / PyTorch Lightning. It implements 19+ SSL methods (SimCLR, MoCo, BYOL, DINO, DINOv2, SwaV, VICReg, Barlow Twins, FroSSL, DetConS, LeJEPA, etc.).

Main entry points:

  • lightly.models — backbones + method-specific heads
  • lightly.loss — SSL loss implementations
  • lightly.transforms — method-specific augmentation pipelines
  • lightly.data — dataset wrapper + collate functions
  • lightly.cli — lightly-* command-line tools (train, embed, crop, magic)
  • lightly.core — one-liner convenience APIs

Repo layout

  • lightly/ — the package (flat layout, no src/)
  • tests/ — mirrors lightly/'s structure
  • examples/ — training examples in three variants: pytorch/, pytorch_lightning/, pytorch_lightning_distributed/, plus generated notebooks/
  • docs/source/ — Sphinx docs, including one .rst page per SSL method under docs/source/examples/
  • benchmarks/ — benchmark scripts
  • CONTRIBUTING.md, MAINTAINING.md, Makefile, pyproject.toml

Setup & common commands

Package manager is uv.

make install-dev

This synchronizes the project environment from the lockfile and installs the pre-commit hooks. Commands should be run through the Makefile or uv run --frozen; manual virtual environment activation is not required.

Command Purpose
make format Auto-fix imports/formatting/lint with ruff
make format-check Check formatting and lint without fixing
make type-check mypy on lightly and tests
make lock Regenerate uv.lock after changing dependencies
make lock-check Fail if uv.lock is out of date with pyproject.toml
make static-checks lock-check + format-check + type-check
make test pytest tests --runslow (full suite)
make test-fast pytest tests (skips @pytest.mark.slow)
make all-checks static-checks + test
make generate-example-notebooks Regenerate examples/notebooks/* from examples/{pytorch,pytorch_lightning,pytorch_lightning_distributed}
make help List the common targets

The install-* and test-* targets not listed above exist for CI: each workflow job runs exactly one make install-<scenario> followed by one make test-<scenario>. Every install target is a single uv command; never layer extra packages on top of an installed environment.

If make format reports changes, re-run it before make all-checks.

Development commands should be executed through the Makefile or uv run --frozen to ensure they use the locked dependency versions.

Dependencies

All dependencies live in pyproject.toml:

  • [project] dependencies — required at runtime for every user.
  • [project.optional-dependencies] — optional user-facing features (lightly[timm], lightly[video], ...). These ship with the package.
  • [dependency-groups] — development-only, never distributed. dev is installed by default; docs, dist and minimal are opt-in via --group.

After changing dependencies run make lock and commit uv.lock; make static-checks fails when the lockfile is stale.

Code style (see CONTRIBUTING.md for full detail)

  • Google + PyTorch styleguide. Docstrings use triple double quotes and the Google convention (checked by ruff's pydocstyle rules); required on public functions unless very short and obvious.
  • Full type hints everywhere (mypy-clean). Use Python 3.10-style unions (str | Path, not Union[str, Path]); this requires from __future__ import annotations at the top of the module (the package declares requires-python = ">=3.8" and CI tests that lowest supported version).
  • Prefer keyword arguments when calling functions with more than one argument.
  • Import functions via their module (from module import submodule; submodule.fn(...)); import classes directly (from module.submodule import MyClass).

Adding or modifying an SSL method (or a standalone transform/loss/model)

Touch points, mirroring an existing method (e.g. BYOL) as the template:

  1. lightly/models/<name>.py, lightly/loss/<name>_loss.py, lightly/transforms/<name>_transform.py as needed
  2. Export the new symbol from the relevant subpackage __init__.py
  3. Add docs/source/examples/<name>.rst and wire it into its parent toctree
  4. Add example scripts under all three examples/ variants, then run make generate-example-notebooks and commit the regenerated notebooks (they're tracked in git)
  5. Add tests mirrored under tests/{models,loss,transforms}/, following existing naming (e.g. test_ModelsBYOL.py, test_barlow_twins_loss.py, test_byol_transform.py)

Testing

  • pytest, config in tests/conftest.py. Test tree mirrors lightly/.
  • Slow tests are marked @pytest.mark.slow and skipped unless --runslow is passed (make test passes it, make test-fast doesn't).

CI (.github/workflows/)

  • test_code_format.yml — make static-checks
  • test.yml — main unit test suite
  • test_minimal_deps.yml — install with lowest-pinned direct dependencies, then test
  • test_setup.yml — package build/install sanity check
  • check_example_nbs.yml — verifies generated notebooks are up to date with examples/
  • weekly_dependency_test.yml — scheduled test against latest dependency versions
  • release_pypi.yml — publish to PyPI

PR workflow

  • Branch off upstream/master; never commit directly to master.
  • Before committing: make format, then make all-checks (or at least static-checks + targeted tests for faster iterations).
  • If you touched examples/, regenerate notebooks (make generate-example-notebooks) and commit them.
  • If you touched docs/source, verify the docs still build (see docs/README.md).