Coming soon/api/

Python API, once the package is actually ready.

The API docs are being kept as the intended package surface, not a live PyPI promise. CLI stays usable from source while the Python package gets cleaned up properly.

Python API status: coming soon.

This is the intended package surface, not a live PyPI promise. Use the CLI from source today; publish the Python package only after the wheel, metadata, and imports are verified.

Planned quickstartThe intended one-call path once the package is actually shipped. Tune every thresholdFace size, confidence, blur, similarity, workers, output folders. Planned model hooksTarget support for detector, embedding, grouping, or InsightFace pack overrides. Planned staged runsDetect once, regroup many times with different rules after the package ships. Planned callbacksTarget callbacks for notebooks, logs, dashboards, or workers. Prefer terminal control?Use the CLI for dry-runs, JSON config, and batch scripts.

Package status: coming soon

The Python API should ship like a normal package, but it should not pretend to be on PyPI before the release is actually done.

# planned
python -m pip install sortmoments

For now, treat this page as the target API shape. The CLI remains the safer published path until the PyPI package, wheel metadata, and import surface are verified.

Next: quickstart · configuration · source CLI setup

Choose the level of control

organize_photos()

Fastest path. Use this for one-off scripts that should match the desktop app defaults.

SortMomentsOrganizer

Reusable object for repeated runs with the same config, model hooks, and callback.

detect_faces()

Run detection and embedding only. Useful when you want to cache face crops/embeddings.

group_faces()

Regroup existing embeddings without redetecting faces. Good for threshold experiments.

Control map

Sort Moments exposes control at the places advanced users normally need it: input/output, filtering, performance, model selection, grouping, and observability.

Folder control

Set input_folder, work_folder, final_output_folder, and session_id.

Output control →

Quality filters

Adjust face size, confidence, face ratio, foreground ratio, and blur thresholds.

Config reference →

Performance

Change batch size, worker count, GPU preference, model pack, and detector input size.

Performance fields →

Model swapping

Inject detector, embedder, and grouping strategy objects without forking the app.

Model swapping guide →

First useful script

from sortmoments import SortMomentsConfig, SortMomentsOrganizer

def progress(current, total, message):
    print(f"[{current}/{total}] {message}")

organizer = SortMomentsOrganizer(
    SortMomentsConfig(
        final_output_folder="D:/sorted/family",
        similarity_threshold=0.58,
        batch_size=8,
        max_workers=4,
        keep_intermediate=True,
    ),
    progress_callback=progress,
)

result = organizer.organize("D:/photos/family-archive")
print(result.output_folder)
print(result.person_count, "people")

Documentation routes

These are intentionally separate URLs, not one overloaded /api page.

/api/how-to/Guided recipes/api/reference/Classes, fields, returns/api/model-swapping/Custom models and contracts/cli/No-GUI terminal workflow