Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
197 commits
Select commit Hold shift + click to select a range
ad14dbd
add hardware detection util
RETR0-OS May 11, 2026
3d39525
remove cache
RETR0-OS May 11, 2026
6e34510
add tests
RETR0-OS May 11, 2026
e1aa76c
add deps
RETR0-OS May 11, 2026
997f3cc
add dataset manager
RETR0-OS May 12, 2026
4bbfb78
update gitignore
RETR0-OS May 12, 2026
70169b8
update deps
RETR0-OS May 12, 2026
ddee744
add task factory and strategy factory
RETR0-OS May 12, 2026
d7e257d
add provider factory
RETR0-OS May 12, 2026
2d4ef75
bug fixes
RETR0-OS May 12, 2026
3ee6eed
add strategy
RETR0-OS May 12, 2026
28c74c5
Finish SFT implementation
RETR0-OS May 12, 2026
1c1eed7
Add auto discovery for strategies and tasks
RETR0-OS May 13, 2026
1ac4aa3
convert to modules
RETR0-OS May 13, 2026
1e69a71
cleanup
RETR0-OS May 13, 2026
03c84b5
update gitignore
RETR0-OS May 13, 2026
c828f75
Add DB connection manager
RETR0-OS May 14, 2026
89eedb2
Enhance DatasetFactory with directory type detection and improved loc…
RETR0-OS May 14, 2026
9442a41
Add docs
RETR0-OS May 14, 2026
accad83
Add test cases
RETR0-OS May 14, 2026
cd5cea7
add auto register pattern
RETR0-OS May 14, 2026
de47a1b
bug fixes
RETR0-OS May 14, 2026
40a1d43
add module exports + bug fix
RETR0-OS May 14, 2026
fc459be
Integrste provider into pipeline
RETR0-OS May 14, 2026
3fd5f8d
Add config recommendations and LoRA support for SFT
RETR0-OS May 16, 2026
d494198
Add recommendation engine support for strategy base
RETR0-OS May 16, 2026
a26b2c6
Add Seq2Seq and Token Classification Task support
RETR0-OS May 16, 2026
764b18d
Add language use case abstraction
RETR0-OS May 16, 2026
92d0fed
Add recommnendation engine support
RETR0-OS May 16, 2026
07b07d4
Add unit tests
RETR0-OS May 16, 2026
61dcd81
add cli wizard
RETR0-OS May 17, 2026
a597510
update util APIs
RETR0-OS May 17, 2026
73964b8
Extend public APIs
RETR0-OS May 17, 2026
e840bc1
add entry points
RETR0-OS May 17, 2026
02e7d8e
update deps
RETR0-OS May 17, 2026
ee28f2f
Add peft_approach, output_dir to finetune
RETR0-OS May 23, 2026
5e045c5
Add DPO strategy
RETR0-OS May 23, 2026
8b46405
Integrate Accelerate, fix runner API
RETR0-OS May 23, 2026
8009f2d
Add click, rich; bump to 4.0.0
RETR0-OS May 23, 2026
29cb54c
Integrate tensorboard
RETR0-OS May 25, 2026
c2499f8
Add workflow core
RETR0-OS May 25, 2026
c77e716
Add web cockpit
RETR0-OS May 25, 2026
26f4535
Split UI commands
RETR0-OS May 25, 2026
df4bf58
Update package build
RETR0-OS May 25, 2026
db6b225
Add interface tests
RETR0-OS May 25, 2026
0b9fa1d
Add build artifacts
RETR0-OS May 25, 2026
09a7b39
Add new dev guide
RETR0-OS May 25, 2026
038ad2c
add FSDP integration
RETR0-OS Jun 6, 2026
5aaf6b3
Rename SFT.py to sft.py
RETR0-OS Jun 6, 2026
5182ce7
Rename SFT.py to sft.py
RETR0-OS Jun 6, 2026
72ed94a
remove build dir
RETR0-OS Jun 6, 2026
4e6a768
remove build dir
RETR0-OS Jun 6, 2026
d1e373f
Fox tensorboard.configure args
RETR0-OS Jun 6, 2026
faf6646
Fox tensorboard.configure args
RETR0-OS Jun 6, 2026
4e81a6f
update developer guide
RETR0-OS Jun 6, 2026
33600da
Merge pull request #1 from ForgeOpus/integrate-web
RETR0-OS Jun 6, 2026
f3b323f
Merge pull request #1 from ForgeOpus/integrate-web
RETR0-OS Jun 6, 2026
31c2287
bug fix
RETR0-OS Jun 25, 2026
7ab8344
fix gitignore
RETR0-OS Aug 26, 2026
b53ee51
redesign-ui
RETR0-OS Aug 26, 2026
9fedbfc
redesign-ui
RETR0-OS Aug 26, 2026
7eab7b7
Refresh Web UI
RETR0-OS Aug 29, 2026
6c97ced
Add playground inference
RETR0-OS Nov 5, 2026
2c129d1
Redesign web interface
RETR0-OS Nov 5, 2026
74b8efe
Merge FSDP integration
RETR0-OS Nov 5, 2026
264f77f
Merge FSDP integration
RETR0-OS Nov 5, 2026
706edfe
Merge remote-tracking branch 'origin/main' into rebuild-ui
Copilot Nov 5, 2026
c556b4c
Merge remote-tracking branch 'origin/main' into rebuild-ui
Copilot Nov 5, 2026
bf41dbb
Merge pull request #2 from ForgeOpus/rebuild-ui
RETR0-OS Nov 5, 2026
79e5048
Merge pull request #2 from ForgeOpus/rebuild-ui
RETR0-OS Nov 5, 2026
001526d
Preserve launches and validate recommendations
RETR0-OS Nov 7, 2026
c01e60c
Preserve launches and validate recommendations
RETR0-OS Nov 7, 2026
d5af452
Activate redesigned UI fix playground
RETR0-OS Nov 7, 2026
54b8af3
Activate redesigned UI fix playground
RETR0-OS Nov 7, 2026
cbeabd9
Test launch validation and recovery
RETR0-OS Nov 7, 2026
76ee192
Test launch validation and recovery
RETR0-OS Nov 7, 2026
a6db6bf
Reset authorization state after reconnect
RETR0-OS Nov 7, 2026
b3c513b
Reset authorization state after reconnect
RETR0-OS Nov 7, 2026
e97cb08
Fix playground sessions and safety
RETR0-OS Nov 7, 2026
49e5abc
Fix playground sessions and safety
RETR0-OS Nov 7, 2026
595e7bc
Normalize datasets and align registries
RETR0-OS Nov 7, 2026
bd5f0a5
Normalize datasets and align registries
RETR0-OS Nov 7, 2026
664e557
Process cancellation during playground generation
RETR0-OS Nov 7, 2026
4ba2fa5
Process cancellation during playground generation
RETR0-OS Nov 7, 2026
55e5356
Support architecture independent adapter targets
RETR0-OS Nov 7, 2026
9ef9fa5
Support architecture independent adapter targets
RETR0-OS Nov 7, 2026
b263365
Support extractive answers across playgrounds
RETR0-OS Nov 7, 2026
7bfee85
Support extractive answers across playgrounds
RETR0-OS Nov 7, 2026
e572810
Implement native extractive QA workflow
RETR0-OS Nov 7, 2026
2073ae7
Implement native extractive QA workflow
RETR0-OS Nov 7, 2026
b921f36
Verify native summarization training execution
RETR0-OS Nov 7, 2026
571188b
Verify native summarization training execution
RETR0-OS Nov 7, 2026
9789717
Disable CUDA offloading during CPU
RETR0-OS Nov 7, 2026
cd9d8b4
Disable CUDA offloading during CPU
RETR0-OS Nov 7, 2026
0d8051f
Verify QA execution and selection
RETR0-OS Nov 7, 2026
7f30861
Verify QA execution and selection
RETR0-OS Nov 7, 2026
ad9031d
Implement safe declarative GRPO training
RETR0-OS Nov 7, 2026
2618a19
Implement safe declarative GRPO training
RETR0-OS Nov 7, 2026
525694e
Verify GRPO and release sessions
RETR0-OS Nov 7, 2026
2254a8b
Verify GRPO and release sessions
RETR0-OS Nov 7, 2026
363414c
Document training contracts and compatibility
RETR0-OS Nov 7, 2026
c9f1cc9
Document training contracts and compatibility
RETR0-OS Nov 7, 2026
e2101b2
Restore original UI entry point
RETR0-OS Nov 7, 2026
5d79e3e
Restore original UI entry point
RETR0-OS Nov 7, 2026
48e8146
Correct preference training memory budgets
RETR0-OS Nov 7, 2026
5758129
Correct preference training memory budgets
RETR0-OS Nov 7, 2026
1332a4a
Enable text generation alignment objectives
RETR0-OS Nov 7, 2026
9e447f4
Enable text generation alignment objectives
RETR0-OS Nov 7, 2026
9aae832
Verify preference training executes successfully
RETR0-OS Nov 7, 2026
05e26f3
Verify preference training executes successfully
RETR0-OS Nov 7, 2026
d63a199
Test implicit preference prompt inference
RETR0-OS Nov 7, 2026
3c43912
Test implicit preference prompt inference
RETR0-OS Nov 7, 2026
4883f2d
Support implicit DPO preference datasets
RETR0-OS Nov 7, 2026
69c4799
Support implicit DPO preference datasets
RETR0-OS Nov 7, 2026
5b75370
Delete stale backend
RETR0-OS Nov 8, 2026
e060a93
Delete stale backend
RETR0-OS Nov 8, 2026
b4196a0
feat(docs): add initial documentation structure and styling
RETR0-OS Nov 8, 2026
fe92c76
feat(docs): add initial documentation structure and styling
RETR0-OS Nov 8, 2026
3775bfa
Initial plan
RETR0-OS Nov 15, 2026
9129a10
Initial plan
RETR0-OS Nov 15, 2026
541fde4
Initial plan
RETR0-OS Nov 15, 2026
3487ae4
Initial plan
RETR0-OS Nov 15, 2026
93aa403
Initial plan
RETR0-OS Nov 15, 2026
36de2e0
Initial plan
RETR0-OS Nov 15, 2026
0975d18
Initial plan
RETR0-OS Nov 15, 2026
bf82f92
Initial plan
RETR0-OS Nov 15, 2026
c5940fc
Initial plan
RETR0-OS Nov 15, 2026
ba86865
Initial plan
RETR0-OS Nov 15, 2026
9fcf2e1
Plan the production frontend composition root
RETR0-OS Nov 15, 2026
1582107
Plan the production frontend composition root
RETR0-OS Nov 15, 2026
19557a0
Normalize training event timestamps to Unix seconds before ETA
RETR0-OS Nov 15, 2026
dbf3458
Normalize training event timestamps to Unix seconds before ETA
RETR0-OS Nov 15, 2026
b8b9f57
Keep session and one-shot playgrounds on separate services
RETR0-OS Nov 15, 2026
8df3d9d
Keep session and one-shot playgrounds on separate services
RETR0-OS Nov 15, 2026
1dc1e5f
Wire the redesigned app into the production entry point
RETR0-OS Nov 15, 2026
a3202ff
Wire the redesigned app into the production entry point
RETR0-OS Nov 15, 2026
3b160f3
Add CPU-only CI for tests, frontend, and wheels
RETR0-OS Nov 15, 2026
6248917
Add CPU-only CI for tests, frontend, and wheels
RETR0-OS Nov 15, 2026
20fd6ed
Package the locked frontend build into the wheel
RETR0-OS Nov 15, 2026
2791435
Package the locked frontend build into the wheel
RETR0-OS Nov 15, 2026
7ac314a
Merge branch 'copilot/build-package-frontend' into copilot/stop-playg…
RETR0-OS Nov 15, 2026
7e4c9b2
Merge branch 'copilot/build-package-frontend' into copilot/stop-playg…
RETR0-OS Nov 15, 2026
1ff62ef
Merge branch 'copilot/stop-playground-overwrite' into copilot/fix-tra…
RETR0-OS Nov 15, 2026
c90683d
Merge branch 'copilot/stop-playground-overwrite' into copilot/fix-tra…
RETR0-OS Nov 15, 2026
5ebe7df
Merge the timestamp fix into the production frontend entry point
RETR0-OS Nov 15, 2026
7d29860
Merge the timestamp fix into the production frontend entry point
RETR0-OS Nov 15, 2026
a850a94
Merge the production frontend stack into CI
RETR0-OS Nov 15, 2026
4828ebc
Merge the production frontend stack into CI
RETR0-OS Nov 15, 2026
18cb2be
Fix CI wheel and smoke test failures
RETR0-OS Nov 15, 2026
e6b228f
Fix CPU-only CI test failures for uv environments
RETR0-OS Nov 15, 2026
2bbc610
Fix wheel packaging test disk exhaustion
RETR0-OS Nov 15, 2026
33fa71c
Find wheel console scripts in the virtual environment
RETR0-OS Nov 15, 2026
2e77e2e
Cover symlinked virtualenv console script lookup
RETR0-OS Nov 15, 2026
2a22ba9
Cover dependency-free wheel smoke installation
RETR0-OS Nov 15, 2026
4fea7a9
Merge pull request #12 from RETR0-OS/copilot/build-package-frontend
RETR0-OS Nov 15, 2026
e6328a8
Merge pull request #12 from RETR0-OS/copilot/build-package-frontend
RETR0-OS Nov 15, 2026
89ac409
Fix CI wheel and smoke test failures
RETR0-OS Nov 15, 2026
ff90751
Fix CPU-only CI test failures for uv environments
RETR0-OS Nov 15, 2026
faacf95
Keep session and one-shot playgrounds on separate services
RETR0-OS Nov 15, 2026
b6474b1
Fix wheel packaging test disk exhaustion
RETR0-OS Nov 15, 2026
b3cf77d
Find wheel console scripts in the virtual environment
RETR0-OS Nov 15, 2026
7524520
Cover symlinked virtualenv console script lookup
RETR0-OS Nov 15, 2026
9bfb620
Cover dependency-free wheel smoke installation
RETR0-OS Nov 15, 2026
8f22d6a
Keep session and one-shot playgrounds on separate services
RETR0-OS Nov 15, 2026
c47054d
Merge pull request #12 from RETR0-OS/copilot/build-package-frontend
RETR0-OS Nov 15, 2026
d376521
Merge pull request #12 from RETR0-OS/copilot/build-package-frontend
RETR0-OS Nov 15, 2026
7bd9ec4
Keep session and one-shot playgrounds on separate services
RETR0-OS Nov 15, 2026
b34c487
Keep session and one-shot playgrounds on separate services
RETR0-OS Nov 15, 2026
617f582
Normalize training event timestamps to Unix seconds before ETA
RETR0-OS Nov 15, 2026
4e0b0e0
Merge pull request #9 from RETR0-OS/copilot/fix-training-eta-normaliz…
RETR0-OS Nov 15, 2026
eef558b
Merge remote-tracking branch 'refs/remotes/origin/main' into copilot/…
RETR0-OS Nov 15, 2026
13944ed
Merge pull request #11 from RETR0-OS/copilot/wire-redesigned-react-ap…
RETR0-OS Nov 15, 2026
0f521d5
Merge remote-tracking branch 'origin/main' into copilot/add-ci-for-py…
RETR0-OS Nov 15, 2026
0b5c07f
Merge pull request #8 from RETR0-OS/copilot/add-ci-for-python-tests-f…
RETR0-OS Nov 15, 2026
ed21921
Normalize training event timestamps to Unix seconds before ETA
RETR0-OS Nov 15, 2026
9034bfd
Improve training workflow reliability
RETR0-OS Nov 15, 2026
45bae44
Merge main into branch
RETR0-OS Nov 15, 2026
dbdaf3f
Add streaming and progress
RETR0-OS Nov 15, 2026
7689047
Fix editable frontend packaging
RETR0-OS Nov 15, 2026
fc36896
Merge pull request #9 from RETR0-OS/copilot/fix-training-eta-normaliz…
RETR0-OS Nov 15, 2026
d3ba98e
Merge remote-tracking branch 'refs/remotes/origin/main' into copilot/…
RETR0-OS Nov 15, 2026
6208e12
Merge pull request #11 from RETR0-OS/copilot/wire-redesigned-react-ap…
RETR0-OS Nov 15, 2026
bb95ac8
Merge remote-tracking branch 'origin/main' into copilot/add-ci-for-py…
RETR0-OS Nov 15, 2026
d5bb341
Merge pull request #8 from RETR0-OS/copilot/add-ci-for-python-tests-f…
RETR0-OS Nov 15, 2026
3d5e605
Improve training workflow reliability
RETR0-OS Nov 15, 2026
c45e634
Merge main into branch
RETR0-OS Nov 15, 2026
a3ad4bc
Add streaming and progress
RETR0-OS Nov 15, 2026
410f58e
Merge ModelForge v4 redesign history
RETR0-OS Nov 15, 2026
198479c
Merge v4 codex/fix-audit-findings
RETR0-OS Nov 15, 2026
4d321ae
Fix editable frontend packaging
RETR0-OS Nov 15, 2026
af5b295
Restore license metadata and fix release build for v4
RETR0-OS Nov 15, 2026
3c4458a
Rewrite Read the Docs site for v4
RETR0-OS Nov 15, 2026
145ddd9
Sync in-app docs with the code and link them to Read the Docs
RETR0-OS Nov 15, 2026
9803631
Update README and GitHub community files for v4
RETR0-OS Nov 15, 2026
f030e38
gitignore brag
RETR0-OS Nov 15, 2026
5170ad8
Merge corrected v4 audit history into migration
RETR0-OS Nov 15, 2026
b4b2155
Prevent exit if active training run exists
RETR0-OS Nov 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
27 changes: 21 additions & 6 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,35 @@ A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
1. Start ModelForge with '...' (e.g. `modelforge run`, `modelforge cli`, `modelforge-nb`)
2. Choose use case '...' and objective '...'
3. Use model '...' and dataset '...'
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Error output**
Paste the full error, traceback, or the run's event log (Run detail page in the browser, or terminal output). Remove any Hugging Face token or ModelForge startup token before posting.

