Skip to content

V4 migration - #64

Merged
RETR0-OS merged 197 commits into
mainfrom
v4-migration
Nov 15, 2026
Merged

RETR0-OS merged 197 commits into
mainfrom
v4-migration

Conversation

@RETR0-OS

Copy link
Copy Markdown
Member

ModelForge v4

This PR brings the ModelForge v4 rewrite into this repository. It keeps the full commit history of both projects, and restores the Read the Docs site, rewritten for v4.

History

v4 was developed in a separate repository (RETR0-OS/ModelForgeRedesign), so the two histories share no commits. They're joined with git merge --allow-unrelated-histories:

  • All 328 commits from v0.1 to v3.0.5 are kept, and the tags 0.1.1 to 3.0.5 still point at their original commits.
  • All v4 commits are kept, so git log and git blame work across both histories.
  • After the merge, the files match v4 exactly, plus the files below that v4 didn't have.

Files kept from this repository: LICENSE (BSD-3-Clause), CODE_OF_CONDUCT.md, the issue templates, the Copilot agent files, and .github/workflows/workflow.yaml. The release workflow keeps its file name because PyPI trusted publishing is tied to it.

What's new in v4

  • Hardware-aware planner. Replaces the fixed low/mid/high model profiles. It reads your GPUs, searches the Hub for models that fit, and picks full fine-tuning, LoRA, or QLoRA (8-bit or 4-bit).

  • Training objectives. Supervised (SFT), preference (DPO) and reinforcement (GRPO), plus native trainers for summarization and extractive QA.

  • Multi-GPU. Data parallel by default, and FSDP for full fine-tunes too large for one GPU.

  • New browser console. Live training logs, checkpoint resume, TensorBoard, and an in-browser Playground for trying out trained models and checkpoints.

  • Token-authenticated API. REST and WebSocket.

  • Three ways to run it. modelforge run (browser), modelforge cli (terminal wizard) and modelforge-nb (notebooks).

  • Breaking changes.

    • Requires Python 3.13 or newer.
    • The Unsloth provider, the rlhf/qlora strategies and the JSON model configs are removed.
    • v3 run history doesn't carry over.

    See the migration guide.

Documentation

  • Read the Docs. The MkDocs site is rewritten against the v4 code, following the structure of the v3 site. Sections: Getting Started, Installation (Windows / Linux / macOS), User Guide, Configuration, Providers, Training Strategies, API Reference, Troubleshooting and Contributing.
    • New pages: Fine-Tuning Concepts, GRPO, Full Fine-Tuning, LoRA and QLoRA, Multi-GPU, Memory Optimizations, the CLI reference, the User Guide section, and Adding a Use Case.
    • Old URLs keep working. Removed pages redirect to their replacements: Unsloth → Providers overview, RLHF → GRPO, Model configs → Adding a use case.
    • Fixes site_url, which pointed at an unrelated project (modelforge.readthedocs.io). The site is modelforge-finetuning.readthedocs.io.
    • Read the Docs now builds on Python 3.13 and Ubuntu 24.04, using mkdocs-material and mkdocs-redirects, with mkdocs pinned below 2.
  • In-app docs. Updated to match the code: how the planner picks a tier, the Playground's One-shot and Streaming modes, QA window sizes, summarization aliases, and the recommendation API fields. Each in-app page links to its Read the Docs page through web/frontend/src/docs/rtd.ts, and a test fails if a page has no matching link.
  • Docs policy. The contributing guide requires every user-facing change to update both doc sets, and includes a table mapping in-app pages to Read the Docs pages.

Packaging and CI

  • pyproject.toml: brings back the license (BSD-3-Clause, PEP 639), authors, keywords, classifiers and project URLs, which v4 didn't have. The build now requires setuptools>=77.
  • Release workflow: builds with the Python and Node versions in .python-version and .node-version, using scripts/build_distribution.sh. That script builds the locked frontend, then the sdist and wheel, and checks both archives include the UI. The workflow also fails if the tag doesn't match the version in pyproject.toml.
  • CI: adds a mkdocs build --strict job, so broken docs links fail the build.
  • README: rewritten as the PyPI project page, with install, quick start, interfaces and docs links.
  • hf auth login replaces huggingface-cli login, which no longer works with huggingface_hub 1.x. This covers the docs and the model-validation error message.
  • .github Copilot instructions, agent files and issue templates are updated for the v4 layout.

