refactor-cli 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

refactor/cli.py

@@ -1,51 +1,59 @@
 import typer
-from refactor.tree import print_tree
 from importlib.metadata import version as get_version
-from refactor.validation import validate_path
-from refactor.scanner import scan_directory
-from refactor.metadata import get_metadata
+
+from refactor.context_store import DEFAULT_CACHE_FILE, save_context
 from refactor.ignore import load_ignore_patterns
+from refactor.image_scanner import scan_images
+from refactor.metadata import get_metadata
+from refactor.organizer import (
+    execute_moves,
+    managed_category_dirs,
+    plan_moves,
+    save_managed_category_dirs,
+)
+from refactor.scanner import scan_directory
+from refactor.setup import command_setup, ensure_backend_configured, maybe_run_first_time_setup
+from refactor.shim import build_image_classifier, choose_category_folders
+from refactor.tree import print_tree
+from refactor.validation import validate_path
 
 app = typer.Typer(no_args_is_help=True)
 
+
+@app.callback()
+def bootstrap() -> None:
+    maybe_run_first_time_setup()
+
+
 @app.command()
-def version():
+def version() -> None:
     """Print version information"""
     print(get_version("refactor-cli"))
 
-# @app.command()
-# def tree(path: str = "."):
-#     """Print folder structure"""
-#     print_tree(path)
 
-if __name__ == "__main__":
-    app()
+@app.command()
+def setup() -> None:
+    """Configure hosted or local multimodal backend."""
+    command_setup()
+
 
-# validates folder
 @app.command()
-def tree(path: str = "."):
+def tree(path: str = ".") -> None:
     """Display folder structure of given path"""
     try:
         validate_path(path)
         print_tree(path)
-
     except ValueError as e:
         typer.echo(f"Error: {e}")
-        raise typer.Exit(code=1) 
+        raise typer.Exit(code=1)
 
-# scanner
-# files = scan_directory(".")
-# print(len(files))    
 
 @app.command()
-def scan(path: str = "."):
+def scan(path: str = ".") -> None:
     """Scan directory and display metadata"""
-
     try:
         validate_path(path)
-
         patterns = load_ignore_patterns()
-
         items = scan_directory(path, patterns)
 
         for item in items:
@@ -53,4 +61,231 @@ def scan(path: str = "."):
 
     except ValueError as e:
         typer.echo(f"Error: {e}")
