troy-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{troy_cli-0.4.0 → troy_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: troy-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Fine-tune LLMs on your MacBook with one YAML file. Built for Apple Silicon.
 Author: Troy
 License: Apache-2.0
@@ -88,6 +88,25 @@ output: ./output
 | `troy export` | Fuse the adapter; export MLX or GGUF |
 | `troy push` | Upload adapter or fused model to the Hugging Face Hub |
 | `troy data inspect` | Dataset stats and format detection |
+| `troy data synth` | Synthesize a dataset with a local teacher model |
+| `troy mesh serve` | Coordinate a LAN mesh: iPhones and Macs generate the dataset for you |
+| `troy mesh join` | Join a mesh as a worker from any Mac |
+
+## The mesh: your idle iPhones generate the dataset
+
+`troy data synth` runs the teacher on one Mac. `troy mesh` farms the same job
+out to every Apple device on your network — the coordinator mints prompts and
+validates results (identical parsing to local synth), workers run the teacher:
+
+```bash
+troy mesh serve --from ./docs --n 500     # Mac: prints URL + token
+troy mesh join http://mac:8765 --token …  # any other Mac
+# iPhones: the TroyWorker app (examples/ios/TroyWorker)
+```
+
+Workers can drop out at any time — leased work requeues automatically, and
+duplicates are rejected centrally. The output is a normal `train.jsonl`:
+validate it, then `troy train`.
 
 ## What Troy can train on your Mac
 

{troy_cli-0.4.0 → troy_cli-0.5.0}/README.md

@@ -71,6 +71,25 @@ output: ./output
 | `troy export` | Fuse the adapter; export MLX or GGUF |
 | `troy push` | Upload adapter or fused model to the Hugging Face Hub |
 | `troy data inspect` | Dataset stats and format detection |
+| `troy data synth` | Synthesize a dataset with a local teacher model |
+| `troy mesh serve` | Coordinate a LAN mesh: iPhones and Macs generate the dataset for you |
+| `troy mesh join` | Join a mesh as a worker from any Mac |
+
+## The mesh: your idle iPhones generate the dataset
+
+`troy data synth` runs the teacher on one Mac. `troy mesh` farms the same job
+out to every Apple device on your network — the coordinator mints prompts and
+validates results (identical parsing to local synth), workers run the teacher:
+
+```bash
+troy mesh serve --from ./docs --n 500     # Mac: prints URL + token
+troy mesh join http://mac:8765 --token …  # any other Mac
+# iPhones: the TroyWorker app (examples/ios/TroyWorker)
+```
+
+Workers can drop out at any time — leased work requeues automatically, and
+duplicates are rejected centrally. The output is a normal `train.jsonl`:
+validate it, then `troy train`.
 
 ## What Troy can train on your Mac
 

{troy_cli-0.4.0 → troy_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "troy-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Fine-tune LLMs on your MacBook with one YAML file. Built for Apple Silicon."
 readme = "README.md"
 requires-python = ">=3.10"

{troy_cli-0.4.0 → troy_cli-0.5.0}/src/troy/__init__.py

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

{troy_cli-0.4.0 → troy_cli-0.5.0}/src/troy/cli.py

@@ -258,14 +258,14 @@ def serve(
 @app.command()
 def export(
     config: Path = typer.Option(Path("troy.yaml"), "--config", "-c", help="Config file."),
-    fmt: str = typer.Option("mlx", "--format", "-f", help="Export format: mlx or gguf."),
+    fmt: str = typer.Option("mlx", "--format", "-f", help="Export format: mlx, gguf, or ios."),
     save_path: Optional[Path] = typer.Option(None, help="Output directory (default: <output>/fused)."),
     dequantize: bool = typer.Option(False, help="Dequantize when fusing a quantized base."),
 ) -> None:
     """Merge the trained adapter into the base model and export it."""
     _require_apple_silicon()
-    if fmt not in ("mlx", "gguf"):
-        console.print("[red]--format must be `mlx` or `gguf`.[/red]")
+    if fmt not in ("mlx", "gguf", "ios"):
+        console.print("[red]--format must be `mlx`, `gguf`, or `ios`.[/red]")
         raise typer.Exit(1)
     from .config import load_config
     from .export import run_export
@@ -378,7 +378,15 @@ def synth(
     n: int = typer.Option(100, "--n", help="Number of examples to generate."),
     fmt: str = typer.Option(
         "chat", "--format", "-f",
-        help="Output format: chat (SFT) or preference (DPO/ORPO).",
+        help="Output format: chat (SFT), preference (DPO/ORPO), or tools (tool calling).",
+    ),
+    tools: Optional[Path] = typer.Option(
+        None, "--tools",
+        help="For -f tools: JSON file with the tool schemas (OpenAI function format).",
+    ),
+    no_think: bool = typer.Option(
+        False, "--no-think",
+        help="For -f tools: omit the <think> reasoning traces.",
     ),
     teacher: str = typer.Option(
         "auto", help="Teacher model (auto = sized to this Mac's memory)."
@@ -398,9 +406,22 @@ def synth(
             '--from ./docs and/or --seed "task description".'
         )
         raise typer.Exit(1)
-    if fmt not in ("chat", "preference"):
-        console.print("[red]--format must be `chat` or `preference`.[/red]")
+    if fmt not in ("chat", "preference", "tools"):
+        console.print("[red]--format must be `chat`, `preference`, or `tools`.[/red]")
         raise typer.Exit(1)
+    if fmt == "tools":
+        if tools is None or not tools.exists():
+            console.print(
+                "[red]-f tools needs --tools schemas.json[/red] — a JSON list of "
+                "OpenAI-style function specs the assistant can call."
+            )
+            raise typer.Exit(1)
+        if seed is None:
+            console.print(
+                '[red]-f tools needs --seed[/red] — it becomes the system prompt, '
+                'e.g. "travel planning assistant that books nothing".'
+            )
+            raise typer.Exit(1)
 
     from .synth import pick_teacher, run_synth
 
@@ -416,6 +437,7 @@ def synth(
         n=n, out_path=out, fmt=fmt, teacher=teacher,
         seed_task=seed, source=source,
         max_tokens=max_tokens, temperature=temperature,
+        tools_path=tools, think=not no_think,
     )
     console.print(
         f"\nWrote [bold]{stats['records']}[/bold] examples to [bold]{stats['out']}[/bold] "
@@ -432,5 +454,156 @@ def synth(
     )
 
 
+mesh_app = typer.Typer(
+    name="mesh",
+    help="Distribute data synthesis across devices on your LAN.",
+    no_args_is_help=True,
+)
+app.add_typer(mesh_app)
+
+
+@mesh_app.command("serve")
+def mesh_serve(
+    source: Optional[Path] = typer.Option(
+        None, "--from", help="Ground examples in a file or folder of docs/code."
+    ),
+    seed: Optional[str] = typer.Option(
+        None, "--seed", help='Task description, e.g. "customer support bot for Acme".'
+    ),
+    n: int = typer.Option(100, "--n", help="Number of examples to generate."),
+    fmt: str = typer.Option(
+        "chat", "--format", "-f",
+        help="Output format: chat (SFT), preference (DPO/ORPO), or tools (tool calling).",
+    ),
+    tools: Optional[Path] = typer.Option(
+        None, "--tools",
+        help="For -f tools: JSON file with the tool schemas (OpenAI function format).",
+    ),
+    no_think: bool = typer.Option(
+        False, "--no-think",
+        help="For -f tools: omit the <think> reasoning traces.",
+    ),
+    out: Optional[Path] = typer.Option(
+        None, "--out", "-o",
+        help="Output file (default: data/train.jsonl or data/preferences.jsonl).",
+    ),
+    max_tokens: int = typer.Option(2048, help="Max tokens per teacher call."),
+    temperature: float = typer.Option(0.8),
+    host: str = typer.Option("0.0.0.0", help="Interface to bind."),
+    port: int = typer.Option(8765),
+    token: Optional[str] = typer.Option(
+        None, help="Shared worker token (default: generated at startup)."
+    ),
+    lease_timeout: float = typer.Option(
+        300.0, help="Seconds before an unanswered work item is requeued."
+    ),
+    linger: float = typer.Option(
+        30.0, help="Seconds to wait for in-flight results after the target is hit."
+    ),
+) -> None:
+    """Coordinate a mesh: serve synth work to iPhones and Macs on your LAN.
+
+    Workers run the teacher model; this machine only mints prompts and
+    validates results, so it can be any Mac (the model never loads here).
+    """
+    if source is None and seed is None:
+        console.print(
+            '[red]Give the workers something to work from:[/red] '
+            '--from ./docs and/or --seed "task description".'
+        )
+        raise typer.Exit(1)
+    if fmt not in ("chat", "preference", "tools"):
+        console.print("[red]--format must be `chat`, `preference`, or `tools`.[/red]")
+        raise typer.Exit(1)
+    if fmt == "tools":
+        if tools is None or not tools.exists():
+            console.print(
+                "[red]-f tools needs --tools schemas.json[/red] — a JSON list of "
+                "OpenAI-style function specs the assistant can call."
+            )
+            raise typer.Exit(1)
+        if seed is None:
+            console.print(
+                '[red]-f tools needs --seed[/red] — it becomes the system prompt.'
+            )
+            raise typer.Exit(1)
+    out = out or Path("data") / ("preferences.jsonl" if fmt == "preference" else "train.jsonl")
+    if out.exists():
+        console.print(f"[red]{out} already exists[/red] — pass -o to write elsewhere.")
+        raise typer.Exit(1)
+
+    import secrets
+
+    from rich.panel import Panel
+
+    from .mesh import MeshState, lan_ip, run_mesh_serve
+    from .synth import prepare_synth
+
+    token = token or secrets.token_urlsafe(16)
+    state = MeshState(
+        prepare_synth(fmt, seed, source, tools), n, out,
+        max_tokens=max_tokens, temperature=temperature,
+        lease_timeout=lease_timeout, think=not no_think,
+    )
+    join_url = f"http://{lan_ip()}:{port}"
+    console.print(Panel.fit(
+        f"Join from a Mac:   [bold]troy mesh join {join_url} --token {token}[/bold]\n"
+        f"Join from iPhone:  TroyWorker app → {join_url} + token [bold]{token}[/bold]",
+        title="troy mesh coordinator",
+    ))
+
+    try:
+        stats = run_mesh_serve(state, host, port, token, linger=linger)
+    except OSError as e:
+        state.close()
+        if out.exists() and out.stat().st_size == 0:
+            out.unlink()  # nothing was written; don't block a relaunch
+        console.print(f"[red]Can't bind {host}:{port}[/red] ({e.strerror}) — "
+                      "pass --port to use a different one.")
+        raise typer.Exit(1)
+    console.print(
+        f"\nWrote [bold]{stats['records']}[/bold] examples to [bold]{stats['out']}[/bold] "
+        f"across {len(stats['workers'])} worker(s)"
+    )
+    if stats["records"] < stats["target"]:
+        console.print(
+            f"[yellow]Stopped at {stats['records']}/{stats['target']}.[/yellow]"
+        )
+    console.print(
+        "Review the data before training — spot-check a dozen examples, then: "
+        f"[bold]troy data validate {out}[/bold] and [bold]troy train[/bold]."
+    )
+
+
+@mesh_app.command("join")
+def mesh_join(
+    url: str = typer.Argument(..., help="Coordinator URL, e.g. http://192.168.1.5:8765"),
+    token: str = typer.Option(..., help="Token printed by `troy mesh serve`."),
+    model: str = typer.Option(
+        "auto", help="Teacher model to run here (auto = sized to this Mac's memory)."
+    ),
+    name: Optional[str] = typer.Option(
+        None, help="Worker name shown on the coordinator (default: hostname)."
+    ),
+    batch: int = typer.Option(2, help="Work items to lease per request."),
+) -> None:
+    """Join a mesh as a worker: run the teacher here, send results back."""
+    _require_apple_silicon()
+
+    import socket
+
+    from .mesh import run_mesh_join
+    from .synth import pick_teacher
+
+    if model == "auto":
+        model = pick_teacher()
+        console.print(f"Teacher: [bold]{model}[/bold] (picked for this Mac's memory)")
+    stats = run_mesh_join(url, token, model, name or socket.gethostname(), batch=batch)
+    console.print(
+        f"\nDone: completed [bold]{stats['completed']}[/bold] work item(s) "
+        f"({stats.get('records', '?')}/{stats.get('target', '?')} mesh total)."
+    )
+
+
 if __name__ == "__main__":
     app()

{troy_cli-0.4.0 → troy_cli-0.5.0}/src/troy/data.py

@@ -62,6 +62,10 @@ _SHAREGPT_ROLES = {
 def _to_messages(record: Dict[str, Any], fmt: str) -> Dict[str, Any]:
     """Normalize an SFT record to mlx-lm chat format ({"messages": [...]})."""
     if fmt == "chat":
+        # Preserve a per-record `tools` list — mlx-lm passes it to the chat
+        # template so tool schemas render exactly as they will at inference.
+        if "tools" in record:
+            return {"messages": record["messages"], "tools": record["tools"]}
         return {"messages": record["messages"]}
     if fmt == "sharegpt":
         messages = [

troy_cli-0.5.0/src/troy/export.py

@@ -0,0 +1,242 @@
+"""Merge adapters and export to deployment formats (MLX, GGUF)."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _fuse(base: str, adapter_path: str, save_path: str, dequantize: bool) -> None:
+    cmd = [
+        sys.executable,
+        "-m",
+        "mlx_lm",
+        "fuse",
+        "--model",
+        base,
+        "--adapter-path",
+        adapter_path,
+        "--save-path",
+        save_path,
+    ]
+    if dequantize:
+        cmd.append("--dequantize")
+    print("Fusing adapter into base model ...")
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+
+def _export_gguf(save_path: Path) -> Path:
+    """Convert a fused MLX model directory to GGUF (llama/mistral/mixtral archs)."""
+    import json
+
+    import mlx.core as mx
+    from mlx_lm import gguf as gguf_mod
+
+    with open(save_path / "config.json") as f:
+        config = json.load(f)
+
+    weights = {}
+    for part in sorted(save_path.glob("*.safetensors")):
+        weights.update(mx.load(str(part)))
+
+    # mlx-lm's converter permutes attention weights into non-contiguous views,
+    # which save_gguf rejects — force contiguity on its output.
+    orig_permute = gguf_mod.permute_weights
+    gguf_mod.permute_weights = lambda *a, **k: mx.contiguous(orig_permute(*a, **k))
+    try:
+        out = save_path / "ggml-model-f16.gguf"
+        gguf_mod.convert_to_gguf(save_path, weights, config, str(out))
+    finally:
+        gguf_mod.permute_weights = orig_permute
+    return out
+
+
+# model_type values registered in mlx-swift-lm's LLMTypeRegistry (MLXLLM).
+# Fused models outside this set won't load in an iOS app using mlx-swift-lm.
+_IOS_SUPPORTED_MODEL_TYPES = {
+    "mistral", "mixtral", "llama", "phi", "phi3", "phimoe",
+    "gemma", "gemma2", "gemma3", "gemma3_text", "gemma3n",
+    "gemma4", "gemma4_unified", "gemma4_text",
+    "qwen2", "qwen3", "qwen3_moe", "qwen3_next",
+    "qwen3_5", "qwen3_5_moe", "qwen3_5_text",
+    "minicpm", "starcoder2", "cohere", "openelm", "internlm2",
+    "deepseek_v2", "deepseek_v3", "granite", "helium", "granitemoehybrid",
+    "glm4", "glm4_moe", "glm4_moe_lite", "falcon_h1", "bitnet", "smollm3",
+    "ernie4_5", "lfm2", "lfm2_moe", "exaone4", "gpt_oss", "olmoe", "olmo2",
+    "olmo3", "nemotron_h", "jamba", "mamba2", "mistral3", "apertus",
+}
+
+# On an 8 GB iPhone, an app with the Increased Memory Limit entitlement gets
+# roughly 6 GB resident; weights + KV cache + app overhead must fit inside it.
+_IOS_COMFORTABLE_GB = 2.2   # loads without entitlements on recent iPhones
+_IOS_MAX_GB = 4.0           # needs Increased Memory Limit / Extended Virtual Addressing
+
+_IOS_README = """\
+# Run this model on iPhone / iPad with MLX Swift
+
+This directory is a fused MLX model in the layout `mlx-swift-lm` loads directly.
+
+## Load it
+
+Add the Swift package: https://github.com/ml-explore/mlx-swift-lm
+
+```swift
+import MLXLLM
+import MLXLMCommon
+
+// From a local directory bundled with (or downloaded by) your app:
+let modelDirectory: URL = ...  // this folder on device
+let container = try await LLMModelFactory.shared.loadContainer(
+    configuration: ModelConfiguration(directory: modelDirectory))
+
+let result = try await container.perform { context in
+    let input = try await context.processor.prepare(
+        input: .init(prompt: "Hello!"))
+    return try MLXLMCommon.generate(
+        input: input, parameters: .init(), context: context)
+}
+```
+
+Weights this large should not ship inside the app bundle — download them on
+first launch (Background Assets, or a direct download from your server or the
+Hugging Face Hub via `troy push`).
+
+## Memory entitlements
+
+Models over ~2 GB need one of these capabilities in Xcode
+(Signing & Capabilities → + Capability):
+
+- **Increased Memory Limit** (`com.apple.developer.kernel.increased-memory-limit`)
+- **Extended Virtual Addressing**
+
+Either is usually sufficient; devices with 8 GB RAM run 4-bit models up to
+roughly 4 GB of weights. Test on the oldest device you target.
+"""
+
+
+def _base_is_quantized(base: str) -> bool:
+    import json
+
+    p = Path(base)
+    if not p.exists():
+        from huggingface_hub import snapshot_download
+
+        p = Path(snapshot_download(base, allow_patterns=["config.json"]))
+    return "quantization" in json.loads((p / "config.json").read_text())
+
+
+def _fuse_for_ios(base: str, adapter_path: str, save_path: str) -> None:
+    """Fuse for iOS without destroying the adapter.
+
+    Fusing a LoRA into 4-bit weights loses the deltas to quantization noise —
+    the exported model silently behaves like the base. So for a quantized
+    base: dequantize-fuse to fp16, then requantize fresh at 8 bits (verified
+    to preserve tuned behavior; 6 bits already degrades it).
+    """
+    import shutil
+    import tempfile
+
+    if not _base_is_quantized(base):
+        _fuse(base, adapter_path, save_path, dequantize=False)
+        return
+    from mlx_lm import convert
+
+    print("Quantized base: dequantize-fusing, then requantizing at 8 bits")
+    print("(fusing straight into 4-bit silently erases the adapter).")
+    out = Path(save_path)
+    if out.exists():
+        shutil.rmtree(out)
+    with tempfile.TemporaryDirectory() as td:
+        _fuse(base, adapter_path, td, dequantize=True)
+        convert(td, mlx_path=str(out), quantize=True, q_bits=8)
+
+
+def _dir_weight_bytes(save_path: Path) -> int:
+    return sum(p.stat().st_size for p in save_path.glob("*.safetensors"))
+
+
+def _export_ios(save_path: Path) -> None:
+    """Validate a fused MLX directory for mlx-swift-lm on iOS and add a how-to."""
+    import json
+
+    with open(save_path / "config.json") as f:
+        config = json.load(f)
+
+    problems = []
+    model_type = config.get("model_type", "?")
+    if model_type not in _IOS_SUPPORTED_MODEL_TYPES:
+        problems.append(
+            f"model_type `{model_type}` is not in mlx-swift-lm's registry — "
+            "it won't load on iOS without adding the architecture in Swift."
+        )
+    for name in ("tokenizer.json", "tokenizer_config.json"):
+        if not (save_path / name).exists():
+            problems.append(
+                f"{name} is missing — swift-transformers needs it to build "
+                "the tokenizer on device."
+            )
+
+    gb = _dir_weight_bytes(save_path) / 1e9
+    quantized = "quantization" in config
+    print(f"Weights: {gb:.2f} GB ({'quantized' if quantized else 'float'}), "
+          f"model_type: {model_type}")
+    if not quantized:
+        print("Tip: unquantized weights are heavy for iPhone — train from a "
+              "4-bit base (e.g. an mlx-community *-4bit model) for iOS.")
+    if gb <= _IOS_COMFORTABLE_GB:
+        print("iPhone fit: comfortable — loads on recent iPhones; the "
+              "Increased Memory Limit capability is still recommended.")
+    elif gb <= _IOS_MAX_GB:
+        print("iPhone fit: needs the Increased Memory Limit or Extended "
+              "Virtual Addressing capability; expect 8 GB-RAM devices only.")
+    else:
+        print(f"iPhone fit: unlikely — {gb:.1f} GB of weights exceeds what "
+              "an 8 GB iPhone can keep resident. Use a smaller or more "
+              "aggressively quantized base.")
+
+    (save_path / "README-iOS.md").write_text(_IOS_README)
+    print(f"Wrote {save_path / 'README-iOS.md'}")
+
+    if problems:
+        for p in problems:
+            print(f"WARNING: {p}")
+        raise SystemExit(1)
+
+
+def run_export(
+    base: str,
+    adapter_path: str,
+    save_path: str,
+    fmt: str = "mlx",
+    dequantize: bool = False,
+) -> None:
+    """Fuse a LoRA adapter into the base model; optionally convert to GGUF.
+
+    fmt: "mlx" (fused MLX weights), "gguf" (also writes ggml-model-f16.gguf
+    for llama.cpp / Ollama / LM Studio; llama, mistral and mixtral
+    architectures, unquantized base), or "ios" (fused MLX weights validated
+    for mlx-swift-lm on iPhone/iPad, plus a README-iOS.md how-to).
+    """
+    if fmt == "ios" and dequantize:
+        print("Note: --dequantize with -f ios makes weights ~4x larger; "
+              "quantized weights are what you want on iPhone.")
+    if not Path(base).exists():
+        # mlx-lm's training path downloads a partial snapshot; fuse checks for
+        # a complete one. Top it up before fusing.
+        from huggingface_hub import snapshot_download
+
+        snapshot_download(base)
+
+    if fmt == "ios":
+        _fuse_for_ios(base, adapter_path, save_path)
+    else:
+        _fuse(base, adapter_path, save_path, dequantize)
+    print(f"Fused model: {Path(save_path).resolve()}")
+    if fmt == "gguf":
+        out = _export_gguf(Path(save_path))
+        print(f"GGUF: {out.resolve()}")
+    elif fmt == "ios":
+        _export_ios(Path(save_path))