Testing

  • pytest: 316 passed, 2 skipped
  • Frontend: tsc --noEmit and vitest, 9 passed
  • mkdocs build --strict: no warnings
  • uv build: the sdist metadata includes the license, author and project URLs

RETR0-OS and others added 25 commits November 15, 2026 01:09
…plication

Wire the redesigned app into the production entry point
…thon-tests-frontend

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…rontend

Add CPU-only CI for Python tests, frontend build, and wheel smoke testing
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…ing-timestamp

Fix training ETA by treating event timestamps as Unix seconds
…wire-redesigned-react-application

# Conflicts:
#	web/frontend/package.json

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…plication

Wire the redesigned app into the production entry point
…thon-tests-frontend

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…rontend

Add CPU-only CI for Python tests, frontend build, and wheel smoke testing
Joins the v4 history (RETR0-OS/ModelForgeRedesign main) with the
v0.1-v3.0.5 history. The tree is v4, plus the legacy files v4 lacks:
LICENSE, CODE_OF_CONDUCT.md, docs/ + mkdocs.yml + .readthedocs.yaml,
issue templates, Copilot agent files, and the PyPI release workflow
(workflow.yaml is kept by name for PyPI trusted publishing).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- pyproject: BSD-3-Clause license (PEP 639), authors, classifiers and
  project URLs, which v4 had dropped. Requires setuptools>=77.
- workflow.yaml (kept by name for PyPI trusted publishing): build with
  Python/Node from .python-version/.node-version via
  scripts/build_distribution.sh, and fail if the tag doesn't match
  pyproject's version.
- ci.yml: add a strict MkDocs build job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rewrites the v3 MkDocs pages against the v4 code and adds pages for the
user guide, GRPO, full fine-tuning, multi-GPU, memory optimizations,
CLI reference and adding a use case. Old URLs keep working: removed
pages (Unsloth, RLHF, model configs) redirect via mkdocs-redirects.

Fixes site_url, which pointed at an unrelated project
(modelforge.readthedocs.io); the real site is
modelforge-finetuning.readthedocs.io. RTD builds on Python 3.13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Tier selection: describe the real algorithm (largest shortlisted
  model, then least-quantized tier it fits).
- Playground: document One-shot vs Streaming modes.
- Use hf auth login; huggingface-cli no longer works with
  huggingface_hub 1.x (also fixed in the model-validation error).
- QA window size, summarization aliases, exact error text, model_id on
  POST /api/recommendations.
- Each in-app page links to its Read the Docs counterpart (rtd.ts);
  a test fails if a page has no mapping.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README doubles as the PyPI page: features, install, quick start,
interfaces and documentation links. Copilot instructions, agent
definitions and issue templates now describe the v4 layout; the
documentation agent enforces updating both doc sets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 15, 2026 12:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Exiting the standalone CLI can abruptly terminate active training and leave stale ledger states, while precision detection can select unsupported bf16 based on an unselected GPU.

2 open issues
What changed in this PR

Migrates ModelForge to the v4 architecture, replacing the legacy package and frontend with shared workflows for browser, terminal, and notebook interfaces.

Changes:

  • Adds registry-based training contracts, hardware-aware configuration helpers, and coverage for supported training objectives.
  • Introduces Vite frontend infrastructure, token authentication, and synchronized documentation links.
  • Reworks distribution builds to bundle the browser UI and removes obsolete v3 code and assets.