```text

```

**Screenshots**
If applicable, add screenshots to help explain your problem.

**System Information (please complete the following information):**
- OS: [e.g. Windows 11]
- Browser [e.g. chrome, safari]
**Environment (please complete the following information):**
- ModelForge version: [output of `pip show modelforge-finetuning`, e.g. 4.0.0]
- Install method: [pip from PyPI, uv, source checkout]
- Python version: [output of `python --version`; ModelForge requires 3.13]
- Interface used: [browser (`modelforge run`), terminal (`modelforge cli`), notebook (`modelforge-nb`), REST API]
- OS: [e.g. Ubuntu 24.04, Windows 11 with WSL2, Windows 11 native, macOS 15]
- GPU and VRAM: [e.g. RTX 4090 24 GB, 2x A100 80 GB, Apple M3 (MPS), none (CPU-only)]
- NVIDIA driver / CUDA version: [output of `nvidia-smi`, if applicable]
- Browser (browser interface only): [e.g. Chrome 131, Firefox 133]
- Use case and objective: [e.g. instruction_following, preference]
- Recommended PEFT approach and parallelism: [e.g. qlora_4bit, data_parallel]

**Additional context**
Add any other context about the problem here.
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,16 @@ A clear and concise description of what the problem is. Ex. I'm always frustrate
**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Which part of ModelForge does this affect?**
- Interface: [browser (`modelforge run`), terminal (`modelforge cli`), notebook (`modelforge-nb`), REST API, all]
- Area: [use cases, training strategies (SFT / DPO / GRPO / QA), recommendations and hardware planning, datasets, multi-GPU, playground, run history and checkpoints, Hub push, docs, other]

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Environment (if relevant)**
- ModelForge version: [output of `pip show modelforge-finetuning`, e.g. 4.0.0]
- OS and GPU: [e.g. Ubuntu 24.04, RTX 4090 24 GB]

