Add CLI commands for model management (fixes #20)

- Add three new CLI commands using typer:
  - `sct download-models`: Pre-download ML models with progress
  - `sct verify-models`: Verify model presence and integrity
  - `sct model-info`: Display model metadata and status
- Migrate CLI from argparse to typer for better command structure
- Maintain backward compatibility with existing CLI usage
- Add typer as a new dependency
- Update README with new command documentation
- Update CHANGELOG for v0.1.5

Author: claude

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.5] - Unreleased
+
+- Add CLI commands for model management (`download-models`, `verify-models`, `model-info`)
+- Migrate CLI from argparse to typer for better command structure
+- Add typer as a dependency
+- Maintain backward compatibility with existing CLI usage
+
 ## [0.1.4] - 2025-04-24
 
 - Added `bytes_offsets` option to generate UTF-8 byte positions instead of character positions

README.md

@@ -26,6 +26,9 @@ pip install iscc-sct
 python -c "import iscc_sct as sct; print(sct.create('Your text here').iscc)"
 
 # Or use the CLI
+sct gen "path/to/textfile.txt"
+
+# Backward-compatible (old-style command still works)
 sct "path/to/textfile.txt"
 ```
 
@@ -172,20 +175,53 @@ print(f"Hamming distance in bits: {distance}")
 The installation also provides a sct command-line tool:
 
 ```shell
-usage: sct [-h] [-b BITS] [-g] [-d] [path]
+usage: sct [OPTIONS] COMMAND [ARGS]...
+
+Generate Semantic Text-Codes for text files and manage models.
+
+Commands:
+  gen               Generate Semantic Text-Codes for text files.
+  download-models   Download all required models with progress reporting.
+  verify-models     Verify model presence and integrity.
+  model-info        Display model metadata (versions, paths, sizes).
+
+Options:
+  --help            Show this message and exit.
+```
 
-Generate Semantic Text-Codes for text files.
+### CLI Commands
 
-positional arguments:
-  path                  Path to text files (supports glob patterns) or 'gui' to launch Gradio demo.
+#### Generate Semantic Text-Codes
 
-options:
-  -h, --help            show this help message and exit
-  -b BITS, --bits BITS  Bit-Length of Code (default 256)
+```shell
+sct gen [OPTIONS] [PATH]
+
+Options:
+  -b, --bits INTEGER    Bit-Length of Code (default 256)
   -g, --granular        Activate granular processing.
   -d, --debug           Show debugging messages.
 ```
 
+#### Model Management
+
+Pre-download models (useful for containers and CI/CD):
+
+```shell
+sct download-models
+```
+
+Verify model integrity:
+
+```shell
+sct verify-models
+```
+
+Display model information:
+
+```shell
+sct model-info
+```
+
 ## How It Works
 
 ```
@@ -218,7 +254,8 @@ See iscc_sct/options.py for more configuration settings.
 
 ## Performance Considerations
 
-- The embedding model will be downloaded on first execution
+- The embedding model will be downloaded automatically on first execution
+- You can pre-download models using `sct download-models` (useful for containers and CI/CD pipelines)
 - **CPU vs GPU**: On systems with CUDA-compatible GPUs, install with `pip install iscc-sct[gpu]` for
   significantly faster processing.
 

iscc_sct/cli.py

@@ -1,70 +1,160 @@
-import argparse
 import glob
+import sys
 from pathlib import Path
+from typing import Optional
+import typer
 from loguru import logger
 from iscc_sct.main import create
 from charset_normalizer import from_bytes
+from iscc_sct import utils
 
+app = typer.Typer(
+    name="iscc-sct",
+    help="Generate Semantic Text-Codes for text files and manage models.",
+    no_args_is_help=True,
+)
 
-def main():
-    parser = argparse.ArgumentParser(description="Generate Semantic Text-Codes for text files.")
-    parser.add_argument(
-        "path",
-        type=str,
+
+@app.command(name="gen")
+def generate(
+    path: Optional[str] = typer.Argument(
+        None,
         help="Path to text files (supports glob patterns) or 'gui' to launch Gradio demo.",
-        nargs="?",
-    )
-    parser.add_argument(
-        "-b", "--bits", type=int, default=256, help="Bit-Length of Code (default 256)"
-    )
-    parser.add_argument(
-        "-g", "--granular", action="store_true", help="Activate granular processing."
-    )
-    parser.add_argument("-d", "--debug", action="store_true", help="Show debugging messages.")
-    args = parser.parse_args()
-
-    if args.path is None:
-        parser.print_help()
-        return
+    ),
+    bits: int = typer.Option(256, "--bits", "-b", help="Bit-Length of Code (default 256)"),
+    granular: bool = typer.Option(False, "--granular", "-g", help="Activate granular processing."),
+    debug: bool = typer.Option(False, "--debug", "-d", help="Show debugging messages."),
+):
+    """Generate Semantic Text-Codes for text files."""
+    if path is None:
+        typer.echo("Error: Missing path argument")
+        raise typer.Exit(1)
 
-    if not args.debug:
+    if not debug:
         logger.remove()
 
-    if args.path == "gui":  # pragma: no cover
+    if path == "gui":  # pragma: no cover
         try:
             from iscc_sct.demo import demo
 
             demo.launch(inbrowser=True)
         except ImportError:
