CLI

docs/CLI_TEST_CHECKLIST.md

@@ -0,0 +1,156 @@
+# CLI Test Checklist
+
+Test commands for the LibreYOLO CLI before merging.
+Uses `coco8.yaml` (8 images) for fast training/validation runs.
+
+## Special Commands
+
+```bash
+# Help (no args)
+libreyolo
+
+# Version
+libreyolo version
+libreyolo version --json
+
+# System checks
+libreyolo checks
+libreyolo checks --json
+
+# List models
+libreyolo models
+libreyolo models --json
+
+# List export formats
+libreyolo formats
+libreyolo formats --json
+
+# Default config
+libreyolo cfg
+libreyolo cfg --json
+
+# Model info (downloads yolox-s if not present)
+libreyolo info model=yolox-s
+libreyolo info model=yolox-s --json
+```
+
+## Predict
+
+```bash
+# Basic inference
+libreyolo predict source=libreyolo/assets/parkour.jpg model=yolox-s
+
+# With conf threshold
+libreyolo predict source=libreyolo/assets/parkour.jpg model=yolox-s conf=0.5
+
+# JSON output
+libreyolo predict source=libreyolo/assets/parkour.jpg model=yolox-s --json --quiet
+
+# Save annotated image
+libreyolo predict source=libreyolo/assets/parkour.jpg model=yolox-s save
+
+# Bare bool flags
+libreyolo predict source=libreyolo/assets/parkour.jpg model=yolox-s half save
+
+# --key value syntax (standard CLI)
+libreyolo predict --source libreyolo/assets/parkour.jpg --model yolox-s --conf 0.5
+
+# Mixed syntax
+libreyolo predict source=libreyolo/assets/parkour.jpg --model yolox-s conf=0.5
+
+# Task prefix (detect is stripped)
+libreyolo detect predict source=libreyolo/assets/parkour.jpg model=yolox-s
+
+# YOLOv9 model (auto-downloads)
+libreyolo predict source=libreyolo/assets/parkour.jpg model=yolo9-t
+
+# Local weights path
+libreyolo predict source=libreyolo/assets/parkour.jpg model=weights/LibreYOLOXs.pt
+
+# Schema discovery
+libreyolo predict --help-json
+libreyolo predict --help
+```
+
+## Train
+
+```bash
+# YOLOX — short real training on coco8
+libreyolo train data=coco8.yaml model=yolox-s epochs=3 batch=4 imgsz=416
+
+# YOLOX — JSON output
+libreyolo train data=coco8.yaml model=yolox-s epochs=3 batch=4 imgsz=416 --json
+
+# YOLOv9 — short real training
+libreyolo train data=coco8.yaml model=yolo9-t epochs=3 batch=4
+
+# RF-DETR — short real training
+libreyolo train data=coco8.yaml model=rfdetr-s epochs=3 batch=2
+
+# Dry run — verify family defaults without training
+libreyolo train data=coco8.yaml model=yolox-s --dry-run --json
+libreyolo train data=coco8.yaml model=yolo9-t --dry-run --json
+libreyolo train data=coco8.yaml model=rfdetr-s --dry-run --json
+
+# User override wins over family default
+libreyolo train data=coco8.yaml model=yolox-s momentum=0.5 --dry-run --json
+
+# Schema discovery
+libreyolo train --help-json
+libreyolo train --help
+```
+
+## Val
+
+```bash
+# Validate with pretrained weights
+libreyolo val model=yolox-s data=coco8.yaml
+
+# JSON output
+libreyolo val model=yolox-s data=coco8.yaml --json
+
+# With overrides
+libreyolo val model=yolox-s data=coco8.yaml batch=8 conf=0.01
+
+# Local weights
+libreyolo val model=weights/LibreYOLOXs.pt data=coco8.yaml
+
+# YOLOv9
+libreyolo val model=yolo9-t data=coco8.yaml
+```
+
+## Export
+
+```bash
+# ONNX export
+libreyolo export model=weights/LibreYOLOXs.pt format=onnx
+
+# ONNX with options
+libreyolo export model=weights/LibreYOLOXs.pt format=onnx half dynamic
+
+# JSON output
+libreyolo export model=weights/LibreYOLOXs.pt format=onnx --json
+
+# TensorRT (engine alias)
+libreyolo export model=weights/LibreYOLOXs.pt format=engine half
+
+# OpenVINO
+libreyolo export model=weights/LibreYOLOXs.pt format=openvino
+```
+
+## Error Cases
+
+```bash
+# Missing source file
+libreyolo predict source=nonexistent.jpg model=yolox-s
+
+# Missing source — JSON error
+libreyolo predict source=nonexistent.jpg model=yolox-s --json
+
+# Missing required arg
+libreyolo train model=yolox-s
+libreyolo predict model=yolox-s
+
+# Half + int8 conflict
+libreyolo export model=weights/LibreYOLOXs.pt format=onnx half int8
+```