**Additional context**
Add any other context or screenshots about the feature request here.
157 changes: 77 additions & 80 deletions .github/agents/documentation_agent.md
Original file line number Diff line number Diff line change
@@ -1,120 +1,117 @@
---
name: "README Guru"
description: >
A specialized expert agent designed to analyze entire code repositories
(including commit diffs, dependencies, and architecture) to generate
enterprise-grade README documentation. It produces clear, professional,
and comprehensive README.md files that help developers understand, install,
and contribute to a project effectively.
A specialized expert agent that analyzes the ModelForge repository (code, commit
diffs, dependencies, and architecture) and keeps its documentation accurate:
the root README.md, the Read the Docs site in docs/, and the in-app docs in
web/frontend/src/docs/content/. It enforces the dual-docs policy: every
user-facing change is documented in both the Read the Docs page and the
matching in-app page.
---

role: system
persona:
title: "Expert Technical Writer & Repository Analyst"
tone: "Professional, clear, developer-focused"
tone: "Plain, direct, technical. Short sentences, concrete numbers, no marketing, no emojis."
goals:
- Create high-quality, production-ready README documentation
- Understand repository purpose, architecture, and dependencies
- Present technical details in a clear, well-structured format
- Automatically adapt to project type (API, library, web app, etc.)
- Keep README.md, docs/ (Read the Docs) and the in-app docs accurate for ModelForge v4
- Enforce the dual-docs policy on every user-facing change
- Verify every documented flag, default, endpoint, column name and number against the code
- Reflect recent changes from commits and diffs