-            print(
+            typer.echo(
                 "Error: Gradio is not installed. Please install it with 'pip install gradio' to use the GUI."
             )
         return
 
-    for path in glob.glob(args.path):
-        path = Path(path)
-        if path.is_file():
-            logger.debug(f"Processing {path.name}")
-            with path.open("rb") as file:
+    for file_path in glob.glob(path):
+        file_path = Path(file_path)
+        if file_path.is_file():
+            logger.debug(f"Processing {file_path.name}")
+            with file_path.open("rb") as file:
                 data = file.read()
                 try:
                     text = data.decode("utf-8")
                     if not text.strip():
-                        logger.warning(f"SKIPPED empty: {path}")
+                        logger.warning(f"SKIPPED empty: {file_path}")
                         continue
                 except UnicodeDecodeError:
-                    logger.debug(f"Could not decode {path.name} as UTF-8.")
+                    logger.debug(f"Could not decode {file_path.name} as UTF-8.")
                     charset_match = from_bytes(data).best()
                     if not charset_match:  # pragma: no cover
-                        logger.error(f"SKIPPING {path.name} - failed to detect text encoding")
+                        logger.error(
+                            f"SKIPPING {file_path.name} - failed to detect text encoding"
+                        )
                         continue
-                    logger.debug(f"Decode {path.name} with {charset_match.encoding}.")
+                    logger.debug(f"Decode {file_path.name} with {charset_match.encoding}.")
                     text = str(charset_match)
-                sct_meta = create(text, granular=args.granular, bits=args.bits)
-                if args.granular:
-                    print(repr(sct_meta))
+                sct_meta = create(text, granular=granular, bits=bits)
+                if granular:
+                    typer.echo(repr(sct_meta))
                 else:
-                    print(sct_meta.iscc)
+                    typer.echo(sct_meta.iscc)
+
+
+@app.command(name="download-models")
+def download_models():
+    """Download all required models with progress reporting."""
+    typer.echo("Downloading models...")
+    typer.echo(f"Model: {utils.MODEL_FILENAME}")
+    typer.echo(f"URL: {utils.MODEL_URL}")
+    typer.echo(f"Destination: {utils.MODEL_PATH}")
+
+    try:
+        model_path = utils.get_model()
+        typer.secho("✓ Model downloaded and verified successfully!", fg=typer.colors.GREEN)
+        typer.echo(f"Location: {model_path}")
+    except Exception as e:
+        typer.secho(f"✗ Failed to download model: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+
+@app.command(name="verify-models")
+def verify_models():
+    """Verify model presence and integrity."""
+    typer.echo("Verifying models...")
+    typer.echo(f"Model: {utils.MODEL_FILENAME}")
+    typer.echo(f"Expected location: {utils.MODEL_PATH}")
+
+    if not utils.MODEL_PATH.exists():
+        typer.secho("✗ Model file not found!", fg=typer.colors.RED)
+        typer.echo(f"Run 'iscc-sct download-models' to download the model.")
+        raise typer.Exit(1)
+
+    try:
+        utils.check_integrity(utils.MODEL_PATH, utils.MODEL_CHECKSUM)
+        typer.secho("✓ Model integrity verified successfully!", fg=typer.colors.GREEN)
+        typer.echo(f"Location: {utils.MODEL_PATH}")
+    except RuntimeError as e:
+        typer.secho(f"✗ Model integrity check failed: {e}", fg=typer.colors.RED, err=True)
+        typer.echo("Run 'iscc-sct download-models' to re-download the model.")
+        raise typer.Exit(1)
+
+
+@app.command(name="model-info")
+def model_info():
+    """Display model metadata (versions, paths, sizes)."""
+    typer.echo("Model Information:")
+    typer.echo("=" * 50)
+    typer.echo(f"Model Name:     {utils.MODEL_FILENAME}")
+    typer.echo(f"Model Version:  {utils.BASE_VERSION}")
+    typer.echo(f"Download URL:   {utils.MODEL_URL}")
+    typer.echo(f"Local Path:     {utils.MODEL_PATH}")
+    typer.echo(f"Checksum:       {utils.MODEL_CHECKSUM}")
+
+    if utils.MODEL_PATH.exists():
+        size_mb = utils.MODEL_PATH.stat().st_size / (1024 * 1024)
+        typer.secho(f"\n✓ Status:        Downloaded ({size_mb:.2f} MB)", fg=typer.colors.GREEN)
+        try:
+            utils.check_integrity(utils.MODEL_PATH, utils.MODEL_CHECKSUM)
+            typer.secho("✓ Integrity:     Verified", fg=typer.colors.GREEN)
+        except RuntimeError:
+            typer.secho("✗ Integrity:     Failed", fg=typer.colors.RED)
+            typer.echo("  Run 'iscc-sct download-models' to re-download the model.")
+    else:
+        typer.secho("\n✗ Status:        Not downloaded", fg=typer.colors.YELLOW)
+        typer.echo("  Run 'iscc-sct download-models' to download the model.")
+
+
+def main():
+    """Main entry point that handles backward compatibility."""
+    # If called with old-style arguments (no subcommand), route to generate command
+    if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in [
+        "gen",
+        "download-models",
+        "verify-models",
+        "model-info",
+        "generate",
+    ]:
+        # Old-style usage: sct <path> [options]
+        # Convert to new style: sct gen <path> [options]
+        sys.argv.insert(1, "gen")
+    elif len(sys.argv) == 1:
+        # No arguments, show help
+        app()
+        return
+
+    app()
 
 
 if __name__ == "__main__":  # pragma: no cover