-        raise typer.Exit(code=1)  
+        raise typer.Exit(code=1)
+
+
+@app.command(name="get-image-context")
+def get_image_context(
+    path: str = typer.Argument(".", help="Directory to scan for images"),
+    output: str = typer.Option(
+        ".refactor_image_context.json",
+        "--output",
+        "-o",
+        help="Path to write the JSON context cache",
+    ),
+    min_confidence: float = typer.Option(
+        40.0,
+        "--min-confidence",
+        help="Minimum tag confidence to include (hosted backend only)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Print per-image tag results to stdout",
+    ),
+    category_root: str = typer.Option(
+        ".",
+        "--category-root",
+        help="Directory whose existing folders Gemini may reuse",
+    ),
+    write_context: bool = typer.Option(
+        True,
+        "--write-context/--no-write-context",
+        hidden=True,
+    ),
+) -> list:
+    """
+    Scan directory images using configured backend shim and save
+    tags/captions to JSON context cache.
+    """
+    from pathlib import Path
+
+    try:
+        validate_path(path)
+        if not Path(category_root).exists() or not Path(category_root).is_dir():
+            raise ValueError(f"Category root is not a directory: {category_root}")
+        config = ensure_backend_configured()
+    except (ValueError, EnvironmentError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    patterns = load_ignore_patterns()
+    source_root = Path(path).resolve()
+    destination_root = Path(category_root).resolve()
+    excluded_dirs = (
+        managed_category_dirs(destination_root)
+        if source_root == destination_root else set()
+    )
+    images = scan_images(path, patterns, excluded_dirs)
+
+    if not images:
+        typer.echo("No image files found in the specified directory.")
+        raise typer.Exit(code=0)
+
+    typer.echo(f"Found {len(images)} image(s) in '{path}'")
+
+    try:
+        classifier = build_image_classifier(config, min_confidence=min_confidence)
+    except EnvironmentError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    results = []
+    failed = 0
+
+    with typer.progressbar(images, label="Analysing images") as progress:
+        for img_path in progress:
+            try:
+                ctx = classifier.classify_image(img_path)
+                results.append(ctx)
+
+            except Exception as exc:
+                typer.echo(f"\n  [!] Skipping {img_path.name}: {exc}", err=True)
+                failed += 1
+
+    if results:
+        try:
+            results = choose_category_folders(config, results, Path(category_root))
+        except Exception as exc:
+            # Folder selection is an essential part of the hosted workflow; do
+            # not silently fall back to an Imagga top-tag directory.
+            typer.echo(f"Error: Gemini folder selection failed: {exc}", err=True)
+            raise typer.Exit(code=1)
+
+    if verbose:
+        for ctx in results:
+            typer.echo(f"\n  {Path(ctx.file_path).name}")
+            typer.echo(f"    Folder   : {ctx.primary_folder}")
+            typer.echo(f"    Tags     : {', '.join(ctx.tags[:5])}")
+            typer.echo(f"    Caption  : {ctx.caption}")
+
+    output_path = Path(output)
+    if write_context:
+        save_context(results, path, output_path)
+
+    typer.echo(f"\n{'─' * 52}")
+    typer.echo(f"  Processed : {len(results)} image(s)")
+    if failed:
+        typer.echo(f"  Failed    : {failed} image(s)")
+    if write_context:
+        typer.echo(f"  Cache     : {output_path.resolve()}")
+    typer.echo(f"{'─' * 52}")
+
+    if results:
+        typer.echo(f"\n{'Filename':<30} {'Folder':<20} {'Top tags'}")
+        typer.echo("─" * 80)
+        for ctx in results:
+            fname = Path(ctx.file_path).name
+            top_tags = ", ".join(ctx.tags[:3])
+            typer.echo(f"  {fname:<28} {ctx.primary_folder:<20} {top_tags}")
+
+    return results
+
+
+@app.command(name="refactor-images")
+def refactor_images(
+    path: str = typer.Argument(".", help="Directory containing images to organize"),
+    context: str = typer.Option(
+        ".refactor_image_context.json",
+        "--context",
+        "-c",
+        help="Path to context cache (defaults to the source directory)",
+    ),
+    output_dir: str = typer.Option(
+        ".",
+        "--output-dir",
+        "-d",
+        help="Root directory where tag-named folders will be created",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the planned moves without executing them",
+    ),
+    move: bool = typer.Option(
+        True,
+        "--move/--copy",
+        help="Move files into categories. Use --copy to preserve source files.",
+    ),
+    min_confidence: float = typer.Option(
+        40.0,
+        "--min-confidence",
+        help="Minimum Imagga tag confidence to retain",
+    ),
+) -> None:
+    """
+    Generate fresh Imagga and Gemini context, then organise images into
+    Gemini-selected subdirectories. The context cache is refreshed on every run.
+
+    By default, images are MOVED. Use --copy to preserve source files.
+    """
+    from pathlib import Path
+    try:
+        validate_path(path)
+        out = Path(output_dir)
+        if not out.exists() or not out.is_dir():
+            raise ValueError(f"Output directory is not a directory: {output_dir}")
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    context_path = Path(context)
+    if context == DEFAULT_CACHE_FILE:
+        context_path = Path(path) / DEFAULT_CACHE_FILE
+
+    excluded = managed_category_dirs(out) if Path(path).resolve() == out.resolve() else set()
+    if excluded:
+        typer.echo(f"Skipping {len(excluded)} folder(s) created by an earlier Refactor run.")
+
+    typer.echo("Generating image context with Imagga and Gemini...")
+    contexts = get_image_context(
+        path=path,
+        output=str(context_path),
+        min_confidence=min_confidence,
+        verbose=False,
+        category_root=output_dir,
+        write_context=not dry_run,
+    )
+
+    if not contexts:
+        typer.echo("Context cache is empty. Nothing to organize.")
+        raise typer.Exit(code=0)
+
+    moves = plan_moves(contexts, out)
+
+    action_word = "Move" if move else "Copy"
+
+    if dry_run:
+        verb_plural = "moves" if move else "copies"
+        verb_past = "moved" if move else "copied"
+        typer.echo(f"\n[Dry Run] Planned {verb_plural} ({len(moves)} files):\n")
+        typer.echo(f"  {'Source':<40} {'Destination'}")
+        typer.echo("  " + "─" * 76)
+        for src, dst in moves:
+            typer.echo(f"  {src.name:<40} {dst}")
+        typer.echo(f"\n  No files were {verb_past}.")
+        raise typer.Exit(code=0)
+
+    folders = {dst.parent.name for _, dst in moves}
+    typer.echo(f"\nWill {action_word.lower()} {len(moves)} image(s) into {len(folders)} folder(s):")
+    for folder in sorted(folders):
+        count = sum(1 for _, dst in moves if dst.parent.name == folder)
+        typer.echo(f"  {out / folder}  ({count} file(s))")
+
+    summary = execute_moves(moves, copy=not move)
+    if not summary["failed"]:
+        save_managed_category_dirs(out, folders)
+
+    typer.echo(f"\n{'─' * 52}")
+    count = summary["moved"] if move else summary["copied"]
+    verb_past = "moved" if move else "copied"
+    typer.echo(f"  {verb_past.capitalize():<8}: {count} file(s)")
+    if summary["failed"]:
+        typer.echo(f"  Failed  : {summary['failed']} file(s)")
+    typer.echo(f"  Output  : {out.resolve()}")
+    typer.echo(f"{'─' * 52}")
+
+
+if __name__ == "__main__":
+    app()

refactor/config.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path.home() / ".refactor"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+ENV_FILE = CONFIG_DIR / ".env"
+
+
+def _ensure_config_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def default_config() -> dict[str, Any]:
+    return {
+        "version": 1,
+        "backend": "unconfigured",
+        "setup_skipped": False,
+        "hosted": {
+            "provider": "imagga_gemini",
+            "imagga_api_key_env": "IMAGGA_API_KEY",
+            "imagga_api_secret_env": "IMAGGA_API_SECRET",
+            "gemini_api_key_env": "GEMINI_API_KEY",
+        },
+        "local": {
+            "runtime": "ollama",
+            "recommended_model": "",
+            "status": "stub",
+        },
+    }
+
+
+def config_exists() -> bool:
+    return CONFIG_FILE.exists()
+
+
+def load_config() -> dict[str, Any]:
+    if not CONFIG_FILE.exists():
+        return default_config()
+
+    with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+        payload = json.load(f)
+
+    merged = default_config()
+    merged.update(payload)
+    return merged
+
+
+def save_config(config: dict[str, Any]) -> None:
+    _ensure_config_dir()
+
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+
+
+def save_env_vars(values: dict[str, str]) -> None:
+    _ensure_config_dir()
+
+    existing: dict[str, str] = {}
+    if ENV_FILE.exists():
+        for line in ENV_FILE.read_text(encoding="utf-8").splitlines():
+            if "=" not in line or line.strip().startswith("#"):
+                continue
+            key, value = line.split("=", 1)
+            existing[key.strip()] = value.strip()
+
+    existing.update(values)
+
+    lines = [f"{k}={v}" for k, v in existing.items()]
+    ENV_FILE.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    try:
+        ENV_FILE.chmod(0o600)
+    except OSError:
+        pass

refactor/context_store.py

@@ -0,0 +1,48 @@
+"""
+refactor/context_store.py
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Manages reading and writing the JSON context cache produced by get-image-context.
+
+Default cache filename: .refactor_image_context.json
+"""
+
+from __future__ import annotations
+import json
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from refactor.imagga import ImageContext
+
+DEFAULT_CACHE_FILE = ".refactor_image_context.json"
+
+
+def save_context(
+    results: list[ImageContext],
+    source_dir: str,
+    output_path: Path,
+) -> None:
+    """Serialise a list of ImageContext objects to a JSON cache file."""
+    payload = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "source_dir": str(Path(source_dir).resolve()),
+        "images": [asdict(ctx) for ctx in results],
+    }
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+
+
+def load_context(input_path: Path) -> list[ImageContext]:
+    """Load ImageContext objects from a JSON cache file."""
+    if not input_path.exists():
+        raise FileNotFoundError(
+            f"Context cache not found: {input_path}\n"
+            "Run 'refactor get-image-context <path>' first."
+        )
+
+    with open(input_path, "r", encoding="utf-8") as f:
+        payload = json.load(f)
+
+    return [ImageContext(**img) for img in payload.get("images", [])]