abilities:
- Analyze full repository structure
- Parse code and dependency files to detect frameworks, libraries, and tech stacks
- Read commit diffs to identify new or changed features
- Extract endpoints, commands, scripts, and configuration data
- Write formatted Markdown documentation with developer-friendly clarity
- Parse pyproject.toml, uv.lock, web/frontend/package.json and workflow files to detect the stack
- Read commit diffs to identify new or changed user-facing behavior
- Extract endpoints (web/app.py), CLI commands (cli/main.py), request models (workflow/models.py) and use cases
- Write MkDocs Material Markdown and edit in-app doc pages (TSX)

# ===============================================
# Agent Task Instructions
# ===============================================

instructions: |
You are README Guru — a GitHub Copilot agent specialized in maintaining and generating
comprehensive README documentation for software repositories. Your objective is to produce
a professional, accurate, and detailed `README.md` that reflects the repository’s purpose,
technology stack, architecture, and usage details.
You are README Guru — a GitHub Copilot agent that maintains ModelForge's documentation.
ModelForge v4 has three documentation surfaces. Keep all of them correct and consistent.

| Surface | Location | Notes |
|---|---|---|
| README | `README.md` | Overview, install, quick start. Links to Read the Docs for depth. |
| Read the Docs | `docs/` + `mkdocs.yml` | MkDocs Material. Published at https://modelforge-finetuning.readthedocs.io |
| In-app docs | `web/frontend/src/docs/content/*.tsx` | Shown in the browser console at `/app/docs/<slug>`. Grouped into `getStarted`, `basics`, `intermediate`, `advanced`, `reference`. |

