Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
0183fbe
Make standard setup ready and migrate image template runtimes
sdevil7th Oct 7, 2026
e08f606
Make source and runtime regression checks portable across hosts
sdevil7th Oct 7, 2026
36d36d9
Refresh bundled source-map-js license notice
sdevil7th Oct 7, 2026
123ede0
Add guidance contracts and native Qwen image compatibility
sdevil7th Oct 7, 2026
d8e6954
Refresh coverage ledgers after final image template build
sdevil7th Oct 8, 2026
ccca4a1
Document Windows feedback acceptance and base runtime readiness
sdevil7th Oct 8, 2026
2769845
Recognize directly installed Instinct SDK runtimes
sdevil7th Oct 8, 2026
73c8b39
Use the default allocator for Linux ROCm runtimes
sdevil7th Oct 8, 2026
ff93a8a
Avoid absent-cache errors and refresh supervisor controls
sdevil7th Oct 8, 2026
41d5995
Refresh publication fingerprints for the reviewed frontend bundle
sdevil7th Oct 8, 2026
2197bec
Keep edited image workflows ready in fresh installations
sdevil7th Oct 8, 2026
fec0f65
Align owned ROCm vision setup and bundled workflow UI
sdevil7th Oct 8, 2026
82d8a0b
Load legacy processors with their selected model config
sdevil7th Oct 8, 2026
5bf4c38
Preserve Qwen multimodal processor inputs and bundle Gallery collecti…
sdevil7th Oct 8, 2026
11db2aa
Use stable Diffusers and add guarded Cosmos Super image workflow
sdevil7th Oct 8, 2026
9f1d93a
Handle Windows extended paths in Hugging Face cache links
sdevil7th Oct 8, 2026
5f38a40
Preserve reviewed workflow bindings and refresh registered Block cont…
sdevil7th Oct 8, 2026
3e107a2
Document Hugging Face feedback and cross-machine validation
sdevil7th Oct 9, 2026
283c55b
Require safe Auto releases for unmeasured model owners
sdevil7th Oct 9, 2026
23951b1
Check the selected full-residency disk requirement
sdevil7th Oct 9, 2026
ad79f3a
Select the paired setup branch in native installation guides
sdevil7th Oct 9, 2026
2a4fe04
Verify Cosmos decoded images pass the SDK safety transform
sdevil7th Oct 9, 2026
e5b96eb
Preserve the original publisher caption in Cosmos starters
sdevil7th Oct 9, 2026
c43b570
Keep measured zero device memory during Auto normalization
sdevil7th Oct 9, 2026
f65d292
Publish authoritative per-mode model dependencies
sdevil7th Oct 9, 2026
18445cf
Publish reviewed runtime recovery and workflow preview bundle
sdevil7th Oct 9, 2026
cc6f54e
Preserve Cosmos file integrity without rejecting read access times
sdevil7th Oct 9, 2026
49d1f5b
Support owned Hugging Face shared-blob bridges and precise repair dia…
sdevil7th Oct 9, 2026
4432062
Compare safety artifact metadata within consistent stat APIs
sdevil7th Oct 9, 2026
3b7cab8
Add full-weight image templates and initialize mandatory Cosmos stage…
sdevil7th Oct 9, 2026
8eba6fb
Document Hugging Face fixes and full-weight image validation
sdevil7th Oct 9, 2026
1634d93
Protect native offload ownership and correct base-runtime repair guid…
sdevil7th Oct 9, 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
  •  
  •  
  •  
22 changes: 17 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ jobs:
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
with: { version: '0.11.26' }
- run: uvx --from ruff==0.12.7 ruff check . --select E9,F
- run: bash -n install.sh run.sh scripts/with-runtime-env.sh

Expand All @@ -40,11 +39,24 @@ jobs:
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with: { python-version: '${{ matrix.python }}' }
- uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
with: { version: '0.11.26' }
- run: uv run --no-project --no-sync --python 3.12 -m modiff.dev plan --accelerator cpu --backend-only --json
- run: uv run --no-project --no-sync --python 3.12 -m modiff.dev setup --accelerator cpu --backend-only --non-interactive --json
- run: uv sync --extra cpu --locked
- run: uv pip install --python ${{ matrix.managed-python }} -r requirements/test.txt
- run: uv pip check --python ${{ matrix.managed-python }}
- run: uv run --no-project --no-sync --python 3.12 -m modiff.dev check --json --check-port 8088 --fail-on-error
- run: ${{ matrix.managed-python }} -m modiff.preflight --json --check-port 8088 --fail-on-error
- run: ${{ matrix.managed-python }} scripts/smoke_base_runtime.py
- run: ${{ matrix.managed-python }} scripts/smoke_service_package.py
# Static catalog proof is independent of the ordinary installed release.
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
env:
# Source audit checks exact Git blob bytes, including on Windows.
GIT_CONFIG_COUNT: '1'
GIT_CONFIG_KEY_0: core.autocrlf
GIT_CONFIG_VALUE_0: 'false'
with:
repository: huggingface/diffusers
ref: fbf49e7f35857f76bc57b177e26f12b03687c668
path: .reviewed-upstream/diffusers
persist-credentials: false
- run: ${{ matrix.managed-python }} -m pytest -q
env:
MODIFF_DIFFUSERS_CATALOG_SOURCE: ${{ github.workspace }}/.reviewed-upstream/diffusers/src/diffusers
87 changes: 10 additions & 77 deletions .github/workflows/qualify-optional-runtime-macos.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Qualify optional runtime on macOS
name: Qualify native base runtime on macOS

on:
workflow_dispatch:
Expand All @@ -7,7 +7,7 @@ permissions:
contents: read

concurrency:
group: optional-runtime-macos-${{ github.ref }}
group: native-runtime-macos-${{ github.ref }}
cancel-in-progress: false

jobs:
Expand All @@ -16,85 +16,18 @@ jobs:
timeout-minutes: 35
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

- uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
- name: Verify hosted target
run: |
test "$(uname -m)" = "arm64"
sw_vers

- name: Prepare prospective clean base
run: |
cat > "$RUNNER_TEMP/prospective-base.patch" <<'PATCH'
diff --git a/pyproject.toml b/pyproject.toml
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,16 +12,14 @@ dependencies = [
"aiohttp-cors>=0.7.0",
"kornia>=0.8.1",
"nanoid>=2.0.0",
# Keep unqualified targets base-delivered until their executable qualifier
# passes; Linux/Windows x86-64 receive the exact optional overlay on use.
- "peft>=0.17.0; sys_platform == 'darwin' or platform_machine == 'aarch64' or platform_machine == 'arm64' or platform_machine == 'ARM64'",
"protobuf>=6.31.1",
"scipy>=1.15.2",
"sentencepiece>=0.2.0",
"torch>=2.6.0",
"torchsde>=0.2.6",
"torchvision>=0.21.0",
- "transformers>=4.49.0; sys_platform == 'darwin' or platform_machine == 'aarch64' or platform_machine == 'arm64' or platform_machine == 'ARM64'",
"diffusers @ git+https://github.com/huggingface/diffusers.git@fbf49e7f35857f76bc57b177e26f12b03687c668",
"ftfy>=6.3.1",
"huggingface-hub>=1.31.0,<2.0",
PATCH
git apply --check "$RUNNER_TEMP/prospective-base.patch"
git apply "$RUNNER_TEMP/prospective-base.patch"
test "$(git diff --name-only)" = "pyproject.toml"
git diff --check
git diff -- pyproject.toml > "$RUNNER_TEMP/prospective-base.diff"
git config user.name "MoDiff qualification"
git config user.email "qualification@modiff.invalid"
git add -- pyproject.toml
git commit -m "chore: prepare prospective macOS qualification base"
test -z "$(git status --porcelain)"

- name: Install isolated CPU base
run: ./install.sh --accelerator cpu --backend-only --non-interactive

- name: Require clean-base qualification readiness
run: |
./scripts/with-runtime-env.sh ./.venv/bin/python \
scripts/qualify_optional_runtime.py --preflight-only \
--profile-id huggingface-transformers-main-96fe6dce-peft-0.20.0 \
| tee "$RUNNER_TEMP/preflight.json"
./.venv/bin/python -c 'import json, os, pathlib; value=json.loads(pathlib.Path(os.environ["RUNNER_TEMP"], "preflight.json").read_text()); assert value["status"] == "ready"; assert value["profileId"] == "huggingface-transformers-main-96fe6dce-peft-0.20.0"; assert value["platform"] == "macos"; assert value["machine"] == "arm64"; assert value["sourceRevisionReady"] is True; assert value["cleanBase"] is True; assert value["stagedPackagesPresent"] == []'

- name: Run explicit-consent qualification
run: |
./scripts/with-runtime-env.sh ./.venv/bin/python \
scripts/qualify_optional_runtime.py --consent \
--profile-id huggingface-transformers-main-96fe6dce-peft-0.20.0 \
--evidence "$RUNNER_TEMP/optional-runtime-macos-arm64.json"
./.venv/bin/python -c 'import json, os, pathlib; value=json.loads(pathlib.Path(os.environ["RUNNER_TEMP"], "optional-runtime-macos-arm64.json").read_text()); assert value["status"] == "passed"; assert value["profileId"] == "huggingface-transformers-main-96fe6dce-peft-0.20.0"; assert value["platform"] == "macos"; assert value["machine"] == "arm64"; assert value["sourceRevisionReady"] is True; assert value["cleanBase"] is True; assert value["managedStateRetained"] is False; assert value["sourceFlagsChanged"] is False'

- name: Record bounded target context
if: ${{ always() }}
run: |
{
git rev-parse HEAD
uname -m
sw_vers
test ! -x ./.venv/bin/python || ./.venv/bin/python --version
} > "$RUNNER_TEMP/target-context.txt"

run: test "$(uname -m)" = "arm64"
- name: Install native base
run: uv sync --locked
- name: Verify required libraries and LoRA without model downloads
run: ./.venv/bin/python scripts/smoke_base_runtime.py | tee "$RUNNER_TEMP/native-runtime-macos-arm64.json"
- name: Upload review evidence
if: ${{ always() }}
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: optional-runtime-macos-arm64-${{ github.run_id }}
path: |
${{ runner.temp }}/optional-runtime-macos-arm64.json
${{ runner.temp }}/preflight.json
${{ runner.temp }}/prospective-base.diff
${{ runner.temp }}/target-context.txt
name: native-runtime-macos-arm64-${{ github.run_id }}
path: ${{ runner.temp }}/native-runtime-macos-arm64.json
if-no-files-found: warn
retention-days: 14
8 changes: 8 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,11 @@ custom/*

data/*
!data/model-artifact-catalog.json
!data/cosmos-safety-artifacts.v1.json
!data/cosmos-safety-runtime-artifacts.v1.json
!data/cosmos3-super-t2i-files.v1.json
!data/cosmos3-super-t2i-publisher-caption.v1.json
!data/cosmos3-super-t2i-publisher-caption-provenance.v1.json
!data/image-prototyping-readiness.v1.json
!data/huggingface-cluster-promotion-receipts.v1.json
!data/huggingface-cluster-promotion-receipts.v2.json
Expand Down Expand Up @@ -101,3 +106,6 @@ __pycache__
*.njsproj
*.sln
*.sw?

# Static upstream catalog source used only by backend CI audits.
.reviewed-upstream/
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,14 @@ These rules apply to AI-assisted work in this repository. `CONTRIBUTING.md` is t
- MoDiff may execute models through an official library maintained and published by Hugging Face. A Hub repository, organization name, or compatible API is not enough: verify the library's upstream ownership and package provenance, then declare and review the exact integration in MoDiff's executable dependency contract.
- All supported libraries run locally behind MoDiff's existing node graph, resource management, Auto/Expert, file, and security boundaries. Do not add an alternate graph executor, hosted inference provider, browser-side runtime, or library-owned workflow representation.
- Keep nodes and client contracts task- or modality-generic. Library- and model-specific loading, parameter aliases, and output normalization belong in small backend adapters selected from a declared execution specification, not new model-named nodes or frontend branches.
- Transformers is an optional runtime, not a default application dependency. Do not install it during startup, registry discovery, template browsing/opening, or Auto planning. A workflow that requires it must declare a reviewed optional runtime profile, present an explicit install/consent action, and verify the installed version before becoming runnable.
- Transformers and PEFT are required application dependencies installed by ordinary setup. Keep their heavyweight imports lazy and verify base-runtime readiness without optional installation or activation. Startup, registry discovery, template browsing, and Auto planning must never install packages. Additional optional runtimes still require an explicit install action and version verification.
- Ordinary deterministic media processing is allowed when narrowly scoped, documented, and covered by tests.
- Never enable arbitrary remote Python code, mutable model revisions, or custom model execution implicitly. Trust-sensitive behavior requires an explicit operator choice and an immutable revision.
- Prefer existing module, graph, configuration, error, and test patterns. Do not create a parallel workflow representation or model-loading path.

## Hugging Face Model Libraries

- Keep the reviewed Diffusers revision pinned in the executable installation contract and update its compatibility test when changing it.
- Declare the reviewed Diffusers minimum in the executable installation contract and record the tested stable resolution in `uv.lock`. Keep immutable upstream catalog provenance separate from the installed distribution identity; update no-download compatibility tests and source-generated contracts when changing either.
- Treat support for each additional official Hugging Face library as an explicit integration: document its purpose and provenance, constrain its compatible version, keep heavyweight imports lazy, and add no-download compatibility and boundary tests.
- Official-library eligibility is not blanket trust for Hub artifacts or repository code. Prefer `safetensors`; pin curated models and adapters immutably; and require a separate explicit operator decision for any reviewed remote-code path.
- Use Diffusers loaders, pipelines, components, schedulers, adapters, and offload hooks instead of reimplementing upstream behavior.
Expand Down
59 changes: 44 additions & 15 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,54 @@ integrating another machine's work, read and follow

For script-free `uv`/`npm` setup, use [Developer setup](docs/developer-setup.md).

Use Python 3.12 and create the same managed CPU profile used by baseline CI:
Use Python 3.12 and the native CPU profile used by baseline CI:

```bash
./install.sh --accelerator cpu --backend-only
```text
uv sync --extra cpu
uv pip install --python .venv/bin/python -r requirements/test.txt
./scripts/with-runtime-env.sh ./.venv/bin/python -m modiff.preflight --json --check-port 8088 --fail-on-error
uv run --extra cpu python -m modiff.preflight --json --check-port 8088 --fail-on-error
```

On Windows PowerShell, use the corresponding managed commands:
On Windows, use `.venv/Scripts/python.exe` in explicit `uv pip --python` commands.
For NVIDIA choose `--extra cuda`, for Intel `--extra xpu`, and on Apple Silicon
omit the accelerator extra. Use the same extra for sync and run. Keep specialized
AMD environments on their reviewed direct-wheel profile and use
`./scripts/with-runtime-env.sh` there; a generic CPU sync would replace their
Torch stack. Report hardware-specific validation separately.

```powershell
.\install.ps1 -Accelerator cpu -BackendOnly
uv pip install --python .venv/Scripts/python.exe -r requirements/test.txt
.\.venv\Scripts\python.exe -m modiff.preflight --json --check-port 8088 --fail-on-error
```
Do not commit `config.ini`, `.env` files, model caches, generated outputs, local logs, virtual environments, or test caches.

Choose the qualified accelerator profile relevant to a hardware-specific change and report that validation separately. Do not use `uv sync` or ordinary `uv run` (the documented `uv run --no-project --no-sync ... -m modiff.dev` bootstrap is the explicit exception): the project is intentionally `uv`-unmanaged because the installer, not the generic resolver, owns the executable Torch profile.
## Historical source-audit fixture

Ordinary setup, startup, preflight and the tiny runtime/LoRA smoke use the
installed compatible Diffusers release. They require no upstream checkout.
Static catalog reproduction tests separately inspect the immutable revision
recorded in `data/modular-workflow-contracts.json`. Backend CI fetches that exact
official source into the ignored `.reviewed-upstream/` directory and sets
`MODIFF_DIFFUSERS_CATALOG_SOURCE` only for those checks. Ordinary runtime and
pytest imports keep the installed release. The three dynamic no-weight Modular
catalog CLIs alone launch a private audit child that imports the byte-verified
historical package, verifies its origin and version, and disables operator
config, credentials, custom extensions and downloads. It never installs that
source or changes the parent import path.

For a full local source-audit gate, obtain the same fixture outside the backend
checkout and set its package path. In a POSIX shell:

```sh
git init ../reviewed-upstream-diffusers
git -C ../reviewed-upstream-diffusers remote add origin https://github.com/huggingface/diffusers.git
git -C ../reviewed-upstream-diffusers fetch --depth=1 origin fbf49e7f35857f76bc57b177e26f12b03687c668
git -C ../reviewed-upstream-diffusers -c core.autocrlf=false checkout --detach FETCH_HEAD
export MODIFF_DIFFUSERS_CATALOG_SOURCE="$(cd ../reviewed-upstream-diffusers/src/diffusers && pwd)"
```

Do not commit `config.ini`, `.env` files, model caches, generated outputs, local logs, virtual environments, or test caches.
On PowerShell, set `$env:MODIFF_DIFFUSERS_CATALOG_SOURCE` to the resolved package
path after the same Git steps. Regenerators verify the source revision and reject
an unavailable or different checkout. They preserve the historical catalog
revision and source hashes, while recording the current base-runtime dependency
contract separately. Updating catalog provenance is a separate reviewed change;
it must classify added and removed exports before regenerating contracts.

## Backend conventions

Expand Down Expand Up @@ -66,18 +95,18 @@ Add focused tests for registry visibility, constructor safety, field contracts,

## Dependency changes

The selected file under `requirements/profiles/`, `pyproject.toml`, and `modiff/compatibility/accelerators.v1.json` jointly define the executable runtime contract. Keep direct wheel URLs hash-verified, keep remote source dependencies pinned to immutable revisions, and retain the exact reviewed Diffusers commit. After an intentional dependency or profile edit, rebuild the relevant managed profile:
The selected file under `requirements/profiles/`, `pyproject.toml`, and `modiff/compatibility/accelerators.v1.json` jointly define the executable runtime contract. Keep direct wheel URLs hash-verified, keep remote source dependencies pinned to immutable revisions, and keep the ordinary Diffusers minimum plus its tested stable lock resolution. Immutable catalog-source provenance describes inspected upstream code; runtime binding describes the distribution actually installed. A normal published wheel needs no Git checkout receipt. After an intentional dependency or profile edit, rebuild the relevant managed profile:

```bash
./install.sh --accelerator cpu --backend-only --repair
uv pip check --python .venv/bin/python
```

Use the corresponding accelerator instead of `cpu` when the change affects CUDA, ROCm, or MPS. Update the compatibility manifest and public installation guidance only when the evidence supports the claim. MoDiff deliberately has no `uv.lock`; do not generate one or describe the top-level requirements files as a cross-platform lock.
For native profiles, update the committed `uv.lock` using `uv lock --upgrade-package <package>` and sync the same accelerator extra. The lock records a reproducible resolution; it does not require exact pins for ordinary libraries. Retain immutable sources and compiled wheel/ABI constraints where the integration needs them. Use the corresponding accelerator when a change affects CUDA, ROCm, XPU, or MPS. Update compatibility claims only when validation supports them.

MoDiff may integrate model libraries officially maintained and published by Hugging Face, but each library remains a separately reviewed execution dependency. Verify its upstream ownership, package provenance, license, supported version, loading behavior, and remote-code boundary. Hub hosting alone does not establish that a library or model is maintained by Hugging Face. Keep execution in the existing backend graph and expose task-generic contracts to the client.

Transformers-specific execution is opt-in. Do not add Transformers to the base application environment or install an optional runtime merely because a template is viewed, nodes are discovered, or Auto compatibility is planned. A requiring workflow must identify its versioned optional runtime, show an explicit install/consent action, perform installation outside graph execution, and re-run package and compatibility checks before the workflow can run.
Transformers and PEFT are required base dependencies. Verify ordinary image and LoRA readiness after setup without optional installation or activation. Keep imports lazy. Viewing a template, discovering nodes, or planning Auto must never install packages. Additional optional runtimes require an explicit install action outside graph execution and compatibility verification.

## Validation

Expand Down
Loading
Loading