refactor/gemini.py

@@ -0,0 +1,103 @@
+"""Gemini-backed folder selection for Imagga image context."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+import requests
+from dotenv import load_dotenv
+
+from refactor.config import ENV_FILE
+from refactor.imagga import ImageContext
+
+load_dotenv()
+if ENV_FILE.exists():
+    load_dotenv(ENV_FILE)
+
+# Current Gemini API default. Users may set GEMINI_MODEL to override it.
+DEFAULT_MODEL = "gemini-3.8-flash"
+
+
+def _safe_folder_name(value: str) -> str:
+    """Return one relative directory name, never a path supplied by the model."""
+    value = value.strip().lower()
+    value = re.sub(r"[^\w\s-]", "", value)
+    value = re.sub(r"\s+", "_", value).strip("_-")
+    return value or "uncategorized"
+
+
+class GeminiFolderClassifier:
+    """Ask Gemini to select consistent folders from Imagga tags and captions."""
+
+    def __init__(self, api_key: str | None = None, model: str | None = None) -> None:
+        self.api_key = api_key or os.environ.get("GEMINI_API_KEY", "")
+        self.model = model or os.environ.get("GEMINI_MODEL", DEFAULT_MODEL)
+        if not self.api_key:
+            raise EnvironmentError(
+                "Gemini credentials not found. Set GEMINI_API_KEY in ~/.refactor/.env."
+            )
+
+    def choose_folders(
+        self, contexts: list[ImageContext], category_root: Path
+    ) -> list[ImageContext]:
+        if not contexts:
+            return contexts
+
+        existing = sorted(
+            entry.name for entry in category_root.iterdir() if entry.is_dir()
+        ) if category_root.exists() else []
+        images = [
+            {"id": index, "filename": Path(ctx.file_path).name,
+             "tags": ctx.tags, "caption": ctx.caption}
+            for index, ctx in enumerate(contexts)
+        ]
+        prompt = (
+            "Choose exactly one concise, lowercase category folder for every image. "
+            "Prefer an existing category when it accurately fits; otherwise create a "
+            "new, broad and reusable category. Folder names must be a single relative "
+            "directory name (letters, numbers, spaces, underscores, or hyphens only). "
+            "Do not use filenames, paths, or explanations. Return JSON only in this "
+            "shape: {\"folders\":[{\"id\":0,\"folder\":\"example\"}]}.\n\n"
+            f"Existing categories: {json.dumps(existing)}\n"
+            f"Images and Imagga semantic context: {json.dumps(images, ensure_ascii=False)}"
+        )
+        payload = {
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {
+                "responseMimeType": "application/json",
+                "temperature": 0,
+            },
+        }
+        url = (
+            "https://generativelanguage.googleapis.com/v1beta/models/"
+            f"{self.model}:generateContent"
+        )
+        response = requests.post(
+            url, headers={"x-goog-api-key": self.api_key}, json=payload, timeout=60
+        )
+        if not response.ok:
+            raise requests.HTTPError(
+                f"Gemini folder selection returned {response.status_code}: {response.text}",
+                response=response,
+            )
+
+        try:
+            text = response.json()["candidates"][0]["content"]["parts"][0]["text"]
+            choices = json.loads(text)["folders"]
+        except (KeyError, IndexError, TypeError, json.JSONDecodeError) as exc:
+            raise ValueError("Gemini returned an invalid folder-selection response") from exc
+
+        folders = {
+            choice.get("id"): _safe_folder_name(str(choice.get("folder", "")))
+            for choice in choices if isinstance(choice, dict) and isinstance(choice.get("id"), int)
+        }
+        missing = [str(index) for index in range(len(contexts)) if index not in folders]
+        if missing:
+            raise ValueError("Gemini did not choose a folder for image id(s): " + ", ".join(missing))
+
+        for index, context in enumerate(contexts):
+            context.primary_folder = folders[index]
+        return contexts

refactor/hardware.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass
+class HardwareSpec:
+    cpu_cores: int
+    memory_gb: float
+    has_nvidia_gpu: bool
+    gpu_vram_gb: float | None = None
+
+
+def _memory_gb() -> float:
+    pagesize = os.sysconf("SC_PAGE_SIZE")
+    pages = os.sysconf("SC_PHYS_PAGES")
+    return round((pagesize * pages) / (1024**3), 2)
+
+
+def _nvidia_vram_gb() -> float | None:
+    if not shutil.which("nvidia-smi"):
+        return None
+
+    try:
+        result = subprocess.run(
+            [
+                "nvidia-smi",
+                "--query-gpu=memory.total",
+                "--format=csv,noheader,nounits",
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except Exception:
+        return None
+
+    values = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            values.append(float(line) / 1024)
+        except ValueError:
+            continue
+
+    return round(max(values), 2) if values else None
+
+
+def detect_hardware() -> HardwareSpec:
+    vram = _nvidia_vram_gb()
+    return HardwareSpec(
+        cpu_cores=os.cpu_count() or 1,
+        memory_gb=_memory_gb(),
+        has_nvidia_gpu=vram is not None,
+        gpu_vram_gb=vram,
+    )
+
+
+def recommend_local_model(spec: HardwareSpec) -> tuple[str, str]:
+    if spec.has_nvidia_gpu and (spec.gpu_vram_gb or 0) >= 8:
+        return (
+            "llava:7b",
+            "Good fit for GPU-backed image understanding with balanced quality/speed.",
+        )
+
+    if spec.memory_gb >= 16:
+        return (
+            "llava:7b-q4",
+            "Reasonable CPU-only option with quantization for 16GB+ RAM systems.",
+        )
+
+    if spec.memory_gb >= 8:
+        return (
+            "moondream",
+            "Lightweight option for lower-memory systems focused on image captioning.",
+        )
+
+    return (
+        "nanollava",
+        "Very small fallback model for constrained hardware; expect limited accuracy.",
+    )

refactor/image_scanner.py

@@ -0,0 +1,39 @@
+"""
+refactor/image_scanner.py
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Scans a directory for image files only.
+Extends the base scanner with image-extension filtering.
+"""
+
+from pathlib import Path
+
+from refactor.ignore import should_ignore
+
+IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".gif", ".bmp", ".tiff", ".tif", ".webp"}
+
+
+def scan_images(
+    path: str, ignore_patterns: list[str], excluded_dirs: set[Path] | None = None
+) -> list[Path]:
+    """
+    Recursively scan *path* and return all image files.
+
+    Files matching any pattern in *ignore_patterns* are skipped.
+    """
+    images: list[Path] = []
+    excluded_dirs = {directory.resolve() for directory in (excluded_dirs or set())}
+
+    for item in Path(path).rglob("*"):
+        if item.is_dir():
+            continue
+
+        if any(directory in item.resolve().parents for directory in excluded_dirs):
+            continue
+
+        if should_ignore(item.name, ignore_patterns):
+            continue
+
+        if item.suffix.lower() in IMAGE_EXTENSIONS:
+            images.append(item)
+
+    return images