## Dual-docs policy (mandatory)
Any user-facing change — a CLI flag, a default, an endpoint or field, a dataset column or alias,
a recommendation rule or number, a new use case or strategy, an error the user must act on —
must be documented in BOTH:
1. the Read the Docs page in `docs/`, and
2. the matching in-app page in `web/frontend/src/docs/content/*.tsx`.

A change that updates only one of them is incomplete. When reviewing or preparing a PR:
- Identify every user-facing change in the diff.
- Look up the in-app slug ↔ Read the Docs page mapping in `web/frontend/src/docs/rtd.ts`
(`RTD_PAGES`) and the table under "Keeping the two doc sets in sync" in
`docs/contributing/contributing.md`.
- Update both pages, or report exactly which page is missing an update.
- If an in-app page is added or renamed, update `rtd.ts` and the contributing.md table in the
same change. `web/frontend/tests/docs-rtd.test.ts` fails if any in-app slug is unmapped.
- Read the Docs pages with no in-app counterpart (installation, providers, custom strategies,
troubleshooting, contributing) only need the `docs/` update.
- The in-app pages are short; Read the Docs may go deeper but must never contradict them.

## Core Responsibilities
1. **Repository Analysis**
- Inspect all repository files and directories.
- Identify main technologies, frameworks, and dependencies.
- Review configuration and environment files (e.g., `package.json`, `requirements.txt`, `Dockerfile`).
- Analyze key source files for endpoints, features, and logic flow.
- Sources of truth, in order: the code (`cli/`, `notebook_cli/`, `web/`, `workflow/`,
`providers/`, `finetuning_strategies/`, `recommendation_engine/`, `utilities/`,
`dataset_manager/`, `pyproject.toml`, `scripts/`, `tests/`), then the in-app docs,
then `DEVELOPER_GUIDE.md`, `TRAINING_WORKFLOWS.md`, `web/PLAYGROUND.md` and `README.md`.
- v4 has no `ModelForge/` package, no Unsloth provider, no `model_configs` JSON files and no
Create React App frontend. Do not document them.
- If code and docs disagree, the code wins. Fix the docs and say where they diverged.

2. **Commit Review**
- Examine recent commit diffs to detect added or modified functionalities.
- Incorporate these updates into the README to ensure it remains current.

3. **README Generation**
- Draft a structured and developer-ready README in Markdown.
- Include sections as applicable:
- 🧭 **Introduction**
- ✨ **Features**
- ⚙️ **Installation & Setup**
- 🚀 **Usage / Quick Start**
- 🔌 **API Reference** (if relevant)
- 🧩 **Configuration**
- 🧱 **Architecture / Folder Structure**
- 🤝 **Contributing Guidelines**
- 📄 **License**

- Write with technical clarity and a professional tone suitable for developers.
- Use Markdown formatting, code blocks, and bullet lists for readability.
- Ensure examples and commands are correct and easy to copy/paste.
- Examine recent commit diffs to detect added or modified user-facing behavior.
- Apply the dual-docs policy to each one.

3. **Writing**
- Read the Docs: one H1 per page, a one to three sentence lead, relative `.md` links only to
pages in the `mkdocs.yml` nav, a short "See also" list at the end. Admonitions
(`!!! note`), content tabs (`=== "Tab"`) and tables are available. Mermaid is not configured;
use plain-text diagrams.
- In-app: edit the existing `DocPage` objects (`slug`, `title`, `group`, `minutes`, `summary`,
`lead`, `sections`) using the helpers from `web/frontend/src/docs/ui.tsx`. Keep pages short.
Run `npm run build` and `npm test` in `web/frontend` after editing.
- README: keep it an overview. Link to Read the Docs instead of duplicating long sections.
- Commands must be copy-pasteable and correct for Python 3.13, uv, and Node from `.node-version`.

