modelforge-finetuning 3.0.5__tar.gz → 4.0.1__tar.gz

modelforge_finetuning-4.0.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include setup.py
+include scripts/build_frontend.py
+recursive-include web/frontend *
+prune web/frontend/node_modules
+global-exclude *.tsbuildinfo
+recursive-include web/frontend_dist *

modelforge_finetuning-4.0.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: modelforge-finetuning
+Version: 4.0.1
+Summary: Hardware-aware fine-tuning utility with browser, terminal, and notebook interfaces.
+Author-email: R3tr0 M1ll3r <r3tr0.m1ll3r@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ForgeOpus/ModelForge
+Project-URL: Documentation, https://modelforge-finetuning.readthedocs.io
+Project-URL: Repository, https://github.com/ForgeOpus/ModelForge
+Project-URL: Issues, https://github.com/ForgeOpus/ModelForge/issues
+Project-URL: Changelog, https://modelforge-finetuning.readthedocs.io/en/latest/getting-started/whats-new/
+Project-URL: Organization, https://github.com/ForgeOpus
+Keywords: fine-tuning,llm,huggingface,lora,qlora,dpo,grpo,peft,transformers
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: accelerate>=1.13.0
+Requires-Dist: bitsandbytes>=0.49.2
+Requires-Dist: fastapi>=0.124.0
+Requires-Dist: huggingface-hub>=1.14.0
+Requires-Dist: nvidia-ml-py>=13.595.45
+Requires-Dist: peft>=0.19.1
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: psutil>=6.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: uvicorn>=0.38.0
+Requires-Dist: websockets>=13.0
+Requires-Dist: tensorboard>=2.20.0
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: transformers>=5.8.0
+Requires-Dist: trl>=1.4.0
+Requires-Dist: setuptools>=81.0.0
+Provides-Extra: cli
+Requires-Dist: click>=8.1; extra == "cli"
+Requires-Dist: rich>=13.0; extra == "cli"
+Provides-Extra: notebook
+Provides-Extra: gpu
+Requires-Dist: liger-kernel>=0.5.0; extra == "gpu"
+Provides-Extra: dev
+Requires-Dist: click>=8.1; extra == "dev"
+Requires-Dist: httpx>=0.28.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: rich>=13.0; extra == "dev"
+Dynamic: license-file
+
+# ModelForge
+
+[![PyPI](https://img.shields.io/pypi/v/modelforge-finetuning)](https://pypi.org/project/modelforge-finetuning/)
+[![Python](https://img.shields.io/pypi/pyversions/modelforge-finetuning)](https://pypi.org/project/modelforge-finetuning/)
+[![Docs](https://readthedocs.org/projects/modelforge-finetuning/badge/?version=latest)](https://modelforge-finetuning.readthedocs.io)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue)](https://github.com/ForgeOpus/ModelForge/blob/main/LICENSE)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/modelforge-finetuning?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/modelforge-finetuning)
+
+<a href="https://www.producthunt.com/products/forgeopus?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-forgeopus" target="_blank" rel="noopener noreferrer"><img alt="ForgeOpus - Where AI masterpieces are forged. Your work, your opus. | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1080450&amp;theme=light&amp;t=1771311433851"></a>
+
+![ModelForge logo](https://github.com/user-attachments/assets/12b3545d-0e8b-4460-9291-d0786c9cb0fa)
+
+Hardware-aware fine-tuning for open models from the Hugging Face Hub, with browser, terminal and notebook interfaces.
+
+ModelForge reads your GPUs, works out how large a model fits, picks a training recipe for your goal, and runs it while you watch the loss come down. It shows its reasoning before anything starts, so you don't find out at step 40 that the run doesn't fit in memory.
+
+## Features
+
+- **Hardware-aware planning.** Total VRAM, the strategy's memory overhead and a per-parameter cost set a ceiling on model size. ModelForge picks full fine-tuning, LoRA or QLoRA (8-bit or 4-bit) to match.
+- **A recipe for each goal.** Supervised fine-tuning (SFT), preference training (DPO) and reinforcement training (GRPO), plus native trainers for summarization and extractive QA.
+- **Model recommendations.** Searches the Hub for popular models of the right type that fit your hardware, or validates any model ID you enter.
+- **Multi-GPU.** Data parallel by default, switching to FSDP automatically when a full fine-tune is too large for one card.
+- **Live runs.** Streamed training logs, checkpoints you can resume from, and TensorBoard logging.
+- **Playground.** Chat with a finished model or any checkpoint in the browser, even while another run is training.
+
+## Install
+
+ModelForge needs Python 3.13 or newer. Real training needs an NVIDIA GPU with CUDA. Apple Silicon (MPS) and CPU-only machines work, but only with small models.
+
+```bash
+pip install modelforge-finetuning
+
+# Optional extras: the terminal wizard, and Liger kernels for CUDA
+pip install "modelforge-finetuning[cli,gpu]"
+```
+
+Per-OS instructions, including PyTorch with CUDA, are in the [installation guides](https://modelforge-finetuning.readthedocs.io/en/latest/installation/linux/).
+
+## Quick start
+
+```bash
+modelforge run
+```
+
+This starts the server and opens the browser console. The link it prints includes a one-time token that connects your browser. On a remote machine, use `modelforge run --no-browser --host 127.0.0.1` and connect through an SSH tunnel.
+
+For gated models such as Llama, accept the licence on the model's Hub page, then log in once with `hf auth login`.
+
+| Interface | Command | Best for |
+|---|---|---|
+| Browser console | `modelforge run` | Most people |
+| Terminal wizard | `modelforge cli` | Headless servers over SSH (needs `[cli]`) |
+| Notebook | `modelforge-nb` | Jupyter and Colab |
+
+The [Quick Start guide](https://modelforge-finetuning.readthedocs.io/en/latest/getting-started/quickstart/) walks through a first run.
+
+## Documentation
+
+Full documentation is at **[modelforge-finetuning.readthedocs.io](https://modelforge-finetuning.readthedocs.io)**. A shorter version ships inside the app at `/app/docs`.
+
+- [What's new in v4 and migrating from v3](https://modelforge-finetuning.readthedocs.io/en/latest/getting-started/whats-new/)
+- [Dataset formats](https://modelforge-finetuning.readthedocs.io/en/latest/configuration/dataset-formats/)
+- [How planning works](https://modelforge-finetuning.readthedocs.io/en/latest/configuration/configuration-guide/)
+- [Training strategies](https://modelforge-finetuning.readthedocs.io/en/latest/strategies/overview/)
+- [REST API](https://modelforge-finetuning.readthedocs.io/en/latest/api-reference/rest-api/)
+- [Troubleshooting](https://modelforge-finetuning.readthedocs.io/en/latest/troubleshooting/common-issues/)
+
+## Running from source
+
+Building or installing from a source checkout needs Node.js and npm, because the browser UI is compiled into `web/frontend_dist/`. That directory isn't committed.
+
+```bash
+git clone https://github.com/ForgeOpus/ModelForge.git
+cd ModelForge
+uv sync --extra dev
+python scripts/build_frontend.py   # or, from web/frontend: npm ci && npm run build
+uv run modelforge run --no-browser
+```
+
+`pip wheel .`, `python -m build` and `uv build` run the frontend build automatically, and fail if Node.js is missing, so a wheel is never published without a UI. Installing an already-built wheel doesn't need Node.
+
+See the [development guide](https://modelforge-finetuning.readthedocs.io/en/latest/contributing/development/) and [DEVELOPER_GUIDE.md](https://github.com/ForgeOpus/ModelForge/blob/main/DEVELOPER_GUIDE.md) for the codebase tour, tests and the release process.
+
+## Contributing
+
+Contributions are welcome. Read the [contributing guide](https://modelforge-finetuning.readthedocs.io/en/latest/contributing/contributing/) and the [code of conduct](https://github.com/ForgeOpus/ModelForge/blob/main/CODE_OF_CONDUCT.md), and report bugs or request features through [GitHub issues](https://github.com/ForgeOpus/ModelForge/issues).
+
+## License
+
+ModelForge is released under the [BSD 3-Clause License](https://github.com/ForgeOpus/ModelForge/blob/main/LICENSE).

modelforge_finetuning-4.0.1/README.md

@@ -0,0 +1,90 @@
+# ModelForge
+
+[![PyPI](https://img.shields.io/pypi/v/modelforge-finetuning)](https://pypi.org/project/modelforge-finetuning/)
+[![Python](https://img.shields.io/pypi/pyversions/modelforge-finetuning)](https://pypi.org/project/modelforge-finetuning/)
+[![Docs](https://readthedocs.org/projects/modelforge-finetuning/badge/?version=latest)](https://modelforge-finetuning.readthedocs.io)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue)](https://github.com/ForgeOpus/ModelForge/blob/main/LICENSE)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/modelforge-finetuning?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/modelforge-finetuning)
+
+<a href="https://www.producthunt.com/products/forgeopus?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-forgeopus" target="_blank" rel="noopener noreferrer"><img alt="ForgeOpus - Where AI masterpieces are forged. Your work, your opus. | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1080450&amp;theme=light&amp;t=1771311433851"></a>
+
+![ModelForge logo](https://github.com/user-attachments/assets/12b3545d-0e8b-4460-9291-d0786c9cb0fa)
+
+Hardware-aware fine-tuning for open models from the Hugging Face Hub, with browser, terminal and notebook interfaces.
+
+ModelForge reads your GPUs, works out how large a model fits, picks a training recipe for your goal, and runs it while you watch the loss come down. It shows its reasoning before anything starts, so you don't find out at step 40 that the run doesn't fit in memory.
+
+## Features
+
+- **Hardware-aware planning.** Total VRAM, the strategy's memory overhead and a per-parameter cost set a ceiling on model size. ModelForge picks full fine-tuning, LoRA or QLoRA (8-bit or 4-bit) to match.
+- **A recipe for each goal.** Supervised fine-tuning (SFT), preference training (DPO) and reinforcement training (GRPO), plus native trainers for summarization and extractive QA.
+- **Model recommendations.** Searches the Hub for popular models of the right type that fit your hardware, or validates any model ID you enter.
+- **Multi-GPU.** Data parallel by default, switching to FSDP automatically when a full fine-tune is too large for one card.
+- **Live runs.** Streamed training logs, checkpoints you can resume from, and TensorBoard logging.
+- **Playground.** Chat with a finished model or any checkpoint in the browser, even while another run is training.
+
+## Install
+
+ModelForge needs Python 3.13 or newer. Real training needs an NVIDIA GPU with CUDA. Apple Silicon (MPS) and CPU-only machines work, but only with small models.
+
+```bash
+pip install modelforge-finetuning
+
+# Optional extras: the terminal wizard, and Liger kernels for CUDA
+pip install "modelforge-finetuning[cli,gpu]"
+```
+
+Per-OS instructions, including PyTorch with CUDA, are in the [installation guides](https://modelforge-finetuning.readthedocs.io/en/latest/installation/linux/).
+
+## Quick start
+
+```bash
+modelforge run
+```
+
+This starts the server and opens the browser console. The link it prints includes a one-time token that connects your browser. On a remote machine, use `modelforge run --no-browser --host 127.0.0.1` and connect through an SSH tunnel.
+
+For gated models such as Llama, accept the licence on the model's Hub page, then log in once with `hf auth login`.
+
+| Interface | Command | Best for |
+|---|---|---|
+| Browser console | `modelforge run` | Most people |
+| Terminal wizard | `modelforge cli` | Headless servers over SSH (needs `[cli]`) |
+| Notebook | `modelforge-nb` | Jupyter and Colab |
+
+The [Quick Start guide](https://modelforge-finetuning.readthedocs.io/en/latest/getting-started/quickstart/) walks through a first run.
+
+## Documentation
+
+Full documentation is at **[modelforge-finetuning.readthedocs.io](https://modelforge-finetuning.readthedocs.io)**. A shorter version ships inside the app at `/app/docs`.
+
+- [What's new in v4 and migrating from v3](https://modelforge-finetuning.readthedocs.io/en/latest/getting-started/whats-new/)
+- [Dataset formats](https://modelforge-finetuning.readthedocs.io/en/latest/configuration/dataset-formats/)
+- [How planning works](https://modelforge-finetuning.readthedocs.io/en/latest/configuration/configuration-guide/)
+- [Training strategies](https://modelforge-finetuning.readthedocs.io/en/latest/strategies/overview/)
+- [REST API](https://modelforge-finetuning.readthedocs.io/en/latest/api-reference/rest-api/)
+- [Troubleshooting](https://modelforge-finetuning.readthedocs.io/en/latest/troubleshooting/common-issues/)
+
+## Running from source
+
+Building or installing from a source checkout needs Node.js and npm, because the browser UI is compiled into `web/frontend_dist/`. That directory isn't committed.
+
+```bash
+git clone https://github.com/ForgeOpus/ModelForge.git
+cd ModelForge
+uv sync --extra dev
+python scripts/build_frontend.py   # or, from web/frontend: npm ci && npm run build
+uv run modelforge run --no-browser
+```
+
+`pip wheel .`, `python -m build` and `uv build` run the frontend build automatically, and fail if Node.js is missing, so a wheel is never published without a UI. Installing an already-built wheel doesn't need Node.
+
+See the [development guide](https://modelforge-finetuning.readthedocs.io/en/latest/contributing/development/) and [DEVELOPER_GUIDE.md](https://github.com/ForgeOpus/ModelForge/blob/main/DEVELOPER_GUIDE.md) for the codebase tour, tests and the release process.
+
+## Contributing
+
+Contributions are welcome. Read the [contributing guide](https://modelforge-finetuning.readthedocs.io/en/latest/contributing/contributing/) and the [code of conduct](https://github.com/ForgeOpus/ModelForge/blob/main/CODE_OF_CONDUCT.md), and report bugs or request features through [GitHub issues](https://github.com/ForgeOpus/ModelForge/issues).
+
+## License
+
+ModelForge is released under the [BSD 3-Clause License](https://github.com/ForgeOpus/ModelForge/blob/main/LICENSE).

modelforge_finetuning-4.0.1/cli/display.py

@@ -0,0 +1,164 @@
+from transformers import TrainerCallback
+from rich.progress import Progress, BarColumn, TimeElapsedColumn, MofNCompleteColumn
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table, box
+from rich.text import Text
+from rich.rule import Rule
+from rich import print as rprint
+from utilities.hardware_detector import HardwareDetector
+from recommendation_engine.validation_models.recommendation import Recommendation
+
+console = Console()
+
+
+def print_header() -> None:
+    banner_lines = [
+        (" __  __           _      _  _____", "bold red"),
+        ("|  \\/  | ___   __| | ___| ||  ___|__  _ __ __ _  ___", "bold yellow"),
+        ("| |\\/| |/ _ \\ / _` |/ _ \\ || |_ / _ \\| '__/ _` |/ _ \\", "bold green"),
+        ("| |  | | (_) | (_| |  __/ ||  _| (_) | | | (_| |  __/", "bold cyan"),
+        ("|_|  |_|\\___/ \\__,_|\\___|_||_|  \\___/|_|  \\__, |\\___|", "bold blue"),
+        ("                                           |___/", "bold magenta"),
+    ]
+    banner_text = Text()
+    for line, color in banner_lines:
+        banner_text.append(line + "\n", style=color)
+    console.print(banner_text)
+
+
+def print_hardware(hardware: HardwareDetector.HardwareSpecs) -> None:
+    table = Table(title="Detected Hardware", show_header=True)
+    table.add_column("Component", style="bold")
+    table.add_column("Details")
+
+    table.add_row("CPU", f"{hardware.physical_core_count} cores")
+    table.add_row("RAM", f"{hardware.ram_gb:.1f} GB")
+    table.add_row(
+        "Disk (free)",
+        f"{hardware.available_disk_storage_gb:.1f} / {hardware.disk_storage_gb:.1f} GB",
+    )
+
+    for i, gpu in enumerate(hardware.gpus):
+        if gpu["total_memory_gb"] == "N/A":
+            detail = "Apple MPS — shared"
+        else:
+            detail = f"{gpu['name']} — {gpu['total_memory_gb']} GB VRAM"
+        table.add_row(f"GPU {i}", detail)
+
+    console.print(table)
+
+
+_PEFT_COLORS = {
+    "full_finetune": "bold green",
+    "lora_bf16": "bold cyan",
+    "qlora_8bit": "bold yellow",
+    "qlora_4bit": "bold orange1",
+}
+
+
+def print_recommendation(recommendation: Recommendation) -> None:
+    r = recommendation
+
+    # ── Summary strip ──────────────────────────────────────────────────────────
+    peft_color = _PEFT_COLORS.get(r.peft_approach, "bold white")
+    summary = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+    summary.add_column(style="bold dim", no_wrap=True)
+    summary.add_column()
+    summary.add_row("Strategy",  r.strategy_slug)
+    summary.add_row("PEFT tier", Text(r.peft_approach, style=peft_color))
+    summary.add_row("Task",      r.task_slug)
+    summary.add_row("Provider",  r.provider_slug)
+    console.print(Panel(summary, title="[bold green]Recommendation[/bold green]", expand=False))
+
+    # ── Candidate models ───────────────────────────────────────────────────────
+    console.print(Rule("[bold]Candidate Models[/bold]", style="green"))
+    models_table = Table(box=box.ROUNDED, show_header=True, header_style="bold")
+    models_table.add_column("#",          justify="right",  style="dim",       no_wrap=True)
+    models_table.add_column("Model ID",                     style="cyan",      no_wrap=True)
+    models_table.add_column("Parameters", justify="right",                     no_wrap=True)
+    models_table.add_column("Downloads",  justify="right",  style="dim green", no_wrap=True)
+    for rank, m in enumerate(r.recommended_models, start=1):
+        models_table.add_row(
+            str(rank),
+            m.model_id,
+            f"{m.num_parameters / 1e9:.2f}B",
+            f"{m.downloads:,}",
+        )
+    console.print(models_table)
+
+    # ── Decision rationale ────────────────────────────────────────────────────
+    console.print(Rule("[bold]Decision Rationale[/bold]", style="dim"))
+    rationale = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+    rationale.add_column(style="bold dim", no_wrap=True, width=14)
+    rationale.add_column(overflow="fold")
+    rationale.add_row("Hardware",     r.rationale.vram_summary)
+    rationale.add_row("Use Case",     r.rationale.use_case_resolution)
+    rationale.add_row("PEFT",         r.rationale.peft_decision)
+    rationale.add_row("Model Filter", r.rationale.model_filter)
+    console.print(rationale)
+
+    # ── Warnings (only if present) ────────────────────────────────────────────
+    if r.rationale.warnings:
+        warn_text = "\n".join(f"[yellow]⚠[/yellow]  {w}" for w in r.rationale.warnings)
+        console.print(Panel(warn_text, title="[bold yellow]Warnings[/bold yellow]", border_style="yellow", expand=False))
+
+
+def print_training_summary(
+    model_id: str,
+    dataset_desc: str,
+    output_dir: str,
+    recommendation: Recommendation,
+    tensorboard_log_dir: str | None = None,
+) -> None:
+    body = (
+        f"Model:          {model_id}\n"
+        f"Dataset:        {dataset_desc}\n"
+        f"Task:           {recommendation.task_slug}\n"
+        f"Strategy:       {recommendation.strategy_slug}\n"
+        f"PEFT approach:  {recommendation.peft_approach}\n"
+        f"Output Dir:     {output_dir}"
+    )
+    if tensorboard_log_dir:
+        body += f"\nTensorBoard:    {tensorboard_log_dir}"
+    rprint(Panel(body, title="[bold blue]Training Summary[/bold blue]"))
+
+
+class RichTrainingCallback(TrainerCallback):
+
+    def __init__(self):
+        self.progress = None
+        self.task_id = None
+        self.current_step = 0
+
+    def on_train_begin(self, args, state, control, **kwargs):
+        self.current_step = 0
+        self.progress = Progress(
+            "[progress.description]{task.description}",
+            BarColumn(),
+            "[progress.percentage]{task.percentage:>3.0f}%",
+            TimeElapsedColumn(),
+            "•",
+            MofNCompleteColumn(),
+        )
+        self.progress.start()
+        self.task_id = self.progress.add_task("Training", total=state.max_steps)
+
+    def on_log(self, args, state, control, logs=None, **kwargs):
+        if logs is None:
+            return
+        step = logs.get("step", self.current_step + 1)
+        advance = step - self.current_step
+        self.current_step = step
+        loss = logs.get("loss", "N/A")
+        epoch = logs.get("epoch", "N/A")
+        self.progress.update(
+            self.task_id,
+            advance=advance,
+            description=f"Training  loss={loss}  epoch={epoch}",
+        )
+
+    def on_train_end(self, args, state, control, **kwargs):
+        if self.progress is not None:
+            self.progress.stop()
+        rprint("[bold green]Training complete![/bold green]")

modelforge_finetuning-4.0.1/cli/main.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+
+from utilities.database_manager import FinetuneLedger, WebRunLedger
+from utilities.hardware_detector import HardwareDetector
+from utilities.recommendation_engine import RecommendationEngine
+from utilities.tensorboard import DEFAULT_TENSORBOARD_HOST, DEFAULT_TENSORBOARD_PORT
+from utilities.training_objective import TrainingObjective
+from workflow.registries import load_core_registries
+from workflow.service import WorkflowService
+
+
+def cli(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return
+    args.func(args)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="modelforge")
+    subcommands = parser.add_subparsers(dest="command")
+
+    run = subcommands.add_parser("run", help="Start the browser UI.")
+    run.add_argument("--host", default="0.0.0.0", help="Host to bind. Defaults to 0.0.0.0.")
+    run.add_argument("--port", default=8000, type=int, help="Port to bind.")
+    run.add_argument("--no-browser", action="store_true", help="Do not open the UI in a browser.")
+    run.add_argument("--token", default=None, help="Use a fixed startup token instead of generating one.")
+    run.set_defaults(func=run_web)
+
+    terminal = subcommands.add_parser("cli", help="Start the optional terminal wizard.")
+    terminal.add_argument("--no-tensorboard", action="store_true", help="Disable TensorBoard logging.")
+    terminal.add_argument("--tensorboard-logdir", default=None, help="Directory for TensorBoard event logs.")
+    terminal.set_defaults(func=run_terminal)
+
+    recommend = subcommands.add_parser("recommend", help="Print hardware-aware model recommendations.")
+    recommend.add_argument("--use-case", default=None, help="Use case slug.")
+    recommend.add_argument("--objective", default="supervised", choices=[item.value for item in TrainingObjective])
+    recommend.add_argument("--n", default=5, type=int)
+    recommend.set_defaults(func=run_recommend)
+
+    history = subcommands.add_parser("history", help="Print run history.")
+    history.add_argument("--legacy", action="store_true", help="Show the legacy terminal finetune ledger.")
+    history.set_defaults(func=run_history)
+
+    list_tasks = subcommands.add_parser("list-tasks", help="List available use cases.")
+    list_tasks.set_defaults(func=run_list_tasks)
+
+    tensorboard = subcommands.add_parser("tensorboard", help="Launch TensorBoard for a log directory.")
+    tensorboard.add_argument("logdir", nargs="?", default=None)
+    tensorboard.add_argument("--host", default=DEFAULT_TENSORBOARD_HOST)
+    tensorboard.add_argument("--port", default=DEFAULT_TENSORBOARD_PORT, type=int)
+    tensorboard.set_defaults(func=run_tensorboard)
+
+    return parser
+
+
+def run_web(args: argparse.Namespace) -> None:
+    import uvicorn
+    from web.app import create_app
+    from web.auth import TokenAuth
+
+    auth = TokenAuth(args.token)
+    url = auth.public_url(args.host, args.port)
+    print("ModelForge v4 browser UI")
+    print(f"Serving on: http://{args.host}:{args.port}")
+    print(f"Open:       {url}")
+    print("The startup token is required for API and WebSocket access.")
+    if not args.no_browser:
+        webbrowser.open(url)
+    app = create_app(auth=auth)
+    uvicorn.run(app, host=args.host, port=args.port)
+
+
+def run_terminal(args: argparse.Namespace) -> None:
+    try:
+        from cli.terminal import run_terminal_wizard
+    except ImportError as exc:
+        raise SystemExit(
+            "The terminal UI requires optional dependencies. "
+            "Install with: pip install \"modelforge-finetuning[cli]\""
+        ) from exc
+    run_terminal_wizard(
+        tensorboard=not args.no_tensorboard,
+        tensorboard_logdir=args.tensorboard_logdir,
+    )
+
+
+def run_recommend(args: argparse.Namespace) -> None:
+    load_core_registries()
+    service = WorkflowService()
+    use_case = args.use_case or _prompt_use_case(service)
+    hardware = HardwareDetector.detect_hardware()
+    recommendation = RecommendationEngine.recommend(
+        use_case,
+        TrainingObjective(args.objective),
+        hardware,
+        n=args.n,
+    )
+    print(f"Task:      {recommendation.task_slug}")
+    print(f"Strategy:  {recommendation.strategy_slug}")
+    print(f"PEFT:      {recommendation.peft_approach}")
+    print("Models:")
+    for model in recommendation.recommended_models:
+        print(f"  - {model.model_id} ({model.num_parameters:,} params, {model.downloads:,} downloads)")
+    if recommendation.rationale.warnings:
+        print("Warnings:")
+        for warning in recommendation.rationale.warnings:
+            print(f"  - {warning}")
+
+
+def run_history(args: argparse.Namespace) -> None:
+    if args.legacy:
+        runs = FinetuneLedger().list_runs()
+        for run in runs:
+            print(f"{run['id']}: {run['timestamp']} {run['model_id']} ({run['peft']}) -> {run['output_dir']}")
+        if not runs:
+            print("No legacy finetune runs recorded yet.")
+        return
+    runs = WebRunLedger().list_runs()
+    for run in runs:
+        print(f"{run['id']}: {run['status']} {run['model_id']} -> {run['output_dir']}")
+    if not runs:
+        print("No runs recorded yet.")
+
+
+def run_list_tasks(args: argparse.Namespace) -> None:
+    service = WorkflowService()
+    for use_case in service.list_use_cases():
+        objectives = ", ".join(use_case["compatible_objectives"])
+        print(f"{use_case['slug']}: {use_case['name']} [{objectives}]")
+        print(f"  {use_case['description']}")
+
+
+def run_tensorboard(args: argparse.Namespace) -> None:
+    try:
+        from cli.terminal import tensorboard_cmd
+    except ImportError as exc:
+        raise SystemExit(
+            "The TensorBoard terminal helper requires optional dependencies. "
+            "Install with: pip install \"modelforge-finetuning[cli]\""
+        ) from exc
+    tensorboard_cmd(args.logdir, args.host, args.port)
+
+
+def _prompt_use_case(service: WorkflowService) -> str:
+    use_cases = service.list_use_cases()
+    print("Available use cases:")
+    for index, use_case in enumerate(use_cases, start=1):
+        print(f"  {index}. {use_case['name']} ({use_case['slug']})")
+    while True:
+        raw = input("Select use case: ").strip()
+        try:
+            choice = int(raw)
+            if 1 <= choice <= len(use_cases):
+                return use_cases[choice - 1]["slug"]
+        except ValueError:
+            if any(use_case["slug"] == raw for use_case in use_cases):
+                return raw
+        print("Enter a number from the list or a use case slug.")
+
+
+if __name__ == "__main__":
+    cli(sys.argv[1:])

modelforge_finetuning-4.0.1/cli/runner.py

@@ -0,0 +1,5 @@
+"""Backward-compatible import path for the shared training runner."""
+
+from workflow.training import assemble_and_train
+
+__all__ = ["assemble_and_train"]