File Description
workflow/​registries.py Bootstraps shared use-case, task, strategy, and provider registries.
workflow/​models.py Defines workflow requests, run records, and training events.
workflow/​__init__.py Exposes the shared workflow service.
web/​PLAYGROUND.md Documents inference modes and resource constraints.
web/​frontend/​vitest.config.ts Configures frontend tests with jsdom.
web/​frontend/​vite.config.ts Configures API proxying and frontend output.
web/​frontend/​tsconfig.node.json Defines TypeScript settings for Vite configuration.
web/​frontend/​tsconfig.json Enables strict frontend type checking.
web/​frontend/​tests/​streaming.test.tsx Covers streaming-session interactions.
web/​frontend/​tests/​routes.test.tsx Covers Playground routing and token capture.
web/​frontend/​tests/​progress.test.ts Covers progress and ETA calculations.
web/​frontend/​tests/​docs-rtd.test.ts Checks documentation-link mappings.
web/​frontend/​src/​vite-env.d.ts Supplies Vite client types.
web/​frontend/​src/​LandingReference.tsx Adds interactive landing-page behavior.
web/​frontend/​src/​docs/​ui.tsx Provides shared documentation display components.
web/​frontend/​src/​docs/​rtd.ts Maps in-app pages to Read the Docs.
web/​frontend/​src/​docs/​pages.ts Collects in-app documentation pages.
web/​frontend/​public/​landing-mock/​theme.js Controls landing-preview themes.
web/​frontend/​public/​favicon.svg Adds the ModelForge favicon.
web/​frontend/​package.json Declares frontend dependencies and scripts.
web/​frontend/​index.html Defines the Vite app shell and metadata.
web/​auth.py Implements startup-token authentication.
web/​__init__.py Identifies the browser-server package.
utilities/​training_objective.py Defines supported training objectives.
utilities/​tensorboard.py Builds isolated log paths and viewer commands.
utilities/​qa_inference.py Parses QA inputs and decodes answer spans.
utilities/​precision.py Selects trainer precision from GPU capabilities.
utilities/​parallelism_validator.py Validates FSDP and adapter compatibility.
utilities/​parallelism_strategy.py Defines parallelism choices.
utilities/​fsdp_config.py Builds full-shard training configuration.
utilities/​chat_format.py Shares chat templates and dataset normalization.
TRAINING_WORKFLOWS.md Documents shared training and data contracts.
tests/​unit_tests/​training_event_test.py Verifies event timestamps use seconds.
tests/​unit_tests/​text_generation_objectives_test.py Covers text-generation objectives and aliases.
tests/​unit_tests/​strategy_factory_test.py Covers strategy lookup and listing.
tests/​unit_tests/​seq2seq_training_test.py Exercises local encoder-decoder training.
tests/​unit_tests/​quantized_loading_test.py Covers quantization conversion and CUDA training.
tests/​unit_tests/​qa_test.py Covers QA preprocessing and training.
tests/​unit_tests/​qa_inference_test.py Covers answer decoding and Playground inference.
tests/​unit_tests/​provider_test.py Covers provider registration and lookup.
tests/​unit_tests/​parallelism_validator_test.py Covers parallelism compatibility checks.
tests/​unit_tests/​notebook_cli_test.py Covers notebook exit and input validation.
tests/​unit_tests/​model_factory_test.py Covers task lookup and metadata.
tests/​unit_tests/​grpo_test.py Covers rewards, configuration, and local GRPO training.
tests/​unit_tests/​fsdp_config_test.py Verifies FSDP trainer overrides.
tests/​unit_tests/​finetuning_task_test.py Covers task registration and validation.
tests/​unit_tests/​dpo_training_test.py Covers DPO training and conversation normalization.
tests/​unit_tests/​audit_launch_test.py Covers resume selection and launch validation.
tests/​test_device_utils.py Removes legacy device-utility tests.
tests/​__init__.py Test package marker.
setup.py Integrates frontend building into Python packaging.
scripts/​build_frontend.py Builds and validates the locked frontend bundle.
scripts/​build_distribution.sh Builds distributions and checks bundled UI assets.
recommendation_engine/​validation_models/​recommendation.py Defines recommendations, rationale, and memory estimates.
recommendation_engine/​validation_models/​__init__.py Exports recommendation models.
recommendation_engine/​language_use_cases/​text_generation.py Defines text-generation objectives and dataset aliases.
recommendation_engine/​language_use_cases/​summarization.py Defines encoder-decoder summarization contracts.
recommendation_engine/​language_use_cases/​instruction_following.py Defines instruction-training objectives and aliases.
recommendation_engine/​language_use_cases/​extractive_qa.py Defines extractive QA requirements.
recommendation_engine/​language_use_cases/​__init__.py Imports and registers built-in use cases.
recommendation_engine/​__init__.py Exports the use-case API.
providers/​provider.py Defines the provider interface and registry.
providers/​provider_factory.py Provides registry-backed provider lookup.
providers/​huggingface.py Implements model loading and quantization conversion.
providers/​__init__.py Declares provider display names.
notebook_cli/​main.py Adds prompt-based notebook training and history access.
notebook_cli/​__init__.py Exports the notebook entry point.
ModelForge/​utilities/​settings_managers/​FileManager.py Removes legacy file management.
ModelForge/​utilities/​settings_managers/​__init__.py Removes the legacy settings package marker.
ModelForge/​utilities/​hardware_detection/​hardware_detector_factory.py Removes the legacy hardware factory.
ModelForge/​utilities/​hardware_detection/​__init__.py Removes the legacy hardware package marker.
ModelForge/​utilities/​finetuning/​quantization.py Removes the old quantization factory.
ModelForge/​utilities/​finetuning/​__init__.py Removes the legacy fine-tuning package marker.
ModelForge/​utilities/​configs/​tasks.json Removes fixed task configuration.
ModelForge/​utilities/​configs/​hardware_thresholds.json Removes fixed hardware-profile thresholds.
ModelForge/​utilities/​__init__.py Removes the legacy utilities package marker.
ModelForge/​test_datasets/​test_dataset.json Removes the legacy QA sample dataset.
ModelForge/​strategies/​strategy_factory.py Removes the old strategy factory.
ModelForge/​strategies/​__init__.py Removes the old training-strategy protocol.
ModelForge/​services/​model_service.py Removes legacy model management.
ModelForge/​services/​hardware_service.py Removes profile-based hardware planning.
ModelForge/​services/​__init__.py Removes the legacy services package.
ModelForge/​schemas/​__init__.py Removes the legacy schemas package.
ModelForge/​routers/​playground_router.py Removes external-terminal Playground launching.
ModelForge/​routers/​models_router.py Removes legacy model endpoints.
ModelForge/​routers/​hub_management_router.py Removes the legacy Hub-upload endpoint.
ModelForge/​providers/​provider_factory.py Removes the old provider factory.
ModelForge/​providers/​__init__.py Removes the old provider protocol.
ModelForge/​notebook_cli/​progress.py Removes widget-based notebook progress displays.
ModelForge/​notebook_cli/​__init__.py Removes the old notebook API exports.
ModelForge/​model_configs/​README.md Removes fixed-profile configuration documentation.
ModelForge/​model_configs/​mid_range.json Removes mid-range model presets.
ModelForge/​model_configs/​low_end.json Removes low-end model presets.
ModelForge/​model_configs/​high_end.json Removes high-end model presets.
ModelForge/​logging_config.py Removes legacy logging setup.
ModelForge/​globals/​globals.py Removes the global settings singleton.
ModelForge/​globals/​globals_instance.py Removes eager global initialization.
ModelForge/​globals/​__init__.py Removes legacy global-state imports.
ModelForge/​Frontend/​build/​static/​js/​main.9df15fbf.js.LICENSE.txt Removes notices accompanying an obsolete bundle.
ModelForge/​Frontend/​build/​static/​js/​main.9cc9257a.js.LICENSE.txt Removes notices accompanying an obsolete bundle.
ModelForge/​Frontend/​build/​static/​js/​main.2b0344e0.js.LICENSE.txt Removes notices accompanying an obsolete bundle.
ModelForge/​Frontend/​build/​static/​js/​453.ad6eb26e.chunk.js Removes an obsolete performance-metrics bundle.
ModelForge/​Frontend/​build/​static/​js/​453.6e4f956a.chunk.js Removes an obsolete performance-metrics bundle.
ModelForge/​Frontend/​build/​robots.txt Removes a legacy generated asset.
ModelForge/​Frontend/​build/​manifest.json Removes the legacy app manifest.
ModelForge/​Frontend/​build/​index.html Removes the old bundled app shell.
ModelForge/​Frontend/​build/​asset-manifest.json Removes the old bundle asset index.
ModelForge/​formatters/​formatting_functions.py Removes legacy task-formatting functions.
ModelForge/​formatters/​__init__.py Removes legacy formatter exports.
ModelForge/​exceptions.py Removes the legacy exception hierarchy.
ModelForge/​evaluation/​metrics.py Removes legacy evaluation metrics.
ModelForge/​evaluation/​dataset_validator.py Removes the old dataset validator.
ModelForge/​evaluation/​__init__.py Removes the legacy evaluation package.
ModelForge/​dependencies.py Removes old service singletons and session state.
ModelForge/​database/​models.py Removes the legacy SQLAlchemy model schema.
ModelForge/​database/​__init__.py Removes the legacy database package.
ModelForge/​cli.py Removes the v3 command-line entry point.
MANIFEST.in Includes frontend sources and bundles in distributions.
Frontend/​tailwind.config.js Removes legacy Tailwind configuration.
Frontend/​src/​styles/​FinetuningSettingsPage.css Removes a legacy settings stylesheet.
Frontend/​src/​styles/​DetectHardwarePage.css Removes a legacy hardware stylesheet.
Frontend/​src/​setupTests.js Removes legacy Jest setup.
Frontend/​src/​services/​api.js Removes the old frontend API client.
Frontend/​src/​reportWebVitals.js Removes legacy performance reporting.
Frontend/​src/​pages/​ListModels.jsx Removes the old model-list page.
Frontend/​src/​index.js Removes the old React entry point.
Frontend/​src/​index.css Removes legacy Tailwind directives.
Frontend/​src/​components/​ErrorDialog.jsx Removes the legacy error dialog.
Frontend/​src/​App.test.js Removes the starter frontend test.
Frontend/​src/​App.js Removes the old frontend routes and state.
Frontend/​src/​App.css Removes legacy app styles.
Frontend/​public/​robots.txt Removes a legacy public asset.
Frontend/​public/​manifest.json Removes the old public app manifest.
Frontend/​public/​index.html Removes the Create React App template.
Frontend/​package.json Removes the old frontend dependencies and scripts.
Frontend/​.gitignore Removes obsolete frontend ignore rules.
Frontend/​.dockerignore Removes obsolete frontend Docker exclusions.
finetuning_strategies/​tasks/​token_classification.py Registers the token-classification model head.
finetuning_strategies/​tasks/​task.py Defines task registration and validation.
finetuning_strategies/​tasks/​seq2seq_modeling.py Registers encoder-decoder language modeling.
finetuning_strategies/​tasks/​question_answering.py Registers the extractive QA model head.
finetuning_strategies/​tasks/​causal_language_modeling.py Registers causal language modeling.
finetuning_strategies/​tasks/​__init__.py Imports built-in tasks and exposes their slugs.
finetuning_strategies/​strategy_factory.py Provides strategy lookup and metadata.
finetuning_strategies/​strategies/​__init__.py Imports built-in training strategies.
finetuning_strategies/​model_factory.py Provides model-task lookup and metadata.
finetuning_strategies/​__init__.py Fine-tuning package marker.
docs/​strategies/​full-finetuning.md Explains full fine-tuning costs and behavior.
docs/​requirements.txt Updates the documentation build dependencies.
docs/​getting-started/​concepts.md Introduces v4 training concepts and objectives.
cli/​runner.py Re-exports the shared training runner.
cli/​__init__.py CLI package marker.
.readthedocs.yaml Updates the documentation build environment.
.python-version Selects Python 3.13.
.node-version Pins the frontend Node runtime.
.gitignore Updates exclusions for the v4 layout.
.github/​workflows/​workflow.yaml Validates release versions and builds bundled distributions.
.github/​ISSUE_TEMPLATE/​feature_request.md Adds v4 interface and feature context.
.github/​ISSUE_TEMPLATE/​bug_report.md Requests v4 diagnostics and token redaction.
__init__.py Root package marker.

Review effort: Balanced

Comment thread notebook_cli/main.py Resolved
Comment thread utilities/precision.py Resolved
Add check for active jobs before exiting the CLI.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@RETR0-OS
RETR0-OS merged commit 64f13f4 into main Nov 15, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants