fix: show Prune button whenever terminal install jobs exist

Previously the Prune button was only shown prominently when ALL jobs
were terminal (no active/cancelable jobs). Now it shows whenever at
least one terminal job exists, even alongside in-progress jobs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitattributes

@@ -4,3 +4,4 @@
 * text=auto
 docker/** text eol=lf
 tests/test_model_probe/stripped_models/** filter=lfs diff=lfs merge=lfs -text
+tests/model_identification/stripped_models/** filter=lfs diff=lfs merge=lfs -text

.github/CODEOWNERS

@@ -1,31 +1,32 @@
 # continuous integration
-/.github/workflows/  @lstein @blessedcoolant @hipsterusername @ebr @jazzhaiku @psychedelicious
+/.github/workflows/  @lstein @blessedcoolant  
 
-# documentation
-/docs/ @lstein @blessedcoolant @hipsterusername @psychedelicious
-/mkdocs.yml @lstein @blessedcoolant @hipsterusername @psychedelicious
+# documentation - anyone with write privileges can review
+/docs/
+/mkdocs.yml
 
 # nodes
-/invokeai/app/ @blessedcoolant @psychedelicious @hipsterusername @jazzhaiku
+/invokeai/app/ @blessedcoolant @lstein @dunkeroni @JPPhoto
 
 # installation and configuration
-/pyproject.toml  @lstein @blessedcoolant @psychedelicious @hipsterusername
-/docker/  @lstein @blessedcoolant @psychedelicious @hipsterusername @ebr
-/scripts/ @ebr @lstein @psychedelicious @hipsterusername
-/installer/ @lstein @ebr @psychedelicious @hipsterusername
-/invokeai/assets @lstein @ebr @psychedelicious @hipsterusername
-/invokeai/configs @lstein @psychedelicious @hipsterusername
-/invokeai/version @lstein @blessedcoolant @psychedelicious @hipsterusername
+/pyproject.toml  @lstein @blessedcoolant  
+/docker/  @lstein @blessedcoolant
+/scripts/  @lstein  @blessedcoolant  
+/installer/ @lstein   @blessedcoolant  
+/invokeai/assets @lstein   @blessedcoolant  
+/invokeai/configs @lstein  @blessedcoolant  
+/invokeai/version @lstein @blessedcoolant  
 
 # web ui
-/invokeai/frontend @blessedcoolant @psychedelicious @lstein @maryhipp @hipsterusername
+/invokeai/frontend @blessedcoolant  @lstein  @dunkeroni  
 
 # generation, model management, postprocessing
-/invokeai/backend  @lstein @blessedcoolant @hipsterusername @jazzhaiku @psychedelicious @maryhipp 
+/invokeai/backend  @lstein @blessedcoolant @dunkeroni @JPPhoto  @Pfannkuchensack 
 
 # front ends
-/invokeai/frontend/CLI @lstein @psychedelicious @hipsterusername
-/invokeai/frontend/install @lstein @ebr @psychedelicious @hipsterusername
-/invokeai/frontend/merge @lstein @blessedcoolant @psychedelicious @hipsterusername
-/invokeai/frontend/training @lstein @blessedcoolant @psychedelicious @hipsterusername
-/invokeai/frontend/web @psychedelicious @blessedcoolant @maryhipp @hipsterusername
+/invokeai/frontend/CLI @lstein  
+/invokeai/frontend/install @lstein   
+/invokeai/frontend/merge @lstein @blessedcoolant  
+/invokeai/frontend/training @lstein @blessedcoolant  
+/invokeai/frontend/web  @blessedcoolant  @lstein @dunkeroni @Pfannkuchensack 
+

.github/ISSUE_TEMPLATE/BUG_REPORT.yml

@@ -21,6 +21,20 @@ body:
         - label: I have searched the existing issues
           required: true
 
+  - type: dropdown
+    id: install_method
+    attributes:
+      label: Install method
+      description: How did you install Invoke?
+      multiple: false
+      options:
+        - "Invoke's Launcher"
+        - 'Stability Matrix'
+        - 'Pinokio'
+        - 'Manual'
+    validations:
+      required: true
+
   - type: markdown
     attributes:
       value: __Describe your environment__
@@ -76,8 +90,8 @@ body:
     attributes:
       label: Version number
       description: |
-        The version of Invoke you have installed. If it is not the latest version, please update and try again to confirm the issue still exists. If you are testing main, please include the commit hash instead.
-      placeholder: ex. 3.6.1
+        The version of Invoke you have installed. If it is not the [latest version](https://github.com/invoke-ai/InvokeAI/releases/latest), please update and try again to confirm the issue still exists. If you are testing main, please include the commit hash instead.
+      placeholder: ex. v6.0.2
     validations:
       required: true
 
@@ -85,17 +99,17 @@ body:
     id: browser-version
     attributes:
       label: Browser
-      description: Your web browser and version.
+      description: Your web browser and version, if you do not use the Launcher's provided GUI.
       placeholder: ex. Firefox 123.0b3
     validations:
-      required: true
+      required: false
 
   - type: textarea
     id: python-deps
     attributes:
-      label: Python dependencies
+      label: System Information
       description: |
-        If the problem occurred during image generation, click the gear icon at the bottom left corner, click "About", click the copy button and then paste here.
+        Click the gear icon at the bottom left corner, then click "About". Click the copy button and then paste here.
     validations:
       required: false
 

.github/pull_request_template.md

@@ -18,5 +18,6 @@
 
 - [ ] _The PR has a short but descriptive title, suitable for a changelog_
 - [ ] _Tests added / updated (if applicable)_
+- [ ] _❗Changes to a redux slice have a corresponding migration_
 - [ ] _Documentation added / updated (if applicable)_
 - [ ] _Updated `What's New` copy (if doing a release after this PR)_

.github/workflows/build-container.yml

@@ -45,13 +45,23 @@ jobs:
     steps:
       - name: Free up more disk space on the runner
         # https://github.com/actions/runner-images/issues/2840#issuecomment-1284059930
+        # the /mnt dir has 70GBs of free space
+        # /dev/sda1        74G   28K   70G   1% /mnt
+        # According to some online posts the /mnt is not always there, so checking before setting docker to use it
         run: |
           echo "----- Free space before cleanup"
           df -h
           sudo rm -rf /usr/share/dotnet
           sudo rm -rf "$AGENT_TOOLSDIRECTORY"
-          sudo swapoff /mnt/swapfile
-          sudo rm -rf /mnt/swapfile
+          if [ -f /mnt/swapfile ]; then
+            sudo swapoff /mnt/swapfile
+            sudo rm -rf /mnt/swapfile
+          fi
+          if [ -d /mnt ]; then
+            sudo chmod -R 777 /mnt
+            echo '{"data-root": "/mnt/docker-root"}' | sudo tee /etc/docker/daemon.json
+            sudo systemctl restart docker
+          fi
           echo "----- Free space after cleanup"
           df -h
 

.github/workflows/close-inactive-issues.yml

@@ -23,6 +23,7 @@ jobs:
           close-issue-message: "Due to inactivity, this issue was automatically closed. If you are still experiencing the issue, please recreate the issue."
           days-before-pr-stale: -1
           days-before-pr-close: -1
+          only-labels: "bug"
           exempt-issue-labels: "Active Issue"
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           operations-per-run: 500

.github/workflows/lfs-checks.yml

@@ -0,0 +1,30 @@
+# Checks that large files and LFS-tracked files are properly checked in with pointer format.
+# Uses https://github.com/ppremk/lfs-warning to detect LFS issues.
+
+name: 'lfs checks'
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    types:
+      - 'ready_for_review'
+      - 'opened'
+      - 'synchronize'
+  merge_group:
+  workflow_dispatch:
+
+jobs:
+  lfs-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      # Required to label and comment on the PRs
+      pull-requests: write
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: check lfs files
+        uses: ppremk/lfs-warning@v3.3

.github/workflows/mkdocs-material.yml

@@ -22,12 +22,12 @@ jobs:
 
     steps:
       - name: checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: setup python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.10'
+          python-version: '3.12'
           cache: pip
           cache-dependency-path: pyproject.toml
 

.github/workflows/typegen-checks.yml

@@ -39,6 +39,20 @@ jobs:
       - name: checkout
         uses: actions/checkout@v4
 
+      - name: Free up more disk space on the runner
+        # https://github.com/actions/runner-images/issues/2840#issuecomment-1284059930
+        run: |
+          echo "----- Free space before cleanup"
+          df -h
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+          if [ -f /mnt/swapfile ]; then
+            sudo swapoff /mnt/swapfile
+            sudo rm -rf /mnt/swapfile
+          fi
+          echo "----- Free space after cleanup"
+          df -h
+
       - name: check for changed files
         if: ${{ inputs.always_run != true }}
         id: changed-files

.gitignore

@@ -190,3 +190,8 @@ installer/update.bat
 installer/update.sh
 installer/InvokeAI-Installer/
 .aider*
+
+.claude/
+
+# Weblate configuration file
+weblate.ini

Makefile

@@ -16,20 +16,20 @@ help:
 	@echo "frontend-build           Build the frontend in order to run on localhost:9090"
 	@echo "frontend-dev             Run the frontend in developer mode on localhost:5173"
 	@echo "frontend-typegen         Generate types for the frontend from the OpenAPI schema"
-	@echo "wheel            				Build the wheel for the current version"
+	@echo "frontend-prettier        Format the frontend using lint:prettier"
+	@echo "wheel            	Build the wheel for the current version"
 	@echo "tag-release              Tag the GitHub repository with the current version (use at release time only!)"
 	@echo "openapi                  Generate the OpenAPI schema for the app, outputting to stdout"
 	@echo "docs                     Serve the mkdocs site with live reload"
 
 # Runs ruff, fixing any safely-fixable errors and formatting
 ruff:
-	ruff check . --fix
-	ruff format .
+	cd invokeai && uv tool run ruff@0.11.2 format
 
 # Runs ruff, fixing all errors it can fix and formatting
 ruff-unsafe:
 	ruff check . --fix --unsafe-fixes
-	ruff format .
+	ruff format
 
 # Runs mypy, using the config in pyproject.toml
 mypy:
@@ -64,6 +64,13 @@ frontend-dev:
 frontend-typegen:
 	cd invokeai/frontend/web && python ../../../scripts/generate_openapi_schema.py | pnpm typegen
 
+frontend-lint:
+	cd invokeai/frontend/web/src && \
+	pnpm lint:tsc && \
+	pnpm lint:dpdm && \
+	pnpm lint:eslint --fix && \
+	pnpm lint:prettier --write 
+
 # Tag the release
 wheel:
 	cd scripts && ./build_wheel.sh
@@ -79,4 +86,4 @@ openapi:
 # Serve the mkdocs site w/ live reload
 .PHONY: docs
 docs:
-	mkdocs serve
+	mkdocs serve

README.md

@@ -4,38 +4,33 @@
 
 # Invoke - Professional Creative AI Tools for Visual Media
 
-#### To learn more about Invoke, or implement our Business solutions, visit [invoke.com]
-
 [![discord badge]][discord link] [![latest release badge]][latest release link] [![github stars badge]][github stars link] [![github forks badge]][github forks link] [![CI checks on main badge]][CI checks on main link] [![latest commit to main badge]][latest commit to main link] [![github open issues badge]][github open issues link] [![github open prs badge]][github open prs link] [![translation status badge]][translation status link]
 
 </div>
 
 Invoke is a leading creative engine built to empower professionals and enthusiasts alike. Generate and create stunning visual media using the latest AI-driven technologies. Invoke offers an industry leading web-based UI, and serves as the foundation for multiple commercial products.
 
-Invoke is available in two editions:
-
-| **Community Edition**                                                                                                      | **Professional Edition**                                                                            |
-|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
-| **For users looking for a locally installed, self-hosted and self-managed service**                                         | **For users or teams looking for a cloud-hosted, fully managed service**                            |
-| - Free to use under a commercially-friendly license                                                                         | - Monthly subscription fee with three different plan levels                                         |
-| - Download and install on compatible hardware                                                                               | - Offers additional benefits, including multi-user support, improved model training, and more                          |
-| - Includes all core studio features: generate, refine, iterate on images, and build workflows                               | - Hosted in the cloud for easy, secure model access and scalability                                               |
-| Quick Start -> [Installation and Updates][installation docs]                                                                     | More Information -> [www.invoke.com/pricing](https://www.invoke.com/pricing)                        |
-
+- Free to use under a commercially-friendly license
+- Download and install on compatible hardware
+- Generate, refine, iterate on images, and build workflows
 
 ![Highlighted Features - Canvas and Workflows](https://github.com/invoke-ai/InvokeAI/assets/31807370/708f7a82-084f-4860-bfbe-e2588c53548d)
 
+---
+> ## 📣 Are you a new or returning InvokeAI user?
+> Take our first annual [User's Survey](https://forms.gle/rCE5KuQ7Wfrd1UnS7)
+
+---
+
 # Documentation
-| **Quick Links**                                                                                                      | 
-|----------------------------------------------------------------------------------------------------------------------------|
-|  [Installation and Updates][installation docs] - [Documentation and Tutorials][docs home] - [Bug Reports][github issues] - [Contributing][contributing docs]  | 
+
+| **Quick Links**                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Installation and Updates][installation docs] - [Documentation and Tutorials][docs home] - [Bug Reports][github issues] - [Contributing][contributing docs] |
 
 # Installation
 
-To get started with Invoke, [Download the Installer](https://www.invoke.com/downloads).
-
-For detailed step by step instructions, or for instructions on manual/docker installations, visit our documentation on [Installation and Updates][installation docs]
-
+To get started with Invoke, [Download the Launcher](https://github.com/invoke-ai/launcher/releases/latest).
 
 ## Troubleshooting, FAQ and Support
 
@@ -57,7 +52,7 @@ The Unified Canvas is a fully integrated canvas implementation with support for
 
 ### Workflows & Nodes
 
-Invoke offers a fully featured workflow management solution, enabling users to combine the power of node-based workflows with the easy of a UI. This allows for customizable generation pipelines to be developed and shared by users looking to create specific workflows to support their production use-cases.
+Invoke offers a fully featured workflow management solution, enabling users to combine the power of node-based workflows with the ease of a UI. This allows for customizable generation pipelines to be developed and shared by users looking to create specific workflows to support their production use-cases.
 
 ### Board & Gallery Management
 
@@ -90,7 +85,6 @@ Original portions of the software are Copyright © 2024 by respective contributo
 [features docs]: https://invoke-ai.github.io/InvokeAI/features/database/
 [faq]: https://invoke-ai.github.io/InvokeAI/faq/
 [contributors]: https://invoke-ai.github.io/InvokeAI/contributing/contributors/
-[invoke.com]: https://www.invoke.com/about
 [github issues]: https://github.com/invoke-ai/InvokeAI/issues
 [docs home]: https://invoke-ai.github.io/InvokeAI
 [installation docs]: https://invoke-ai.github.io/InvokeAI/installation/

USER_ISOLATION_IMPLEMENTATION.md

@@ -0,0 +1,169 @@
+# User Isolation Implementation Summary
+
+This document describes the implementation of user isolation features in the InvokeAI session queue and processing system to address issues identified in the enhancement request.
+
+## Issues Addressed
+
+### 1. Cross-User Image/Preview Visibility
+**Problem:** When two users are logged in simultaneously and one initiates a generation, the generation preview shows up in both users' browsers and the generated image gets saved to both users' image boards.
+
+**Solution:** Implemented socket-level event filtering based on user authentication:
+
+#### Backend Changes (`invokeai/app/api/sockets.py`):
+- Added socket authentication middleware in `_handle_connect()` method
+- Extracts JWT token from socket auth data or HTTP headers
+- Verifies token using existing `verify_token()` function
+- Stores `user_id` and `is_admin` in socket session for later use
+- Modified `_handle_queue_event()` to filter events by user:
+  - For `QueueItemEventBase` events, only emit to:
+    - The user who owns the queue item (`user_id` matches)
+    - Admin users (`is_admin` is True)
+  - For general queue events, emit to all subscribers
+
+#### Event System Changes (`invokeai/app/services/events/events_common.py`):
+- Added `user_id` field to `QueueItemEventBase` class
+- Updated all event builders to include `user_id` from queue items:
+  - `InvocationStartedEvent.build()`
+  - `InvocationProgressEvent.build()`
+  - `InvocationCompleteEvent.build()`
+  - `InvocationErrorEvent.build()`
+  - `QueueItemStatusChangedEvent.build()`
+
+### 2. Batch Field Values Privacy
+**Problem:** Users can see batch field values from generation processes launched by other users.
+
+**Solution:** Implemented field value sanitization at the API level:
+
+#### API Router Changes (`invokeai/app/api/routers/session_queue.py`):
+- Created `sanitize_queue_item_for_user()` helper function
+  - Clears `field_values` for non-admin users viewing other users' items
+  - Admins and item owners can see all field values
+- Updated endpoints to require authentication and sanitize responses:
+  - `list_all_queue_items()` - Added `CurrentUser` dependency
+  - `get_queue_items_by_item_ids()` - Added `CurrentUser` dependency
+  - `get_queue_item()` - Added `CurrentUser` dependency
+
+### 3. Queue Updates Across Browser Windows
+**Problem:** When the job queue tab is open in multiple browsers and a generation is begun in one browser window, the queue does not update in the other window.
+
+**Status:** This issue is likely resolved by the socket authentication and event filtering changes. The existing socket subscription mechanism (`subscribe_queue` event) already supports multiple connections per user. Testing is required to confirm this works correctly with the new authentication flow.
+
+### 4. User Information Display
+**Problem:** Queue table lacks user identification, making it difficult to know who launched which job.
+
+**Solution:** Added user information to queue items and UI:
+
+#### Database Layer (`invokeai/app/services/session_queue/session_queue_sqlite.py`):
+- Updated SQL queries to JOIN with `users` table
+- Modified methods to fetch user information:
+  - `get_queue_item()` - Now selects `display_name` and `email` from users table
+  - `dequeue()` - Includes user info
+  - `get_next()` - Includes user info
+  - `get_current()` - Includes user info
+  - `list_all_queue_items()` - Includes user info
+
+#### Data Model Changes (`invokeai/app/services/session_queue/session_queue_common.py`):
+- Added optional fields to `SessionQueueItem`:
+  - `user_display_name: Optional[str]` - Display name from users table
+  - `user_email: Optional[str]` - Email from users table
+  - Note: `user_id` field already existed from Migration 25
+
+#### Frontend UI Changes:
+- **Constants** (`constants.ts`): Added `user: '8rem'` column width
+- **Header** (`QueueListHeader.tsx`): Added "User" column header
+- **Item Component** (`QueueItemComponent.tsx`):
+  - Added logic to display user information (display_name → email → user_id)
+  - Added user column to queue item row
+  - Added tooltip with full username on hover
+  - Added "Hidden for privacy" message when field_values are null for non-owned items
+- **Localization** (`en.json`): Added translations:
+  - `"user": "User"`
+  - `"fieldValuesHidden": "Hidden for privacy"`
+
+## Security Considerations
+
+### Token Verification
+- Tokens are verified using the existing `verify_token()` function from `invokeai.app.services.auth.token_service`
+- Invalid or missing tokens default to "system" user with non-admin privileges
+- Socket connections without valid tokens are still accepted for backward compatibility but have limited access
+
+### Data Privacy
+- Field values are only visible to:
+  - The user who created the queue item
+  - Admin users
+- Non-admin users viewing other users' queue items see "Hidden for privacy" instead of field values
+
+### Admin Privileges
+- Admin users can see all queue events and field values across all users
+- Admin status is determined from the JWT token's `is_admin` field
+
+## Migration Notes
+
+No database migration is required. The changes leverage:
+- Existing `user_id` column in `session_queue` table (added in Migration 25)
+- Existing `users` table (added in Migration 25)
+- SQL LEFT JOINs to fetch user information (gracefully handles missing user records)
+
+## Testing Requirements
+
+### Backend Testing
+1. **Socket Authentication:**
+   - Verify valid tokens are accepted and user context is stored
+   - Verify invalid tokens default to system user
+   - Verify expired tokens are rejected
+
+2. **Event Filtering:**
+   - User A should only receive events for their own queue items
+   - Admin users should receive all events
+   - Non-admin users should not receive events from other users
+
+3. **Field Value Sanitization:**
+   - Non-admin users should see null field_values for other users' items
+   - Admins should see all field values
+   - Users should see their own field values
+
+### Frontend Testing
+1. **UI Display:**
+   - User column should display in queue list
+   - Display name should be shown when available
+   - Email should be shown as fallback when display name is missing
+   - User ID should be shown when both display name and email are missing
+   - Tooltip should show full username on hover
+
+2. **Field Values Display:**
+   - "Hidden for privacy" message should appear when viewing other users' items
+   - Own items should show field values normally
+
+3. **Multi-Browser Testing:**
+   - Open queue tab in two browsers with different users
+   - Start generation in one browser
+   - Verify other browser doesn't see the preview/progress
+   - Verify admin user can see all generations
+
+### Integration Testing
+1. Multi-user scenarios with simultaneous generations
+2. Queue updates across multiple browser windows
+3. Admin vs. non-admin privilege differentiation
+4. Socket reconnection handling
+
+## Known Limitations
+
+1. **TypeScript Types:**
+   - The OpenAPI schema needs to be regenerated to include new fields
+   - Run: `cd invokeai/frontend/web && python ../../../scripts/generate_openapi_schema.py | pnpm typegen`
+
+2. **Backward Compatibility:**
+   - System user ("system") entries will not have display name or email
+   - Existing queue items from before Migration 25 will have user_id="system"
+
+3. **Socket.IO Session Storage:**
+   - Socket.IO's in-memory session storage may not persist across server restarts
+   - Consider implementing persistent session storage if needed for production
+
+## Future Enhancements
+
+1. Add user filtering to queue list (show only my items vs. all items)
+2. Add permission system for queue management operations (cancel, retry, delete)
+3. Implement queue item ownership transfer for administrative purposes
+4. Add audit logging for queue operations with user attribution
+5. Consider implementing user-specific queue limits or quotas

docker/.env.sample

@@ -22,6 +22,10 @@
 ## GPU_DRIVER can be set to either `cuda` or `rocm` to enable GPU support in the container accordingly.
 # GPU_DRIVER=cuda #| rocm
 
+## If you are using ROCM, you will need to ensure that the render group within the container and the host system use the same group ID.
+## To obtain the group ID of the render group on the host system, run `getent group render` and grab the number.
+# RENDER_GROUP_ID=
+
 ## CONTAINER_UID can be set to the UID of the user on the host system that should own the files in the container.
 ## It is usually not necessary to change this. Use `id -u` on the host system to find the UID.
 # CONTAINER_UID=1000

docker/Dockerfile

@@ -5,8 +5,7 @@
 FROM docker.io/node:22-slim AS web-builder
 ENV PNPM_HOME="/pnpm"
 ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack use pnpm@8.x
-RUN corepack enable
+RUN corepack use pnpm@10.x && corepack enable
 
 WORKDIR /build
 COPY invokeai/frontend/web/ ./
@@ -44,7 +43,6 @@ ENV \
     UV_MANAGED_PYTHON=1 \
     UV_LINK_MODE=copy \
     UV_PROJECT_ENVIRONMENT=/opt/venv \
-    UV_INDEX="https://download.pytorch.org/whl/cu124" \
     INVOKEAI_ROOT=/invokeai \
     INVOKEAI_HOST=0.0.0.0 \
     INVOKEAI_PORT=9090 \
@@ -75,19 +73,17 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=bind,source=uv.lock,target=uv.lock \
     # this is just to get the package manager to recognize that the project exists, without making changes to the docker layer
     --mount=type=bind,source=invokeai/version,target=invokeai/version \
-    if [ "$TARGETPLATFORM" = "linux/arm64" ] || [ "$GPU_DRIVER" = "cpu" ]; then UV_INDEX="https://download.pytorch.org/whl/cpu"; \
-    elif [ "$GPU_DRIVER" = "rocm" ]; then UV_INDEX="https://download.pytorch.org/whl/rocm6.2"; \
-    fi && \
-    uv sync --frozen
-
-# build patchmatch
-RUN cd /usr/lib/$(uname -p)-linux-gnu/pkgconfig/ && ln -sf opencv4.pc opencv.pc
-RUN python -c "from patchmatch import patch_match"
+    ulimit -n 30000 && \
+    uv sync --extra $GPU_DRIVER --frozen
 
 # Link amdgpu.ids for ROCm builds
 # contributed by https://github.com/Rubonnek
 RUN mkdir -p "/opt/amdgpu/share/libdrm" &&\
-    ln -s "/usr/share/libdrm/amdgpu.ids" "/opt/amdgpu/share/libdrm/amdgpu.ids"
+    ln -s "/usr/share/libdrm/amdgpu.ids" "/opt/amdgpu/share/libdrm/amdgpu.ids" && groupadd render
+
+# build patchmatch
+RUN cd /usr/lib/$(uname -p)-linux-gnu/pkgconfig/ && ln -sf opencv4.pc opencv.pc
+RUN python -c "from patchmatch import patch_match"
 
 RUN mkdir -p ${INVOKEAI_ROOT} && chown -R ${CONTAINER_UID}:${CONTAINER_GID} ${INVOKEAI_ROOT}
 
@@ -106,8 +102,6 @@ COPY invokeai ${INVOKEAI_SRC}/invokeai
 RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
     --mount=type=bind,source=uv.lock,target=uv.lock \
-    if [ "$TARGETPLATFORM" = "linux/arm64" ] || [ "$GPU_DRIVER" = "cpu" ]; then UV_INDEX="https://download.pytorch.org/whl/cpu"; \
-    elif [ "$GPU_DRIVER" = "rocm" ]; then UV_INDEX="https://download.pytorch.org/whl/rocm6.2"; \
-    fi && \
-    uv pip install -e .
+    ulimit -n 30000 && \
+    uv pip install -e .[$GPU_DRIVER]
 

docker/Dockerfile-rocm-full

@@ -0,0 +1,136 @@
+# syntax=docker/dockerfile:1.4
+
+#### Web UI ------------------------------------
+
+FROM docker.io/node:22-slim AS web-builder
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack use pnpm@8.x
+RUN corepack enable
+
+WORKDIR /build
+COPY invokeai/frontend/web/ ./
+RUN --mount=type=cache,target=/pnpm/store \
+    pnpm install --frozen-lockfile
+RUN npx vite build
+
+## Backend ---------------------------------------
+
+FROM library/ubuntu:24.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+RUN rm -f /etc/apt/apt.conf.d/docker-clean; echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
+RUN --mount=type=cache,target=/var/cache/apt \
+    --mount=type=cache,target=/var/lib/apt \
+    apt update && apt install -y --no-install-recommends \
+    ca-certificates \
+    git \
+    gosu \
+    libglib2.0-0 \
+    libgl1 \
+    libglx-mesa0 \
+    build-essential \
+    libopencv-dev \
+    libstdc++-10-dev \
+    wget
+
+ENV \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    VIRTUAL_ENV=/opt/venv \
+    INVOKEAI_SRC=/opt/invokeai \
+    PYTHON_VERSION=3.12 \
+    UV_PYTHON=3.12 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_MANAGED_PYTHON=1 \
+    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT=/opt/venv \
+    INVOKEAI_ROOT=/invokeai \
+    INVOKEAI_HOST=0.0.0.0 \
+    INVOKEAI_PORT=9090 \
+    PATH="/opt/venv/bin:$PATH" \
+    CONTAINER_UID=${CONTAINER_UID:-1000} \
+    CONTAINER_GID=${CONTAINER_GID:-1000}
+
+ARG GPU_DRIVER=cuda
+
+# Install `uv` for package management
+COPY --from=ghcr.io/astral-sh/uv:0.6.9 /uv /uvx /bin/
+
+# Install python & allow non-root user to use it by traversing the /root dir without read permissions
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv python install ${PYTHON_VERSION} && \
+    # chmod --recursive a+rX /root/.local/share/uv/python
+    chmod 711 /root
+
+WORKDIR ${INVOKEAI_SRC}
+
+# Install project's dependencies as a separate layer so they aren't rebuilt every commit.
+# bind-mount instead of copy to defer adding sources to the image until next layer.
+#
+# NOTE: there are no pytorch builds for arm64 + cuda, only cpu
+# x86_64/CUDA is the default
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    # this is just to get the package manager to recognize that the project exists, without making changes to the docker layer
+    --mount=type=bind,source=invokeai/version,target=invokeai/version \
+    ulimit -n 30000 && \
+    uv sync --extra $GPU_DRIVER --frozen
+
+RUN --mount=type=cache,target=/var/cache/apt \
+    --mount=type=cache,target=/var/lib/apt \
+    if [ "$GPU_DRIVER" = "rocm" ]; then \
+    wget -O /tmp/amdgpu-install.deb \
+    https://repo.radeon.com/amdgpu-install/6.3.4/ubuntu/noble/amdgpu-install_6.3.60304-1_all.deb && \
+    apt install -y /tmp/amdgpu-install.deb && \
+    apt update && \
+    amdgpu-install --usecase=rocm -y && \
+    apt-get autoclean && \
+    apt clean && \
+    rm -rf /tmp/* /var/tmp/* && \
+    usermod -a -G render ubuntu && \
+    usermod -a -G video ubuntu && \
+    echo "\\n/opt/rocm/lib\\n/opt/rocm/lib64" >> /etc/ld.so.conf.d/rocm.conf && \
+    ldconfig && \
+    update-alternatives --auto rocm; \
+    fi
+
+## Heathen711: Leaving this for review input, will remove before merge
+# RUN --mount=type=cache,target=/var/cache/apt \
+#     --mount=type=cache,target=/var/lib/apt \
+#     if [ "$GPU_DRIVER" = "rocm" ]; then \
+#     groupadd render && \
+#     usermod -a -G render ubuntu && \
+#     usermod -a -G video ubuntu; \
+#     fi
+
+## Link amdgpu.ids for ROCm builds
+## contributed by https://github.com/Rubonnek
+# RUN mkdir -p "/opt/amdgpu/share/libdrm" &&\
+#     ln -s "/usr/share/libdrm/amdgpu.ids" "/opt/amdgpu/share/libdrm/amdgpu.ids"
+
+# build patchmatch
+RUN cd /usr/lib/$(uname -p)-linux-gnu/pkgconfig/ && ln -sf opencv4.pc opencv.pc
+RUN python -c "from patchmatch import patch_match"
+
+RUN mkdir -p ${INVOKEAI_ROOT} && chown -R ${CONTAINER_UID}:${CONTAINER_GID} ${INVOKEAI_ROOT}
+
+COPY docker/docker-entrypoint.sh ./
+ENTRYPOINT ["/opt/invokeai/docker-entrypoint.sh"]
+CMD ["invokeai-web"]
+
+# --link requires buldkit w/ dockerfile syntax 1.4, does not work with podman
+COPY --link --from=web-builder /build/dist ${INVOKEAI_SRC}/invokeai/frontend/web/dist
+
+# add sources last to minimize image changes on code changes
+COPY invokeai ${INVOKEAI_SRC}/invokeai
+
+# this should not increase image size because we've already installed dependencies
+# in a previous layer
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    ulimit -n 30000 && \
+    uv pip install -e .[$GPU_DRIVER]
+

docker/docker-compose.yml

@@ -47,8 +47,9 @@ services:
 
   invokeai-rocm:
     <<: *invokeai
-    devices:
-      - /dev/kfd:/dev/kfd
-      - /dev/dri:/dev/dri
+    environment:
+      - AMD_VISIBLE_DEVICES=all
+      - RENDER_GROUP_ID=${RENDER_GROUP_ID}
+    runtime: amd
     profiles:
       - rocm

docker/docker-entrypoint.sh

@@ -21,6 +21,17 @@ _=$(id ${USER} 2>&1) || useradd -u ${USER_ID} ${USER}
 # ensure the UID is correct
 usermod -u ${USER_ID} ${USER} 1>/dev/null
 
+## ROCM specific configuration
+# render group within the container must match the host render group
+# otherwise the container will not be able to access the host GPU.
+if [[ -v "RENDER_GROUP_ID" ]] && [[ ! -z "${RENDER_GROUP_ID}" ]]; then
+  # ensure the render group exists
+  groupmod -g ${RENDER_GROUP_ID} render
+  usermod -a -G render ${USER}
+  usermod -a -G video ${USER}
+fi
+
+
 ### Set the $PUBLIC_KEY env var to enable SSH access.
 # We do not install openssh-server in the image by default to avoid bloat.
 # but it is useful to have the full SSH server e.g. on Runpod.

docker/run.sh

@@ -13,7 +13,7 @@ run() {
 
   # parse .env file for build args
   build_args=$(awk '$1 ~ /=[^$]/ && $0 !~ /^#/ {print "--build-arg " $0 " "}' .env) &&
-  profile="$(awk -F '=' '/GPU_DRIVER/ {print $2}' .env)"
+  profile="$(awk -F '=' '/GPU_DRIVER=/ {print $2}' .env)"
 
   # default to 'cuda' profile
   [[ -z "$profile" ]] && profile="cuda"
@@ -30,7 +30,7 @@ run() {
 
   printf "%s\n" "starting service $service_name"
   docker compose --profile "$profile" up -d "$service_name"
-  docker compose logs -f
+  docker compose --profile "$profile" logs -f
 }
 
 run

docs/RELEASE.md

@@ -16,7 +16,9 @@ The launcher uses GitHub as the source of truth for available releases.
 
 ## General Prep
 
-Make a developer call-out for PRs to merge. Merge and test things out. Bump the version by editing `invokeai/version/invokeai_version.py`.
+Make a developer call-out for PRs to merge. Merge and test things
+out. Create a branch with a name like user/chore/vX.X.X-prep and bump the version by editing
+`invokeai/version/invokeai_version.py` and commit locally.
 
 ## Release Workflow
 
@@ -26,14 +28,14 @@ It is triggered on **tag push**, when the tag matches `v*`.
 
 ### Triggering the Workflow
 
-Ensure all commits that should be in the release are merged, and you have pulled them locally.
-
-Double-check that you have checked out the commit that will represent the release (typically the latest commit on `main`).
+Ensure all commits that should be in the release are merged into this branch, and that you have pulled them locally.
 
 Run `make tag-release` to tag the current commit and kick off the workflow. You will be prompted to provide a message - use the version specifier.
 
 If this version's tag already exists for some reason (maybe you had to make a last minute change), the script will overwrite it.
 
+Push the commit to trigger the workflow.
+
 > In case you cannot use the Make target, the release may also be dispatched [manually] via GH.
 
 ### Workflow Jobs and Process
@@ -89,7 +91,7 @@ The publish jobs will not run if any of the previous jobs fail.
 
 They use [GitHub environments], which are configured as [trusted publishers] on PyPI.
 
-Both jobs require a @hipsterusername or @psychedelicious to approve them from the workflow's **Summary** tab.
+Both jobs require a @lstein or @blessedcoolant to approve them from the workflow's **Summary** tab.
 
 - Click the **Review deployments** button
 - Select the environment (either `testpypi` or `pypi` - typically you select both)
@@ -101,7 +103,7 @@ Both jobs require a @hipsterusername or @psychedelicious to approve them from th
 
 Check the [python infrastructure status page] for incidents.
 
-If there are no incidents, contact @hipsterusername or @lstein, who have owner access to GH and PyPI, to see if access has expired or something like that.
+If there are no incidents, contact @lstein or @blessedcoolant, who have owner access to GH and PyPI, to see if access has expired or something like that.
 
 #### `publish-testpypi` Job
 

docs/contributing/HOTKEYS.md

@@ -0,0 +1,295 @@
+# Hotkeys System
+
+This document describes the technical implementation of the customizable hotkeys system in InvokeAI.
+
+> **Note:** For user-facing documentation on how to use customizable hotkeys, see [Hotkeys Feature Documentation](../features/hotkeys.md).
+
+## Overview
+
+The hotkeys system allows users to customize keyboard shortcuts throughout the application. All hotkeys are:
+- Centrally defined and managed
+- Customizable by users
+- Persisted across sessions
+- Type-safe and validated
+
+## Architecture
+
+The customizable hotkeys feature is built on top of the existing hotkey system with the following components:
+
+### 1. Hotkeys State Slice (`hotkeysSlice.ts`)
+
+Location: `invokeai/frontend/web/src/features/system/store/hotkeysSlice.ts`
+
+**Responsibilities:**
+- Stores custom hotkey mappings in Redux state
+- Persisted to IndexedDB using `redux-remember`
+- Provides actions to change, reset individual, or reset all hotkeys
+
+**State Shape:**
+```typescript
+{
+  _version: 1,
+  customHotkeys: {
+    'app.invoke': ['mod+enter'],
+    'canvas.undo': ['mod+z'],
+    // ...
+  }
+}
+```
+
+**Actions:**
+- `hotkeyChanged(id, hotkeys)` - Update a single hotkey
+- `hotkeyReset(id)` - Reset a single hotkey to default
+- `allHotkeysReset()` - Reset all hotkeys to defaults
+
+### 2. useHotkeyData Hook (`useHotkeyData.ts`)
+
+Location: `invokeai/frontend/web/src/features/system/components/HotkeysModal/useHotkeyData.ts`
+
+**Responsibilities:**
+- Defines all default hotkeys
+- Merges default hotkeys with custom hotkeys from the store
+- Returns the effective hotkeys that should be used throughout the app
+- Provides platform-specific key translations (Ctrl/Cmd, Alt/Option)
+
+**Key Functions:**
+- `useHotkeyData()` - Returns all hotkeys organized by category
+- `useRegisteredHotkeys()` - Hook to register a hotkey in a component
+
+### 3. HotkeyEditor Component (`HotkeyEditor.tsx`)
+
+Location: `invokeai/frontend/web/src/features/system/components/HotkeysModal/HotkeyEditor.tsx`
+
+**Features:**
+- Inline editor with input field
+- Modifier buttons (Mod, Ctrl, Shift, Alt) for quick insertion
+- Live preview of hotkey combinations
+- Validation with visual feedback
+- Help tooltip with syntax examples
+- Save/cancel/reset buttons
+
+**Smart Features:**
+- Automatic `+` insertion between modifiers
+- Cursor position preservation
+- Validation prevents invalid combinations (e.g., modifier-only keys)
+
+### 4. HotkeysModal Component (`HotkeysModal.tsx`)
+
+Location: `invokeai/frontend/web/src/features/system/components/HotkeysModal/HotkeysModal.tsx`
+
+**Features:**
+- View Mode / Edit Mode toggle
+- Search functionality
+- Category-based organization
+- Shows HotkeyEditor components when in edit mode
+- "Reset All to Default" button in edit mode
+
+## Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. User opens Hotkeys Modal                                 │
+│ 2. User clicks "Edit Mode" button                           │
+│ 3. User clicks edit icon next to a hotkey                   │
+│ 4. User enters new hotkey(s) using editor                   │
+│ 5. User clicks save or presses Enter                        │
+│ 6. Custom hotkey stored via hotkeyChanged() action          │
+│ 7. Redux state persisted to IndexedDB (redux-remember)      │
+│ 8. useHotkeyData() hook picks up the change                 │
+│ 9. All components using useRegisteredHotkeys() get update   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Hotkey Format
+
+Hotkeys use the format from `react-hotkeys-hook` library:
+
+- **Modifiers:** `mod`, `ctrl`, `shift`, `alt`, `meta`
+- **Keys:** Letters, numbers, function keys, special keys
+- **Separator:** `+` between keys in a combination
+- **Multiple hotkeys:** Comma-separated (e.g., `mod+a, ctrl+b`)
+
+**Examples:**
+- `mod+enter` - Mod key + Enter
+- `shift+x` - Shift + X
+- `ctrl+shift+a` - Control + Shift + A
+- `f1, f2` - F1 or F2 (alternatives)
+
+## Developer Guide
+
+### Using Hotkeys in Components
+
+To use a hotkey in a component:
+
+```tsx
+import { useRegisteredHotkeys } from 'features/system/components/HotkeysModal/useHotkeyData';
+
+const MyComponent = () => {
+  const handleAction = useCallback(() => {
+    // Your action here
+  }, []);
+
+  // This automatically uses custom hotkeys if configured
+  useRegisteredHotkeys({
+    id: 'myAction',
+    category: 'app', // or 'canvas', 'viewer', 'gallery', 'workflows'
+    callback: handleAction,
+    options: { enabled: true, preventDefault: true },
+    dependencies: [handleAction]
+  });
+
+  // ...
+};
+```
+
+**Options:**
+- `enabled` - Whether the hotkey is active
+- `preventDefault` - Prevent default browser behavior
+- `enableOnFormTags` - Allow hotkey in form elements (default: false)
+
+### Adding New Hotkeys
+
+To add a new hotkey to the system:
+
+#### 1. Add Translation Strings
+
+In `invokeai/frontend/web/public/locales/en.json`:
+
+```json
+{
+  "hotkeys": {
+    "app": {
+      "myAction": {
+        "title": "My Action",
+        "desc": "Description of what this hotkey does"
+      }
+    }
+  }
+}
+```
+
+#### 2. Register the Hotkey
+
+In `invokeai/frontend/web/src/features/system/components/HotkeysModal/useHotkeyData.ts`:
+
+```typescript
+// Inside the appropriate category builder function
+addHotkey('app', 'myAction', ['mod+k']); // Default binding
+```
+
+#### 3. Use the Hotkey
+
+In your component:
+
+```typescript
+useRegisteredHotkeys({
+  id: 'myAction',
+  category: 'app',
+  callback: handleMyAction,
+  options: { enabled: true },
+  dependencies: [handleMyAction]
+});
+```
+
+### Hotkey Categories
+
+Current categories:
+- **app** - Global application hotkeys
+- **canvas** - Canvas/drawing operations
+- **viewer** - Image viewer operations
+- **gallery** - Gallery/image grid operations
+- **workflows** - Node workflow editor
+
+To add a new category, update `useHotkeyData.ts` and add translations.
+
+## Testing
+
+Tests are located in `invokeai/frontend/web/src/features/system/store/hotkeysSlice.test.ts`.
+
+**Test Coverage:**
+- Adding custom hotkeys
+- Updating existing custom hotkeys
+- Resetting individual hotkeys
+- Resetting all hotkeys
+- State persistence and migration
+
+Run tests with:
+
+```bash
+cd invokeai/frontend/web
+pnpm test:no-watch
+```
+
+## Persistence
+
+Custom hotkeys are persisted using the same mechanism as other app settings:
+
+- Stored in Redux state under the `hotkeys` slice
+- Persisted to IndexedDB via `redux-remember`
+- Automatically loaded when the app starts
+- Survives page refreshes and browser restarts
+- Includes migration support for state schema changes
+
+**State Location:**
+- IndexedDB database: `invoke`
+- Store key: `hotkeys`
+
+## Dependencies
+
+- **react-hotkeys-hook** (v4.5.0) - Core hotkey handling
+- **@reduxjs/toolkit** - State management
+- **redux-remember** - Persistence
+- **zod** - State validation
+
+## Best Practices
+
+1. **Use `mod` instead of `ctrl`** - Automatically maps to Cmd on Mac, Ctrl elsewhere
+2. **Provide descriptive translations** - Help users understand what each hotkey does
+3. **Avoid conflicts** - Check existing hotkeys before adding new ones
+4. **Use preventDefault** - Prevent browser default behavior when appropriate
+5. **Check enabled state** - Only activate hotkeys when the action is available
+6. **Use dependencies correctly** - Ensure callbacks are stable with useCallback
+
+## Common Patterns
+
+### Conditional Hotkeys
+
+```typescript
+useRegisteredHotkeys({
+  id: 'save',
+  category: 'app',
+  callback: handleSave,
+  options: {
+    enabled: hasUnsavedChanges && !isLoading, // Only when valid
+    preventDefault: true
+  },
+  dependencies: [hasUnsavedChanges, isLoading, handleSave]
+});
+```
+
+### Multiple Hotkeys for Same Action
+
+```typescript
+// In useHotkeyData.ts
+addHotkey('canvas', 'redo', ['mod+shift+z', 'mod+y']); // Two alternatives
+```
+
+### Focus-Scoped Hotkeys
+
+```typescript
+import { useFocusRegion } from 'common/hooks/focus';
+
+const MyComponent = () => {
+  const focusRegionRef = useFocusRegion('myRegion');
+
+  // Hotkey only works when this region has focus
+  useRegisteredHotkeys({
+    id: 'myAction',
+    category: 'app',
+    callback: handleAction,
+    options: { enabled: true }
+  });
+
+  return <div ref={focusRegionRef}>...</div>;
+};
+```

docs/contributing/MODEL_MANAGER.md

@@ -265,7 +265,7 @@ If the key is unrecognized, this call raises an
 
 #### exists(key) -> AnyModelConfig
 
-Returns True if a model with the given key exists in the databsae.
+Returns True if a model with the given key exists in the database.
 
 #### search_by_path(path) -> AnyModelConfig
 
@@ -718,7 +718,7 @@ When downloading remote models is implemented, additional
 configuration information, such as list of trigger terms, will be
 retrieved from the HuggingFace and Civitai model repositories.
 
-The probed values can be overriden by providing a dictionary in the
+The probed values can be overridden by providing a dictionary in the
 optional `config` argument passed to `import_model()`. You may provide
 overriding values for any of the model's configuration
 attributes. Here is an example of setting the
@@ -841,7 +841,7 @@ variable.
 
 #### installer.start(invoker)
 
-The `start` method is called by the API intialization routines when
+The `start` method is called by the API initialization routines when
 the API starts up. Its effect is to call `sync_to_config()` to
 synchronize the model record store database with what's currently on
 disk.

docs/contributing/PR-MERGE-POLICY.md

@@ -0,0 +1,64 @@
+# Pull Request Merge Policy
+
+This document outlines the process for reviewing and merging pull requests (PRs) into the InvokeAI repository.
+
+## Review Process
+
+### 1. Assignment
+
+One of the repository maintainers will assign collaborators to review a pull request. The assigned reviewer(s) will be responsible for conducting the code review.
+
+### 2. Review and Iteration
+
+The assignee is responsible for:
+- Reviewing the PR thoroughly
+- Providing constructive feedback
+- Iterating with the PR author until the assignee is satisfied that the PR is fit to merge
+- Ensuring the PR meets code quality standards, follows project conventions, and doesn't introduce bugs or regressions
+
+### 3. Approval and Notification
+
+Once the assignee is satisfied with the PR:
+- The assignee approves the PR
+- The assignee alerts one of the maintainers that the PR is ready for merge using the **#request-reviews Discord channel**
+
+### 4. Final Merge
+
+One of the maintainers is responsible for:
+- Performing a final check of the PR
+- Merging the PR into the appropriate branch
+
+**Important:** Collaborators are strongly discouraged from merging PRs on their own, except in case of emergency (e.g., critical bug fix and no maintainer is available).
+
+### 5. Release Policy
+
+Once a feature release candidate is published, no feature PRs are to
+be merged into main. Only bugfixes are allowed until the final
+release.
+
+## Best Practices
+
+### Clean Commit History
+
+To encourage a clean development log, PR authors are encouraged to use `git rebase -i` to suppress trivial commit messages (e.g., `ruff` and `prettier` formatting fixes) after the PR is accepted but before it is merged.
+
+### Merge Strategy
+
+The maintainer will perform either a **3-way merge** or **squash merge** when merging a PR into the `main` branch. This approach helps avoid rebase conflict hell and maintains a cleaner project history.
+
+### Attribution
+
+The PR author should reference any papers, source code or
+documentation that they used while creating the code both in the PR
+and as comments in the code itself. If there are any licensing
+restrictions, these should be linked to and/or reproduced in the repo
+root.
+
+
+## Summary
+
+This policy ensures that:
+- All PRs receive proper review from assigned collaborators
+- Maintainers have final oversight before code enters the main branch
+- The commit history remains clean and meaningful
+- Merge conflicts are minimized through appropriate merge strategies

docs/contributing/RECALL_PARAMETERS/RECALL_API_LORAS_CONTROLNETS_IMAGES.md

@@ -0,0 +1,375 @@
+# Recall Parameters API - LoRAs, ControlNets, and IP Adapters with Images
+
+## Overview
+
+The Recall Parameters API supports recalling LoRAs, ControlNets (including T2I Adapters and Control LoRAs), and IP Adapters along with their associated weights and settings. Control Layers and IP Adapters can now include image references from the `INVOKEAI_ROOT/outputs/images` directory for fully functional control and image prompt functionality.
+
+## Key Features
+
+✅ **LoRAs**: Fully functional - adds to UI, queries model configs, applies weights
+✅ **Control Layers**: Full support with optional images from outputs/images
+✅ **IP Adapters**: Full support with optional reference images from outputs/images
+✅ **Model Name Resolution**: Automatic lookup from human-readable names to internal keys
+✅ **Image Validation**: Backend validates that image files exist before sending
+
+## Endpoints
+
+### POST `/api/v1/recall/{queue_id}`
+
+Updates recallable parameters for the frontend, including LoRAs, control adapters, and IP adapters with optional images.
+
+**Path Parameters:**
+- `queue_id` (string): The queue ID to associate parameters with (typically "default")
+
+**Request Body:**
+
+All fields are optional. Include only the parameters you want to update.
+
+```typescript
+{
+  // Standard parameters
+  positive_prompt?: string;
+  negative_prompt?: string;
+  model?: string;           // Model name or key
+  steps?: number;
+  cfg_scale?: number;
+  width?: number;
+  height?: number;
+  seed?: number;
+  // ... other standard parameters
+  
+  // LoRAs
+  loras?: Array<{
+    model_name: string;     // LoRA model name
+    weight?: number;        // Default: 0.75, Range: -10 to 10
+    is_enabled?: boolean;   // Default: true
+  }>;
+  
+  // Control Layers (ControlNet, T2I Adapter, Control LoRA)
+  control_layers?: Array<{
+    model_name: string;            // Control adapter model name
+    image_name?: string;           // Optional image filename from outputs/images
+    weight?: number;               // Default: 1.0, Range: -1 to 2
+    begin_step_percent?: number;   // Default: 0.0, Range: 0 to 1
+    end_step_percent?: number;     // Default: 1.0, Range: 0 to 1
+    control_mode?: "balanced" | "more_prompt" | "more_control";  // ControlNet only
+  }>;
+  
+  // IP Adapters
+  ip_adapters?: Array<{
+    model_name: string;            // IP Adapter model name
+    image_name?: string;           // Optional reference image filename from outputs/images
+    weight?: number;               // Default: 1.0, Range: -1 to 2
+    begin_step_percent?: number;   // Default: 0.0, Range: 0 to 1
+    end_step_percent?: number;     // Default: 1.0, Range: 0 to 1
+    method?: "full" | "style" | "composition";  // Default: "full"
+    influence?: "Lowest" | "Low" | "Medium" | "High" | "Highest";  // Flux Redux only; default: "highest"
+  }>;
+}
+```
+
+## Model Name Resolution
+
+The backend automatically resolves model names to their internal keys:
+
+1. **Main Models**: Resolved from the name to the model key
+2. **LoRAs**: Searched in the LoRA model database
+3. **Control Adapters**: Tried in order - ControlNet → T2I Adapter → Control LoRA
+4. **IP Adapters**: Searched in the IP Adapter model database
+
+Models that cannot be resolved are skipped with a warning in the logs.
+
+## Image File Handling
+
+### Image Path Resolution
+
+When you specify an `image_name`, the backend:
+1. Constructs the full path: `{INVOKEAI_ROOT}/outputs/images/{image_name}`
+2. Validates that the file exists
+3. Includes the image reference in the event sent to the frontend
+4. Logs whether the image was found or not
+
+### Image Naming
+
+Images should be referenced by their filename as it appears in the outputs/images directory:
+- ✅ Correct: `"image_name": "example.png"`
+- ✅ Correct: `"image_name": "my_control_image_20240110.jpg"`
+- ❌ Incorrect: `"image_name": "outputs/images/example.png"`  (use relative filename only)
+- ❌ Incorrect: `"image_name": "/full/path/to/example.png"`   (use relative filename only)
+
+## Frontend Behavior
+
+### LoRAs
+- **Fully Supported**: LoRAs are immediately added to the LoRA list in the UI
+- Existing LoRAs are cleared before adding new ones
+- Each LoRA's model config is fetched and applied with the specified weight
+- LoRAs appear in the LoRA selector panel
+
+### Control Layers with Images
+- **Fully Supported**: Control layers now support images from outputs/images
+- Configuration includes model, weights, step percentages, and image reference
+- Image availability is logged in frontend console
+- Images can be used to create actual control layers through the UI
+
+### IP Adapters with Images
+- **Fully Supported**: IP Adapters now support reference images from outputs/images
+- Configuration includes model, weights, step percentages, method, and image reference
+- Image availability is logged in frontend console
+- Images can be used to create actual reference image layers through the UI
+
+## Examples
+
+### 1. Add LoRAs Only
+
+```bash
+curl -X POST http://localhost:9090/api/v1/recall/default \
+  -H "Content-Type: application/json" \
+  -d '{
+    "loras": [
+      {
+        "model_name": "add-detail-xl",
+        "weight": 0.8,
+        "is_enabled": true
+      },
+      {
+        "model_name": "sd_xl_offset_example-lora_1.0",
+        "weight": 0.5,
+        "is_enabled": true
+      }
+    ]
+  }'
+```
+
+### 2. Configure Control Layers with Image
+
+Replace `my_control_image.png` with an actual image filename from your outputs/images directory.
+
+```bash
+curl -X POST http://localhost:9090/api/v1/recall/default \
+  -H "Content-Type: application/json" \
+  -d '{
+    "control_layers": [
+      {
+        "model_name": "controlnet-canny-sdxl-1.0",
+        "image_name": "my_control_image.png",
+        "weight": 0.75,
+        "begin_step_percent": 0.0,
+        "end_step_percent": 0.8,
+        "control_mode": "balanced"
+      }
+    ]
+  }'
+```
+
+### 3. Configure IP Adapters with Reference Image
+
+Replace `reference_face.png` with an actual image filename from your outputs/images directory.
+
+```bash
+curl -X POST http://localhost:9090/api/v1/recall/default \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ip_adapters": [
+      {
+        "model_name": "ip-adapter-plus-face_sd15",
+        "image_name": "reference_face.png",
+        "weight": 0.7,
+        "begin_step_percent": 0.0,
+        "end_step_percent": 1.0,
+        "method": "composition"
+      }
+    ]
+  }'
+```
+
+### 4. Complete Configuration with All Features
+
+```bash
+curl -X POST http://localhost:9090/api/v1/recall/default \
+  -H "Content-Type: application/json" \
+  -d '{
+    "positive_prompt": "masterpiece, detailed photo with specific style",
+    "negative_prompt": "blurry, low quality",
+    "model": "FLUX Schnell",
+    "steps": 25,
+    "cfg_scale": 8.0,
+    "width": 1024,
+    "height": 768,
+    "seed": 42,
+    "loras": [
+      {
+        "model_name": "add-detail-xl",
+        "weight": 0.6,
+        "is_enabled": true
+      }
+    ],
+    "control_layers": [
+      {
+        "model_name": "controlnet-depth-sdxl-1.0",
+        "image_name": "depth_map.png",
+        "weight": 1.0,
+        "begin_step_percent": 0.0,
+        "end_step_percent": 0.7
+      }
+    ],
+    "ip_adapters": [
+      {
+        "model_name": "ip-adapter-plus-face_sd15",
+        "image_name": "style_reference.png",
+        "weight": 0.5,
+        "begin_step_percent": 0.0,
+        "end_step_percent": 1.0,
+        "method": "style"
+      }
+    ]
+  }'
+```
+
+## Response Format
+
+```json
+{
+  "status": "success",
+  "queue_id": "default",
+  "updated_count": 15,
+  "parameters": {
+    "positive_prompt": "...",
+    "steps": 25,
+    "loras": [
+      {
+        "model_key": "abc123...",
+        "weight": 0.6,
+        "is_enabled": true
+      }
+    ],
+    "control_layers": [
+      {
+        "model_key": "controlnet-xyz...",
+        "weight": 1.0,
+        "image": {
+          "image_name": "depth_map.png"
+        }
+      }
+    ],
+    "ip_adapters": [
+      {
+        "model_key": "ip-adapter-xyz...",
+        "weight": 0.5,
+        "image": {
+          "image_name": "style_reference.png"
+        }
+      }
+    ]
+  }
+}
+```
+
+## WebSocket Events
+
+When parameters are updated, a `recall_parameters_updated` event is emitted via WebSocket to the queue room. The frontend automatically:
+
+1. Applies standard parameters (prompts, steps, dimensions, etc.)
+2. Loads and adds LoRAs to the LoRA list
+3. Logs control layer and IP adapter configurations with image information
+4. Makes image references available for manual canvas/reference image creation
+
+## Logging
+
+### Backend Logs
+
+Backend logs show:
+- Model name → key resolution (success/failure)
+- Image file validation (found/not found)
+- Parameter storage confirmation
+- Event emission status
+
+Example log messages:
+```
+INFO: Resolved ControlNet model name 'controlnet-canny-sdxl-1.0' to key 'controlnet-xyz...'
+INFO: Found image file: depth_map.png
+INFO: Updated 12 recall parameters for queue default
+INFO: Resolved 1 LoRA(s)
+INFO: Resolved 1 control layer(s)
+INFO: Resolved 1 IP adapter(s)
+```
+
+### Frontend Logs
+
+Frontend logs (check browser console):
+- Set `localStorage.ROARR_FILTER = 'debug'` to see all debug messages
+- Look for messages from the `events` namespace
+- LoRA loading, model resolution, and parameter application are logged
+
+Example log messages:
+```
+INFO: Applied 5 recall parameters to store
+INFO: Received 1 control layer(s) with image support
+INFO: Control layer 1: controlnet-xyz... (weight: 0.75, image: depth_map.png)
+DEBUG: Control layer 1 image available at: outputs/images/depth_map.png
+INFO: Received 1 IP adapter(s) with image support
+INFO: IP adapter 1: ip-adapter-xyz... (weight: 0.7, image: style_reference.png)
+DEBUG: IP adapter 1 image available at: outputs/images/style_reference.png
+```
+
+## Limitations
+
+1. **Canvas Integration**: Control layers and IP adapters with images are currently logged but not automatically added to canvas layers
+   - Users can view the configuration and manually create canvas layers with the provided images
+   - Future enhancement: Auto-create canvas layers with stored images
+
+2. **Model Availability**: Models must be installed in InvokeAI before they can be recalled
+
+3. **Image Availability**: Images must exist in the outputs/images directory
+   - Missing images are logged as warnings but don't fail the request
+   - Other parameters are still applied even if images are missing
+
+4. **Image URLs**: Only local filenames from outputs/images are supported
+   - Remote image URLs are not currently supported
+
+## Testing
+
+Use the provided test script:
+
+```bash
+./test_recall_loras_controlnets.sh
+```
+
+This will test:
+- LoRA addition with multiple models
+- Control layer configuration with image references
+- IP adapter configuration with image references
+- Combined parameter updates with all features
+
+Note: Update the image names in the test script to match actual images in your outputs/images directory.
+
+## Troubleshooting
+
+### Images Not Found
+
+If you see "Image file not found" in the logs:
+1. Verify the image filename matches exactly (case-sensitive)
+2. Ensure the image is in `{INVOKEAI_ROOT}/outputs/images/`
+3. Check that the filename doesn't include the `outputs/images/` prefix
+
+### Models Not Found
+
+If you see "Could not find model" messages:
+1. Verify the model name matches exactly (case-sensitive)
+2. Ensure the model is installed in InvokeAI
+3. Check the model name using the models browser in the UI
+
+### Event Not Received
+
+If the frontend doesn't receive the event:
+1. Check browser console for connection errors
+2. Verify the queue_id matches the frontend's queue (usually "default")
+3. Check backend logs for event emission errors
+
+## Future Enhancements
+
+Potential improvements:
+1. Auto-create canvas layers with provided control layer images
+2. Auto-create reference image layers with provided IP adapter images
+3. Support for image URLs
+4. Batch operations for multiple queue IDs
+5. Image upload capability (accept base64 or file upload)

docs/contributing/RECALL_PARAMETERS/RECALL_PARAMETERS_API.md

@@ -0,0 +1,208 @@
+# Recall Parameters API
+
+## Overview
+
+A new REST API endpoint has been added to the InvokeAI backend that allows programmatic updates to recallable parameters from another process. This enables external applications or scripts to modify frontend parameters like prompts, models, and step counts via HTTP requests.
+
+When parameters are updated via the API, the backend automatically broadcasts a WebSocket event to all connected frontend clients subscribed to that queue, causing them to update immediately.
+
+## How It Works
+
+1. **API Request**: External application sends a POST request with parameters to update
+2. **Storage**: Parameters are stored in client state persistence, associated with a queue ID
+3. **Broadcast**: A WebSocket event (`recall_parameters_updated`) is emitted to all frontend clients listening to that queue
+4. **Frontend Update**: Connected frontend clients receive the event and can process the updated parameters
+5. **Immediate Display**: The frontend UI updates automatically with the new values
+
+This means if you have the InvokeAI frontend open in a browser, updating parameters via the API will instantly reflect on the screen without any manual action needed.
+
+## Endpoint
+
+**Base URL**: `http://localhost:9090/api/v1/recall/{queue_id}`
+
+## POST - Update Recall Parameters
+
+Updates recallable parameters for a given queue ID.
+
+### Request
+
+```http
+POST /api/v1/recall/{queue_id}
+Content-Type: application/json
+
+{
+  "positive_prompt": "a beautiful landscape",
+  "negative_prompt": "blurry, low quality",
+  "model": "sd-1.5",
+  "steps": 20,
+  "cfg_scale": 7.5,
+  "width": 512,
+  "height": 512,
+  "seed": 12345
+}
+```
+
+The queue id is usually "default".
+
+### Parameters
+
+All parameters are optional. Only provide the parameters you want to update:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `positive_prompt` | string | Positive prompt text |
+| `negative_prompt` | string | Negative prompt text |
+| `model` | string | Main model name/identifier |
+| `refiner_model` | string | Refiner model name/identifier |
+| `vae_model` | string | VAE model name/identifier |
+| `scheduler` | string | Scheduler name |
+| `steps` | integer | Number of generation steps (≥1) |
+| `refiner_steps` | integer | Number of refiner steps (≥0) |
+| `cfg_scale` | number | CFG scale for guidance |
+| `cfg_rescale_multiplier` | number | CFG rescale multiplier |
+| `refiner_cfg_scale` | number | Refiner CFG scale |
+| `guidance` | number | Guidance scale |
+| `width` | integer | Image width in pixels (≥64) |
+| `height` | integer | Image height in pixels (≥64) |
+| `seed` | integer | Random seed (≥0) |
+| `denoise_strength` | number | Denoising strength (0-1) |
+| `refiner_denoise_start` | number | Refiner denoising start (0-1) |
+| `clip_skip` | integer | CLIP skip layers (≥0) |
+| `seamless_x` | boolean | Enable seamless X tiling |
+| `seamless_y` | boolean | Enable seamless Y tiling |
+| `refiner_positive_aesthetic_score` | number | Refiner positive aesthetic score |
+| `refiner_negative_aesthetic_score` | number | Refiner negative aesthetic score |
+
+### Response
+
+```json
+{
+  "status": "success",
+  "queue_id": "queue_123",
+  "updated_count": 7,
+  "parameters": {
+    "positive_prompt": "a beautiful landscape",
+    "negative_prompt": "blurry, low quality",
+    "model": "sd-1.5",
+    "steps": 20,
+    "cfg_scale": 7.5,
+    "width": 512,
+    "height": 512,
+    "seed": 12345
+  }
+}
+```
+
+## GET - Retrieve Recall Parameters
+
+Retrieves metadata about stored recall parameters.
+
+### Request
+
+```http
+GET /api/v1/recall/{queue_id}
+```
+
+### Response
+
+```json
+{
+  "status": "success",
+  "queue_id": "queue_123",
+  "note": "Use the frontend to access stored recall parameters, or set specific parameters using POST"
+}
+```
+
+## Usage Examples
+
+### Using cURL
+
+```bash
+# Update prompts and model
+curl -X POST http://localhost:9090/api/v1/recall/default \
+  -H "Content-Type: application/json" \
+  -d '{
+    "positive_prompt": "a cyberpunk city at night",
+    "negative_prompt": "dark, unclear",
+    "model": "sd-1.5",
+    "steps": 30
+  }'
+
+# Update just the seed
+curl -X POST http://localhost:9090/api/v1/recall/default \
+  -H "Content-Type: application/json" \
+  -d '{"seed": 99999}'
+```
+
+### Using Python
+
+```python
+import requests
+import json
+
+# Configuration
+API_URL = "http://localhost:9090/api/v1/recall/default"
+
+# Update multiple parameters
+params = {
+    "positive_prompt": "a serene forest",
+    "negative_prompt": "people, buildings",
+    "steps": 25,
+    "cfg_scale": 7.0,
+    "seed": 42
+}
+
+response = requests.post(API_URL, json=params)
+result = response.json()
+
+print(f"Status: {result['status']}")
+print(f"Updated {result['updated_count']} parameters")
+print(json.dumps(result['parameters'], indent=2))
+```
+
+### Using Node.js/JavaScript
+
+```javascript
+const API_URL = 'http://localhost:9090/api/v1/recall/default';
+
+const params = {
+  positive_prompt: 'a beautiful sunset',
+  negative_prompt: 'blurry',
+  steps: 20,
+  width: 768,
+  height: 768,
+  seed: 12345
+};
+
+fetch(API_URL, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(params)
+})
+  .then(res => res.json())
+  .then(data => console.log(data));
+```
+
+## Implementation Details
+
+- Parameters are stored in the client state persistence service, using keys prefixed with `recall_`
+- The parameters are associated with a `queue_id`, allowing multiple concurrent sessions to maintain separate parameter sets
+- Only non-null parameters are processed and stored
+- The endpoint provides validation for numeric ranges (e.g., steps ≥ 1, dimensions ≥ 64)
+- All parameter values are JSON-serialized for storage
+- When parameter values are changed, the backend generates a web sockets event that the frontend listens to.
+
+## Integration with Frontend
+
+The stored parameters can be accessed by the frontend through the
+existing client state API or by implementing hooks that read from the
+recall parameter storage. This allows external applications to
+pre-populate generation parameters before the user initiates image
+generation.
+
+## Error Handling
+
+- **400 Bad Request**: Invalid parameters or parameter values
+- **500 Internal Server Error**: Server-side error storing or retrieving parameters
+
+Errors include detailed messages explaining what went wrong.

docs/contributing/contributors.md

@@ -16,7 +16,7 @@ We thank [all contributors](https://github.com/invoke-ai/InvokeAI/graphs/contrib
 - @psychedelicious (Spencer Mabrito) - Web Team Leader
 - @joshistoast (Josh Corbett) - Web Development
 - @cheerio (Mary Rogers) - Lead Engineer & Web App Development
-- @ebr (Eugene Brodsky) - Cloud/DevOps/Sofware engineer; your friendly neighbourhood cluster-autoscaler
+- @ebr (Eugene Brodsky) - Cloud/DevOps/Software engineer; your friendly neighbourhood cluster-autoscaler
 - @sunija - Standalone version
 - @brandon (Brandon Rising) - Platform, Infrastructure, Backend Systems
 - @ryanjdick (Ryan Dick) - Machine Learning & Training

docs/contributing/dev-environment.md

@@ -41,7 +41,7 @@ If you just want to use Invoke, you should use the [launcher][launcher link].
      With the modifications made, the install command should look something like this:
 
       ```sh
-      uv pip install -e ".[dev,test,docs,xformers]" --python 3.12 --python-preference only-managed --index=https://download.pytorch.org/whl/cu126 --reinstall
+      uv pip install -e ".[dev,test,docs,xformers]" --python 3.12 --python-preference only-managed --index=https://download.pytorch.org/whl/cu128 --reinstall
       ```
 
 6. At this point, you should have Invoke installed, a venv set up and activated, and the server running. But you will see a warning in the terminal that no UI was found. If you go to the URL for the server, you won't get a UI.
@@ -50,11 +50,11 @@ If you just want to use Invoke, you should use the [launcher][launcher link].
 
       If you only want to edit the docs, you can stop here and skip to the **Documentation** section below.
 
-7. Install the frontend dev toolchain:
+7. Install the frontend dev toolchain, paying attention to versions:
 
-      - [`nodejs`](https://nodejs.org/) (v20+)
+      - [`nodejs`](https://nodejs.org/) (tested on LTS, v22)
 
-      - [`pnpm`](https://pnpm.io/8.x/installation) (must be v8 - not v9!)
+      - [`pnpm`](https://pnpm.io/installation) (tested on v10)
 
 8. Do a production build of the frontend:
 

docs/contributing/frontend/canvas-text-tool.md

@@ -0,0 +1,35 @@
+# Canvas Text Tool
+
+## Overview
+
+The canvas text workflow is split between a Konva module that owns tool state and a React overlay that handles text entry.
+
+- `invokeai/frontend/web/src/features/controlLayers/konva/CanvasTool/CanvasTextToolModule.ts`
+  - Owns the tool, cursor preview, and text session state (including the cursor "T" marker).
+  - Manages dynamic cursor contrast, starts sessions on pointer down, and commits sessions by rasterizing the active text block into a new raster layer.
+- `invokeai/frontend/web/src/features/controlLayers/components/Text/CanvasTextOverlay.tsx`
+  - Renders the on-canvas editor as a `contentEditable` overlay positioned in canvas space.
+  - Syncs keyboard input, suppresses app hotkeys, and forwards commits/cancels to the Konva module.
+- `invokeai/frontend/web/src/features/controlLayers/components/Text/TextToolOptions.tsx`
+  - Provides the font dropdown, size slider/input, formatting toggles, and alignment buttons that appear when the Text tool is active.
+
+## Rasterization pipeline
+
+`renderTextToCanvas()` (`invokeai/frontend/web/src/features/controlLayers/text/textRenderer.ts`) converts the editor contents into a transparent canvas. The Text tool module configures the renderer with the active font stack, weight, styling flags, alignment, and the active canvas color. The resulting canvas is encoded to a PNG data URL and stored in a new raster layer (`image` object) with a transparent background.
+
+Layer placement preserves the original click location:
+
+- The session stores the anchor coordinate (where the user clicked) and current alignment.
+- `calculateLayerPosition()` calculates the top-left position for the raster layer after applying the configured padding and alignment offsets.
+- New layers are inserted directly above the currently-selected raster layer (when present) and selected automatically.
+
+## Font stacks
+
+Font definitions live in `invokeai/frontend/web/src/features/controlLayers/text/textConstants.ts` as ten deterministic stacks (sans, serif, mono, rounded, script, humanist, slab serif, display, narrow, UI serif). Each stack lists system-safe fallbacks so the editor can choose the first available font per platform.
+
+To add or adjust fonts:
+
+1. Update `TEXT_FONT_STACKS` with the new `id`, `label`, and CSS `font-family` stack.
+2. If you add a new stack, extend the `TEXT_FONT_IDS` tuple and update the `canvasTextSlice` schema default (`TEXT_DEFAULT_FONT_ID`).
+3. Provide translation strings for any new labels in `public/locales/*`.
+4. The editor and renderer will automatically pick up the new stack via `getFontStackById()`.

docs/contributing/frontend/workflows.md

@@ -297,7 +297,7 @@ Migration logic is in [migrations.ts].
 <!-- links -->
 
 [pydantic]: https://github.com/pydantic/pydantic 'pydantic'
-[zod]: https://github.com/colinhacks/zod 'zod/v4'
+[zod]: https://github.com/colinhacks/zod 'zod'
 [openapi-types]: https://github.com/kogosoftwarellc/open-api/tree/main/packages/openapi-types 'openapi-types'
 [reactflow]: https://github.com/xyflow/xyflow 'reactflow'
 [reactflow-concepts]: https://reactflow.dev/learn/concepts/terms-and-definitions

docs/contributing/index.md

@@ -18,7 +18,7 @@ If you’d like to add a Node, please see our [nodes contribution guide](../node
 
 Helping support other users in [Discord](https://discord.gg/ZmtBAhwWhy) and on Github are valuable forms of contribution that we greatly appreciate.
 
-We receive many issues and requests for help from users. We're limited in bandwidth relative to our the user base, so providing answers to questions or helping identify causes of issues is very helpful. By doing this, you enable us to spend time on the highest priority work.
+We receive many issues and requests for help from users. We're limited in bandwidth relative to our user base, so providing answers to questions or helping identify causes of issues is very helpful. By doing this, you enable us to spend time on the highest priority work.
 
 ## Documentation
 

docs/features/Text_tool.md

@@ -0,0 +1,19 @@
+# Text Tool
+
+## Font selection
+
+The Text tool uses a set of predefined font stacks. When you choose a font, the app resolves the first available font on your system from that stack and uses it for both the editor overlay and the rasterized result. This provides consistent styling across platforms while still falling back to safe system fonts if a preferred font is missing.
+
+## Size and spacing
+
+- **Size** controls the font size in pixels.
+- **Spacing** controls the line height multiplier (Dense, Normal, Spacious). This affects the distance between lines while editing the text.
+
+## Uncommitted state
+
+While text is uncommitted, it remains editable on-canvas. Access to other tools is blocked. Switching to other tabs (Generate, Upascaling, Workflows etc.) discards the text. The uncommitted box can be moved and rotated:
+
+- **Move:** Hold Ctrl (Windows/Linux) or Command (macOS) and drag to move the text box.
+- **Rotate:** Drag the rotation handle above the box. Hold **Shift** while rotating to snap to 15 degree increments.
+
+The text is committed to a raster layer when you press **Enter**. Press **Esc** to discard the current text session.

docs/features/hotkeys.md

@@ -0,0 +1,80 @@
+# Customizable Hotkeys
+
+InvokeAI allows you to customize all keyboard shortcuts (hotkeys) to match your workflow preferences.
+
+## Features
+
+- **View All Hotkeys**: See all available keyboard shortcuts in one place
+- **Customize Any Hotkey**: Change any shortcut to your preference
+- **Multiple Bindings**: Assign multiple key combinations to the same action
+- **Smart Validation**: Built-in validation prevents invalid combinations
+- **Persistent Settings**: Your custom hotkeys are saved and restored across sessions
+- **Easy Reset**: Reset individual hotkeys or all hotkeys back to defaults
+
+## How to Use
+
+### Opening the Hotkeys Modal
+
+Press `Shift+?` or click the keyboard icon in the application to open the Hotkeys Modal.
+
+### Viewing Hotkeys
+
+In **View Mode** (default), you can:
+- Browse all available hotkeys organized by category (App, Canvas, Gallery, Workflows, etc.)
+- Search for specific hotkeys using the search bar
+- See the current key combination for each action
+
+### Customizing Hotkeys
+
+1. Click the **Edit Mode** button at the bottom of the Hotkeys Modal
+2. Find the hotkey you want to change
+3. Click the **pencil icon** next to it
+4. The editor will appear with:
+   - **Input field**: Enter your new hotkey combination
+   - **Modifier buttons**: Quick-insert Mod, Ctrl, Shift, Alt keys
+   - **Help icon** (?): Shows syntax examples and valid keys
+   - **Live preview**: See how your hotkey will look
+
+5. Enter your new hotkey using the format:
+   - `mod+a` - Mod key + A (Mod = Ctrl on Windows/Linux, Cmd on Mac)
+   - `ctrl+shift+k` - Multiple modifiers
+   - `f1` - Function keys
+   - `mod+enter, ctrl+enter` - Multiple alternatives (separated by comma)
+
+6. Click the **checkmark** or press Enter to save
+7. Click the **X** or press Escape to cancel
+
+### Resetting Hotkeys
+
+**Reset a single hotkey:**
+- Click the counter-clockwise arrow icon that appears next to customized hotkeys
+
+**Reset all hotkeys:**
+- In Edit Mode, click the **Reset All to Default** button at the bottom
+
+### Hotkey Format Reference
+
+**Valid Modifiers:**
+- `mod` - Context-aware: Ctrl (Windows/Linux) or Cmd (Mac)
+- `ctrl` - Control key
+- `shift` - Shift key
+- `alt` - Alt key (Option on Mac)
+
+**Valid Keys:**
+- Letters: `a-z`
+- Numbers: `0-9`
+- Function keys: `f1-f12`
+- Special keys: `enter`, `space`, `tab`, `backspace`, `delete`, `escape`
+- Arrow keys: `up`, `down`, `left`, `right`
+- And more...
+
+**Examples:**
+- ✅ `mod+s` - Save action
+- ✅ `ctrl+shift+p` - Command palette
+- ✅ `f5, mod+r` - Two alternatives for refresh
+- ❌ `mod+` - Invalid (no key after modifier)
+- ❌ `shift+ctrl+` - Invalid (ends with modifier)
+
+## For Developers
+
+For technical implementation details, architecture, and how to add new hotkeys to the system, see the [Hotkeys Developer Documentation](../contributing/HOTKEYS.md).

docs/features/orphaned_model_removal.md

@@ -0,0 +1,152 @@
+# Orphaned Models Synchronization Feature
+
+## Overview
+This feature adds a UI for synchronizing the models directory by finding and removing orphaned model files. Orphaned models are directories that contain model files but are not referenced in the InvokeAI database.
+
+## Implementation Summary
+
+### Backend (Python)
+
+#### New Service: `OrphanedModelsService`
+- Location: `invokeai/app/services/orphaned_models/`
+- Implements the core logic from the CLI script
+- Methods:
+  - `find_orphaned_models()`: Scans the models directory and database to find orphaned models
+  - `delete_orphaned_models(paths)`: Safely deletes specified orphaned model directories
+
+#### API Routes
+Added to `invokeai/app/api/routers/model_manager.py`:
+- `GET /api/v2/models/sync/orphaned`: Returns list of orphaned models with metadata
+- `DELETE /api/v2/models/sync/orphaned`: Deletes selected orphaned models
+
+#### Data Models
+- `OrphanedModelInfo`: Contains path, absolute_path, files list, and size_bytes
+- `DeleteOrphanedModelsRequest`: Contains list of paths to delete
+- `DeleteOrphanedModelsResponse`: Contains deleted paths and errors
+
+### Frontend (TypeScript/React)
+
+#### New Components
+
+1. **SyncModelsButton.tsx**
+   - Red button styled with `colorScheme="error"` for visual prominence
+   - Labeled "Sync Models" 
+   - Opens the SyncModelsDialog when clicked
+   - Located next to the "+ Add Models" button
+
+2. **SyncModelsDialog.tsx**
+   - Modal dialog that displays orphaned models
+   - Features:
+     - List of orphaned models with checkboxes (default: all checked)
+     - "Select All" / "Deselect All" toggle
+     - Shows file count and total size for each model
+     - "Delete" and "Cancel" buttons
+     - Loading spinner while fetching data
+     - Error handling with user-friendly messages
+   - Automatically shows toast if no orphaned models found
+   - Shows success/error toasts after deletion
+
+#### API Integration
+- Added `useGetOrphanedModelsQuery` and `useDeleteOrphanedModelsMutation` hooks to `services/api/endpoints/models.ts`
+- Integrated with RTK Query for efficient data fetching and caching
+
+#### Translation Strings
+Added to `public/locales/en.json`:
+- syncModels, noOrphanedModels, orphanedModelsFound
+- orphanedModelsDescription, foundOrphanedModels (with pluralization)
+- filesCount, deleteSelected, deselectAll
+- Success/error messages for deletion operations
+
+## User Experience Flow
+
+1. User clicks the red "Sync Models" button in the Model Manager
+2. System queries the backend for orphaned models
+3. If no orphaned models:
+   - Toast message: "The models directory is synchronized. No orphaned files found."
+   - Dialog closes automatically
+4. If orphaned models found:
+   - Dialog shows list with checkboxes (all selected by default)
+   - User can toggle individual models or use "Select All" / "Deselect All"
+   - Each model shows:
+     - Directory path
+     - File count
+     - Total size (formatted: B, KB, MB, GB)
+5. User clicks "Delete {{count}} selected"
+6. System deletes selected models
+7. Success/error toasts appear
+8. Dialog closes
+
+## Safety Features
+
+1. **Database Backup**: The service creates a backup before any deletion
+2. **Selective Deletion**: Users choose which models to delete
+3. **Path Validation**: Ensures paths are within the models directory
+4. **Error Handling**: Reports which models failed to delete and why
+5. **Default Selected**: All models are selected by default for convenience
+6. **Confirmation Required**: User must explicitly click Delete
+
+## Technical Details
+
+### Directory-Based Detection
+The system treats model paths as directories:
+- If database has `model-id/file.safetensors`, the entire `model-id/` directory belongs to that model
+- All files and subdirectories within a registered model directory are protected
+- Only directories with NO registered models are flagged as orphaned
+
+### Supported File Extensions
+- .safetensors
+- .ckpt
+- .pt
+- .pth
+- .bin
+- .onnx
+
+### Skipped Directories
+- .download_cache
+- .convert_cache
+- \_\_pycache\_\_
+- .git
+
+## Testing Recommendations
+
+1. **Test with orphaned models**: 
+   - Manually copy a model directory to models folder
+   - Verify it appears in the dialog
+   - Delete it and verify removal
+
+2. **Test with no orphaned models**:
+   - Clean install
+   - Verify toast message appears
+
+3. **Test partial selection**:
+   - Select only some models
+   - Verify only selected ones are deleted
+
+4. **Test error scenarios**:
+   - Invalid paths
+   - Permission issues
+   - Verify error messages are clear
+
+## Files Changed
+
+### Backend
+- `invokeai/app/services/orphaned_models/__init__.py` (new)
+- `invokeai/app/services/orphaned_models/orphaned_models_service.py` (new)
+- `invokeai/app/api/routers/model_manager.py` (modified)
+
+### Frontend
+- `invokeai/frontend/web/src/services/api/endpoints/models.ts` (modified)
+- `invokeai/frontend/web/src/features/modelManagerV2/subpanels/ModelManager.tsx` (modified)
+- `invokeai/frontend/web/src/features/modelManagerV2/subpanels/ModelManagerPanel/SyncModelsButton.tsx` (new)
+- `invokeai/frontend/web/src/features/modelManagerV2/subpanels/ModelManagerPanel/SyncModelsDialog.tsx` (new)
+- `invokeai/frontend/web/public/locales/en.json` (modified)
+
+## Future Enhancements
+
+Potential improvements for future versions:
+1. Show preview of what will be deleted before deletion
+2. Add option to move orphaned models to archive instead of deleting
+3. Show disk space that will be freed
+4. Add filter/search in orphaned models list
+5. Support for undo operation
+6. Scheduled automatic cleanup

docs/installation/manual.md

@@ -69,34 +69,34 @@ The following commands vary depending on the version of Invoke being installed a
     - If you have an Nvidia 20xx series GPU or older, use `invokeai[xformers]`.
     - If you have an Nvidia 30xx series GPU or newer, or do not have an Nvidia GPU, use `invokeai`.
 
-7. Determine the `PyPI` index URL to use for installation, if any. This is necessary to get the right version of torch installed.
+7. Determine the torch backend to use for installation, if any. This is necessary to get the right version of torch installed. This is acheived by using [UV's built in torch support.](https://docs.astral.sh/uv/guides/integration/pytorch/#automatic-backend-selection)
 
     === "Invoke v5.12 and later"
 
-        - If you are on Windows or Linux with an Nvidia GPU, use `https://download.pytorch.org/whl/cu128`.
-        - If you are on Linux with no GPU, use `https://download.pytorch.org/whl/cpu`.
-        - If you are on Linux with an AMD GPU, use `https://download.pytorch.org/whl/rocm6.2.4`.
-        - **In all other cases, do not use an index.**
+        - If you are on Windows or Linux with an Nvidia GPU, use `--torch-backend=cu128`.
+        - If you are on Linux with no GPU, use `--torch-backend=cpu`.
+        - If you are on Linux with an AMD GPU, use `--torch-backend=rocm6.3`.
+        - **In all other cases, do not use a torch backend.**
 
     === "Invoke v5.10.0 to v5.11.0"
 
-        - If you are on Windows or Linux with an Nvidia GPU, use `https://download.pytorch.org/whl/cu126`.
-        - If you are on Linux with no GPU, use `https://download.pytorch.org/whl/cpu`.
-        - If you are on Linux with an AMD GPU, use `https://download.pytorch.org/whl/rocm6.2.4`.
+        - If you are on Windows or Linux with an Nvidia GPU, use `--torch-backend=cu126`.
+        - If you are on Linux with no GPU, use `--torch-backend=cpu`.
+        - If you are on Linux with an AMD GPU, use `--torch-backend=rocm6.2.4`.
         - **In all other cases, do not use an index.**
 
     === "Invoke v5.0.0 to v5.9.1"
 
-        - If you are on Windows with an Nvidia GPU, use `https://download.pytorch.org/whl/cu124`.
-        - If you are on Linux with no GPU, use `https://download.pytorch.org/whl/cpu`.
-        - If you are on Linux with an AMD GPU, use `https://download.pytorch.org/whl/rocm6.1`.
+        - If you are on Windows with an Nvidia GPU, use `--torch-backend=cu124`.
+        - If you are on Linux with no GPU, use `--torch-backend=cpu`.
+        - If you are on Linux with an AMD GPU, use `--torch-backend=rocm6.1`.
         - **In all other cases, do not use an index.**
 
     === "Invoke v4"
 
-        - If you are on Windows with an Nvidia GPU, use `https://download.pytorch.org/whl/cu124`.
-        - If you are on Linux with no GPU, use `https://download.pytorch.org/whl/cpu`.
-        - If you are on Linux with an AMD GPU, use `https://download.pytorch.org/whl/rocm5.2`.
+        - If you are on Windows with an Nvidia GPU, use `--torch-backend=cu124`.
+        - If you are on Linux with no GPU, use `--torch-backend=cpu`.
+        - If you are on Linux with an AMD GPU, use `--torch-backend=rocm5.2`.
         - **In all other cases, do not use an index.**
 
 8. Install the `invokeai` package. Substitute the package specifier and version.
@@ -105,10 +105,10 @@ The following commands vary depending on the version of Invoke being installed a
     uv pip install <PACKAGE_SPECIFIER>==<VERSION> --python 3.12 --python-preference only-managed --force-reinstall
     ```
 
-    If you determined you needed to use a `PyPI` index URL in the previous step, you'll need to add `--index=<INDEX_URL>` like this:
+    If you determined you needed to use a torch backend in the previous step, you'll need to set the backend like this:
 
     ```sh
-    uv pip install <PACKAGE_SPECIFIER>==<VERSION> --python 3.12 --python-preference only-managed --index=<INDEX_URL> --force-reinstall
+    uv pip install <PACKAGE_SPECIFIER>==<VERSION> --python 3.12 --python-preference only-managed --torch-backend=<VERSION> --force-reinstall
     ```
 
 9. Deactivate and reactivate your venv so that the invokeai-specific commands become available in the environment:

docs/installation/patchmatch.md

@@ -70,7 +70,7 @@ Prior to installing PyPatchMatch, you need to take the following steps:
    `from patchmatch import patch_match`: It should look like the following:
 
    ```py
-   Python 3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0] on linux
+   Python 3.12.3 (main, Aug 14 2025, 17:47:21) [GCC 13.3.0] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> from patchmatch import patch_match
    Compiling and loading c extensions from "/home/lstein/Projects/InvokeAI/.invokeai-env/src/pypatchmatch/patchmatch".

docs/installation/quick_start.md

@@ -25,38 +25,65 @@ Hardware requirements vary significantly depending on model and image output siz
         - Memory: At least 16GB RAM.
         - Disk: 10GB for base installation plus 100GB for models.
 
-    === "FLUX - 1024×1024"
+    === "FLUX.1 - 1024×1024"
 
         - GPU: Nvidia 20xx series or later, 10GB+ VRAM.
         - Memory: At least 32GB RAM.
         - Disk: 10GB for base installation plus 200GB for models.
 
+    === "FLUX.2 Klein - 1024×1024"
+
+        - GPU: Nvidia 20xx series or later, 6GB+ VRAM for GGUF Q4 quantized models, 12GB+ for full precision.
+        - Memory: At least 16GB RAM.
+        - Disk: 10GB for base installation plus 20GB for models.
+
+    === "Z-Image Turbo - 1024x1024"
+        - GPU: Nvidia 20xx series or later, 8GB+ VRAM for the Q4_K quantized model. 16GB+ needed for the Q8 or BF16 models.
+        - Memory: At least 16GB RAM.
+        - Disk: 10GB for base installation plus 35GB for models.
+
+
 More detail on system requirements can be found [here](./requirements.md).
 
-## Step 2: Download
+## Step 2: Download and Set Up the Launcher
 
-Download the most recent launcher for your operating system:
+The Launcher manages your Invoke install. Follow these instructions to download and set up the Launcher.
 
-- [Download for Windows](https://download.invoke.ai/Invoke%20Community%20Edition.exe)
-- [Download for macOS](https://download.invoke.ai/Invoke%20Community%20Edition.dmg)
-- [Download for Linux](https://download.invoke.ai/Invoke%20Community%20Edition.AppImage)
+!!! info "Instructions for each OS"
 
-## Step 3: Install or Update
+    === "Windows"
 
-Run the launcher you just downloaded, click **Install** and follow the instructions to get set up.
+        - [Download for Windows](https://github.com/invoke-ai/launcher/releases/latest/download/Invoke.Community.Edition.Setup.latest.exe)
+        - Run the `EXE` to install the Launcher and start it.
+        - A desktop shortcut will be created; use this to run the Launcher in the future.
+        - You can delete the `EXE` file you downloaded.
+
+    === "macOS"
+
+        - [Download for macOS](https://github.com/invoke-ai/launcher/releases/latest/download/Invoke.Community.Edition-latest-arm64.dmg)
+        - Open the `DMG` and drag the app into `Applications`.
+        - Run the Launcher using its entry in `Applications`.
+        - You can delete the `DMG` file you downloaded.
+
+    === "Linux"
+
+        - [Download for Linux](https://github.com/invoke-ai/launcher/releases/latest/download/Invoke.Community.Edition-latest.AppImage)
+        - You may need to edit the `AppImage` file properties and make it executable.
+        - Optionally move the file to a location that does not require admin privileges and add a desktop shortcut for it.
+        - Run the Launcher by double-clicking the `AppImage` or the shortcut you made.
+
+## Step 3: Install Invoke
+
+Run the Launcher you just set up if you haven't already. Click **Install** and follow the instructions to install (or update) Invoke.
 
 If you have an existing Invoke installation, you can select it and let the launcher manage the install. You'll be able to update or launch the installation.
 
-!!! warning "Problem running the launcher on macOS"
+!!! tip "Updating"
 
-    macOS may not allow you to run the launcher. We are working to resolve this by signing the launcher executable. Until that is done, you can manually flag the launcher as safe:
+    The Launcher will check for updates for itself _and_ Invoke.
 
-    - Open the **Invoke Community Edition.dmg** file.
-    - Drag the launcher to **Applications**.
-    - Open a terminal.
-    - Run `xattr -d 'com.apple.quarantine' /Applications/Invoke\ Community\ Edition.app`.
-
-    You should now be able to run the launcher.
+    - When the Launcher detects an update is available for itself, you'll get a small popup window. Click through this and the Launcher will update itself.
+    - When the Launcher detects an update for Invoke, you'll see a small green alert in the Launcher. Click that and follow the instructions to update Invoke.
 
 ## Step 4: Launch
 

docs/installation/requirements.md

@@ -6,7 +6,9 @@ Invoke runs on Windows 10+, macOS 14+ and Linux (Ubuntu 20.04+ is well-tested).
 
 Hardware requirements vary significantly depending on model and image output size.
 
-The requirements below are rough guidelines for best performance. GPUs with less VRAM typically still work, if a bit slower. Follow the [Low-VRAM mode guide](./features/low-vram.md) to optimize performance.
+The requirements below are rough guidelines for best performance. GPUs
+with less VRAM typically still work, if a bit slower. Follow the
+[Low-VRAM mode guide](../features/low-vram.md) to optimize performance.
 
 - All Apple Silicon (M1, M2, etc) Macs work, but 16GB+ memory is recommended.
 - AMD GPUs are supported on Linux only. The VRAM requirements are the same as Nvidia GPUs.
@@ -25,12 +27,29 @@ The requirements below are rough guidelines for best performance. GPUs with less
         - Memory: At least 16GB RAM.
         - Disk: 10GB for base installation plus 100GB for models.
 
-    === "FLUX - 1024×1024"
+    === "FLUX.1 - 1024×1024"
 
         - GPU: Nvidia 20xx series or later, 10GB+ VRAM.
         - Memory: At least 32GB RAM.
         - Disk: 10GB for base installation plus 200GB for models.
 
+    === "FLUX.2 Klein 4B - 1024×1024"
+
+        - GPU: Nvidia 30xx series or later, 12GB+ VRAM (e.g. RTX 3090, RTX 4070). FP8 version works with 8GB+ VRAM.
+        - Memory: At least 16GB RAM.
+        - Disk: 10GB for base installation plus 20GB for models (Diffusers format with encoder).
+
+    === "FLUX.2 Klein 9B - 1024×1024"
+
+        - GPU: Nvidia 40xx series, 24GB+ VRAM (e.g. RTX 4090). FP8 version works with 12GB+ VRAM.
+        - Memory: At least 32GB RAM.
+        - Disk: 10GB for base installation plus 40GB for models (Diffusers format with encoder).
+
+    === "Z-Image Turbo - 1024x1024"
+        - GPU: Nvidia 20xx series or later, 8GB+ VRAM for the Q4_K quantized model. 16GB+ needed for the Q8 or BF16 models.
+        - Memory: At least 16GB RAM.
+        - Disk: 10GB for base installation plus 35GB for models.
+
 !!! info "`tmpfs` on Linux"
 
     If your temporary directory is mounted as a `tmpfs`, ensure it has sufficient space.
@@ -41,7 +60,7 @@ The requirements below are rough guidelines for best performance. GPUs with less
 
     You don't need to do this if you are installing with the [Invoke Launcher](./quick_start.md).
 
-Invoke requires python 3.10 through 3.12. If you don't already have one of these versions installed, we suggest installing 3.12, as it will be supported for longer.
+Invoke requires python 3.11 through 3.12. If you don't already have one of these versions installed, we suggest installing 3.12, as it will be supported for longer.
 
 Check that your system has an up-to-date Python installed by running `python3 --version` in the terminal (Linux, macOS) or cmd/powershell (Windows).
 
@@ -56,7 +75,7 @@ Check that your system has an up-to-date Python installed by running `python3 --
     === "macOS"
 
         - Install python with [an official installer].
-        - If model installs fail with a certificate error, you may need to run this command (changing the python version to match what you have installed): `/Applications/Python\ 3.10/Install\ Certificates.command`
+        - If model installs fail with a certificate error, you may need to run this command (changing the python version to match what you have installed): `/Applications/Python\ 3.11/Install\ Certificates.command`
         - If you haven't already, you will need to install the XCode CLI Tools by running `xcode-select --install` in a terminal.
 
     === "Linux"

docs/multiuser/admin_guide.md

@@ -0,0 +1,876 @@
+# InvokeAI Multi-User Administrator Guide
+
+## Overview
+
+This guide is for administrators managing a multi-user InvokeAI installation. It covers initial setup, user management, security best practices, and troubleshooting.
+
+## Prerequisites
+
+Before enabling multi-user support, ensure you have:
+
+- InvokeAI installed and running
+- Access to the server filesystem (for initial setup)
+- Understanding of your deployment environment
+- Backup of your existing data (recommended)
+
+## Initial Setup
+
+### Activating Multiuser Mode
+
+To put InvokeAI into multiuser mode, you will need to add the option
+`multiuser: true` to its configuration file. This file is located at
+`INVOKEAI_ROOT/invokeai.yaml` With the InvokeAI backend halted, add
+the new configuration option to the end of the file with a text editor
+so that it looks like this:
+
+```yaml
+# Internal metadata - do not edit:
+schema_version: 4.0.2
+
+# Enable/disable multi-user mode
+multiuser: true
+```
+
+Then restart the InvokeAI server backend from the command line or
+using the launcher.
+
+!!! note "Reverting to single-user mode"
+	If at any time you wish to revert to single-user mode, simply comment
+    out the `multiuser` line, or change "true" to "false". Then
+	restart the server. Because of the way that browsers cache pages,
+	users with open InvokeAI sessions may need to force-refresh their
+	browsers.
+	
+
+### First Administrator Account
+
+When InvokeAI starts for the first time in multi-user mode, you'll see the **Administrator Setup** dialog.
+
+**Setup Steps:**
+
+1. **Email Address**: Enter a valid email address (this becomes your username)
+
+    * Example: `admin@example.com` or `admin@localhost` for testing
+    * Must be a valid email format
+    * Cannot be changed later without database access
+
+2. **Display Name**: Enter a friendly name
+
+    * Example: "System Administrator" or your real name
+    * Can be changed later in your profile
+    * Visible to other users in shared contexts
+
+3. **Password**: Create a strong administrator password
+
+    * **Minimum requirements:**
+
+        * At least 8 characters long
+        * Contains uppercase letters (A-Z)
+        * Contains lowercase letters (a-z)
+        * Contains numbers (0-9)
+
+    * **Recommended:**
+
+        * Use 12+ characters
+        * Include special characters (!@#$%^&*)
+        * Use a password manager to generate and store
+        * Don't reuse passwords from other services
+
+4. **Confirm Password**: Re-enter the password
+
+5. Click **Create Administrator Account**
+
+!!! warning "Important" 
+    Store these credentials securely! The
+    first administrator account can reset 
+	the password to something new, but cannot 
+	retrieve a lost one.
+
+### Configuration
+
+InvokeAI can run in single-user or multi-user mode, controlled by the `multiuser` configuration option in `invokeai.yaml`:
+
+```yaml
+# Enable/disable multi-user mode
+multiuser: true   # Enable multi-user mode (requires authentication)
+# multiuser: false  # Single-user mode (no authentication required)
+# If the multiuser option is absent, single-user mode is used
+
+# Database configuration
+use_memory_db: false  # Use persistent database
+db_path: databases/invokeai.db  # Database location
+
+# Session configuration (multi-user mode only)
+jwt_secret_key: "your-secret-key-here"  # Auto-generated if not specified
+jwt_token_expiry_hours: 24  # Default session timeout
+jwt_remember_me_days: 7  # "Remember me" duration
+```
+
+**Single-User Mode** (`multiuser: false` or option absent):
+- No authentication required
+- All functionality enabled by default
+- All boards and images visible in unified view
+- Ideal for personal use or trusted environments
+
+**Multi-User Mode** (`multiuser: true`):
+- Authentication required for access
+- User isolation for boards, images, and workflows
+- Role-based permissions enforced
+- Ideal for shared servers or team environments
+
+!!! warning "Mode Switching Behavior"
+    **Switching to Single-User Mode:** If boards or images were created in multi-user mode, they will all be combined into a single unified view when switching to single-user mode.
+    
+    **Switching to Multi-User Mode:** Legacy boards and images created under single-user mode will be owned by an internal user named "system." Only the Administrator will have access to these legacy assets. A utility to migrate these legacy assets to another user will be part of a future release.
+
+### Migration from Single-User
+
+When upgrading from a single-user installation or switching modes:
+
+1. **Automatic Migration**: The database will automatically migrate to multi-user schema when multi-user mode is first enabled
+2. **Legacy Data Ownership**: Existing data (boards, images, workflows) created in single-user mode is assigned to an internal user named "system"
+3. **Administrator Access**: Only administrators will have access to legacy "system"-owned assets when in multi-user mode
+4. **No Data Loss**: All existing content is preserved
+
+**Migration Process:**
+
+```bash
+# Backup your database first
+cp databases/invokeai.db databases/invokeai.db.backup
+
+# Enable multi-user mode in invokeai.yaml
+# multiuser: true
+
+# Start InvokeAI (migration happens automatically)
+invokeai-web
+
+# Complete the administrator setup dialog
+# Legacy data will be owned by "system" user
+```
+
+!!! note "Legacy Asset Migration"
+    A utility to migrate legacy "system"-owned assets to specific user accounts will be available in a future release. Until then, administrators can access and manage all legacy content.
+
+## User Management
+
+### Creating Users
+
+**Via Web Interface (Coming Soon):**
+
+!!! info "Web UI for User Management"
+    A web-based user interface that allows administrators to manage users is coming in a future release. Until then, use the command-line scripts described below.
+
+**Via Command Line Scripts:**
+
+InvokeAI provides several command-line scripts in the `scripts/` directory for user management:
+
+**useradd.py** - Add a new user:
+
+```bash
+# Interactive mode (prompts for details)
+python scripts/useradd.py
+
+# Create a regular user
+python scripts/useradd.py \
+  --email user@example.com \
+  --password TempPass123 \
+  --name "User Name"
+
+# Create an administrator
+python scripts/useradd.py \
+  --email admin@example.com \
+  --password AdminPass123 \
+  --name "Admin Name" \
+  --admin
+```
+
+**userlist.py** - List all users:
+
+```bash
+# List all users
+python scripts/userlist.py
+
+# Show detailed information
+python scripts/userlist.py --verbose
+```
+
+**usermod.py** - Modify an existing user:
+
+```bash
+# Change display name
+python scripts/usermod.py --email user@example.com --name "New Name"
+
+# Promote to administrator
+python scripts/usermod.py --email user@example.com --admin
+
+# Demote from administrator
+python scripts/usermod.py --email user@example.com --no-admin
+
+# Deactivate account
+python scripts/usermod.py --email user@example.com --deactivate
+
+# Reactivate account
+python scripts/usermod.py --email user@example.com --activate
+
+# Change password
+python scripts/usermod.py --email user@example.com --password NewPassword123
+```
+
+**userdel.py** - Delete a user:
+
+```bash
+# Delete a user (prompts for confirmation)
+python scripts/userdel.py --email user@example.com
+
+# Delete without confirmation
+python scripts/userdel.py --email user@example.com --force
+```
+
+!!! tip "Script Usage"
+    Run any script with `--help` to see all available options:
+    ```bash
+    python scripts/useradd.py --help
+    ```
+
+!!! warning "Command Line Management"
+    - These scripts directly modify the database
+    - Always backup your database before making changes
+    - Changes take effect immediately (users may need to log in again)
+    - Deleting a user permanently removes all their content
+
+### Editing Users
+
+**Via Command Line:**
+
+Use `usermod.py` as described above to modify user properties.
+
+!!! warning "Last Administrator"
+    You cannot remove admin privileges from the last remaining administrator account.
+
+### Resetting User Passwords
+
+**Via Web Interface (Coming Soon):**
+
+Web-based password reset functionality for administrators is coming in a future release.
+
+**Via Command Line:**
+
+```bash
+# Reset a user's password
+python scripts/usermod.py --email user@example.com --password NewTempPassword123
+```
+
+**Security Note:** Never send passwords via email or unsecured channels. Use secure communication methods.
+
+### Deactivating Users
+
+**Via Command Line:**
+
+```bash
+# Deactivate a user account
+python scripts/usermod.py --email user@example.com --deactivate
+
+# Reactivate a user account
+python scripts/usermod.py --email user@example.com --activate
+```
+
+**Effects:**
+
+- User cannot log in when deactivated
+- Existing sessions are immediately invalidated
+- User's data is preserved
+- Can be reactivated at any time
+
+### Deleting Users
+
+**Via Command Line:**
+
+```bash
+# Delete a user (prompts for confirmation)
+python scripts/userdel.py --email user@example.com
+
+# Delete without confirmation prompt
+python scripts/userdel.py --email user@example.com --force
+```
+
+**Important:**
+
+- ⚠️ This action is **permanent**
+- User's boards, images, and workflows are deleted
+- Cannot be undone
+- Consider deactivating instead of deleting
+
+!!! warning "Data Loss"
+    Deleting a user permanently removes all their content. Back up the database first if recovery might be needed.
+
+### Viewing User Activity
+
+**Queue Management:**
+
+1. Navigate to **Admin** → **Queue Overview**
+2. View all users' active and pending generations
+3. Filter by user
+4. Cancel stuck or problematic tasks
+
+**User Statistics:**
+
+- Number of boards created
+- Number of images generated
+- Storage usage (if enabled)
+- Last login time
+
+## Model Management
+
+As an administrator, you have full access to model management.
+
+### Adding Models
+
+**Via Model Manager UI:**
+
+1. Go to **Models** tab
+2. Click **Add Model**
+3. Choose installation method:
+   - **From URL**: Provide HuggingFace repo or download URL
+   - **From Local Path**: Scan local directories
+   - **Import**: Import model from filesystem
+
+**Supported Model Types:**
+
+- Main models (Stable Diffusion, SDXL, FLUX)
+- LoRA models
+- ControlNet models
+- VAE models
+- Textual Inversions
+- IP-Adapters
+
+### Configuring Models
+
+**Model Settings:**
+
+- Display name
+- Description
+- Default generation settings (CFG, steps, scheduler)
+- Variant selection (fp16/fp32)
+- Model thumbnail image
+
+**Default Settings:**
+
+Set default parameters that users will start with:
+
+1. Select a model
+2. Go to **Default Settings** tab
+3. Configure:
+   - CFG Scale
+   - Steps
+   - Scheduler
+   - VAE selection
+4. Save settings
+
+### Removing Models
+
+1. Go to **Models** tab
+2. Select model(s) to remove
+3. Click **Delete**
+4. Confirm deletion
+
+!!! warning "Impact"
+    Removing a model affects all users who may be using it in workflows or saved settings.
+
+## Shared Boards
+
+Shared boards enable collaboration between users while maintaining control.
+
+!!! note "Future Feature"
+	Board sharing will be implemented in a future release.
+
+### Creating Shared Boards
+
+1. Log in as administrator
+2. Create a new board (or use existing board)
+3. Right-click the board → **Share Board**
+4. Add users and set permissions
+5. Click **Save Sharing Settings**
+
+### Permission Levels
+
+| Level | View | Add Images | Edit/Delete | Manage Sharing |
+|-------|------|------------|-------------|----------------|
+| **Read** | ✅ | ❌ | ❌ | ❌ |
+| **Write** | ✅ | ✅ | ✅ | ❌ |
+| **Admin** | ✅ | ✅ | ✅ | ✅ |
+
+**Permission Recommendations:**
+
+- **Read**: For viewers who should see but not modify content
+- **Write**: For active collaborators who add and organize images
+- **Admin**: For trusted users who help manage the shared board
+
+### Managing Shared Boards
+
+**Add Users to Shared Board:**
+
+1. Right-click shared board → **Manage Sharing**
+2. Click **Add User**
+3. Select user from dropdown
+4. Choose permission level
+5. Save changes
+
+**Remove Users from Shared Board:**
+
+1. Right-click shared board → **Manage Sharing**
+2. Find user in list
+3. Click **Remove**
+4. Confirm removal
+
+**Change User Permissions:**
+
+1. Right-click shared board → **Manage Sharing**
+2. Find user in list
+3. Change permission dropdown
+4. Save changes
+
+### Shared Board Best Practices
+
+- Give meaningful names to shared boards
+- Document the board's purpose in the description
+- Assign minimum necessary permissions
+- Regularly audit access lists
+- Remove users who no longer need access
+
+## Security
+
+### Password Policies
+
+**Enforced Requirements:**
+
+- Minimum 8 characters
+- Must contain uppercase letters
+- Must contain lowercase letters
+- Must contain numbers
+
+**Recommended Policies:**
+
+- Require 12+ character passwords
+- Include special characters
+- Implement password rotation every 90 days
+- Prevent password reuse
+- Use multi-factor authentication (when available)
+
+### Session Management
+
+**Session Security and Token Management:**
+
+This system uses stateless JWT tokens with HMAC signatures to
+identify users after they provide their initial credentials. The
+tokens will persist for 24 hours by default, or for 7 days if the user
+clicks the "Remember me" checkbox at login. Expired tokens are
+automatically rejected and the user will have to log in again.
+
+At the client side, tokens are stored in browser localStorage. Logging
+out clears them. No server-side session storage is required.
+
+The tokens include the user's ID, email, and admin status, along with
+an HMAC signature.
+
+### Secret Key Management
+
+**Important:** The JWT secret key must be kept confidential.
+
+To generate tokens, each InvokeAI instance has a distinct secret JWT key that must be
+kept confidential. The key is stored in the `app_settings` table of
+the InvokeAI database with in a field value named `jwt_secret`.
+
+The secret key is automatically generated during database creation or
+migration. If you wish to change the key, you may generate a
+replacement using either of these commands:
+
+
+```bash
+# Python
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+
+# OpenSSL
+openssl rand -base64 32
+```
+
+Then cut and paste the printed secret into this Sqlite3 command:
+
+```bash
+sqlite3 INVOKE_ROOT/databases/invokeai.db 'update app_settings set value="THE_SECRET" where key="jwt_secret"'
+```
+
+(replace INVOKE_ROOT with your InvokeAI root directory and THE_SECRET
+with the new secret).
+
+After this, restart the server. All logged in users will be logged out
+and will need to provide their usernames and passwords again.
+
+### Hosting a Shared InvokeAI Instance
+
+The multiuser feature allows you to run an InvokeAI backend that can
+be accessed by your friends and family across your home network. It is
+also possible to host a backend that is accessible over the Internet.
+
+By default, InvokeAI runs on `localhost`, IP address `127.0.0.1`,
+which is only accessible to browsers running on the same machine as
+the backend. To make the backend accessible to any machine on your
+home or work LAN, add the line `host: 0.0.0.0` to the InvokeAI
+configuration file, usually stored at `INVOKE_ROOT/invokeai.yaml`.
+
+Here is a minimal example.
+
+```yaml
+# Internal metadata - do not edit:
+schema_version: 4.0.2
+
+# Put user settings here - see https://invoke-ai.github.io/InvokeAI/configuration/:
+multiuser: true
+host: 0.0.0.0
+```
+
+After relaunching the backend you will be able to reach the server
+from other machines on the LAN using the server machine's IP address
+or hostname and port 9090.
+
+#### Connecting to the Internet
+
+!!! warning "Use at your own risk"
+	The InvokeAI team has done its best to make the software free of
+	exploitable bugs, but the software has not undergone a rigorous security
+	audit or intrusion testing. Use at your own risk
+
+It is also possible to create a (semi) public server accessible from
+the Internet. The details of how to do this depend very much on your
+home or corporate router/firewall system and are beyond the scope of
+this document. 
+
+If you expose InvokeAI to the Internet, there are a number of
+precautions to take. Here is a brief list of recommended network
+security practices.
+
+**HTTPS Configuration:**
+
+For internet deployments, always use HTTPS:
+
+```yaml
+# Use a reverse proxy like nginx or Traefik
+# Example nginx configuration:
+
+server {
+    listen 443 ssl http2;
+    server_name invoke.example.com;
+    
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    location / {
+        proxy_pass http://localhost:9090;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+**Firewall Rules:**
+
+It is best to restrict access to trusted networks and remote IP
+addresses, or use a VPN to connect to your home network. Rate limit
+connections to InvokeAI's authentication endpoint
+`http://your.host:9090/login`.
+
+**Backup and Recovery:**
+
+It is a good idea to periodically backup your InvokeAI database,
+images, and possibly models in the event of unauthorized use of a
+publicly-accessible server.
+
+**Manual Backup:**
+
+```bash
+# Stop InvokeAI
+# Copy database file
+cd INVOKE_ROOT
+cp databases/invokeai.db databases/invokeai.db.$(date +%Y%m%d)
+
+# Or create compressed backup
+tar -czf invokeai_backup_$(date +%Y%m%d).tar.gz databases/
+```
+
+**Automated Backup Script:**
+
+```bash
+#!/bin/bash
+# backup_invokeai.sh
+
+INVOKE_ROOT="/path/to/invoke_root"
+BACKUP_DIR="/path/to/backups"
+DB_PATH="$INVOKE_ROOT/databases/invokeai.db"
+DATE=$(date +%Y%m%d_%H%M%S)
+
+# Create backup directory
+mkdir -p "$BACKUP_DIR"
+
+# Copy database
+cp "$DB_PATH" "$BACKUP_DIR/invokeai_$DATE.db"
+
+# Keep only last 30 days
+find "$BACKUP_DIR" -name "invokeai_*.db" -mtime +30 -delete
+
+echo "Backup completed: invokeai_$DATE.db"
+```
+
+**Schedule with cron:**
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add daily backup at 2 AM
+0 2 * * * /path/to/backup_invokeai.sh
+```
+
+
+
+```bash
+# Stop InvokeAI
+# Replace current database with backup
+cd INVOKE_ROOT
+cp databases/invokeai.db databases/invokeai.db.old  # Save current
+cp databases/invokeai_backup.db databases/invokeai.db
+
+# Restart InvokeAI
+invokeai-web
+```
+
+**Disaster Recover - Complete System Backup:**
+
+Include these directories/files:
+
+- `databases/` - All database files
+- `models/` - Installed models (if locally stored)
+- `outputs/` - Generated images
+- `invokeai.yaml` - Configuration file
+- Any custom scripts or modifications
+
+**Recovery Process:**
+
+1. Install InvokeAI on new system
+2. Restore configuration file
+3. Restore database directory
+4. Restore models and outputs
+5. Verify file permissions
+6. Start InvokeAI and test
+
+## Troubleshooting
+
+### User Cannot Login
+
+**Symptom:** User reports unable to log in
+
+**Diagnosis:**
+
+1. Verify account exists and is active
+   ```bash
+   sqlite3 databases/invokeai.db "SELECT * FROM users WHERE email = 'user@example.com';"
+   ```
+
+2. Check password (have user try resetting)
+3. Verify account is active (`is_active = 1`)
+4. Check for account lockout (if implemented)
+
+**Solutions:**
+
+- Reset user password
+- Reactivate disabled account
+- Verify email address is correct
+- Check system logs for auth errors
+
+### Database Locked Errors
+
+**Symptom:** "Database is locked" errors
+
+**Causes:**
+
+- Concurrent write operations
+- Long-running transactions
+- Backup process accessing database
+- File system issues
+
+**Solutions:**
+
+```bash
+# Check for locks
+fuser databases/invokeai.db
+
+# Increase timeout (in config)
+# Or switch to WAL mode:
+sqlite3 databases/invokeai.db "PRAGMA journal_mode=WAL;"
+```
+
+### Forgotten Admin Password
+
+**Recovery Process:**
+
+1. Stop InvokeAI
+2. Direct database access:
+   ```bash
+   sqlite3 databases/invokeai.db
+   ```
+
+3. Reset admin password (requires password hash):
+   ```sql
+   -- Generate hash first using Python:
+   -- from passlib.context import CryptContext
+   -- pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+   -- print(pwd_context.hash("NewPassword123"))
+   
+   UPDATE users 
+   SET password_hash = '$2b$12$...' 
+   WHERE email = 'admin@example.com';
+   ```
+
+4. Restart InvokeAI
+
+**Alternative:** Remove `jwt_secret_key` from config to trigger setup wizard (will create new admin).
+
+### Performance Issues
+
+**Symptom:** Slow generation or UI
+
+**Diagnosis:**
+
+1. Check active generation count
+2. Review resource usage (CPU/GPU/RAM)
+3. Check database size and performance
+4. Review network latency
+
+**Solutions:**
+
+- Limit concurrent generations
+- Increase hardware resources
+- Optimize database (`VACUUM`, `ANALYZE`)
+- Add indexes for slow queries
+- Consider load balancing
+
+### Migration Failures
+
+**Symptom:** Database migration fails on upgrade
+
+**Prevention:**
+
+- Always backup before upgrading
+- Test migration on copy of database
+- Review migration logs
+
+**Recovery:**
+
+```bash
+# Restore backup
+cp databases/invokeai.db.backup databases/invokeai.db
+
+# Try migration again with verbose logging
+invokeai-web --log-level DEBUG
+```
+
+## Configuration Reference
+
+### Complete Configuration Example for a Public Site
+
+```yaml
+# invokeai.yaml - Multi-user configuration
+
+# Internal metadata - do not edit:
+schema_version: 4.0.2
+
+# Put user settings here
+multiuser: true
+
+# Server
+host: "0.0.0.0"
+port: 9090
+
+# Performance
+enable_partial_loading: true
+precision: float16
+pytorch_cuda_alloc_conf: "backend:cudaMallocAsync"
+hashing_algorithm: blake3_multi
+```
+## Frequently Asked Questions
+
+### How many users can InvokeAI support?
+
+The backend will support dozens of concurrent users. However, because
+the image generation queue is single-threaded, image generation tasks
+are processed on a first-come, first-serve basis. This means that a
+user may have to wait for all the other users' image generation jobs
+to complete before their generation job starts to execute.
+
+A future version of InvokeAI may support concurrent execution on
+systems with multiple GPUs/graphics cards.
+
+### Can I integrate with existing authentication systems?
+
+OAuth2/OpenID Connect support is planned for a future release. Currently, InvokeAI uses its own authentication system.
+
+### How do I audit user actions?
+
+Full audit logging is planned for a future release. Currently, you can:
+
+- Monitor the generation queue
+- Review database changes
+- Check application logs
+
+### Can users have different model access?
+
+Not in the current release. All users can view and use all installed models. Per-user model access is a possible enhancement.
+
+### How do I handle user data when they leave?
+
+Best practice:
+
+1. Deactivate the account first
+2. Transfer ownership of shared boards
+3. After transition period, delete the account
+4. Or keep the account deactivated for audit purposes
+
+### What's the licensing impact of multi-user mode?
+
+InvokeAI remains under its existing license. Multi-user mode does not change licensing terms.
+
+## Getting Help
+
+### Support Resources
+
+- **Documentation**: [InvokeAI Docs](https://invoke-ai.github.io/InvokeAI/)
+- **Discord**: [Join Community](https://discord.gg/ZmtBAhwWhy)
+- **GitHub Issues**: [Report Problems](https://github.com/invoke-ai/InvokeAI/issues)
+- **User Guide**: [For Users](user_guide.md)
+- **API Guide**: [For Developers](api_guide.md)
+
+### Reporting Issues
+
+When reporting administrator issues, include:
+
+- InvokeAI version
+- Operating system and version
+- Database size and user count
+- Relevant log excerpts
+- Steps to reproduce
+- Expected vs actual behavior
+
+## Additional Resources
+
+- [User Guide](user_guide.md) - For end users
+- [API Guide](api_guide.md) - For API consumers
+- [Multiuser Specification](specification.md) - Technical details
+
+---
+
+**Need additional assistance?** Visit the [InvokeAI Discord](https://discord.gg/ZmtBAhwWhy) or file an issue on [GitHub](https://github.com/invoke-ai/InvokeAI/issues).

docs/multiuser/specification.md

@@ -0,0 +1,870 @@
+# InvokeAI Multi-User Support - Detailed Specification
+
+## 1. Executive Summary
+
+This document provides a comprehensive specification for adding multi-user support to InvokeAI. The feature will enable a single InvokeAI instance to support multiple isolated users, each with their own generation settings, image boards, and workflows, while maintaining administrative controls for model management and system configuration.
+
+## 2. Overview
+
+### 2.1 Goals
+- Enable multiple users to share a single InvokeAI instance
+- Provide user isolation for personal content (boards, images, workflows, settings)
+- Maintain centralized model management by administrators
+- Support shared boards for collaboration
+- Provide secure authentication and authorization
+- Minimize impact on existing single-user installations
+
+### 2.2 Non-Goals
+- Real-time collaboration features (multiple users editing same workflow simultaneously)
+- Advanced team management features (in initial release)
+- Migration of existing multi-user enterprise edition data
+- Support for external identity providers (in initial release, can be added later)
+
+## 3. User Roles and Permissions
+
+### 3.1 Administrator Role
+**Capabilities:**
+
+- Full access to all InvokeAI features
+- Model management (add, delete, configure models)
+- User management (create, edit, delete users)
+- View and manage all users' queue sessions
+- Access system configuration
+- Create and manage shared boards
+- Grant/revoke administrative privileges to other users
+
+**Restrictions:**
+
+- Cannot delete their own account if they are the last administrator
+- Cannot revoke their own admin privileges if they are the last administrator
+
+### 3.2 Regular User Role
+**Capabilities:**
+
+- Create, edit, and delete their own image boards
+- Upload and manage their own assets
+- Use all image generation tools (linear, canvas, upscale, workflow tabs)
+- Create, edit, save, and load workflows
+- Access public/shared workflows
+- View and manage their own queue sessions
+- Adjust personal UI preferences (theme, hotkeys, etc.)
+- Access shared boards (read/write based on permissions)
+- **View model configurations** (read-only access to model manager)
+- **View model details, default settings, and metadata**
+
+**Restrictions:**
+
+- Cannot add, delete, or edit models
+- **Can view but cannot modify model manager settings** (read-only access)
+- Cannot reidentify, convert, or update model paths
+- Cannot upload or change model thumbnail images
+- Cannot save changes to model default settings
+- Cannot perform bulk delete operations on models
+- Cannot view or modify other users' boards, images, or workflows
+- Cannot cancel or modify other users' queue sessions
+- Cannot access system configuration
+- Cannot manage users or permissions
+
+### 3.3 Future Role Considerations
+- **Viewer Role**: Read-only access (future enhancement)
+- **Team/Group-based Permissions**: Organizational hierarchy (future enhancement)
+
+## 4. Authentication System
+
+### 4.1 Authentication Method
+- **Primary Method**: Username and password authentication with secure password hashing
+- **Password Hashing**: Use bcrypt or Argon2 for password storage
+- **Session Management**: JWT tokens or secure session cookies
+- **Token Expiration**: Configurable session timeout (default: 7 days for "remember me", 24 hours otherwise)
+
+### 4.2 Initial Administrator Setup
+**First-time Launch Flow:**
+
+1. Application detects no administrator account exists
+2. Displays mandatory setup dialog (cannot be skipped)
+3. Prompts for:
+   - Administrator username (email format recommended)
+   - Administrator display name
+   - Strong password (minimum requirements enforced)
+   - Password confirmation
+4. Stores hashed credentials in configuration
+5. Creates administrator account in database
+6. Proceeds to normal login screen
+
+**Reset Capability:**
+
+- Administrators can be reset by manually editing the config file
+- Requires access to server filesystem (intentional security measure)
+- Database maintains user records; config file contains root admin credentials
+
+### 4.3 Password Requirements
+- Minimum 8 characters
+- At least one uppercase letter
+- At least one lowercase letter
+- At least one number
+- At least one special character (optional but recommended)
+- Not in common password list
+
+### 4.4 Login Flow
+
+1. User navigates to InvokeAI URL
+2. If not authenticated, redirect to login page
+3. User enters username/email and password
+4. Optional "Remember me" checkbox for extended session
+5. Backend validates credentials
+6. On success: Generate session token, redirect to application
+7. On failure: Display error, allow retry with rate limiting (prevent brute force)
+
+### 4.5 Logout Flow
+- User clicks logout button
+- Frontend clears session token
+- Backend invalidates session (if using server-side sessions)
+- Redirect to login page
+
+### 4.6 Future Authentication Enhancements
+- OAuth2/OpenID Connect support
+- Two-factor authentication (2FA)
+- SSO integration
+- API key authentication for programmatic access
+
+## 5. User Management
+
+### 5.1 User Creation (Administrator)
+**Flow:**
+
+1. Administrator navigates to user management interface
+2. Clicks "Add User" button
+3. Enters user information:
+   - Email address (required, used as username)
+   - Display name (optional, defaults to email)
+   - Role (User or Administrator)
+   - Initial password or "Send invitation email"
+4. System validates email uniqueness
+5. System creates user account
+6. If invitation mode:
+   - Generate one-time secure token
+   - Send email with setup link
+   - Link expires after 7 days
+7. If direct password mode:
+   - Administrator provides initial password
+   - User must change on first login
+
+**Invitation Email Flow:**
+
+1. User receives email with unique link
+2. Link contains secure token
+3. User clicks link, redirected to setup page
+4. User enters desired password
+5. Token validated and consumed (single-use)
+6. Account activated
+7. User redirected to login page
+
+### 5.2 User Profile Management
+**User Self-Service:**
+
+- Update display name
+- Change password (requires current password)
+- Update email address (requires verification)
+- Manage UI preferences
+- View account creation date and last login
+
+**Administrator Actions:**
+
+- Edit user information (name, email)
+- Reset user password (generates reset link)
+- Toggle administrator privileges
+- Assign to groups (future feature)
+- Suspend/unsuspend account
+- Delete account (with data retention options)
+
+### 5.3 Password Reset Flow
+**User-Initiated (Future Enhancement):**
+
+1. User clicks "Forgot Password" on login page
+2. Enters email address
+3. System sends password reset link (if email exists)
+4. User clicks link, enters new password
+5. Password updated, user can login
+
+**Administrator-Initiated:**
+
+1. Administrator selects user
+2. Clicks "Send Password Reset"
+3. System generates reset token and link
+4. Email sent to user
+5. User follows same flow as user-initiated reset
+
+## 6. Data Model and Database Schema
+
+### 6.1 New Tables
+
+#### 6.1.1 users
+```sql
+CREATE TABLE users (
+    user_id TEXT NOT NULL PRIMARY KEY,
+    email TEXT NOT NULL UNIQUE,
+    display_name TEXT,
+    password_hash TEXT NOT NULL,
+    is_admin BOOLEAN NOT NULL DEFAULT FALSE,
+    is_active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+    updated_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+    last_login_at DATETIME
+);
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_is_admin ON users(is_admin);
+CREATE INDEX idx_users_is_active ON users(is_active);
+```
+
+#### 6.1.2 user_sessions
+```sql
+CREATE TABLE user_sessions (
+    session_id TEXT NOT NULL PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    expires_at DATETIME NOT NULL,
+    created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+    last_activity_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+    user_agent TEXT,
+    ip_address TEXT,
+    FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+);
+CREATE INDEX idx_user_sessions_user_id ON user_sessions(user_id);
+CREATE INDEX idx_user_sessions_expires_at ON user_sessions(expires_at);
+CREATE INDEX idx_user_sessions_token_hash ON user_sessions(token_hash);
+```
+
+#### 6.1.3 user_invitations
+```sql
+CREATE TABLE user_invitations (
+    invitation_id TEXT NOT NULL PRIMARY KEY,
+    email TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    invited_by_user_id TEXT NOT NULL,
+    expires_at DATETIME NOT NULL,
+    used_at DATETIME,
+    created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+    FOREIGN KEY (invited_by_user_id) REFERENCES users(user_id) ON DELETE CASCADE
+);
+CREATE INDEX idx_user_invitations_email ON user_invitations(email);
+CREATE INDEX idx_user_invitations_token_hash ON user_invitations(token_hash);
+CREATE INDEX idx_user_invitations_expires_at ON user_invitations(expires_at);
+```
+
+#### 6.1.4 shared_boards
+```sql
+CREATE TABLE shared_boards (
+    board_id TEXT NOT NULL,
+    user_id TEXT NOT NULL,
+    permission TEXT NOT NULL CHECK(permission IN ('read', 'write', 'admin')),
+    created_at DATETIME NOT NULL DEFAULT(STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+    PRIMARY KEY (board_id, user_id),
+    FOREIGN KEY (board_id) REFERENCES boards(board_id) ON DELETE CASCADE,
+    FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+);
+CREATE INDEX idx_shared_boards_user_id ON shared_boards(user_id);
+CREATE INDEX idx_shared_boards_board_id ON shared_boards(board_id);
+```
+
+### 6.2 Modified Tables
+
+#### 6.2.1 boards
+```sql
+-- Add columns:
+ALTER TABLE boards ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE boards ADD COLUMN is_shared BOOLEAN NOT NULL DEFAULT FALSE;
+ALTER TABLE boards ADD COLUMN created_by_user_id TEXT;
+
+-- Add foreign key (requires recreation in SQLite):
+FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+FOREIGN KEY (created_by_user_id) REFERENCES users(user_id) ON DELETE SET NULL
+
+-- Add indices:
+CREATE INDEX idx_boards_user_id ON boards(user_id);
+CREATE INDEX idx_boards_is_shared ON boards(is_shared);
+```
+
+#### 6.2.2 images
+```sql
+-- Add column:
+ALTER TABLE images ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
+
+-- Add foreign key:
+FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+
+-- Add index:
+CREATE INDEX idx_images_user_id ON images(user_id);
+```
+
+#### 6.2.3 workflows
+```sql
+-- Add columns:
+ALTER TABLE workflows ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE workflows ADD COLUMN is_public BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- Add foreign key:
+FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+
+-- Add indices:
+CREATE INDEX idx_workflows_user_id ON workflows(user_id);
+CREATE INDEX idx_workflows_is_public ON workflows(is_public);
+```
+
+#### 6.2.4 session_queue
+```sql
+-- Add column:
+ALTER TABLE session_queue ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
+
+-- Add foreign key:
+FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+
+-- Add index:
+CREATE INDEX idx_session_queue_user_id ON session_queue(user_id);
+```
+
+#### 6.2.5 style_presets
+```sql
+-- Add columns:
+ALTER TABLE style_presets ADD COLUMN user_id TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE style_presets ADD COLUMN is_public BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- Add foreign key:
+FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+
+-- Add indices:
+CREATE INDEX idx_style_presets_user_id ON style_presets(user_id);
+CREATE INDEX idx_style_presets_is_public ON style_presets(is_public);
+```
+
+### 6.3 Migration Strategy
+
+1. Create new user tables (users, user_sessions, user_invitations, shared_boards)
+2. Create default 'system' user for backward compatibility
+3. Update existing data to reference 'system' user
+4. Add foreign key constraints
+5. Version as database migration (e.g., migration_25.py)
+
+### 6.4 Migration for Existing Installations
+- Single-user installations: Prompt to create admin account on first launch after update
+- Existing data migration: Administrator can specify an arbitrary user account to hold legacy data (can be the admin account or a separate user)
+- System provides UI during migration to choose destination user for existing data
+
+## 7. API Endpoints
+
+### 7.1 Authentication Endpoints
+
+#### POST /api/v1/auth/setup
+- Initialize first administrator account
+- Only works if no admin exists
+- Body: `{ email, display_name, password }`
+- Response: `{ success, user }`
+
+#### POST /api/v1/auth/login
+- Authenticate user
+- Body: `{ email, password, remember_me? }`
+- Response: `{ token, user, expires_at }`
+
+#### POST /api/v1/auth/logout
+- Invalidate current session
+- Headers: `Authorization: Bearer <token>`
+- Response: `{ success }`
+
+#### GET /api/v1/auth/me
+- Get current user information
+- Headers: `Authorization: Bearer <token>`
+- Response: `{ user }`
+
+#### POST /api/v1/auth/change-password
+- Change current user's password
+- Body: `{ current_password, new_password }`
+- Headers: `Authorization: Bearer <token>`
+- Response: `{ success }`
+
+### 7.2 User Management Endpoints (Admin Only)
+
+#### GET /api/v1/users
+- List all users (paginated)
+- Query params: `offset`, `limit`, `search`, `role_filter`
+- Response: `{ users[], total, offset, limit }`
+
+#### POST /api/v1/users
+- Create new user
+- Body: `{ email, display_name, is_admin, send_invitation?, initial_password? }`
+- Response: `{ user, invitation_link? }`
+
+#### GET /api/v1/users/{user_id}
+- Get user details
+- Response: `{ user }`
+
+#### PATCH /api/v1/users/{user_id}
+- Update user
+- Body: `{ display_name?, is_admin?, is_active? }`
+- Response: `{ user }`
+
+#### DELETE /api/v1/users/{user_id}
+- Delete user
+- Query params: `delete_data` (true/false)
+- Response: `{ success }`
+
+#### POST /api/v1/users/{user_id}/reset-password
+- Send password reset email
+- Response: `{ success, reset_link }`
+
+### 7.3 Shared Boards Endpoints
+
+#### POST /api/v1/boards/{board_id}/share
+- Share board with users
+- Body: `{ user_ids[], permission: 'read' | 'write' | 'admin' }`
+- Response: `{ success, shared_with[] }`
+
+#### GET /api/v1/boards/{board_id}/shares
+- Get board sharing information
+- Response: `{ shares[] }`
+
+#### DELETE /api/v1/boards/{board_id}/share/{user_id}
+- Remove board sharing
+- Response: `{ success }`
+
+### 7.4 Modified Endpoints
+
+All existing endpoints will be modified to:
+
+1. Require authentication (except setup/login)
+2. Filter data by current user (unless admin viewing all)
+3. Enforce permissions (e.g., model management requires admin)
+4. Include user context in operations
+
+Example modifications:
+- `GET /api/v1/boards` → Returns only user's boards + shared boards
+- `POST /api/v1/session/queue` → Associates queue item with current user
+- `GET /api/v1/queue` → Returns all items for admin, only user's items for regular users
+
+## 8. Frontend Changes
+
+### 8.1 New Components
+
+#### LoginPage
+- Email/password form
+- "Remember me" checkbox
+- Login button
+- Forgot password link (future)
+- Branding and welcome message
+
+#### AdministratorSetup
+- Modal dialog (cannot be dismissed)
+- Administrator account creation form
+- Password strength indicator
+- Terms/welcome message
+
+#### UserManagementPage (Admin only)
+- User list table
+- Add user button
+- User actions (edit, delete, reset password)
+- Search and filter
+- Role toggle
+
+#### UserProfilePage
+- Display user information
+- Change password form
+- UI preferences
+- Account details
+
+#### BoardSharingDialog
+- User picker/search
+- Permission selector
+- Share button
+- Current shares list
+
+### 8.2 Modified Components
+
+#### App Root
+- Add authentication check
+- Redirect to login if not authenticated
+- Handle session expiration
+- Add global error boundary for auth errors
+
+#### Navigation/Header
+- Add user menu with logout
+- Display current user name
+- Admin indicator badge
+
+#### ModelManagerTab
+- Hide/disable for non-admin users
+- Show "Admin only" message
+
+#### QueuePanel
+- Filter by current user (for non-admin)
+- Show all with user indicators (for admin)
+- Disable actions on other users' items (for non-admin)
+
+#### BoardsPanel
+- Show personal boards section
+- Show shared boards section
+- Add sharing controls to board actions
+
+### 8.3 State Management
+
+New Redux slices/zustand stores:
+- `authSlice`: Current user, authentication status, token
+- `usersSlice`: User list for admin interface
+- `sharingSlice`: Board sharing state
+
+Updated slices:
+- `boardsSlice`: Include shared boards, ownership info
+- `queueSlice`: Include user filtering
+- `workflowsSlice`: Include public/private status
+
+## 9. Configuration
+
+### 9.1 New Config Options
+
+Add to `InvokeAIAppConfig`:
+
+```python
+# Authentication
+auth_enabled: bool = True  # Enable/disable multi-user auth
+session_expiry_hours: int = 24  # Default session expiration
+session_expiry_hours_remember: int = 168  # "Remember me" expiration (7 days)
+password_min_length: int = 8  # Minimum password length
+require_strong_passwords: bool = True  # Enforce password complexity
+
+# Session tracking
+enable_server_side_sessions: bool = False  # Optional server-side session tracking
+
+# Audit logging
+audit_log_auth_events: bool = True  # Log authentication events
+audit_log_admin_actions: bool = True  # Log administrative actions
+
+# Email (optional - for invitations and password reset)
+email_enabled: bool = False
+smtp_host: str = ""
+smtp_port: int = 587
+smtp_username: str = ""
+smtp_password: str = ""
+smtp_from_address: str = ""
+smtp_from_name: str = "InvokeAI"
+
+# Initial admin (stored as hash)
+admin_email: Optional[str] = None
+admin_password_hash: Optional[str] = None
+```
+
+### 9.2 Backward Compatibility
+
+- If `auth_enabled = False`, system runs in legacy single-user mode
+- All data belongs to implicit "system" user
+- No authentication required
+- Smooth upgrade path for existing installations
+
+## 10. Security Considerations
+
+### 10.1 Password Security
+- Never store passwords in plain text
+- Use bcrypt or Argon2id for password hashing
+- Implement proper salt generation
+- Enforce password complexity requirements
+- Implement rate limiting on login attempts
+- Consider password breach checking (Have I Been Pwned API)
+
+### 10.2 Session Security
+- Use cryptographically secure random tokens
+- Implement token rotation
+- Set appropriate cookie flags (HttpOnly, Secure, SameSite)
+- Implement session timeout and renewal
+- Invalidate sessions on logout
+- Clean up expired sessions periodically
+
+### 10.3 Authorization
+- Always verify user identity from session token (never trust client)
+- Check permissions on every API call
+- Implement principle of least privilege
+- Validate user ownership of resources before operations
+- Implement proper error messages (avoid information leakage)
+
+### 10.4 Data Isolation
+- Strict separation of user data in database queries
+- Prevent SQL injection via parameterized queries
+- Validate all user inputs
+- Implement proper access control checks
+- Audit trail for sensitive operations
+
+### 10.5 API Security
+- Implement rate limiting on sensitive endpoints
+- Use HTTPS in production (enforce via config)
+- Implement CSRF protection
+- Validate and sanitize all inputs
+- Implement proper CORS configuration
+- Add security headers (CSP, X-Frame-Options, etc.)
+
+### 10.6 Deployment Security
+- Document secure deployment practices
+- Recommend reverse proxy configuration (nginx, Apache)
+- Provide example configurations for HTTPS
+- Document firewall requirements
+- Recommend network isolation strategies
+
+## 11. Email Integration (Optional)
+
+**Note**: Email/SMTP configuration is optional. Many administrators will not have ready access to an outgoing SMTP server. When email is not configured, the system provides fallback mechanisms by displaying setup links directly in the admin UI.
+
+### 11.1 Email Templates
+
+#### User Invitation
+```
+Subject: You've been invited to InvokeAI
+
+Hello,
+
+You've been invited to join InvokeAI by [Administrator Name].
+
+Click the link below to set up your account:
+[Setup Link]
+
+This link expires in 7 days.
+
+---
+InvokeAI
+```
+
+#### Password Reset
+```
+Subject: Reset your InvokeAI password
+
+Hello [User Name],
+
+A password reset was requested for your account.
+
+Click the link below to reset your password:
+[Reset Link]
+
+This link expires in 24 hours.
+
+If you didn't request this, please ignore this email.
+
+---
+InvokeAI
+```
+
+### 11.2 Email Service
+- Support SMTP configuration
+- Use secure connection (TLS)
+- Handle email failures gracefully
+- Implement email queue for reliability
+- Log email activities (without sensitive data)
+- Provide fallback for no-email deployments (show links in admin UI)
+
+## 12. Testing Requirements
+
+### 12.1 Unit Tests
+- Authentication service (password hashing, validation)
+- Authorization checks
+- Token generation and validation
+- User management operations
+- Shared board permissions
+- Data isolation queries
+
+### 12.2 Integration Tests
+- Complete authentication flows
+- User creation and invitation
+- Password reset flow
+- Multi-user data isolation
+- Shared board access
+- Session management
+- Admin operations
+
+### 12.3 Security Tests
+- SQL injection prevention
+- XSS prevention
+- CSRF protection
+- Session hijacking prevention
+- Brute force protection
+- Authorization bypass attempts
+
+### 12.4 Performance Tests
+- Authentication overhead
+- Query performance with user filters
+- Concurrent user sessions
+- Database scalability with many users
+
+## 13. Documentation Requirements
+
+### 13.1 User Documentation
+- Getting started with multi-user InvokeAI
+- Login and account management
+- Using shared boards
+- Understanding permissions
+- Troubleshooting authentication issues
+
+### 13.2 Administrator Documentation
+- Setting up multi-user InvokeAI
+- User management guide
+- Creating and managing shared boards
+- Email configuration
+- Security best practices
+- Backup and restore with user data
+
+### 13.3 Developer Documentation
+- Authentication architecture
+- API authentication requirements
+- Adding new multi-user features
+- Database schema changes
+- Testing multi-user features
+
+### 13.4 Migration Documentation
+- Upgrading from single-user to multi-user
+- Data migration strategies
+- Rollback procedures
+- Common issues and solutions
+
+## 14. Future Enhancements
+
+### 14.1 Phase 2 Features
+- **OAuth2/OpenID Connect integration** (deferred from initial release to keep scope manageable)
+- Two-factor authentication
+- API keys for programmatic access
+- Enhanced team/group management
+- Advanced permission system (roles and capabilities)
+
+### 14.2 Phase 3 Features
+- SSO integration (SAML, LDAP)
+- User quotas and limits
+- Resource usage tracking
+- Advanced collaboration features
+- Workflow template library with permissions
+- Model access controls per user/group
+
+## 15. Success Metrics
+
+### 15.1 Functionality Metrics
+- Successful user authentication rate
+- Zero unauthorized data access incidents
+- All tests passing (unit, integration, security)
+- API response time within acceptable limits
+
+### 15.2 Usability Metrics
+- User setup completion time < 2 minutes
+- Login time < 2 seconds
+- Clear error messages for all auth failures
+- Positive user feedback on multi-user features
+
+### 15.3 Security Metrics
+- No critical security vulnerabilities identified
+- CodeQL scan passes
+- Penetration testing completed
+- Security best practices followed
+
+## 16. Risks and Mitigations
+
+### 16.1 Technical Risks
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| Performance degradation with user filtering | Medium | Low | Index optimization, query caching |
+| Database migration failures | High | Low | Thorough testing, rollback procedures |
+| Session management complexity | Medium | Medium | Use proven libraries (PyJWT), extensive testing |
+| Auth bypass vulnerabilities | High | Low | Security review, penetration testing |
+
+### 16.2 UX Risks
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| Confusion in migration for existing users | Medium | High | Clear documentation, migration wizard |
+| Friction from additional login step | Low | High | Remember me option, long session timeout |
+| Complexity of admin interface | Medium | Medium | Intuitive UI design, user testing |
+
+### 16.3 Operational Risks
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| Email delivery failures | Low | Medium | Show links in UI, document manual methods |
+| Lost admin password | High | Low | Document recovery procedure, config reset |
+| User data conflicts in migration | Medium | Low | Data validation, backup requirements |
+
+## 17. Implementation Phases
+
+### Phase 1: Foundation (Weeks 1-2)
+- Database schema design and migration
+- Basic authentication service
+- Password hashing and validation
+- Session management
+
+### Phase 2: Backend API (Weeks 3-4)
+- Authentication endpoints
+- User management endpoints
+- Authorization middleware
+- Update existing endpoints with auth
+
+### Phase 3: Frontend Auth (Weeks 5-6)
+- Login page and flow
+- Administrator setup
+- Session management
+- Auth state management
+
+### Phase 4: Multi-tenancy (Weeks 7-9)
+- User isolation in all services
+- Shared boards implementation
+- Queue permission filtering
+- Workflow public/private
+
+### Phase 5: Admin Interface (Weeks 10-11)
+- User management UI
+- Board sharing UI
+- Admin-specific features
+- User profile page
+
+### Phase 6: Testing & Polish (Weeks 12-13)
+- Comprehensive testing
+- Security audit
+- Performance optimization
+- Documentation
+- Bug fixes
+
+### Phase 7: Beta & Release (Week 14+)
+- Beta testing with selected users
+- Feedback incorporation
+- Final testing
+- Release preparation
+- Documentation finalization
+
+## 18. Acceptance Criteria
+
+- [ ] Administrator can set up initial account on first launch
+- [ ] Users can log in with email and password
+- [ ] Users can change their password
+- [ ] Administrators can create, edit, and delete users
+- [ ] User data is properly isolated (boards, images, workflows)
+- [ ] Shared boards work correctly with permissions
+- [ ] Non-admin users cannot access model management
+- [ ] Queue filtering works correctly for users and admins
+- [ ] Session management works correctly (expiry, renewal, logout)
+- [ ] All security tests pass
+- [ ] API documentation is updated
+- [ ] User and admin documentation is complete
+- [ ] Migration from single-user works smoothly
+- [ ] Performance is acceptable with multiple concurrent users
+- [ ] Backward compatibility mode works (auth disabled)
+
+## 19. Design Decisions
+
+The following design decisions have been approved for implementation:
+
+1. **OAuth2 Priority**: OAuth2/OpenID Connect integration will be a **future enhancement**. The initial release will focus on username/password authentication to keep scope manageable.
+
+2. **Email Requirement**: Email/SMTP configuration is **optional**. Many administrators will not have ready access to an outgoing SMTP server. The system will provide fallback mechanisms (showing setup links directly in the admin UI) when email is not configured.
+
+3. **Data Migration**: During migration from single-user to multi-user mode, the administrator will be given the **option to specify an arbitrary user account** to hold legacy data. The admin account can be used for this purpose if the administrator wishes.
+
+4. **API Compatibility**: Authentication will be **required on all APIs**, but authentication will not be required if multi-user support is disabled (backward compatibility mode with `auth_enabled: false`).
+
+5. **Session Storage**: The system will use **JWT tokens with optional server-side session tracking**. This provides scalability while allowing administrators to enable server-side tracking if needed.
+
+6. **Audit Logging**: The system will **log authentication events and admin actions**. This provides accountability and security monitoring for critical operations.
+
+## 20. Conclusion
+
+This specification provides a comprehensive blueprint for implementing multi-user support in InvokeAI. The design prioritizes:
+
+- **Security**: Proper authentication, authorization, and data isolation
+- **Usability**: Intuitive UI, smooth migration, minimal friction
+- **Scalability**: Efficient database design, performant queries
+- **Maintainability**: Clean architecture, comprehensive testing
+- **Flexibility**: Future enhancement paths, optional features
+
+The phased implementation approach allows for iterative development and testing, while the detailed specifications ensure all stakeholders have clear expectations of the final system.

docs/multiuser/user_guide.md

@@ -0,0 +1,399 @@
+# InvokeAI Multi-User Guide
+
+## Overview
+
+Multi-User mode is a recent feature (introduced in version 6.12), which allows multiple individuals to share a single InvokeAI server while keeping their work separate and organized. Each user has their own username and login password, images, assets, image boards, customization settings and workflows. 
+
+Two types of users are recognized:
+
+* A user with **Administrator** status can add, remove and modify other users, and can install models. They also have the ability to view the full session queue and pause or kill other users' jobs.
+* **Non-administrator** users can modify their own profile but not others. They also do not have the ability to install or configure models, but must ask an Administrator to do this task.
+
+Multiple users can be granted Administrator status.
+
+*** 
+
+## Getting Started
+
+To activate Multi-User mode, open the `INVOKEAI_ROOT/invokeai.yaml` configuration file in a text editor. Add this line anywhere in the file:
+```yaml
+multiuser: true
+```
+
+You may also wish to make InvokeAI available to other machines on your local LAN. Add an additional line to `invokeai.yaml`:
+
+```yaml
+host: 0.0.0.0
+```
+
+Restart the server. It will now be in multi-user mode. If you enabled
+the `host` option, other users on your home or office LAN will be able
+to reach it by browsing to the IP address of the machine the backend
+is running on (`http://host-ip-address:9090`).
+
+!!! tip "Do not expose InvokeAI to the internet"
+    It is not recommended to expose the InvokeAI host to the internet
+	due to security concerns.	
+
+### Initial Setup (First Time in Multi-User Mode)
+
+If you're the first person to access a fresh InvokeAI installation in multi-user mode, you'll see the **Administrator Setup** dialog:
+
+![Administrator Setup Screen](../../assets/multiuser/admin-setup.png)
+
+Now
+
+1. Enter your email address (this will be your login name)
+2. Create a display name (this will be the name other users see)
+3. Choose a strong password that meets the requirements:
+    - At least 8 characters long
+    - Contains uppercase letters
+    - Contains lowercase letters
+    - Contains numbers
+4. Confirm your password
+5. Click **Create Administrator Account**
+
+You'll now be taken to a login screen and can enter the credentials
+you just created.
+
+### Adding and Modifying Users
+
+If you are logged in as Administrator, you can add additional users. Click on the small "person silhouette" icon at the bottom left of the main Invoke screen and select "User Management:"
+
+![Administrator Menu](../../assets/multiuser/admin-add-user-1.png)
+
+This will take you to the User Management screen...
+
+![User Management screen](../../assets/multiuser/admin-add-user-2.png)
+
+...where you can click "Create User" to add a new user.
+
+![Add User Screen](../../assets/multiuser/admin-add-user-3.png)
+
+The User Management screen also allows you to:
+
+1. Temporarily change a user's status to Inactive, preventing them from logging in to Invoke.
+2. Edit a user (by clicking on the pencil icon) to change the user's display name or password.
+3. Permanently delete a user.
+4. Grant a user Administrator privileges.
+
+### Command-line User Management Scripts
+
+Administrators can also use a series of command-line scripts to add, modify, or delete users. If you use the launcher, click the ">" icon to enter the command-line interface. Otherwise, if you are a native command-line user, activate the InvokeAI environment from your terminal.
+
+The commands are named:
+
+* **invoke-useradd** -- add a user
+* **invoke-usermod** -- modify a user
+* **invoke-userdel** -- delete a user
+* **invoke-userlist** -- list all users
+
+Pass the `--help` argument to get the usage of each script. For example:
+
+```bash
+> invoke-useradd --help
+usage: invoke-useradd [-h] [--root ROOT] [--email EMAIL] [--password PASSWORD] [--name NAME] [--admin]
+
+Add a user to the InvokeAI database
+
+options:
+  -h, --help            show this help message and exit
+  --root ROOT, -r ROOT  Path to the InvokeAI root directory. If omitted, the root is resolved in this order: the $INVOKEAI_ROOT environment
+                        variable, the active virtual environment's parent directory, or $HOME/invokeai.
+  --email EMAIL, -e EMAIL
+                        User email address
+  --password PASSWORD, -p PASSWORD
+                        User password
+  --name NAME, -n NAME  User display name (optional)
+  --admin, -a           Make user an administrator
+
+If no arguments are provided, the script will run in interactive mode.
+```
+
+***
+
+## Logging in as a Non-Administrative User
+
+If you are a registered user on the system, enter your email address and password to log in. The Administrator will be able to provide you with the values to use:
+
+![Login Screen](../../assets/multiuser/user-login-1.png)
+
+As an unprivileged user you can do pretty much anything that's allowed under single-user mode -- generating images, using LoRAs, creating and running workflows, creating image boards -- but you are restricted against installing new models, changing low-level server settings, or interfering with other users. More information on user roles is given below.
+
+### Changing your Profile
+
+To change your display name or profile, click on the person silhouette icon at the bottom left of the screen and choose "My Profile". This will take you to a screen that lets you change these values. At this time you can change your display name but not your login ID (ordinarily your contact email address). 
+
+*** 
+
+## Understanding User Roles
+
+In single-user mode, you have access to all features without restrictions. In multi-user mode, InvokeAI has two user roles:
+
+### Regular User
+
+As a regular user, you can:
+
+- ✅ Create and manage your own image boards
+- ✅ Generate images using all AI tools (Linear, Canvas, Upscale, Workflows)
+- ✅ Create, save, and load your own workflows
+- ✅ View your own generation queue
+- ✅ Customize your UI preferences (theme, hotkeys, etc.)
+- ✅ View available models (read-only access to Model Manager)
+- ✅ Access shared boards (based on permissions granted to you) (FUTURE FEATURE)
+- ✅ Access workflows marked as public (FUTURE FEATURE)
+
+You cannot:
+
+- ❌ Add, delete, or modify models
+- ❌ View or modify other users' boards, images, or workflows
+- ❌ Manage user accounts
+- ❌ Access system configuration
+- ❌ View or cancel other users' generation tasks
+
+!!! tip "The generation queue"
+	When two or more users are accessing InvokeAI at the same time,
+	their image generation jobs will be placed on the session queue on
+	a first-come, first-serve basis. This means that you will have to
+	wait for other users' image rendering jobs to complete before
+	yours will start.
+	
+	When another user's job is running, you will see the image
+	generation progress bar and a queue badge that reads `X/Y`, where
+	"X" is the number of jobs you have queued and "Y" is the total
+	number of jobs queued, including your own and others.
+	
+	You can also pull up the Queue tab in order to see where your job
+	is in relationship to other queued tasks.
+
+### Administrator
+
+Administrators have all regular user capabilities, plus:
+
+- ✅ Full model management (add, delete, configure models)
+- ✅ Create and manage user accounts
+- ✅ View and manage all users' generation queues
+- ✅ Create and manage shared boards (FUTURE FEATURE)
+- ✅ Access system configuration
+- ✅ Grant or revoke admin privileges
+
+***
+
+## Working with Your Content in Multi-User Mode
+
+### Image Boards
+
+In multi-user model, Image Boards work as before. Each user can create an unlimited number of boards and organize their images and assets as they see fit. Boards are private: you cannot see a board owned by a different user.
+
+!!! tip "Shared Boards"
+    InvokeAI 6.13 will add support for creating public boards that are accessible to all users.
+
+The Administrator can see all users Image Boards and their contents.
+
+### Going From Multi-User to Single-User mode
+
+If an InvokeAI instance was in multiuser mode and then restarted in single user mode (by setting `multiuser: false` in the configuration file), all users' boards will be consolidated in one place. Any images that were in  "Uncategorized" will be merged together into a single Uncategorized board. If, at a later date, the server is restarted in multi-user mode, the boards and images will be separated and restored to their owners.
+
+### Workflows
+
+In the current released version (6.12) workflows are always shared among users. Any workflow that you create will be visible to other users and vice-versa, and there is no protection against one user modifying another user's workflow.
+
+!!! tip "Private and Shared Workflows"
+    InvokeAI 6.13 will provide the ability to create private and shared workflows. A private workflow can only be viewed by the user who created it. At any time, however, the user can designate the workflow *shared*, in which case it can be opened on a read-only basis by all logged-in users.
+
+
+### The Generation Queue
+
+The queue shows your pending and running generation tasks.
+
+**Queue Features:**
+
+- View your current and completed generations
+- Cancel pending tasks
+- Re-run previous generations
+- Monitor progress in real-time
+
+**Queue Isolation:**
+
+- You will see your own queue items, as well as the items generated by
+  either users, but the generation parameters (e.g. prompts) for other
+  users' are hidden for privacy reasons.
+- Administrators can view all queues for troubleshooting
+- Your generations won't interfere with other users' tasks
+
+***
+
+## Customizing Your Experience
+
+### Personal Preferences
+
+Your UI preferences are saved to your account and are restored when you log in:
+
+- **Theme**: Choose between light and dark modes
+- **Hotkeys**: Customize keyboard shortcuts
+- **Canvas Settings**: Default zoom, grid visibility, etc.
+- **Generation Defaults**: Default values for width, height, steps, etc.
+
+These settings are stored per-user and won't affect other users.
+
+***
+
+## Troubleshooting
+
+### Cannot Log In
+
+**Issue:** Login fails with "Incorrect email or password"
+
+**Solutions:**
+
+- Verify you're entering the correct email address
+- Check that Caps Lock is off
+- Try typing the password slowly to avoid mistakes
+- Contact your administrator if you've forgotten your password
+
+**Issue:** Login fails with "Account is disabled"
+
+**Solution:** Contact your administrator to reactivate your account
+
+### Session Expired
+
+**Issue:** You're suddenly logged out and see "Session expired"
+
+**Explanation:** Sessions expire after 24 hours (or 7 days with "remember me")
+
+**Solution:** Simply log in again with your credentials
+
+### Cannot Access Features
+
+**Issue:** Features like Model Manager show "Admin privileges required"
+
+**Explanation:** Some features are restricted to administrators
+
+**Solution:** 
+
+- For model viewing: You can view but not modify models
+- For user management: Contact an administrator
+- For system configuration: Contact an administrator
+
+### Missing Boards or Images
+
+**Issue:** Boards or images you created are not visible
+
+**Possible Causes:**
+
+1. **Filter Applied:** Check if a filter is hiding content
+2. **Wrong User:** Ensure you're logged in with the correct account
+3. **Archived Board:** Check the "Show Archived" option
+
+**Solution:** 
+
+- Clear any active filters
+- Verify you're logged in as the right user
+- Check archived items
+
+### Slow Performance
+
+**Issue:** Generation or UI feels slower than expected
+
+**Possible Causes:**
+
+- Other users generating images simultaneously
+- Server resource limits
+- Network latency
+
+**Solutions:**
+
+- Check the queue to see if others are generating
+- Wait for current generations to complete
+- Contact administrator if persistent
+
+### Generation Stuck in Queue
+
+**Issue:** Your generation is queued but not starting
+
+**Possible Causes:**
+
+- Server is processing other users' generations
+- Server resources are fully utilized
+- Technical issue with the server
+
+**Solutions:**
+
+- Wait for your turn in the queue
+- Check if your generation is paused
+- Contact administrator if stuck for extended period
+
+
+***
+
+## Frequently Asked Questions
+
+### Can other users see my images?
+
+No, unless you add them to a shared board (FUTURE FEATURE). All your personal boards and images are private.
+
+### Can I share my workflows with others?
+
+Not directly. Ask your administrator to mark workflows as public if you want to share them.
+
+### How long do sessions last?
+
+- 24 hours by default
+- 7 days if you check "Remember me" during login
+
+### Can I use the API with multi-user mode?
+
+Yes, but you'll need to authenticate with a JWT token. See the [API Guide](api_guide.md) for details.
+
+### What happens if I forget my password?
+
+Contact your administrator. They can reset your password for you.
+
+### Can I have multiple sessions?
+
+Yes, you can log in from multiple devices or browsers simultaneously. All sessions will use the same account and see the same content.
+
+### Why can't I see the Model Manager "Add Models" tab?
+
+Regular users can see the Models tab but with read-only access. Check that you're logged in and try refreshing the page.
+
+### How do I know if I'm an administrator?
+
+Administrators see an "Admin" badge next to their name in the top-right corner and have access to additional features like User Management.
+
+### Can I request admin privileges?
+
+Yes, ask your current administrator to grant you admin
+privileges. Admin privileges will give you the ability to see all
+other user's boards and images, as well as to add models and change
+various server-wide settings.
+
+## Getting Help
+
+### Support Channels
+
+- **Administrator:** Contact your system administrator for account issues
+- **Documentation:** Check the [FAQ](../faq.md) for common issues
+- **Community:** Join the [Discord](https://discord.gg/ZmtBAhwWhy) for help
+- **Bug Reports:** File issues on [GitHub](https://github.com/invoke-ai/InvokeAI/issues)
+
+### Reporting Issues
+
+When reporting an issue, include:
+
+- Your role (regular user or administrator)
+- What you were trying to do
+- What happened instead
+- Any error messages you saw
+- Your browser and operating system
+
+## Additional Resources
+
+- [Administrator Guide](admin_guide.md) - For administrators managing users and the system
+- [API Guide](api_guide.md) - For developers using the InvokeAI API
+- [Multiuser Specification](specification.md) - Technical details about the feature
+- [InvokeAI Documentation](../index.md) - Main documentation hub
+
+---
+
+**Need more help?** Contact your administrator or visit the [InvokeAI Discord](https://discord.gg/ZmtBAhwWhy).

docs/nodes/NODES.md

@@ -41,7 +41,7 @@ Nodes have a "Use Cache" option in their footer. This allows for performance imp
 
 There are several node grouping concepts that can be examined with a narrow focus. These (and other) groupings can be pieced together to make up functional graph setups, and are important to understanding how groups of nodes work together as part of a whole. Note that the screenshots below aren't examples of complete functioning node graphs (see Examples).
 
-### Noise
+### Create Latent Noise
 
 An initial noise tensor is necessary for the latent diffusion process. As a result, the Denoising node requires a noise node input.  
 

docs/nodes/communityNodes.md

@@ -4,21 +4,22 @@ These are nodes that have been developed by the community, for the community. If
 
 If you'd like to submit a node for the community, please refer to the [node creation overview](contributingNodes.md).
 
-To use a node, add the node to the `nodes` folder found in your InvokeAI install location. 
+To use a node, add the node to the `nodes` folder found in your InvokeAI install location.
 
-The suggested method is to use `git clone` to clone the repository the node is found in. This allows for easy updates of the node in the future. 
+The suggested method is to use `git clone` to clone the repository the node is found in. This allows for easy updates of the node in the future.
 
-If you'd prefer, you can also just download the whole node folder from the linked repository and add it to the `nodes` folder. 
+If you'd prefer, you can also just download the whole node folder from the linked repository and add it to the `nodes` folder.
 
-To use a community workflow, download the `.json` node graph file and load it into Invoke AI via the **Load Workflow** button in the Workflow Editor. 
+To use a community workflow, download the `.json` node graph file and load it into Invoke AI via the **Load Workflow** button in the Workflow Editor.
 
 - Community Nodes
     + [Anamorphic Tools](#anamorphic-tools)
     + [Adapters-Linked](#adapters-linked-nodes)
     + [Autostereogram](#autostereogram-nodes)
     + [Average Images](#average-images)
+    + [BiRefNet Background Removal](#birefnet-background-removal)
     + [Clean Image Artifacts After Cut](#clean-image-artifacts-after-cut)
-    + [Close Color Mask](#close-color-mask) 
+    + [Close Color Mask](#close-color-mask)
     + [Clothing Mask](#clothing-mask)
     + [Contrast Limited Adaptive Histogram Equalization](#contrast-limited-adaptive-histogram-equalization)
     + [Curves](#curves)
@@ -34,6 +35,7 @@ To use a community workflow, download the `.json` node graph file and load it in
     + [Hand Refiner with MeshGraphormer](#hand-refiner-with-meshgraphormer)
     + [Image and Mask Composition Pack](#image-and-mask-composition-pack)
     + [Image Dominant Color](#image-dominant-color)
+    + [Image Export](#image-export)
     + [Image to Character Art Image Nodes](#image-to-character-art-image-nodes)
     + [Image Picker](#image-picker)
     + [Image Resize Plus](#image-resize-plus)
@@ -51,7 +53,7 @@ To use a community workflow, download the `.json` node graph file and load it in
     + [Prompt Tools](#prompt-tools)
     + [Remote Image](#remote-image)
     + [BriaAI Background Remove](#briaai-remove-background)
-    + [Remove Background](#remove-background)    
+    + [Remove Background](#remove-background)
     + [Retroize](#retroize)
     + [Stereogram](#stereogram-nodes)
     + [Size Stepper Nodes](#size-stepper-nodes)
@@ -81,7 +83,7 @@ To use a community workflow, download the `.json` node graph file and load it in
 - `IP-Adapter-Linked` - Collects IP-Adapter info to pass to other nodes.
 - `T2I-Adapter-Linked` - Collects T2I-Adapter info to pass to other nodes.
 
-Note: These are inherited from the core nodes so any update to the core nodes should be reflected in these. 
+Note: These are inherited from the core nodes so any update to the core nodes should be reflected in these.
 
 **Node Link:** https://github.com/skunkworxdark/adapters-linked-nodes
 
@@ -103,6 +105,20 @@ Note: These are inherited from the core nodes so any update to the core nodes sh
 
 **Node Link:** https://github.com/JPPhoto/average-images-node
 
+--------------------------------
+### BiRefNet Background Removal
+
+**Description:** Remove image backgrounds using BiRefNet (Bilateral Reference Network), a high-quality segmentation model. Supports multiple model variants including standard, high-resolution, matting, portrait, and specialized models for different use cases.
+
+**Node Link:** https://github.com/veeliks/invoke_birefnet
+
+**Output Examples**
+
+<section>
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_birefnet/main/.readme/example_before_removal.png" width="49%" alt="Before background removal">
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_birefnet/main/.readme/example_after_removal.png" width="49%" alt="After background removal">
+</section>
+
 --------------------------------
 ### Clean Image Artifacts After Cut
 
@@ -216,7 +232,7 @@ This includes 3 Nodes:
 
 **Node Link:** https://github.com/mickr777/GPT2RandomPromptMaker
 
-**Output Examples** 
+**Output Examples**
 
 Generated Prompt: An enchanted weapon will be usable by any character regardless of their alignment.
 
@@ -231,7 +247,7 @@ Generated Prompt: An enchanted weapon will be usable by any character regardless
 
 **Example Node Graph:**  https://github.com/mildmisery/invokeai-GridToGifNode/blob/main/Grid%20to%20Gif%20Example%20Workflow.json
 
-**Output Examples** 
+**Output Examples**
 
 <img src="https://raw.githubusercontent.com/mildmisery/invokeai-GridToGifNode/main/input.png" width="300" />
 <img src="https://raw.githubusercontent.com/mildmisery/invokeai-GridToGifNode/main/output.gif" width="300" />
@@ -293,7 +309,7 @@ This includes 15 Nodes:
 - *Text Mask (simple 2D)* - create and position a white on black (or black on white) line of text using any font locally available to Invoke.
 
 **Node Link:** https://github.com/dwringer/composition-nodes
-  
+
 </br><img src="https://raw.githubusercontent.com/dwringer/composition-nodes/main/composition_pack_overview.jpg" width="500" />
 
 --------------------------------
@@ -306,6 +322,23 @@ Node Link: https://github.com/VeyDlin/image-dominant-color-node
 View:
 </br><img src="https://raw.githubusercontent.com/VeyDlin/image-dominant-color-node/master/.readme/node.png" width="500" />
 
+--------------------------------
+### Image Export
+
+**Description:** Export images in multiple formats (AVIF, JPEG, PNG, TIFF, WebP) with format-specific compression and quality options.
+
+**Node Link:** https://github.com/veeliks/invoke_image_export
+
+**Nodes:**
+
+<section>
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_image_export/main/.readme/node_avif.png" width="19%" alt="Save Image as AVIF">
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_image_export/main/.readme/node_jpeg.png" width="19%" alt="Save Image as JPEG">
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_image_export/main/.readme/node_png.png" width="19%" alt="Save Image as PNG">
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_image_export/main/.readme/node_tiff.png" width="19%" alt="Save Image as TIFF">
+  <img src="https://raw.githubusercontent.com/veeliks/invoke_image_export/main/.readme/node_webp.png" width="19%" alt="Save Image as WebP">
+</section>
+
 --------------------------------
 ### Image to Character Art Image Nodes
 
@@ -352,7 +385,7 @@ View:
 
 **Node Link:** https://github.com/helix4u/load_video_frame
 
-**Output Example:** 
+**Output Example:**
 <img src="https://raw.githubusercontent.com/helix4u/load_video_frame/refs/heads/main/_git_assets/dance1736978273.gif" width="500" />
 
 --------------------------------
@@ -364,7 +397,7 @@ View:
 
 **Example Node Graph:**  https://gitlab.com/srcrr/shift3d/-/raw/main/example-workflow.json?ref_type=heads&inline=false
 
-**Output Examples** 
+**Output Examples**
 
 <img src="https://gitlab.com/srcrr/shift3d/-/raw/main/example-1.png" width="300" />
 <img src="https://gitlab.com/srcrr/shift3d/-/raw/main/example-2.png" width="300" />
@@ -386,13 +419,13 @@ View:
 - Option to only transfer luminance channel.
 - Option to save output as grayscale
 
-A good use case for this node is to normalize the colors of an image that has been through the tiled scaling workflow of my XYGrid Nodes. 
+A good use case for this node is to normalize the colors of an image that has been through the tiled scaling workflow of my XYGrid Nodes.
 
 See full docs here: https://github.com/skunkworxdark/Prompt-tools-nodes/edit/main/README.md
 
 **Node Link:** https://github.com/skunkworxdark/match_histogram
 
-**Output Examples** 
+**Output Examples**
 
 <img src="https://github.com/skunkworxdark/match_histogram/assets/21961335/ed12f329-a0ef-444a-9bae-129ed60d6097" />
 
@@ -410,12 +443,12 @@ See full docs here: https://github.com/skunkworxdark/Prompt-tools-nodes/edit/mai
 - `Metadata To Bool` - Extracts Bool types from metadata
 - `Metadata To Model` - Extracts model types from metadata
 - `Metadata To SDXL Model` - Extracts SDXL model types from metadata
-- `Metadata To LoRAs` - Extracts Loras from metadata. 
+- `Metadata To LoRAs` - Extracts Loras from metadata.
 - `Metadata To SDXL LoRAs` - Extracts SDXL Loras from metadata
 - `Metadata To ControlNets` - Extracts ControNets from metadata
 - `Metadata To IP-Adapters` - Extracts IP-Adapters from metadata
 - `Metadata To T2I-Adapters` - Extracts T2I-Adapters from metadata
-- `Denoise Latents + Metadata` - This is an inherited version of the existing `Denoise Latents` node but with a metadata input and output. 
+- `Denoise Latents + Metadata` - This is an inherited version of the existing `Denoise Latents` node but with a metadata input and output.
 
 **Node Link:** https://github.com/skunkworxdark/metadata-linked-nodes
 
@@ -445,7 +478,7 @@ View:
 
 **Example Node Graph:**  https://github.com/Jonseed/Ollama-Node/blob/main/Ollama-Node-Flux-example.json
 
-**View:** 
+**View:**
 
 ![ollama node](https://raw.githubusercontent.com/Jonseed/Ollama-Node/a3e7cdc55e394cb89c1ea7ed54e106c212c85e8c/ollama-node-screenshot.png)
 
@@ -454,7 +487,7 @@ View:
 
 <img src="https://raw.githubusercontent.com/AIrjen/OneButtonPrompt_X_InvokeAI/refs/heads/main/images/background.png" width="800" />
 
-**Description:** an extensive suite of auto prompt generation and prompt helper nodes based on extensive logic. Get creative with the best prompt generator in the world. 
+**Description:** an extensive suite of auto prompt generation and prompt helper nodes based on extensive logic. Get creative with the best prompt generator in the world.
 
 The main node generates interesting prompts based on a set of parameters. There are also some additional nodes such as Auto Negative Prompt, One Button Artify, Create Prompt Variant and other cool prompt toys to play around with.
 
@@ -491,14 +524,14 @@ a Text-Generation-Webui instance (might work remotely too, but I never tried it)
 This node works best with SDXL models, especially as the style can be described independently of the LLM's output.
 
 --------------------------------
-### Prompt Tools 
+### Prompt Tools
 
 **Description:** A set of InvokeAI nodes that add general prompt (string) manipulation tools.  Designed to accompany the `Prompts From File` node and other prompt generation nodes.
 
 1. `Prompt To File` - saves a prompt or collection of prompts to a file. one per line. There is an append/overwrite option.
-2. `PTFields Collect` - Converts image generation fields into a Json format string that can be passed to Prompt to file. 
+2. `PTFields Collect` - Converts image generation fields into a Json format string that can be passed to Prompt to file.
 3. `PTFields Expand` - Takes Json string and converts it to individual generation parameters. This can be fed from the Prompts to file node.
-4. `Prompt Strength` - Formats prompt with strength like the weighted format of compel 
+4. `Prompt Strength` - Formats prompt with strength like the weighted format of compel
 5. `Prompt Strength Combine` - Combines weighted prompts for .and()/.blend()
 6. `CSV To Index String` - Gets a string from a CSV by index. Includes a Random index option
 
@@ -513,7 +546,7 @@ See full docs here: https://github.com/skunkworxdark/Prompt-tools-nodes/edit/mai
 
 **Node Link:** https://github.com/skunkworxdark/Prompt-tools-nodes
 
-**Workflow Examples** 
+**Workflow Examples**
 
 <img src="https://raw.githubusercontent.com/skunkworxdark/prompt-tools/refs/heads/main/images/CSVToIndexStringNode.png"/>
 
@@ -648,7 +681,7 @@ Highlights/Midtones/Shadows (with LUT blur enabled):
 - Generate grids of images from multiple input images
 - Create XY grid images with labels from parameters
 - Split images into overlapping tiles for processing (for super-resolution workflows)
-- Recombine image tiles into a single output image blending the seams 
+- Recombine image tiles into a single output image blending the seams
 
 The nodes include:
 1. `Images To Grids` - Combine multiple images into a grid of images
@@ -661,7 +694,7 @@ See full docs here: https://github.com/skunkworxdark/XYGrid_nodes/edit/main/READ
 
 **Node Link:** https://github.com/skunkworxdark/XYGrid_nodes
 
-**Output Examples** 
+**Output Examples**
 
 <img src="https://raw.githubusercontent.com/skunkworxdark/XYGrid_nodes/refs/heads/main/images/collage.png" />
 
@@ -675,7 +708,7 @@ See full docs here: https://github.com/skunkworxdark/XYGrid_nodes/edit/main/READ
 
 **Example Workflow:**  https://github.com/invoke-ai/InvokeAI/blob/docs/main/docs/workflows/Prompt_from_File.json
 
-**Output Examples** 
+**Output Examples**
 
 </br><img src="https://invoke-ai.github.io/InvokeAI/assets/invoke_ai_banner.png" width="500" />
 
@@ -686,5 +719,5 @@ The nodes linked have been developed and contributed by members of the Invoke AI
 
 
 ## Help
-If you run into any issues with a node, please post in the [InvokeAI Discord](https://discord.gg/ZmtBAhwWhy). 
+If you run into any issues with a node, please post in the [InvokeAI Discord](https://discord.gg/ZmtBAhwWhy).
 

invokeai/app/api/auth_dependencies.py

@@ -0,0 +1,166 @@
+"""FastAPI dependencies for authentication."""
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from invokeai.app.api.dependencies import ApiDependencies
+from invokeai.app.services.auth.token_service import TokenData, verify_token
+from invokeai.backend.util.logging import logging
+
+logger = logging.getLogger(__name__)
+
+# HTTP Bearer token security scheme
+security = HTTPBearer(auto_error=False)
+
+
+async def get_current_user(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
+) -> TokenData:
+    """Get current authenticated user from Bearer token.
+
+    Note: This function accesses ApiDependencies.invoker.services.users directly,
+    which is the established pattern in this codebase. The ApiDependencies.invoker
+    is initialized in the FastAPI lifespan context before any requests are handled.
+
+    Args:
+        credentials: The HTTP authorization credentials containing the Bearer token
+
+    Returns:
+        TokenData containing user information from the token
+
+    Raises:
+        HTTPException: If token is missing, invalid, or expired (401 Unauthorized)
+    """
+    if credentials is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    token = credentials.credentials
+    token_data = verify_token(token)
+
+    if token_data is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Verify user still exists and is active
+    user_service = ApiDependencies.invoker.services.users
+    user = user_service.get(token_data.user_id)
+
+    if user is None or not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User account is inactive or does not exist",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return token_data
+
+
+async def get_current_user_or_default(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
+) -> TokenData:
+    """Get current authenticated user from Bearer token, or return a default system user if not authenticated.
+
+    This dependency is useful for endpoints that should work in both single-user and multiuser modes.
+
+    When multiuser mode is disabled (default), this always returns a system user with admin privileges,
+    allowing unrestricted access to all operations.
+
+    When multiuser mode is enabled, authentication is required and this function validates the token,
+    returning authenticated user data or raising 401 Unauthorized if no valid credentials are provided.
+
+    Args:
+        credentials: The HTTP authorization credentials containing the Bearer token
+
+    Returns:
+        TokenData containing user information from the token, or system user in single-user mode
+
+    Raises:
+        HTTPException: 401 Unauthorized if in multiuser mode and credentials are missing, invalid, or user is inactive
+    """
+    # Get configuration to check if multiuser is enabled
+    config = ApiDependencies.invoker.services.configuration
+
+    # In single-user mode (multiuser=False), always return system user with admin privileges
+    if not config.multiuser:
+        return TokenData(user_id="system", email="system@system.invokeai", is_admin=True)
+
+    # Multiuser mode is enabled - validate credentials
+    if credentials is None:
+        # In multiuser mode, authentication is required
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Authentication required")
+
+    token = credentials.credentials
+    token_data = verify_token(token)
+
+    if token_data is None:
+        # Invalid token in multiuser mode - reject
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid or expired token")
+
+    # Verify user still exists and is active
+    user_service = ApiDependencies.invoker.services.users
+    user = user_service.get(token_data.user_id)
+
+    if user is None or not user.is_active:
+        # User doesn't exist or is inactive in multiuser mode - reject
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found or inactive")
+
+    return token_data
+
+
+async def require_admin(
+    current_user: Annotated[TokenData, Depends(get_current_user)],
+) -> TokenData:
+    """Require admin role for the current user.
+
+    Args:
+        current_user: The current authenticated user's token data
+
+    Returns:
+        The token data if user is an admin
+
+    Raises:
+        HTTPException: If user does not have admin privileges (403 Forbidden)
+    """
+    if not current_user.is_admin:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin privileges required")
+    return current_user
+
+
+async def require_admin_or_default(
+    current_user: Annotated[TokenData, Depends(get_current_user_or_default)],
+) -> TokenData:
+    """Require admin role for the current user, or return default system admin in single-user mode.
+
+    This dependency is useful for admin-only endpoints that should work in both single-user and multiuser modes.
+
+    When multiuser mode is disabled (default), this always returns a system user with admin privileges.
+    When multiuser mode is enabled, this validates that the authenticated user has admin privileges.
+
+    Args:
+        current_user: The current authenticated user's token data (or default system user)
+
+    Returns:
+        The token data if user is an admin (or system user in single-user mode)
+
+    Raises:
+        HTTPException: If user does not have admin privileges (403 Forbidden) in multiuser mode
+    """
+    if not current_user.is_admin:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin privileges required")
+    return current_user
+
+
+# Type aliases for convenient use in route dependencies
+CurrentUser = Annotated[TokenData, Depends(get_current_user)]
+CurrentUserOrDefault = Annotated[TokenData, Depends(get_current_user_or_default)]
+AdminUser = Annotated[TokenData, Depends(require_admin)]
+AdminUserOrDefault = Annotated[TokenData, Depends(require_admin_or_default)]

invokeai/app/api/dependencies.py

@@ -5,11 +5,14 @@ from logging import Logger
 
 import torch
 
+from invokeai.app.services.app_settings import AppSettingsService
+from invokeai.app.services.auth.token_service import set_jwt_secret
 from invokeai.app.services.board_image_records.board_image_records_sqlite import SqliteBoardImageRecordStorage
 from invokeai.app.services.board_images.board_images_default import BoardImagesService
 from invokeai.app.services.board_records.board_records_sqlite import SqliteBoardRecordStorage
 from invokeai.app.services.boards.boards_default import BoardService
 from invokeai.app.services.bulk_download.bulk_download_default import BulkDownloadService
+from invokeai.app.services.client_state_persistence.client_state_persistence_sqlite import ClientStatePersistenceSqlite
 from invokeai.app.services.config.config_default import InvokeAIAppConfig
 from invokeai.app.services.download.download_default import DownloadQueueService
 from invokeai.app.services.events.events_fastapievents import FastAPIEventService
@@ -39,6 +42,7 @@ from invokeai.app.services.shared.sqlite.sqlite_util import init_db
 from invokeai.app.services.style_preset_images.style_preset_images_disk import StylePresetImageFileStorageDisk
 from invokeai.app.services.style_preset_records.style_preset_records_sqlite import SqliteStylePresetRecordsStorage
 from invokeai.app.services.urls.urls_default import LocalUrlService
+from invokeai.app.services.users.users_default import UserService
 from invokeai.app.services.workflow_records.workflow_records_sqlite import SqliteWorkflowRecordsStorage
 from invokeai.app.services.workflow_thumbnails.workflow_thumbnails_disk import WorkflowThumbnailFileStorageDisk
 from invokeai.backend.stable_diffusion.diffusion.conditioning_data import (
@@ -48,6 +52,7 @@ from invokeai.backend.stable_diffusion.diffusion.conditioning_data import (
     FLUXConditioningInfo,
     SD3ConditioningInfo,
     SDXLConditioningInfo,
+    ZImageConditioningInfo,
 )
 from invokeai.backend.util.logging import InvokeAILogger
 from invokeai.version.invokeai_version import __version__
@@ -99,6 +104,12 @@ class ApiDependencies:
 
         db = init_db(config=config, logger=logger, image_files=image_files)
 
+        # Initialize JWT secret from database
+        app_settings = AppSettingsService(db=db)
+        jwt_secret = app_settings.get_jwt_secret()
+        set_jwt_secret(jwt_secret)
+        logger.info("JWT secret loaded from database")
+
         configuration = config
         logger = logger
 
@@ -128,6 +139,7 @@ class ApiDependencies:
                     FLUXConditioningInfo,
                     SD3ConditioningInfo,
                     CogView4ConditioningInfo,
+                    ZImageConditioningInfo,
                 ],
                 ephemeral=True,
             ),
@@ -151,6 +163,8 @@ class ApiDependencies:
         style_preset_records = SqliteStylePresetRecordsStorage(db=db)
         style_preset_image_files = StylePresetImageFileStorageDisk(style_presets_folder / "images")
         workflow_thumbnails = WorkflowThumbnailFileStorageDisk(workflow_thumbnails_folder)
+        client_state_persistence = ClientStatePersistenceSqlite(db=db)
+        users = UserService(db=db)
 
         services = InvocationServices(
             board_image_records=board_image_records,
@@ -181,6 +195,8 @@ class ApiDependencies:
             style_preset_records=style_preset_records,
             style_preset_image_files=style_preset_image_files,
             workflow_thumbnails=workflow_thumbnails,
+            client_state_persistence=client_state_persistence,
+            users=users,
         )
 
         ApiDependencies.invoker = Invoker(services)

invokeai/app/api/no_cache_staticfiles.py

@@ -1,7 +1,9 @@
 from typing import Any
 
+from starlette.exceptions import HTTPException
 from starlette.responses import Response
 from starlette.staticfiles import StaticFiles
+from starlette.types import Scope
 
 
 class NoCacheStaticFiles(StaticFiles):
@@ -12,6 +14,10 @@ class NoCacheStaticFiles(StaticFiles):
 
     Static files include the javascript bundles, fonts, locales, and some images. Generated
     images are not included, as they are served by a router.
+
+    This class also implements proper SPA (Single Page Application) routing by serving index.html
+    for any routes that don't match static files, enabling client-side routing to work correctly
+    in production builds.
     """
 
     def __init__(self, *args: Any, **kwargs: Any):
@@ -26,3 +32,19 @@ class NoCacheStaticFiles(StaticFiles):
         resp.headers.setdefault("Pragma", self.pragma)
         resp.headers.setdefault("Expires", self.expires)
         return resp
+
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        """
+        Override get_response to implement SPA routing.
+
+        When a file is not found and html mode is enabled, serve index.html instead of raising a 404.
+        This allows client-side routing to work correctly in SPAs.
+        """
+        try:
+            return await super().get_response(path, scope)
+        except HTTPException as exc:
+            # If the file is not found (404) and html mode is enabled, serve index.html
+            # This allows client-side routing to handle the path
+            if exc.status_code == 404 and self.html:
+                return await super().get_response("index.html", scope)
+            raise

invokeai/app/api/routers/app_info.py

@@ -1,8 +1,5 @@
-import typing
 from enum import Enum
 from importlib.metadata import distributions
-from pathlib import Path
-from typing import Optional
 
 import torch
 from fastapi import Body
@@ -10,7 +7,6 @@ from fastapi.routing import APIRouter
 from pydantic import BaseModel, Field
 
 from invokeai.app.api.dependencies import ApiDependencies
-from invokeai.app.invocations.upscale import ESRGAN_MODELS
 from invokeai.app.services.config.config_default import InvokeAIAppConfig, get_config
 from invokeai.app.services.invocation_cache.invocation_cache_common import InvocationCacheStatus
 from invokeai.backend.image_util.infill_methods.patchmatch import PatchMatch
@@ -27,11 +23,6 @@ class LogLevel(int, Enum):
     Critical = logging.CRITICAL
 
 
-class Upscaler(BaseModel):
-    upscaling_method: str = Field(description="Name of upscaling method")
-    upscaling_models: list[str] = Field(description="List of upscaling models for this method")
-
-
 app_router = APIRouter(prefix="/v1/app", tags=["app"])
 
 
@@ -40,17 +31,6 @@ class AppVersion(BaseModel):
 
     version: str = Field(description="App version")
 
-    highlights: Optional[list[str]] = Field(default=None, description="Highlights of release")
-
-
-class AppConfig(BaseModel):
-    """App Config Response"""
-
-    infill_methods: list[str] = Field(description="List of available infill methods")
-    upscaling_methods: list[Upscaler] = Field(description="List of upscaling methods")
-    nsfw_methods: list[str] = Field(description="List of NSFW checking methods")
-    watermarking_methods: list[str] = Field(description="List of invisible watermark methods")
-
 
 @app_router.get("/version", operation_id="app_version", status_code=200, response_model=AppVersion)
 async def get_version() -> AppVersion:
@@ -72,27 +52,9 @@ async def get_app_deps() -> dict[str, str]:
     return sorted_deps
 
 
-@app_router.get("/config", operation_id="get_config", status_code=200, response_model=AppConfig)
-async def get_config_() -> AppConfig:
-    infill_methods = ["lama", "tile", "cv2", "color"]  # TODO: add mosaic back
-    if PatchMatch.patchmatch_available():
-        infill_methods.append("patchmatch")
-
-    upscaling_models = []
-    for model in typing.get_args(ESRGAN_MODELS):
-        upscaling_models.append(str(Path(model).stem))
-    upscaler = Upscaler(upscaling_method="esrgan", upscaling_models=upscaling_models)
-
-    nsfw_methods = ["nsfw_checker"]
-
-    watermarking_methods = ["invisible_watermark"]
-
-    return AppConfig(
-        infill_methods=infill_methods,
-        upscaling_methods=[upscaler],
-        nsfw_methods=nsfw_methods,
-        watermarking_methods=watermarking_methods,
-    )
+@app_router.get("/patchmatch_status", operation_id="get_patchmatch_status", status_code=200, response_model=bool)
+async def get_patchmatch_status() -> bool:
+    return PatchMatch.patchmatch_available()
 
 
 class InvokeAIAppConfigWithSetFields(BaseModel):

invokeai/app/api/routers/auth.py

@@ -0,0 +1,524 @@
+"""Authentication endpoints."""
+
+import secrets
+import string
+from datetime import timedelta
+from typing import Annotated
+
+from fastapi import APIRouter, Body, HTTPException, Path, status
+from pydantic import BaseModel, Field, field_validator
+
+from invokeai.app.api.auth_dependencies import AdminUser, CurrentUser
+from invokeai.app.api.dependencies import ApiDependencies
+from invokeai.app.services.auth.token_service import TokenData, create_access_token
+from invokeai.app.services.users.users_common import (
+    UserCreateRequest,
+    UserDTO,
+    UserUpdateRequest,
+    validate_email_with_special_domains,
+)
+
+auth_router = APIRouter(prefix="/v1/auth", tags=["authentication"])
+
+# Token expiration constants (in days)
+TOKEN_EXPIRATION_NORMAL = 1  # 1 day for normal login
+TOKEN_EXPIRATION_REMEMBER_ME = 7  # 7 days for "remember me" login
+
+
+class LoginRequest(BaseModel):
+    """Request body for user login."""
+
+    email: str = Field(description="User email address")
+    password: str = Field(description="User password")
+    remember_me: bool = Field(default=False, description="Whether to extend session duration")
+
+    @field_validator("email")
+    @classmethod
+    def validate_email(cls, v: str) -> str:
+        """Validate email address, allowing special-use domains."""
+        return validate_email_with_special_domains(v)
+
+
+class LoginResponse(BaseModel):
+    """Response from successful login."""
+
+    token: str = Field(description="JWT access token")
+    user: UserDTO = Field(description="User information")
+    expires_in: int = Field(description="Token expiration time in seconds")
+
+
+class SetupRequest(BaseModel):
+    """Request body for initial admin setup."""
+
+    email: str = Field(description="Admin email address")
+    display_name: str | None = Field(default=None, description="Admin display name")
+    password: str = Field(description="Admin password")
+
+    @field_validator("email")
+    @classmethod
+    def validate_email(cls, v: str) -> str:
+        """Validate email address, allowing special-use domains."""
+        return validate_email_with_special_domains(v)
+
+
+class SetupResponse(BaseModel):
+    """Response from successful admin setup."""
+
+    success: bool = Field(description="Whether setup was successful")
+    user: UserDTO = Field(description="Created admin user information")
+
+
+class LogoutResponse(BaseModel):
+    """Response from logout."""
+
+    success: bool = Field(description="Whether logout was successful")
+
+
+class SetupStatusResponse(BaseModel):
+    """Response for setup status check."""
+
+    setup_required: bool = Field(description="Whether initial setup is required")
+    multiuser_enabled: bool = Field(description="Whether multiuser mode is enabled")
+    strict_password_checking: bool = Field(description="Whether strict password requirements are enforced")
+
+
+@auth_router.get("/status", response_model=SetupStatusResponse)
+async def get_setup_status() -> SetupStatusResponse:
+    """Check if initial administrator setup is required.
+
+    Returns:
+        SetupStatusResponse indicating whether setup is needed and multiuser mode status
+    """
+    config = ApiDependencies.invoker.services.configuration
+
+    # If multiuser is disabled, setup is never required
+    if not config.multiuser:
+        return SetupStatusResponse(
+            setup_required=False, multiuser_enabled=False, strict_password_checking=config.strict_password_checking
+        )
+
+    # In multiuser mode, check if an admin exists
+    user_service = ApiDependencies.invoker.services.users
+    setup_required = not user_service.has_admin()
+
+    return SetupStatusResponse(
+        setup_required=setup_required, multiuser_enabled=True, strict_password_checking=config.strict_password_checking
+    )
+
+
+@auth_router.post("/login", response_model=LoginResponse)
+async def login(
+    request: Annotated[LoginRequest, Body(description="Login credentials")],
+) -> LoginResponse:
+    """Authenticate user and return access token.
+
+    Args:
+        request: Login credentials (email and password)
+
+    Returns:
+        LoginResponse containing JWT token and user information
+
+    Raises:
+        HTTPException: 401 if credentials are invalid or user is inactive
+        HTTPException: 403 if multiuser mode is disabled
+    """
+    config = ApiDependencies.invoker.services.configuration
+
+    # Check if multiuser is enabled
+    if not config.multiuser:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Multiuser mode is disabled. Authentication is not required in single-user mode.",
+        )
+
+    user_service = ApiDependencies.invoker.services.users
+    user = user_service.authenticate(request.email, request.password)
+
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not user.is_active:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="User account is disabled")
+
+    # Create token with appropriate expiration
+    expires_delta = timedelta(days=TOKEN_EXPIRATION_REMEMBER_ME if request.remember_me else TOKEN_EXPIRATION_NORMAL)
+    token_data = TokenData(
+        user_id=user.user_id,
+        email=user.email,
+        is_admin=user.is_admin,
+    )
+    token = create_access_token(token_data, expires_delta)
+
+    return LoginResponse(
+        token=token,
+        user=user,
+        expires_in=int(expires_delta.total_seconds()),
+    )
+
+
+@auth_router.post("/logout", response_model=LogoutResponse)
+async def logout(
+    current_user: CurrentUser,
+) -> LogoutResponse:
+    """Logout current user.
+
+    Currently a no-op since we use stateless JWT tokens. For token invalidation in
+    future implementations, consider:
+    - Token blacklist: Store invalidated tokens in Redis/database with expiration
+    - Token versioning: Add version field to user record, increment on logout
+    - Short-lived tokens: Use refresh token pattern with token rotation
+    - Session storage: Track active sessions server-side for revocation
+
+    Args:
+        current_user: The authenticated user (validates token)
+
+    Returns:
+        LogoutResponse indicating success
+    """
+    # TODO: Implement token invalidation when server-side session management is added
+    # For now, this is a no-op since we use stateless JWT tokens
+    return LogoutResponse(success=True)
+
+
+@auth_router.get("/me", response_model=UserDTO)
+async def get_current_user_info(
+    current_user: CurrentUser,
+) -> UserDTO:
+    """Get current authenticated user's information.
+
+    Args:
+        current_user: The authenticated user's token data
+
+    Returns:
+        UserDTO containing user information
+
+    Raises:
+        HTTPException: 404 if user is not found (should not happen normally)
+    """
+    user_service = ApiDependencies.invoker.services.users
+    user = user_service.get(current_user.user_id)
+
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    return user
+
+
+@auth_router.post("/setup", response_model=SetupResponse)
+async def setup_admin(
+    request: Annotated[SetupRequest, Body(description="Admin account details")],
+) -> SetupResponse:
+    """Set up initial administrator account.
+
+    This endpoint can only be called once, when no admin user exists. It creates
+    the first admin user for the system.
+
+    Args:
+        request: Admin account details (email, display_name, password)
+
+    Returns:
+        SetupResponse containing the created admin user
+
+    Raises:
+        HTTPException: 400 if admin already exists or password is weak
+        HTTPException: 403 if multiuser mode is disabled
+    """
+    config = ApiDependencies.invoker.services.configuration
+
+    # Check if multiuser is enabled
+    if not config.multiuser:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Multiuser mode is disabled. Admin setup is not required in single-user mode.",
+        )
+
+    user_service = ApiDependencies.invoker.services.users
+
+    # Check if any admin exists
+    if user_service.has_admin():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Administrator account already configured",
+        )
+
+    # Create admin user - this will validate password strength
+    try:
+        user_data = UserCreateRequest(
+            email=request.email,
+            display_name=request.display_name,
+            password=request.password,
+            is_admin=True,
+        )
+        user = user_service.create_admin(user_data, strict_password_checking=config.strict_password_checking)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+    return SetupResponse(success=True, user=user)
+
+
+# ---------------------------------------------------------------------------
+# User management models
+# ---------------------------------------------------------------------------
+
+_PASSWORD_ALPHABET = string.ascii_letters + string.digits + string.punctuation
+
+
+class AdminUserCreateRequest(BaseModel):
+    """Request body for admin to create a new user."""
+
+    email: str = Field(description="User email address")
+    display_name: str | None = Field(default=None, description="Display name")
+    password: str = Field(description="User password")
+    is_admin: bool = Field(default=False, description="Whether user should have admin privileges")
+
+    @field_validator("email")
+    @classmethod
+    def validate_email(cls, v: str) -> str:
+        """Validate email address, allowing special-use domains."""
+        return validate_email_with_special_domains(v)
+
+
+class AdminUserUpdateRequest(BaseModel):
+    """Request body for admin to update any user."""
+
+    display_name: str | None = Field(default=None, description="Display name")
+    password: str | None = Field(default=None, description="New password")
+    is_admin: bool | None = Field(default=None, description="Whether user should have admin privileges")
+    is_active: bool | None = Field(default=None, description="Whether user account should be active")
+
+
+class UserProfileUpdateRequest(BaseModel):
+    """Request body for a user to update their own profile."""
+
+    display_name: str | None = Field(default=None, description="New display name")
+    current_password: str | None = Field(default=None, description="Current password (required when changing password)")
+    new_password: str | None = Field(default=None, description="New password")
+
+
+class GeneratePasswordResponse(BaseModel):
+    """Response containing a generated password."""
+
+    password: str = Field(description="Generated strong password")
+
+
+# ---------------------------------------------------------------------------
+# User management endpoints
+# ---------------------------------------------------------------------------
+
+
+@auth_router.get("/generate-password", response_model=GeneratePasswordResponse)
+async def generate_password(
+    current_user: CurrentUser,
+) -> GeneratePasswordResponse:
+    """Generate a strong random password.
+
+    Returns a cryptographically secure random password of 16 characters
+    containing uppercase, lowercase, digits, and punctuation.
+    """
+    # Ensure the generated password always meets strength requirements:
+    # at least one uppercase, one lowercase, one digit, one special char.
+    while True:
+        password = "".join(secrets.choice(_PASSWORD_ALPHABET) for _ in range(16))
+        if (
+            any(c.isupper() for c in password)
+            and any(c.islower() for c in password)
+            and any(c.isdigit() for c in password)
+        ):
+            return GeneratePasswordResponse(password=password)
+
+
+@auth_router.get("/users", response_model=list[UserDTO])
+async def list_users(
+    current_user: AdminUser,
+) -> list[UserDTO]:
+    """List all users. Requires admin privileges.
+
+    The internal 'system' user (created for backward compatibility) is excluded
+    from the results since it cannot be managed through this interface.
+
+    Returns:
+        List of all real users (system user excluded)
+    """
+    user_service = ApiDependencies.invoker.services.users
+    return [u for u in user_service.list_users() if u.user_id != "system"]
+
+
+@auth_router.post("/users", response_model=UserDTO, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    request: Annotated[AdminUserCreateRequest, Body(description="New user details")],
+    current_user: AdminUser,
+) -> UserDTO:
+    """Create a new user. Requires admin privileges.
+
+    Args:
+        request: New user details
+
+    Returns:
+        The created user
+
+    Raises:
+        HTTPException: 400 if email already exists or password is weak
+    """
+    user_service = ApiDependencies.invoker.services.users
+    config = ApiDependencies.invoker.services.configuration
+    try:
+        user_data = UserCreateRequest(
+            email=request.email,
+            display_name=request.display_name,
+            password=request.password,
+            is_admin=request.is_admin,
+        )
+        return user_service.create(user_data, strict_password_checking=config.strict_password_checking)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+
+@auth_router.get("/users/{user_id}", response_model=UserDTO)
+async def get_user(
+    user_id: Annotated[str, Path(description="User ID")],
+    current_user: AdminUser,
+) -> UserDTO:
+    """Get a user by ID. Requires admin privileges.
+
+    Args:
+        user_id: The user ID
+
+    Returns:
+        The user
+
+    Raises:
+        HTTPException: 404 if user not found
+    """
+    user_service = ApiDependencies.invoker.services.users
+    user = user_service.get(user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    return user
+
+
+@auth_router.patch("/users/{user_id}", response_model=UserDTO)
+async def update_user(
+    user_id: Annotated[str, Path(description="User ID")],
+    request: Annotated[AdminUserUpdateRequest, Body(description="User fields to update")],
+    current_user: AdminUser,
+) -> UserDTO:
+    """Update a user. Requires admin privileges.
+
+    Args:
+        user_id: The user ID
+        request: Fields to update
+
+    Returns:
+        The updated user
+
+    Raises:
+        HTTPException: 400 if password is weak
+        HTTPException: 404 if user not found
+    """
+    user_service = ApiDependencies.invoker.services.users
+    config = ApiDependencies.invoker.services.configuration
+    try:
+        changes = UserUpdateRequest(
+            display_name=request.display_name,
+            password=request.password,
+            is_admin=request.is_admin,
+            is_active=request.is_active,
+        )
+        return user_service.update(user_id, changes, strict_password_checking=config.strict_password_checking)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+
+@auth_router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: Annotated[str, Path(description="User ID")],
+    current_user: AdminUser,
+) -> None:
+    """Delete a user. Requires admin privileges.
+
+    Admins can delete any user including other admins, but cannot delete the last
+    remaining admin.
+
+    Args:
+        user_id: The user ID
+
+    Raises:
+        HTTPException: 400 if attempting to delete the last admin
+        HTTPException: 404 if user not found
+    """
+    user_service = ApiDependencies.invoker.services.users
+    user = user_service.get(user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    # Prevent deleting the last active admin
+    if user.is_admin and user.is_active and user_service.count_admins() <= 1:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Cannot delete the last administrator",
+        )
+
+    try:
+        user_service.delete(user_id)
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+
+@auth_router.patch("/me", response_model=UserDTO)
+async def update_current_user(
+    request: Annotated[UserProfileUpdateRequest, Body(description="Profile fields to update")],
+    current_user: CurrentUser,
+) -> UserDTO:
+    """Update the current user's own profile.
+
+    To change the password, both ``current_password`` and ``new_password`` must
+    be provided. The current password is verified before the change is applied.
+
+    Args:
+        request: Profile fields to update
+        current_user: The authenticated user
+
+    Returns:
+        The updated user
+
+    Raises:
+        HTTPException: 400 if current password is incorrect or new password is weak
+        HTTPException: 404 if user not found
+    """
+    user_service = ApiDependencies.invoker.services.users
+    config = ApiDependencies.invoker.services.configuration
+
+    # Verify current password when attempting a password change
+    if request.new_password is not None:
+        if not request.current_password:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is required to set a new password",
+            )
+
+        # Re-authenticate to verify the current password
+        user = user_service.get(current_user.user_id)
+        if user is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+        authenticated = user_service.authenticate(user.email, request.current_password)
+        if authenticated is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect",
+            )
+
+    try:
+        changes = UserUpdateRequest(
+            display_name=request.display_name,
+            password=request.new_password,
+        )
+        return user_service.update(
+            current_user.user_id, changes, strict_password_checking=config.strict_password_checking
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e

invokeai/app/api/routers/boards.py

@@ -4,6 +4,7 @@ from fastapi import Body, HTTPException, Path, Query
 from fastapi.routing import APIRouter
 from pydantic import BaseModel, Field
 
+from invokeai.app.api.auth_dependencies import CurrentUserOrDefault
 from invokeai.app.api.dependencies import ApiDependencies
 from invokeai.app.services.board_records.board_records_common import BoardChanges, BoardRecordOrderBy
 from invokeai.app.services.boards.boards_common import BoardDTO
@@ -32,12 +33,12 @@ class DeleteBoardResult(BaseModel):
     response_model=BoardDTO,
 )
 async def create_board(
+    current_user: CurrentUserOrDefault,
     board_name: str = Query(description="The name of the board to create", max_length=300),
-    is_private: bool = Query(default=False, description="Whether the board is private"),
 ) -> BoardDTO:
-    """Creates a board"""
+    """Creates a board for the current user"""
     try:
-        result = ApiDependencies.invoker.services.boards.create(board_name=board_name)
+        result = ApiDependencies.invoker.services.boards.create(board_name=board_name, user_id=current_user.user_id)
         return result
     except Exception:
         raise HTTPException(status_code=500, detail="Failed to create board")
@@ -45,16 +46,21 @@ async def create_board(
 
 @boards_router.get("/{board_id}", operation_id="get_board", response_model=BoardDTO)
 async def get_board(
+    current_user: CurrentUserOrDefault,
     board_id: str = Path(description="The id of board to get"),
 ) -> BoardDTO:
-    """Gets a board"""
+    """Gets a board (user must have access to it)"""
 
     try:
         result = ApiDependencies.invoker.services.boards.get_dto(board_id=board_id)
-        return result
     except Exception:
         raise HTTPException(status_code=404, detail="Board not found")
 
+    if not current_user.is_admin and result.user_id != current_user.user_id:
+        raise HTTPException(status_code=403, detail="Not authorized to access this board")
+
+    return result
+
 
 @boards_router.patch(
     "/{board_id}",
@@ -68,10 +74,19 @@ async def get_board(
     response_model=BoardDTO,
 )
 async def update_board(
+    current_user: CurrentUserOrDefault,
     board_id: str = Path(description="The id of board to update"),
     changes: BoardChanges = Body(description="The changes to apply to the board"),
 ) -> BoardDTO:
-    """Updates a board"""
+    """Updates a board (user must have access to it)"""
+    try:
+        board = ApiDependencies.invoker.services.boards.get_dto(board_id=board_id)
+    except Exception:
+        raise HTTPException(status_code=404, detail="Board not found")
+
+    if not current_user.is_admin and board.user_id != current_user.user_id:
+        raise HTTPException(status_code=403, detail="Not authorized to update this board")
+
     try:
         result = ApiDependencies.invoker.services.boards.update(board_id=board_id, changes=changes)
         return result
@@ -81,10 +96,19 @@ async def update_board(
 
 @boards_router.delete("/{board_id}", operation_id="delete_board", response_model=DeleteBoardResult)
 async def delete_board(
+    current_user: CurrentUserOrDefault,
     board_id: str = Path(description="The id of board to delete"),
     include_images: Optional[bool] = Query(description="Permanently delete all images on the board", default=False),
 ) -> DeleteBoardResult:
-    """Deletes a board"""
+    """Deletes a board (user must have access to it)"""
+    try:
+        board = ApiDependencies.invoker.services.boards.get_dto(board_id=board_id)
+    except Exception:
+        raise HTTPException(status_code=404, detail="Board not found")
+
+    if not current_user.is_admin and board.user_id != current_user.user_id:
+        raise HTTPException(status_code=403, detail="Not authorized to delete this board")
+
     try:
         if include_images is True:
             deleted_images = ApiDependencies.invoker.services.board_images.get_all_board_image_names_for_board(
@@ -121,6 +145,7 @@ async def delete_board(
     response_model=Union[OffsetPaginatedResults[BoardDTO], list[BoardDTO]],
 )
 async def list_boards(
+    current_user: CurrentUserOrDefault,
     order_by: BoardRecordOrderBy = Query(default=BoardRecordOrderBy.CreatedAt, description="The attribute to order by"),
     direction: SQLiteDirection = Query(default=SQLiteDirection.Descending, description="The direction to order by"),
     all: Optional[bool] = Query(default=None, description="Whether to list all boards"),
@@ -128,11 +153,15 @@ async def list_boards(
     limit: Optional[int] = Query(default=None, description="The number of boards per page"),
     include_archived: bool = Query(default=False, description="Whether or not to include archived boards in list"),
 ) -> Union[OffsetPaginatedResults[BoardDTO], list[BoardDTO]]:
-    """Gets a list of boards"""
+    """Gets a list of boards for the current user, including shared boards. Admin users see all boards."""
     if all:
-        return ApiDependencies.invoker.services.boards.get_all(order_by, direction, include_archived)
+        return ApiDependencies.invoker.services.boards.get_all(
+            current_user.user_id, current_user.is_admin, order_by, direction, include_archived
+        )
     elif offset is not None and limit is not None:
-        return ApiDependencies.invoker.services.boards.get_many(order_by, direction, offset, limit, include_archived)
+        return ApiDependencies.invoker.services.boards.get_many(
+            current_user.user_id, current_user.is_admin, order_by, direction, offset, limit, include_archived
+        )
     else:
         raise HTTPException(
             status_code=400,
@@ -146,12 +175,22 @@ async def list_boards(
     response_model=list[str],
 )
 async def list_all_board_image_names(
+    current_user: CurrentUserOrDefault,
     board_id: str = Path(description="The id of the board or 'none' for uncategorized images"),
     categories: list[ImageCategory] | None = Query(default=None, description="The categories of image to include."),
     is_intermediate: bool | None = Query(default=None, description="Whether to list intermediate images."),
 ) -> list[str]:
     """Gets a list of images for a board"""
 
+    if board_id != "none":
+        try:
+            board = ApiDependencies.invoker.services.boards.get_dto(board_id=board_id)
+        except Exception:
+            raise HTTPException(status_code=404, detail="Board not found")
+
+        if not current_user.is_admin and board.user_id != current_user.user_id:
+            raise HTTPException(status_code=403, detail="Not authorized to access this board")
+
     image_names = ApiDependencies.invoker.services.board_images.get_all_board_image_names_for_board(
         board_id,
         categories,

invokeai/app/api/routers/client_state.py

@@ -0,0 +1,62 @@
+from fastapi import Body, HTTPException, Path, Query
+from fastapi.routing import APIRouter
+
+from invokeai.app.api.auth_dependencies import CurrentUserOrDefault
+from invokeai.app.api.dependencies import ApiDependencies
+from invokeai.backend.util.logging import logging
+
+client_state_router = APIRouter(prefix="/v1/client_state", tags=["client_state"])
+
+
+@client_state_router.get(
+    "/{queue_id}/get_by_key",
+    operation_id="get_client_state_by_key",
+    response_model=str | None,
+)
+async def get_client_state_by_key(
+    current_user: CurrentUserOrDefault,
+    queue_id: str = Path(description="The queue id (ignored, kept for backwards compatibility)"),
+    key: str = Query(..., description="Key to get"),
+) -> str | None:
+    """Gets the client state for the current user (or system user if not authenticated)"""
+    try:
+        return ApiDependencies.invoker.services.client_state_persistence.get_by_key(current_user.user_id, key)
+    except Exception as e:
+        logging.error(f"Error getting client state: {e}")
+        raise HTTPException(status_code=500, detail="Error getting client state")
+
+
+@client_state_router.post(
+    "/{queue_id}/set_by_key",
+    operation_id="set_client_state",
+    response_model=str,
+)
+async def set_client_state(
+    current_user: CurrentUserOrDefault,
+    queue_id: str = Path(description="The queue id (ignored, kept for backwards compatibility)"),
+    key: str = Query(..., description="Key to set"),
+    value: str = Body(..., description="Stringified value to set"),
+) -> str:
+    """Sets the client state for the current user (or system user if not authenticated)"""
+    try:
+        return ApiDependencies.invoker.services.client_state_persistence.set_by_key(current_user.user_id, key, value)
+    except Exception as e:
+        logging.error(f"Error setting client state: {e}")
+        raise HTTPException(status_code=500, detail="Error setting client state")
+
+
+@client_state_router.post(
+    "/{queue_id}/delete",
+    operation_id="delete_client_state",
+    responses={204: {"description": "Client state deleted"}},
+)
+async def delete_client_state(
+    current_user: CurrentUserOrDefault,
+    queue_id: str = Path(description="The queue id (ignored, kept for backwards compatibility)"),
+) -> None:
+    """Deletes the client state for the current user (or system user if not authenticated)"""
+    try:
+        ApiDependencies.invoker.services.client_state_persistence.delete(current_user.user_id)
+    except Exception as e:
+        logging.error(f"Error deleting client state: {e}")
+        raise HTTPException(status_code=500, detail="Error deleting client state")

invokeai/app/api/routers/images.py

@@ -9,6 +9,7 @@ from fastapi.routing import APIRouter
 from PIL import Image
 from pydantic import BaseModel, Field, model_validator
 
+from invokeai.app.api.auth_dependencies import CurrentUserOrDefault
 from invokeai.app.api.dependencies import ApiDependencies
 from invokeai.app.api.extract_metadata_from_image import extract_metadata_from_image
 from invokeai.app.invocations.fields import MetadataField
@@ -61,6 +62,7 @@ class ResizeToDimensions(BaseModel):
     response_model=ImageDTO,
 )
 async def upload_image(
+    current_user: CurrentUserOrDefault,
     file: UploadFile,
     request: Request,
     response: Response,
@@ -80,7 +82,7 @@ async def upload_image(
         embed=True,
     ),
 ) -> ImageDTO:
-    """Uploads an image"""
+    """Uploads an image for the current user"""
     if not file.content_type or not file.content_type.startswith("image"):
         raise HTTPException(status_code=415, detail="Not an image")
 
@@ -133,6 +135,7 @@ async def upload_image(
             workflow=extracted_metadata.invokeai_workflow,
             graph=extracted_metadata.invokeai_graph,
             is_intermediate=is_intermediate,
+            user_id=current_user.user_id,
         )
 
         response.status_code = 201
@@ -373,6 +376,7 @@ async def get_image_urls(
     response_model=OffsetPaginatedResults[ImageDTO],
 )
 async def list_image_dtos(
+    current_user: CurrentUserOrDefault,
     image_origin: Optional[ResourceOrigin] = Query(default=None, description="The origin of images to list."),
     categories: Optional[list[ImageCategory]] = Query(default=None, description="The categories of image to include."),
     is_intermediate: Optional[bool] = Query(default=None, description="Whether to list intermediate images."),
@@ -386,10 +390,19 @@ async def list_image_dtos(
     starred_first: bool = Query(default=True, description="Whether to sort by starred images first"),
     search_term: Optional[str] = Query(default=None, description="The term to search for"),
 ) -> OffsetPaginatedResults[ImageDTO]:
-    """Gets a list of image DTOs"""
+    """Gets a list of image DTOs for the current user"""
 
     image_dtos = ApiDependencies.invoker.services.images.get_many(
-        offset, limit, starred_first, order_dir, image_origin, categories, is_intermediate, board_id, search_term
+        offset,
+        limit,
+        starred_first,
+        order_dir,
+        image_origin,
+        categories,
+        is_intermediate,
+        board_id,
+        search_term,
+        current_user.user_id,
     )
 
     return image_dtos
@@ -567,6 +580,7 @@ async def get_bulk_download_item(
 
 @images_router.get("/names", operation_id="get_image_names")
 async def get_image_names(
+    current_user: CurrentUserOrDefault,
     image_origin: Optional[ResourceOrigin] = Query(default=None, description="The origin of images to list."),
     categories: Optional[list[ImageCategory]] = Query(default=None, description="The categories of image to include."),
     is_intermediate: Optional[bool] = Query(default=None, description="Whether to list intermediate images."),
@@ -589,6 +603,8 @@ async def get_image_names(
             is_intermediate=is_intermediate,
             board_id=board_id,
             search_term=search_term,
+            user_id=current_user.user_id,
+            is_admin=current_user.is_admin,
         )
         return result
     except Exception:

invokeai/app/api/routers/model_manager.py

@@ -19,6 +19,7 @@ from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field
 from starlette.exceptions import HTTPException
 from typing_extensions import Annotated
 
+from invokeai.app.api.auth_dependencies import AdminUserOrDefault
 from invokeai.app.api.dependencies import ApiDependencies
 from invokeai.app.services.model_images.model_images_common import ModelImageFileNotFoundException
 from invokeai.app.services.model_install.model_install_common import ModelInstallJob
@@ -27,15 +28,19 @@ from invokeai.app.services.model_records import (
     ModelRecordChanges,
     UnknownModelException,
 )
+from invokeai.app.services.orphaned_models import OrphanedModelInfo
 from invokeai.app.util.suppress_output import SuppressOutput
-from invokeai.backend.model_manager import BaseModelType, ModelFormat, ModelType
-from invokeai.backend.model_manager.config import (
-    AnyModelConfig,
-    MainCheckpointConfig,
+from invokeai.backend.model_manager.configs.factory import AnyModelConfig, ModelConfigFactory
+from invokeai.backend.model_manager.configs.main import (
+    Main_Checkpoint_SD1_Config,
+    Main_Checkpoint_SD2_Config,
+    Main_Checkpoint_SDXL_Config,
+    Main_Checkpoint_SDXLRefiner_Config,
 )
 from invokeai.backend.model_manager.load.model_cache.cache_stats import CacheStats
 from invokeai.backend.model_manager.metadata.fetch.huggingface import HuggingFaceMetadataFetch
 from invokeai.backend.model_manager.metadata.metadata_base import ModelMetadataWithFiles, UnknownMetadataException
+from invokeai.backend.model_manager.model_on_disk import ModelOnDisk
 from invokeai.backend.model_manager.search import ModelSearch
 from invokeai.backend.model_manager.starter_models import (
     STARTER_BUNDLES,
@@ -44,6 +49,7 @@ from invokeai.backend.model_manager.starter_models import (
     StarterModelBundle,
     StarterModelWithoutDependencies,
 )
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelFormat, ModelType
 
 model_manager_router = APIRouter(prefix="/v2/models", tags=["model_manager"])
 
@@ -144,6 +150,28 @@ async def list_model_records(
     return ModelsList(models=found_models)
 
 
+@model_manager_router.get(
+    "/missing",
+    operation_id="list_missing_models",
+    responses={200: {"description": "List of models with missing files"}},
+)
+async def list_missing_models() -> ModelsList:
+    """Get models whose files are missing from disk.
+
+    These are models that have database entries but their corresponding
+    weight files have been deleted externally (not via Model Manager).
+    """
+    record_store = ApiDependencies.invoker.services.model_manager.store
+    models_path = ApiDependencies.invoker.services.configuration.models_path
+
+    missing_models: list[AnyModelConfig] = []
+    for model_config in record_store.all_models():
+        if not (models_path / model_config.path).resolve().exists():
+            missing_models.append(model_config)
+
+    return ModelsList(models=missing_models)
+
+
 @model_manager_router.get(
     "/get_by_attrs",
     operation_id="get_model_records_by_attrs",
@@ -165,6 +193,23 @@ async def get_model_records_by_attrs(
     return configs[0]
 
 
+@model_manager_router.get(
+    "/get_by_hash",
+    operation_id="get_model_records_by_hash",
+    response_model=AnyModelConfig,
+)
+async def get_model_records_by_hash(
+    hash: str = Query(description="The hash of the model"),
+) -> AnyModelConfig:
+    """Gets a model by its hash. This is useful for recalling models that were deleted and reinstalled,
+    as the hash remains stable across reinstallations while the key (UUID) changes."""
+    configs = ApiDependencies.invoker.services.model_manager.store.search_by_hash(hash)
+    if not configs:
+        raise HTTPException(status_code=404, detail="No model found with this hash")
+
+    return configs[0]
+
+
 @model_manager_router.get(
     "/i/{key}",
     operation_id="get_model_record",
@@ -188,6 +233,52 @@ async def get_model_record(
         raise HTTPException(status_code=404, detail=str(e))
 
 
+@model_manager_router.post(
+    "/i/{key}/reidentify",
+    operation_id="reidentify_model",
+    responses={
+        200: {
+            "description": "The model configuration was retrieved successfully",
+            "content": {"application/json": {"example": example_model_config}},
+        },
+        400: {"description": "Bad request"},
+        404: {"description": "The model could not be found"},
+    },
+)
+async def reidentify_model(
+    key: Annotated[str, Path(description="Key of the model to reidentify.")],
+    current_admin: AdminUserOrDefault,
+) -> AnyModelConfig:
+    """Attempt to reidentify a model by re-probing its weights file."""
+    try:
+        config = ApiDependencies.invoker.services.model_manager.store.get_model(key)
+        models_path = ApiDependencies.invoker.services.configuration.models_path
+        if pathlib.Path(config.path).is_relative_to(models_path):
+            model_path = pathlib.Path(config.path)
+        else:
+            model_path = models_path / config.path
+        mod = ModelOnDisk(model_path)
+        result = ModelConfigFactory.from_model_on_disk(mod)
+        if result.config is None:
+            raise InvalidModelException("Unable to identify model format")
+
+        # Retain user-editable fields from the original config
+        result.config.path = config.path
+        result.config.key = config.key
+        result.config.name = config.name
+        result.config.description = config.description
+        result.config.cover_image = config.cover_image
+        if hasattr(config, "trigger_phrases") and hasattr(result.config, "trigger_phrases"):
+            result.config.trigger_phrases = config.trigger_phrases
+        result.config.source = config.source
+        result.config.source_type = config.source_type
+
+        new_config = ApiDependencies.invoker.services.model_manager.store.replace_model(config.key, result.config)
+        return new_config
+    except UnknownModelException as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
 class FoundModel(BaseModel):
     path: str = Field(description="Path to the model")
     is_installed: bool = Field(description="Whether or not the model is already installed")
@@ -235,9 +326,10 @@ async def scan_for_models(
             found_model = FoundModel(path=path, is_installed=is_installed)
             scan_results.append(found_model)
     except Exception as e:
+        error_type = type(e).__name__
         raise HTTPException(
             status_code=500,
-            detail=f"An error occurred while searching the directory: {e}",
+            detail=f"An error occurred while searching the directory: {error_type}",
         )
     return scan_results
 
@@ -293,14 +385,13 @@ async def get_hugging_face_models(
 async def update_model_record(
     key: Annotated[str, Path(description="Unique key of model")],
     changes: Annotated[ModelRecordChanges, Body(description="Model config", examples=[example_model_input])],
+    current_admin: AdminUserOrDefault,
 ) -> AnyModelConfig:
     """Update a model's config."""
     logger = ApiDependencies.invoker.services.logger
     record_store = ApiDependencies.invoker.services.model_manager.store
-    installer = ApiDependencies.invoker.services.model_manager.install
     try:
-        record_store.update_model(key, changes=changes)
-        config = installer.sync_model_path(key)
+        config = record_store.update_model(key, changes=changes, allow_class_change=True)
         config = add_cover_image_to_model_config(config, ApiDependencies)
         logger.info(f"Updated model: {key}")
     except UnknownModelException as e:
@@ -357,6 +448,7 @@ async def get_model_image(
 async def update_model_image(
     key: Annotated[str, Path(description="Unique key of model")],
     image: UploadFile,
+    current_admin: AdminUserOrDefault,
 ) -> None:
     if not image.content_type or not image.content_type.startswith("image"):
         raise HTTPException(status_code=415, detail="Not an image")
@@ -390,6 +482,7 @@ async def update_model_image(
     status_code=204,
 )
 async def delete_model(
+    current_admin: AdminUserOrDefault,
     key: str = Path(description="Unique key of model to remove from model registry."),
 ) -> Response:
     """
@@ -410,6 +503,60 @@ async def delete_model(
         raise HTTPException(status_code=404, detail=str(e))
 
 
+class BulkDeleteModelsRequest(BaseModel):
+    """Request body for bulk model deletion."""
+
+    keys: List[str] = Field(description="List of model keys to delete")
+
+
+class BulkDeleteModelsResponse(BaseModel):
+    """Response body for bulk model deletion."""
+
+    deleted: List[str] = Field(description="List of successfully deleted model keys")
+    failed: List[dict] = Field(description="List of failed deletions with error messages")
+
+
+@model_manager_router.post(
+    "/i/bulk_delete",
+    operation_id="bulk_delete_models",
+    responses={
+        200: {"description": "Models deleted (possibly with some failures)"},
+    },
+    status_code=200,
+)
+async def bulk_delete_models(
+    current_admin: AdminUserOrDefault,
+    request: BulkDeleteModelsRequest = Body(description="List of model keys to delete"),
+) -> BulkDeleteModelsResponse:
+    """
+    Delete multiple model records from database.
+
+    The configuration records will be removed. The corresponding weights files will be
+    deleted as well if they reside within the InvokeAI "models" directory.
+    Returns a list of successfully deleted keys and failed deletions with error messages.
+    """
+    logger = ApiDependencies.invoker.services.logger
+    installer = ApiDependencies.invoker.services.model_manager.install
+
+    deleted = []
+    failed = []
+
+    for key in request.keys:
+        try:
+            installer.delete(key)
+            deleted.append(key)
+            logger.info(f"Deleted model: {key}")
+        except UnknownModelException as e:
+            logger.error(f"Failed to delete model {key}: {str(e)}")
+            failed.append({"key": key, "error": str(e)})
+        except Exception as e:
+            logger.error(f"Failed to delete model {key}: {str(e)}")
+            failed.append({"key": key, "error": str(e)})
+
+    logger.info(f"Bulk delete completed: {len(deleted)} deleted, {len(failed)} failed")
+    return BulkDeleteModelsResponse(deleted=deleted, failed=failed)
+
+
 @model_manager_router.delete(
     "/i/{key}/image",
     operation_id="delete_model_image",
@@ -420,6 +567,7 @@ async def delete_model(
     status_code=204,
 )
 async def delete_model_image(
+    current_admin: AdminUserOrDefault,
     key: str = Path(description="Unique key of model image to remove from model_images directory."),
 ) -> None:
     logger = ApiDependencies.invoker.services.logger
@@ -445,6 +593,7 @@ async def delete_model_image(
     status_code=201,
 )
 async def install_model(
+    current_admin: AdminUserOrDefault,
     source: str = Query(description="Model source to install, can be a local path, repo_id, or remote URL"),
     inplace: Optional[bool] = Query(description="Whether or not to install a local model in place", default=False),
     access_token: Optional[str] = Query(description="access token for the remote resource", default=None),
@@ -515,6 +664,7 @@ async def install_model(
     response_class=HTMLResponse,
 )
 async def install_hugging_face_model(
+    current_admin: AdminUserOrDefault,
     source: str = Query(description="HuggingFace repo_id to install"),
 ) -> HTMLResponse:
     """Install a Hugging Face model using a string identifier."""
@@ -643,6 +793,7 @@ async def list_model_installs() -> List[ModelInstallJob]:
     * "waiting" -- Job is waiting in the queue to run
     * "downloading" -- Model file(s) are downloading
     * "running" -- Model has downloaded and the model probing and registration process is running
+    * "paused" -- Job is paused and can be resumed
     * "completed" -- Installation completed successfully
     * "error" -- An error occurred. Details will be in the "error_type" and "error" fields.
     * "cancelled" -- Job was cancelled before completion.
@@ -686,7 +837,10 @@ async def get_model_install_job(id: int = Path(description="Model install id"))
     },
     status_code=201,
 )
-async def cancel_model_install_job(id: int = Path(description="Model install job ID")) -> None:
+async def cancel_model_install_job(
+    current_admin: AdminUserOrDefault,
+    id: int = Path(description="Model install job ID"),
+) -> None:
     """Cancel the model install job(s) corresponding to the given job ID."""
     installer = ApiDependencies.invoker.services.model_manager.install
     try:
@@ -696,6 +850,89 @@ async def cancel_model_install_job(id: int = Path(description="Model install job
     installer.cancel_job(job)
 
 
+@model_manager_router.post(
+    "/install/{id}/pause",
+    operation_id="pause_model_install_job",
+    responses={
+        201: {"description": "The job was paused successfully"},
+        415: {"description": "No such job"},
+    },
+    status_code=201,
+)
+async def pause_model_install_job(id: int = Path(description="Model install job ID")) -> ModelInstallJob:
+    """Pause the model install job corresponding to the given job ID."""
+    installer = ApiDependencies.invoker.services.model_manager.install
+    try:
+        job = installer.get_job_by_id(id)
+    except ValueError as e:
+        raise HTTPException(status_code=415, detail=str(e))
+    installer.pause_job(job)
+    return job
+
+
+@model_manager_router.post(
+    "/install/{id}/resume",
+    operation_id="resume_model_install_job",
+    responses={
+        201: {"description": "The job was resumed successfully"},
+        415: {"description": "No such job"},
+    },
+    status_code=201,
+)
+async def resume_model_install_job(id: int = Path(description="Model install job ID")) -> ModelInstallJob:
+    """Resume a paused model install job corresponding to the given job ID."""
+    installer = ApiDependencies.invoker.services.model_manager.install
+    try:
+        job = installer.get_job_by_id(id)
+    except ValueError as e:
+        raise HTTPException(status_code=415, detail=str(e))
+    installer.resume_job(job)
+    return job
+
+
+@model_manager_router.post(
+    "/install/{id}/restart_failed",
+    operation_id="restart_failed_model_install_job",
+    responses={
+        201: {"description": "Failed files restarted successfully"},
+        415: {"description": "No such job"},
+    },
+    status_code=201,
+)
+async def restart_failed_model_install_job(id: int = Path(description="Model install job ID")) -> ModelInstallJob:
+    """Restart failed or non-resumable file downloads for the given job."""
+    installer = ApiDependencies.invoker.services.model_manager.install
+    try:
+        job = installer.get_job_by_id(id)
+    except ValueError as e:
+        raise HTTPException(status_code=415, detail=str(e))
+    installer.restart_failed(job)
+    return job
+
+
+@model_manager_router.post(
+    "/install/{id}/restart_file",
+    operation_id="restart_model_install_file",
+    responses={
+        201: {"description": "File restarted successfully"},
+        415: {"description": "No such job"},
+    },
+    status_code=201,
+)
+async def restart_model_install_file(
+    id: int = Path(description="Model install job ID"),
+    file_source: AnyHttpUrl = Body(description="File download URL to restart"),
+) -> ModelInstallJob:
+    """Restart a specific file download for the given job."""
+    installer = ApiDependencies.invoker.services.model_manager.install
+    try:
+        job = installer.get_job_by_id(id)
+    except ValueError as e:
+        raise HTTPException(status_code=415, detail=str(e))
+    installer.restart_file(job, str(file_source))
+    return job
+
+
 @model_manager_router.delete(
     "/install",
     operation_id="prune_model_install_jobs",
@@ -704,7 +941,7 @@ async def cancel_model_install_job(id: int = Path(description="Model install job
         400: {"description": "Bad request"},
     },
 )
-async def prune_model_install_jobs() -> Response:
+async def prune_model_install_jobs(current_admin: AdminUserOrDefault) -> Response:
     """Prune all completed and errored jobs from the install job list."""
     ApiDependencies.invoker.services.model_manager.install.prune_jobs()
     return Response(status_code=204)
@@ -724,6 +961,7 @@ async def prune_model_install_jobs() -> Response:
     },
 )
 async def convert_model(
+    current_admin: AdminUserOrDefault,
     key: str = Path(description="Unique key of the safetensors main model to convert to diffusers format."),
 ) -> AnyModelConfig:
     """
@@ -743,9 +981,18 @@ async def convert_model(
         logger.error(str(e))
         raise HTTPException(status_code=424, detail=str(e))
 
-    if not isinstance(model_config, MainCheckpointConfig):
-        logger.error(f"The model with key {key} is not a main checkpoint model.")
-        raise HTTPException(400, f"The model with key {key} is not a main checkpoint model.")
+    if not isinstance(
+        model_config,
+        (
+            Main_Checkpoint_SD1_Config,
+            Main_Checkpoint_SD2_Config,
+            Main_Checkpoint_SDXL_Config,
+            Main_Checkpoint_SDXLRefiner_Config,
+        ),
+    ):
+        msg = f"The model with key {key} is not a main SD 1/2/XL checkpoint model."
+        logger.error(msg)
+        raise HTTPException(400, msg)
 
     with TemporaryDirectory(dir=ApiDependencies.invoker.services.configuration.models_path) as tmpdir:
         convert_path = pathlib.Path(tmpdir) / pathlib.Path(model_config.path).stem
@@ -806,15 +1053,48 @@ class StarterModelResponse(BaseModel):
 def get_is_installed(
     starter_model: StarterModel | StarterModelWithoutDependencies, installed_models: list[AnyModelConfig]
 ) -> bool:
+    from invokeai.backend.model_manager.taxonomy import ModelType
+
     for model in installed_models:
+        # Check if source matches exactly
         if model.source == starter_model.source:
             return True
+        # Check if name (or previous names), base and type match
         if (
             (model.name == starter_model.name or model.name in starter_model.previous_names)
             and model.base == starter_model.base
             and model.type == starter_model.type
         ):
             return True
+
+    # Special handling for Qwen3Encoder models - check by type and variant
+    # This allows renamed models to still be detected as installed
+    if starter_model.type == ModelType.Qwen3Encoder:
+        from invokeai.backend.model_manager.taxonomy import Qwen3VariantType
+
+        # Determine expected variant from source pattern
+        expected_variant: Qwen3VariantType | None = None
+        if "klein-9B" in starter_model.source or "qwen3_8b" in starter_model.source.lower():
+            expected_variant = Qwen3VariantType.Qwen3_8B
+        elif (
+            "klein-4B" in starter_model.source
+            or "qwen3_4b" in starter_model.source.lower()
+            or "Z-Image" in starter_model.source
+        ):
+            expected_variant = Qwen3VariantType.Qwen3_4B
+
+        if expected_variant is not None:
+            for model in installed_models:
+                if model.type == ModelType.Qwen3Encoder and hasattr(model, "variant"):
+                    model_variant = model.variant
+                    # Handle both enum and string values
+                    if isinstance(model_variant, Qwen3VariantType):
+                        if model_variant == expected_variant:
+                            return True
+                    elif isinstance(model_variant, str):
+                        if model_variant == expected_variant.value:
+                            return True
+
     return False
 
 
@@ -863,7 +1143,7 @@ async def get_stats() -> Optional[CacheStats]:
     operation_id="empty_model_cache",
     status_code=200,
 )
-async def empty_model_cache() -> None:
+async def empty_model_cache(current_admin: AdminUserOrDefault) -> None:
     """Drop all models from the model cache to free RAM/VRAM. 'Locked' models that are in active use will not be dropped."""
     # Request 1000GB of room in order to force the cache to drop all models.
     ApiDependencies.invoker.services.logger.info("Emptying model cache.")
@@ -880,11 +1160,11 @@ class HFTokenHelper:
     @classmethod
     def get_status(cls) -> HFTokenStatus:
         try:
-            if huggingface_hub.get_token_permission(huggingface_hub.get_token()):
-                # Valid token!
-                return HFTokenStatus.VALID
-            # No token set
-            return HFTokenStatus.INVALID
+            token = huggingface_hub.get_token()
+            if not token:
+                return HFTokenStatus.INVALID
+            huggingface_hub.whoami(token=token)
+            return HFTokenStatus.VALID
         except Exception:
             return HFTokenStatus.UNKNOWN
 
@@ -913,6 +1193,7 @@ async def get_hf_login_status() -> HFTokenStatus:
 
 @model_manager_router.post("/hf_login", operation_id="do_hf_login", response_model=HFTokenStatus)
 async def do_hf_login(
+    current_admin: AdminUserOrDefault,
     token: str = Body(description="Hugging Face token to use for login", embed=True),
 ) -> HFTokenStatus:
     HFTokenHelper.set_token(token)
@@ -925,5 +1206,81 @@ async def do_hf_login(
 
 
 @model_manager_router.delete("/hf_login", operation_id="reset_hf_token", response_model=HFTokenStatus)
-async def reset_hf_token() -> HFTokenStatus:
+async def reset_hf_token(current_admin: AdminUserOrDefault) -> HFTokenStatus:
     return HFTokenHelper.reset_token()
+
+
+# Orphaned Models Management Routes
+
+
+class DeleteOrphanedModelsRequest(BaseModel):
+    """Request to delete specific orphaned model directories."""
+
+    paths: list[str] = Field(description="List of relative paths to delete")
+
+
+class DeleteOrphanedModelsResponse(BaseModel):
+    """Response from deleting orphaned models."""
+
+    deleted: list[str] = Field(description="Paths that were successfully deleted")
+    errors: dict[str, str] = Field(description="Paths that had errors, with error messages")
+
+
+@model_manager_router.get(
+    "/sync/orphaned",
+    operation_id="get_orphaned_models",
+    response_model=list[OrphanedModelInfo],
+)
+async def get_orphaned_models() -> list[OrphanedModelInfo]:
+    """Find orphaned model directories.
+
+    Orphaned models are directories in the models folder that contain model files
+    but are not referenced in the database. This can happen when models are deleted
+    from the database but the files remain on disk.
+
+    Returns:
+        List of orphaned model directory information
+    """
+    from invokeai.app.services.orphaned_models import OrphanedModelsService
+
+    # Access the database through the model records service
+    model_records_service = ApiDependencies.invoker.services.model_manager.store
+
+    service = OrphanedModelsService(
+        config=ApiDependencies.invoker.services.configuration,
+        db=model_records_service._db,  # Access the database from model records service
+    )
+    return service.find_orphaned_models()
+
+
+@model_manager_router.delete(
+    "/sync/orphaned",
+    operation_id="delete_orphaned_models",
+    response_model=DeleteOrphanedModelsResponse,
+)
+async def delete_orphaned_models(request: DeleteOrphanedModelsRequest) -> DeleteOrphanedModelsResponse:
+    """Delete specified orphaned model directories.
+
+    Args:
+        request: Request containing list of relative paths to delete
+
+    Returns:
+        Response indicating which paths were deleted and which had errors
+    """
+    from invokeai.app.services.orphaned_models import OrphanedModelsService
+
+    # Access the database through the model records service
+    model_records_service = ApiDependencies.invoker.services.model_manager.store
+
+    service = OrphanedModelsService(
+        config=ApiDependencies.invoker.services.configuration,
+        db=model_records_service._db,  # Access the database from model records service
+    )
+
+    results = service.delete_orphaned_models(request.paths)
+
+    # Separate successful deletions from errors
+    deleted = [path for path, status in results.items() if status == "deleted"]
+    errors = {path: status for path, status in results.items() if status != "deleted"}
+
+    return DeleteOrphanedModelsResponse(deleted=deleted, errors=errors)

invokeai/app/api/routers/recall_parameters.py

@@ -0,0 +1,458 @@
+"""Router for updating recallable parameters on the frontend."""
+
+import json
+from typing import Any, Literal, Optional
+
+from fastapi import Body, HTTPException, Path
+from fastapi.routing import APIRouter
+from pydantic import BaseModel, ConfigDict, Field
+
+from invokeai.app.api.dependencies import ApiDependencies
+from invokeai.backend.image_util.controlnet_processor import process_controlnet_image
+from invokeai.backend.model_manager.taxonomy import ModelType
+
+recall_parameters_router = APIRouter(prefix="/v1/recall", tags=["recall"])
+
+
+class LoRARecallParameter(BaseModel):
+    """LoRA configuration for recall"""
+
+    model_name: str = Field(description="The name of the LoRA model")
+    weight: float = Field(default=0.75, ge=-10, le=10, description="The weight for the LoRA")
+    is_enabled: bool = Field(default=True, description="Whether the LoRA is enabled")
+
+
+class ControlNetRecallParameter(BaseModel):
+    """ControlNet configuration for recall"""
+
+    model_name: str = Field(description="The name of the ControlNet/T2I Adapter/Control LoRA model")
+    image_name: Optional[str] = Field(default=None, description="The filename of the control image in outputs/images")
+    weight: float = Field(default=1.0, ge=-1, le=2, description="The weight for the control adapter")
+    begin_step_percent: Optional[float] = Field(
+        default=None, ge=0, le=1, description="When the control adapter is first applied (% of total steps)"
+    )
+    end_step_percent: Optional[float] = Field(
+        default=None, ge=0, le=1, description="When the control adapter is last applied (% of total steps)"
+    )
+    control_mode: Optional[Literal["balanced", "more_prompt", "more_control"]] = Field(
+        default=None, description="The control mode (ControlNet only)"
+    )
+
+
+class IPAdapterRecallParameter(BaseModel):
+    """IP Adapter configuration for recall"""
+
+    model_name: str = Field(description="The name of the IP Adapter model")
+    image_name: Optional[str] = Field(default=None, description="The filename of the reference image in outputs/images")
+    weight: float = Field(default=1.0, ge=-1, le=2, description="The weight for the IP Adapter")
+    begin_step_percent: Optional[float] = Field(
+        default=None, ge=0, le=1, description="When the IP Adapter is first applied (% of total steps)"
+    )
+    end_step_percent: Optional[float] = Field(
+        default=None, ge=0, le=1, description="When the IP Adapter is last applied (% of total steps)"
+    )
+    method: Optional[Literal["full", "style", "composition"]] = Field(default=None, description="The IP Adapter method")
+    image_influence: Optional[Literal["lowest", "low", "medium", "high", "highest"]] = Field(
+        default=None, description="FLUX Redux image influence (if model is flux_redux)"
+    )
+
+
+class RecallParameter(BaseModel):
+    """Request model for updating recallable parameters."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Prompts
+    positive_prompt: Optional[str] = Field(None, description="Positive prompt text")
+    negative_prompt: Optional[str] = Field(None, description="Negative prompt text")
+
+    # Model configuration
+    model: Optional[str] = Field(None, description="Main model name/identifier")
+    refiner_model: Optional[str] = Field(None, description="Refiner model name/identifier")
+    vae_model: Optional[str] = Field(None, description="VAE model name/identifier")
+    scheduler: Optional[str] = Field(None, description="Scheduler name")
+
+    # Generation parameters
+    steps: Optional[int] = Field(None, ge=1, description="Number of generation steps")
+    refiner_steps: Optional[int] = Field(None, ge=0, description="Number of refiner steps")
+    cfg_scale: Optional[float] = Field(None, description="CFG scale for guidance")
+    cfg_rescale_multiplier: Optional[float] = Field(None, description="CFG rescale multiplier")
+    refiner_cfg_scale: Optional[float] = Field(None, description="Refiner CFG scale")
+    guidance: Optional[float] = Field(None, description="Guidance scale")
+
+    # Image parameters
+    width: Optional[int] = Field(None, ge=64, description="Image width in pixels")
+    height: Optional[int] = Field(None, ge=64, description="Image height in pixels")
+    seed: Optional[int] = Field(None, ge=0, description="Random seed")
+
+    # Advanced parameters
+    denoise_strength: Optional[float] = Field(None, ge=0, le=1, description="Denoising strength")
+    refiner_denoise_start: Optional[float] = Field(None, ge=0, le=1, description="Refiner denoising start")
+    clip_skip: Optional[int] = Field(None, ge=0, description="CLIP skip layers")
+    seamless_x: Optional[bool] = Field(None, description="Enable seamless X tiling")
+    seamless_y: Optional[bool] = Field(None, description="Enable seamless Y tiling")
+
+    # Refiner aesthetics
+    refiner_positive_aesthetic_score: Optional[float] = Field(None, description="Refiner positive aesthetic score")
+    refiner_negative_aesthetic_score: Optional[float] = Field(None, description="Refiner negative aesthetic score")
+
+    # LoRAs, ControlNets, and IP Adapters
+    loras: Optional[list[LoRARecallParameter]] = Field(None, description="List of LoRAs with their weights")
+    control_layers: Optional[list[ControlNetRecallParameter]] = Field(
+        None, description="List of control adapters (ControlNet, T2I Adapter, Control LoRA) with their settings"
+    )
+    ip_adapters: Optional[list[IPAdapterRecallParameter]] = Field(
+        None, description="List of IP Adapters with their settings"
+    )
+
+
+def resolve_model_name_to_key(model_name: str, model_type: ModelType = ModelType.Main) -> Optional[str]:
+    """
+    Look up a model by name and return its key.
+
+    Args:
+        model_name: The name of the model to look up
+        model_type: The type of model to search for (default: Main)
+
+    Returns:
+        The key of the first matching model, or None if not found.
+    """
+    logger = ApiDependencies.invoker.services.logger
+    try:
+        models = ApiDependencies.invoker.services.model_manager.store.search_by_attr(
+            model_name=model_name, model_type=model_type
+        )
+
+        if models:
+            logger.info(f"Resolved {model_type.value} model name '{model_name}' to key '{models[0].key}'")
+            return models[0].key
+
+        logger.warning(f"Could not find {model_type.value} model with name '{model_name}'")
+        return None
+    except Exception as e:
+        logger.error(f"Exception during {model_type.value} model lookup: {e}", exc_info=True)
+        return None
+
+
+def load_image_file(image_name: str) -> Optional[dict[str, Any]]:
+    """
+    Load an image from the outputs/images directory.
+
+    Args:
+        image_name: The filename of the image in outputs/images
+
+    Returns:
+        A dictionary with image_name, width, and height, or None if the image cannot be found
+    """
+    logger = ApiDependencies.invoker.services.logger
+    try:
+        # Prefer using the image_files service to validate & open images
+        image_files = ApiDependencies.invoker.services.image_files
+        # Resolve a safe path inside outputs
+        image_path = image_files.get_path(image_name)
+
+        if not image_files.validate_path(str(image_path)):
+            logger.warning(f"Image file not found: {image_name} (searched in {image_path.parent})")
+            return None
+
+        # Open the image via service to leverage caching
+        pil_image = image_files.get(image_name)
+        width, height = pil_image.size
+        logger.info(f"Found image file: {image_name} ({width}x{height})")
+        return {"image_name": image_name, "width": width, "height": height}
+    except Exception as e:
+        logger.warning(f"Error loading image file {image_name}: {e}")
+        return None
+
+
+def resolve_lora_models(loras: list[LoRARecallParameter]) -> list[dict[str, Any]]:
+    """
+    Resolve LoRA model names to keys and build configuration list.
+
+    Args:
+        loras: List of LoRA recall parameters
+
+    Returns:
+        List of resolved LoRA configurations with model keys
+    """
+    logger = ApiDependencies.invoker.services.logger
+    resolved_loras = []
+
+    for lora in loras:
+        model_key = resolve_model_name_to_key(lora.model_name, ModelType.LoRA)
+        if model_key:
+            resolved_loras.append({"model_key": model_key, "weight": lora.weight, "is_enabled": lora.is_enabled})
+        else:
+            logger.warning(f"Skipping LoRA '{lora.model_name}' - model not found")
+
+    return resolved_loras
+
+
+def resolve_control_models(control_layers: list[ControlNetRecallParameter]) -> list[dict[str, Any]]:
+    """
+    Resolve control adapter model names to keys and build configuration list.
+
+    Tries to resolve as ControlNet, T2I Adapter, or Control LoRA in that order.
+
+    Args:
+        control_layers: List of control adapter recall parameters
+
+    Returns:
+        List of resolved control adapter configurations with model keys
+    """
+    logger = ApiDependencies.invoker.services.logger
+    services = ApiDependencies.invoker.services
+    resolved_controls = []
+
+    for control in control_layers:
+        model_key = None
+
+        # Try ControlNet first
+        model_key = resolve_model_name_to_key(control.model_name, ModelType.ControlNet)
+        if not model_key:
+            # Try T2I Adapter
+            model_key = resolve_model_name_to_key(control.model_name, ModelType.T2IAdapter)
+        if not model_key:
+            # Try Control LoRA (also uses LoRA type)
+            model_key = resolve_model_name_to_key(control.model_name, ModelType.LoRA)
+
+        if model_key:
+            config: dict[str, Any] = {"model_key": model_key, "weight": control.weight}
+            if control.image_name is not None:
+                image_data = load_image_file(control.image_name)
+                if image_data:
+                    config["image"] = image_data
+
+                    # Try to process the image using the model's default processor
+                    processed_image_data = process_controlnet_image(control.image_name, model_key, services)
+                    if processed_image_data:
+                        config["processed_image"] = processed_image_data
+                        logger.info(f"Added processed image for control adapter {control.model_name}")
+                else:
+                    logger.warning(f"Could not load image for control adapter: {control.image_name}")
+            if control.begin_step_percent is not None:
+                config["begin_step_percent"] = control.begin_step_percent
+            if control.end_step_percent is not None:
+                config["end_step_percent"] = control.end_step_percent
+            if control.control_mode is not None:
+                config["control_mode"] = control.control_mode
+
+            resolved_controls.append(config)
+        else:
+            logger.warning(f"Skipping control adapter '{control.model_name}' - model not found")
+
+    return resolved_controls
+
+
+def resolve_ip_adapter_models(ip_adapters: list[IPAdapterRecallParameter]) -> list[dict[str, Any]]:
+    """
+    Resolve IP Adapter model names to keys and build configuration list.
+
+    Args:
+        ip_adapters: List of IP Adapter recall parameters
+
+    Returns:
+        List of resolved IP Adapter configurations with model keys
+    """
+    logger = ApiDependencies.invoker.services.logger
+    resolved_adapters = []
+
+    for adapter in ip_adapters:
+        # Try resolving as IP Adapter; if not found, try FLUX Redux
+        model_key = resolve_model_name_to_key(adapter.model_name, ModelType.IPAdapter)
+        if not model_key:
+            model_key = resolve_model_name_to_key(adapter.model_name, ModelType.FluxRedux)
+        if model_key:
+            config: dict[str, Any] = {
+                "model_key": model_key,
+                # Always include weight; ignored by FLUX Redux on the frontend
+                "weight": adapter.weight,
+            }
+            if adapter.image_name is not None:
+                image_data = load_image_file(adapter.image_name)
+                if image_data:
+                    config["image"] = image_data
+                else:
+                    logger.warning(f"Could not load image for IP Adapter: {adapter.image_name}")
+            if adapter.begin_step_percent is not None:
+                config["begin_step_percent"] = adapter.begin_step_percent
+            if adapter.end_step_percent is not None:
+                config["end_step_percent"] = adapter.end_step_percent
+            if adapter.method is not None:
+                config["method"] = adapter.method
+            # Include FLUX Redux image influence when provided
+            if adapter.image_influence is not None:
+                config["image_influence"] = adapter.image_influence
+
+            resolved_adapters.append(config)
+        else:
+            logger.warning(f"Skipping IP Adapter '{adapter.model_name}' - model not found")
+
+    return resolved_adapters
+
+
+@recall_parameters_router.post(
+    "/{queue_id}",
+    operation_id="update_recall_parameters",
+    response_model=dict[str, Any],
+)
+async def update_recall_parameters(
+    queue_id: str = Path(..., description="The queue id to perform this operation on"),
+    parameters: RecallParameter = Body(..., description="Recall parameters to update"),
+) -> dict[str, Any]:
+    """
+    Update recallable parameters that can be recalled on the frontend.
+
+    This endpoint allows updating parameters such as prompt, model, steps, and other
+    generation settings. These parameters are stored in client state and can be
+    accessed by the frontend to populate UI elements.
+
+    Args:
+        queue_id: The queue ID to associate these parameters with
+        parameters: The RecallParameter object containing the parameters to update
+
+    Returns:
+        A dictionary containing the updated parameters and status
+
+    Example:
+        POST /api/v1/recall/{queue_id}
+        {
+            "positive_prompt": "a beautiful landscape",
+            "model": "sd-1.5",
+            "steps": 20,
+            "cfg_scale": 7.5,
+            "width": 512,
+            "height": 512,
+            "seed": 12345
+        }
+    """
+    logger = ApiDependencies.invoker.services.logger
+
+    try:
+        # Get only the parameters that were actually provided (non-None values)
+        provided_params = {k: v for k, v in parameters.model_dump().items() if v is not None}
+
+        if not provided_params:
+            return {"status": "no_parameters_provided", "updated_count": 0}
+
+        # Store each parameter in client state using a consistent key format
+        updated_count = 0
+        for param_key, param_value in provided_params.items():
+            # Convert parameter values to JSON strings for storage
+            value_str = json.dumps(param_value)
+            try:
+                ApiDependencies.invoker.services.client_state_persistence.set_by_key(
+                    queue_id, f"recall_{param_key}", value_str
+                )
+                updated_count += 1
+            except Exception as e:
+                logger.error(f"Error setting recall parameter {param_key}: {e}")
+                raise HTTPException(
+                    status_code=500,
+                    detail=f"Error setting recall parameter {param_key}",
+                )
+
+        logger.info(f"Updated {updated_count} recall parameters for queue {queue_id}")
+
+        # Resolve model name to key if a model was provided
+        if "model" in provided_params and isinstance(provided_params["model"], str):
+            model_name = provided_params["model"]
+            model_key = resolve_model_name_to_key(model_name, ModelType.Main)
+
+            if model_key:
+                logger.info(f"Resolved model name '{model_name}' to key '{model_key}'")
+                provided_params["model"] = model_key
+            else:
+                logger.warning(f"Could not resolve model name '{model_name}' to a model key")
+                # Remove model from parameters if we couldn't resolve it
+                del provided_params["model"]
+
+        # Process LoRAs if provided
+        if "loras" in provided_params:
+            loras_param = parameters.loras
+            if loras_param is not None:
+                resolved_loras = resolve_lora_models(loras_param)
+                provided_params["loras"] = resolved_loras
+                logger.info(f"Resolved {len(resolved_loras)} LoRA(s)")
+
+        # Process control layers if provided
+        if "control_layers" in provided_params:
+            control_layers_param = parameters.control_layers
+            if control_layers_param is not None:
+                resolved_controls = resolve_control_models(control_layers_param)
+                provided_params["control_layers"] = resolved_controls
+                logger.info(f"Resolved {len(resolved_controls)} control layer(s)")
+
+        # Process IP adapters if provided
+        if "ip_adapters" in provided_params:
+            ip_adapters_param = parameters.ip_adapters
+            if ip_adapters_param is not None:
+                resolved_adapters = resolve_ip_adapter_models(ip_adapters_param)
+                provided_params["ip_adapters"] = resolved_adapters
+                logger.info(f"Resolved {len(resolved_adapters)} IP adapter(s)")
+
+        # Emit event to notify frontend of parameter updates
+        try:
+            logger.info(
+                f"Emitting recall_parameters_updated event for queue {queue_id} with {len(provided_params)} parameters"
+            )
+            ApiDependencies.invoker.services.events.emit_recall_parameters_updated(queue_id, provided_params)
+            logger.info("Successfully emitted recall_parameters_updated event")
+        except Exception as e:
+            logger.error(f"Error emitting recall parameters event: {e}", exc_info=True)
+            # Don't fail the request if event emission fails, just log it
+
+        return {
+            "status": "success",
+            "queue_id": queue_id,
+            "updated_count": updated_count,
+            "parameters": provided_params,
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error updating recall parameters: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail="Error updating recall parameters",
+        )
+
+
+@recall_parameters_router.get(
+    "/{queue_id}",
+    operation_id="get_recall_parameters",
+    response_model=dict[str, Any],
+)
+async def get_recall_parameters(
+    queue_id: str = Path(..., description="The queue id to retrieve parameters for"),
+) -> dict[str, Any]:
+    """
+    Retrieve all stored recall parameters for a given queue.
+
+    Returns a dictionary of all recall parameters that have been set for the queue.
+
+    Args:
+        queue_id: The queue ID to retrieve parameters for
+
+    Returns:
+        A dictionary containing all stored recall parameters
+    """
+    logger = ApiDependencies.invoker.services.logger
+
+    try:
+        # Retrieve all recall parameters by iterating through expected keys
+        # Since client_state_persistence doesn't have a "get_all" method, we'll
+        # return an informative response
+        return {
+            "status": "success",
+            "queue_id": queue_id,
+            "note": "Use the frontend to access stored recall parameters, or set specific parameters using POST",
+        }
+
+    except Exception as e:
+        logger.error(f"Error retrieving recall parameters: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail="Error retrieving recall parameters",
+        )

invokeai/app/api/routers/session_queue.py

@@ -2,12 +2,12 @@ from typing import Optional
 
 from fastapi import Body, HTTPException, Path, Query
 from fastapi.routing import APIRouter
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
+from invokeai.app.api.auth_dependencies import AdminUserOrDefault, CurrentUserOrDefault
 from invokeai.app.api.dependencies import ApiDependencies
 from invokeai.app.services.session_processor.session_processor_common import SessionProcessorStatus
 from invokeai.app.services.session_queue.session_queue_common import (
-    QUEUE_ITEM_STATUS,
     Batch,
     BatchStatus,
     CancelAllExceptCurrentResult,
@@ -17,7 +17,7 @@ from invokeai.app.services.session_queue.session_queue_common import (
     DeleteAllExceptCurrentResult,
     DeleteByDestinationResult,
     EnqueueBatchResult,
-    FieldIdentifier,
+    ItemIdsResult,
     PruneResult,
     RetryItemsResult,
     SessionQueueCountsByDestination,
@@ -25,7 +25,8 @@ from invokeai.app.services.session_queue.session_queue_common import (
     SessionQueueItemNotFoundError,
     SessionQueueStatus,
 )
-from invokeai.app.services.shared.pagination import CursorPaginatedResults
+from invokeai.app.services.shared.graph import Graph, GraphExecutionState
+from invokeai.app.services.shared.sqlite.sqlite_common import SQLiteDirection
 
 session_queue_router = APIRouter(prefix="/v1/queue", tags=["queue"])
 
@@ -37,10 +38,38 @@ class SessionQueueAndProcessorStatus(BaseModel):
     processor: SessionProcessorStatus
 
 
-class ValidationRunData(BaseModel):
-    workflow_id: str = Field(description="The id of the workflow being published.")
-    input_fields: list[FieldIdentifier] = Body(description="The input fields for the published workflow")
-    output_fields: list[FieldIdentifier] = Body(description="The output fields for the published workflow")
+def sanitize_queue_item_for_user(
+    queue_item: SessionQueueItem, current_user_id: str, is_admin: bool
+) -> SessionQueueItem:
+    """Sanitize queue item for non-admin users viewing other users' items.
+
+    For non-admin users viewing queue items belonging to other users,
+    the field_values, session graph, and workflow should be hidden/cleared to protect privacy.
+
+    Args:
+        queue_item: The queue item to sanitize
+        current_user_id: The ID of the current user viewing the item
+        is_admin: Whether the current user is an admin
+
+    Returns:
+        The sanitized queue item (sensitive fields cleared if necessary)
+    """
+    # Admins and item owners can see everything
+    if is_admin or queue_item.user_id == current_user_id:
+        return queue_item
+
+    # For non-admins viewing other users' items, clear sensitive fields
+    # Create a shallow copy to avoid mutating the original
+    sanitized_item = queue_item.model_copy(deep=False)
+    sanitized_item.field_values = None
+    sanitized_item.workflow = None
+    # Clear the session graph by replacing it with an empty graph execution state
+    # This prevents information leakage through the generation graph
+    sanitized_item.session = GraphExecutionState(
+        id=queue_item.session.id,
+        graph=Graph(),
+    )
+    return sanitized_item
 
 
 @session_queue_router.post(
@@ -51,53 +80,20 @@ class ValidationRunData(BaseModel):
     },
 )
 async def enqueue_batch(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     batch: Batch = Body(description="Batch to process"),
     prepend: bool = Body(default=False, description="Whether or not to prepend this batch in the queue"),
-    validation_run_data: Optional[ValidationRunData] = Body(
-        default=None,
-        description="The validation run data to use for this batch. This is only used if this is a validation run.",
-    ),
 ) -> EnqueueBatchResult:
-    """Processes a batch and enqueues the output graphs for execution."""
+    """Processes a batch and enqueues the output graphs for execution for the current user."""
     try:
         return await ApiDependencies.invoker.services.session_queue.enqueue_batch(
-            queue_id=queue_id, batch=batch, prepend=prepend
+            queue_id=queue_id, batch=batch, prepend=prepend, user_id=current_user.user_id
         )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while enqueuing batch: {e}")
 
 
-@session_queue_router.get(
-    "/{queue_id}/list",
-    operation_id="list_queue_items",
-    responses={
-        200: {"model": CursorPaginatedResults[SessionQueueItem]},
-    },
-)
-async def list_queue_items(
-    queue_id: str = Path(description="The queue id to perform this operation on"),
-    limit: int = Query(default=50, description="The number of items to fetch"),
-    status: Optional[QUEUE_ITEM_STATUS] = Query(default=None, description="The status of items to fetch"),
-    cursor: Optional[int] = Query(default=None, description="The pagination cursor"),
-    priority: int = Query(default=0, description="The pagination cursor priority"),
-    destination: Optional[str] = Query(default=None, description="The destination of queue items to fetch"),
-) -> CursorPaginatedResults[SessionQueueItem]:
-    """Gets cursor-paginated queue items"""
-
-    try:
-        return ApiDependencies.invoker.services.session_queue.list_queue_items(
-            queue_id=queue_id,
-            limit=limit,
-            status=status,
-            cursor=cursor,
-            priority=priority,
-            destination=destination,
-        )
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Unexpected error while listing all items: {e}")
-
-
 @session_queue_router.get(
     "/{queue_id}/list_all",
     operation_id="list_all_queue_items",
@@ -106,28 +102,85 @@ async def list_queue_items(
     },
 )
 async def list_all_queue_items(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     destination: Optional[str] = Query(default=None, description="The destination of queue items to fetch"),
 ) -> list[SessionQueueItem]:
     """Gets all queue items"""
     try:
-        return ApiDependencies.invoker.services.session_queue.list_all_queue_items(
+        items = ApiDependencies.invoker.services.session_queue.list_all_queue_items(
             queue_id=queue_id,
             destination=destination,
         )
+        # Sanitize items for non-admin users
+        return [sanitize_queue_item_for_user(item, current_user.user_id, current_user.is_admin) for item in items]
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while listing all queue items: {e}")
 
 
+@session_queue_router.get(
+    "/{queue_id}/item_ids",
+    operation_id="get_queue_item_ids",
+    responses={
+        200: {"model": ItemIdsResult},
+    },
+)
+async def get_queue_item_ids(
+    queue_id: str = Path(description="The queue id to perform this operation on"),
+    order_dir: SQLiteDirection = Query(default=SQLiteDirection.Descending, description="The order of sort"),
+) -> ItemIdsResult:
+    """Gets all queue item ids that match the given parameters"""
+    try:
+        return ApiDependencies.invoker.services.session_queue.get_queue_item_ids(queue_id=queue_id, order_dir=order_dir)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Unexpected error while listing all queue item ids: {e}")
+
+
+@session_queue_router.post(
+    "/{queue_id}/items_by_ids",
+    operation_id="get_queue_items_by_item_ids",
+    responses={200: {"model": list[SessionQueueItem]}},
+)
+async def get_queue_items_by_item_ids(
+    current_user: CurrentUserOrDefault,
+    queue_id: str = Path(description="The queue id to perform this operation on"),
+    item_ids: list[int] = Body(
+        embed=True, description="Object containing list of queue item ids to fetch queue items for"
+    ),
+) -> list[SessionQueueItem]:
+    """Gets queue items for the specified queue item ids. Maintains order of item ids."""
+    try:
+        session_queue_service = ApiDependencies.invoker.services.session_queue
+
+        # Fetch queue items preserving the order of requested item ids
+        queue_items: list[SessionQueueItem] = []
+        for item_id in item_ids:
+            try:
+                queue_item = session_queue_service.get_queue_item(item_id=item_id)
+                if queue_item.queue_id != queue_id:  # Auth protection for items from other queues
+                    continue
+                # Sanitize item for non-admin users
+                sanitized_item = sanitize_queue_item_for_user(queue_item, current_user.user_id, current_user.is_admin)
+                queue_items.append(sanitized_item)
+            except Exception:
+                # Skip missing queue items - they may have been deleted between item id fetch and queue item fetch
+                continue
+
+        return queue_items
+    except Exception:
+        raise HTTPException(status_code=500, detail="Failed to get queue items")
+
+
 @session_queue_router.put(
     "/{queue_id}/processor/resume",
     operation_id="resume",
     responses={200: {"model": SessionProcessorStatus}},
 )
 async def resume(
+    current_user: AdminUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> SessionProcessorStatus:
-    """Resumes session processor"""
+    """Resumes session processor. Admin only."""
     try:
         return ApiDependencies.invoker.services.session_processor.resume()
     except Exception as e:
@@ -139,10 +192,11 @@ async def resume(
     operation_id="pause",
     responses={200: {"model": SessionProcessorStatus}},
 )
-async def Pause(
+async def pause(
+    current_user: AdminUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> SessionProcessorStatus:
-    """Pauses session processor"""
+    """Pauses session processor. Admin only."""
     try:
         return ApiDependencies.invoker.services.session_processor.pause()
     except Exception as e:
@@ -155,11 +209,16 @@ async def Pause(
     responses={200: {"model": CancelAllExceptCurrentResult}},
 )
 async def cancel_all_except_current(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> CancelAllExceptCurrentResult:
-    """Immediately cancels all queue items except in-processing items"""
+    """Immediately cancels all queue items except in-processing items. Non-admin users can only cancel their own items."""
     try:
-        return ApiDependencies.invoker.services.session_queue.cancel_all_except_current(queue_id=queue_id)
+        # Admin users can cancel all items, non-admin users can only cancel their own
+        user_id = None if current_user.is_admin else current_user.user_id
+        return ApiDependencies.invoker.services.session_queue.cancel_all_except_current(
+            queue_id=queue_id, user_id=user_id
+        )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while canceling all except current: {e}")
 
@@ -170,11 +229,16 @@ async def cancel_all_except_current(
     responses={200: {"model": DeleteAllExceptCurrentResult}},
 )
 async def delete_all_except_current(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> DeleteAllExceptCurrentResult:
-    """Immediately deletes all queue items except in-processing items"""
+    """Immediately deletes all queue items except in-processing items. Non-admin users can only delete their own items."""
     try:
-        return ApiDependencies.invoker.services.session_queue.delete_all_except_current(queue_id=queue_id)
+        # Admin users can delete all items, non-admin users can only delete their own
+        user_id = None if current_user.is_admin else current_user.user_id
+        return ApiDependencies.invoker.services.session_queue.delete_all_except_current(
+            queue_id=queue_id, user_id=user_id
+        )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while deleting all except current: {e}")
 
@@ -185,13 +249,16 @@ async def delete_all_except_current(
     responses={200: {"model": CancelByBatchIDsResult}},
 )
 async def cancel_by_batch_ids(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     batch_ids: list[str] = Body(description="The list of batch_ids to cancel all queue items for", embed=True),
 ) -> CancelByBatchIDsResult:
-    """Immediately cancels all queue items from the given batch ids"""
+    """Immediately cancels all queue items from the given batch ids. Non-admin users can only cancel their own items."""
     try:
+        # Admin users can cancel all items, non-admin users can only cancel their own
+        user_id = None if current_user.is_admin else current_user.user_id
         return ApiDependencies.invoker.services.session_queue.cancel_by_batch_ids(
-            queue_id=queue_id, batch_ids=batch_ids
+            queue_id=queue_id, batch_ids=batch_ids, user_id=user_id
         )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while canceling by batch id: {e}")
@@ -203,13 +270,16 @@ async def cancel_by_batch_ids(
     responses={200: {"model": CancelByDestinationResult}},
 )
 async def cancel_by_destination(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     destination: str = Query(description="The destination to cancel all queue items for"),
 ) -> CancelByDestinationResult:
-    """Immediately cancels all queue items with the given origin"""
+    """Immediately cancels all queue items with the given destination. Non-admin users can only cancel their own items."""
     try:
+        # Admin users can cancel all items, non-admin users can only cancel their own
+        user_id = None if current_user.is_admin else current_user.user_id
         return ApiDependencies.invoker.services.session_queue.cancel_by_destination(
-            queue_id=queue_id, destination=destination
+            queue_id=queue_id, destination=destination, user_id=user_id
         )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while canceling by destination: {e}")
@@ -221,12 +291,28 @@ async def cancel_by_destination(
     responses={200: {"model": RetryItemsResult}},
 )
 async def retry_items_by_id(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     item_ids: list[int] = Body(description="The queue item ids to retry"),
 ) -> RetryItemsResult:
-    """Immediately cancels all queue items with the given origin"""
+    """Retries the given queue items. Users can only retry their own items unless they are an admin."""
     try:
+        # Check authorization: user must own all items or be an admin
+        if not current_user.is_admin:
+            for item_id in item_ids:
+                try:
+                    queue_item = ApiDependencies.invoker.services.session_queue.get_queue_item(item_id)
+                    if queue_item.user_id != current_user.user_id:
+                        raise HTTPException(
+                            status_code=403, detail=f"You do not have permission to retry queue item {item_id}"
+                        )
+                except SessionQueueItemNotFoundError:
+                    # Skip items that don't exist - they will be handled by retry_items_by_id
+                    continue
+
         return ApiDependencies.invoker.services.session_queue.retry_items_by_id(queue_id=queue_id, item_ids=item_ids)
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while retrying queue items: {e}")
 
@@ -239,15 +325,25 @@ async def retry_items_by_id(
     },
 )
 async def clear(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> ClearResult:
-    """Clears the queue entirely, immediately canceling the currently-executing session"""
+    """Clears the queue entirely. Admin users clear all items; non-admin users only clear their own items. If there's a currently-executing item, users can only cancel it if they own it or are an admin."""
     try:
         queue_item = ApiDependencies.invoker.services.session_queue.get_current(queue_id)
         if queue_item is not None:
+            # Check authorization for canceling the current item
+            if queue_item.user_id != current_user.user_id and not current_user.is_admin:
+                raise HTTPException(
+                    status_code=403, detail="You do not have permission to cancel the currently executing queue item"
+                )
             ApiDependencies.invoker.services.session_queue.cancel_queue_item(queue_item.item_id)
-        clear_result = ApiDependencies.invoker.services.session_queue.clear(queue_id)
+        # Admin users can clear all items, non-admin users can only clear their own
+        user_id = None if current_user.is_admin else current_user.user_id
+        clear_result = ApiDependencies.invoker.services.session_queue.clear(queue_id, user_id=user_id)
         return clear_result
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while clearing queue: {e}")
 
@@ -260,11 +356,14 @@ async def clear(
     },
 )
 async def prune(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> PruneResult:
-    """Prunes all completed or errored queue items"""
+    """Prunes all completed or errored queue items. Non-admin users can only prune their own items."""
     try:
-        return ApiDependencies.invoker.services.session_queue.prune(queue_id)
+        # Admin users can prune all items, non-admin users can only prune their own
+        user_id = None if current_user.is_admin else current_user.user_id
+        return ApiDependencies.invoker.services.session_queue.prune(queue_id, user_id=user_id)
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while pruning queue: {e}")
 
@@ -311,11 +410,12 @@ async def get_next_queue_item(
     },
 )
 async def get_queue_status(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
 ) -> SessionQueueAndProcessorStatus:
     """Gets the status of the session queue"""
     try:
-        queue = ApiDependencies.invoker.services.session_queue.get_queue_status(queue_id)
+        queue = ApiDependencies.invoker.services.session_queue.get_queue_status(queue_id, user_id=current_user.user_id)
         processor = ApiDependencies.invoker.services.session_processor.get_status()
         return SessionQueueAndProcessorStatus(queue=queue, processor=processor)
     except Exception as e:
@@ -349,12 +449,17 @@ async def get_batch_status(
     response_model_exclude_none=True,
 )
 async def get_queue_item(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     item_id: int = Path(description="The queue item to get"),
 ) -> SessionQueueItem:
     """Gets a queue item"""
     try:
-        return ApiDependencies.invoker.services.session_queue.get_queue_item(item_id)
+        queue_item = ApiDependencies.invoker.services.session_queue.get_queue_item(item_id=item_id)
+        if queue_item.queue_id != queue_id:
+            raise HTTPException(status_code=404, detail=f"Queue item with id {item_id} not found in queue {queue_id}")
+        # Sanitize item for non-admin users
+        return sanitize_queue_item_for_user(queue_item, current_user.user_id, current_user.is_admin)
     except SessionQueueItemNotFoundError:
         raise HTTPException(status_code=404, detail=f"Queue item with id {item_id} not found in queue {queue_id}")
     except Exception as e:
@@ -366,12 +471,24 @@ async def get_queue_item(
     operation_id="delete_queue_item",
 )
 async def delete_queue_item(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     item_id: int = Path(description="The queue item to delete"),
 ) -> None:
-    """Deletes a queue item"""
+    """Deletes a queue item. Users can only delete their own items unless they are an admin."""
     try:
+        # Get the queue item to check ownership
+        queue_item = ApiDependencies.invoker.services.session_queue.get_queue_item(item_id)
+
+        # Check authorization: user must own the item or be an admin
+        if queue_item.user_id != current_user.user_id and not current_user.is_admin:
+            raise HTTPException(status_code=403, detail="You do not have permission to delete this queue item")
+
         ApiDependencies.invoker.services.session_queue.delete_queue_item(item_id)
+    except SessionQueueItemNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Queue item with id {item_id} not found in queue {queue_id}")
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while deleting queue item: {e}")
 
@@ -384,14 +501,24 @@ async def delete_queue_item(
     },
 )
 async def cancel_queue_item(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to perform this operation on"),
     item_id: int = Path(description="The queue item to cancel"),
 ) -> SessionQueueItem:
-    """Deletes a queue item"""
+    """Cancels a queue item. Users can only cancel their own items unless they are an admin."""
     try:
+        # Get the queue item to check ownership
+        queue_item = ApiDependencies.invoker.services.session_queue.get_queue_item(item_id)
+
+        # Check authorization: user must own the item or be an admin
+        if queue_item.user_id != current_user.user_id and not current_user.is_admin:
+            raise HTTPException(status_code=403, detail="You do not have permission to cancel this queue item")
+
         return ApiDependencies.invoker.services.session_queue.cancel_queue_item(item_id)
     except SessionQueueItemNotFoundError:
         raise HTTPException(status_code=404, detail=f"Queue item with id {item_id} not found in queue {queue_id}")
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while canceling queue item: {e}")
 
@@ -420,13 +547,16 @@ async def counts_by_destination(
     responses={200: {"model": DeleteByDestinationResult}},
 )
 async def delete_by_destination(
+    current_user: CurrentUserOrDefault,
     queue_id: str = Path(description="The queue id to query"),
     destination: str = Path(description="The destination to query"),
 ) -> DeleteByDestinationResult:
-    """Deletes all items with the given destination"""
+    """Deletes all items with the given destination. Non-admin users can only delete their own items."""
     try:
+        # Admin users can delete all items, non-admin users can only delete their own
+        user_id = None if current_user.is_admin else current_user.user_id
         return ApiDependencies.invoker.services.session_queue.delete_by_destination(
-            queue_id=queue_id, destination=destination
+            queue_id=queue_id, destination=destination, user_id=user_id
         )
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Unexpected error while deleting by destination: {e}")

invokeai/app/api/routers/workflows.py

@@ -106,7 +106,6 @@ async def list_workflows(
     tags: Optional[list[str]] = Query(default=None, description="The tags of workflow to get"),
     query: Optional[str] = Query(default=None, description="The text to query by (matches name and description)"),
     has_been_opened: Optional[bool] = Query(default=None, description="Whether to include/exclude recent workflows"),
-    is_published: Optional[bool] = Query(default=None, description="Whether to include/exclude published workflows"),
 ) -> PaginatedResults[WorkflowRecordListItemWithThumbnailDTO]:
     """Gets a page of workflows"""
     workflows_with_thumbnails: list[WorkflowRecordListItemWithThumbnailDTO] = []
@@ -119,7 +118,6 @@ async def list_workflows(
         categories=categories,
         tags=tags,
         has_been_opened=has_been_opened,
-        is_published=is_published,
     )
     for workflow in workflows.items:
         workflows_with_thumbnails.append(
@@ -225,6 +223,15 @@ async def get_workflow_thumbnail(
         raise HTTPException(status_code=404)
 
 
+@workflows_router.get("/tags", operation_id="get_all_tags")
+async def get_all_tags(
+    categories: Optional[list[WorkflowCategory]] = Query(default=None, description="The categories to include"),
+) -> list[str]:
+    """Gets all unique tags from workflows"""
+
+    return ApiDependencies.invoker.services.workflow_records.get_all_tags(categories=categories)
+
+
 @workflows_router.get("/counts_by_tag", operation_id="get_counts_by_tag")
 async def get_counts_by_tag(
     tags: list[str] = Query(description="The tags to get counts for"),

invokeai/app/api/sockets.py

@@ -6,6 +6,7 @@ from fastapi import FastAPI
 from pydantic import BaseModel
 from socketio import ASGIApp, AsyncServer
 
+from invokeai.app.services.auth.token_service import verify_token
 from invokeai.app.services.events.events_common import (
     BatchEnqueuedEvent,
     BulkDownloadCompleteEvent,
@@ -35,8 +36,12 @@ from invokeai.app.services.events.events_common import (
     QueueClearedEvent,
     QueueEventBase,
     QueueItemStatusChangedEvent,
+    RecallParametersUpdatedEvent,
     register_events,
 )
+from invokeai.backend.util.logging import InvokeAILogger
+
+logger = InvokeAILogger.get_logger()
 
 
 class QueueSubscriptionEvent(BaseModel):
@@ -61,6 +66,7 @@ QUEUE_EVENTS = {
     QueueItemStatusChangedEvent,
     BatchEnqueuedEvent,
     QueueClearedEvent,
+    RecallParametersUpdatedEvent,
 }
 
 MODEL_EVENTS = {
@@ -94,6 +100,13 @@ class SocketIO:
         self._app = ASGIApp(socketio_server=self._sio, socketio_path="/ws/socket.io")
         app.mount("/ws", self._app)
 
+        # Track user information for each socket connection
+        self._socket_users: dict[str, dict[str, Any]] = {}
+
+        # Set up authentication middleware
+        self._sio.on("connect", handler=self._handle_connect)
+        self._sio.on("disconnect", handler=self._handle_disconnect)
+
         self._sio.on(self._sub_queue, handler=self._handle_sub_queue)
         self._sio.on(self._unsub_queue, handler=self._handle_unsub_queue)
         self._sio.on(self._sub_bulk_download, handler=self._handle_sub_bulk_download)
@@ -103,8 +116,83 @@ class SocketIO:
         register_events(MODEL_EVENTS, self._handle_model_event)
         register_events(BULK_DOWNLOAD_EVENTS, self._handle_bulk_image_download_event)
 
+    async def _handle_connect(self, sid: str, environ: dict, auth: dict | None) -> bool:
+        """Handle socket connection and authenticate the user.
+
+        Returns True to accept the connection, False to reject it.
+        Stores user_id in the internal socket users dict for later use.
+        """
+        # Extract token from auth data or headers
+        token = None
+        if auth and isinstance(auth, dict):
+            token = auth.get("token")
+
+        if not token and environ:
+            # Try to get token from headers
+            headers = environ.get("HTTP_AUTHORIZATION", "")
+            if headers.startswith("Bearer "):
+                token = headers[7:]
+
+        # Verify the token
+        if token:
+            token_data = verify_token(token)
+            if token_data:
+                # Store user_id and is_admin in socket users dict
+                self._socket_users[sid] = {
+                    "user_id": token_data.user_id,
+                    "is_admin": token_data.is_admin,
+                }
+                logger.info(
+                    f"Socket {sid} connected with user_id: {token_data.user_id}, is_admin: {token_data.is_admin}"
+                )
+                return True
+
+        # If no valid token, store system user for backward compatibility
+        self._socket_users[sid] = {
+            "user_id": "system",
+            "is_admin": False,
+        }
+        logger.debug(f"Socket {sid} connected as system user (no valid token)")
+        return True
+
+    async def _handle_disconnect(self, sid: str) -> None:
+        """Handle socket disconnection and cleanup user info."""
+        if sid in self._socket_users:
+            del self._socket_users[sid]
+            logger.debug(f"Socket {sid} disconnected and cleaned up")
+
     async def _handle_sub_queue(self, sid: str, data: Any) -> None:
-        await self._sio.enter_room(sid, QueueSubscriptionEvent(**data).queue_id)
+        """Handle queue subscription and add socket to both queue and user-specific rooms."""
+        queue_id = QueueSubscriptionEvent(**data).queue_id
+
+        # Check if we have user info for this socket
+        if sid not in self._socket_users:
+            logger.warning(
+                f"Socket {sid} subscribing to queue {queue_id} but has no user info - need to authenticate via connect event"
+            )
+            # Store as system user temporarily - real auth should happen in connect
+            self._socket_users[sid] = {
+                "user_id": "system",
+                "is_admin": False,
+            }
+
+        user_id = self._socket_users[sid]["user_id"]
+        is_admin = self._socket_users[sid]["is_admin"]
+
+        # Add socket to the queue room
+        await self._sio.enter_room(sid, queue_id)
+
+        # Also add socket to a user-specific room for event filtering
+        user_room = f"user:{user_id}"
+        await self._sio.enter_room(sid, user_room)
+
+        # If admin, also add to admin room to receive all events
+        if is_admin:
+            await self._sio.enter_room(sid, "admin")
+
+        logger.debug(
+            f"Socket {sid} (user_id: {user_id}, is_admin: {is_admin}) subscribed to queue {queue_id} and user room {user_room}"
+        )
 
     async def _handle_unsub_queue(self, sid: str, data: Any) -> None:
         await self._sio.leave_room(sid, QueueSubscriptionEvent(**data).queue_id)
@@ -116,7 +204,62 @@ class SocketIO:
         await self._sio.leave_room(sid, BulkDownloadSubscriptionEvent(**data).bulk_download_id)
 
     async def _handle_queue_event(self, event: FastAPIEvent[QueueEventBase]):
-        await self._sio.emit(event=event[0], data=event[1].model_dump(mode="json"), room=event[1].queue_id)
+        """Handle queue events with user isolation.
+
+        Invocation events (progress, started, complete) are private - only emit to owner and admins.
+        Queue item status events are public - emit to all users (field values hidden via API).
+        Other queue events emit to all subscribers.
+
+        IMPORTANT: Check InvocationEventBase BEFORE QueueItemEventBase since InvocationEventBase
+        inherits from QueueItemEventBase. The order of isinstance checks matters!
+        """
+        try:
+            event_name, event_data = event
+
+            # Import here to avoid circular dependency
+            from invokeai.app.services.events.events_common import InvocationEventBase, QueueItemEventBase
+
+            # Check InvocationEventBase FIRST (before QueueItemEventBase) since it's a subclass
+            # Invocation events (progress, started, complete, error) are private to owner + admins
+            if isinstance(event_data, InvocationEventBase) and hasattr(event_data, "user_id"):
+                user_room = f"user:{event_data.user_id}"
+
+                # Emit to the user's room
+                await self._sio.emit(event=event_name, data=event_data.model_dump(mode="json"), room=user_room)
+
+                # Also emit to admin room so admins can see all events, but strip image preview data
+                # from InvocationProgressEvent to prevent admins from seeing other users' image content
+                if isinstance(event_data, InvocationProgressEvent):
+                    admin_event_data = event_data.model_copy(update={"image": None})
+                    await self._sio.emit(event=event_name, data=admin_event_data.model_dump(mode="json"), room="admin")
+                else:
+                    await self._sio.emit(event=event_name, data=event_data.model_dump(mode="json"), room="admin")
+
+                logger.debug(f"Emitted private invocation event {event_name} to user room {user_room} and admin room")
+
+            # Queue item status events are visible to all users (field values masked via API)
+            # This catches QueueItemStatusChangedEvent but NOT InvocationEvents (already handled above)
+            elif isinstance(event_data, QueueItemEventBase) and hasattr(event_data, "user_id"):
+                # Emit to all subscribers in the queue
+                await self._sio.emit(
+                    event=event_name, data=event_data.model_dump(mode="json"), room=event_data.queue_id
+                )
+
+                logger.info(
+                    f"Emitted public queue item event {event_name} to all subscribers in queue {event_data.queue_id}"
+                )
+
+            else:
+                # For other queue events (like QueueClearedEvent, BatchEnqueuedEvent), emit to all subscribers
+                await self._sio.emit(
+                    event=event_name, data=event_data.model_dump(mode="json"), room=event_data.queue_id
+                )
+                logger.info(
+                    f"Emitted general queue event {event_name} to all subscribers in queue {event_data.queue_id}"
+                )
+        except Exception as e:
+            # Log any unhandled exceptions in event handling to prevent silent failures
+            logger.error(f"Error handling queue event {event[0]}: {e}", exc_info=True)
 
     async def _handle_model_event(self, event: FastAPIEvent[ModelEventBase | DownloadEventBase]) -> None:
         await self._sio.emit(event=event[0], data=event[1].model_dump(mode="json"))

invokeai/app/api_app.py

@@ -17,12 +17,15 @@ from invokeai.app.api.dependencies import ApiDependencies
 from invokeai.app.api.no_cache_staticfiles import NoCacheStaticFiles
 from invokeai.app.api.routers import (
     app_info,
+    auth,
     board_images,
     boards,
+    client_state,
     download_queue,
     images,
     model_manager,
     model_relationships,
+    recall_parameters,
     session_queue,
     style_presets,
     utilities,
@@ -120,6 +123,8 @@ app.add_middleware(GZipMiddleware, minimum_size=1000)
 
 
 # Include all routers
+# Authentication router should be first so it's registered before protected routes
+app.include_router(auth.auth_router, prefix="/api")
 app.include_router(utilities.utilities_router, prefix="/api")
 app.include_router(model_manager.model_manager_router, prefix="/api")
 app.include_router(download_queue.download_queue_router, prefix="/api")
@@ -131,6 +136,8 @@ app.include_router(app_info.app_router, prefix="/api")
 app.include_router(session_queue.session_queue_router, prefix="/api")
 app.include_router(workflows.workflows_router, prefix="/api")
 app.include_router(style_presets.style_presets_router, prefix="/api")
+app.include_router(client_state.client_state_router, prefix="/api")
+app.include_router(recall_parameters.recall_parameters_router, prefix="/api")
 
 app.openapi = get_openapi_func(app)
 
@@ -155,6 +162,12 @@ def overridden_redoc() -> HTMLResponse:
 
 web_root_path = Path(list(web_dir.__path__)[0])
 
+if app_config.unsafe_disable_picklescan:
+    logger.warning(
+        "The unsafe_disable_picklescan option is enabled. This disables malware scanning while installing and"
+        "loading models, which may allow malicious code to be executed. Use at your own risk."
+    )
+
 try:
     app.mount("/", NoCacheStaticFiles(directory=Path(web_root_path, "dist"), html=True), name="ui")
 except RuntimeError:

invokeai/app/invocations/baseinvocation.py

@@ -36,6 +36,9 @@ from pydantic_core import PydanticUndefined
 from invokeai.app.invocations.fields import (
     FieldKind,
     Input,
+    InputFieldJSONSchemaExtra,
+    UIType,
+    migrate_model_ui_type,
 )
 from invokeai.app.services.config.config_default import get_config
 from invokeai.app.services.shared.invocation_context import InvocationContext
@@ -256,7 +259,9 @@ class BaseInvocation(ABC, BaseModel):
     is_intermediate: bool = Field(
         default=False,
         description="Whether or not this is an intermediate invocation.",
-        json_schema_extra={"ui_type": "IsIntermediate", "field_kind": FieldKind.NodeAttribute},
+        json_schema_extra=InputFieldJSONSchemaExtra(
+            input=Input.Direct, field_kind=FieldKind.NodeAttribute, ui_type=UIType._IsIntermediate
+        ).model_dump(exclude_none=True),
     )
     use_cache: bool = Field(
         default=True,
@@ -445,6 +450,15 @@ with warnings.catch_warnings():
     RESERVED_PYDANTIC_FIELD_NAMES = {m[0] for m in inspect.getmembers(_Model())}
 
 
+def is_enum_member(value: Any, enum_class: type[Enum]) -> bool:
+    """Checks if a value is a member of an enum class."""
+    try:
+        enum_class(value)
+        return True
+    except ValueError:
+        return False
+
+
 def validate_fields(model_fields: dict[str, FieldInfo], model_type: str) -> None:
     """
     Validates the fields of an invocation or invocation output:
@@ -456,51 +470,99 @@ def validate_fields(model_fields: dict[str, FieldInfo], model_type: str) -> None
     """
     for name, field in model_fields.items():
         if name in RESERVED_PYDANTIC_FIELD_NAMES:
-            raise InvalidFieldError(f'Invalid field name "{name}" on "{model_type}" (reserved by pydantic)')
+            raise InvalidFieldError(f"{model_type}.{name}: Invalid field name (reserved by pydantic)")
 
         if not field.annotation:
-            raise InvalidFieldError(f'Invalid field type "{name}" on "{model_type}" (missing annotation)')
+            raise InvalidFieldError(f"{model_type}.{name}: Invalid field type (missing annotation)")
 
         if not isinstance(field.json_schema_extra, dict):
-            raise InvalidFieldError(
-                f'Invalid field definition for "{name}" on "{model_type}" (missing json_schema_extra dict)'
-            )
+            raise InvalidFieldError(f"{model_type}.{name}: Invalid field definition (missing json_schema_extra dict)")
 
         field_kind = field.json_schema_extra.get("field_kind", None)
 
         # must have a field_kind
-        if not isinstance(field_kind, FieldKind):
+        if not is_enum_member(field_kind, FieldKind):
             raise InvalidFieldError(
-                f'Invalid field definition for "{name}" on "{model_type}" (maybe it\'s not an InputField or OutputField?)'
+                f"{model_type}.{name}: Invalid field definition for (maybe it's not an InputField or OutputField?)"
             )
 
-        if field_kind is FieldKind.Input and (
+        if field_kind == FieldKind.Input.value and (
             name in RESERVED_NODE_ATTRIBUTE_FIELD_NAMES or name in RESERVED_INPUT_FIELD_NAMES
         ):
-            raise InvalidFieldError(f'Invalid field name "{name}" on "{model_type}" (reserved input field name)')
+            raise InvalidFieldError(f"{model_type}.{name}: Invalid field name (reserved input field name)")
 
-        if field_kind is FieldKind.Output and name in RESERVED_OUTPUT_FIELD_NAMES:
-            raise InvalidFieldError(f'Invalid field name "{name}" on "{model_type}" (reserved output field name)')
+        if field_kind == FieldKind.Output.value and name in RESERVED_OUTPUT_FIELD_NAMES:
+            raise InvalidFieldError(f"{model_type}.{name}: Invalid field name (reserved output field name)")
 
-        if (field_kind is FieldKind.Internal) and name not in RESERVED_INPUT_FIELD_NAMES:
-            raise InvalidFieldError(
-                f'Invalid field name "{name}" on "{model_type}" (internal field without reserved name)'
-            )
+        if field_kind == FieldKind.Internal.value and name not in RESERVED_INPUT_FIELD_NAMES:
+            raise InvalidFieldError(f"{model_type}.{name}: Invalid field name (internal field without reserved name)")
 
         # node attribute fields *must* be in the reserved list
         if (
-            field_kind is FieldKind.NodeAttribute
+            field_kind == FieldKind.NodeAttribute.value
             and name not in RESERVED_NODE_ATTRIBUTE_FIELD_NAMES
             and name not in RESERVED_OUTPUT_FIELD_NAMES
         ):
             raise InvalidFieldError(
-                f'Invalid field name "{name}" on "{model_type}" (node attribute field without reserved name)'
+                f"{model_type}.{name}: Invalid field name (node attribute field without reserved name)"
             )
 
         ui_type = field.json_schema_extra.get("ui_type", None)
-        if isinstance(ui_type, str) and ui_type.startswith("DEPRECATED_"):
-            logger.warning(f'"UIType.{ui_type.split("_")[-1]}" is deprecated, ignoring')
-            field.json_schema_extra.pop("ui_type")
+        ui_model_base = field.json_schema_extra.get("ui_model_base", None)
+        ui_model_type = field.json_schema_extra.get("ui_model_type", None)
+        ui_model_variant = field.json_schema_extra.get("ui_model_variant", None)
+        ui_model_format = field.json_schema_extra.get("ui_model_format", None)
+
+        if ui_type is not None:
+            # There are 3 cases where we may need to take action:
+            #
+            # 1. The ui_type is a migratable, deprecated value. For example, ui_type=UIType.MainModel value is
+            #    deprecated and should be migrated to:
+            #       - ui_model_base=[BaseModelType.StableDiffusion1, BaseModelType.StableDiffusion2]
+            #       - ui_model_type=[ModelType.Main]
+            #
+            # 2. ui_type was set in conjunction with any of the new ui_model_[base|type|variant|format] fields, which
+            #    is not allowed (they are mutually exclusive). In this case, we ignore ui_type and log a warning.
+            #
+            # 3. ui_type is a deprecated value that is not migratable. For example, ui_type=UIType.Image is deprecated;
+            #    Image fields are now automatically detected based on the field's type annotation. In this case, we
+            #    ignore ui_type and log a warning.
+            #
+            # The cases must be checked in this order to ensure proper handling.
+
+            # Easier to work with as an enum
+            ui_type = UIType(ui_type)
+
+            # The enum member values are not always the same as their names - we want to log the name so the user can
+            # easily review their code and see where the deprecated enum member is used.
+            human_readable_name = f"UIType.{ui_type.name}"
+
+            # Case 1: migratable deprecated value
+            did_migrate = migrate_model_ui_type(ui_type, field.json_schema_extra)
+
+            if did_migrate:
+                logger.warning(
+                    f'{model_type}.{name}: Migrated deprecated "ui_type" "{human_readable_name}" to new ui_model_[base|type|variant|format] fields'
+                )
+                field.json_schema_extra.pop("ui_type")
+
+            # Case 2: mutually exclusive with new fields
+            elif (
+                ui_model_base is not None
+                or ui_model_type is not None
+                or ui_model_variant is not None
+                or ui_model_format is not None
+            ):
+                logger.warning(
+                    f'{model_type}.{name}: "ui_type" is mutually exclusive with "ui_model_[base|type|format|variant]", ignoring "ui_type"'
+                )
+                field.json_schema_extra.pop("ui_type")
+
+            # Case 3: deprecated value that is not migratable
+            elif ui_type.startswith("DEPRECATED_"):
+                logger.warning(f'{model_type}.{name}: Deprecated "ui_type" "{human_readable_name}", ignoring')
+                field.json_schema_extra.pop("ui_type")
+
     return None
 
 

invokeai/app/invocations/cogview4_denoise.py

@@ -22,7 +22,7 @@ from invokeai.app.invocations.model import TransformerField
 from invokeai.app.invocations.primitives import LatentsOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.flux.sampling_utils import clip_timestep_schedule_fractional
-from invokeai.backend.model_manager.config import BaseModelType
+from invokeai.backend.model_manager.taxonomy import BaseModelType
 from invokeai.backend.rectified_flow.rectified_flow_inpaint_extension import RectifiedFlowInpaintExtension
 from invokeai.backend.stable_diffusion.diffusers_pipeline import PipelineIntermediateState
 from invokeai.backend.stable_diffusion.diffusion.conditioning_data import CogView4ConditioningInfo

invokeai/app/invocations/cogview4_image_to_latents.py

@@ -17,6 +17,7 @@ from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.model_manager.load.load_base import LoadedModel
 from invokeai.backend.stable_diffusion.diffusers_pipeline import image_resized_to_grid_as_tensor
 from invokeai.backend.util.devices import TorchDevice
+from invokeai.backend.util.vae_working_memory import estimate_vae_working_memory_cogview4
 
 # TODO(ryand): This is effectively a copy of SD3ImageToLatentsInvocation and a subset of ImageToLatentsInvocation. We
 # should refactor to avoid this duplication.
@@ -38,7 +39,11 @@ class CogView4ImageToLatentsInvocation(BaseInvocation, WithMetadata, WithBoard):
 
     @staticmethod
     def vae_encode(vae_info: LoadedModel, image_tensor: torch.Tensor) -> torch.Tensor:
-        with vae_info as vae:
+        assert isinstance(vae_info.model, AutoencoderKL)
+        estimated_working_memory = estimate_vae_working_memory_cogview4(
+            operation="encode", image_tensor=image_tensor, vae=vae_info.model
+        )
+        with vae_info.model_on_device(working_mem_bytes=estimated_working_memory) as (_, vae):
             assert isinstance(vae, AutoencoderKL)
 
             vae.disable_tiling()
@@ -62,6 +67,8 @@ class CogView4ImageToLatentsInvocation(BaseInvocation, WithMetadata, WithBoard):
             image_tensor = einops.rearrange(image_tensor, "c h w -> 1 c h w")
 
         vae_info = context.models.load(self.vae.vae)
+        assert isinstance(vae_info.model, AutoencoderKL)
+
         latents = self.vae_encode(vae_info=vae_info, image_tensor=image_tensor)
 
         latents = latents.to("cpu")

invokeai/app/invocations/cogview4_latents_to_image.py

@@ -6,7 +6,6 @@ from einops import rearrange
 from PIL import Image
 
 from invokeai.app.invocations.baseinvocation import BaseInvocation, Classification, invocation
-from invokeai.app.invocations.constants import LATENT_SCALE_FACTOR
 from invokeai.app.invocations.fields import (
     FieldDescriptions,
     Input,
@@ -20,6 +19,7 @@ from invokeai.app.invocations.primitives import ImageOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.stable_diffusion.extensions.seamless import SeamlessExt
 from invokeai.backend.util.devices import TorchDevice
+from invokeai.backend.util.vae_working_memory import estimate_vae_working_memory_cogview4
 
 # TODO(ryand): This is effectively a copy of SD3LatentsToImageInvocation and a subset of LatentsToImageInvocation. We
 # should refactor to avoid this duplication.
@@ -39,22 +39,15 @@ class CogView4LatentsToImageInvocation(BaseInvocation, WithMetadata, WithBoard):
     latents: LatentsField = InputField(description=FieldDescriptions.latents, input=Input.Connection)
     vae: VAEField = InputField(description=FieldDescriptions.vae, input=Input.Connection)
 
-    def _estimate_working_memory(self, latents: torch.Tensor, vae: AutoencoderKL) -> int:
-        """Estimate the working memory required by the invocation in bytes."""
-        out_h = LATENT_SCALE_FACTOR * latents.shape[-2]
-        out_w = LATENT_SCALE_FACTOR * latents.shape[-1]
-        element_size = next(vae.parameters()).element_size()
-        scaling_constant = 2200  # Determined experimentally.
-        working_memory = out_h * out_w * element_size * scaling_constant
-        return int(working_memory)
-
     @torch.no_grad()
     def invoke(self, context: InvocationContext) -> ImageOutput:
         latents = context.tensors.load(self.latents.latents_name)
 
         vae_info = context.models.load(self.vae.vae)
         assert isinstance(vae_info.model, (AutoencoderKL))
-        estimated_working_memory = self._estimate_working_memory(latents, vae_info.model)
+        estimated_working_memory = estimate_vae_working_memory_cogview4(
+            operation="decode", image_tensor=latents, vae=vae_info.model
+        )
         with (
             SeamlessExt.static_patch_model(vae_info.model, self.vae.seamless_axes),
             vae_info.model_on_device(working_mem_bytes=estimated_working_memory) as (_, vae),

invokeai/app/invocations/cogview4_model_loader.py

@@ -5,7 +5,7 @@ from invokeai.app.invocations.baseinvocation import (
     invocation,
     invocation_output,
 )
-from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField
 from invokeai.app.invocations.model import (
     GlmEncoderField,
     ModelIdentifierField,
@@ -13,7 +13,7 @@ from invokeai.app.invocations.model import (
     VAEField,
 )
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager.config import SubModelType
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType, SubModelType
 
 
 @invocation_output("cogview4_model_loader_output")
@@ -38,8 +38,9 @@ class CogView4ModelLoaderInvocation(BaseInvocation):
 
     model: ModelIdentifierField = InputField(
         description=FieldDescriptions.cogview4_model,
-        ui_type=UIType.CogView4MainModel,
         input=Input.Direct,
+        ui_model_base=BaseModelType.CogView4,
+        ui_model_type=ModelType.Main,
     )
 
     def invoke(self, context: InvocationContext) -> CogView4ModelLoaderOutput:

invokeai/app/invocations/cogview4_text_encoder.py

@@ -6,11 +6,11 @@ from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField
 from invokeai.app.invocations.model import GlmEncoderField
 from invokeai.app.invocations.primitives import CogView4ConditioningOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.load.model_cache.utils import get_effective_device
 from invokeai.backend.stable_diffusion.diffusion.conditioning_data import (
     CogView4ConditioningInfo,
     ConditioningFieldData,
 )
-from invokeai.backend.util.devices import TorchDevice
 
 # The CogView4 GLM Text Encoder max sequence length set based on the default in diffusers.
 COGVIEW4_GLM_MAX_SEQ_LEN = 1024
@@ -37,6 +37,8 @@ class CogView4TextEncoderInvocation(BaseInvocation):
     @torch.no_grad()
     def invoke(self, context: InvocationContext) -> CogView4ConditioningOutput:
         glm_embeds = self._glm_encode(context, max_seq_len=COGVIEW4_GLM_MAX_SEQ_LEN)
+        # Move embeddings to CPU for storage to save VRAM
+        glm_embeds = glm_embeds.detach().to("cpu")
         conditioning_data = ConditioningFieldData(conditionings=[CogView4ConditioningInfo(glm_embeds=glm_embeds)])
         conditioning_name = context.conditioning.save(conditioning_data)
         return CogView4ConditioningOutput.build(conditioning_name)
@@ -45,10 +47,18 @@ class CogView4TextEncoderInvocation(BaseInvocation):
         prompt = [self.prompt]
 
         # TODO(ryand): Add model inputs to the invocation rather than hard-coding.
+        glm_text_encoder_info = context.models.load(self.glm_encoder.text_encoder)
         with (
-            context.models.load(self.glm_encoder.text_encoder).model_on_device() as (_, glm_text_encoder),
+            glm_text_encoder_info.model_on_device() as (_, glm_text_encoder),
             context.models.load(self.glm_encoder.tokenizer).model_on_device() as (_, glm_tokenizer),
         ):
+            repaired_tensors = glm_text_encoder_info.repair_required_tensors_on_device()
+            device = get_effective_device(glm_text_encoder)
+            if repaired_tensors > 0:
+                context.logger.warning(
+                    f"Recovered {repaired_tensors} required GLM tensor(s) onto {device} after a partial device mismatch."
+                )
+
             context.util.signal_progress("Running GLM text encoder")
             assert isinstance(glm_text_encoder, GlmModel)
             assert isinstance(glm_tokenizer, PreTrainedTokenizerFast)
@@ -84,9 +94,7 @@ class CogView4TextEncoderInvocation(BaseInvocation):
                     device=text_input_ids.device,
                 )
                 text_input_ids = torch.cat([pad_ids, text_input_ids], dim=1)
-            prompt_embeds = glm_text_encoder(
-                text_input_ids.to(TorchDevice.choose_torch_device()), output_hidden_states=True
-            ).hidden_states[-2]
+            prompt_embeds = glm_text_encoder(text_input_ids.to(device), output_hidden_states=True).hidden_states[-2]
 
         assert isinstance(prompt_embeds, torch.Tensor)
         return prompt_embeds

invokeai/app/invocations/compel.py

@@ -103,7 +103,7 @@ class CompelInvocation(BaseInvocation):
                 textual_inversion_manager=ti_manager,
                 dtype_for_device_getter=TorchDevice.choose_torch_dtype,
                 truncate_long_prompts=False,
-                device=TorchDevice.choose_torch_device(),
+                device=text_encoder.device,  # Use the device the model is actually on
                 split_long_text_mode=SplitLongTextMode.SENTENCES,
             )
 
@@ -212,7 +212,7 @@ class SDXLPromptInvocationBase:
                 truncate_long_prompts=False,  # TODO:
                 returned_embeddings_type=ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NON_NORMALIZED,  # TODO: clip skip
                 requires_pooled=get_pooled,
-                device=TorchDevice.choose_torch_device(),
+                device=text_encoder.device,  # Use the device the model is actually on
                 split_long_text_mode=SplitLongTextMode.SENTENCES,
             )
 

invokeai/app/invocations/controlnet.py

@@ -16,7 +16,6 @@ from invokeai.app.invocations.fields import (
     ImageField,
     InputField,
     OutputField,
-    UIType,
 )
 from invokeai.app.invocations.model import ModelIdentifierField
 from invokeai.app.invocations.primitives import ImageOutput
@@ -28,6 +27,7 @@ from invokeai.app.util.controlnet_utils import (
     heuristic_resize_fast,
 )
 from invokeai.backend.image_util.util import np_to_pil, pil_to_np
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
 
 
 class ControlField(BaseModel):
@@ -63,13 +63,17 @@ class ControlOutput(BaseInvocationOutput):
     control: ControlField = OutputField(description=FieldDescriptions.control)
 
 
-@invocation("controlnet", title="ControlNet - SD1.5, SDXL", tags=["controlnet"], category="controlnet", version="1.1.3")
+@invocation(
+    "controlnet", title="ControlNet - SD1.5, SD2, SDXL", tags=["controlnet"], category="controlnet", version="1.1.3"
+)
 class ControlNetInvocation(BaseInvocation):
     """Collects ControlNet info to pass to other nodes"""
 
     image: ImageField = InputField(description="The control image")
     control_model: ModelIdentifierField = InputField(
-        description=FieldDescriptions.controlnet_model, ui_type=UIType.ControlNetModel
+        description=FieldDescriptions.controlnet_model,
+        ui_model_base=[BaseModelType.StableDiffusion1, BaseModelType.StableDiffusion2, BaseModelType.StableDiffusionXL],
+        ui_model_type=ModelType.ControlNet,
     )
     control_weight: Union[float, List[float]] = InputField(
         default=1.0, ge=-1, le=2, description="The weight given to the ControlNet"

invokeai/app/invocations/create_gradient_mask.py

@@ -20,9 +20,7 @@ from invokeai.app.invocations.fields import (
 from invokeai.app.invocations.image_to_latents import ImageToLatentsInvocation
 from invokeai.app.invocations.model import UNetField, VAEField
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager import LoadedModel
-from invokeai.backend.model_manager.config import MainConfigBase
-from invokeai.backend.model_manager.taxonomy import ModelVariantType
+from invokeai.backend.model_manager.taxonomy import FluxVariantType, ModelType, ModelVariantType
 from invokeai.backend.stable_diffusion.diffusers_pipeline import image_resized_to_grid_as_tensor
 
 
@@ -182,10 +180,11 @@ class CreateGradientMaskInvocation(BaseInvocation):
         if self.unet is not None and self.vae is not None and self.image is not None:
             # all three fields must be present at the same time
             main_model_config = context.models.get_config(self.unet.unet.key)
-            assert isinstance(main_model_config, MainConfigBase)
-            if main_model_config.variant is ModelVariantType.Inpaint:
+            assert main_model_config.type is ModelType.Main
+            variant = getattr(main_model_config, "variant", None)
+            if variant is ModelVariantType.Inpaint or variant is FluxVariantType.DevFill:
                 mask = dilated_mask_tensor
-                vae_info: LoadedModel = context.models.load(self.vae.vae)
+                vae_info = context.models.load(self.vae.vae)
                 image = context.images.get_pil(self.image.image_name)
                 image_tensor = image_resized_to_grid_as_tensor(image.convert("RGB"))
                 if image_tensor.dim() == 3:

invokeai/app/invocations/denoise_latents.py

@@ -39,7 +39,7 @@ from invokeai.app.invocations.t2i_adapter import T2IAdapterField
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.app.util.controlnet_utils import prepare_control_image
 from invokeai.backend.ip_adapter.ip_adapter import IPAdapter
-from invokeai.backend.model_manager.config import AnyModelConfig
+from invokeai.backend.model_manager.configs.factory import AnyModelConfig
 from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelVariantType
 from invokeai.backend.model_patcher import ModelPatcher
 from invokeai.backend.patches.layer_patcher import LayerPatcher

invokeai/app/invocations/fields.py

@@ -1,11 +1,19 @@
 from enum import Enum
 from typing import Any, Callable, Optional, Tuple
 
-from pydantic import BaseModel, ConfigDict, Field, RootModel, TypeAdapter, model_validator
+from pydantic import BaseModel, ConfigDict, Field, RootModel, TypeAdapter
 from pydantic.fields import _Unset
 from pydantic_core import PydanticUndefined
 
 from invokeai.app.util.metaenum import MetaEnum
+from invokeai.backend.image_util.segment_anything.shared import BoundingBox
+from invokeai.backend.model_manager.taxonomy import (
+    BaseModelType,
+    ClipVariantType,
+    ModelFormat,
+    ModelType,
+    ModelVariantType,
+)
 from invokeai.backend.util.logging import InvokeAILogger
 
 logger = InvokeAILogger.get_logger()
@@ -38,35 +46,6 @@ class UIType(str, Enum, metaclass=MetaEnum):
     used, and the type will be ignored. They are included here for backwards compatibility.
     """
 
-    # region Model Field Types
-    MainModel = "MainModelField"
-    CogView4MainModel = "CogView4MainModelField"
-    FluxMainModel = "FluxMainModelField"
-    SD3MainModel = "SD3MainModelField"
-    SDXLMainModel = "SDXLMainModelField"
-    SDXLRefinerModel = "SDXLRefinerModelField"
-    ONNXModel = "ONNXModelField"
-    VAEModel = "VAEModelField"
-    FluxVAEModel = "FluxVAEModelField"
-    LoRAModel = "LoRAModelField"
-    ControlNetModel = "ControlNetModelField"
-    IPAdapterModel = "IPAdapterModelField"
-    T2IAdapterModel = "T2IAdapterModelField"
-    T5EncoderModel = "T5EncoderModelField"
-    CLIPEmbedModel = "CLIPEmbedModelField"
-    CLIPLEmbedModel = "CLIPLEmbedModelField"
-    CLIPGEmbedModel = "CLIPGEmbedModelField"
-    SpandrelImageToImageModel = "SpandrelImageToImageModelField"
-    ControlLoRAModel = "ControlLoRAModelField"
-    SigLipModel = "SigLipModelField"
-    FluxReduxModel = "FluxReduxModelField"
-    LlavaOnevisionModel = "LLaVAModelField"
-    Imagen3Model = "Imagen3ModelField"
-    Imagen4Model = "Imagen4ModelField"
-    ChatGPT4oModel = "ChatGPT4oModelField"
-    FluxKontextModel = "FluxKontextModelField"
-    # endregion
-
     # region Misc Field Types
     Scheduler = "SchedulerField"
     Any = "AnyField"
@@ -75,6 +54,7 @@ class UIType(str, Enum, metaclass=MetaEnum):
     # region Internal Field Types
     _Collection = "CollectionField"
     _CollectionItem = "CollectionItemField"
+    _IsIntermediate = "IsIntermediate"
     # endregion
 
     # region DEPRECATED
@@ -112,13 +92,44 @@ class UIType(str, Enum, metaclass=MetaEnum):
     CollectionItem = "DEPRECATED_CollectionItem"
     Enum = "DEPRECATED_Enum"
     WorkflowField = "DEPRECATED_WorkflowField"
-    IsIntermediate = "DEPRECATED_IsIntermediate"
     BoardField = "DEPRECATED_BoardField"
     MetadataItem = "DEPRECATED_MetadataItem"
     MetadataItemCollection = "DEPRECATED_MetadataItemCollection"
     MetadataItemPolymorphic = "DEPRECATED_MetadataItemPolymorphic"
     MetadataDict = "DEPRECATED_MetadataDict"
 
+    # Deprecated Model Field Types - use ui_model_[base|type|variant|format] instead
+    MainModel = "DEPRECATED_MainModelField"
+    CogView4MainModel = "DEPRECATED_CogView4MainModelField"
+    FluxMainModel = "DEPRECATED_FluxMainModelField"
+    SD3MainModel = "DEPRECATED_SD3MainModelField"
+    SDXLMainModel = "DEPRECATED_SDXLMainModelField"
+    SDXLRefinerModel = "DEPRECATED_SDXLRefinerModelField"
+    ONNXModel = "DEPRECATED_ONNXModelField"
+    VAEModel = "DEPRECATED_VAEModelField"
+    FluxVAEModel = "DEPRECATED_FluxVAEModelField"
+    LoRAModel = "DEPRECATED_LoRAModelField"
+    ControlNetModel = "DEPRECATED_ControlNetModelField"
+    IPAdapterModel = "DEPRECATED_IPAdapterModelField"
+    T2IAdapterModel = "DEPRECATED_T2IAdapterModelField"
+    T5EncoderModel = "DEPRECATED_T5EncoderModelField"
+    CLIPEmbedModel = "DEPRECATED_CLIPEmbedModelField"
+    CLIPLEmbedModel = "DEPRECATED_CLIPLEmbedModelField"
+    CLIPGEmbedModel = "DEPRECATED_CLIPGEmbedModelField"
+    SpandrelImageToImageModel = "DEPRECATED_SpandrelImageToImageModelField"
+    ControlLoRAModel = "DEPRECATED_ControlLoRAModelField"
+    SigLipModel = "DEPRECATED_SigLipModelField"
+    FluxReduxModel = "DEPRECATED_FluxReduxModelField"
+    LlavaOnevisionModel = "DEPRECATED_LLaVAModelField"
+    Imagen3Model = "DEPRECATED_Imagen3ModelField"
+    Imagen4Model = "DEPRECATED_Imagen4ModelField"
+    ChatGPT4oModel = "DEPRECATED_ChatGPT4oModelField"
+    Gemini2_5Model = "DEPRECATED_Gemini2_5ModelField"
+    FluxKontextModel = "DEPRECATED_FluxKontextModelField"
+    Veo3Model = "DEPRECATED_Veo3ModelField"
+    RunwayModel = "DEPRECATED_RunwayModelField"
+    # endregion
+
 
 class UIComponent(str, Enum, metaclass=MetaEnum):
     """
@@ -143,6 +154,7 @@ class FieldDescriptions:
     clip = "CLIP (tokenizer, text encoder, LoRAs) and skipped layer count"
     t5_encoder = "T5 tokenizer and text encoder"
     glm_encoder = "GLM (THUDM) tokenizer and text encoder"
+    qwen3_encoder = "Qwen3 tokenizer and text encoder"
     clip_embed_model = "CLIP Embed loader"
     clip_g_model = "CLIP-G Embed loader"
     unet = "UNet (scheduler, LoRAs)"
@@ -158,6 +170,7 @@ class FieldDescriptions:
     flux_model = "Flux model (Transformer) to load"
     sd3_model = "SD3 model (MMDiTX) to load"
     cogview4_model = "CogView4 model (Transformer) to load"
+    z_image_model = "Z-Image model (Transformer) to load"
     sdxl_main_model = "SDXL Main model (UNet, VAE, CLIP1, CLIP2) to load"
     sdxl_refiner_model = "SDXL Refiner Main Modde (UNet, VAE, CLIP2) to load"
     onnx_main_model = "ONNX Main model (UNet, VAE, CLIP) to load"
@@ -230,6 +243,12 @@ class BoardField(BaseModel):
     board_id: str = Field(description="The id of the board")
 
 
+class StylePresetField(BaseModel):
+    """A style preset primitive field"""
+
+    style_preset_id: str = Field(description="The id of the style preset")
+
+
 class DenoiseMaskField(BaseModel):
     """An inpaint mask field"""
 
@@ -310,6 +329,17 @@ class CogView4ConditioningField(BaseModel):
     conditioning_name: str = Field(description="The name of conditioning tensor")
 
 
+class ZImageConditioningField(BaseModel):
+    """A Z-Image conditioning tensor primitive value"""
+
+    conditioning_name: str = Field(description="The name of conditioning tensor")
+    mask: Optional[TensorField] = Field(
+        default=None,
+        description="The mask associated with this conditioning tensor for regional prompting. "
+        "Excluded regions should be set to False, included regions should be set to True.",
+    )
+
+
 class ConditioningField(BaseModel):
     """A conditioning tensor primitive value"""
 
@@ -321,14 +351,9 @@ class ConditioningField(BaseModel):
     )
 
 
-class BoundingBoxField(BaseModel):
+class BoundingBoxField(BoundingBox):
     """A bounding box primitive value."""
 
-    x_min: int = Field(ge=0, description="The minimum x-coordinate of the bounding box (inclusive).")
-    x_max: int = Field(ge=0, description="The maximum x-coordinate of the bounding box (exclusive).")
-    y_min: int = Field(ge=0, description="The minimum y-coordinate of the bounding box (inclusive).")
-    y_max: int = Field(ge=0, description="The maximum y-coordinate of the bounding box (exclusive).")
-
     score: Optional[float] = Field(
         default=None,
         ge=0.0,
@@ -337,21 +362,6 @@ class BoundingBoxField(BaseModel):
         "when the bounding box was produced by a detector and has an associated confidence score.",
     )
 
-    @model_validator(mode="after")
-    def check_coords(self):
-        if self.x_min > self.x_max:
-            raise ValueError(f"x_min ({self.x_min}) is greater than x_max ({self.x_max}).")
-        if self.y_min > self.y_max:
-            raise ValueError(f"y_min ({self.y_min}) is greater than y_max ({self.y_max}).")
-        return self
-
-    def tuple(self) -> Tuple[int, int, int, int]:
-        """
-        Returns the bounding box as a tuple suitable for use with PIL's `Image.crop()` method.
-        This method returns a tuple of the form (left, upper, right, lower) == (x_min, y_min, x_max, y_max).
-        """
-        return (self.x_min, self.y_min, self.x_max, self.y_max)
-
 
 class MetadataField(RootModel[dict[str, Any]]):
     """
@@ -418,10 +428,15 @@ class InputFieldJSONSchemaExtra(BaseModel):
     ui_component: Optional[UIComponent] = None
     ui_order: Optional[int] = None
     ui_choice_labels: Optional[dict[str, str]] = None
+    ui_model_base: Optional[list[BaseModelType]] = None
+    ui_model_type: Optional[list[ModelType]] = None
+    ui_model_variant: Optional[list[ClipVariantType | ModelVariantType]] = None
+    ui_model_format: Optional[list[ModelFormat]] = None
 
     model_config = ConfigDict(
         validate_assignment=True,
         json_schema_serialization_defaults_required=True,
+        use_enum_values=True,
     )
 
 
@@ -474,16 +489,100 @@ class OutputFieldJSONSchemaExtra(BaseModel):
     """
 
     field_kind: FieldKind
-    ui_hidden: bool
-    ui_type: Optional[UIType]
-    ui_order: Optional[int]
+    ui_hidden: bool = False
+    ui_order: Optional[int] = None
+    ui_type: Optional[UIType] = None
 
     model_config = ConfigDict(
         validate_assignment=True,
         json_schema_serialization_defaults_required=True,
+        use_enum_values=True,
     )
 
 
+def migrate_model_ui_type(ui_type: UIType | str, json_schema_extra: dict[str, Any]) -> bool:
+    """Migrate deprecated model-specifier ui_type values to new-style ui_model_[base|type|variant|format] in json_schema_extra."""
+    if not isinstance(ui_type, UIType):
+        ui_type = UIType(ui_type)
+
+    ui_model_type: list[ModelType] | None = None
+    ui_model_base: list[BaseModelType] | None = None
+    ui_model_format: list[ModelFormat] | None = None
+    ui_model_variant: list[ClipVariantType | ModelVariantType] | None = None
+
+    match ui_type:
+        case UIType.MainModel:
+            ui_model_base = [BaseModelType.StableDiffusion1, BaseModelType.StableDiffusion2]
+            ui_model_type = [ModelType.Main]
+        case UIType.CogView4MainModel:
+            ui_model_base = [BaseModelType.CogView4]
+            ui_model_type = [ModelType.Main]
+        case UIType.FluxMainModel:
+            ui_model_base = [BaseModelType.Flux]
+            ui_model_type = [ModelType.Main]
+        case UIType.SD3MainModel:
+            ui_model_base = [BaseModelType.StableDiffusion3]
+            ui_model_type = [ModelType.Main]
+        case UIType.SDXLMainModel:
+            ui_model_base = [BaseModelType.StableDiffusionXL]
+            ui_model_type = [ModelType.Main]
+        case UIType.SDXLRefinerModel:
+            ui_model_base = [BaseModelType.StableDiffusionXLRefiner]
+            ui_model_type = [ModelType.Main]
+        case UIType.VAEModel:
+            ui_model_type = [ModelType.VAE]
+        case UIType.FluxVAEModel:
+            ui_model_base = [BaseModelType.Flux, BaseModelType.Flux2]
+            ui_model_type = [ModelType.VAE]
+        case UIType.LoRAModel:
+            ui_model_type = [ModelType.LoRA]
+        case UIType.ControlNetModel:
+            ui_model_type = [ModelType.ControlNet]
+        case UIType.IPAdapterModel:
+            ui_model_type = [ModelType.IPAdapter]
+        case UIType.T2IAdapterModel:
+            ui_model_type = [ModelType.T2IAdapter]
+        case UIType.T5EncoderModel:
+            ui_model_type = [ModelType.T5Encoder]
+        case UIType.CLIPEmbedModel:
+            ui_model_type = [ModelType.CLIPEmbed]
+        case UIType.CLIPLEmbedModel:
+            ui_model_type = [ModelType.CLIPEmbed]
+            ui_model_variant = [ClipVariantType.L]
+        case UIType.CLIPGEmbedModel:
+            ui_model_type = [ModelType.CLIPEmbed]
+            ui_model_variant = [ClipVariantType.G]
+        case UIType.SpandrelImageToImageModel:
+            ui_model_type = [ModelType.SpandrelImageToImage]
+        case UIType.ControlLoRAModel:
+            ui_model_type = [ModelType.ControlLoRa]
+        case UIType.SigLipModel:
+            ui_model_type = [ModelType.SigLIP]
+        case UIType.FluxReduxModel:
+            ui_model_type = [ModelType.FluxRedux]
+        case UIType.LlavaOnevisionModel:
+            ui_model_type = [ModelType.LlavaOnevision]
+        case _:
+            pass
+
+    did_migrate = False
+
+    if ui_model_type is not None:
+        json_schema_extra["ui_model_type"] = [m.value for m in ui_model_type]
+        did_migrate = True
+    if ui_model_base is not None:
+        json_schema_extra["ui_model_base"] = [m.value for m in ui_model_base]
+        did_migrate = True
+    if ui_model_format is not None:
+        json_schema_extra["ui_model_format"] = [m.value for m in ui_model_format]
+        did_migrate = True
+    if ui_model_variant is not None:
+        json_schema_extra["ui_model_variant"] = [m.value for m in ui_model_variant]
+        did_migrate = True
+
+    return did_migrate
+
+
 def InputField(
     # copied from pydantic's Field
     # TODO: Can we support default_factory?
@@ -510,35 +609,63 @@ def InputField(
     ui_hidden: Optional[bool] = None,
     ui_order: Optional[int] = None,
     ui_choice_labels: Optional[dict[str, str]] = None,
+    ui_model_base: Optional[BaseModelType | list[BaseModelType]] = None,
+    ui_model_type: Optional[ModelType | list[ModelType]] = None,
+    ui_model_variant: Optional[ClipVariantType | ModelVariantType | list[ClipVariantType | ModelVariantType]] = None,
+    ui_model_format: Optional[ModelFormat | list[ModelFormat]] = None,
 ) -> Any:
     """
     Creates an input field for an invocation.
 
-    This is a wrapper for Pydantic's [Field](https://docs.pydantic.dev/latest/api/fields/#pydantic.fields.Field) \
+    This is a wrapper for Pydantic's [Field](https://docs.pydantic.dev/latest/api/fields/#pydantic.fields.Field)
     that adds a few extra parameters to support graph execution and the node editor UI.
 
-    :param Input input: [Input.Any] The kind of input this field requires. \
-      `Input.Direct` means a value must be provided on instantiation. \
-      `Input.Connection` means the value must be provided by a connection. \
-      `Input.Any` means either will do.
+    If the field is a `ModelIdentifierField`, use the `ui_model_[base|type|variant|format]` args to filter the model list
+    in the Workflow Editor. Otherwise, use `ui_type` to provide extra type hints for the UI.
 
-    :param UIType ui_type: [None] Optionally provides an extra type hint for the UI. \
-      In some situations, the field's type is not enough to infer the correct UI type. \
-      For example, model selection fields should render a dropdown UI component to select a model. \
-      Internally, there is no difference between SD-1, SD-2 and SDXL model fields, they all use \
-      `MainModelField`. So to ensure the base-model-specific UI is rendered, you can use \
-      `UIType.SDXLMainModelField` to indicate that the field is an SDXL main model field.
+    Don't use both `ui_type` and `ui_model_[base|type|variant|format]` - if both are provided, a warning will be
+    logged and `ui_type` will be ignored.
 
-    :param UIComponent ui_component: [None] Optionally specifies a specific component to use in the UI. \
-      The UI will always render a suitable component, but sometimes you want something different than the default. \
-      For example, a `string` field will default to a single-line input, but you may want a multi-line textarea instead. \
-      For this case, you could provide `UIComponent.Textarea`.
+    Args:
+        input: The kind of input this field requires.
+        - `Input.Direct` means a value must be provided on instantiation.
+        - `Input.Connection` means the value must be provided by a connection.
+        - `Input.Any` means either will do.
 
-    :param bool ui_hidden: [False] Specifies whether or not this field should be hidden in the UI.
+        ui_type: Optionally provides an extra type hint for the UI. In some situations, the field's type is not enough
+        to infer the correct UI type. For example, Scheduler fields are enums, but we want to render a special scheduler
+        dropdown in the UI. Use `UIType.Scheduler` to indicate this.
 
-    :param int ui_order: [None] Specifies the order in which this field should be rendered in the UI.
+        ui_component: Optionally specifies a specific component to use in the UI. The UI will always render a suitable
+        component, but sometimes you want something different than the default. For example, a `string` field will
+        default to a single-line input, but you may want a multi-line textarea instead. In this case, you could use
+        `UIComponent.Textarea`.
 
-    :param dict[str, str] ui_choice_labels: [None] Specifies the labels to use for the choices in an enum field.
+        ui_hidden: Specifies whether or not this field should be hidden in the UI.
+
+        ui_order: Specifies the order in which this field should be rendered in the UI. If omitted, the field will be
+        rendered after all fields with an explicit order, in the order they are defined in the Invocation class.
+
+        ui_model_base: Specifies the base model architectures to filter the model list by in the Workflow Editor. For
+        example, `ui_model_base=BaseModelType.StableDiffusionXL` will show only SDXL architecture models. This arg is
+        only valid if this Input field is annotated as a `ModelIdentifierField`.
+
+        ui_model_type: Specifies the model type(s) to filter the model list by in the Workflow Editor. For example,
+        `ui_model_type=ModelType.VAE` will show only VAE models. This arg is only valid if this Input field is
+        annotated as a `ModelIdentifierField`.
+
+        ui_model_variant: Specifies the model variant(s) to filter the model list by in the Workflow Editor. For example,
+        `ui_model_variant=ModelVariantType.Inpainting` will show only inpainting models. This arg is only valid if this
+        Input field is annotated as a `ModelIdentifierField`.
+
+        ui_model_format: Specifies the model format(s) to filter the model list by in the Workflow Editor. For example,
+        `ui_model_format=ModelFormat.Diffusers` will show only models in the diffusers format. This arg is only valid
+        if this Input field is annotated as a `ModelIdentifierField`.
+
+        ui_choice_labels: Specifies the labels to use for the choices in an enum field. If omitted, the enum values
+        will be used. This arg is only valid if the field is annotated with as a `Literal`. For example,
+        `Literal["choice1", "choice2", "choice3"]` with `ui_choice_labels={"choice1": "Choice 1", "choice2": "Choice 2",
+        "choice3": "Choice 3"}` will render a dropdown with the labels "Choice 1", "Choice 2" and "Choice 3".
     """
 
     json_schema_extra_ = InputFieldJSONSchemaExtra(
@@ -546,8 +673,6 @@ def InputField(
         field_kind=FieldKind.Input,
     )
 
-    if ui_type is not None:
-        json_schema_extra_.ui_type = ui_type
     if ui_component is not None:
         json_schema_extra_.ui_component = ui_component
     if ui_hidden is not None:
@@ -556,6 +681,28 @@ def InputField(
         json_schema_extra_.ui_order = ui_order
     if ui_choice_labels is not None:
         json_schema_extra_.ui_choice_labels = ui_choice_labels
+    if ui_model_base is not None:
+        if isinstance(ui_model_base, list):
+            json_schema_extra_.ui_model_base = ui_model_base
+        else:
+            json_schema_extra_.ui_model_base = [ui_model_base]
+    if ui_model_type is not None:
+        if isinstance(ui_model_type, list):
+            json_schema_extra_.ui_model_type = ui_model_type
+        else:
+            json_schema_extra_.ui_model_type = [ui_model_type]
+    if ui_model_variant is not None:
+        if isinstance(ui_model_variant, list):
+            json_schema_extra_.ui_model_variant = ui_model_variant
+        else:
+            json_schema_extra_.ui_model_variant = [ui_model_variant]
+    if ui_model_format is not None:
+        if isinstance(ui_model_format, list):
+            json_schema_extra_.ui_model_format = ui_model_format
+        else:
+            json_schema_extra_.ui_model_format = [ui_model_format]
+    if ui_type is not None:
+        json_schema_extra_.ui_type = ui_type
 
     """
     There is a conflict between the typing of invocation definitions and the typing of an invocation's
@@ -657,20 +804,20 @@ def OutputField(
     """
     Creates an output field for an invocation output.
 
-    This is a wrapper for Pydantic's [Field](https://docs.pydantic.dev/1.10/usage/schema/#field-customization) \
+    This is a wrapper for Pydantic's [Field](https://docs.pydantic.dev/1.10/usage/schema/#field-customization)
     that adds a few extra parameters to support graph execution and the node editor UI.
 
-    :param UIType ui_type: [None] Optionally provides an extra type hint for the UI. \
-      In some situations, the field's type is not enough to infer the correct UI type. \
-      For example, model selection fields should render a dropdown UI component to select a model. \
-      Internally, there is no difference between SD-1, SD-2 and SDXL model fields, they all use \
-      `MainModelField`. So to ensure the base-model-specific UI is rendered, you can use \
-      `UIType.SDXLMainModelField` to indicate that the field is an SDXL main model field.
+    Args:
+        ui_type: Optionally provides an extra type hint for the UI. In some situations, the field's type is not enough
+        to infer the correct UI type. For example, Scheduler fields are enums, but we want to render a special scheduler
+        dropdown in the UI. Use `UIType.Scheduler` to indicate this.
 
-    :param bool ui_hidden: [False] Specifies whether or not this field should be hidden in the UI. \
+        ui_hidden: Specifies whether or not this field should be hidden in the UI.
 
-    :param int ui_order: [None] Specifies the order in which this field should be rendered in the UI. \
+        ui_order: Specifies the order in which this field should be rendered in the UI. If omitted, the field will be
+        rendered after all fields with an explicit order, in the order they are defined in the Invocation class.
     """
+
     return Field(
         default=default,
         title=title,
@@ -688,9 +835,9 @@ def OutputField(
         min_length=min_length,
         max_length=max_length,
         json_schema_extra=OutputFieldJSONSchemaExtra(
-            ui_type=ui_type,
             ui_hidden=ui_hidden,
             ui_order=ui_order,
+            ui_type=ui_type,
             field_kind=FieldKind.Output,
         ).model_dump(exclude_none=True),
     )

invokeai/app/invocations/flux2_denoise.py

@@ -0,0 +1,530 @@
+"""Flux2 Klein Denoise Invocation.
+
+Run denoising process with a FLUX.2 Klein transformer model.
+Uses Qwen3 conditioning instead of CLIP+T5.
+"""
+
+from contextlib import ExitStack
+from typing import Callable, Iterator, Optional, Tuple
+
+import torch
+import torchvision.transforms as tv_transforms
+from torchvision.transforms.functional import resize as tv_resize
+
+from invokeai.app.invocations.baseinvocation import BaseInvocation, Classification, invocation
+from invokeai.app.invocations.fields import (
+    DenoiseMaskField,
+    FieldDescriptions,
+    FluxConditioningField,
+    FluxKontextConditioningField,
+    Input,
+    InputField,
+    LatentsField,
+)
+from invokeai.app.invocations.model import TransformerField, VAEField
+from invokeai.app.invocations.primitives import LatentsOutput
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.flux.sampling_utils import clip_timestep_schedule_fractional
+from invokeai.backend.flux.schedulers import FLUX_SCHEDULER_LABELS, FLUX_SCHEDULER_MAP, FLUX_SCHEDULER_NAME_VALUES
+from invokeai.backend.flux2.denoise import denoise
+from invokeai.backend.flux2.ref_image_extension import Flux2RefImageExtension
+from invokeai.backend.flux2.sampling_utils import (
+    compute_empirical_mu,
+    generate_img_ids_flux2,
+    get_noise_flux2,
+    get_schedule_flux2,
+    pack_flux2,
+    unpack_flux2,
+)
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelFormat, ModelType
+from invokeai.backend.patches.layer_patcher import LayerPatcher
+from invokeai.backend.patches.lora_conversions.flux_bfl_peft_lora_conversion_utils import (
+    convert_bfl_lora_patch_to_diffusers,
+)
+from invokeai.backend.patches.lora_conversions.flux_lora_constants import FLUX_LORA_TRANSFORMER_PREFIX
+from invokeai.backend.patches.model_patch_raw import ModelPatchRaw
+from invokeai.backend.rectified_flow.rectified_flow_inpaint_extension import RectifiedFlowInpaintExtension
+from invokeai.backend.stable_diffusion.diffusers_pipeline import PipelineIntermediateState
+from invokeai.backend.stable_diffusion.diffusion.conditioning_data import FLUXConditioningInfo
+from invokeai.backend.util.devices import TorchDevice
+
+
+@invocation(
+    "flux2_denoise",
+    title="FLUX2 Denoise",
+    tags=["image", "flux", "flux2", "klein", "denoise"],
+    category="image",
+    version="1.4.0",
+    classification=Classification.Prototype,
+)
+class Flux2DenoiseInvocation(BaseInvocation):
+    """Run denoising process with a FLUX.2 Klein transformer model.
+
+    This node is designed for FLUX.2 Klein models which use Qwen3 as the text encoder.
+    It does not support ControlNet, IP-Adapters, or regional prompting.
+    """
+
+    latents: Optional[LatentsField] = InputField(
+        default=None,
+        description=FieldDescriptions.latents,
+        input=Input.Connection,
+    )
+    denoise_mask: Optional[DenoiseMaskField] = InputField(
+        default=None,
+        description=FieldDescriptions.denoise_mask,
+        input=Input.Connection,
+    )
+    denoising_start: float = InputField(
+        default=0.0,
+        ge=0,
+        le=1,
+        description=FieldDescriptions.denoising_start,
+    )
+    denoising_end: float = InputField(
+        default=1.0,
+        ge=0,
+        le=1,
+        description=FieldDescriptions.denoising_end,
+    )
+    add_noise: bool = InputField(default=True, description="Add noise based on denoising start.")
+    transformer: TransformerField = InputField(
+        description=FieldDescriptions.flux_model,
+        input=Input.Connection,
+        title="Transformer",
+    )
+    positive_text_conditioning: FluxConditioningField = InputField(
+        description=FieldDescriptions.positive_cond,
+        input=Input.Connection,
+    )
+    negative_text_conditioning: Optional[FluxConditioningField] = InputField(
+        default=None,
+        description="Negative conditioning tensor. Can be None if cfg_scale is 1.0.",
+        input=Input.Connection,
+    )
+    cfg_scale: float = InputField(
+        default=1.0,
+        description=FieldDescriptions.cfg_scale,
+        title="CFG Scale",
+    )
+    width: int = InputField(default=1024, multiple_of=16, description="Width of the generated image.")
+    height: int = InputField(default=1024, multiple_of=16, description="Height of the generated image.")
+    num_steps: int = InputField(
+        default=4,
+        description="Number of diffusion steps. Use 4 for distilled models, 28+ for base models.",
+    )
+    scheduler: FLUX_SCHEDULER_NAME_VALUES = InputField(
+        default="euler",
+        description="Scheduler (sampler) for the denoising process. 'euler' is fast and standard. "
+        "'heun' is 2nd-order (better quality, 2x slower). 'lcm' is optimized for few steps.",
+        ui_choice_labels=FLUX_SCHEDULER_LABELS,
+    )
+    seed: int = InputField(default=0, description="Randomness seed for reproducibility.")
+    vae: VAEField = InputField(
+        description="FLUX.2 VAE model (required for BN statistics).",
+        input=Input.Connection,
+    )
+    kontext_conditioning: FluxKontextConditioningField | list[FluxKontextConditioningField] | None = InputField(
+        default=None,
+        description="FLUX Kontext conditioning (reference images for multi-reference image editing).",
+        input=Input.Connection,
+        title="Reference Images",
+    )
+
+    def _get_bn_stats(self, context: InvocationContext) -> Optional[Tuple[torch.Tensor, torch.Tensor]]:
+        """Extract BN statistics from the FLUX.2 VAE.
+
+        The FLUX.2 VAE uses batch normalization on the patchified 128-channel representation.
+        IMPORTANT: BFL FLUX.2 VAE uses affine=False, so there are NO learnable weight/bias.
+
+        BN formula (affine=False): y = (x - mean) / std
+        Inverse: x = y * std + mean
+
+        Returns:
+            Tuple of (bn_mean, bn_std) tensors of shape (128,), or None if BN layer not found.
+        """
+        with context.models.load(self.vae.vae).model_on_device() as (_, vae):
+            # Ensure VAE is in eval mode to prevent BN stats from being updated
+            vae.eval()
+
+            # Try to find the BN layer - it may be at different locations depending on model format
+            bn_layer = None
+            if hasattr(vae, "bn"):
+                bn_layer = vae.bn
+            elif hasattr(vae, "batch_norm"):
+                bn_layer = vae.batch_norm
+            elif hasattr(vae, "encoder") and hasattr(vae.encoder, "bn"):
+                bn_layer = vae.encoder.bn
+
+            if bn_layer is None:
+                return None
+
+            # Verify running statistics are initialized
+            if bn_layer.running_mean is None or bn_layer.running_var is None:
+                return None
+
+            # Get BN running statistics from VAE
+            bn_mean = bn_layer.running_mean.clone()  # Shape: (128,)
+            bn_var = bn_layer.running_var.clone()  # Shape: (128,)
+            bn_eps = bn_layer.eps if hasattr(bn_layer, "eps") else 1e-4  # BFL uses 1e-4
+            bn_std = torch.sqrt(bn_var + bn_eps)
+
+        return bn_mean, bn_std
+
+    def _bn_normalize(
+        self,
+        x: torch.Tensor,
+        bn_mean: torch.Tensor,
+        bn_std: torch.Tensor,
+    ) -> torch.Tensor:
+        """Apply BN normalization to packed latents.
+
+        BN formula (affine=False): y = (x - mean) / std
+
+        Args:
+            x: Packed latents of shape (B, seq, 128).
+            bn_mean: BN running mean of shape (128,).
+            bn_std: BN running std of shape (128,).
+
+        Returns:
+            Normalized latents of same shape.
+        """
+        # x: (B, seq, 128), params: (128,) -> broadcast over batch and sequence dims
+        bn_mean = bn_mean.to(x.device, x.dtype)
+        bn_std = bn_std.to(x.device, x.dtype)
+        return (x - bn_mean) / bn_std
+
+    def _bn_denormalize(
+        self,
+        x: torch.Tensor,
+        bn_mean: torch.Tensor,
+        bn_std: torch.Tensor,
+    ) -> torch.Tensor:
+        """Apply BN denormalization to packed latents (inverse of normalization).
+
+        Inverse BN (affine=False): x = y * std + mean
+
+        Args:
+            x: Packed latents of shape (B, seq, 128).
+            bn_mean: BN running mean of shape (128,).
+            bn_std: BN running std of shape (128,).
+
+        Returns:
+            Denormalized latents of same shape.
+        """
+        # x: (B, seq, 128), params: (128,) -> broadcast over batch and sequence dims
+        bn_mean = bn_mean.to(x.device, x.dtype)
+        bn_std = bn_std.to(x.device, x.dtype)
+        return x * bn_std + bn_mean
+
+    @torch.no_grad()
+    def invoke(self, context: InvocationContext) -> LatentsOutput:
+        latents = self._run_diffusion(context)
+        latents = latents.detach().to("cpu")
+
+        name = context.tensors.save(tensor=latents)
+        return LatentsOutput.build(latents_name=name, latents=latents, seed=None)
+
+    def _run_diffusion(self, context: InvocationContext) -> torch.Tensor:
+        inference_dtype = torch.bfloat16
+        device = TorchDevice.choose_torch_device()
+
+        # Get BN statistics from VAE for latent denormalization (optional)
+        # BFL FLUX.2 VAE uses affine=False, so only mean/std are needed
+        # Some VAE formats (e.g. diffusers) may not expose BN stats directly
+        bn_stats = self._get_bn_stats(context)
+        bn_mean, bn_std = bn_stats if bn_stats is not None else (None, None)
+
+        # Load the input latents, if provided
+        init_latents = context.tensors.load(self.latents.latents_name) if self.latents else None
+        if init_latents is not None:
+            init_latents = init_latents.to(device=device, dtype=inference_dtype)
+
+        # Prepare input noise (FLUX.2 uses 32 channels)
+        noise = get_noise_flux2(
+            num_samples=1,
+            height=self.height,
+            width=self.width,
+            device=device,
+            dtype=inference_dtype,
+            seed=self.seed,
+        )
+        b, _c, latent_h, latent_w = noise.shape
+        packed_h = latent_h // 2
+        packed_w = latent_w // 2
+
+        # Load the conditioning data
+        pos_cond_data = context.conditioning.load(self.positive_text_conditioning.conditioning_name)
+        assert len(pos_cond_data.conditionings) == 1
+        pos_flux_conditioning = pos_cond_data.conditionings[0]
+        assert isinstance(pos_flux_conditioning, FLUXConditioningInfo)
+        pos_flux_conditioning = pos_flux_conditioning.to(dtype=inference_dtype, device=device)
+
+        # Qwen3 stacked embeddings (stored in t5_embeds field for compatibility)
+        txt = pos_flux_conditioning.t5_embeds
+
+        # Generate text position IDs (4D format for FLUX.2: T, H, W, L)
+        # FLUX.2 uses 4D position coordinates for its rotary position embeddings
+        # IMPORTANT: Position IDs must be int64 (long) dtype
+        # Diffusers uses: T=0, H=0, W=0, L=0..seq_len-1
+        seq_len = txt.shape[1]
+        txt_ids = torch.zeros(1, seq_len, 4, device=device, dtype=torch.long)
+        txt_ids[..., 3] = torch.arange(seq_len, device=device, dtype=torch.long)  # L coordinate varies
+
+        # Load negative conditioning if provided
+        neg_txt = None
+        neg_txt_ids = None
+        if self.negative_text_conditioning is not None:
+            neg_cond_data = context.conditioning.load(self.negative_text_conditioning.conditioning_name)
+            assert len(neg_cond_data.conditionings) == 1
+            neg_flux_conditioning = neg_cond_data.conditionings[0]
+            assert isinstance(neg_flux_conditioning, FLUXConditioningInfo)
+            neg_flux_conditioning = neg_flux_conditioning.to(dtype=inference_dtype, device=device)
+            neg_txt = neg_flux_conditioning.t5_embeds
+            # For text tokens: T=0, H=0, W=0, L=0..seq_len-1 (only L varies per token)
+            neg_seq_len = neg_txt.shape[1]
+            neg_txt_ids = torch.zeros(1, neg_seq_len, 4, device=device, dtype=torch.long)
+            neg_txt_ids[..., 3] = torch.arange(neg_seq_len, device=device, dtype=torch.long)
+
+        # Validate transformer config
+        transformer_config = context.models.get_config(self.transformer.transformer)
+        assert transformer_config.base == BaseModelType.Flux2 and transformer_config.type == ModelType.Main
+
+        # Calculate the timestep schedule using FLUX.2 specific schedule
+        # This matches diffusers' Flux2Pipeline implementation
+        # Note: Schedule shifting is handled by the scheduler via mu parameter
+        image_seq_len = packed_h * packed_w
+        timesteps = get_schedule_flux2(
+            num_steps=self.num_steps,
+            image_seq_len=image_seq_len,
+        )
+        # Compute mu for dynamic schedule shifting (used by FlowMatchEulerDiscreteScheduler)
+        mu = compute_empirical_mu(image_seq_len=image_seq_len, num_steps=self.num_steps)
+
+        # Clip the timesteps schedule based on denoising_start and denoising_end
+        timesteps = clip_timestep_schedule_fractional(timesteps, self.denoising_start, self.denoising_end)
+
+        # Prepare input latent image
+        if init_latents is not None:
+            if self.add_noise:
+                t_0 = timesteps[0]
+                x = t_0 * noise + (1.0 - t_0) * init_latents
+            else:
+                x = init_latents
+        else:
+            if self.denoising_start > 1e-5:
+                raise ValueError("denoising_start should be 0 when initial latents are not provided.")
+            x = noise
+
+        # If len(timesteps) == 1, then short-circuit
+        if len(timesteps) <= 1:
+            return x
+
+        # Generate image position IDs (FLUX.2 uses 4D coordinates)
+        # Position IDs use int64 dtype like diffusers
+        img_ids = generate_img_ids_flux2(h=latent_h, w=latent_w, batch_size=b, device=device)
+
+        # Prepare inpaint mask
+        inpaint_mask = self._prep_inpaint_mask(context, x)
+
+        # Pack all latent tensors
+        init_latents_packed = pack_flux2(init_latents) if init_latents is not None else None
+        inpaint_mask_packed = pack_flux2(inpaint_mask) if inpaint_mask is not None else None
+        noise_packed = pack_flux2(noise)
+        x = pack_flux2(x)
+
+        # BN normalization for img2img/inpainting:
+        # - The init_latents from VAE encode are NOT BN-normalized
+        # - The transformer operates in BN-normalized space
+        # - We must normalize x, init_latents, AND noise for InpaintExtension
+        # - Output MUST be denormalized after denoising before VAE decode
+        #
+        # This ensures that:
+        # 1. x starts in the correct normalized space for the transformer
+        # 2. When InpaintExtension merges intermediate_latents with noised_init_latents,
+        #    both are in the same scale/space (noise and init_latents must be in same space
+        #    for the linear interpolation: noised = noise * t + init * (1-t))
+        if bn_mean is not None and bn_std is not None:
+            if init_latents_packed is not None:
+                init_latents_packed = self._bn_normalize(init_latents_packed, bn_mean, bn_std)
+                # Also normalize noise for InpaintExtension - it's used to compute
+                # noised_init_latents = noise * t + init_latents * (1-t)
+                # Both operands must be in the same normalized space
+                noise_packed = self._bn_normalize(noise_packed, bn_mean, bn_std)
+            # For img2img/inpainting, x is computed from init_latents and must also be normalized
+            # For txt2img, x is pure noise (already N(0,1)) - normalizing it would be incorrect
+            # We detect img2img by checking if init_latents was provided
+            if init_latents is not None:
+                x = self._bn_normalize(x, bn_mean, bn_std)
+
+        # Verify packed dimensions
+        assert packed_h * packed_w == x.shape[1]
+
+        # Prepare inpaint extension
+        inpaint_extension: Optional[RectifiedFlowInpaintExtension] = None
+        if inpaint_mask_packed is not None:
+            assert init_latents_packed is not None
+            inpaint_extension = RectifiedFlowInpaintExtension(
+                init_latents=init_latents_packed,
+                inpaint_mask=inpaint_mask_packed,
+                noise=noise_packed,
+            )
+
+        # Prepare CFG scale list
+        num_steps = len(timesteps) - 1
+        cfg_scale_list = [self.cfg_scale] * num_steps
+
+        # Check if we're doing inpainting (have a mask or a clipped schedule)
+        is_inpainting = self.denoise_mask is not None or self.denoising_start > 1e-5
+
+        # Create scheduler with FLUX.2 Klein configuration
+        # For inpainting/img2img, use manual Euler stepping to preserve the exact timestep schedule
+        # For txt2img, use the scheduler with dynamic shifting for optimal results
+        scheduler = None
+        if self.scheduler in FLUX_SCHEDULER_MAP and not is_inpainting:
+            # Only use scheduler for txt2img - use manual Euler for inpainting to preserve exact timesteps
+            scheduler_class = FLUX_SCHEDULER_MAP[self.scheduler]
+            # FlowMatchHeunDiscreteScheduler only supports num_train_timesteps and shift parameters
+            # FlowMatchEulerDiscreteScheduler and FlowMatchLCMScheduler support dynamic shifting
+            if self.scheduler == "heun":
+                scheduler = scheduler_class(
+                    num_train_timesteps=1000,
+                    shift=3.0,
+                )
+            else:
+                scheduler = scheduler_class(
+                    num_train_timesteps=1000,
+                    shift=3.0,
+                    use_dynamic_shifting=True,
+                    base_shift=0.5,
+                    max_shift=1.15,
+                    base_image_seq_len=256,
+                    max_image_seq_len=4096,
+                    time_shift_type="exponential",
+                )
+
+        # Prepare reference image extension for FLUX.2 Klein built-in editing
+        ref_image_extension = None
+        if self.kontext_conditioning:
+            ref_image_extension = Flux2RefImageExtension(
+                context=context,
+                ref_image_conditioning=self.kontext_conditioning
+                if isinstance(self.kontext_conditioning, list)
+                else [self.kontext_conditioning],
+                vae_field=self.vae,
+                device=device,
+                dtype=inference_dtype,
+                bn_mean=bn_mean,
+                bn_std=bn_std,
+            )
+
+        with ExitStack() as exit_stack:
+            # Load the transformer model
+            (cached_weights, transformer) = exit_stack.enter_context(
+                context.models.load(self.transformer.transformer).model_on_device()
+            )
+            config = transformer_config
+
+            # Determine if the model is quantized
+            if config.format in [ModelFormat.Diffusers]:
+                model_is_quantized = False
+            elif config.format in [
+                ModelFormat.BnbQuantizedLlmInt8b,
+                ModelFormat.BnbQuantizednf4b,
+                ModelFormat.GGUFQuantized,
+            ]:
+                model_is_quantized = True
+            else:
+                model_is_quantized = False
+
+            # Apply LoRA models to the transformer
+            exit_stack.enter_context(
+                LayerPatcher.apply_smart_model_patches(
+                    model=transformer,
+                    patches=self._lora_iterator(context),
+                    prefix=FLUX_LORA_TRANSFORMER_PREFIX,
+                    dtype=inference_dtype,
+                    cached_weights=cached_weights,
+                    force_sidecar_patching=model_is_quantized,
+                )
+            )
+
+            # Prepare reference image conditioning if provided
+            img_cond_seq = None
+            img_cond_seq_ids = None
+            if ref_image_extension is not None:
+                # Ensure batch sizes match
+                ref_image_extension.ensure_batch_size(x.shape[0])
+                img_cond_seq, img_cond_seq_ids = (
+                    ref_image_extension.ref_image_latents,
+                    ref_image_extension.ref_image_ids,
+                )
+
+            x = denoise(
+                model=transformer,
+                img=x,
+                img_ids=img_ids,
+                txt=txt,
+                txt_ids=txt_ids,
+                timesteps=timesteps,
+                step_callback=self._build_step_callback(context),
+                cfg_scale=cfg_scale_list,
+                neg_txt=neg_txt,
+                neg_txt_ids=neg_txt_ids,
+                scheduler=scheduler,
+                mu=mu,
+                inpaint_extension=inpaint_extension,
+                img_cond_seq=img_cond_seq,
+                img_cond_seq_ids=img_cond_seq_ids,
+            )
+
+        # Apply BN denormalization if BN stats are available
+        # The diffusers Flux2KleinPipeline applies: latents = latents * bn_std + bn_mean
+        # This transforms latents from normalized space to VAE's expected input space
+        if bn_mean is not None and bn_std is not None:
+            x = self._bn_denormalize(x, bn_mean, bn_std)
+
+        x = unpack_flux2(x.float(), self.height, self.width)
+        return x
+
+    def _prep_inpaint_mask(self, context: InvocationContext, latents: torch.Tensor) -> Optional[torch.Tensor]:
+        """Prepare the inpaint mask."""
+        if self.denoise_mask is None:
+            return None
+
+        mask = context.tensors.load(self.denoise_mask.mask_name)
+        mask = 1.0 - mask
+
+        _, _, latent_height, latent_width = latents.shape
+        mask = tv_resize(
+            img=mask,
+            size=[latent_height, latent_width],
+            interpolation=tv_transforms.InterpolationMode.BILINEAR,
+            antialias=False,
+        )
+
+        mask = mask.to(device=latents.device, dtype=latents.dtype)
+        return mask.expand_as(latents)
+
+    def _lora_iterator(self, context: InvocationContext) -> Iterator[Tuple[ModelPatchRaw, float]]:
+        """Iterate over LoRA models to apply.
+
+        Converts BFL-format LoRA keys to diffusers format if needed, since FLUX.2 Klein
+        uses Flux2Transformer2DModel (diffusers naming) but LoRAs may have been loaded
+        with BFL naming (e.g. when a Klein 4B LoRA is misidentified as FLUX.1).
+        """
+        for lora in self.transformer.loras:
+            lora_info = context.models.load(lora.lora)
+            assert isinstance(lora_info.model, ModelPatchRaw)
+            converted = convert_bfl_lora_patch_to_diffusers(lora_info.model)
+            yield (converted, lora.weight)
+            del lora_info
+
+    def _build_step_callback(self, context: InvocationContext) -> Callable[[PipelineIntermediateState], None]:
+        """Build a callback for step progress updates."""
+
+        def step_callback(state: PipelineIntermediateState) -> None:
+            latents = state.latents.float()
+            state.latents = unpack_flux2(latents, self.height, self.width).squeeze()
+            context.util.flux2_step_callback(state)
+
+        return step_callback

invokeai/app/invocations/flux2_klein_lora_loader.py

@@ -0,0 +1,182 @@
+"""FLUX.2 Klein LoRA Loader Invocation.
+
+Applies LoRA models to a FLUX.2 Klein transformer and/or Qwen3 text encoder.
+Unlike standard FLUX which uses CLIP+T5, Klein uses only Qwen3 for text encoding.
+"""
+
+from typing import Optional
+
+from invokeai.app.invocations.baseinvocation import (
+    BaseInvocation,
+    BaseInvocationOutput,
+    Classification,
+    invocation,
+    invocation_output,
+)
+from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField
+from invokeai.app.invocations.model import LoRAField, ModelIdentifierField, Qwen3EncoderField, TransformerField
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
+
+
+@invocation_output("flux2_klein_lora_loader_output")
+class Flux2KleinLoRALoaderOutput(BaseInvocationOutput):
+    """FLUX.2 Klein LoRA Loader Output"""
+
+    transformer: Optional[TransformerField] = OutputField(
+        default=None, description=FieldDescriptions.transformer, title="Transformer"
+    )
+    qwen3_encoder: Optional[Qwen3EncoderField] = OutputField(
+        default=None, description=FieldDescriptions.qwen3_encoder, title="Qwen3 Encoder"
+    )
+
+
+@invocation(
+    "flux2_klein_lora_loader",
+    title="Apply LoRA - Flux2 Klein",
+    tags=["lora", "model", "flux", "klein", "flux2"],
+    category="model",
+    version="1.0.0",
+    classification=Classification.Prototype,
+)
+class Flux2KleinLoRALoaderInvocation(BaseInvocation):
+    """Apply a LoRA model to a FLUX.2 Klein transformer and/or Qwen3 text encoder."""
+
+    lora: ModelIdentifierField = InputField(
+        description=FieldDescriptions.lora_model,
+        title="LoRA",
+        ui_model_base=BaseModelType.Flux2,
+        ui_model_type=ModelType.LoRA,
+    )
+    weight: float = InputField(default=0.75, description=FieldDescriptions.lora_weight)
+    transformer: TransformerField | None = InputField(
+        default=None,
+        description=FieldDescriptions.transformer,
+        input=Input.Connection,
+        title="Transformer",
+    )
+    qwen3_encoder: Qwen3EncoderField | None = InputField(
+        default=None,
+        title="Qwen3 Encoder",
+        description=FieldDescriptions.qwen3_encoder,
+        input=Input.Connection,
+    )
+
+    def invoke(self, context: InvocationContext) -> Flux2KleinLoRALoaderOutput:
+        lora_key = self.lora.key
+
+        if not context.models.exists(lora_key):
+            raise ValueError(f"Unknown lora: {lora_key}!")
+
+        # Warn if LoRA variant doesn't match transformer variant
+        lora_config = context.models.get_config(lora_key)
+        lora_variant = getattr(lora_config, "variant", None)
+        if lora_variant and self.transformer is not None:
+            transformer_config = context.models.get_config(self.transformer.transformer.key)
+            transformer_variant = getattr(transformer_config, "variant", None)
+            if transformer_variant and lora_variant != transformer_variant:
+                context.logger.warning(
+                    f"LoRA variant mismatch: LoRA '{lora_config.name}' is for {lora_variant.value} "
+                    f"but transformer is {transformer_variant.value}. This may cause shape errors."
+                )
+
+        # Check for existing LoRAs with the same key.
+        if self.transformer and any(lora.lora.key == lora_key for lora in self.transformer.loras):
+            raise ValueError(f'LoRA "{lora_key}" already applied to transformer.')
+        if self.qwen3_encoder and any(lora.lora.key == lora_key for lora in self.qwen3_encoder.loras):
+            raise ValueError(f'LoRA "{lora_key}" already applied to Qwen3 encoder.')
+
+        output = Flux2KleinLoRALoaderOutput()
+
+        # Attach LoRA layers to the models.
+        if self.transformer is not None:
+            output.transformer = self.transformer.model_copy(deep=True)
+            output.transformer.loras.append(
+                LoRAField(
+                    lora=self.lora,
+                    weight=self.weight,
+                )
+            )
+        if self.qwen3_encoder is not None:
+            output.qwen3_encoder = self.qwen3_encoder.model_copy(deep=True)
+            output.qwen3_encoder.loras.append(
+                LoRAField(
+                    lora=self.lora,
+                    weight=self.weight,
+                )
+            )
+
+        return output
+
+
+@invocation(
+    "flux2_klein_lora_collection_loader",
+    title="Apply LoRA Collection - Flux2 Klein",
+    tags=["lora", "model", "flux", "klein", "flux2"],
+    category="model",
+    version="1.0.0",
+    classification=Classification.Prototype,
+)
+class Flux2KleinLoRACollectionLoader(BaseInvocation):
+    """Applies a collection of LoRAs to a FLUX.2 Klein transformer and/or Qwen3 text encoder."""
+
+    loras: Optional[LoRAField | list[LoRAField]] = InputField(
+        default=None, description="LoRA models and weights. May be a single LoRA or collection.", title="LoRAs"
+    )
+
+    transformer: Optional[TransformerField] = InputField(
+        default=None,
+        description=FieldDescriptions.transformer,
+        input=Input.Connection,
+        title="Transformer",
+    )
+    qwen3_encoder: Qwen3EncoderField | None = InputField(
+        default=None,
+        title="Qwen3 Encoder",
+        description=FieldDescriptions.qwen3_encoder,
+        input=Input.Connection,
+    )
+
+    def invoke(self, context: InvocationContext) -> Flux2KleinLoRALoaderOutput:
+        output = Flux2KleinLoRALoaderOutput()
+        loras = self.loras if isinstance(self.loras, list) else [self.loras]
+        added_loras: list[str] = []
+
+        if self.transformer is not None:
+            output.transformer = self.transformer.model_copy(deep=True)
+
+        if self.qwen3_encoder is not None:
+            output.qwen3_encoder = self.qwen3_encoder.model_copy(deep=True)
+
+        for lora in loras:
+            if lora is None:
+                continue
+            if lora.lora.key in added_loras:
+                continue
+
+            if not context.models.exists(lora.lora.key):
+                raise Exception(f"Unknown lora: {lora.lora.key}!")
+
+            assert lora.lora.base in (BaseModelType.Flux, BaseModelType.Flux2)
+
+            # Warn if LoRA variant doesn't match transformer variant
+            lora_config = context.models.get_config(lora.lora.key)
+            lora_variant = getattr(lora_config, "variant", None)
+            if lora_variant and self.transformer is not None:
+                transformer_config = context.models.get_config(self.transformer.transformer.key)
+                transformer_variant = getattr(transformer_config, "variant", None)
+                if transformer_variant and lora_variant != transformer_variant:
+                    context.logger.warning(
+                        f"LoRA variant mismatch: LoRA '{lora_config.name}' is for {lora_variant.value} "
+                        f"but transformer is {transformer_variant.value}. This may cause shape errors."
+                    )
+
+            added_loras.append(lora.lora.key)
+
+            if self.transformer is not None and output.transformer is not None:
+                output.transformer.loras.append(lora)
+
+            if self.qwen3_encoder is not None and output.qwen3_encoder is not None:
+                output.qwen3_encoder.loras.append(lora)
+
+        return output

invokeai/app/invocations/flux2_klein_model_loader.py

@@ -0,0 +1,222 @@
+"""Flux2 Klein Model Loader Invocation.
+
+Loads a Flux2 Klein model with its Qwen3 text encoder and VAE.
+Unlike standard FLUX which uses CLIP+T5, Klein uses only Qwen3.
+"""
+
+from typing import Literal, Optional
+
+from invokeai.app.invocations.baseinvocation import (
+    BaseInvocation,
+    BaseInvocationOutput,
+    Classification,
+    invocation,
+    invocation_output,
+)
+from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField
+from invokeai.app.invocations.model import (
+    ModelIdentifierField,
+    Qwen3EncoderField,
+    TransformerField,
+    VAEField,
+)
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.taxonomy import (
+    BaseModelType,
+    Flux2VariantType,
+    ModelFormat,
+    ModelType,
+    Qwen3VariantType,
+    SubModelType,
+)
+
+
+@invocation_output("flux2_klein_model_loader_output")
+class Flux2KleinModelLoaderOutput(BaseInvocationOutput):
+    """Flux2 Klein model loader output."""
+
+    transformer: TransformerField = OutputField(description=FieldDescriptions.transformer, title="Transformer")
+    qwen3_encoder: Qwen3EncoderField = OutputField(description=FieldDescriptions.qwen3_encoder, title="Qwen3 Encoder")
+    vae: VAEField = OutputField(description=FieldDescriptions.vae, title="VAE")
+    max_seq_len: Literal[256, 512] = OutputField(
+        description="The max sequence length for the Qwen3 encoder.",
+        title="Max Seq Length",
+    )
+
+
+@invocation(
+    "flux2_klein_model_loader",
+    title="Main Model - Flux2 Klein",
+    tags=["model", "flux", "klein", "qwen3"],
+    category="model",
+    version="1.0.0",
+    classification=Classification.Prototype,
+)
+class Flux2KleinModelLoaderInvocation(BaseInvocation):
+    """Loads a Flux2 Klein model, outputting its submodels.
+
+    Flux2 Klein uses Qwen3 as the text encoder instead of CLIP+T5.
+    It uses a 32-channel VAE (AutoencoderKLFlux2) instead of the 16-channel FLUX.1 VAE.
+
+    When using a Diffusers format model, both VAE and Qwen3 encoder are extracted
+    automatically from the main model. You can override with standalone models:
+    - Transformer: Always from Flux2 Klein main model
+    - VAE: From main model (Diffusers) or standalone VAE
+    - Qwen3 Encoder: From main model (Diffusers) or standalone Qwen3 model
+    """
+
+    model: ModelIdentifierField = InputField(
+        description=FieldDescriptions.flux_model,
+        input=Input.Direct,
+        ui_model_base=BaseModelType.Flux2,
+        ui_model_type=ModelType.Main,
+        title="Transformer",
+    )
+
+    vae_model: Optional[ModelIdentifierField] = InputField(
+        default=None,
+        description="Standalone VAE model. Flux2 Klein uses the same VAE as FLUX (16-channel). "
+        "If not provided, VAE will be loaded from the Qwen3 Source model.",
+        input=Input.Direct,
+        ui_model_base=[BaseModelType.Flux, BaseModelType.Flux2],
+        ui_model_type=ModelType.VAE,
+        title="VAE",
+    )
+
+    qwen3_encoder_model: Optional[ModelIdentifierField] = InputField(
+        default=None,
+        description="Standalone Qwen3 Encoder model. "
+        "If not provided, encoder will be loaded from the Qwen3 Source model.",
+        input=Input.Direct,
+        ui_model_type=ModelType.Qwen3Encoder,
+        title="Qwen3 Encoder",
+    )
+
+    qwen3_source_model: Optional[ModelIdentifierField] = InputField(
+        default=None,
+        description="Diffusers Flux2 Klein model to extract VAE and/or Qwen3 encoder from. "
+        "Use this if you don't have separate VAE/Qwen3 models. "
+        "Ignored if both VAE and Qwen3 Encoder are provided separately.",
+        input=Input.Direct,
+        ui_model_base=BaseModelType.Flux2,
+        ui_model_type=ModelType.Main,
+        ui_model_format=ModelFormat.Diffusers,
+        title="Qwen3 Source (Diffusers)",
+    )
+
+    max_seq_len: Literal[256, 512] = InputField(
+        default=512,
+        description="Max sequence length for the Qwen3 encoder.",
+        title="Max Seq Length",
+    )
+
+    def invoke(self, context: InvocationContext) -> Flux2KleinModelLoaderOutput:
+        # Transformer always comes from the main model
+        transformer = self.model.model_copy(update={"submodel_type": SubModelType.Transformer})
+
+        # Check if main model is Diffusers format (can extract VAE directly)
+        main_config = context.models.get_config(self.model)
+        main_is_diffusers = main_config.format == ModelFormat.Diffusers
+
+        # Determine VAE source
+        # IMPORTANT: FLUX.2 Klein uses a 32-channel VAE (AutoencoderKLFlux2), not the 16-channel FLUX.1 VAE.
+        # The VAE should come from the FLUX.2 Klein Diffusers model, not a separate FLUX VAE.
+        if self.vae_model is not None:
+            # Use standalone VAE (user explicitly selected one)
+            vae = self.vae_model.model_copy(update={"submodel_type": SubModelType.VAE})
+        elif main_is_diffusers:
+            # Extract VAE from main model (recommended for FLUX.2)
+            vae = self.model.model_copy(update={"submodel_type": SubModelType.VAE})
+        elif self.qwen3_source_model is not None:
+            # Extract from Qwen3 source Diffusers model
+            self._validate_diffusers_format(context, self.qwen3_source_model, "Qwen3 Source")
+            vae = self.qwen3_source_model.model_copy(update={"submodel_type": SubModelType.VAE})
+        else:
+            raise ValueError(
+                "No VAE source provided. Standalone safetensors/GGUF models require a separate VAE. "
+                "Options:\n"
+                "  1. Set 'VAE' to a standalone FLUX VAE model\n"
+                "  2. Set 'Qwen3 Source' to a Diffusers Flux2 Klein model to extract the VAE from"
+            )
+
+        # Determine Qwen3 Encoder source
+        if self.qwen3_encoder_model is not None:
+            # Use standalone Qwen3 Encoder - validate it matches the FLUX.2 Klein variant
+            self._validate_qwen3_encoder_variant(context, main_config)
+            qwen3_tokenizer = self.qwen3_encoder_model.model_copy(update={"submodel_type": SubModelType.Tokenizer})
+            qwen3_encoder = self.qwen3_encoder_model.model_copy(update={"submodel_type": SubModelType.TextEncoder})
+        elif main_is_diffusers:
+            # Extract from main model (recommended for FLUX.2 Klein)
+            qwen3_tokenizer = self.model.model_copy(update={"submodel_type": SubModelType.Tokenizer})
+            qwen3_encoder = self.model.model_copy(update={"submodel_type": SubModelType.TextEncoder})
+        elif self.qwen3_source_model is not None:
+            # Extract from separate Diffusers model
+            self._validate_diffusers_format(context, self.qwen3_source_model, "Qwen3 Source")
+            qwen3_tokenizer = self.qwen3_source_model.model_copy(update={"submodel_type": SubModelType.Tokenizer})
+            qwen3_encoder = self.qwen3_source_model.model_copy(update={"submodel_type": SubModelType.TextEncoder})
+        else:
+            raise ValueError(
+                "No Qwen3 Encoder source provided. Standalone safetensors/GGUF models require a separate text encoder. "
+                "Options:\n"
+                "  1. Set 'Qwen3 Encoder' to a standalone Qwen3 text encoder model "
+                "(Klein 4B needs Qwen3 4B, Klein 9B needs Qwen3 8B)\n"
+                "  2. Set 'Qwen3 Source' to a Diffusers Flux2 Klein model to extract the encoder from"
+            )
+
+        return Flux2KleinModelLoaderOutput(
+            transformer=TransformerField(transformer=transformer, loras=[]),
+            qwen3_encoder=Qwen3EncoderField(tokenizer=qwen3_tokenizer, text_encoder=qwen3_encoder),
+            vae=VAEField(vae=vae),
+            max_seq_len=self.max_seq_len,
+        )
+
+    def _validate_diffusers_format(
+        self, context: InvocationContext, model: ModelIdentifierField, model_name: str
+    ) -> None:
+        """Validate that a model is in Diffusers format."""
+        config = context.models.get_config(model)
+        if config.format != ModelFormat.Diffusers:
+            raise ValueError(
+                f"The {model_name} model must be a Diffusers format model. "
+                f"The selected model '{config.name}' is in {config.format.value} format."
+            )
+
+    def _validate_qwen3_encoder_variant(self, context: InvocationContext, main_config) -> None:
+        """Validate that the standalone Qwen3 encoder variant matches the FLUX.2 Klein variant.
+
+        - FLUX.2 Klein 4B requires Qwen3 4B encoder
+        - FLUX.2 Klein 9B requires Qwen3 8B encoder
+        """
+        if self.qwen3_encoder_model is None:
+            return
+
+        # Get the Qwen3 encoder config
+        qwen3_config = context.models.get_config(self.qwen3_encoder_model)
+
+        # Check if the config has a variant field
+        if not hasattr(qwen3_config, "variant"):
+            # Can't validate, skip
+            return
+
+        qwen3_variant = qwen3_config.variant
+
+        # Get the FLUX.2 Klein variant from the main model config
+        if not hasattr(main_config, "variant"):
+            return
+
+        flux2_variant = main_config.variant
+
+        # Validate the variants match
+        # Klein4B requires Qwen3_4B, Klein9B/Klein9BBase requires Qwen3_8B
+        expected_qwen3_variant = None
+        if flux2_variant == Flux2VariantType.Klein4B:
+            expected_qwen3_variant = Qwen3VariantType.Qwen3_4B
+        elif flux2_variant in (Flux2VariantType.Klein9B, Flux2VariantType.Klein9BBase):
+            expected_qwen3_variant = Qwen3VariantType.Qwen3_8B
+
+        if expected_qwen3_variant is not None and qwen3_variant != expected_qwen3_variant:
+            raise ValueError(
+                f"Qwen3 encoder variant mismatch: FLUX.2 Klein {flux2_variant.value} requires "
+                f"{expected_qwen3_variant.value} encoder, but {qwen3_variant.value} was selected. "
+                f"Please select a matching Qwen3 encoder or use a Diffusers format model which includes the correct encoder."
+            )

invokeai/app/invocations/flux2_klein_text_encoder.py

@@ -0,0 +1,200 @@
+"""Flux2 Klein Text Encoder Invocation.
+
+Flux2 Klein uses Qwen3 as the text encoder instead of CLIP+T5.
+The key difference is that it extracts hidden states from layers (9, 18, 27)
+and stacks them together for richer text representations.
+
+This implementation matches the diffusers Flux2KleinPipeline exactly.
+"""
+
+from contextlib import ExitStack
+from typing import Iterator, Literal, Optional, Tuple
+
+import torch
+from transformers import PreTrainedModel, PreTrainedTokenizerBase
+
+from invokeai.app.invocations.baseinvocation import BaseInvocation, Classification, invocation
+from invokeai.app.invocations.fields import (
+    FieldDescriptions,
+    FluxConditioningField,
+    Input,
+    InputField,
+    TensorField,
+    UIComponent,
+)
+from invokeai.app.invocations.model import Qwen3EncoderField
+from invokeai.app.invocations.primitives import FluxConditioningOutput
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.load.model_cache.utils import get_effective_device
+from invokeai.backend.patches.layer_patcher import LayerPatcher
+from invokeai.backend.patches.lora_conversions.flux_lora_constants import FLUX_LORA_T5_PREFIX
+from invokeai.backend.patches.model_patch_raw import ModelPatchRaw
+from invokeai.backend.stable_diffusion.diffusion.conditioning_data import ConditioningFieldData, FLUXConditioningInfo
+from invokeai.backend.util.devices import TorchDevice
+
+# FLUX.2 Klein extracts hidden states from these specific layers
+# Matching diffusers Flux2KleinPipeline: (9, 18, 27)
+# hidden_states[0] is embedding layer, so layer N is at index N
+KLEIN_EXTRACTION_LAYERS = (9, 18, 27)
+
+# Default max sequence length for Klein models
+KLEIN_MAX_SEQ_LEN = 512
+
+
+@invocation(
+    "flux2_klein_text_encoder",
+    title="Prompt - Flux2 Klein",
+    tags=["prompt", "conditioning", "flux", "klein", "qwen3"],
+    category="conditioning",
+    version="1.1.1",
+    classification=Classification.Prototype,
+)
+class Flux2KleinTextEncoderInvocation(BaseInvocation):
+    """Encodes and preps a prompt for Flux2 Klein image generation.
+
+    Flux2 Klein uses Qwen3 as the text encoder, extracting hidden states from
+    layers (9, 18, 27) and stacking them for richer text representations.
+    This matches the diffusers Flux2KleinPipeline implementation exactly.
+    """
+
+    prompt: str = InputField(description="Text prompt to encode.", ui_component=UIComponent.Textarea)
+    qwen3_encoder: Qwen3EncoderField = InputField(
+        title="Qwen3 Encoder",
+        description=FieldDescriptions.qwen3_encoder,
+        input=Input.Connection,
+    )
+    max_seq_len: Literal[256, 512] = InputField(
+        default=512,
+        description="Max sequence length for the Qwen3 encoder.",
+    )
+    mask: Optional[TensorField] = InputField(
+        default=None,
+        description="A mask defining the region that this conditioning prompt applies to.",
+    )
+
+    @torch.no_grad()
+    def invoke(self, context: InvocationContext) -> FluxConditioningOutput:
+        # Open the exitstack here to lock models for the duration of the node
+        with ExitStack() as exit_stack:
+            # Pass the locked stack down to the helper function
+            qwen3_embeds, pooled_embeds = self._encode_prompt(context, exit_stack)
+
+            conditioning_data = ConditioningFieldData(
+                conditionings=[FLUXConditioningInfo(clip_embeds=pooled_embeds, t5_embeds=qwen3_embeds)]
+            )
+
+            # The models are still locked while we save the data
+            conditioning_name = context.conditioning.save(conditioning_data)
+            return FluxConditioningOutput(
+                conditioning=FluxConditioningField(conditioning_name=conditioning_name, mask=self.mask)
+            )
+
+    def _encode_prompt(self, context: InvocationContext, exit_stack: ExitStack) -> Tuple[torch.Tensor, torch.Tensor]:
+        prompt = self.prompt
+
+        # Reordered loading to prevent the annoying cache drop issue
+        # This prevents it from being evicted while we look up the tokenizer
+        text_encoder_info = context.models.load(self.qwen3_encoder.text_encoder)
+        (cached_weights, text_encoder) = exit_stack.enter_context(text_encoder_info.model_on_device())
+
+        # Now it is safe to load and lock the tokenizer
+        tokenizer_info = context.models.load(self.qwen3_encoder.tokenizer)
+        (_, tokenizer) = exit_stack.enter_context(tokenizer_info.model_on_device())
+
+        repaired_tensors = text_encoder_info.repair_required_tensors_on_device()
+        device = get_effective_device(text_encoder)
+        if repaired_tensors > 0:
+            context.logger.warning(
+                f"Recovered {repaired_tensors} required Qwen3 tensor(s) onto {device} after a partial device mismatch."
+            )
+
+        # Apply LoRA models
+        lora_dtype = TorchDevice.choose_bfloat16_safe_dtype(device)
+        exit_stack.enter_context(
+            LayerPatcher.apply_smart_model_patches(
+                model=text_encoder,
+                patches=self._lora_iterator(context),
+                prefix=FLUX_LORA_T5_PREFIX,
+                dtype=lora_dtype,
+                cached_weights=cached_weights,
+            )
+        )
+
+        context.util.signal_progress("Running Qwen3 text encoder (Klein)")
+
+        if not isinstance(text_encoder, PreTrainedModel):
+            raise TypeError(
+                f"Expected PreTrainedModel for text encoder, got {type(text_encoder).__name__}. "
+                "The Qwen3 encoder model may be corrupted or incompatible."
+            )
+        if not isinstance(tokenizer, PreTrainedTokenizerBase):
+            raise TypeError(
+                f"Expected PreTrainedTokenizerBase for tokenizer, got {type(tokenizer).__name__}. "
+                "The Qwen3 tokenizer may be corrupted or incompatible."
+            )
+
+        messages = [{"role": "user", "content": prompt}]
+
+        text: str = tokenizer.apply_chat_template(  # type: ignore[assignment]
+            messages,
+            tokenize=False,
+            add_generation_prompt=True,
+            enable_thinking=False,
+        )
+
+        inputs = tokenizer(
+            text,
+            return_tensors="pt",
+            padding="max_length",
+            truncation=True,
+            max_length=self.max_seq_len,
+        )
+
+        input_ids = inputs["input_ids"].to(device)
+        attention_mask = inputs["attention_mask"].to(device)
+
+        # Forward pass through the model
+        outputs = text_encoder(
+            input_ids=input_ids,
+            attention_mask=attention_mask,
+            output_hidden_states=True,
+            use_cache=False,
+        )
+        if not hasattr(outputs, "hidden_states") or outputs.hidden_states is None:
+            raise RuntimeError(
+                "Text encoder did not return hidden_states. "
+                "Ensure output_hidden_states=True is supported by this model."
+            )
+        num_hidden_layers = len(outputs.hidden_states)
+
+        hidden_states_list = []
+        for layer_idx in KLEIN_EXTRACTION_LAYERS:
+            if layer_idx >= num_hidden_layers:
+                layer_idx = num_hidden_layers - 1
+            hidden_states_list.append(outputs.hidden_states[layer_idx])
+
+        out = torch.stack(hidden_states_list, dim=1)
+        out = out.to(dtype=text_encoder.dtype, device=device)
+
+        batch_size, num_channels, seq_len, hidden_dim = out.shape
+        prompt_embeds = out.permute(0, 2, 1, 3).reshape(batch_size, seq_len, num_channels * hidden_dim)
+
+        last_hidden_state = outputs.hidden_states[-1]
+        expanded_mask = attention_mask.unsqueeze(-1).expand_as(last_hidden_state).float()
+        sum_embeds = (last_hidden_state * expanded_mask).sum(dim=1)
+        num_tokens = expanded_mask.sum(dim=1).clamp(min=1)
+        pooled_embeds = sum_embeds / num_tokens
+
+        return prompt_embeds, pooled_embeds
+
+    def _lora_iterator(self, context: InvocationContext) -> Iterator[Tuple[ModelPatchRaw, float]]:
+        """Iterate over LoRA models to apply to the Qwen3 text encoder."""
+        for lora in self.qwen3_encoder.loras:
+            lora_info = context.models.load(lora.lora)
+            if not isinstance(lora_info.model, ModelPatchRaw):
+                raise TypeError(
+                    f"Expected ModelPatchRaw for LoRA '{lora.lora.key}', got {type(lora_info.model).__name__}. "
+                    "The LoRA model may be corrupted or incompatible."
+                )
+            yield (lora_info.model, lora.weight)
+            del lora_info

invokeai/app/invocations/flux2_vae_decode.py

@@ -0,0 +1,92 @@
+"""Flux2 Klein VAE Decode Invocation.
+
+Decodes latents to images using the FLUX.2 32-channel VAE (AutoencoderKLFlux2).
+"""
+
+import torch
+from einops import rearrange
+from PIL import Image
+
+from invokeai.app.invocations.baseinvocation import BaseInvocation, Classification, invocation
+from invokeai.app.invocations.fields import (
+    FieldDescriptions,
+    Input,
+    InputField,
+    LatentsField,
+    WithBoard,
+    WithMetadata,
+)
+from invokeai.app.invocations.model import VAEField
+from invokeai.app.invocations.primitives import ImageOutput
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.load.load_base import LoadedModel
+from invokeai.backend.util.devices import TorchDevice
+
+
+@invocation(
+    "flux2_vae_decode",
+    title="Latents to Image - FLUX2",
+    tags=["latents", "image", "vae", "l2i", "flux2", "klein"],
+    category="latents",
+    version="1.0.0",
+    classification=Classification.Prototype,
+)
+class Flux2VaeDecodeInvocation(BaseInvocation, WithMetadata, WithBoard):
+    """Generates an image from latents using FLUX.2 Klein's 32-channel VAE."""
+
+    latents: LatentsField = InputField(
+        description=FieldDescriptions.latents,
+        input=Input.Connection,
+    )
+    vae: VAEField = InputField(
+        description=FieldDescriptions.vae,
+        input=Input.Connection,
+    )
+
+    def _vae_decode(self, vae_info: LoadedModel, latents: torch.Tensor) -> Image.Image:
+        """Decode latents to image using FLUX.2 VAE.
+
+        Input latents should already be in the correct space after BN denormalization
+        was applied in the denoiser. The VAE expects (B, 32, H, W) format.
+        """
+        with vae_info.model_on_device() as (_, vae):
+            vae_dtype = next(iter(vae.parameters())).dtype
+            device = TorchDevice.choose_torch_device()
+            latents = latents.to(device=device, dtype=vae_dtype)
+
+            # Decode using diffusers API
+            decoded = vae.decode(latents, return_dict=False)[0]
+
+        # Convert from [-1, 1] to [0, 1] then to [0, 255] PIL image
+        img = (decoded / 2 + 0.5).clamp(0, 1)
+        img = rearrange(img[0], "c h w -> h w c")
+        img_np = (img * 255).byte().cpu().numpy()
+        # Explicitly create RGB image (not grayscale)
+        img_pil = Image.fromarray(img_np, mode="RGB")
+        return img_pil
+
+    @torch.no_grad()
+    def invoke(self, context: InvocationContext) -> ImageOutput:
+        latents = context.tensors.load(self.latents.latents_name)
+
+        # Log latent statistics for debugging black image issues
+        context.logger.debug(
+            f"FLUX.2 VAE decode input: shape={latents.shape}, "
+            f"min={latents.min().item():.4f}, max={latents.max().item():.4f}, "
+            f"mean={latents.mean().item():.4f}"
+        )
+
+        # Warn if input latents are all zeros or very small (would cause black images)
+        if latents.abs().max() < 1e-6:
+            context.logger.warning(
+                "FLUX.2 VAE decode received near-zero latents! This will cause black images. "
+                "The latent cache may be corrupted - try clearing the cache."
+            )
+
+        vae_info = context.models.load(self.vae.vae)
+        context.util.signal_progress("Running VAE")
+        image = self._vae_decode(vae_info=vae_info, latents=latents)
+
+        TorchDevice.empty_cache()
+        image_dto = context.images.save(image=image)
+        return ImageOutput.build(image_dto)

invokeai/app/invocations/flux2_vae_encode.py

@@ -0,0 +1,88 @@
+"""Flux2 Klein VAE Encode Invocation.
+
+Encodes images to latents using the FLUX.2 32-channel VAE (AutoencoderKLFlux2).
+"""
+
+import einops
+import torch
+
+from invokeai.app.invocations.baseinvocation import BaseInvocation, Classification, invocation
+from invokeai.app.invocations.fields import (
+    FieldDescriptions,
+    ImageField,
+    Input,
+    InputField,
+)
+from invokeai.app.invocations.model import VAEField
+from invokeai.app.invocations.primitives import LatentsOutput
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.load.load_base import LoadedModel
+from invokeai.backend.stable_diffusion.diffusers_pipeline import image_resized_to_grid_as_tensor
+from invokeai.backend.util.devices import TorchDevice
+
+
+@invocation(
+    "flux2_vae_encode",
+    title="Image to Latents - FLUX2",
+    tags=["latents", "image", "vae", "i2l", "flux2", "klein"],
+    category="latents",
+    version="1.0.0",
+    classification=Classification.Prototype,
+)
+class Flux2VaeEncodeInvocation(BaseInvocation):
+    """Encodes an image into latents using FLUX.2 Klein's 32-channel VAE."""
+
+    image: ImageField = InputField(
+        description="The image to encode.",
+    )
+    vae: VAEField = InputField(
+        description=FieldDescriptions.vae,
+        input=Input.Connection,
+    )
+
+    def _vae_encode(self, vae_info: LoadedModel, image_tensor: torch.Tensor) -> torch.Tensor:
+        """Encode image to latents using FLUX.2 VAE.
+
+        The VAE encodes to 32-channel latent space.
+        Output latents shape: (B, 32, H/8, W/8).
+        """
+        with vae_info.model_on_device() as (_, vae):
+            vae_dtype = next(iter(vae.parameters())).dtype
+            device = TorchDevice.choose_torch_device()
+            image_tensor = image_tensor.to(device=device, dtype=vae_dtype)
+
+            # Encode using diffusers API
+            # The VAE.encode() returns a DiagonalGaussianDistribution-like object
+            latent_dist = vae.encode(image_tensor, return_dict=False)[0]
+
+            # Sample from the distribution (or use mode for deterministic output)
+            # Using mode() for deterministic encoding
+            if hasattr(latent_dist, "mode"):
+                latents = latent_dist.mode()
+            elif hasattr(latent_dist, "sample"):
+                # Fall back to sampling if mode is not available
+                generator = torch.Generator(device=device).manual_seed(0)
+                latents = latent_dist.sample(generator=generator)
+            else:
+                # Direct tensor output (some VAE implementations)
+                latents = latent_dist
+
+        return latents
+
+    @torch.no_grad()
+    def invoke(self, context: InvocationContext) -> LatentsOutput:
+        image = context.images.get_pil(self.image.image_name)
+
+        vae_info = context.models.load(self.vae.vae)
+
+        # Convert image to tensor (HWC -> CHW, normalize to [-1, 1])
+        image_tensor = image_resized_to_grid_as_tensor(image.convert("RGB"))
+        if image_tensor.dim() == 3:
+            image_tensor = einops.rearrange(image_tensor, "c h w -> 1 c h w")
+
+        context.util.signal_progress("Running VAE Encode")
+        latents = self._vae_encode(vae_info=vae_info, image_tensor=image_tensor)
+
+        latents = latents.to("cpu")
+        name = context.tensors.save(tensor=latents)
+        return LatentsOutput.build(latents_name=name, latents=latents, seed=None)

invokeai/app/invocations/flux_control_lora_loader.py

@@ -4,9 +4,10 @@ from invokeai.app.invocations.baseinvocation import (
     invocation,
     invocation_output,
 )
-from invokeai.app.invocations.fields import FieldDescriptions, ImageField, InputField, OutputField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, ImageField, InputField, OutputField
 from invokeai.app.invocations.model import ControlLoRAField, ModelIdentifierField
 from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
 
 
 @invocation_output("flux_control_lora_loader_output")
@@ -29,7 +30,10 @@ class FluxControlLoRALoaderInvocation(BaseInvocation):
     """LoRA model and Image to use with FLUX transformer generation."""
 
     lora: ModelIdentifierField = InputField(
-        description=FieldDescriptions.control_lora_model, title="Control LoRA", ui_type=UIType.ControlLoRAModel
+        description=FieldDescriptions.control_lora_model,
+        title="Control LoRA",
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.ControlLoRa,
     )
     image: ImageField = InputField(description="The image to encode.")
     weight: float = InputField(description="The weight of the LoRA.", default=1.0)

invokeai/app/invocations/flux_controlnet.py

@@ -6,11 +6,12 @@ from invokeai.app.invocations.baseinvocation import (
     invocation,
     invocation_output,
 )
-from invokeai.app.invocations.fields import FieldDescriptions, ImageField, InputField, OutputField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, ImageField, InputField, OutputField
 from invokeai.app.invocations.model import ModelIdentifierField
 from invokeai.app.invocations.util import validate_begin_end_step, validate_weights
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.app.util.controlnet_utils import CONTROLNET_RESIZE_VALUES
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
 
 
 class FluxControlNetField(BaseModel):
@@ -57,7 +58,9 @@ class FluxControlNetInvocation(BaseInvocation):
 
     image: ImageField = InputField(description="The control image")
     control_model: ModelIdentifierField = InputField(
-        description=FieldDescriptions.controlnet_model, ui_type=UIType.ControlNetModel
+        description=FieldDescriptions.controlnet_model,
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.ControlNet,
     )
     control_weight: float | list[float] = InputField(
         default=1.0, ge=-1, le=2, description="The weight given to the ControlNet"

invokeai/app/invocations/flux_denoise.py

@@ -32,6 +32,13 @@ from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.flux.controlnet.instantx_controlnet_flux import InstantXControlNetFlux
 from invokeai.backend.flux.controlnet.xlabs_controlnet_flux import XLabsControlNetFlux
 from invokeai.backend.flux.denoise import denoise
+from invokeai.backend.flux.dype.presets import (
+    DYPE_PRESET_LABELS,
+    DYPE_PRESET_OFF,
+    DyPEPreset,
+    get_dype_config_from_preset,
+)
+from invokeai.backend.flux.extensions.dype_extension import DyPEExtension
 from invokeai.backend.flux.extensions.instantx_controlnet_extension import InstantXControlNetExtension
 from invokeai.backend.flux.extensions.kontext_extension import KontextExtension
 from invokeai.backend.flux.extensions.regional_prompting_extension import RegionalPromptingExtension
@@ -47,8 +54,9 @@ from invokeai.backend.flux.sampling_utils import (
     pack,
     unpack,
 )
+from invokeai.backend.flux.schedulers import FLUX_SCHEDULER_LABELS, FLUX_SCHEDULER_MAP, FLUX_SCHEDULER_NAME_VALUES
 from invokeai.backend.flux.text_conditioning import FluxReduxConditioning, FluxTextConditioning
-from invokeai.backend.model_manager.taxonomy import ModelFormat, ModelVariantType
+from invokeai.backend.model_manager.taxonomy import BaseModelType, FluxVariantType, ModelFormat, ModelType
 from invokeai.backend.patches.layer_patcher import LayerPatcher
 from invokeai.backend.patches.lora_conversions.flux_lora_constants import FLUX_LORA_TRANSFORMER_PREFIX
 from invokeai.backend.patches.model_patch_raw import ModelPatchRaw
@@ -63,7 +71,7 @@ from invokeai.backend.util.devices import TorchDevice
     title="FLUX Denoise",
     tags=["image", "flux"],
     category="image",
-    version="4.0.0",
+    version="4.5.1",
 )
 class FluxDenoiseInvocation(BaseInvocation):
     """Run denoising process with a FLUX transformer model."""
@@ -132,6 +140,12 @@ class FluxDenoiseInvocation(BaseInvocation):
     num_steps: int = InputField(
         default=4, description="Number of diffusion steps. Recommended values are schnell: 4, dev: 50."
     )
+    scheduler: FLUX_SCHEDULER_NAME_VALUES = InputField(
+        default="euler",
+        description="Scheduler (sampler) for the denoising process. 'euler' is fast and standard. "
+        "'heun' is 2nd-order (better quality, 2x slower). 'lcm' is optimized for few steps.",
+        ui_choice_labels=FLUX_SCHEDULER_LABELS,
+    )
     guidance: float = InputField(
         default=4.0,
         description="The guidance strength. Higher values adhere more strictly to the prompt, and will produce less diverse images. FLUX dev only, ignored for schnell.",
@@ -153,12 +167,37 @@ class FluxDenoiseInvocation(BaseInvocation):
         description=FieldDescriptions.ip_adapter, title="IP-Adapter", default=None, input=Input.Connection
     )
 
-    kontext_conditioning: Optional[FluxKontextConditioningField] = InputField(
+    kontext_conditioning: FluxKontextConditioningField | list[FluxKontextConditioningField] | None = InputField(
         default=None,
         description="FLUX Kontext conditioning (reference image).",
         input=Input.Connection,
     )
 
+    # DyPE (Dynamic Position Extrapolation) for high-resolution generation
+    dype_preset: DyPEPreset = InputField(
+        default=DYPE_PRESET_OFF,
+        description=(
+            "DyPE preset for high-resolution generation. 'auto' enables automatically for resolutions > 1536px. "
+            "'area' enables automatically based on image area. '4k' uses optimized settings for 4K output."
+        ),
+        ui_order=100,
+        ui_choice_labels=DYPE_PRESET_LABELS,
+    )
+    dype_scale: Optional[float] = InputField(
+        default=None,
+        ge=0.0,
+        le=8.0,
+        description="DyPE magnitude (λs). Higher values = stronger extrapolation. Only used when dype_preset is not 'off'.",
+        ui_order=101,
+    )
+    dype_exponent: Optional[float] = InputField(
+        default=None,
+        ge=0.0,
+        le=1000.0,
+        description="DyPE decay speed (λt). Controls transition from low to high frequency detail. Only used when dype_preset is not 'off'.",
+        ui_order=102,
+    )
+
     @torch.no_grad()
     def invoke(self, context: InvocationContext) -> LatentsOutput:
         latents = self._run_diffusion(context)
@@ -232,7 +271,14 @@ class FluxDenoiseInvocation(BaseInvocation):
         )
 
         transformer_config = context.models.get_config(self.transformer.transformer)
-        is_schnell = "schnell" in getattr(transformer_config, "config_path", "")
+        assert (
+            transformer_config.base in (BaseModelType.Flux, BaseModelType.Flux2)
+            and transformer_config.type is ModelType.Main
+        )
+        # Schnell is only for FLUX.1, FLUX.2 Klein behaves like Dev (with guidance)
+        is_schnell = (
+            transformer_config.base is BaseModelType.Flux and transformer_config.variant is FluxVariantType.Schnell
+        )
 
         # Calculate the timestep schedule.
         timesteps = get_schedule(
@@ -241,6 +287,12 @@ class FluxDenoiseInvocation(BaseInvocation):
             shift=not is_schnell,
         )
 
+        # Create scheduler if not using default euler
+        scheduler = None
+        if self.scheduler in FLUX_SCHEDULER_MAP:
+            scheduler_class = FLUX_SCHEDULER_MAP[self.scheduler]
+            scheduler = scheduler_class(num_train_timesteps=1000)
+
         # Clip the timesteps schedule based on denoising_start and denoising_end.
         timesteps = clip_timestep_schedule_fractional(timesteps, self.denoising_start, self.denoising_end)
 
@@ -277,7 +329,7 @@ class FluxDenoiseInvocation(BaseInvocation):
 
         # Prepare the extra image conditioning tensor (img_cond) for either FLUX structural control or FLUX Fill.
         img_cond: torch.Tensor | None = None
-        is_flux_fill = transformer_config.variant == ModelVariantType.Inpaint  # type: ignore
+        is_flux_fill = transformer_config.variant is FluxVariantType.DevFill
         if is_flux_fill:
             img_cond = self._prep_flux_fill_img_cond(
                 context, device=TorchDevice.choose_torch_device(), dtype=inference_dtype
@@ -328,6 +380,21 @@ class FluxDenoiseInvocation(BaseInvocation):
             cfg_scale_end_step=self.cfg_scale_end_step,
         )
 
+        kontext_extension = None
+        if self.kontext_conditioning:
+            if not self.controlnet_vae:
+                raise ValueError("A VAE (e.g., controlnet_vae) must be provided to use Kontext conditioning.")
+
+            kontext_extension = KontextExtension(
+                context=context,
+                kontext_conditioning=self.kontext_conditioning
+                if isinstance(self.kontext_conditioning, list)
+                else [self.kontext_conditioning],
+                vae_field=self.controlnet_vae,
+                device=TorchDevice.choose_torch_device(),
+                dtype=inference_dtype,
+            )
+
         with ExitStack() as exit_stack:
             # Prepare ControlNet extensions.
             # Note: We do this before loading the transformer model to minimize peak memory (see implementation).
@@ -385,19 +452,6 @@ class FluxDenoiseInvocation(BaseInvocation):
                 dtype=inference_dtype,
             )
 
-            kontext_extension = None
-            if self.kontext_conditioning is not None:
-                if not self.controlnet_vae:
-                    raise ValueError("A VAE (e.g., controlnet_vae) must be provided to use Kontext conditioning.")
-
-                kontext_extension = KontextExtension(
-                    context=context,
-                    kontext_conditioning=self.kontext_conditioning,
-                    vae_field=self.controlnet_vae,
-                    device=TorchDevice.choose_torch_device(),
-                    dtype=inference_dtype,
-                )
-
             # Prepare Kontext conditioning if provided
             img_cond_seq = None
             img_cond_seq_ids = None
@@ -406,6 +460,30 @@ class FluxDenoiseInvocation(BaseInvocation):
                 kontext_extension.ensure_batch_size(x.shape[0])
                 img_cond_seq, img_cond_seq_ids = kontext_extension.kontext_latents, kontext_extension.kontext_ids
 
+            # Prepare DyPE extension for high-resolution generation
+            dype_extension: DyPEExtension | None = None
+            dype_config = get_dype_config_from_preset(
+                preset=self.dype_preset,
+                width=self.width,
+                height=self.height,
+                custom_scale=self.dype_scale,
+                custom_exponent=self.dype_exponent,
+            )
+            if dype_config is not None:
+                dype_extension = DyPEExtension(
+                    config=dype_config,
+                    target_height=self.height,
+                    target_width=self.width,
+                )
+                context.logger.info(
+                    f"DyPE enabled: resolution={self.width}x{self.height}, preset={self.dype_preset}, "
+                    f"method={dype_config.method}, scale={dype_config.dype_scale:.2f}, "
+                    f"exponent={dype_config.dype_exponent:.2f}, start_sigma={dype_config.dype_start_sigma:.2f}, "
+                    f"base_resolution={dype_config.base_resolution}"
+                )
+            else:
+                context.logger.debug(f"DyPE disabled: resolution={self.width}x{self.height}, preset={self.dype_preset}")
+
             x = denoise(
                 model=transformer,
                 img=x,
@@ -423,6 +501,8 @@ class FluxDenoiseInvocation(BaseInvocation):
                 img_cond=img_cond,
                 img_cond_seq=img_cond_seq,
                 img_cond_seq_ids=img_cond_seq_ids,
+                dype_extension=dype_extension,
+                scheduler=scheduler,
             )
 
         x = unpack(x.float(), self.height, self.width)

invokeai/app/invocations/flux_ip_adapter.py

@@ -5,7 +5,7 @@ from pydantic import field_validator, model_validator
 from typing_extensions import Self
 
 from invokeai.app.invocations.baseinvocation import BaseInvocation, invocation
-from invokeai.app.invocations.fields import InputField, UIType
+from invokeai.app.invocations.fields import InputField
 from invokeai.app.invocations.ip_adapter import (
     CLIP_VISION_MODEL_MAP,
     IPAdapterField,
@@ -16,10 +16,8 @@ from invokeai.app.invocations.model import ModelIdentifierField
 from invokeai.app.invocations.primitives import ImageField
 from invokeai.app.invocations.util import validate_begin_end_step, validate_weights
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager.config import (
-    IPAdapterCheckpointConfig,
-    IPAdapterInvokeAIConfig,
-)
+from invokeai.backend.model_manager.configs.ip_adapter import IPAdapter_Checkpoint_FLUX_Config
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
 
 
 @invocation(
@@ -36,7 +34,10 @@ class FluxIPAdapterInvocation(BaseInvocation):
 
     image: ImageField = InputField(description="The IP-Adapter image prompt(s).")
     ip_adapter_model: ModelIdentifierField = InputField(
-        description="The IP-Adapter model.", title="IP-Adapter Model", ui_type=UIType.IPAdapterModel
+        description="The IP-Adapter model.",
+        title="IP-Adapter Model",
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.IPAdapter,
     )
     # Currently, the only known ViT model used by FLUX IP-Adapters is ViT-L.
     clip_vision_model: Literal["ViT-L"] = InputField(description="CLIP Vision model to use.", default="ViT-L")
@@ -64,7 +65,7 @@ class FluxIPAdapterInvocation(BaseInvocation):
     def invoke(self, context: InvocationContext) -> IPAdapterOutput:
         # Lookup the CLIP Vision encoder that is intended to be used with the IP-Adapter model.
         ip_adapter_info = context.models.get_config(self.ip_adapter_model.key)
-        assert isinstance(ip_adapter_info, (IPAdapterInvokeAIConfig, IPAdapterCheckpointConfig))
+        assert isinstance(ip_adapter_info, IPAdapter_Checkpoint_FLUX_Config)
 
         # Note: There is a IPAdapterInvokeAIConfig.image_encoder_model_id field, but it isn't trustworthy.
         image_encoder_starter_model = CLIP_VISION_MODEL_MAP[self.clip_vision_model]

invokeai/app/invocations/flux_lora_loader.py

@@ -6,10 +6,10 @@ from invokeai.app.invocations.baseinvocation import (
     invocation,
     invocation_output,
 )
-from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField
 from invokeai.app.invocations.model import CLIPField, LoRAField, ModelIdentifierField, T5EncoderField, TransformerField
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager.taxonomy import BaseModelType
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
 
 
 @invocation_output("flux_lora_loader_output")
@@ -36,7 +36,10 @@ class FluxLoRALoaderInvocation(BaseInvocation):
     """Apply a LoRA model to a FLUX transformer and/or text encoder."""
 
     lora: ModelIdentifierField = InputField(
-        description=FieldDescriptions.lora_model, title="LoRA", ui_type=UIType.LoRAModel
+        description=FieldDescriptions.lora_model,
+        title="LoRA",
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.LoRA,
     )
     weight: float = InputField(default=0.75, description=FieldDescriptions.lora_weight)
     transformer: TransformerField | None = InputField(
@@ -159,7 +162,7 @@ class FLUXLoRACollectionLoader(BaseInvocation):
             if not context.models.exists(lora.lora.key):
                 raise Exception(f"Unknown lora: {lora.lora.key}!")
 
-            assert lora.lora.base is BaseModelType.Flux
+            assert lora.lora.base in (BaseModelType.Flux, BaseModelType.Flux2)
 
             added_loras.append(lora.lora.key)
 

invokeai/app/invocations/flux_model_loader.py

@@ -6,18 +6,16 @@ from invokeai.app.invocations.baseinvocation import (
     invocation,
     invocation_output,
 )
-from invokeai.app.invocations.fields import FieldDescriptions, Input, InputField, OutputField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, InputField, OutputField
 from invokeai.app.invocations.model import CLIPField, ModelIdentifierField, T5EncoderField, TransformerField, VAEField
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.app.util.t5_model_identifier import (
     preprocess_t5_encoder_model_identifier,
     preprocess_t5_tokenizer_model_identifier,
 )
-from invokeai.backend.flux.util import max_seq_lengths
-from invokeai.backend.model_manager.config import (
-    CheckpointConfigBase,
-)
-from invokeai.backend.model_manager.taxonomy import SubModelType
+from invokeai.backend.flux.util import get_flux_max_seq_length
+from invokeai.backend.model_manager.configs.base import Checkpoint_Config_Base
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType, SubModelType
 
 
 @invocation_output("flux_model_loader_output")
@@ -39,30 +37,34 @@ class FluxModelLoaderOutput(BaseInvocationOutput):
     title="Main Model - FLUX",
     tags=["model", "flux"],
     category="model",
-    version="1.0.6",
+    version="1.0.7",
 )
 class FluxModelLoaderInvocation(BaseInvocation):
     """Loads a flux base model, outputting its submodels."""
 
     model: ModelIdentifierField = InputField(
         description=FieldDescriptions.flux_model,
-        ui_type=UIType.FluxMainModel,
-        input=Input.Direct,
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.Main,
     )
 
     t5_encoder_model: ModelIdentifierField = InputField(
-        description=FieldDescriptions.t5_encoder, ui_type=UIType.T5EncoderModel, input=Input.Direct, title="T5 Encoder"
+        description=FieldDescriptions.t5_encoder,
+        title="T5 Encoder",
+        ui_model_type=ModelType.T5Encoder,
     )
 
     clip_embed_model: ModelIdentifierField = InputField(
         description=FieldDescriptions.clip_embed_model,
-        ui_type=UIType.CLIPEmbedModel,
-        input=Input.Direct,
         title="CLIP Embed",
+        ui_model_type=ModelType.CLIPEmbed,
     )
 
     vae_model: ModelIdentifierField = InputField(
-        description=FieldDescriptions.vae_model, ui_type=UIType.FluxVAEModel, title="VAE"
+        description=FieldDescriptions.vae_model,
+        title="VAE",
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.VAE,
     )
 
     def invoke(self, context: InvocationContext) -> FluxModelLoaderOutput:
@@ -80,12 +82,12 @@ class FluxModelLoaderInvocation(BaseInvocation):
         t5_encoder = preprocess_t5_encoder_model_identifier(self.t5_encoder_model)
 
         transformer_config = context.models.get_config(transformer)
-        assert isinstance(transformer_config, CheckpointConfigBase)
+        assert isinstance(transformer_config, Checkpoint_Config_Base)
 
         return FluxModelLoaderOutput(
             transformer=TransformerField(transformer=transformer, loras=[]),
             clip=CLIPField(tokenizer=tokenizer, text_encoder=clip_encoder, loras=[], skipped_layers=0),
             t5_encoder=T5EncoderField(tokenizer=tokenizer2, text_encoder=t5_encoder, loras=[]),
             vae=VAEField(vae=vae),
-            max_seq_len=max_seq_lengths[transformer_config.config_path],
+            max_seq_len=get_flux_max_seq_length(transformer_config.variant),
         )

invokeai/app/invocations/flux_redux.py

@@ -18,16 +18,15 @@ from invokeai.app.invocations.fields import (
     InputField,
     OutputField,
     TensorField,
-    UIType,
 )
 from invokeai.app.invocations.model import ModelIdentifierField
 from invokeai.app.invocations.primitives import ImageField
 from invokeai.app.services.model_records.model_records_base import ModelRecordChanges
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.flux.redux.flux_redux_model import FluxReduxModel
-from invokeai.backend.model_manager import BaseModelType, ModelType
-from invokeai.backend.model_manager.config import AnyModelConfig
+from invokeai.backend.model_manager.configs.factory import AnyModelConfig
 from invokeai.backend.model_manager.starter_models import siglip
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType
 from invokeai.backend.sig_lip.sig_lip_pipeline import SigLipPipeline
 from invokeai.backend.util.devices import TorchDevice
 
@@ -64,7 +63,8 @@ class FluxReduxInvocation(BaseInvocation):
     redux_model: ModelIdentifierField = InputField(
         description="The FLUX Redux model to use.",
         title="FLUX Redux Model",
-        ui_type=UIType.FluxReduxModel,
+        ui_model_base=BaseModelType.Flux,
+        ui_model_type=ModelType.FluxRedux,
     )
     downsampling_factor: int = InputField(
         ge=1,

invokeai/app/invocations/flux_text_encoder.py

@@ -17,7 +17,7 @@ from invokeai.app.invocations.model import CLIPField, T5EncoderField
 from invokeai.app.invocations.primitives import FluxConditioningOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.flux.modules.conditioner import HFEncoder
-from invokeai.backend.model_manager import ModelFormat
+from invokeai.backend.model_manager.taxonomy import ModelFormat
 from invokeai.backend.patches.layer_patcher import LayerPatcher
 from invokeai.backend.patches.lora_conversions.flux_lora_constants import FLUX_LORA_CLIP_PREFIX, FLUX_LORA_T5_PREFIX
 from invokeai.backend.patches.model_patch_raw import ModelPatchRaw
@@ -58,6 +58,12 @@ class FluxTextEncoderInvocation(BaseInvocation):
         # scoped. This ensures that the T5 model can be freed and gc'd before loading the CLIP model (if necessary).
         t5_embeddings = self._t5_encode(context)
         clip_embeddings = self._clip_encode(context)
+
+        # Move embeddings to CPU for storage to save VRAM
+        # They will be moved to the appropriate device when used by the denoiser
+        t5_embeddings = t5_embeddings.detach().to("cpu")
+        clip_embeddings = clip_embeddings.detach().to("cpu")
+
         conditioning_data = ConditioningFieldData(
             conditionings=[FLUXConditioningInfo(clip_embeds=clip_embeddings, t5_embeds=t5_embeddings)]
         )

invokeai/app/invocations/flux_vae_decode.py

@@ -3,7 +3,6 @@ from einops import rearrange
 from PIL import Image
 
 from invokeai.app.invocations.baseinvocation import BaseInvocation, invocation
-from invokeai.app.invocations.constants import LATENT_SCALE_FACTOR
 from invokeai.app.invocations.fields import (
     FieldDescriptions,
     Input,
@@ -18,6 +17,7 @@ from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.flux.modules.autoencoder import AutoEncoder
 from invokeai.backend.model_manager.load.load_base import LoadedModel
 from invokeai.backend.util.devices import TorchDevice
+from invokeai.backend.util.vae_working_memory import estimate_vae_working_memory_flux
 
 
 @invocation(
@@ -39,17 +39,11 @@ class FluxVaeDecodeInvocation(BaseInvocation, WithMetadata, WithBoard):
         input=Input.Connection,
     )
 
-    def _estimate_working_memory(self, latents: torch.Tensor, vae: AutoEncoder) -> int:
-        """Estimate the working memory required by the invocation in bytes."""
-        out_h = LATENT_SCALE_FACTOR * latents.shape[-2]
-        out_w = LATENT_SCALE_FACTOR * latents.shape[-1]
-        element_size = next(vae.parameters()).element_size()
-        scaling_constant = 2200  # Determined experimentally.
-        working_memory = out_h * out_w * element_size * scaling_constant
-        return int(working_memory)
-
     def _vae_decode(self, vae_info: LoadedModel, latents: torch.Tensor) -> Image.Image:
-        estimated_working_memory = self._estimate_working_memory(latents, vae_info.model)
+        assert isinstance(vae_info.model, AutoEncoder)
+        estimated_working_memory = estimate_vae_working_memory_flux(
+            operation="decode", image_tensor=latents, vae=vae_info.model
+        )
         with vae_info.model_on_device(working_mem_bytes=estimated_working_memory) as (_, vae):
             assert isinstance(vae, AutoEncoder)
             vae_dtype = next(iter(vae.parameters())).dtype

invokeai/app/invocations/flux_vae_encode.py

@@ -12,9 +12,10 @@ from invokeai.app.invocations.model import VAEField
 from invokeai.app.invocations.primitives import LatentsOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.flux.modules.autoencoder import AutoEncoder
-from invokeai.backend.model_manager import LoadedModel
+from invokeai.backend.model_manager.load.load_base import LoadedModel
 from invokeai.backend.stable_diffusion.diffusers_pipeline import image_resized_to_grid_as_tensor
 from invokeai.backend.util.devices import TorchDevice
+from invokeai.backend.util.vae_working_memory import estimate_vae_working_memory_flux
 
 
 @invocation(
@@ -41,8 +42,12 @@ class FluxVaeEncodeInvocation(BaseInvocation):
         # TODO(ryand): Write a util function for generating random tensors that is consistent across devices / dtypes.
         # There's a starting point in get_noise(...), but it needs to be extracted and generalized. This function
         # should be used for VAE encode sampling.
+        assert isinstance(vae_info.model, AutoEncoder)
+        estimated_working_memory = estimate_vae_working_memory_flux(
+            operation="encode", image_tensor=image_tensor, vae=vae_info.model
+        )
         generator = torch.Generator(device=TorchDevice.choose_torch_device()).manual_seed(0)
-        with vae_info as vae:
+        with vae_info.model_on_device(working_mem_bytes=estimated_working_memory) as (_, vae):
             assert isinstance(vae, AutoEncoder)
             vae_dtype = next(iter(vae.parameters())).dtype
             image_tensor = image_tensor.to(device=TorchDevice.choose_torch_device(), dtype=vae_dtype)

invokeai/app/invocations/ideal_size.py

@@ -46,7 +46,12 @@ class IdealSizeInvocation(BaseInvocation):
             dimension = 512
         elif unet_config.base == BaseModelType.StableDiffusion2:
             dimension = 768
-        elif unet_config.base in (BaseModelType.StableDiffusionXL, BaseModelType.Flux, BaseModelType.StableDiffusion3):
+        elif unet_config.base in (
+            BaseModelType.StableDiffusionXL,
+            BaseModelType.Flux,
+            BaseModelType.Flux2,
+            BaseModelType.StableDiffusion3,
+        ):
             dimension = 1024
         else:
             raise ValueError(f"Unsupported model type: {unet_config.base}")

invokeai/app/invocations/image.py

@@ -649,102 +649,104 @@ class MaskCombineInvocation(BaseInvocation, WithMetadata, WithBoard):
     title="Color Correct",
     tags=["image", "color"],
     category="image",
-    version="1.2.2",
+    version="2.0.0",
 )
 class ColorCorrectInvocation(BaseInvocation, WithMetadata, WithBoard):
     """
-    Shifts the colors of a target image to match the reference image, optionally
-    using a mask to only color-correct certain regions of the target image.
+    Matches the color histogram of a base image to a reference image, optionally
+    using a mask to only color-correct certain regions of the base image.
     """
 
-    image: ImageField = InputField(description="The image to color-correct")
-    reference: ImageField = InputField(description="Reference image for color-correction")
-    mask: Optional[ImageField] = InputField(default=None, description="Mask to use when applying color-correction")
-    mask_blur_radius: float = InputField(default=8, description="Mask blur radius")
+    base_image: ImageField = InputField(description="The image to color-correct")
+    color_reference: ImageField = InputField(description="Reference image for color-correction")
+    mask: Optional[ImageField] = InputField(default=None, description="Optional mask to limit color correction area")
+    colorspace: Literal["RGB", "YCbCr", "YCbCr-Chroma", "YCbCr-Luma"] = InputField(
+        default="RGB", description="Colorspace in which to apply histogram matching", title="Color Space"
+    )
+
+    def _match_histogram_channel(self, source: numpy.ndarray, reference: numpy.ndarray) -> numpy.ndarray:
+        """Match histogram of source channel to reference channel using cumulative distribution functions."""
+        # Compute histograms
+        source_hist, _ = numpy.histogram(source.flatten(), bins=256, range=(0, 256))
+        reference_hist, _ = numpy.histogram(reference.flatten(), bins=256, range=(0, 256))
+
+        # Compute cumulative distribution functions
+        source_cdf = source_hist.cumsum()
+        reference_cdf = reference_hist.cumsum()
+
+        # Normalize CDFs (avoid division by zero)
+        if source_cdf[-1] > 0:
+            source_cdf = source_cdf / source_cdf[-1]
+        if reference_cdf[-1] > 0:
+            reference_cdf = reference_cdf / reference_cdf[-1]
+
+        # Create lookup table using linear interpolation
+        lookup_table = numpy.interp(source_cdf, reference_cdf, numpy.arange(256))
+
+        # Apply lookup table to source image
+        return lookup_table[source].astype(numpy.uint8)
 
     def invoke(self, context: InvocationContext) -> ImageOutput:
-        pil_init_mask = None
+        # Load images as RGBA
+        base_image = context.images.get_pil(self.base_image.image_name, "RGBA")
+
+        # Store original alpha channel
+        original_alpha = base_image.getchannel("A")
+
+        # Convert to working colorspace
+        if self.colorspace == "RGB":
+            base_array = numpy.asarray(base_image.convert("RGB"), dtype=numpy.uint8)
+            ref_rgb = context.images.get_pil(self.color_reference.image_name, "RGB")
+            ref_array = numpy.asarray(ref_rgb, dtype=numpy.uint8)
+            channels_to_match = [0, 1, 2]  # R, G, B
+        else:
+            # Convert to YCbCr colorspace
+            base_ycbcr = base_image.convert("YCbCr")
+            ref_ycbcr = context.images.get_pil(self.color_reference.image_name, "YCbCr")
+
+            base_array = numpy.asarray(base_ycbcr, dtype=numpy.uint8)
+            ref_array = numpy.asarray(ref_ycbcr, dtype=numpy.uint8)
+
+            # Determine which channels to match based on mode
+            if self.colorspace == "YCbCr":
+                channels_to_match = [0, 1, 2]  # Y, Cb, Cr
+            elif self.colorspace == "YCbCr-Chroma":
+                channels_to_match = [1, 2]  # Cb, Cr only
+            else:  # YCbCr-Luma
+                channels_to_match = [0]  # Y only
+
+        # Apply histogram matching to selected channels
+        corrected_array = base_array.copy()
+        for channel_idx in channels_to_match:
+            corrected_array[:, :, channel_idx] = self._match_histogram_channel(
+                base_array[:, :, channel_idx], ref_array[:, :, channel_idx]
+            )
+
+        # Convert back to RGB if we were in YCbCr
+        if self.colorspace != "RGB":
+            corrected_image = Image.fromarray(corrected_array, mode="YCbCr").convert("RGB")
+        else:
+            corrected_image = Image.fromarray(corrected_array, mode="RGB")
+
+        # Apply mask if provided (white = original, black = result)
         if self.mask is not None:
-            pil_init_mask = context.images.get_pil(self.mask.image_name).convert("L")
-
-        init_image = context.images.get_pil(self.reference.image_name)
-
-        result = context.images.get_pil(self.image.image_name).convert("RGBA")
-
-        # if init_image is None or init_mask is None:
-        #    return result
-
-        # Get the original alpha channel of the mask if there is one.
-        # Otherwise it is some other black/white image format ('1', 'L' or 'RGB')
-        # pil_init_mask = (
-        #    init_mask.getchannel("A")
-        #    if init_mask.mode == "RGBA"
-        #    else init_mask.convert("L")
-        # )
-        pil_init_image = init_image.convert("RGBA")  # Add an alpha channel if one doesn't exist
-
-        # Build an image with only visible pixels from source to use as reference for color-matching.
-        init_rgb_pixels = numpy.asarray(init_image.convert("RGB"), dtype=numpy.uint8)
-        init_a_pixels = numpy.asarray(pil_init_image.getchannel("A"), dtype=numpy.uint8)
-        init_mask_pixels = numpy.asarray(pil_init_mask, dtype=numpy.uint8)
-
-        # Get numpy version of result
-        np_image = numpy.asarray(result.convert("RGB"), dtype=numpy.uint8)
-
-        # Mask and calculate mean and standard deviation
-        mask_pixels = init_a_pixels * init_mask_pixels > 0
-        np_init_rgb_pixels_masked = init_rgb_pixels[mask_pixels, :]
-        np_image_masked = np_image[mask_pixels, :]
-
-        if np_init_rgb_pixels_masked.size > 0:
-            init_means = np_init_rgb_pixels_masked.mean(axis=0)
-            init_std = np_init_rgb_pixels_masked.std(axis=0)
-            gen_means = np_image_masked.mean(axis=0)
-            gen_std = np_image_masked.std(axis=0)
-
-            # Color correct
-            np_matched_result = np_image.copy()
-            np_matched_result[:, :, :] = (
-                (
-                    (
-                        (np_matched_result[:, :, :].astype(numpy.float32) - gen_means[None, None, :])
-                        / gen_std[None, None, :]
-                    )
-                    * init_std[None, None, :]
-                    + init_means[None, None, :]
-                )
-                .clip(0, 255)
-                .astype(numpy.uint8)
-            )
-            matched_result = Image.fromarray(np_matched_result, mode="RGB")
+            # Load mask as grayscale
+            mask_image = context.images.get_pil(self.mask.image_name, "L")
+            # Start with corrected image, paste base image where mask is white
+            result = corrected_image.copy()
+            if mask_image.size != result.size:
+                raise ValueError("Mask size must match base image size.")
+            else:
+                result.paste(base_image.convert("RGB"), mask=mask_image)
         else:
-            matched_result = Image.fromarray(np_image, mode="RGB")
+            result = corrected_image
 
-        # Blur the mask out (into init image) by specified amount
-        if self.mask_blur_radius > 0:
-            nm = numpy.asarray(pil_init_mask, dtype=numpy.uint8)
-            inverted_nm = 255 - nm
-            dilation_size = int(round(self.mask_blur_radius) + 20)
-            dilating_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (dilation_size, dilation_size))
-            inverted_dilated_nm = cv2.dilate(inverted_nm, dilating_kernel)
-            dilated_nm = 255 - inverted_dilated_nm
-            nmd = cv2.erode(
-                dilated_nm,
-                kernel=numpy.ones((3, 3), dtype=numpy.uint8),
-                iterations=int(self.mask_blur_radius / 2),
-            )
-            pmd = Image.fromarray(nmd, mode="L")
-            blurred_init_mask = pmd.filter(ImageFilter.BoxBlur(self.mask_blur_radius))
-        else:
-            blurred_init_mask = pil_init_mask
-
-        multiplied_blurred_init_mask = ImageChops.multiply(blurred_init_mask, result.split()[-1])
-
-        # Paste original on color-corrected generation (using blurred mask)
-        matched_result.paste(init_image, (0, 0), mask=multiplied_blurred_init_mask)
-
-        image_dto = context.images.save(image=matched_result)
+        # Convert to RGBA and restore original alpha
+        result = result.convert("RGBA")
+        result.putalpha(original_alpha)
 
+        # Save and return
+        image_dto = context.images.save(image=result)
         return ImageOutput.build(image_dto)
 
 
@@ -1347,3 +1349,96 @@ class PasteImageIntoBoundingBoxInvocation(BaseInvocation, WithMetadata, WithBoar
 
         image_dto = context.images.save(image=target_image)
         return ImageOutput.build(image_dto)
+
+
+@invocation(
+    "flux_kontext_image_prep",
+    title="FLUX Kontext Image Prep",
+    tags=["image", "concatenate", "flux", "kontext"],
+    category="image",
+    version="1.0.0",
+)
+class FluxKontextConcatenateImagesInvocation(BaseInvocation, WithMetadata, WithBoard):
+    """Prepares an image or images for use with FLUX Kontext. The first/single image is resized to the nearest
+    preferred Kontext resolution. All other images are concatenated horizontally, maintaining their aspect ratio."""
+
+    images: list[ImageField] = InputField(
+        description="The images to concatenate",
+        min_length=1,
+        max_length=10,
+    )
+
+    use_preferred_resolution: bool = InputField(
+        default=True, description="Use FLUX preferred resolutions for the first image"
+    )
+
+    def invoke(self, context: InvocationContext) -> ImageOutput:
+        from invokeai.backend.flux.util import PREFERED_KONTEXT_RESOLUTIONS
+
+        # Step 1: Load all images
+        pil_images = []
+        for image_field in self.images:
+            image = context.images.get_pil(image_field.image_name, mode="RGBA")
+            pil_images.append(image)
+
+        # Step 2: Determine target resolution for the first image
+        first_image = pil_images[0]
+        width, height = first_image.size
+
+        if self.use_preferred_resolution:
+            aspect_ratio = width / height
+
+            # Find the closest preferred resolution for the first image
+            _, target_width, target_height = min(
+                ((abs(aspect_ratio - w / h), w, h) for w, h in PREFERED_KONTEXT_RESOLUTIONS), key=lambda x: x[0]
+            )
+
+            # Apply BFL's scaling formula
+            scaled_height = 2 * int(target_height / 16)
+            final_height = 8 * scaled_height  # This will be consistent for all images
+            scaled_width = 2 * int(target_width / 16)
+            first_width = 8 * scaled_width
+        else:
+            # Use original dimensions of first image, ensuring divisibility by 16
+            final_height = 16 * (height // 16)
+            first_width = 16 * (width // 16)
+            # Ensure minimum dimensions
+            if final_height < 16:
+                final_height = 16
+            if first_width < 16:
+                first_width = 16
+
+        # Step 3: Process and resize all images with consistent height
+        processed_images = []
+        total_width = 0
+
+        for i, image in enumerate(pil_images):
+            if i == 0:
+                # First image uses the calculated dimensions
+                final_width = first_width
+            else:
+                # Subsequent images maintain aspect ratio with the same height
+                img_aspect_ratio = image.width / image.height
+                # Calculate width that maintains aspect ratio at the target height
+                calculated_width = int(final_height * img_aspect_ratio)
+                # Ensure width is divisible by 16 for proper VAE encoding
+                final_width = 16 * (calculated_width // 16)
+                # Ensure minimum width
+                if final_width < 16:
+                    final_width = 16
+
+            # Resize image to calculated dimensions
+            resized_image = image.resize((final_width, final_height), Image.Resampling.LANCZOS)
+            processed_images.append(resized_image)
+            total_width += final_width
+
+        # Step 4: Concatenate images horizontally
+        concatenated_image = Image.new("RGB", (total_width, final_height))
+        x_offset = 0
+        for img in processed_images:
+            concatenated_image.paste(img, (x_offset, 0))
+            x_offset += img.width
+
+        # Save the concatenated image
+        image_dto = context.images.save(image=concatenated_image)
+        return ImageOutput.build(image_dto)

invokeai/app/invocations/image_to_latents.py

@@ -1,5 +1,6 @@
 from contextlib import nullcontext
 from functools import singledispatchmethod
+from typing import Literal
 
 import einops
 import torch
@@ -20,13 +21,22 @@ from invokeai.app.invocations.fields import (
     Input,
     InputField,
 )
-from invokeai.app.invocations.model import VAEField
+from invokeai.app.invocations.model import BaseModelType, VAEField
 from invokeai.app.invocations.primitives import LatentsOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager import LoadedModel
+from invokeai.backend.model_manager.load.load_base import LoadedModel
 from invokeai.backend.stable_diffusion.diffusers_pipeline import image_resized_to_grid_as_tensor
 from invokeai.backend.stable_diffusion.vae_tiling import patch_vae_tiling_params
 from invokeai.backend.util.devices import TorchDevice
+from invokeai.backend.util.vae_working_memory import estimate_vae_working_memory_sd15_sdxl
+
+"""
+SDXL VAE color compensation values determined experimentally to reduce color drift.
+If more reliable values are found in the future (e.g. individual color channels), they can be updated.
+SD1.5, TAESD, TAESDXL VAEs distort in less predictable ways, so no compensation is offered at this time.
+"""
+COMPENSATION_OPTIONS = Literal["None", "SDXL"]
+COLOR_COMPENSATION_MAP = {"None": [1, 0], "SDXL": [1.015, -0.002]}
 
 
 @invocation(
@@ -34,7 +44,7 @@ from invokeai.backend.util.devices import TorchDevice
     title="Image to Latents - SD1.5, SDXL",
     tags=["latents", "image", "vae", "i2l"],
     category="latents",
-    version="1.1.1",
+    version="1.2.0",
 )
 class ImageToLatentsInvocation(BaseInvocation):
     """Encodes an image into latents."""
@@ -51,13 +61,30 @@ class ImageToLatentsInvocation(BaseInvocation):
     # offer a way to directly set None values.
     tile_size: int = InputField(default=0, multiple_of=8, description=FieldDescriptions.vae_tile_size)
     fp32: bool = InputField(default=False, description=FieldDescriptions.fp32)
+    color_compensation: COMPENSATION_OPTIONS = InputField(
+        default="None",
+        description="Apply VAE scaling compensation when encoding images (reduces color drift).",
+    )
 
-    @staticmethod
+    @classmethod
     def vae_encode(
-        vae_info: LoadedModel, upcast: bool, tiled: bool, image_tensor: torch.Tensor, tile_size: int = 0
+        cls,
+        vae_info: LoadedModel,
+        upcast: bool,
+        tiled: bool,
+        image_tensor: torch.Tensor,
+        tile_size: int = 0,
     ) -> torch.Tensor:
-        with vae_info as vae:
-            assert isinstance(vae, (AutoencoderKL, AutoencoderTiny))
+        assert isinstance(vae_info.model, (AutoencoderKL, AutoencoderTiny)), "VAE must be of type SD-1.5 or SDXL"
+        estimated_working_memory = estimate_vae_working_memory_sd15_sdxl(
+            operation="encode",
+            image_tensor=image_tensor,
+            vae=vae_info.model,
+            tile_size=tile_size if tiled else None,
+            fp32=upcast,
+        )
+        with vae_info.model_on_device(working_mem_bytes=estimated_working_memory) as (_, vae):
+            assert isinstance(vae, (AutoencoderKL, AutoencoderTiny)), "VAE must be of type SD-1.5 or SDXL"
             orig_dtype = vae.dtype
             if upcast:
                 vae.to(dtype=torch.float32)
@@ -113,14 +140,24 @@ class ImageToLatentsInvocation(BaseInvocation):
         image = context.images.get_pil(self.image.image_name)
 
         vae_info = context.models.load(self.vae.vae)
+        assert isinstance(vae_info.model, (AutoencoderKL, AutoencoderTiny)), "VAE must be of type SD-1.5 or SDXL"
 
         image_tensor = image_resized_to_grid_as_tensor(image.convert("RGB"))
+
+        if self.color_compensation != "None" and vae_info.config.base == BaseModelType.StableDiffusionXL:
+            scale, bias = COLOR_COMPENSATION_MAP[self.color_compensation]
+            image_tensor = image_tensor * scale + bias
+
         if image_tensor.dim() == 3:
             image_tensor = einops.rearrange(image_tensor, "c h w -> 1 c h w")
 
         context.util.signal_progress("Running VAE encoder")
         latents = self.vae_encode(
-            vae_info=vae_info, upcast=self.fp32, tiled=self.tiled, image_tensor=image_tensor, tile_size=self.tile_size
+            vae_info=vae_info,
+            upcast=self.fp32,
+            tiled=self.tiled or context.config.get().force_tiled_decode,
+            image_tensor=image_tensor,
+            tile_size=self.tile_size,
         )
 
         latents = latents.to("cpu")

invokeai/app/invocations/ip_adapter.py

@@ -5,16 +5,16 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 from typing_extensions import Self
 
 from invokeai.app.invocations.baseinvocation import BaseInvocation, BaseInvocationOutput, invocation, invocation_output
-from invokeai.app.invocations.fields import FieldDescriptions, InputField, OutputField, TensorField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, InputField, OutputField, TensorField
 from invokeai.app.invocations.model import ModelIdentifierField
 from invokeai.app.invocations.primitives import ImageField
 from invokeai.app.invocations.util import validate_begin_end_step, validate_weights
 from invokeai.app.services.model_records.model_records_base import ModelRecordChanges
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager.config import (
-    AnyModelConfig,
-    IPAdapterCheckpointConfig,
-    IPAdapterInvokeAIConfig,
+from invokeai.backend.model_manager.configs.factory import AnyModelConfig
+from invokeai.backend.model_manager.configs.ip_adapter import (
+    IPAdapter_Checkpoint_Config_Base,
+    IPAdapter_InvokeAI_Config_Base,
 )
 from invokeai.backend.model_manager.starter_models import (
     StarterModel,
@@ -85,7 +85,8 @@ class IPAdapterInvocation(BaseInvocation):
         description="The IP-Adapter model.",
         title="IP-Adapter Model",
         ui_order=-1,
-        ui_type=UIType.IPAdapterModel,
+        ui_model_base=[BaseModelType.StableDiffusion1, BaseModelType.StableDiffusionXL],
+        ui_model_type=ModelType.IPAdapter,
     )
     clip_vision_model: Literal["ViT-H", "ViT-G", "ViT-L"] = InputField(
         description="CLIP Vision model to use. Overrides model settings. Mandatory for checkpoint models.",
@@ -122,9 +123,9 @@ class IPAdapterInvocation(BaseInvocation):
     def invoke(self, context: InvocationContext) -> IPAdapterOutput:
         # Lookup the CLIP Vision encoder that is intended to be used with the IP-Adapter model.
         ip_adapter_info = context.models.get_config(self.ip_adapter_model.key)
-        assert isinstance(ip_adapter_info, (IPAdapterInvokeAIConfig, IPAdapterCheckpointConfig))
+        assert isinstance(ip_adapter_info, (IPAdapter_InvokeAI_Config_Base, IPAdapter_Checkpoint_Config_Base))
 
-        if isinstance(ip_adapter_info, IPAdapterInvokeAIConfig):
+        if isinstance(ip_adapter_info, IPAdapter_InvokeAI_Config_Base):
             image_encoder_model_id = ip_adapter_info.image_encoder_model_id
             image_encoder_model_name = image_encoder_model_id.split("/")[-1].strip()
         else:

invokeai/app/invocations/latents_to_image.py

@@ -2,12 +2,6 @@ from contextlib import nullcontext
 
 import torch
 from diffusers.image_processor import VaeImageProcessor
-from diffusers.models.attention_processor import (
-    AttnProcessor2_0,
-    LoRAAttnProcessor2_0,
-    LoRAXFormersAttnProcessor,
-    XFormersAttnProcessor,
-)
 from diffusers.models.autoencoders.autoencoder_kl import AutoencoderKL
 from diffusers.models.autoencoders.autoencoder_tiny import AutoencoderTiny
 
@@ -27,6 +21,7 @@ from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.stable_diffusion.extensions.seamless import SeamlessExt
 from invokeai.backend.stable_diffusion.vae_tiling import patch_vae_tiling_params
 from invokeai.backend.util.devices import TorchDevice
+from invokeai.backend.util.vae_working_memory import estimate_vae_working_memory_sd15_sdxl
 
 
 @invocation(
@@ -53,39 +48,6 @@ class LatentsToImageInvocation(BaseInvocation, WithMetadata, WithBoard):
     tile_size: int = InputField(default=0, multiple_of=8, description=FieldDescriptions.vae_tile_size)
     fp32: bool = InputField(default=False, description=FieldDescriptions.fp32)
 
-    def _estimate_working_memory(
-        self, latents: torch.Tensor, use_tiling: bool, vae: AutoencoderKL | AutoencoderTiny
-    ) -> int:
-        """Estimate the working memory required by the invocation in bytes."""
-        # It was found experimentally that the peak working memory scales linearly with the number of pixels and the
-        # element size (precision). This estimate is accurate for both SD1 and SDXL.
-        element_size = 4 if self.fp32 else 2
-        scaling_constant = 2200  # Determined experimentally.
-
-        if use_tiling:
-            tile_size = self.tile_size
-            if tile_size == 0:
-                tile_size = vae.tile_sample_min_size
-                assert isinstance(tile_size, int)
-            out_h = tile_size
-            out_w = tile_size
-            working_memory = out_h * out_w * element_size * scaling_constant
-
-            # We add 25% to the working memory estimate when tiling is enabled to account for factors like tile overlap
-            # and number of tiles. We could make this more precise in the future, but this should be good enough for
-            # most use cases.
-            working_memory = working_memory * 1.25
-        else:
-            out_h = LATENT_SCALE_FACTOR * latents.shape[-2]
-            out_w = LATENT_SCALE_FACTOR * latents.shape[-1]
-            working_memory = out_h * out_w * element_size * scaling_constant
-
-        if self.fp32:
-            # If we are running in FP32, then we should account for the likely increase in model size (~250MB).
-            working_memory += 250 * 2**20
-
-        return int(working_memory)
-
     @torch.no_grad()
     def invoke(self, context: InvocationContext) -> ImageOutput:
         latents = context.tensors.load(self.latents.latents_name)
@@ -94,8 +56,13 @@ class LatentsToImageInvocation(BaseInvocation, WithMetadata, WithBoard):
 
         vae_info = context.models.load(self.vae.vae)
         assert isinstance(vae_info.model, (AutoencoderKL, AutoencoderTiny))
-
-        estimated_working_memory = self._estimate_working_memory(latents, use_tiling, vae_info.model)
+        estimated_working_memory = estimate_vae_working_memory_sd15_sdxl(
+            operation="decode",
+            image_tensor=latents,
+            vae=vae_info.model,
+            tile_size=self.tile_size if use_tiling else None,
+            fp32=self.fp32,
+        )
         with (
             SeamlessExt.static_patch_model(vae_info.model, self.vae.seamless_axes),
             vae_info.model_on_device(working_mem_bytes=estimated_working_memory) as (_, vae),
@@ -104,26 +71,9 @@ class LatentsToImageInvocation(BaseInvocation, WithMetadata, WithBoard):
             assert isinstance(vae, (AutoencoderKL, AutoencoderTiny))
             latents = latents.to(TorchDevice.choose_torch_device())
             if self.fp32:
+                # FP32 mode: convert everything to float32 for maximum precision
                 vae.to(dtype=torch.float32)
-
-                use_torch_2_0_or_xformers = hasattr(vae.decoder, "mid_block") and isinstance(
-                    vae.decoder.mid_block.attentions[0].processor,
-                    (
-                        AttnProcessor2_0,
-                        XFormersAttnProcessor,
-                        LoRAXFormersAttnProcessor,
-                        LoRAAttnProcessor2_0,
-                    ),
-                )
-                # if xformers or torch_2_0 is used attention block does not need
-                # to be in float32 which can save lots of memory
-                if use_torch_2_0_or_xformers:
-                    vae.post_quant_conv.to(latents.dtype)
-                    vae.decoder.conv_in.to(latents.dtype)
-                    vae.decoder.mid_block.to(latents.dtype)
-                else:
-                    latents = latents.float()
-
+                latents = latents.float()
             else:
                 vae.to(dtype=torch.float16)
                 latents = latents.half()

invokeai/app/invocations/llava_onevision_vllm.py

@@ -6,11 +6,12 @@ from pydantic import field_validator
 from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration, LlavaOnevisionProcessor
 
 from invokeai.app.invocations.baseinvocation import BaseInvocation, Classification, invocation
-from invokeai.app.invocations.fields import FieldDescriptions, ImageField, InputField, UIComponent, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, ImageField, InputField, UIComponent
 from invokeai.app.invocations.model import ModelIdentifierField
 from invokeai.app.invocations.primitives import StringOutput
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.backend.llava_onevision_pipeline import LlavaOnevisionPipeline
+from invokeai.backend.model_manager.taxonomy import ModelType
 from invokeai.backend.util.devices import TorchDevice
 
 
@@ -34,7 +35,7 @@ class LlavaOnevisionVllmInvocation(BaseInvocation):
     vllm_model: ModelIdentifierField = InputField(
         title="LLaVA Model Type",
         description=FieldDescriptions.vllm_model,
-        ui_type=UIType.LlavaOnevisionModel,
+        ui_model_type=ModelType.LlavaOnevision,
     )
 
     @field_validator("images", mode="before")

invokeai/app/invocations/metadata.py

@@ -150,6 +150,10 @@ GENERATION_MODES = Literal[
     "flux_img2img",
     "flux_inpaint",
     "flux_outpaint",
+    "flux2_txt2img",
+    "flux2_img2img",
+    "flux2_inpaint",
+    "flux2_outpaint",
     "sd3_txt2img",
     "sd3_img2img",
     "sd3_inpaint",
@@ -158,6 +162,10 @@ GENERATION_MODES = Literal[
     "cogview4_img2img",
     "cogview4_inpaint",
     "cogview4_outpaint",
+    "z_image_txt2img",
+    "z_image_img2img",
+    "z_image_inpaint",
+    "z_image_outpaint",
 ]
 
 
@@ -166,7 +174,7 @@ GENERATION_MODES = Literal[
     title="Core Metadata",
     tags=["metadata"],
     category="metadata",
-    version="2.0.0",
+    version="2.1.0",
     classification=Classification.Internal,
 )
 class CoreMetadataInvocation(BaseInvocation):
@@ -217,6 +225,10 @@ class CoreMetadataInvocation(BaseInvocation):
         default=None,
         description="The VAE used for decoding, if the main model's default was not used",
     )
+    qwen3_encoder: Optional[ModelIdentifierField] = InputField(
+        default=None,
+        description="The Qwen3 text encoder model used for Z-Image inference",
+    )
 
     # High resolution fix metadata.
     hrf_enabled: Optional[bool] = InputField(

invokeai/app/invocations/metadata_linked.py

@@ -52,8 +52,9 @@ from invokeai.app.invocations.primitives import (
 )
 from invokeai.app.invocations.scheduler import SchedulerOutput
 from invokeai.app.invocations.t2i_adapter import T2IAdapterField, T2IAdapterInvocation
+from invokeai.app.invocations.z_image_denoise import ZImageDenoiseInvocation
 from invokeai.app.services.shared.invocation_context import InvocationContext
-from invokeai.backend.model_manager.taxonomy import ModelType, SubModelType
+from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType, SubModelType
 from invokeai.backend.stable_diffusion.schedulers.schedulers import SCHEDULER_NAME_VALUES
 from invokeai.version import __version__
 
@@ -473,7 +474,6 @@ class MetadataToModelOutput(BaseInvocationOutput):
     model: ModelIdentifierField = OutputField(
         description=FieldDescriptions.main_model,
         title="Model",
-        ui_type=UIType.MainModel,
     )
     name: str = OutputField(description="Model Name", title="Name")
     unet: UNetField = OutputField(description=FieldDescriptions.unet, title="UNet")
@@ -488,7 +488,6 @@ class MetadataToSDXLModelOutput(BaseInvocationOutput):
     model: ModelIdentifierField = OutputField(
         description=FieldDescriptions.main_model,
         title="Model",
-        ui_type=UIType.SDXLMainModel,
     )
     name: str = OutputField(description="Model Name", title="Name")
     unet: UNetField = OutputField(description=FieldDescriptions.unet, title="UNet")
@@ -519,8 +518,7 @@ class MetadataToModelInvocation(BaseInvocation, WithMetadata):
         input=Input.Direct,
     )
     default_value: ModelIdentifierField = InputField(
-        description="The default model to use if not found in the metadata",
-        ui_type=UIType.MainModel,
+        description="The default model to use if not found in the metadata", ui_model_type=ModelType.Main
     )
 
     _validate_custom_label = model_validator(mode="after")(validate_custom_label)
@@ -575,7 +573,8 @@ class MetadataToSDXLModelInvocation(BaseInvocation, WithMetadata):
     )
     default_value: ModelIdentifierField = InputField(
         description="The default SDXL Model to use if not found in the metadata",
-        ui_type=UIType.SDXLMainModel,
+        ui_model_type=ModelType.Main,
+        ui_model_base=BaseModelType.StableDiffusionXL,
     )
 
     _validate_custom_label = model_validator(mode="after")(validate_custom_label)
@@ -731,6 +730,52 @@ class FluxDenoiseLatentsMetaInvocation(FluxDenoiseInvocation, WithMetadata):
         return LatentsMetaOutput(**params, metadata=MetadataField.model_validate(md))
 
 
+@invocation(
+    "z_image_denoise_meta",
+    title=f"{ZImageDenoiseInvocation.UIConfig.title} + Metadata",
+    tags=["z-image", "latents", "denoise", "txt2img", "t2i", "t2l", "img2img", "i2i", "l2l"],
+    category="latents",
+    version="1.0.0",
+)
+class ZImageDenoiseMetaInvocation(ZImageDenoiseInvocation, WithMetadata):
+    """Run denoising process with a Z-Image transformer model + metadata."""
+
+    def invoke(self, context: InvocationContext) -> LatentsMetaOutput:
+        def _loras_to_json(obj: Union[Any, list[Any]]):
+            if not isinstance(obj, list):
+                obj = [obj]
+
+            output: list[dict[str, Any]] = []
+            for item in obj:
+                output.append(
+                    LoRAMetadataField(
+                        model=item.lora,
+                        weight=item.weight,
+                    ).model_dump(exclude_none=True, exclude={"id", "type", "is_intermediate", "use_cache"})
+                )
+            return output
+
+        obj = super().invoke(context)
+
+        md: Dict[str, Any] = {} if self.metadata is None else self.metadata.root
+        md.update({"width": obj.width})
+        md.update({"height": obj.height})
+        md.update({"steps": self.steps})
+        md.update({"guidance": self.guidance_scale})
+        md.update({"denoising_start": self.denoising_start})
+        md.update({"denoising_end": self.denoising_end})
+        md.update({"scheduler": self.scheduler})
+        md.update({"model": self.transformer.transformer})
+        md.update({"seed": self.seed})
+        if len(self.transformer.loras) > 0:
+            md.update({"loras": _loras_to_json(self.transformer.loras)})
+
+        params = obj.__dict__.copy()
+        del params["type"]
+
+        return LatentsMetaOutput(**params, metadata=MetadataField.model_validate(md))
+
+
 @invocation(
     "metadata_to_vae",
     title="Metadata To VAE",

invokeai/app/invocations/model.py

@@ -9,12 +9,10 @@ from invokeai.app.invocations.baseinvocation import (
     invocation,
     invocation_output,
 )
-from invokeai.app.invocations.fields import FieldDescriptions, ImageField, Input, InputField, OutputField, UIType
+from invokeai.app.invocations.fields import FieldDescriptions, ImageField, Input, InputField, OutputField
 from invokeai.app.services.shared.invocation_context import InvocationContext
 from invokeai.app.shared.models import FreeUConfig
-from invokeai.backend.model_manager.config import (
-    AnyModelConfig,
-)
+from invokeai.backend.model_manager.configs.factory import AnyModelConfig
 from invokeai.backend.model_manager.taxonomy import BaseModelType, ModelType, SubModelType
 
 
@@ -24,8 +22,9 @@ class ModelIdentifierField(BaseModel):
     name: str = Field(description="The model's name")
     base: BaseModelType = Field(description="The model's base model type")
     type: ModelType = Field(description="The model's type")
-    submodel_type: Optional[SubModelType] = Field(
-        description="The submodel to load, if this is a main model", default=None
+    submodel_type: SubModelType | None = Field(
+        description="The submodel to load, if this is a main model",
+        default=None,
     )
 
     @classmethod
@@ -73,6 +72,14 @@ class GlmEncoderField(BaseModel):
     text_encoder: ModelIdentifierField = Field(description="Info to load text_encoder submodel")
 
 
+class Qwen3EncoderField(BaseModel):
+    """Field for Qwen3 text encoder used by Z-Image models."""
+
+    tokenizer: ModelIdentifierField = Field(description="Info to load tokenizer submodel")
+    text_encoder: ModelIdentifierField = Field(description="Info to load text_encoder submodel")
+    loras: List[LoRAField] = Field(default_factory=list, description="LoRAs to apply on model loading")
+
+
 class VAEField(BaseModel):
     vae: ModelIdentifierField = Field(description="Info to load vae submodel")
     seamless_axes: List[str] = Field(default_factory=list, description='Axes("x" and "y") to which apply seamless')
@@ -145,7 +152,7 @@ class ModelIdentifierInvocation(BaseInvocation):
 
 @invocation(
     "main_model_loader",
-    title="Main Model - SD1.5",
+    title="Main Model - SD1.5, SD2",
     tags=["model"],
     category="model",
     version="1.0.4",
@@ -153,7 +160,11 @@ class ModelIdentifierInvocation(BaseInvocation):
 class MainModelLoaderInvocation(BaseInvocation):
     """Loads a main model, outputting its submodels."""
 
-    model: ModelIdentifierField = InputField(description=FieldDescriptions.main_model, ui_type=UIType.MainModel)
+    model: ModelIdentifierField = InputField(
+        description=FieldDescriptions.main_model,
+        ui_model_base=[BaseModelType.StableDiffusion1, BaseModelType.StableDiffusion2],
+        ui_model_type=ModelType.Main,
+    )
     # TODO: precision?
 
     def invoke(self, context: InvocationContext) -> ModelLoaderOutput:
@@ -187,7 +198,10 @@ class LoRALoaderInvocation(BaseInvocation):
     """Apply selected lora to unet and text_encoder."""
 
     lora: ModelIdentifierField = InputField(
-        description=FieldDescriptions.lora_model, title="LoRA", ui_type=UIType.LoRAModel
+        description=FieldDescriptions.lora_model,
+        title="LoRA",
+        ui_model_base=BaseModelType.StableDiffusion1,
+        ui_model_type=ModelType.LoRA,
     )
     weight: float = InputField(default=0.75, description=FieldDescriptions.lora_weight)
     unet: Optional[UNetField] = InputField(
@@ -250,7 +264,9 @@ class LoRASelectorInvocation(BaseInvocation):
     """Selects a LoRA model and weight."""
 
     lora: ModelIdentifierField = InputField(
-        description=FieldDescriptions.lora_model, title="LoRA", ui_type=UIType.LoRAModel
+        description=FieldDescriptions.lora_model,
+        title="LoRA",
+        ui_model_type=ModelType.LoRA,
     )
     weight: float = InputField(default=0.75, description=FieldDescriptions.lora_weight)
 
@@ -332,7 +348,10 @@ class SDXLLoRALoaderInvocation(BaseInvocation):
     """Apply selected lora to unet and text_encoder."""
 
     lora: ModelIdentifierField = InputField(
-        description=FieldDescriptions.lora_model, title="LoRA", ui_type=UIType.LoRAModel
+        description=FieldDescriptions.lora_model,
+        title="LoRA",
+        ui_model_base=BaseModelType.StableDiffusionXL,
+        ui_model_type=ModelType.LoRA,
     )
     weight: float = InputField(default=0.75, description=FieldDescriptions.lora_weight)
     unet: Optional[UNetField] = InputField(
@@ -473,13 +492,27 @@ class SDXLLoRACollectionLoader(BaseInvocation):
 
 
 @invocation(
-    "vae_loader", title="VAE Model - SD1.5, SDXL, SD3, FLUX", tags=["vae", "model"], category="model", version="1.0.4"
+    "vae_loader",
+    title="VAE Model - SD1.5, SD2, SDXL, SD3, FLUX",
+    tags=["vae", "model"],
+    category="model",
+    version="1.0.4",
 )
 class VAELoaderInvocation(BaseInvocation):
     """Loads a VAE model, outputting a VaeLoaderOutput"""
 
     vae_model: ModelIdentifierField = InputField(
-        description=FieldDescriptions.vae_model, title="VAE", ui_type=UIType.VAEModel
+        description=FieldDescriptions.vae_model,
+        title="VAE",
+        ui_model_base=[
+            BaseModelType.StableDiffusion1,
+            BaseModelType.StableDiffusion2,
+            BaseModelType.StableDiffusionXL,
+            BaseModelType.StableDiffusion3,
+            BaseModelType.Flux,
+            BaseModelType.Flux2,
+        ],
+        ui_model_type=ModelType.VAE,
     )
 
     def invoke(self, context: InvocationContext) -> VAEOutput:

invokeai/app/invocations/pbr_maps.py

@@ -0,0 +1,59 @@
+import pathlib
+from typing import Literal
+
+from invokeai.app.invocations.baseinvocation import BaseInvocation, BaseInvocationOutput, invocation, invocation_output
+from invokeai.app.invocations.fields import ImageField, InputField, OutputField, WithBoard, WithMetadata
+from invokeai.app.services.shared.invocation_context import InvocationContext
+from invokeai.backend.image_util.pbr_maps.architecture.pbr_rrdb_net import PBR_RRDB_Net
+from invokeai.backend.image_util.pbr_maps.pbr_maps import NORMAL_MAP_MODEL, OTHER_MAP_MODEL, PBRMapsGenerator
+from invokeai.backend.util.devices import TorchDevice
+
+
+@invocation_output("pbr_maps-output")
+class PBRMapsOutput(BaseInvocationOutput):
+    normal_map: ImageField = OutputField(default=None, description="The generated normal map")
+    roughness_map: ImageField = OutputField(default=None, description="The generated roughness map")
+    displacement_map: ImageField = OutputField(default=None, description="The generated displacement map")
+
+
+@invocation("pbr_maps", title="PBR Maps", tags=["image", "material"], category="image", version="1.0.0")
+class PBRMapsInvocation(BaseInvocation, WithMetadata, WithBoard):
+    """Generate Normal, Displacement and Roughness Map from a given image"""
+
+    image: ImageField = InputField(description="Input image")
+    tile_size: int = InputField(default=512, description="Tile size")
+    border_mode: Literal["none", "seamless", "mirror", "replicate"] = InputField(
+        default="none", description="Border mode to apply to eliminate any artifacts or seams"
+    )
+
+    def invoke(self, context: InvocationContext) -> PBRMapsOutput:
+        image_pil = context.images.get_pil(self.image.image_name, mode="RGB")
+
+        def loader(model_path: pathlib.Path):
+            return PBRMapsGenerator.load_model(model_path, TorchDevice.choose_torch_device())
+
+        torch_device = TorchDevice.choose_torch_device()
+
+        with (
+            context.models.load_remote_model(NORMAL_MAP_MODEL, loader) as normal_map_model,
+            context.models.load_remote_model(OTHER_MAP_MODEL, loader) as other_map_model,
+        ):
+            assert isinstance(normal_map_model, PBR_RRDB_Net)
+            assert isinstance(other_map_model, PBR_RRDB_Net)
+            pbr_pipeline = PBRMapsGenerator(normal_map_model, other_map_model, torch_device)
+            normal_map, roughness_map, displacement_map = pbr_pipeline.generate_maps(
+                image_pil, self.tile_size, self.border_mode
+            )
+
+            normal_map = context.images.save(normal_map)
+            normal_map_field = ImageField(image_name=normal_map.image_name)
+
+            roughness_map = context.images.save(roughness_map)
+            roughness_map_field = ImageField(image_name=roughness_map.image_name)
+
+            displacement_map = context.images.save(displacement_map)
+            displacement_map_field = ImageField(image_name=displacement_map.image_name)
+
+        return PBRMapsOutput(
+            normal_map=normal_map_field, roughness_map=roughness_map_field, displacement_map=displacement_map_field
+        )