Skip to content

Personal AI, On Personal Devices

Python

feat(cli): add jarvis model convert for local HF→MLX/GGUF conversion (#542)

Gilbert Barajas80b9c997eed9
diff --git a/src/openjarvis/cli/model.py b/src/openjarvis/cli/model.py
index 9e5f5617..46247d83 100644
--- a/src/openjarvis/cli/model.py
+++ b/src/openjarvis/cli/model.py
@@ -3,8 +3,14 @@
from __future__ import annotations
import os
+import re
+import shlex
+import shutil
import subprocess
import sys
+import tempfile
+import uuid
+from pathlib import Path
import click
import httpx
@@ -12,7 +18,7 @@ from rich.console import Console
from rich.panel import Panel
from rich.table import Table
-from openjarvis.core.config import load_config
+from openjarvis.core.config import DEFAULT_CONFIG_DIR, load_config
from openjarvis.core.registry import ModelRegistry
from openjarvis.engine import discover_engines, discover_models
from openjarvis.intelligence import merge_discovered_models, register_builtin_models
@@ -263,3 +269,449 @@ def pull(model_name: str, engine: str | None) -> None:
f"Manual download required for engine [cyan]{engine}[/cyan].\n"
f"Check the engine documentation for instructions."
)
+
+
+def _slug_from_repo(
+ hf_repo: str, engine: str, quantize: str | None, mlx_4bit: bool
+) -> str:
+ """Generate output directory slug from HF repo and conversion params."""
+ base = re.sub(r"[^A-Za-z0-9._-]+", "-", hf_repo.replace("/", "--"))
+ base = base.strip("._-") or "model"
+ if engine == "mlx":
+ return f"{base}-mlx-4bit" if mlx_4bit else f"{base}-mlx"
+ elif engine == "llamacpp":
+ if quantize:
+ return f"{base}-{quantize}"
+ return f"{base}-gguf"
+ return base
+
+
+def _download_snapshot(hf_repo: str, console: Console) -> str | None:
+ """Download *hf_repo* and return the concrete local snapshot directory."""
+ try:
+ from huggingface_hub import snapshot_download
+ except ImportError:
+ console.print(
+ "[red]Model conversion needs huggingface_hub.[/red]\n"
+ "Install it: [cyan]pip install huggingface_hub[/cyan]"
+ )
+ return None
+
+ try:
+ console.print(f"Downloading [cyan]{hf_repo}[/cyan]...")
+ return str(snapshot_download(repo_id=hf_repo))
+ except Exception as exc:
+ console.print(f"[red]Hugging Face download failed:[/red] {exc}")
+ return None
+
+
+def _convert_mlx(hf_repo: str, output: str, mlx_4bit: bool, console: Console) -> bool:
+ """Convert an HF model to MLX format. Returns True on success."""
+ try:
+ import mlx_lm
+ except ImportError:
+ console.print(
+ "[red]MLX conversion needs the inference-mlx extra.[/red]\n"
+ 'Install it: [cyan]pip install "openjarvis[inference-mlx]"[/cyan]'
+ )
+ return False
+
+ snapshot = _download_snapshot(hf_repo, console)
+ if snapshot is None:
+ return False
+
+ try:
+ # mlx_lm.convert deliberately refuses an existing output path. The
+ # command gives it a fresh staging destination and only publishes that
+ # directory after conversion succeeds.
+ Path(output).parent.mkdir(parents=True, exist_ok=True)
+ console.print(
+ f"Converting [cyan]{hf_repo}[/cyan] to MLX at [cyan]{output}[/cyan]..."
+ )
+ mlx_lm.convert(hf_path=snapshot, mlx_path=output, quantize=mlx_4bit)
+ if not Path(output).is_dir() or not any(Path(output).iterdir()):
+ raise RuntimeError("converter completed without producing an artifact")
+ console.print(f"[green]Converted → {output}[/green]")
+ return True
+ except Exception as exc:
+ console.print(f"[red]MLX conversion failed:[/red] {exc}")
+ return False
+
+
+def _convert_gguf(
+ hf_repo: str,
+ output: str,
+ quantize: str | None,
+ console: Console,
+ config: object | None = None,
+) -> str | None:
+ """Convert an HF model to GGUF and return the final artifact path."""
+ snapshot = _download_snapshot(hf_repo, console)
+ if snapshot is None:
+ return None
+
+ # Step 2: locate and run convert_hf_to_gguf.py
+ convert_script = _locate_convert_script(console, config)
+ if not convert_script:
+ return None
+
+ # Determine output file path
+ os.makedirs(output, exist_ok=True)
+ artifact_stem = _slug_from_repo(hf_repo, "", None, False)
+ output_gguf = os.path.join(output, f"{artifact_stem}.f16.gguf")
+
+ console.print(f"Converting to [cyan]{output_gguf}[/cyan]...")
+ try:
+ subprocess.run(
+ [
+ sys.executable,
+ convert_script,
+ snapshot,
+ "--outtype",
+ "f16",
+ "--outfile",
+ output_gguf,
+ ],
+ check=True,
+ )
+ if not os.path.isfile(output_gguf):
+ raise RuntimeError("converter completed without producing a GGUF file")
+ except FileNotFoundError:
+ console.print(
+ "[red]convert_hf_to_gguf.py not found.[/red]\n"
+ "Install llama.cpp and set [cyan]$LLAMACPP_PATH[/cyan] to the repo "
+ "root, or configure [cyan]engine.llamacpp.binary_path[/cyan]."
+ )
+ return None
+ except (subprocess.CalledProcessError, RuntimeError) as exc:
+ if isinstance(exc, RuntimeError):
+ console.print(f"[red]Conversion to GGUF failed:[/red] {exc}")
+ return None
+ console.print("[red]Conversion to GGUF failed.[/red]")
+ return None
+
+ # Step 3: optional quantization
+ if quantize:
+ console.print(f"Quantizing to [cyan]{quantize}[/cyan]...")
+ quant_script = _locate_quantize_script(console, config)
+ if not quant_script:
+ return None
+
+ quantized_out = os.path.join(output, f"{artifact_stem}.{quantize}.gguf")
+ try:
+ subprocess.run(
+ [quant_script, output_gguf, quantized_out, quantize],
+ check=True,
+ )
+ if not os.path.isfile(quantized_out):
+ raise RuntimeError("quantizer completed without producing a GGUF file")
+ console.print(f"[green]Quantized → {quantized_out}[/green]")
+ except FileNotFoundError:
+ console.print(
+ "[red]llama-quantize not found.[/red]\n"
+ "Install llama.cpp and set [cyan]$LLAMACPP_PATH[/cyan] to the "
+ "repo root, or configure "
+ "[cyan]engine.llamacpp.binary_path[/cyan]."
+ )
+ return None
+ except (subprocess.CalledProcessError, RuntimeError) as exc:
+ if isinstance(exc, RuntimeError):
+ console.print(f"[red]Quantization failed:[/red] {exc}")
+ return None
+ console.print("[red]Quantization failed.[/red]")
+ return None
+ return quantized_out
+ else:
+ console.print(f"[green]Converted → {output_gguf}[/green]")
+
+ return output_gguf
+
+
+def _llamacpp_search_roots(config: object | None) -> list[Path]:
+ """Return deduplicated llama.cpp roots from env and engine config."""
+ configured_path = ""
+ try:
+ configured_path = str(config.engine.llamacpp.binary_path) # type: ignore[attr-defined]
+ except AttributeError:
+ pass
+
+ raw_paths = [
+ os.environ.get("LLAMACPP_PATH", ""),
+ os.environ.get("LLAMA_CPP_DIR", ""),
+ configured_path,
+ ]
+ roots: list[Path] = []
+ for raw_path in raw_paths:
+ if not raw_path:
+ continue
+ path = Path(raw_path).expanduser()
+ # A configured path commonly points at build/bin/llama-server. Walk a
+ # few ancestors so the repository-level conversion script is found.
+ if path.name.startswith("llama-") or path.name.endswith(".py"):
+ path = path.parent
+ for root in (path, *list(path.parents)[:4]):
+ if root not in roots:
+ roots.append(root)
+ return roots
+
+
+def _locate_convert_script(
+ console: Console, config: object | None = None
+) -> str | None:
+ """Locate convert_hf_to_gguf.py via env, config, or PATH."""
+ for llama_dir in _llamacpp_search_roots(config):
+ script = llama_dir / "convert_hf_to_gguf.py"
+ if script.is_file():
+ return str(script)
+ # Try PATH
+ script = shutil.which("convert_hf_to_gguf.py")
+ if script:
+ return script
+ console.print(
+ "[red]convert_hf_to_gguf.py not found.[/red]\n"
+ "Install llama.cpp and set [cyan]$LLAMACPP_PATH[/cyan] to the repo "
+ "root, or configure [cyan]engine.llamacpp.binary_path[/cyan]."
+ )
+ return None
+
+
+def _locate_quantize_script(
+ console: Console, config: object | None = None
+) -> str | None:
+ """Locate llama-quantize via env, config, or PATH."""
+ for llama_dir in _llamacpp_search_roots(config):
+ # llama-quantize is typically in the main llama.cpp build directory
+ for name in (
+ "llama-quantize",
+ "bin/llama-quantize",
+ "build/bin/llama-quantize",
+ ):
+ script = llama_dir / name
+ if script.is_file():
+ return str(script)
+ # Try PATH
+ script = shutil.which("llama-quantize")
+ if script:
+ return script
+ console.print(
+ "[red]llama-quantize not found.[/red]\n"
+ "Install llama.cpp and set [cyan]$LLAMACPP_PATH[/cyan] to the repo "
+ "root, or configure [cyan]engine.llamacpp.binary_path[/cyan]."
+ )
+ return None
+
+
+def _remove_path(path: Path) -> None:
+ """Remove one file, symlink, or directory without following symlinks."""
+ if path.is_symlink() or path.is_file():
+ path.unlink()
+ elif path.is_dir():
+ shutil.rmtree(path)
+
+
+def _publish_output(staged: Path, output: Path) -> None:
+ """Publish a completed staging directory, restoring the old output on error."""
+ output.parent.mkdir(parents=True, exist_ok=True)
+ backup: Path | None = None
+ if os.path.lexists(output):
+ backup = output.with_name(f".{output.name}.backup-{uuid.uuid4().hex}")
+ os.replace(output, backup)
+ try:
+ os.replace(staged, output)
+ except Exception:
+ if backup is not None and os.path.lexists(backup):
+ os.replace(backup, output)
+ raise
+ else:
+ if backup is not None:
+ _remove_path(backup)
+
+
+def _import_ollama(
+ gguf_path: str,
+ staging_output: Path,
+ model_name: str,
+ console: Console,
+) -> bool:
+ """Import a staged GGUF into Ollama using a relocatable Modelfile."""
+ artifact = Path(gguf_path)
+ relative_artifact = artifact.relative_to(staging_output)
+ modelfile = staging_output / "Modelfile"
+ modelfile.write_text(f"FROM ./{relative_artifact.as_posix()}\n", encoding="utf-8")
+ try:
+ subprocess.run(
+ ["ollama", "create", model_name, "-f", str(modelfile)],
+ check=True,
+ )
+ except FileNotFoundError:
+ console.print(
+ "[red]ollama not found.[/red] Install Ollama and ensure the "
+ "[cyan]ollama[/cyan] command is on PATH."
+ )
+ return False
+ except subprocess.CalledProcessError:
+ console.print("[red]Ollama model import failed.[/red]")
+ return False
+ return True
+
+
[email protected]("--engine", default=None, help="Engine to convert for.")
+ "--quantize",
+ default=None,
+ help="GGUF quantization type (e.g., q4_k_m, q8_0).",
+)
+ "-q",
+ "--mlx-4bit",
+ is_flag=True,
+ default=False,
+ help="Enable 4-bit quantization for MLX.",
+)
+ "--output",
+ default=None,
+ help="Output directory for converted artifact.",
+)
+ "--force",
+ is_flag=True,
+ default=False,
+ help="Replace existing output only after conversion succeeds.",
+)
+def convert(
+ hf_repo: str,
+ engine: str | None,
+ quantize: str | None,
+ mlx_4bit: bool,
+ output: str | None,
+ force: bool,
+) -> None:
+ """Convert a Hugging Face model to a local engine format."""
+ console = Console()
+ config = load_config()
+
+ # Resolve engine and reject combinations that would otherwise be silently
+ # ignored or produce an artifact the selected runtime cannot consume.
+ engine = (engine or config.engine.default or "mlx").lower()
+ if engine in ("vllm", "sglang"):
+ console.print(
+ f"[green]No conversion needed for {engine}.[/green] It consumes "
+ f"Hugging Face repositories directly.\n"
+ f"[cyan]Start with:[/cyan] jarvis host {shlex.quote(hf_repo)} "
+ f"--backend {engine}"
+ )
+ return
+ if engine not in ("mlx", "llamacpp", "ollama"):
+ console.print(f"[red]Unsupported conversion engine:[/red] {engine}")
+ raise SystemExit(1)
+ if engine == "mlx" and quantize:
+ console.print("[red]--quantize is only valid for GGUF conversion.[/red]")
+ raise SystemExit(1)
+ if engine != "mlx" and mlx_4bit:
+ console.print("[red]--mlx-4bit is only valid with --engine mlx.[/red]")
+ raise SystemExit(1)
+ if quantize and not re.fullmatch(r"[A-Za-z0-9_]+", quantize):
+ console.print("[red]Invalid GGUF quantization name.[/red]")
+ raise SystemExit(1)
+ quantize = quantize.lower() if quantize else None
+
+ # Resolve output path
+ if output is None:
+ slug = _slug_from_repo(hf_repo, engine, quantize, mlx_4bit)
+ output = str(DEFAULT_CONFIG_DIR / "models" / slug)
+
+ # Keep the final path absolute without resolving a user-supplied symlink:
+ # --force must replace the link itself, never its target.
+ output_path = Path(os.path.abspath(Path(output).expanduser()))
+
+ # Check existing output. --force does not remove it yet: conversion happens
+ # in a sibling staging directory, so failures leave the old artifact intact.
+ if os.path.lexists(output_path):
+ # A symlink is always an existing output object, even when it points to
+ # an empty directory. Never follow it to decide whether overwriting is
+ # safe; --force replaces the link itself after conversion succeeds.
+ if output_path.is_symlink() and not force:
+ console.print(
+ f"[red]Output path exists as a symlink:[/red] {output_path}\n"
+ "Use [cyan]--force[/cyan] to overwrite."
+ )
+ sys.exit(1)
+ if output_path.is_dir() and not output_path.is_symlink():
+ contents = os.listdir(output_path)
+ if contents and not force:
+ console.print(
+ "[red]Output directory exists and is non-empty:[/red] "
+ f"{output_path}\n"
+ "Use [cyan]--force[/cyan] to overwrite."
+ )
+ sys.exit(1)
+ elif not force:
+ console.print(
+ f"[red]Output path exists as a file:[/red] {output_path}\n"
+ "Use [cyan]--force[/cyan] to overwrite."
+ )
+ sys.exit(1)
+
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ temp_root = Path(
+ tempfile.mkdtemp(prefix=f".{output_path.name}.convert-", dir=output_path.parent)
+ )
+ staged_output = temp_root / "artifact"
+ artifact_relative: Path | None = None
+ ollama_name: str | None = None
+ try:
+ if engine == "mlx":
+ if not _convert_mlx(hf_repo, str(staged_output), mlx_4bit, console):
+ raise SystemExit(1)
+ else:
+ gguf_path = _convert_gguf(
+ hf_repo,
+ str(staged_output),
+ quantize,
+ console,
+ config,
+ )
+ if gguf_path is None:
+ raise SystemExit(1)
+ artifact_relative = Path(gguf_path).relative_to(staged_output)
+ if engine == "ollama":
+ ollama_name = _slug_from_repo(
+ hf_repo.rsplit("/", 1)[-1], "", None, False
+ ).lower()
+ if not _import_ollama(
+ gguf_path,
+ staged_output,
+ ollama_name,
+ console,
+ ):
+ raise SystemExit(1)
+
+ _publish_output(staged_output, output_path)
+ finally:
+ if temp_root.exists():
+ shutil.rmtree(temp_root)
+
+ if engine == "mlx":
+ artifact = output_path
+ hint = f"jarvis host {shlex.quote(str(artifact))} --backend mlx"
+ title = "MLX conversion complete"
+ else:
+ assert artifact_relative is not None
+ artifact = output_path / artifact_relative
+ if engine == "ollama":
+ assert ollama_name is not None
+ hint = f"jarvis chat --engine ollama --model {shlex.quote(ollama_name)}"
+ title = "GGUF conversion and Ollama import complete"
+ else:
+ hint = f"jarvis host {shlex.quote(str(artifact))} --backend llamacpp"
+ title = "GGUF conversion complete"
+ console.print(
+ Panel(
+ f"[bold]Artifact:[/bold] {artifact}\n\n[cyan]Start with:[/cyan]\n {hint}",
+ title=title,
+ border_style="green",
+ )
+ )
diff --git a/tests/cli/test_model_convert.py b/tests/cli/test_model_convert.py
new file mode 100644
index 00000000..7896e4a8
--- /dev/null
+++ b/tests/cli/test_model_convert.py
@@ -0,0 +1,684 @@
+"""Tests for ``jarvis model convert`` command."""
+
+from __future__ import annotations
+
+# Import the real module via importlib to patch its attributes.
+import importlib
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+from click.testing import CliRunner
+
+from openjarvis.cli.model import model
+
+model_module = importlib.import_module("openjarvis.cli.model")
+
+
+class TestModelConvert:
+ """Tests for the convert command."""
+
+ def test_convert_mlx_quantize(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """convert some/repo -q --engine mlx calls mlx_lm.convert with quantize=True."""
+ # Create a fake output directory
+ output_dir = tmp_path / "some--repo-mlx"
+ output_dir.mkdir(parents=True)
+ snapshot = tmp_path / "snapshot"
+ snapshot.mkdir()
+
+ # Track calls to mlx_lm.convert
+ convert_calls = []
+
+ class FakeMLXLM:
+ @staticmethod
+ def convert(hf_path: str, mlx_path: str, quantize: bool) -> None:
+ convert_calls.append((hf_path, mlx_path, quantize))
+ target = Path(mlx_path)
+ target.mkdir(parents=True)
+ (target / "config.json").write_text("{}", encoding="utf-8")
+
+ # Monkeypatch sys.modules to inject fake mlx_lm
+ monkeypatch.setitem(sys.modules, "mlx_lm", FakeMLXLM)
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(snapshot)
+ )
+
+ # Monkeypatch load_config to return default engine
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ # Run the command
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ "mlx",
+ "-q",
+ "--output",
+ str(output_dir),
+ ],
+ )
+
+ assert result.exit_code == 0
+ assert len(convert_calls) == 1
+ assert convert_calls[0][0] == str(snapshot)
+ assert convert_calls[0][2] is True
+ # mlx_lm receives a fresh sibling staging path; only a complete result
+ # is published to the requested output directory.
+ assert Path(convert_calls[0][1]) != output_dir
+ assert Path(convert_calls[0][1]).parent.parent == output_dir.parent
+ assert (output_dir / "config.json").is_file()
+ assert "jarvis host" in result.output
+ assert "--backend mlx" in result.output
+
+ def test_convert_mlx_missing_extra(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """convert with --engine mlx fails when mlx_lm is not installed."""
+ # Create a fake output directory
+ output_dir = tmp_path / "some--repo-mlx"
+ output_dir.mkdir(parents=True)
+ snapshot = tmp_path / "snapshot"
+ snapshot.mkdir()
+
+ # Make import mlx_lm raise ImportError
+ real_import_func = __builtins__.get("__import__", __builtins__["__import__"])
+
+ def fake_import(name, *args, **kwargs):
+ if name == "mlx_lm" or name.startswith("mlx_lm."):
+ raise ImportError("No module named 'mlx_lm'")
+ return real_import_func(name, *args, **kwargs)
+
+ monkeypatch.setitem(__builtins__, "__import__", fake_import)
+
+ # Monkeypatch load_config
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ # Run the command
+ result = CliRunner().invoke(
+ model,
+ ["convert", "some/repo", "--engine", "mlx", "--output", str(output_dir)],
+ )
+
+ assert result.exit_code == 1
+ assert "inference-mlx" in result.output
+
+ def test_convert_engine_defaults_to_config(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """convert some/repo with no --engine uses config.engine.default == 'mlx'."""
+ # Create a fake output directory
+ output_dir = tmp_path / "some--repo-mlx"
+ output_dir.mkdir(parents=True)
+ snapshot = tmp_path / "snapshot"
+ snapshot.mkdir()
+
+ # Track calls to mlx_lm.convert
+ convert_calls = []
+
+ class FakeMLXLM:
+ @staticmethod
+ def convert(hf_path: str, mlx_path: str, quantize: bool) -> None:
+ convert_calls.append((hf_path, mlx_path, quantize))
+ target = Path(mlx_path)
+ target.mkdir(parents=True)
+ (target / "config.json").write_text("{}", encoding="utf-8")
+
+ monkeypatch.setitem(sys.modules, "mlx_lm", FakeMLXLM)
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(snapshot)
+ )
+
+ # Monkeypatch load_config to return mlx as default
+ class FakeConfig:
+ class Engine:
+ default = "mlx"
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ # Run the command without --engine flag
+ result = CliRunner().invoke(
+ model, ["convert", "some/repo", "--output", str(output_dir)]
+ )
+
+ assert result.exit_code == 0
+ assert len(convert_calls) == 1
+
+ def test_snapshot_download_returns_concrete_cache_path(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ snapshot = tmp_path / "models--some--repo" / "snapshots" / "revision"
+ snapshot.mkdir(parents=True)
+ calls = []
+
+ def fake_snapshot_download(*, repo_id: str):
+ calls.append(repo_id)
+ return snapshot
+
+ monkeypatch.setitem(
+ sys.modules,
+ "huggingface_hub",
+ SimpleNamespace(snapshot_download=fake_snapshot_download),
+ )
+
+ resolved = model_module._download_snapshot("some/repo", MagicMock())
+
+ assert resolved == str(snapshot)
+ assert calls == ["some/repo"]
+
+ def test_convert_gguf_shells_and_quantizes(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """llamacpp + --quantize shells the converter and the quantizer."""
+ # Create a fake output directory
+ output_dir = tmp_path / "some--repo-q4_k_m"
+ output_dir.mkdir(parents=True)
+ snapshot = tmp_path / "snapshot"
+ snapshot.mkdir()
+
+ # Track subprocess calls
+ subprocess_calls = []
+
+ def fake_subprocess_run(args, check=False, **kwargs):
+ subprocess_calls.append(args)
+ if args[0] == "/fake/llama-quantize":
+ Path(args[2]).write_bytes(b"quantized")
+ else:
+ Path(args[args.index("--outfile") + 1]).write_bytes(b"f16")
+ return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
+
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(snapshot)
+ )
+
+ # Monkeypatch locators to return fake paths
+ monkeypatch.setattr(
+ model_module,
+ "_locate_convert_script",
+ lambda console, config=None: "/fake/convert_hf_to_gguf.py",
+ )
+ monkeypatch.setattr(
+ model_module,
+ "_locate_quantize_script",
+ lambda console, config=None: "/fake/llama-quantize",
+ )
+
+ # Patch subprocess.run at the module level (where it's imported).
+ monkeypatch.setattr("subprocess.run", fake_subprocess_run)
+
+ # Monkeypatch load_config
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ # Run the command
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ "llamacpp",
+ "--quantize",
+ "q4_k_m",
+ "--output",
+ str(output_dir),
+ ],
+ )
+
+ assert result.exit_code == 0
+
+ # Check both subprocess calls were made
+ assert any("convert_hf_to_gguf.py" in " ".join(c) for c in subprocess_calls)
+ assert any("llama-quantize" in " ".join(c) for c in subprocess_calls)
+ converter_out = Path(subprocess_calls[0][-1])
+ assert subprocess_calls[0][:-1] == [
+ sys.executable,
+ "/fake/convert_hf_to_gguf.py",
+ str(snapshot),
+ "--outtype",
+ "f16",
+ "--outfile",
+ ]
+ assert converter_out.name == "some--repo.f16.gguf"
+ assert subprocess_calls[1] == [
+ "/fake/llama-quantize",
+ str(converter_out),
+ str(converter_out.with_name("some--repo.q4_k_m.gguf")),
+ "q4_k_m",
+ ]
+ assert (output_dir / "some--repo.q4_k_m.gguf").read_bytes() == b"quantized"
+ assert "jarvis host" in result.output
+ assert "--backend llamacpp" in result.output
+
+ def test_convert_gguf_missing_tool(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """convert with --engine llamacpp fails when convert script is missing."""
+ # Create a fake output directory
+ output_dir = tmp_path / "some--repo-gguf"
+ output_dir.mkdir(parents=True)
+
+ snapshot = tmp_path / "snapshot"
+ snapshot.mkdir()
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(snapshot)
+ )
+
+ # Monkeypatch locator to return None (tool not found)
+ def fake_locate_convert_script(console, config=None):
+ console.print(
+ "[red]convert_hf_to_gguf.py not found.[/red]\n"
+ "Install llama.cpp and set [cyan]$LLAMA_CPP_DIR[/cyan] "
+ "to the repo root."
+ )
+ return None
+
+ monkeypatch.setattr(
+ model_module, "_locate_convert_script", fake_locate_convert_script
+ )
+
+ # Monkeypatch load_config
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ # Run the command
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ "llamacpp",
+ "--output",
+ str(output_dir),
+ ],
+ )
+
+ assert result.exit_code == 1
+ assert (
+ "convert_hf_to_gguf.py" in result.output
+ or "llama.cpp" in result.output.lower()
+ )
+
+ def test_convert_refuses_nonempty_output(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """convert refuses to overwrite non-empty output without --force."""
+ # Create a fake output directory with existing content
+ output_dir = tmp_path / "some--repo-mlx"
+ output_dir.mkdir(parents=True)
+ (output_dir / "existing_file.txt").write_text("keep")
+
+ # Monkeypatch mlx_lm to track if it would be called (should not be)
+ convert_calls = []
+
+ class FakeMLXLM:
+ @staticmethod
+ def convert(hf_path: str, mlx_path: str, quantize: bool) -> None:
+ convert_calls.append((hf_path, mlx_path, quantize))
+ target = Path(mlx_path)
+ target.mkdir(parents=True)
+ (target / "config.json").write_text("{}", encoding="utf-8")
+
+ monkeypatch.setitem(sys.modules, "mlx_lm", FakeMLXLM)
+ snapshot = tmp_path / "snapshot"
+ snapshot.mkdir()
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(snapshot)
+ )
+
+ # Monkeypatch load_config
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ # Run without --force
+ result = CliRunner().invoke(
+ model,
+ ["convert", "some/repo", "--engine", "mlx", "--output", str(output_dir)],
+ )
+
+ assert result.exit_code == 1
+ assert "--force" in result.output
+ assert len(convert_calls) == 0 # mlx_lm.convert should NOT be called
+
+ # Now run WITH --force
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ "mlx",
+ "--output",
+ str(output_dir),
+ "--force",
+ ],
+ )
+
+ assert result.exit_code == 0
+ assert len(convert_calls) == 1
+ assert not (output_dir / "existing_file.txt").exists()
+ assert (output_dir / "config.json").is_file()
+ assert list(tmp_path.glob(".some--repo-mlx.convert-*")) == []
+
+ def test_force_failure_preserves_existing_output(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """A failed forced conversion cannot destroy the previous artifact."""
+ output_dir = tmp_path / "some--repo-mlx"
+ output_dir.mkdir(parents=True)
+ sentinel = output_dir / "existing_file.txt"
+ sentinel.write_text("keep", encoding="utf-8")
+
+ class FailingMLXLM:
+ @staticmethod
+ def convert(hf_path: str, mlx_path: str, quantize: bool) -> None:
+ target = Path(mlx_path)
+ target.mkdir(parents=True)
+ (target / "partial.bin").write_bytes(b"partial")
+ raise RuntimeError("conversion interrupted")
+
+ monkeypatch.setitem(sys.modules, "mlx_lm", FailingMLXLM)
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(tmp_path / "snapshot")
+ )
+
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ "mlx",
+ "--output",
+ str(output_dir),
+ "--force",
+ ],
+ )
+
+ assert result.exit_code == 1
+ assert sentinel.read_text(encoding="utf-8") == "keep"
+ assert not (output_dir / "partial.bin").exists()
+ assert list(tmp_path.glob(".some--repo-mlx.convert-*")) == []
+
+ def test_publish_failure_rolls_back_existing_output(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ output_dir = tmp_path / "model"
+ output_dir.mkdir()
+ sentinel = output_dir / "old.bin"
+ sentinel.write_bytes(b"old")
+ staged = tmp_path / "staged"
+ staged.mkdir()
+ (staged / "new.bin").write_bytes(b"new")
+ real_replace = model_module.os.replace
+
+ def fail_publish(source, destination):
+ if Path(source) == staged and Path(destination) == output_dir:
+ raise OSError("simulated publish failure")
+ return real_replace(source, destination)
+
+ monkeypatch.setattr(model_module.os, "replace", fail_publish)
+
+ with pytest.raises(OSError, match="simulated publish failure"):
+ model_module._publish_output(staged, output_dir)
+
+ assert sentinel.read_bytes() == b"old"
+ assert staged.joinpath("new.bin").read_bytes() == b"new"
+ assert list(tmp_path.glob(".model.backup-*")) == []
+
+ def test_force_replaces_symlink_without_touching_target(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ target = tmp_path / "target"
+ target.mkdir()
+ sentinel = target / "keep.txt"
+ sentinel.write_text("keep", encoding="utf-8")
+ output_dir = tmp_path / "model-link"
+ output_dir.symlink_to(target, target_is_directory=True)
+
+ class FakeMLXLM:
+ @staticmethod
+ def convert(hf_path: str, mlx_path: str, quantize: bool) -> None:
+ converted = Path(mlx_path)
+ converted.mkdir(parents=True)
+ (converted / "config.json").write_text("{}", encoding="utf-8")
+
+ monkeypatch.setitem(sys.modules, "mlx_lm", FakeMLXLM)
+ monkeypatch.setattr(
+ model_module, "_download_snapshot", lambda *args: str(tmp_path / "snapshot")
+ )
+
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ "mlx",
+ "--output",
+ str(output_dir),
+ "--force",
+ ],
+ )
+
+ assert result.exit_code == 0
+ assert not output_dir.is_symlink()
+ assert (output_dir / "config.json").is_file()
+ assert sentinel.read_text(encoding="utf-8") == "keep"
+
+ def test_convert_refuses_empty_directory_symlink_without_force(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ target = tmp_path / "empty-target"
+ target.mkdir()
+ output_dir = tmp_path / "model-link"
+ output_dir.symlink_to(target, target_is_directory=True)
+
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ result = CliRunner().invoke(
+ model,
+ ["convert", "some/repo", "--engine", "mlx", "--output", str(output_dir)],
+ )
+
+ assert result.exit_code == 1
+ assert "symlink" in result.output
+ assert "--force" in result.output
+ assert output_dir.is_symlink()
+ assert list(target.iterdir()) == []
+
+ def test_convert_ollama_creates_model_from_gguf(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Ollama conversion creates a GGUF-backed model via a Modelfile."""
+ output_dir = tmp_path / "some--repo-ollama"
+ subprocess_calls: list[list[str]] = []
+
+ def fake_convert_gguf(hf_repo, output, quantize, console, config=None):
+ target = Path(output)
+ target.mkdir(parents=True)
+ gguf = target / "some--repo.f16.gguf"
+ gguf.write_bytes(b"gguf")
+ return str(gguf)
+
+ def fake_subprocess_run(args, check=False, **kwargs):
+ subprocess_calls.append(args)
+ modelfile = Path(args[-1])
+ assert modelfile.read_text(encoding="utf-8") == (
+ "FROM ./some--repo.f16.gguf\n"
+ )
+ return subprocess.CompletedProcess(args, 0)
+
+ monkeypatch.setattr(model_module, "_convert_gguf", fake_convert_gguf)
+ monkeypatch.setattr(model_module.subprocess, "run", fake_subprocess_run)
+
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ result = CliRunner().invoke(
+ model,
+ ["convert", "some/repo", "--engine", "ollama", "--output", str(output_dir)],
+ )
+
+ assert result.exit_code == 0
+ assert subprocess_calls == [
+ ["ollama", "create", "repo", "-f", subprocess_calls[0][-1]]
+ ]
+ assert (output_dir / "some--repo.f16.gguf").read_bytes() == b"gguf"
+ assert (output_dir / "Modelfile").read_text(encoding="utf-8") == (
+ "FROM ./some--repo.f16.gguf\n"
+ )
+ assert "jarvis chat --engine ollama --model repo" in result.output
+
+ @pytest.mark.parametrize("engine", ["vllm", "sglang"])
+ def test_direct_hf_engines_are_noop(
+ self, engine: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ output_dir = tmp_path / "must-not-exist"
+
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+
+ result = CliRunner().invoke(
+ model,
+ [
+ "convert",
+ "some/repo",
+ "--engine",
+ engine,
+ "--output",
+ str(output_dir),
+ ],
+ )
+
+ assert result.exit_code == 0
+ assert not output_dir.exists()
+ assert f"jarvis host some/repo --backend {engine}" in result.output
+
+ def test_llamacpp_tools_found_from_configured_binary(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ repo = tmp_path / "llama.cpp"
+ converter = repo / "convert_hf_to_gguf.py"
+ quantizer = repo / "build" / "bin" / "llama-quantize"
+ binary = repo / "build" / "bin" / "llama-server"
+ converter.parent.mkdir(parents=True)
+ converter.write_text("", encoding="utf-8")
+ quantizer.parent.mkdir(parents=True)
+ quantizer.write_text("", encoding="utf-8")
+ binary.write_text("", encoding="utf-8")
+ config = SimpleNamespace(
+ engine=SimpleNamespace(llamacpp=SimpleNamespace(binary_path=str(binary)))
+ )
+ monkeypatch.delenv("LLAMACPP_PATH", raising=False)
+ monkeypatch.delenv("LLAMA_CPP_DIR", raising=False)
+ monkeypatch.setattr(model_module.shutil, "which", lambda _: None)
+
+ assert model_module._locate_convert_script(MagicMock(), config) == str(
+ converter
+ )
+ assert model_module._locate_quantize_script(MagicMock(), config) == str(
+ quantizer
+ )
+
+ @pytest.mark.parametrize(
+ ("args", "message"),
+ [
+ (["--engine", "mlx", "--quantize", "q4_k_m"], "--quantize"),
+ (["--engine", "llamacpp", "--mlx-4bit"], "--mlx-4bit"),
+ (["--engine", "llamacpp", "--quantize", "../bad"], "Invalid"),
+ (["--engine", "unknown"], "Unsupported"),
+ ],
+ )
+ def test_invalid_engine_options_fail_before_writing(
+ self,
+ args: list[str],
+ message: str,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ ) -> None:
+ output_dir = tmp_path / "must-not-exist"
+
+ class FakeConfig:
+ class Engine:
+ default = None
+
+ engine = Engine()
+
+ monkeypatch.setattr(model_module, "load_config", lambda: FakeConfig())
+ result = CliRunner().invoke(
+ model,
+ ["convert", "some/repo", *args, "--output", str(output_dir)],
+ )
+
+ assert result.exit_code == 1
+ assert message in result.output
+ assert not output_dir.exists()