libreyolo/cli/__init__.py

@@ -0,0 +1,67 @@
+"""LibreYOLO CLI — ultralytics-compatible command-line interface.
+
+Entry point registered in pyproject.toml as ``libreyolo``.
+"""
+
+import sys
+
+import typer
+
+app = typer.Typer(
+    name="libreyolo",
+    help="LibreYOLO — open source YOLO detection toolkit.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+def _strip_task_prefix() -> None:
+    """Strip optional 'detect' task prefix from argv.
+
+    ``libreyolo detect predict ...`` becomes ``libreyolo predict ...``.
+    """
+    known_tasks = {"detect"}
+    args = sys.argv[1:]
+    if args and args[0] in known_tasks:
+        sys.argv = [sys.argv[0]] + args[1:]
+
+
+def _setup_logging_from_argv() -> None:
+    """Configure logging early, before Typer parses args.
+
+    Peeks at sys.argv for --quiet/--verbose so the logger is ready
+    before any command code runs.
+    """
+    from ..utils.logging import setup_logging
+
+    args = sys.argv[1:]
+    quiet = "--quiet" in args
+    verbose = "--verbose" in args
+    setup_logging(quiet=quiet, verbose=verbose)
+
+
+def entrypoint() -> None:
+    """CLI entry point registered in pyproject.toml."""
+    import warnings
+
+    warnings.filterwarnings("ignore")
+
+    _strip_task_prefix()
+    _setup_logging_from_argv()
+
+    from .commands import special, predict, train, val, export  # noqa: F401
+    from .parsing import KeyValueCommand
+
+    # Special commands
+    for cmd_name in ("version", "checks", "models", "formats", "cfg", "info"):
+        app.command(cmd_name, cls=KeyValueCommand)(
+            getattr(special, f"{cmd_name}_cmd")
+        )
+
+    # Core mode commands
+    app.command("predict", cls=KeyValueCommand)(predict.predict_cmd)
+    app.command("train", cls=KeyValueCommand)(train.train_cmd)
+    app.command("val", cls=KeyValueCommand)(val.val_cmd)
+    app.command("export", cls=KeyValueCommand)(export.export_cmd)
+
+    app()

libreyolo/cli/aliases.py

@@ -0,0 +1,41 @@
+"""Mode-aware alias resolution for CLI parameter names.
+
+Translates user-facing ultralytics names to internal library field names.
+This is the single source of truth for name translation.
+"""
+
+TRAIN_ALIASES: dict[str, str] = {
+    "mosaic": "mosaic_prob",
+    "mixup": "mixup_prob",
+}
+
+VAL_ALIASES: dict[str, str] = {
+    "batch": "batch_size",
+    "conf": "conf_thres",
+    "iou": "iou_thres",
+    "workers": "num_workers",
+}
+
+# Predict and export use native parameter names — no aliases needed.
+
+_MODE_ALIASES: dict[str, dict[str, str]] = {
+    "train": TRAIN_ALIASES,
+    "val": VAL_ALIASES,
+}
+
+
+def resolve_aliases(overrides: dict, mode: str) -> dict:
+    """Translate CLI-facing keys to internal config field names.
+
+    Args:
+        overrides: Dict of CLI parameter names and values.
+        mode: Command mode ("train", "val", "predict", "export").
+
+    Returns:
+        Dict with internal field names.
+    """
+    aliases = _MODE_ALIASES.get(mode, {})
+    resolved = {}
+    for key, value in overrides.items():
+        resolved[aliases.get(key, key)] = value
+    return resolved

libreyolo/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""