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

refactor/cli.py

@@ -11,18 +11,32 @@ from refactor.organizer import (
     plan_moves,
     save_managed_category_dirs,
 )
+from refactor.plan_cache import load_valid_plan, save_plan
 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.text import (
+    TextContext,
+    classify_documents,
+    managed_text_dirs,
+    save_managed_text_dirs,
+    scan_documents,
+)
+from refactor.imagga import ImageContext
 from refactor.tree import print_tree
 from refactor.validation import validate_path
 
 app = typer.Typer(no_args_is_help=True)
 
+TEXT_PLAN_FILE = ".refactor_text_context.json"
+
 
 @app.callback()
-def bootstrap() -> None:
-    maybe_run_first_time_setup()
+def bootstrap(ctx: typer.Context) -> None:
+    # `refactor setup` is itself the setup command. Running first-time setup in
+    # the callback as well caused that command to prompt twice on a new install.
+    if ctx.invoked_subcommand != "setup":
+        maybe_run_first_time_setup()
 
 
 @app.command()
@@ -33,7 +47,7 @@ def version() -> None:
 
 @app.command()
 def setup() -> None:
-    """Configure hosted or local multimodal backend."""
+    """Configure hosted APIs or a local Ollama multimodal backend."""
     command_setup()
 
 
@@ -87,7 +101,7 @@ def get_image_context(
     category_root: str = typer.Option(
         ".",
         "--category-root",
-        help="Directory whose existing folders Gemini may reuse",
+        help="Directory whose existing folders the configured model may reuse",
     ),
     write_context: bool = typer.Option(
         True,
@@ -121,7 +135,7 @@ def get_image_context(
 
     if not images:
         typer.echo("No image files found in the specified directory.")
-        raise typer.Exit(code=0)
+        return []
 
     typer.echo(f"Found {len(images)} image(s) in '{path}'")
 
@@ -148,9 +162,8 @@ def get_image_context(
         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)
+            # Folder selection is essential; do not silently fall back to a top tag.
+            typer.echo(f"Error: model folder selection failed: {exc}", err=True)
             raise typer.Exit(code=1)
 
     if verbose:
@@ -183,6 +196,71 @@ def get_image_context(
     return results
 
 
+@app.command(name="refactor-text")
+def refactor_text(
+    path: str = typer.Argument(".", help="Directory containing documents to organize"),
+    output_dir: str = typer.Option(".", "--output-dir", "-d"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    move: bool = typer.Option(True, "--move/--copy"),
+) -> list:
+    """Use the configured backend to categorize .txt, .md, .pdf, and .docx 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}")
+        config = ensure_backend_configured()
+    except (ValueError, EnvironmentError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1)
+
+    patterns = load_ignore_patterns()
+    excluded = managed_text_dirs(out) if Path(path).resolve() == out.resolve() else set()
+    documents = scan_documents(path, patterns, excluded)
+    if not documents:
+        typer.echo("No supported document files found in the specified directory.")
+        return []
+
+    plan_path = Path(path) / TEXT_PLAN_FILE
+    contexts = load_valid_plan(
+        plan_path, "text", path, output_dir, documents, TextContext
+    )
+    if contexts is not None:
+        typer.echo(f"Reusing validated document context from {plan_path}.")
+    else:
+        typer.echo(f"Found {len(documents)} document(s) in '{path}'")
+        try:
+            contexts, failures = classify_documents(documents, out, config)
+        except EnvironmentError as exc:
+            typer.echo(f"Error: {exc}", err=True)
+            raise typer.Exit(code=1)
+        for document, error in failures:
+            typer.echo(f"  [!] Skipping {document.name}: {error}", err=True)
+        if contexts and len(contexts) == len(documents):
+            save_plan(plan_path, "text", path, output_dir, documents, contexts)
+
+    if not contexts:
+        typer.echo("No documents were categorized.")
+        return []
+
+    moves = plan_moves(contexts, out)
+    if dry_run:
+        typer.echo(f"\n[Dry Run] Planned document moves ({len(moves)} files):")
+        for src, dst in moves:
+            typer.echo(f"  {src} → {dst}")
+        return contexts
+
+    summary = execute_moves(moves, copy=not move)
+    folders = {destination.parent.name for _, destination in moves}
+    if not summary["failed"]:
+        save_managed_text_dirs(out, folders)
+    verb = "Moved" if move else "Copied"
+    typer.echo(f"{verb} {summary['moved'] if move else summary['copied']} document(s).")
+    return contexts
+
+
 @app.command(name="refactor-images")
 def refactor_images(
     path: str = typer.Argument(".", help="Directory containing images to organize"),
@@ -211,12 +289,12 @@ def refactor_images(
     min_confidence: float = typer.Option(
         40.0,
         "--min-confidence",
-        help="Minimum Imagga tag confidence to retain",
+        help="Minimum Imagga tag confidence to retain (hosted backend only)",
     ),
-) -> None:
+) -> list:
     """
-    Generate fresh Imagga and Gemini context, then organise images into
-    Gemini-selected subdirectories. The context cache is refreshed on every run.
+    Generate fresh context with the configured image backend, then organise
+    images into model-selected subdirectories. The context cache is refreshed on every run.
 
     By default, images are MOVED. Use --copy to preserve source files.
     """
@@ -238,19 +316,31 @@ def refactor_images(
     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,
+    patterns = load_ignore_patterns()
+    current_images = scan_images(path, patterns, excluded)
+    contexts = load_valid_plan(
+        context_path, "image", path, output_dir, current_images, ImageContext
     )
+    if contexts is not None:
+        typer.echo(f"Reusing validated image context from {context_path}.")
+    else:
+        typer.echo("Generating image context with the configured backend...")
+        contexts = get_image_context(
+            path=path,
+            output=str(context_path),
+            min_confidence=min_confidence,
+            verbose=False,
+            category_root=output_dir,
+            write_context=False,
+        )
+        if contexts and len(contexts) == len(current_images):
+            save_plan(
+                context_path, "image", path, output_dir, current_images, contexts
+            )
 
     if not contexts:
         typer.echo("Context cache is empty. Nothing to organize.")
-        raise typer.Exit(code=0)
+        return []
 
     moves = plan_moves(contexts, out)
 
@@ -265,7 +355,7 @@ def refactor_images(
         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)
+        return contexts
 
     folders = {dst.parent.name for _, dst in moves}
     typer.echo(f"\nWill {action_word.lower()} {len(moves)} image(s) into {len(folders)} folder(s):")
@@ -285,6 +375,29 @@ def refactor_images(
         typer.echo(f"  Failed  : {summary['failed']} file(s)")
     typer.echo(f"  Output  : {out.resolve()}")
     typer.echo(f"{'─' * 52}")
+    return contexts
+
+
+@app.command(name="now")
+def refactor_now(
+    path: str = typer.Argument(".", help="Directory containing documents and images"),
+    output_dir: str = typer.Option(".", "--output-dir", "-d"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    move: bool = typer.Option(True, "--move/--copy"),
+    min_confidence: float = typer.Option(40.0, "--min-confidence"),
+) -> None:
+    """Categorize supported documents first, then images in a mixed folder."""
+    typer.echo("\n[1/2] Categorizing documents")
+    refactor_text(path=path, output_dir=output_dir, dry_run=dry_run, move=move)
+    typer.echo("\n[2/2] Categorizing images")
+    refactor_images(
+        path=path,
+        context=DEFAULT_CACHE_FILE,
+        output_dir=output_dir,
+        dry_run=dry_run,
+        move=move,
+        min_confidence=min_confidence,
+    )
 
 
 if __name__ == "__main__":

refactor/config.py

@@ -27,7 +27,7 @@ def default_config() -> dict[str, Any]:
         "local": {
             "runtime": "ollama",
             "recommended_model": "",
-            "status": "stub",
+            "status": "not_configured",
         },
     }
 

refactor/gemini.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import base64
 from pathlib import Path
 
 import requests
@@ -101,3 +102,55 @@ class GeminiFolderClassifier:
         for index, context in enumerate(contexts):
             context.primary_folder = folders[index]
         return contexts
+
+    def choose_document_folder(
+        self,
+        file_path: Path,
+        extracted_text: str,
+        category_root: Path,
+        is_pdf: bool = False,
+    ) -> str:
+        """Choose one folder from a document's text or native PDF content."""
+        prompt = (
+            "Choose one concise, lowercase category folder for this document. "
+            "Use letters, numbers, spaces, underscores, or hyphens only; return "
+            "JSON only as {\"folder\":\"example\"}. Prefer an existing category "
+            "when it fits. Do not use a filename or path.\n\n"
+            f"Existing categories: {json.dumps(sorted(entry.name for entry in category_root.iterdir() if entry.is_dir()))}\n"
+            f"Filename: {file_path.name}\n"
+        )
+        parts = [{"text": prompt + ("The PDF is attached." if is_pdf else extracted_text)}]
+        if is_pdf:
+            parts.append(
+                {
+                    "inlineData": {
+                        "mimeType": "application/pdf",
+                        "data": base64.b64encode(file_path.read_bytes()).decode("ascii"),
+                    }
+                }
+            )
+
+        payload = {
+            "contents": [{"parts": parts}],
+            "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 document classification returned {response.status_code}: {response.text}",
+                response=response,
+            )
+        try:
+            text = response.json()["candidates"][0]["content"]["parts"][0]["text"]
+            return _safe_folder_name(str(json.loads(text)["folder"]))
+        except (KeyError, IndexError, TypeError, json.JSONDecodeError) as exc:
+            raise ValueError("Gemini returned an invalid document-folder response") from exc

refactor/hardware.py

@@ -20,26 +20,60 @@ def _memory_gb() -> float:
     return round((pagesize * pages) / (1024**3), 2)
 
 
-def _nvidia_vram_gb() -> float | None:
-    if not shutil.which("nvidia-smi"):
-        return None
-
+def _run(command: list[str]) -> str | None:
+    """Return command output without allowing hardware probes to fail setup."""
     try:
         result = subprocess.run(
-            [
-                "nvidia-smi",
-                "--query-gpu=memory.total",
-                "--format=csv,noheader,nounits",
-            ],
+            command,
             capture_output=True,
             text=True,
             check=True,
+            timeout=5,
         )
-    except Exception:
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return result.stdout
+
+
+def _has_nvidia_gpu() -> bool:
+    """Detect NVIDIA hardware even when the driver utility cannot report VRAM."""
+    if shutil.which("nvidia-smi") and _run(["nvidia-smi", "-L"]):
+        return True
+
+    if os.name != "nt":
+        pci_devices = _run(["lspci"])
+        if pci_devices and "nvidia" in pci_devices.lower():
+            return True
+        nvidia_devices = "/proc/driver/nvidia/gpus"
+        try:
+            if os.path.isdir(nvidia_devices) and os.listdir(nvidia_devices):
+                return True
+        except OSError:
+            pass
+    else:
+        output = _run(["wmic", "path", "win32_VideoController", "get", "name"])
+        if output and "nvidia" in output.lower():
+            return True
+
+    return False
+
+
+def _nvidia_vram_gb() -> float | None:
+    if not shutil.which("nvidia-smi"):
+        return None
+
+    output = _run(
+        [
+            "nvidia-smi",
+            "--query-gpu=memory.total",
+            "--format=csv,noheader,nounits",
+        ]
+    )
+    if output is None:
         return None
 
     values = []
-    for line in result.stdout.splitlines():
+    for line in output.splitlines():
         line = line.strip()
         if not line:
             continue
@@ -56,7 +90,7 @@ def detect_hardware() -> HardwareSpec:
     return HardwareSpec(
         cpu_cores=os.cpu_count() or 1,
         memory_gb=_memory_gb(),
-        has_nvidia_gpu=vram is not None,
+        has_nvidia_gpu=_has_nvidia_gpu(),
         gpu_vram_gb=vram,
     )
 
@@ -64,23 +98,32 @@ def detect_hardware() -> HardwareSpec:
 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.",
+            "gemma3:4b",
+            "Multimodal instruction-following model suitable for both document and image organization.",
+        )
+
+    if spec.has_nvidia_gpu:
+        return (
+            "gemma3:4b",
+            "A multimodal model is required for reliable structured document and image categorization; "
+            "verify available memory if NVIDIA VRAM cannot be read.",
         )
 
     if spec.memory_gb >= 16:
         return (
-            "llava:7b-q4",
-            "Reasonable CPU-only option with quantization for 16GB+ RAM systems.",
+            "gemma3:4b",
+            "Multimodal model with enough context for document and image organization on 16GB+ RAM.",
         )
 
     if spec.memory_gb >= 8:
         return (
-            "moondream",
-            "Lightweight option for lower-memory systems focused on image captioning.",
+            "gemma3:4b",
+            "Smallest recommended multimodal option for structured document and image organization; "
+            "expect slower operation on CPU-only systems.",
         )
 
     return (
-        "nanollava",
-        "Very small fallback model for constrained hardware; expect limited accuracy.",
+        "gemma3:4b",
+        "Refactor requires a multimodal instruction-following model for all supported file types. "
+        "This system may not have enough memory; use hosted mode or add memory if the model cannot run.",
     )

refactor/plan_cache.py

@@ -0,0 +1,66 @@
+"""Persistent, source-validated plans for dry-run reuse."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Type
+
+
+def _snapshot(files: list[Path]) -> list[dict[str, Any]]:
+    return [
+        {
+            "path": str(file_path.resolve()),
+            "size": file_path.stat().st_size,
+            "mtime_ns": file_path.stat().st_mtime_ns,
+        }
+        for file_path in sorted(files)
+    ]
+
+
+def save_plan(
+    output_path: Path,
+    kind: str,
+    source_dir: str,
+    output_dir: str,
+    files: list[Path],
+    contexts: list[Any],
+) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "kind": kind,
+        "source_dir": str(Path(source_dir).resolve()),
+        "output_dir": str(Path(output_dir).resolve()),
+        "snapshot": _snapshot(files),
+        "items": [asdict(context) for context in contexts],
+    }
+    output_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def load_valid_plan(
+    input_path: Path,
+    kind: str,
+    source_dir: str,
+    output_dir: str,
+    files: list[Path],
+    context_type: Type[Any],
+) -> list[Any] | None:
+    """Return cached contexts only if they exactly match the current source."""
+    if not input_path.exists():
+        return None
+    try:
+        payload = json.loads(input_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if (
+        payload.get("kind") != kind
+        or payload.get("source_dir") != str(Path(source_dir).resolve())
+        or payload.get("output_dir") != str(Path(output_dir).resolve())
+        or payload.get("snapshot") != _snapshot(files)
+    ):
+        return None
+    try:
+        return [context_type(**item) for item in payload["items"]]
+    except (KeyError, TypeError):
+        return None

refactor/setup.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
 import os
+import shutil
+import subprocess
 import sys
 
 import typer
 
 from refactor.config import config_exists, default_config, load_config, save_config, save_env_vars
 from refactor.hardware import detect_hardware, recommend_local_model
+from refactor.shim import ollama_model_available, ollama_server_available
 
 
 def _interactive() -> bool:
@@ -80,7 +83,7 @@ def run_setup() -> dict:
     typer.echo("\nRefactor setup")
     typer.echo("Choose backend:")
     typer.echo("  1) Hosted model (bring your own API keys)")
-    typer.echo("  2) Local multimodal recommendation (stub integration)")
+    typer.echo("  2) Local multimodal model with Ollama")
 
     choice = typer.prompt("Select option", default="1").strip()
 
@@ -120,14 +123,41 @@ def run_setup() -> dict:
         typer.echo(f"- Model: {model}")
         typer.echo(f"- Why: {reason}")
         typer.echo("- Suggested runtime: ollama")
-        typer.echo("- Example install: ollama pull " + model)
+        typer.echo("- Model command: ollama pull " + model)
 
         config["backend"] = "local"
         config["setup_skipped"] = False
         config["local"]["runtime"] = "ollama"
         config["local"]["recommended_model"] = model
-        config["local"]["status"] = "stub"
-        typer.echo("Local backend configured with stub shim for now.")
+        config["local"]["status"] = "not_ready"
+
+        if not shutil.which("ollama"):
+            typer.echo("\nOllama is not installed, so Refactor cannot use a local model yet.")
+            typer.echo("Install Ollama from: https://ollama.com/download")
+            typer.echo("Then run:")
+            typer.echo(f"  ollama pull {model}")
+            typer.echo("  refactor setup")
+        elif not ollama_server_available():
+            typer.echo("\nOllama is installed but its local server is not running.")
+            typer.echo("Start it in another terminal with:")
+            typer.echo("  ollama serve")
+            typer.echo("Then rerun: refactor setup")
+        elif ollama_model_available(model):
+            config["local"]["status"] = "ready"
+            typer.echo(f"\nOllama model '{model}' is installed and ready to use.")
+        else:
+            typer.echo(f"\nOllama is ready, but '{model}' is not installed.")
+            if typer.confirm(f"Download '{model}' now?", default=True):
+                result = subprocess.run(["ollama", "pull", model], check=False)
+                if result.returncode == 0 and ollama_model_available(model):
+                    config["local"]["status"] = "ready"
+                    typer.echo(f"Local model '{model}' is ready to use.")
+                else:
+                    typer.echo(
+                        f"Could not verify '{model}'. Run `ollama pull {model}` and then `refactor setup` again."
+                    )
+            else:
+                typer.echo(f"Run `ollama pull {model}` and then `refactor setup` when ready.")
 
     else:
         raise typer.BadParameter("Invalid option. Choose 1 or 2.")

refactor/shim.py

@@ -1,12 +1,22 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+import base64
+import json
 from pathlib import Path
+from urllib.error import URLError
+from urllib.request import Request, urlopen
 
 from refactor.imagga import ImageContext, ImaggaClient
 from refactor.gemini import GeminiFolderClassifier
 
 
+def _safe_folder_name(value: str) -> str:
+    value = value.strip().lower()
+    safe = "".join(char for char in value if char.isalnum() or char in " -_")
+    return "_".join(safe.split()).strip("_-") or "uncategorized"
+
+
 class ImageClassifier(ABC):
     @abstractmethod
     def classify_image(self, file_path: Path) -> ImageContext:
@@ -26,27 +36,251 @@ class HostedImageClassifier(ImageClassifier):
         return GeminiFolderClassifier().choose_folders(contexts, category_root)
 
 
-class LocalStubImageClassifier(ImageClassifier):
+OLLAMA_URL = "http://127.0.0.1:11434"
+
+# ``format: "json"`` ensures only syntactically valid JSON. A schema also
+# constrains keys and array length, which is essential for small local models.
+IMAGE_CONTEXT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "caption": {"type": "string"},
+        "tags": {
+            "type": "array",
+            "items": {"type": "string"},
+            "minItems": 1,
+            "maxItems": 5,
+        },
+        "folder": {"type": "string"},
+    },
+    "required": ["caption", "tags", "folder"],
+    "additionalProperties": False,
+}
+FOLDER_SCHEMA = {
+    "type": "object",
+    "properties": {"folder": {"type": "string"}},
+    "required": ["folder"],
+    "additionalProperties": False,
+}
+FOLDER_BATCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "folders": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {"id": {"type": "integer"}, "folder": {"type": "string"}},
+                "required": ["id", "folder"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["folders"],
+    "additionalProperties": False,
+}
+
+
+def _parse_ollama_json(response: dict, description: str) -> dict:
+    """Return one JSON object without exposing unbounded model output on errors."""
+    if response.get("error"):
+        raise RuntimeError(f"Ollama {description} request failed: {response['error']}")
+    content = response.get("message", {}).get("content", "")
+    try:
+        parsed = json.loads(content)
+    except (TypeError, json.JSONDecodeError) as exc:
+        preview = str(content).replace("\n", " ")[:300]
+        reason = response.get("done_reason", "unknown")
+        raise RuntimeError(
+            f"Ollama returned invalid {description} JSON "
+            f"(done_reason={reason}, preview={preview!r})"
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"Ollama returned a non-object {description} response")
+    return parsed
+
+
+def _ollama_request(path: str, payload: dict | None = None) -> dict:
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    request = Request(
+        f"{OLLAMA_URL}{path}",
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST" if data is not None else "GET",
+    )
+    try:
+        with urlopen(request, timeout=120) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except (URLError, OSError, json.JSONDecodeError) as exc:
+        raise EnvironmentError(
+            "Cannot reach Ollama at http://127.0.0.1:11434. Start it with `ollama serve`."
+        ) from exc
+
+
+def ollama_server_available() -> bool:
+    try:
+        _ollama_request("/api/tags")
+    except EnvironmentError:
+        return False
+    return True
+
+
+def ollama_model_available(model_name: str) -> bool:
+    try:
+        response = _ollama_request("/api/tags")
+    except EnvironmentError:
+        return False
+    installed = {model.get("name", "") for model in response.get("models", [])}
+    return model_name in installed or f"{model_name}:latest" in installed
+
+
+class OllamaImageClassifier(ImageClassifier):
     def __init__(self, model_name: str) -> None:
         self.model_name = model_name
 
     def classify_image(self, file_path: Path) -> ImageContext:
-        name_tokens = [t for t in file_path.stem.lower().replace("-", "_").split("_") if t]
-        tags = name_tokens[:3] if name_tokens else ["unclassified"]
-        primary = tags[0] if tags else "unclassified"
+        try:
+            encoded_image = base64.b64encode(file_path.read_bytes()).decode("ascii")
+        except OSError as exc:
+            raise RuntimeError(f"Could not read image: {file_path}") from exc
+
+        prompt = (
+            "Analyze this image for file organization. Return one JSON object matching "
+            "the supplied schema: a short caption, 1 to 5 distinct concise lowercase "
+            "tags, and one broad reusable folder name. Do not repeat tags or add keys."
+        )
+        response = _ollama_request(
+            "/api/chat",
+            {
+                "model": self.model_name,
+                "stream": False,
+                "format": IMAGE_CONTEXT_SCHEMA,
+                "options": {"temperature": 0, "num_predict": 160},
+                "think": False,
+                "messages": [{"role": "user", "content": prompt, "images": [encoded_image]}],
+            },
+        )
+        result = _parse_ollama_json(response, "image classification")
+
+        raw_tags = result.get("tags")
+        if not isinstance(raw_tags, list) or not all(isinstance(tag, str) for tag in raw_tags):
+            raise RuntimeError("Ollama image classification did not return a string tag list")
+        tags = list(dict.fromkeys(tag.strip().lower() for tag in raw_tags if tag.strip()))[:5]
+        caption = str(result.get("caption", "")).strip()
+        primary = _safe_folder_name(str(result.get("folder", "")))
+        if not tags:
+            tags = ["unclassified"]
+        if not caption:
+            caption = "No caption returned by local model."
+        if primary == "uncategorized":
+            primary = tags[0]
 
         return ImageContext(
             file_path=str(file_path.resolve()),
-            upload_id="local-stub",
+            upload_id="ollama-local",
             tags=tags,
             confidences={tag: 0.0 for tag in tags},
-            caption=(
-                f"Local stub classification using '{self.model_name}'. "
-                "Install and connect a local multimodal runtime in a future step."
-            ),
+            caption=caption,
             primary_folder=primary,
         )
 
+    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(context.file_path).name,
+             "tags": context.tags, "caption": context.caption}
+            for index, context 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). "
+            "Return exactly one id/folder object for every image and no other keys.\n\n"
+            f"Existing categories: {json.dumps(existing)}\n"
+            f"Images and local semantic context: {json.dumps(images, ensure_ascii=False)}"
+        )
+        response = _ollama_request(
+            "/api/chat",
+            {
+                "model": self.model_name,
+                "stream": False,
+                "format": FOLDER_BATCH_SCHEMA,
+                "options": {"temperature": 0, "num_predict": max(80, len(contexts) * 40)},
+                "think": False,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+        )
+        result = _parse_ollama_json(response, "image folder-selection")
+        try:
+            choices = result["folders"]
+            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)
+            }
+        except (KeyError, TypeError) as exc:
+            raise RuntimeError(
+                "Ollama image folder-selection response did not contain folders"
+            ) from exc
+        missing = [str(index) for index in range(len(contexts)) if index not in folders]
+        if missing:
+            raise RuntimeError("Ollama did not choose a folder for image id(s): " + ", ".join(missing))
+        for index, context in enumerate(contexts):
+            context.primary_folder = folders[index]
+        return contexts
+
+
+class OllamaDocumentClassifier:
+    """Choose a document folder through a local Ollama text-capable model."""
+
+    def __init__(self, model_name: str) -> None:
+        self.model_name = model_name
+
+    def choose_document_folder(
+        self, file_path: Path, extracted_text: str, category_root: Path
+    ) -> str:
+        existing = (
+            sorted(entry.name for entry in category_root.iterdir() if entry.is_dir())
+            if category_root.exists()
+            else []
+        )
+        prompt = (
+            "Choose one concise, lowercase category folder for this document. "
+            "Prefer an existing category when it fits. The folder must not be a filename "
+            "or path. Return one JSON object matching the supplied schema and no other keys.\n\n"
+            f"Existing categories: {json.dumps(existing)}\n"
+            f"Filename: {file_path.name}\n"
+            f"Document text:\n{extracted_text}"
+        )
+        response = _ollama_request(
+            "/api/chat",
+            {
+                "model": self.model_name,
+                "stream": False,
+                "format": FOLDER_SCHEMA,
+                "options": {"temperature": 0, "num_predict": 80},
+                "think": False,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+        )
+        result = _parse_ollama_json(response, "document classification")
+        try:
+            folder = result["folder"]
+        except KeyError as exc:
+            raise RuntimeError(
+                "Ollama document classification response did not contain a folder"
+            ) from exc
+        if not isinstance(folder, str):
+            raise RuntimeError("Ollama document classification returned a non-string folder")
+        return _safe_folder_name(folder)
+
 
 def build_image_classifier(config: dict, min_confidence: float) -> ImageClassifier:
     backend = config.get("backend", "unconfigured")
@@ -56,9 +290,37 @@ def build_image_classifier(config: dict, min_confidence: float) -> ImageClassifi
 
     if backend == "local":
         local_cfg = config.get("local", {})
-        model_name = local_cfg.get("recommended_model") or "local-stub"
-        return LocalStubImageClassifier(model_name=model_name)
+        model_name = local_cfg.get("recommended_model")
+        if not model_name:
+            raise EnvironmentError("No local Ollama model is configured. Run `refactor setup`.")
+        if not ollama_server_available():
+            raise EnvironmentError("Ollama is not running. Start it with `ollama serve`.")
+        if not ollama_model_available(model_name):
+            raise EnvironmentError(
+                f"Ollama model '{model_name}' is not installed. Run `ollama pull {model_name}`."
+            )
+        return OllamaImageClassifier(model_name=model_name)
+
+    raise EnvironmentError(
+        "Refactor setup is incomplete. Run 'refactor setup' to configure hosted or local backend."
+    )
 
+
+def build_document_classifier(config: dict):
+    """Return the configured backend's folder classifier for documents."""
+    if config.get("backend") == "hosted":
+        return GeminiFolderClassifier()
+    if config.get("backend") == "local":
+        model_name = config.get("local", {}).get("recommended_model")
+        if not model_name:
+            raise EnvironmentError("No local Ollama model is configured. Run `refactor setup`.")
+        if not ollama_server_available():
+            raise EnvironmentError("Ollama is not running. Start it with `ollama serve`.")
+        if not ollama_model_available(model_name):
+            raise EnvironmentError(
+                f"Ollama model '{model_name}' is not installed. Run `ollama pull {model_name}`."
+            )
+        return OllamaDocumentClassifier(model_name)
     raise EnvironmentError(
         "Refactor setup is incomplete. Run 'refactor setup' to configure hosted or local backend."
     )
@@ -67,7 +329,12 @@ def build_image_classifier(config: dict, min_confidence: float) -> ImageClassifi
 def choose_category_folders(
     config: dict, contexts: list[ImageContext], category_root: Path
 ) -> list[ImageContext]:
-    """Use Gemini for hosted classifications; local mode keeps its stub result."""
+    """Use the configured model to consistently choose category folders."""
     if config.get("backend") == "hosted":
         return GeminiFolderClassifier().choose_folders(contexts, category_root)
+    if config.get("backend") == "local":
+        model_name = config.get("local", {}).get("recommended_model")
+        if not model_name:
+            raise EnvironmentError("No local Ollama model is configured. Run `refactor setup`.")
+        return OllamaImageClassifier(model_name).choose_folders(contexts, category_root)
     return contexts

refactor/text.py

@@ -0,0 +1,103 @@
+"""Document discovery, text extraction, and configured-backend categorization."""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from xml.etree import ElementTree
+
+from refactor.ignore import should_ignore
+from refactor.shim import build_document_classifier
+
+TEXT_EXTENSIONS = {".txt", ".md", ".pdf", ".docx"}
+TEXT_CATEGORY_MANIFEST = ".refactor_text_categories.json"
+MAX_TEXT_CHARS = 60_000
+MAX_PDF_BYTES = 50 * 1024 * 1024
+
+
+@dataclass
+class TextContext:
+    file_path: str
+    primary_folder: str
+
+
+def managed_text_dirs(output_dir: Path) -> set[Path]:
+    manifest = output_dir / TEXT_CATEGORY_MANIFEST
+    if not manifest.exists():
+        return set()
+    try:
+        folders = json.loads(manifest.read_text(encoding="utf-8")).get("folders", [])
+    except (OSError, json.JSONDecodeError):
+        return set()
+    return {
+        (output_dir / folder).resolve() for folder in folders
+        if isinstance(folder, str) and (output_dir / folder).is_dir()
+    }
+
+
+def save_managed_text_dirs(output_dir: Path, folders: set[str]) -> None:
+    (output_dir / TEXT_CATEGORY_MANIFEST).write_text(
+        json.dumps({"folders": sorted(folders)}, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def scan_documents(path: str, patterns: list[str], excluded_dirs: set[Path]) -> list[Path]:
+    documents: list[Path] = []
+    excluded_dirs = {directory.resolve() for directory in excluded_dirs}
+    for item in Path(path).rglob("*"):
+        if item.is_dir() or item.suffix.lower() not in TEXT_EXTENSIONS:
+            continue
+        if any(directory in item.resolve().parents for directory in excluded_dirs):
+            continue
+        if not should_ignore(item.name, patterns):
+            documents.append(item)
+    return documents
+
+
+def extract_text(file_path: Path) -> str:
+    """Extract text locally from supported document formats."""
+    if file_path.suffix.lower() in {".txt", ".md"}:
+        return file_path.read_text(encoding="utf-8", errors="replace")[:MAX_TEXT_CHARS]
+    if file_path.suffix.lower() == ".docx":
+        with zipfile.ZipFile(file_path) as document:
+            root = ElementTree.fromstring(document.read("word/document.xml"))
+        text = " ".join(node.text or "" for node in root.iter() if node.tag.endswith("}t"))
+        return text[:MAX_TEXT_CHARS]
+    if file_path.suffix.lower() == ".pdf":
+        try:
+            from pypdf import PdfReader
+        except ImportError as exc:
+            raise EnvironmentError(
+                "PDF classification needs the `pypdf` package. Reinstall refactor-cli to include it."
+            ) from exc
+        reader = PdfReader(file_path)
+        return "\n".join(page.extract_text() or "" for page in reader.pages)[:MAX_TEXT_CHARS]
+    return ""
+
+
+def classify_documents(
+    documents: list[Path], category_root: Path, config: dict
+) -> tuple[list[TextContext], list[tuple[Path, Exception]]]:
+    classifier = build_document_classifier(config)
+    results: list[TextContext] = []
+    failures: list[tuple[Path, Exception]] = []
+    for document in documents:
+        try:
+            is_pdf = document.suffix.lower() == ".pdf"
+            if is_pdf and document.stat().st_size > MAX_PDF_BYTES:
+                raise ValueError("PDF exceeds Refactor's 50 MB document input limit")
+            if config.get("backend") == "hosted":
+                # Preserve the hosted flow's native PDF input capability.
+                folder = classifier.choose_document_folder(
+                    document, extract_text(document), category_root, is_pdf=is_pdf
+                )
+            else:
+                folder = classifier.choose_document_folder(
+                    document, extract_text(document), category_root
+                )
+            results.append(TextContext(str(document.resolve()), folder))
+        except Exception as exc:
+            failures.append((document, exc))
+    return results, failures

{refactor_cli-0.2.0.dist-info → refactor_cli-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactor-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: CLI tool to organize files using AI
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ License-File: LICENSE
 Requires-Dist: typer
 Requires-Dist: requests
 Requires-Dist: python-dotenv
+Requires-Dist: pypdf
 Dynamic: license-file
 
 # refactor.ai
@@ -22,11 +23,15 @@ The CLI entry point in [refactor/cli.py](refactor/cli.py) provides:
 - `tree` — prints a recursive directory tree through [refactor/tree.py](refactor/tree.py).
 - `scan` — collects basic file and directory metadata through [refactor/scanner.py](refactor/scanner.py) and [refactor/metadata.py](refactor/metadata.py).
 - `setup` — configures a multimodal backend (`hosted` or `local`), persisted to `~/.refactor/config.json`.
-- `get-image-context` — obtains Imagga V3 tags/captions, asks Gemini to choose a
-  destination category, and writes JSON context.
-- `refactor-images` — automatically refreshes image context, then moves images
-  into Gemini-selected existing or new category folders (`--copy` is available
-  when the originals must be retained).
+- `get-image-context` — obtains image tags/captions and asks the configured
+  backend to choose a destination category, then writes JSON context.
+- `refactor-images` — automatically refreshes image context with the configured
+  backend, then moves images into model-selected category folders (`--copy` is
+  available when the originals must be retained).
+- `refactor-text` — uses the configured backend to categorize `.txt`, `.md`,
+  `.pdf`, and `.docx` files.
+- `now` — runs `refactor-text` and then `refactor-images`, so mixed folders are
+  organized in one invocation.
 - Path checks through [refactor/validation.py](refactor/validation.py), including existence, directory type, and read access.
 - Optional filename exclusions through [refactor/ignore.py](refactor/ignore.py).
 
@@ -39,10 +44,19 @@ After installing `refactor-cli`, the first CLI run prompts:
 1. **Hosted model (bring your own API keys)**  
    - Prompts for `IMAGGA_API_KEY`, `IMAGGA_API_SECRET`, and `GEMINI_API_KEY`  
    - Saves credentials to `~/.refactor/.env` with restricted file permissions
-2. **Local multimodal recommendation (stub)**  
-   - Detects basic hardware (CPU, memory, NVIDIA GPU/VRAM if available)  
-   - Recommends an OSS multimodal model and records it in config  
-   - Uses a local shim stub today (full local runtime integration is a follow-up)
+2. **Local multimodal model with Ollama**
+   - Detects CPU, memory, and NVIDIA hardware (even if VRAM is temporarily unavailable)
+   - Recommends a vision model and verifies the local Ollama runtime
+   - Guides the user to install Ollama or pulls the recommended model when Ollama is ready
+   - Sends images to the local Ollama API for captions, tags, and category selection; documents are text-extracted locally and categorized through the same Ollama model. No image or document data is uploaded to Refactor services.
+
+For a local setup, install [Ollama](https://ollama.com/download), then run the exact command printed by setup, for example:
+
+```shell
+ollama pull gemma3:4b
+```
+
+Run `refactor setup` again after the download finishes. Refactor verifies both the local Ollama service and the selected model before classifying images or documents.
 
 For the hosted workflow, local images are uploaded to Imagga and classified with
 the V3 `/tags` endpoint using `model=light` and `include_caption=true`. The
@@ -57,6 +71,16 @@ Run `refactor refactor-images ./incoming --output-dir ./organized` to generate
 fresh context and move the images. Add `--dry-run` to inspect destinations or
 `--copy` to retain the originals.
 
+Run `refactor now ./incoming --output-dir ./organized` to organize supported
+documents and images together. Hosted mode sends PDFs to Gemini as native
+document input; local mode text-extracts PDFs, text, Markdown, and Word files
+before sending their contents to Ollama.
+
+`--dry-run` saves a source-validated organization plan. Running the same command
+without `--dry-run` reuses that plan without another Imagga or Gemini request,
+provided the source files and output directory are unchanged. Any added, removed,
+or modified source file invalidates the plan and triggers fresh classification.
+
 ## Techniques used
 
 - **Recursive traversal with `pathlib`** — [refactor/scanner.py](refactor/scanner.py) uses [`Path.rglob()`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.rglob) to discover nested paths. [refactor/tree.py](refactor/tree.py) recursively walks directory entries to render a text tree.

refactor_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+refactor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+refactor/cli.py,sha256=8B2DFFoLiQDMGV3We1BQq9uvjmU-piiksUOjg0cQ5VE,13808
+refactor/config.py,sha256=bE45IvJHhrIfyVi7MZW_OUl8TdbavDJhdq-PKUOgOOw,1958
+refactor/context_store.py,sha256=LE7ypaOOxqTS7V8YIs1QIyDSqKZRB5_Y6B8RFg40q3g,1453
+refactor/gemini.py,sha256=TH7NBn9erhkV42JJIRH658w2dxXeT_pfG8HNh2Y7ACw,6242
+refactor/hardware.py,sha256=qhJUq0aOB6FwEIHxQ2LbckIZo0DEYf0Xi4uKoN8uB90,3589
+refactor/ignore.py,sha256=KBvsrb1ptHWuX7VU2qXuX4lYVP97fis8zuJdGKHrq-4,549
+refactor/image_scanner.py,sha256=KsJu_DWTazssmlGVO3pvl3QrzLvefRYsLWjS-PLnYzY,1055
+refactor/imagga.py,sha256=jn6t7IV63MOfF1dOzrF3ORyjaVdilPrY5FG59Xs_u3E,6472
+refactor/metadata.py,sha256=fE7L46j85S5TbcYXQTQrT2AaXW4ut_Yg4JT7z_ZgyVU,248
+refactor/organizer.py,sha256=EeLQKqFfmJCPXO3wqy1Zjd7iroV9wxiqmL7srU4XgDQ,3183
+refactor/plan_cache.py,sha256=iX3hMbeUNpiBQDY0PD2NiARXX03HpJ4uOoXsUNuJ-7A,1899
+refactor/scanner.py,sha256=epuaACLR845I0cYw9wTt5WyqPaKe_Ic0mrcuH-SB2jA,306
+refactor/setup.py,sha256=HsxjvI314DlWQhD9MI7Cw1BecUhi2zNO1NGngbKU3wY,7063
+refactor/shim.py,sha256=hRNdhJZ-iOkee18wUzy5ERaEl2JhzOtdy1VC2VJttQ0,13349
+refactor/text.py,sha256=PbKV6jKIfYklBxle-jYk2TgzuRI0y1kyaPs3sT7LSjM,3960
+refactor/tree.py,sha256=y1p2FGvmQQ5eAmuncjTqOURa6wKQ3US3VGV6pfi0DLY,446
+refactor/validation.py,sha256=SM9VaPA-VF1-UuRQqmDuYs19rgVKtHmRkIGyz4wJ_I8,374
+refactor_cli-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+refactor_cli-0.3.0.dist-info/METADATA,sha256=Az5HHH4RQXWXfd9LVbKSh3L7sukcT3s5MhNGz5S-6zs,7884
+refactor_cli-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+refactor_cli-0.3.0.dist-info/entry_points.txt,sha256=oXn5HKS9c_VwsJ-QNKFd2GKXNhlWxr_tkfueSAmWr3M,46
+refactor_cli-0.3.0.dist-info/top_level.txt,sha256=jCNAQcJGcXPbLuqADBNCQxentGSDGWA08qs5wEtb_AU,9
+refactor_cli-0.3.0.dist-info/RECORD,,

refactor_cli-0.2.0.dist-info/RECORD

@@ -1,22 +0,0 @@
-refactor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-refactor/cli.py,sha256=T0HaNhFgZ8F9BcoWkrW76y6RbEzrVhIVsNcmQiP18GU,9331
-refactor/config.py,sha256=1fQPV2f_MkP9nuwBbD3qMEWKQZ13TF1UA3q9wP315yI,1948
-refactor/context_store.py,sha256=LE7ypaOOxqTS7V8YIs1QIyDSqKZRB5_Y6B8RFg40q3g,1453
-refactor/gemini.py,sha256=tMiBHMUUt615uX4YznuIQOve-AQCKYuMBnUvTYN-2PM,4044
-refactor/hardware.py,sha256=nZjLBON3I44MP458ojGuXZNXW_rtKyQHJDkhKlt8FLw,2101
-refactor/ignore.py,sha256=KBvsrb1ptHWuX7VU2qXuX4lYVP97fis8zuJdGKHrq-4,549
-refactor/image_scanner.py,sha256=KsJu_DWTazssmlGVO3pvl3QrzLvefRYsLWjS-PLnYzY,1055
-refactor/imagga.py,sha256=jn6t7IV63MOfF1dOzrF3ORyjaVdilPrY5FG59Xs_u3E,6472
-refactor/metadata.py,sha256=fE7L46j85S5TbcYXQTQrT2AaXW4ut_Yg4JT7z_ZgyVU,248
-refactor/organizer.py,sha256=EeLQKqFfmJCPXO3wqy1Zjd7iroV9wxiqmL7srU4XgDQ,3183
-refactor/scanner.py,sha256=epuaACLR845I0cYw9wTt5WyqPaKe_Ic0mrcuH-SB2jA,306
-refactor/setup.py,sha256=O98KOtOU8V8_WyMY1zR08LRN2oKq-nIpHDpQbvIscmk,5490
-refactor/shim.py,sha256=B0_I_jn3OTBm1dA7VI3--ECnARh8_jbcOZ2Yy1pk0Zk,2604
-refactor/tree.py,sha256=y1p2FGvmQQ5eAmuncjTqOURa6wKQ3US3VGV6pfi0DLY,446
-refactor/validation.py,sha256=SM9VaPA-VF1-UuRQqmDuYs19rgVKtHmRkIGyz4wJ_I8,374
-refactor_cli-0.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-refactor_cli-0.2.0.dist-info/METADATA,sha256=Ydb0IKFPcDXl5Ew-M8KYuOB8Ry-X7dOJ3DpUtksonKM,6443
-refactor_cli-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-refactor_cli-0.2.0.dist-info/entry_points.txt,sha256=oXn5HKS9c_VwsJ-QNKFd2GKXNhlWxr_tkfueSAmWr3M,46
-refactor_cli-0.2.0.dist-info/top_level.txt,sha256=jCNAQcJGcXPbLuqADBNCQxentGSDGWA08qs5wEtb_AU,9
-refactor_cli-0.2.0.dist-info/RECORD,,