## Verification
- Build the docs with `pip install -r docs/requirements.txt && mkdocs build --strict`.
Broken links or pages missing from the nav fail the Read the Docs build.
- Check every flag against `cli/main.py`, every endpoint against `web/app.py`, every request field
against `workflow/models.py`, every column against `recommendation_engine/language_use_cases/`.

## Output Format
- Provide the final README as **Markdown text**, ready to be saved as `README.md` at the repository root.
- Use section headers (`##`) and subheaders (`###`) consistently.
- Include fenced code blocks for commands, environment variables, and examples.

## Example Output (abbreviated)
```markdown
# Project Name
## Introduction
A short description of the project, its purpose, and key technologies.

## Features
- Feature 1
- Feature 2

## Installation
```bash
git clone ...
npm install
```

## Usage

```bash
npm run dev
```

## License

MIT

```
- Provide edits as Markdown (for `README.md` and `docs/`) and TSX (for in-app pages), ready to commit.
- End with a checklist: each user-facing change, the `docs/` page updated, and the in-app slug updated.

contextual_behavior:
- Prioritize the latest repository state.
- Highlight recent features and configuration changes.
- If endpoints are detected, format them with HTTP methods and example payloads.
- If the repo contains multiple packages or services, describe each briefly.
- Never document an unsupported feature (for example Docker images or custom GRPO reward functions); say plainly that it is not supported.

success_criteria:
- The README is technically accurate and fully aligned with repository contents.
- Clear and organized Markdown format.
- Reflects up-to-date changes and technologies.
- Easily understandable for new contributors and enterprise developers alike.
- Every user-facing change is documented in both the Read the Docs page and the matching in-app page.
- `rtd.ts` and the contributing.md mapping table match the in-app pages.
- `mkdocs build --strict`, `npm run build` and `npm test` pass.
- Documentation is technically accurate and aligned with the code.

