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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: troy-cli
-Version: 0.3.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.3.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.3.0 → troy_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "troy-cli"
-version = "0.3.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.3.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.3.0"
+__version__ = "0.5.0"

{troy_cli-0.3.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
@@ -319,15 +319,19 @@ def push(
     run_push(folder, repo, private=not public)
 
 
-@app.command()
-def data(
-    action: str = typer.Argument(help="Action: inspect"),
+data_app = typer.Typer(
+    name="data",
+    help="Inspect, validate, and synthesize datasets.",
+    no_args_is_help=True,
+)
+app.add_typer(data_app)
+
+
+@data_app.command()
+def inspect(
     path: Path = typer.Argument(help="Dataset file (.jsonl, .json, .csv)."),
 ) -> None:
     """Inspect a dataset: record count, detected format, sizes."""
-    if action != "inspect":
-        console.print("[red]Only `troy data inspect <path>` is supported.[/red]")
-        raise typer.Exit(1)
     from .data import inspect_stats
 
     stats = inspect_stats(str(path))
@@ -341,5 +345,265 @@ def data(
     console.print(table)
 
 
+@data_app.command()
+def validate(
+    path: Path = typer.Argument(help="Dataset file (.jsonl, .json, .csv)."),
+) -> None:
+    """Lint a dataset: broken records, mixed formats, empty fields, duplicates."""
+    from .data import validate_records
+
+    report = validate_records(str(path))
+    console.print(
+        f"{report['records']} records, format: [bold]{report['format']}[/bold]"
+    )
+    if not report["issues"]:
+        console.print("[green]No issues found.[/green]")
+        return
+    for issue in report["issues"]:
+        console.print(f"  [yellow]•[/yellow] {issue}")
+    if report["truncated"]:
+        console.print("  [dim]... more issues not shown[/dim]")
+    console.print(f"[red]{len(report['issues'])}{'+' if report['truncated'] else ''} issue(s).[/red]")
+    raise typer.Exit(1)
+
+
+@data_app.command()
+def synth(
+    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.",
+    ),
+    teacher: str = typer.Option(
+        "auto", help="Teacher model (auto = sized to this Mac's memory)."
+    ),
+    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),
+) -> None:
+    """Synthesize a training dataset with a local teacher model."""
+    _require_apple_silicon()
+    if source is None and seed is None:
+        console.print(
+            '[red]Give the teacher 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, '
+                'e.g. "travel planning assistant that books nothing".'
+            )
+            raise typer.Exit(1)
+
+    from .synth import pick_teacher, run_synth
+
+    if teacher == "auto":
+        teacher = pick_teacher()
+        console.print(f"Teacher: [bold]{teacher}[/bold] (picked for this Mac's memory)")
+    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)
+
+    stats = run_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] "
+        f"({stats['teacher_calls']} teacher calls)"
+    )
+    if stats["records"] < stats["requested"]:
+        console.print(
+            f"[yellow]Stopped at {stats['records']}/{stats['requested']} — "
+            "try a larger --teacher, higher --max-tokens, or more source material.[/yellow]"
+        )
+    console.print(
+        "Review the data before training — spot-check a dozen examples, then: "
+        "[bold]troy data validate " + str(out) + "[/bold] and [bold]troy train[/bold]."
+    )
+
+
+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.3.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 = [
@@ -152,6 +156,120 @@ def load_and_prepare(
     return train, valid, fmt
 
 
+# Required non-empty string fields per format (nested fields checked separately).
+_REQUIRED_FIELDS = {
+    "alpaca": ("instruction", "output"),
+    "completions": ("prompt", "completion"),
+    "preference": ("prompt", "chosen", "rejected"),
+    "text": ("text",),
+}
+
+
+def _record_issues(record: Dict[str, Any], fmt: str, line: int) -> List[str]:
+    issues = []
+
+    def empty(v: Any) -> bool:
+        return not (isinstance(v, str) and v.strip())
+
+    for field in _REQUIRED_FIELDS.get(fmt, ()):
+        if empty(record.get(field)):
+            issues.append(f"line {line}: empty or missing `{field}`")
+    if fmt == "chat":
+        msgs = record.get("messages")
+        if not isinstance(msgs, list) or not msgs:
+            issues.append(f"line {line}: `messages` is not a non-empty list")
+        else:
+            roles = [m.get("role") for m in msgs if isinstance(m, dict)]
+            if "assistant" not in roles:
+                issues.append(f"line {line}: no assistant message")
+            if any(
+                not isinstance(m, dict) or empty(m.get("content"))
+                for m in msgs
+            ):
+                issues.append(f"line {line}: message with empty content")
+    if fmt == "sharegpt":
+        convs = record.get("conversations")
+        if not isinstance(convs, list) or not convs:
+            issues.append(f"line {line}: `conversations` is not a non-empty list")
+        else:
+            bad = [
+                m.get("from")
+                for m in convs
+                if not isinstance(m, dict)
+                or str(m.get("from", "")).lower() not in _SHAREGPT_ROLES
+            ]
+            if bad:
+                issues.append(f"line {line}: unknown speaker role(s): {bad}")
+    if fmt == "preference" and not issues:
+        if record["chosen"].strip() == record["rejected"].strip():
+            issues.append(f"line {line}: chosen == rejected")
+    return issues
+
+
+def validate_records(path: str, max_issues: int = 50) -> Dict[str, Any]:
+    """Lint a dataset: per-record issues, mixed formats, duplicates.
+
+    Returns {"records", "format", "issues", "duplicates", "truncated"}.
+    """
+    p = Path(path).expanduser()
+    issues: List[str] = []
+    records: List[Tuple[int, Dict[str, Any]]] = []
+
+    if p.suffix.lower() == ".jsonl":
+        with open(p) as f:
+            for i, line in enumerate(f, 1):
+                if not line.strip():
+                    continue
+                try:
+                    records.append((i, json.loads(line)))
+                except json.JSONDecodeError as e:
+                    issues.append(f"line {i}: invalid JSON ({e.msg})")
+    else:
+        records = [(i, r) for i, r in enumerate(_read_records(p), 1)]
+
+    if not records:
+        return {
+            "records": 0, "format": "unknown", "issues": issues or ["file has no records"],
+            "duplicates": 0, "truncated": False,
+        }
+
+    try:
+        fmt = detect_format(records[0][1])
+    except ValueError as e:
+        return {
+            "records": len(records), "format": "unknown",
+            "issues": issues + [str(e)], "duplicates": 0, "truncated": False,
+        }
+
+    seen: Dict[str, int] = {}
+    duplicates = 0
+    for line, record in records:
+        try:
+            rec_fmt = detect_format(record)
+        except ValueError:
+            issues.append(f"line {line}: keys match no known format")
+            continue
+        if rec_fmt != fmt:
+            issues.append(f"line {line}: format `{rec_fmt}` (file is `{fmt}`)")
+            continue
+        issues.extend(_record_issues(record, fmt, line))
+        key = json.dumps(record, sort_keys=True)
+        if key in seen:
+            duplicates += 1
+            issues.append(f"line {line}: exact duplicate of line {seen[key]}")
+        else:
+            seen[key] = line
+
+    truncated = len(issues) > max_issues
+    return {
+        "records": len(records),
+        "format": fmt,
+        "issues": issues[:max_issues],
+        "duplicates": duplicates,
+        "truncated": truncated,
+    }
+
+
 def inspect_stats(path: str) -> Dict[str, Any]:
     """Lightweight dataset statistics for `troy data inspect`-style output."""
     records = _read_records(Path(path).expanduser())