libavalon 0.0.1__py3-none-any.whl

avalon/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

avalon/analysis/essentia_analyzer.py

@@ -0,0 +1,140 @@
+"""Runs the full Essentia extraction roster against audio files.
+
+One embedding pass (discogs-effnet) feeds every classifier head, so
+breadth is cheap -- this is the "extract as much information as we can
+from essentia" implementation, not a curated subset.
+
+Loading a TensorFlow graph has real fixed overhead (~1-2s each); with 14
+classifier heads plus the embedding extractor, reloading all of them for
+every file measured at ~25s/track. Loading them once and reusing the
+loaded graphs across files drops that to ~1.1s/track (measured), which is
+the difference between a usable batch tool and one that takes days on a
+real library. `EssentiaAnalyzer` is therefore a reusable object, not a
+stateless function: construct one per CLI run and call `.analyze()` per
+file.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import numpy as np
+
+from avalon.analysis import model_cache
+from avalon.constants import to_camelot
+from avalon.models import Label, TrackAnalysis
+
+logger = logging.getLogger(__name__)
+
+_ANALYSIS_SAMPLE_RATE = 44100
+_EMBEDDING_SAMPLE_RATE = 16000
+_TOP_N_BY_MODEL = {"genre_discogs400": 3, "mtg_jamendo_moodtheme": 5}
+
+
+def _clean_label(raw: str) -> str:
+    """ "Electronic---Techno" -> "Electronic / Techno" for readability."""
+    return raw.replace("---", " / ")
+
+
+class EssentiaAnalyzer:
+    """Loads every model once; call `analyze(path)` per file."""
+
+    def __init__(self) -> None:
+        os.environ.setdefault("TF_CPP_MIN_LOG_LEVEL", "3")
+
+        import essentia
+        import essentia.standard as es
+
+        essentia.log.warningActive = False
+        essentia.log.infoActive = False
+
+        self._es = es
+        embedding_pb, embedding_output = model_cache.get_embedding_model()
+        self._embedding_algo = es.TensorflowPredictEffnetDiscogs(
+            graphFilename=embedding_pb, output=embedding_output
+        )
+        self._classifiers: dict[str, tuple[object, model_cache.ModelMeta]] = {}
+        for spec in model_cache.CLASSIFIER_HEADS:
+            meta = model_cache.get_classifier(spec)
+            algo = es.TensorflowPredict2D(
+                graphFilename=meta.pb_path,
+                input=meta.input_name,
+                output=meta.output_name,
+            )
+            self._classifiers[spec.name] = (algo, meta)
+
+    def analyze(self, path: str) -> TrackAnalysis:
+        es = self._es
+
+        rhythm_audio = es.MonoLoader(filename=path, sampleRate=_ANALYSIS_SAMPLE_RATE)()
+        bpm, _beats, bpm_confidence, _estimates, _intervals = es.RhythmExtractor2013(
+            method="multifeature"
+        )(rhythm_audio)
+        key, scale, key_strength = es.KeyExtractor()(rhythm_audio)
+        dynamic_complexity, loudness = es.DynamicComplexity()(rhythm_audio)
+
+        embedding_audio = es.Resample(
+            inputSampleRate=_ANALYSIS_SAMPLE_RATE,
+            outputSampleRate=_EMBEDDING_SAMPLE_RATE,
+            quality=4,
+        )(rhythm_audio)
+        embeddings = self._embedding_algo(embedding_audio)
+
+        binary_probs: dict[str, float] = {}
+        categorical: dict[str, tuple[str, float]] = {}
+        multilabel: dict[str, list[Label]] = {}
+
+        for spec in model_cache.CLASSIFIER_HEADS:
+            algo, meta = self._classifiers[spec.name]
+            track_scores = np.mean(algo(embeddings), axis=0)
+
+            if spec.kind == "binary":
+                binary_probs[spec.name] = float(
+                    track_scores[meta.classes.index(spec.positive_label)]
+                )
+            elif spec.kind == "categorical":
+                idx = int(np.argmax(track_scores))
+                categorical[spec.name] = (meta.classes[idx], float(track_scores[idx]))
+            elif spec.kind == "multilabel":
+                top_n = _TOP_N_BY_MODEL[spec.name]
+                order = np.argsort(track_scores)[::-1][:top_n]
+                multilabel[spec.name] = [
+                    Label(
+                        name=_clean_label(meta.classes[i]),
+                        confidence=float(track_scores[i]),
+                    )
+                    for i in order
+                ]
+            else:
+                raise ValueError(f"Unknown model kind: {spec.kind!r}")
+
+        gender_label, gender_confidence = categorical["gender"]
+        timbre_label, timbre_confidence = categorical["timbre"]
+
+        return TrackAnalysis(
+            bpm=float(bpm),
+            bpm_confidence=float(bpm_confidence),
+            key=key,
+            scale=scale,
+            camelot=to_camelot(key, scale),
+            key_strength=float(key_strength),
+            loudness=float(loudness),
+            dynamic_complexity=float(dynamic_complexity),
+            mood_aggressive=binary_probs["mood_aggressive"],
+            mood_happy=binary_probs["mood_happy"],
+            mood_sad=binary_probs["mood_sad"],
+            mood_relaxed=binary_probs["mood_relaxed"],
+            mood_party=binary_probs["mood_party"],
+            danceability=binary_probs["danceability"],
+            mood_acoustic=binary_probs["mood_acoustic"],
+            mood_electronic=binary_probs["mood_electronic"],
+            voice_probability=binary_probs["voice_instrumental"],
+            gender=gender_label,
+            gender_confidence=gender_confidence,
+            tonal_probability=binary_probs["tonal_atonal"],
+            timbre=timbre_label,
+            timbre_confidence=timbre_confidence,
+            genres=multilabel["genre_discogs400"],
+            mood_themes=multilabel["mtg_jamendo_moodtheme"],
+        )

avalon/analysis/model_cache.py

@@ -0,0 +1,140 @@
+"""Downloads and caches the Essentia pretrained models avalon uses.
+
+Each model's input/output tensor names and class label order come from its
+`.json` sidecar at run time rather than being hardcoded: node names vary
+per model (e.g. genre_discogs400 uses a different input node than the
+mood/character heads), and -- more importantly -- class order is *not*
+consistent (`mood_sad` is `["non_sad", "sad"]` while `mood_happy` is
+`["happy", "non_happy"]`). Trusting the declared schema avoids silently
+inverted probabilities.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import requests
+
+from avalon.constants import MODEL_CACHE_DIRNAME
+
+logger = logging.getLogger(__name__)
+
+_BASE_URL = "https://essentia.upf.edu/models"
+_EMBEDDING_SUBDIR = "feature-extractors/discogs-effnet"
+_EMBEDDING_STEM = "discogs-effnet-bs64-1"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSpec:
+    """One classifier head. `kind` drives how essentia_analyzer reads its
+    output vector:
+      binary      -> single probability of `positive_label`
+      categorical -> whichever of `labels` scores highest, plus its confidence
+      multilabel  -> independent (sigmoid) scores, no single "positive" class
+    """
+
+    name: str
+    subdir: str
+    kind: str
+    positive_label: str | None = None
+
+
+CLASSIFIER_HEADS: tuple[ModelSpec, ...] = (
+    ModelSpec("danceability", "danceability", "binary", positive_label="danceable"),
+    ModelSpec("mood_acoustic", "mood_acoustic", "binary", positive_label="acoustic"),
+    ModelSpec(
+        "mood_aggressive", "mood_aggressive", "binary", positive_label="aggressive"
+    ),
+    ModelSpec(
+        "mood_electronic", "mood_electronic", "binary", positive_label="electronic"
+    ),
+    ModelSpec("mood_happy", "mood_happy", "binary", positive_label="happy"),
+    ModelSpec("mood_sad", "mood_sad", "binary", positive_label="sad"),
+    ModelSpec("mood_relaxed", "mood_relaxed", "binary", positive_label="relaxed"),
+    ModelSpec("mood_party", "mood_party", "binary", positive_label="party"),
+    ModelSpec(
+        "voice_instrumental", "voice_instrumental", "binary", positive_label="voice"
+    ),
+    ModelSpec("tonal_atonal", "tonal_atonal", "binary", positive_label="tonal"),
+    ModelSpec("gender", "gender", "categorical"),
+    ModelSpec("timbre", "timbre", "categorical"),
+    ModelSpec("genre_discogs400", "genre_discogs400", "multilabel"),
+    ModelSpec("mtg_jamendo_moodtheme", "mtg_jamendo_moodtheme", "multilabel"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ModelMeta:
+    """Parsed `.json` sidecar: local file path plus the schema bits needed
+    to run inference generically."""
+
+    pb_path: str
+    input_name: str
+    output_name: str
+    classes: tuple[str, ...]
+
+
+def _cache_dir() -> Path:
+    path = Path.home() / ".cache" / MODEL_CACHE_DIRNAME / "models"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _download(url: str, dest: Path) -> None:
+    if dest.exists():
+        return
+    logger.info("Downloading model file %s", url)
+    response = requests.get(url, timeout=60)
+    response.raise_for_status()
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    tmp.write_bytes(response.content)
+    tmp.rename(dest)
+
+
+def _fetch(subdir: str, filename_stem: str) -> tuple[Path, dict]:
+    cache = _cache_dir()
+    pb_dest = cache / f"{filename_stem}.pb"
+    json_dest = cache / f"{filename_stem}.json"
+    base = f"{_BASE_URL}/{subdir}/{filename_stem}"
+    _download(f"{base}.pb", pb_dest)
+    _download(f"{base}.json", json_dest)
+    return pb_dest, json.loads(json_dest.read_text())
+
+
+def _output_by_purpose(outputs: list[dict], purpose: str) -> str:
+    for out in outputs:
+        if out.get("output_purpose") == purpose:
+            return out["name"]
+    return outputs[0]["name"]
+
+
+def get_embedding_model() -> tuple[str, str]:
+    """Downloads (if needed) the shared discogs-effnet embedding extractor.
+
+    Returns (pb_path, embedding_output_node_name).
+    """
+    pb_path, meta = _fetch(_EMBEDDING_SUBDIR, _EMBEDDING_STEM)
+    output_name = _output_by_purpose(meta["schema"]["outputs"], "embeddings")
+    return str(pb_path), output_name
+
+
+def get_classifier(spec: ModelSpec) -> ModelMeta:
+    filename_stem = f"{spec.name}-discogs-effnet-1"
+    pb_path, meta = _fetch(f"classification-heads/{spec.subdir}", filename_stem)
+    schema = meta["schema"]
+    return ModelMeta(
+        pb_path=str(pb_path),
+        input_name=schema["inputs"][0]["name"],
+        output_name=_output_by_purpose(schema["outputs"], "predictions"),
+        classes=tuple(meta["classes"]),
+    )
+
+
+def prefetch_all() -> None:
+    """Downloads every model avalon needs, up front (~26.5MB total)."""
+    get_embedding_model()
+    for spec in CLASSIFIER_HEADS:
+        get_classifier(spec)

avalon/cli.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import random
+import sys
+from collections.abc import Callable, Iterator
+from concurrent.futures import FIRST_COMPLETED, Future, ProcessPoolExecutor, wait
+from pathlib import Path
+
+from avalon.constants import AUDIO_EXTENSIONS
+from avalon.models import ProcessResult
+from avalon.pathing import DEFAULT_TEMPLATE
+from avalon.pipeline import Pipeline, PipelineOptions, init_worker, process_planned_in_worker
+from avalon.tagging import analysis_blob, tag_writer
+from avalon import state as state_module
+from avalon import watcher
+
+logger = logging.getLogger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="avalon", description="Audio analysis, tagging, and organization"
+    )
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose (info) logging"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    _add_pipeline_flags(_add_analyze_parser(subparsers))
+    _add_pipeline_flags(_add_watch_parser(subparsers))
+    _add_inspect_parser(subparsers)
+    return parser
+
+
+def _add_analyze_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "analyze", help="Analyze/tag/convert a file or folder"
+    )
+    parser.add_argument(
+        "sources", nargs="+", help="Audio file(s) or folder(s) to process"
+    )
+    parser.add_argument(
+        "--recursive", action="store_true", help="Recurse into subfolders"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would happen without writing anything",
+    )
+    parser.add_argument(
+        "--random",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Process a random sample of N files instead of everything found "
+        "(fast, repeatable smoke-testing on a large library)",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        metavar="N",
+        help="Process N files concurrently in separate worker processes (default: 1, sequential)",
+    )
+    parser.set_defaults(func=run_analyze)
+    return parser
+
+
+def _add_watch_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "watch", help="Watch folder(s) and process new/changed files"
+    )
+    parser.add_argument("sources", nargs="+", help="Folder(s) to watch")
+    parser.add_argument(
+        "--debounce-seconds",
+        type=int,
+        default=5,
+        help="Quiet period before processing a file (default: 5)",
+    )
+    parser.add_argument(
+        "--no-backfill",
+        action="store_true",
+        help="Skip processing pre-existing files on startup",
+    )
+    parser.set_defaults(func=run_watch)
+    return parser
+
+
+def _headline_fields_type(raw: str) -> tuple[str, ...]:
+    try:
+        return analysis_blob.parse_headline_fields(raw)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
+
+
+def _add_pipeline_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--dest", type=str, default=None, help="Destination root; omit to tag in place"
+    )
+    parser.add_argument("--path-template", type=str, default=DEFAULT_TEMPLATE)
+    parser.add_argument(
+        "--convert-lossless-to",
+        type=str,
+        default=None,
+        help="Re-encode lossless sources (FLAC/ALAC/WAV/AIFF/...) to this format (e.g. aiff); "
+        "lossy sources (mp3, aac, ...) are left untouched regardless",
+    )
+    parser.add_argument("--max-sample-rate", type=int, default=None)
+    parser.add_argument("--max-bit-depth", type=int, default=None)
+    parser.add_argument(
+        "--no-analyze", action="store_true", help="Skip essentia analysis"
+    )
+    parser.add_argument(
+        "--no-convert", action="store_true", help="Skip format/rate/depth conversion"
+    )
+    parser.add_argument(
+        "--force-reanalyze",
+        action="store_true",
+        help="Re-run analysis even if already current",
+    )
+    parser.add_argument(
+        "--overwrite", action="store_true", help="Overwrite existing destination files"
+    )
+    parser.add_argument(
+        "--overwrite-description",
+        action="store_true",
+        help="Replace the headline tag instead of merging into it",
+    )
+    parser.add_argument(
+        "--headline-tag",
+        type=str,
+        default=None,
+        help="Tag/field name to write the headline to (default: COMM for MP3/AIFF/WAV, "
+        "DESCRIPTION for FLAC, desc for MP4). A name other than the default becomes a "
+        "TXXX frame (ID3-family) or freeform atom (MP4) rather than the native comment field",
+    )
+    parser.add_argument(
+        "--headline-format",
+        type=_headline_fields_type,
+        default=analysis_blob.DEFAULT_HEADLINE_FIELDS,
+        help="Comma-separated fields (and order) for the headline tag. Available: "
+        f"{', '.join(analysis_blob.HEADLINE_FIELD_VALUES)} "
+        f"(default: {','.join(analysis_blob.DEFAULT_HEADLINE_FIELDS)})",
+    )
+    parser.add_argument(
+        "--delete-original",
+        action="store_true",
+        help="Delete the source file after successful processing",
+    )
+
+
+def _add_inspect_parser(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "inspect", help="Show a file's parsed canonical + analysis tags"
+    )
+    parser.add_argument("path", help="Audio file to inspect")
+    parser.set_defaults(func=run_inspect)
+
+
+def setup_logging(debug: bool, verbose: bool) -> None:
+    level = logging.DEBUG if debug else (logging.INFO if verbose else logging.WARNING)
+    logging.basicConfig(
+        level=level, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    logging.getLogger("urllib3").setLevel(logging.INFO)
+
+
+def _is_audio_file(path: Path) -> bool:
+    return path.suffix.lower() in AUDIO_EXTENSIONS and not path.name.startswith("._")
+
+
+def _iter_files_shuffled(root: Path, recursive: bool) -> Iterator[Path]:
+    with os.scandir(root) as it:
+        entries = list(it)
+    random.shuffle(entries)
+    subdirs = []
+    for entry in entries:
+        if entry.is_file():
+            yield Path(entry.path)
+        elif recursive and entry.is_dir():
+            subdirs.append(entry.path)
+    for subdir in subdirs:
+        yield from _iter_files_shuffled(Path(subdir), recursive)
+
+
+def gather_files(
+    sources: list[str], recursive: bool, sample_size: int | None = None
+) -> Iterator[Path]:
+    found = 0
+    for source in sources:
+        path = Path(source)
+        if path.is_file():
+            if _is_audio_file(path):
+                yield path
+                found += 1
+                if sample_size is not None and found >= sample_size:
+                    return
+            continue
+        if not path.is_dir():
+            logger.warning("Source not found: %s", path)
+            continue
+        walker = (
+            _iter_files_shuffled(path, recursive)
+            if sample_size is not None
+            else (path.rglob("*") if recursive else path.glob("*"))
+        )
+        for p in walker:
+            if p.is_file() and _is_audio_file(p):
+                yield p
+                found += 1
+                if sample_size is not None and found >= sample_size:
+                    return
+
+
+def _default_state_dir(first_source: str) -> Path:
+    path = Path(first_source).resolve()
+    return path if path.is_dir() else path.parent
+
+
+def _pipeline_options_from_args(args: argparse.Namespace) -> PipelineOptions:
+    return PipelineOptions(
+        dest_root=Path(args.dest) if args.dest else None,
+        path_template=args.path_template,
+        convert_lossless_to=args.convert_lossless_to,
+        max_sample_rate=args.max_sample_rate,
+        max_bit_depth=args.max_bit_depth,
+        do_analyze=not args.no_analyze,
+        do_convert=not args.no_convert,
+        force_reanalyze=args.force_reanalyze,
+        overwrite=args.overwrite,
+        overwrite_description=args.overwrite_description,
+        headline_tag=args.headline_tag,
+        headline_fields=args.headline_format,
+        delete_original=args.delete_original,
+        dry_run=getattr(args, "dry_run", False),
+    )
+
+
+def _process_parallel(
+    pipeline: Pipeline,
+    paths: Iterator[Path],
+    workers: int,
+    handle: Callable[[Path, ProcessResult], None],
+) -> None:
+    max_in_flight = workers * 2
+    with ProcessPoolExecutor(
+        max_workers=workers, initializer=init_worker, initargs=(pipeline.options,)
+    ) as executor:
+        in_flight: dict[Future, Path] = {}
+
+        def submit_next() -> bool:
+            path = next(paths, None)
+            if path is None:
+                return False
+            try:
+                planned = pipeline.plan(path)
+            except Exception as exc:
+                handle(
+                    path,
+                    ProcessResult(
+                        source_path=str(path),
+                        output_path=str(path),
+                        analyzed=False,
+                        converted=False,
+                        error=str(exc),
+                    ),
+                )
+                return True
+            in_flight[executor.submit(process_planned_in_worker, planned)] = path
+            return True
+
+        while len(in_flight) < max_in_flight and submit_next():
+            pass
+        while in_flight:
+            done, _ = wait(in_flight, return_when=FIRST_COMPLETED)
+            for future in done:
+                path = in_flight.pop(future)
+                handle(path, future.result())
+                submit_next()
+
+
+def run_analyze(args: argparse.Namespace) -> int:
+    options = _pipeline_options_from_args(args)
+    pipeline = Pipeline(options)
+    dest_root = options.dest_root or _default_state_dir(args.sources[0])
+    state = state_module.load(dest_root)
+    skip_fast_path = args.dry_run or args.force_reanalyze
+
+    def unprocessed() -> Iterator[Path]:
+        for path in gather_files(args.sources, args.recursive, sample_size=args.random):
+            if not skip_fast_path and state_module.is_unchanged(state, path):
+                logger.debug("Unchanged, skipping: %s", path)
+                continue
+            yield path
+
+    failures: list[tuple[Path, str]] = []
+    processed = 0
+
+    def handle(path: Path, result: ProcessResult) -> None:
+        nonlocal processed
+        if result.error:
+            failures.append((path, result.error))
+            logger.error("Failed: %s: %s", path, result.error)
+            return
+        processed += 1
+        logger.info(
+            "%s%s -> %s",
+            "[dry-run] " if args.dry_run else "",
+            path,
+            result.output_path,
+        )
+        if not args.dry_run:
+            state_module.record(state, path)
+
+    if args.workers > 1:
+        _process_parallel(pipeline, unprocessed(), args.workers, handle)
+    else:
+        for path in unprocessed():
+            handle(path, pipeline.process_file(path))
+
+    if not args.dry_run:
+        state_module.save(dest_root, state)
+
+    logger.info("Processed %d file(s), %d failure(s)", processed, len(failures))
+    return 0 if not failures else 2
+
+
+def run_watch(args: argparse.Namespace) -> int:
+    source_roots = [Path(s).resolve() for s in args.sources]
+    missing = [s for s in source_roots if not s.is_dir()]
+    if missing:
+        for path in missing:
+            logger.error("Source folder not found: %s", path)
+        return 1
+
+    options = _pipeline_options_from_args(args)
+    pipeline = Pipeline(options)
+    dest_root = options.dest_root or source_roots[0]
+    state = state_module.load(dest_root)
+
+    skip_fast_path = args.force_reanalyze
+
+    def handle(path: Path) -> None:
+        if not skip_fast_path and state_module.is_unchanged(state, path):
+            return
+        result = pipeline.process_file(path)
+        if result.error:
+            logger.error("Failed: %s: %s", path, result.error)
+        else:
+            logger.info("%s -> %s", path, result.output_path)
+            state_module.record(state, path)
+            state_module.save(dest_root, state)
+
+    if not args.no_backfill:
+        logger.info("Backfilling existing files")
+        for path in gather_files([str(root) for root in source_roots], recursive=True):
+            handle(path)
+
+    watcher.watch(source_roots, handle, debounce_seconds=args.debounce_seconds)
+    return 0
+
+
+def run_inspect(args: argparse.Namespace) -> int:
+    path = args.path
+    file_format = tag_writer.detect_format(path)
+    audio = tag_writer.load(path, file_format)
+
+    print(f"path: {path}")
+    print(f"format: {file_format.value}")
+    print("\ncanonical fields:")
+    for key, value in tag_writer.read_canonical(audio, file_format).items():
+        print(f"  {key}: {value}")
+
+    headline = tag_writer.read_headline(audio, file_format)
+    print(f"\nheadline tag (raw): {headline}")
+    parsed_headline = analysis_blob.parse_headline(headline)
+    if parsed_headline:
+        print("headline tag (parsed):")
+        for key, value in parsed_headline.items():
+            print(f"  {key}: {value}")
+
+    extended = tag_writer.read_extended(audio, file_format)
+    print(f"\nextended tag (raw): {extended}")
+    if extended:
+        print("extended tag (parsed):")
+        for key, value in analysis_blob.decode_extended(extended).items():
+            print(f"  {key}: {value}")
+        for field in ("genre", "moodtheme"):
+            labels = analysis_blob.decode_extended_labels(extended, field)
+            if labels:
+                print(
+                    f"  {field} labels: "
+                    + ", ".join(
+                        f"{label.name} ({label.confidence:.2f})" for label in labels
+                    )
+                )
+    return 0
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    setup_logging(args.debug, args.verbose)
+    exit_code = args.func(args)
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()