troy-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{troy_cli-0.2.1 → troy_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: troy-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Fine-tune LLMs on your MacBook with one YAML file. Built for Apple Silicon.
 Author: Troy
 License: Apache-2.0
@@ -11,6 +11,8 @@ Requires-Dist: pydantic>=2.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.12
+Provides-Extra: vision
+Requires-Dist: mlx-vlm[train]>=0.7; extra == 'vision'
 Description-Content-Type: text/markdown
 
 # Troy
@@ -79,7 +81,7 @@ output: ./output
 |---|---|
 | `troy init` | Create a config from a template (`chat`, `dpo`, `orpo`) |
 | `troy doctor` | Hardware + dependency check, with model-size guidance |
-| `troy train` | LoRA fine-tuning: SFT, DPO, or ORPO |
+| `troy train` | LoRA fine-tuning: SFT, DPO, or ORPO — text, or vision with `[vision]` extra |
 | `troy chat` | Interactive REPL (or `-p` for one-shot) with your adapter |
 | `troy eval` | Base-vs-tuned val loss, perplexity, side-by-side samples |
 | `troy serve` | OpenAI-compatible API server for your model |

{troy_cli-0.2.1 → troy_cli-0.3.0}/README.md

@@ -64,7 +64,7 @@ output: ./output
 |---|---|
 | `troy init` | Create a config from a template (`chat`, `dpo`, `orpo`) |
 | `troy doctor` | Hardware + dependency check, with model-size guidance |
-| `troy train` | LoRA fine-tuning: SFT, DPO, or ORPO |
+| `troy train` | LoRA fine-tuning: SFT, DPO, or ORPO — text, or vision with `[vision]` extra |
 | `troy chat` | Interactive REPL (or `-p` for one-shot) with your adapter |
 | `troy eval` | Base-vs-tuned val loss, perplexity, side-by-side samples |
 | `troy serve` | OpenAI-compatible API server for your model |

{troy_cli-0.2.1 → troy_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "troy-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Fine-tune LLMs on your MacBook with one YAML file. Built for Apple Silicon."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -15,6 +15,9 @@ dependencies = [
     "rich>=13.0",
 ]
 
+[project.optional-dependencies]
+vision = ["mlx-vlm[train]>=0.7"]
+
 [project.scripts]
 troy = "troy.cli:app"
 

{troy_cli-0.2.1 → troy_cli-0.3.0}/src/troy/__init__.py

@@ -1,3 +1,3 @@
 """Troy: fine-tune LLMs on your MacBook with one YAML file."""
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{troy_cli-0.2.1 → troy_cli-0.3.0}/src/troy/cli.py

@@ -120,7 +120,12 @@ def doctor() -> None:
     except ImportError:
         table.add_row("mlx-lm", f"{fail} (not installed)")
 
-    table.add_row("Fine-tunable models", model_guidance(hw.memory_gb))
+    table.add_row("Comfortable size", model_guidance(hw.memory_gb))
+    table.add_row(
+        "Supported models",
+        "any mlx-lm architecture (Llama, Qwen, Gemma, Phi, Mistral, ...)\n"
+        "thousands of ready conversions: hf.co/mlx-community",
+    )
     console.print(table)
 
     if not hw.is_apple_silicon:
@@ -137,6 +142,19 @@ def train(
     from .data import load_and_prepare
 
     cfg = load_config(config)
+
+    if Path(cfg.data.train).expanduser().is_dir():  # folder of images => vision
+        if cfg.task != "sft":
+            console.print("[red]Vision fine-tuning supports task: sft (for now).[/red]")
+            raise typer.Exit(1)
+        from .train_vision import run_vision_sft
+
+        run_vision_sft(cfg)
+        console.print(
+            '\nTry it: [bold]troy chat --image photo.png -p "your question"[/bold]'
+        )
+        return
+
     train_records, valid_records, fmt = load_and_prepare(
         cfg.data, cfg.task, cfg.training.seed
     )
@@ -174,6 +192,7 @@ def chat(
     max_tokens: int = typer.Option(512),
     temperature: float = typer.Option(0.7),
     prompt: Optional[str] = typer.Option(None, "--prompt", "-p", help="One-shot prompt (no REPL)."),
+    image: Optional[Path] = typer.Option(None, help="Image for a vision model (one-shot; needs -p)."),
 ) -> None:
     """Chat with your fine-tuned model."""
     _require_apple_silicon()
@@ -193,6 +212,14 @@ def chat(
                 console.print(
                     "[yellow]No trained adapter found — chatting with the base model.[/yellow]"
                 )
+    if image is not None:
+        if prompt is None:
+            console.print("[red]--image needs a one-shot prompt: -p \"your question\"[/red]")
+            raise typer.Exit(1)
+        from .train_vision import run_vision_chat
+
+        run_vision_chat(model, adapter, str(image), prompt, max_tokens, temperature)
+        return
     run_chat(model, adapter, max_tokens, temperature, prompt)
 
 

{troy_cli-0.2.1 → troy_cli-0.3.0}/src/troy/hardware.py

@@ -42,7 +42,8 @@ def detect() -> Hardware:
     )
 
 
-# (min unified memory GB, guidance) — QLoRA 4-bit fine-tuning headroom.
+# (min unified memory GB, guidance) — QLoRA 4-bit sizing EXAMPLES, not a
+# whitelist: any mlx-lm-supported architecture trains.
 MODEL_GUIDANCE = [
     (128, "up to ~70B (4-bit QLoRA), e.g. Llama-3.3-70B, Qwen2.5-72B"),
     (64, "up to ~32B (4-bit QLoRA), e.g. Qwen2.5-32B, Gemma-2-27B"),

troy_cli-0.3.0/src/troy/train_vision.py

@@ -0,0 +1,94 @@
+"""Vision-language fine-tuning (wraps mlx-vlm's LoRA trainer).
+
+Contract: `data.train` is a FOLDER containing images plus a metadata.jsonl
+with {"file_name", "question", "answer"} rows (HF imagefolder format).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+
+from .config import TroyConfig
+
+
+def ensure_mlx_vlm() -> None:
+    try:
+        import mlx_vlm  # noqa: F401
+    except ImportError:
+        raise SystemExit(
+            "Vision fine-tuning needs mlx-vlm. Install with:\n"
+            "  pip install 'troy-cli[vision]'"
+        )
+
+
+def count_records(data_dir: Path) -> int:
+    meta = data_dir / "metadata.jsonl"
+    if not meta.exists():
+        raise SystemExit(
+            f"{data_dir} has no metadata.jsonl. Vision data is a folder of images "
+            'plus metadata.jsonl rows: {"file_name": ..., "question": ..., "answer": ...}'
+        )
+    with open(meta) as f:
+        rows = [json.loads(line) for line in f if line.strip()]
+    if rows and not {"file_name", "question", "answer"} <= set(rows[0]):
+        raise SystemExit(
+            "metadata.jsonl rows need file_name, question, and answer fields."
+        )
+    return len(rows)
+
+
+def run_vision_sft(config: TroyConfig) -> None:
+    ensure_mlx_vlm()
+    data_dir = Path(config.data.train).expanduser()
+    n = count_records(data_dir)
+    print(f"Vision data: {n} images (folder: {data_dir})")
+
+    t = config.training
+    batch_size = 1 if t.batch_size == "auto" else int(t.batch_size)
+    iters = t.iters or max(1, math.ceil((t.epochs or 3) * n / batch_size))
+
+    config.adapter_path.mkdir(parents=True, exist_ok=True)
+    cmd = [
+        sys.executable, "-m", "mlx_vlm.lora",
+        "--model-path", config.base,
+        "--dataset", str(data_dir),
+        "--split", "train",
+        "--batch-size", str(batch_size),
+        "--iters", str(iters),
+        "--learning-rate", str(t.lr),
+        "--lora-rank", str(t.lora.r),
+        "--lora-alpha", str(t.lora.alpha),
+        "--lora-dropout", str(t.lora.dropout),
+        "--max-seq-length", str(t.seq_len),
+        "--steps-per-save", str(t.save_every),
+        "--output-path", str(config.adapter_path),
+    ]
+    if t.grad_checkpoint:
+        cmd.append("--grad-checkpoint")
+
+    print(f"Training: task=sft (vision) batch_size={batch_size} iters={iters} lr={t.lr}")
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+    print(f"\nDone. Adapter saved to {config.adapter_path}")
+
+
+def run_vision_chat(
+    model: str, adapter: str | None, image: str, prompt: str, max_tokens: int, temperature: float
+) -> None:
+    ensure_mlx_vlm()
+    cmd = [
+        sys.executable, "-m", "mlx_vlm", "generate",
+        "--model", model,
+        "--image", image,
+        "--prompt", prompt,
+        "--max-tokens", str(max_tokens),
+        "--temperature", str(temperature),
+    ]
+    if adapter:
+        cmd += ["--adapter-path", adapter]
+    raise SystemExit(subprocess.run(cmd).returncode)