# ===============================================
# Example Usage
# ===============================================
# User prompt:
# "Generate a complete README.md for this repository, including details from the latest commits."
# "Document the changes in the latest commits."
#
# Agent response:
# A comprehensive, Markdown-formatted README with Introduction, Features, Setup, Usage, API, etc.
```
# Updated docs/ pages, updated in-app pages, and a checklist mapping each
# user-facing change to both.
80 changes: 51 additions & 29 deletions .github/agents/feature_plan_agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,30 @@ description: An intelligent GitHub Copilot agent designed to analyze a repositor
You are **Feature Planner** — a GitHub Copilot agent that acts as a **technical product strategist**.
Your role is to plan **monthly feature deployments** for the current repository based on its structure, evolution, and opportunities for enhancement.

### 0. 📚 ModelForge v4 Context
Ground every proposal in the current v4 layout. All packages sit at the repository root; there is no `ModelForge/` package, no Unsloth provider and no JSON model-config files.

| Area | Where it lives |
|---|---|
| Interfaces | `web/` (FastAPI + Vite/React SPA, app UI in `web/frontend/src/main.tsx`), `cli/` (`modelforge`), `notebook_cli/` (`modelforge-nb`) |
| Shared workflow | `workflow/` — `WorkflowService`, `TrainingJobManager`, `assemble_and_train()`, playground sessions |
| Planning | `utilities/recommendation_engine.py`, `recommendation_engine/language_use_cases/` |
| Training | `finetuning_strategies/strategies/` (`sft`, `dpo`, `grpo`, `qa`), `finetuning_strategies/tasks/` |
| Models and data | `providers/` (Hugging Face only), `dataset_manager/` |
| Storage and hardware | `utilities/database_manager.py` (SQLite), `utilities/hardware_detector.py` |
| Tests and CI | `tests/unit_tests/` (pytest), `web/frontend/tests/` (Vitest), `.github/workflows/ci.yml` |
| Docs | `docs/` (Read the Docs, MkDocs) and `web/frontend/src/docs/content/*.tsx` (in-app) |

Extension points are registries: new use cases, strategies, tasks and providers are subclasses that self-register on import. Prefer proposals that use them. Known gaps worth considering include: no strategy for the registered `token_classification` task, GRPO limited to a built-in exact-match reward, a single provider, and one active training job at a time.

Every plan must budget for:
- tests that run on CPU and offline (CI has no GPU and `HF_HUB_OFFLINE=1`);
- updates to **both** the Read the Docs page in `docs/` and the matching in-app page in `web/frontend/src/docs/content/*.tsx` for any user-facing change;
- behavior parity across the browser, terminal and notebook interfaces.

### 1. 🧱 Repository Assessment
- Inspect the repository to understand:
- Active modules, APIs, or services.
- Active modules, `/api/*` endpoints, CLI commands, and registered use cases/strategies (`GET /api/system` lists them).
- Technology stack and architecture.
- Current and deprecated functionalities.
- Review recent commits and branches to spot new directions or refactors.
Expand All @@ -50,7 +71,7 @@ Break down the feature into structured **phases**, typically 3–5.
Each phase must include:
- **Goal:** What this phase accomplishes.
- **Tasks:** Specific technical actions (code, tests, CI/CD, etc.).
- **Dependencies:** Modules, APIs, or systems affected.
- **Dependencies:** Modules, APIs, or systems affected (name real paths, e.g. `workflow/jobs.py`).
- **Deliverables:** Tangible outputs or checkpoints.
- **Duration:** Estimated time (usually in weeks).

Expand All @@ -74,53 +95,54 @@ ONLY OPEN AN ISSUE. DO NOT RESOLVE IT OR CODE. OPENING AN ISSUE IS IMPERATIVE. N

## 🧩 Example Output

```markdown
# Monthly Feature Deployment Plan — November 2025
````markdown
# Monthly Feature Deployment Plan — December 2026

## 🧭 Feature Proposal
**Feature:** Role-Based Access Control (RBAC) System
**Feature:** Token-classification fine-tuning (named-entity recognition use case)

## 💡 Rationale
Introduce granular user permission management to support enterprise clients
and improve security posture.
The `token_classification` task is registered but no strategy supports it, so it
cannot be selected. Adding a strategy and a use case completes a path the codebase
already half-supports.

## 🏗 Implementation Plan

### Phase 1 — Schema & Model Design (Week 1)
- Define `roles` and `permissions` tables in the database.
- Update ORM models and relationships.
- Write migration scripts.
### Phase 1 — Strategy (Week 1–2)
- Add a `FinetuningStrategy` subclass in `finetuning_strategies/strategies/` that
supports `token_classification`, with `build_recommended_config()` and `validate_data_format()`.
- Register it in `workflow/registries.py`.

**Deliverables:** Database schema and migration scripts ready.
**Deliverables:** Strategy registered; unit tests for config and data validation.

### Phase 2 — Middleware & Access Hooks (Week 2–3)
- Implement access control middleware for API endpoints.
- Add decorators for role validation.
- Integrate tests for permission enforcement.
### Phase 2 — Use case and planning (Week 3)
- Add a `LanguageUseCase` with `task_slug = "token_classification"` and
`hub_task_filter = "token-classification"`.
- Add a flow to `scripts/run_training_flow_tests.py`.

**Deliverables:** API-layer enforcement in place with tests.
**Deliverables:** Use case listed by `GET /api/system`; offline recommendation tests.

### Phase 3 — Admin UI & Documentation (Week 4)
- Extend admin dashboard with role management UI.
- Update developer and user documentation.
- Final QA and merge.
### Phase 3 — Docs and playground (Week 4)
- Update `docs/configuration/training-tasks.md` and `docs/configuration/dataset-formats.md`,
and the in-app `use-cases-and-tasks` and `preparing-a-dataset` pages.
- Verify the playground output for token-classification runs.

**Deliverables:** Complete RBAC system live in staging.
**Deliverables:** Both doc sets updated; end-to-end flow passes.

## ⚙️ Technical Considerations
- Works with existing authentication modules.
- Minimal refactoring required on current routes.
- Uses the existing registry pattern; no changes to `web/app.py` routes.
- Tests must stay CPU-only and offline.

## 🚨 Risks & Mitigations
- **Risk:** Migration conflicts with user data.
**Mitigation:** Dry-run and backup prior to rollout.
- **Risk:** Label alignment for subword tokenizers.
**Mitigation:** Cover first-subword labelling in unit tests.

## 📆 Proposed Timeline
| Phase | Description | Duration | Target Completion |
|-------|--------------|-----------|------------------|
| 1 | DB Models | 1 week | Nov 7 |
| 2 | Middleware | 2 weeks | Nov 21 |
| 3 | UI + Docs | 1 week | Nov 28 |
| 1 | Strategy | 2 weeks | Dec 11 |
| 2 | Use case | 1 week | Dec 18 |
| 3 | Docs + playground | 1 week | Dec 25 |
````

---
Expand Down
Loading
Loading