absolutize model paths returned by the web API

.dev_scripts/diff_images.py

@@ -20,13 +20,13 @@ def calc_images_mean_L1(image1_path, image2_path):
 
 def parse_args():
     parser = argparse.ArgumentParser()
-    parser.add_argument("image1_path")
-    parser.add_argument("image2_path")
+    parser.add_argument('image1_path')
+    parser.add_argument('image2_path')
     args = parser.parse_args()
     return args
 
 
-if __name__ == "__main__":
+if __name__ == '__main__':
     args = parse_args()
     mean_L1 = calc_images_mean_L1(args.image1_path, args.image2_path)
     print(mean_L1)

.git-blame-ignore-revs

@@ -1,2 +1 @@
 b3dccfaeb636599c02effc377cdd8a87d658256c
-218b6d0546b990fc449c876fb99f44b50c4daa35

.gitattributes

@@ -2,4 +2,3 @@
 # Only affects text files and ignores other file types.
 # For more info see: https://www.aleksandrhovhannisyan.com/blog/crlf-vs-lf-normalizing-line-endings-in-git/
 * text=auto
-docker/** text eol=lf

.github/CODEOWNERS

@@ -1,32 +1,34 @@
 # continuous integration
-/.github/workflows/  @lstein @blessedcoolant @hipsterusername @ebr
+/.github/workflows/  @lstein @blessedcoolant
 
 # documentation
-/docs/ @lstein @blessedcoolant @hipsterusername @Millu
-/mkdocs.yml @lstein  @blessedcoolant @hipsterusername @Millu
+/docs/ @lstein @blessedcoolant @hipsterusername
+/mkdocs.yml @lstein  @blessedcoolant
 
 # nodes
-/invokeai/app/ @Kyle0654 @blessedcoolant @psychedelicious @brandonrising @hipsterusername
+/invokeai/app/ @Kyle0654 @blessedcoolant @psychedelicious @brandonrising 
 
 # installation and configuration
-/pyproject.toml  @lstein @blessedcoolant @hipsterusername
-/docker/  @lstein @blessedcoolant @hipsterusername @ebr
-/scripts/ @ebr @lstein @hipsterusername
-/installer/ @lstein @ebr @hipsterusername
-/invokeai/assets @lstein @ebr @hipsterusername
-/invokeai/configs @lstein @hipsterusername
-/invokeai/version @lstein @blessedcoolant @hipsterusername
+/pyproject.toml  @lstein @blessedcoolant
+/docker/  @lstein @blessedcoolant
+/scripts/ @ebr @lstein
+/installer/ @lstein @ebr
+/invokeai/assets @lstein @ebr
+/invokeai/configs @lstein
+/invokeai/version @lstein @blessedcoolant
 
 # web ui
-/invokeai/frontend @blessedcoolant @psychedelicious @lstein @maryhipp @hipsterusername
-/invokeai/backend @blessedcoolant @psychedelicious @lstein @maryhipp @hipsterusername
+/invokeai/frontend @blessedcoolant @psychedelicious @lstein @maryhipp
+/invokeai/backend @blessedcoolant @psychedelicious @lstein @maryhipp
 
 # generation, model management, postprocessing
-/invokeai/backend  @damian0815 @lstein @blessedcoolant @gregghelt2 @StAlKeR7779 @brandonrising @ryanjdick @hipsterusername
+/invokeai/backend  @damian0815 @lstein @blessedcoolant @gregghelt2 @StAlKeR7779 @brandonrising
 
 # front ends
-/invokeai/frontend/CLI @lstein @hipsterusername
-/invokeai/frontend/install @lstein @ebr @hipsterusername
-/invokeai/frontend/merge @lstein @blessedcoolant @hipsterusername
-/invokeai/frontend/training @lstein @blessedcoolant @hipsterusername
-/invokeai/frontend/web @psychedelicious @blessedcoolant @maryhipp @hipsterusername
+/invokeai/frontend/CLI @lstein
+/invokeai/frontend/install @lstein @ebr  
+/invokeai/frontend/merge @lstein @blessedcoolant 
+/invokeai/frontend/training @lstein @blessedcoolant 
+/invokeai/frontend/web @psychedelicious @blessedcoolant @maryhipp 
+
+

.github/ISSUE_TEMPLATE/BUG_REPORT.yml

@@ -6,6 +6,10 @@ title: '[bug]: '
 
 labels: ['bug']
 
+# assignees:
+#   - moderator_bot
+#   - lstein
+
 body:
   - type: markdown
     attributes:
@@ -14,9 +18,10 @@ body:
 
   - type: checkboxes
     attributes:
-      label: Is there an existing issue for this problem?
+      label: Is there an existing issue for this?
       description: |
-        Please [search](https://github.com/invoke-ai/InvokeAI/issues) first to see if an issue already exists for the problem.
+        Please use the [search function](https://github.com/invoke-ai/InvokeAI/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+        irst to see if an issue already exists for the bug you encountered.
       options:
         - label: I have searched the existing issues
           required: true
@@ -28,119 +33,80 @@ body:
   - type: dropdown
     id: os_dropdown
     attributes:
-      label: Operating system
-      description: Your computer's operating system.
+      label: OS
+      description: Which operating System did you use when the bug occured
       multiple: false
       options:
         - 'Linux'
         - 'Windows'
         - 'macOS'
-        - 'other'
     validations:
       required: true
 
   - type: dropdown
     id: gpu_dropdown
     attributes:
-      label: GPU vendor
-      description: Your GPU's vendor.
+      label: GPU
+      description: Which kind of Graphic-Adapter is your System using
       multiple: false
       options:
-        - 'Nvidia (CUDA)'
-        - 'AMD (ROCm)'
-        - 'Apple Silicon (MPS)'
-        - 'None (CPU)'
+        - 'cuda'
+        - 'amd'
+        - 'mps'
+        - 'cpu'
     validations:
       required: true
 
-  - type: input
-    id: gpu_model
-    attributes:
-      label: GPU model
-      description: Your GPU's model. If on Apple Silicon, this is your Mac's chip. Leave blank if on CPU.
-      placeholder: ex. RTX 2080 Ti, Mac M1 Pro
-    validations:
-      required: false
-
   - type: input
     id: vram
     attributes:
-      label: GPU VRAM
-      description: Your GPU's VRAM. If on Apple Silicon, this is your Mac's unified memory. Leave blank if on CPU.
+      label: VRAM
+      description: Size of the VRAM if known
       placeholder: 8GB
     validations:
       required: false
-
+      
   - type: input
     id: version-number
     attributes:
-      label: Version number
+      label: What version did you experience this issue on?
       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
+        Please share the version of Invoke AI that you experienced the issue on. If this is not the latest version, please update first to confirm the issue still exists. If you are testing main, please include the commit hash instead.
+      placeholder: X.X.X
     validations:
       required: true
 
-  - type: input
-    id: browser-version
-    attributes:
-      label: Browser
-      description: Your web browser and version.
-      placeholder: ex. Firefox 123.0b3
-    validations:
-      required: true
-
-  - type: textarea
-    id: python-deps
-    attributes:
-      label: Python dependencies
-      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.
-    validations:
-      required: false
-
   - type: textarea
     id: what-happened
     attributes:
-      label: What happened
+      label: What happened?
       description: |
-        Describe what happened. Include any relevant error messages, stack traces and screenshots here.
-      placeholder: I clicked button X and then Y happened.
+        Briefly describe what happened, what you expected to happen and how to reproduce this bug.
+      placeholder: When using the webinterface and right-clicking on button X instead of the popup-menu there error Y appears
     validations:
       required: true
 
   - type: textarea
-    id: what-you-expected
     attributes:
-      label: What you expected to happen
-      description: Describe what you expected to happen.
-      placeholder: I expected Z to happen.
-    validations:
-      required: true
-
-  - type: textarea
-    id: how-to-repro
-    attributes:
-      label: How to reproduce the problem
-      description: List steps to reproduce the problem.
-      placeholder: Start the app, generate an image with these settings, then click button X.
+      label: Screenshots
+      description: If applicable, add screenshots to help explain your problem
+      placeholder: this is what the result looked like <screenshot>
     validations:
       required: false
 
   - type: textarea
-    id: additional-context
     attributes:
       label: Additional context
-      description: Any other context that might help us to understand the problem.
+      description: Add any other context about the problem here
       placeholder: Only happens when there is full moon and Friday the 13th on Christmas Eve 🎅🏻
     validations:
       required: false
 
   - type: input
-    id: discord-username
+    id: contact
     attributes:
-      label: Discord username
-      description: If you are on the Invoke discord and would prefer to be contacted there, please provide your username.
-      placeholder: supercoolusername123
+      label: Contact Details
+      description: __OPTIONAL__ How can we get in touch with you if we need more info (besides this issue)?
+      placeholder: ex. email@example.com, discordname, twitter, ...
     validations:
       required: false

.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml

@@ -1,5 +1,5 @@
 name: Feature Request
-description: Contribute a idea or request a new feature
+description: Commit a idea or Request a new feature
 title: '[enhancement]: '
 labels: ['enhancement']
 # assignees:
@@ -9,14 +9,14 @@ body:
   - type: markdown
     attributes:
       value: |
-        Thanks for taking the time to fill out this feature request!
+        Thanks for taking the time to fill out this Feature request!
 
   - type: checkboxes
     attributes:
       label: Is there an existing issue for this?
       description: |
         Please make use of the [search function](https://github.com/invoke-ai/InvokeAI/labels/enhancement)
-        to see if a similar issue already exists for the feature you want to request
+        to see if a simmilar issue already exists for the feature you want to request
       options:
         - label: I have searched the existing issues
           required: true
@@ -34,9 +34,12 @@ body:
     id: whatisexpected
     attributes:
       label: What should this feature add?
-      description: Explain the functionality this feature should add. Feature requests should be for single features. Please create multiple requests if you want to request multiple features.
+      description: Please try to explain the functionality this feature should add
       placeholder: |
-        I'd like a button that creates an image of banana sushi every time I press it. Each image should be different. There should be a toggle next to the button that enables strawberry mode, in which the images are of strawberry sushi instead.
+        Instead of one huge textfield, it would be nice to have forms for bug-reports, feature-requests, ...
+        Great benefits with automatic labeling, assigning and other functionalitys not available in that form
+        via old-fashioned markdown-templates. I would also love to see the use of a moderator bot 🤖 like
+        https://github.com/marketplace/actions/issue-moderator-with-commands to auto close old issues and other things
     validations:
       required: true
 
@@ -48,6 +51,6 @@ body:
 
   - type: textarea
     attributes:
-      label: Additional Content
+      label: Aditional Content
       description: Add any other context or screenshots about the feature request here.
-      placeholder: This is a mockup of the design how I imagine it <screenshot>
+      placeholder: This is a Mockup of the design how I imagine it <screenshot>

.github/actions/install-frontend-deps/action.yml

@@ -1,33 +0,0 @@
-name: install frontend dependencies
-description: Installs frontend dependencies with pnpm, with caching
-runs:
-  using: 'composite'
-  steps:
-    - name: setup node 18
-      uses: actions/setup-node@v4
-      with:
-        node-version: '18'
-
-    - name: setup pnpm
-      uses: pnpm/action-setup@v2
-      with:
-        version: 8
-        run_install: false
-
-    - name: get pnpm store directory
-      shell: bash
-      run: |
-        echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-    - name: setup cache
-      uses: actions/cache@v4
-      with:
-        path: ${{ env.STORE_PATH }}
-        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-        restore-keys: |
-          ${{ runner.os }}-pnpm-store-
-
-    - name: install frontend dependencies
-      run: pnpm install --prefer-frozen-lockfile
-      shell: bash
-      working-directory: invokeai/frontend/web

.github/pr_labels.yml

@@ -1,59 +0,0 @@
-root:
-- changed-files:
-  - any-glob-to-any-file: '*'
-
-python-deps:
-- changed-files:
-  - any-glob-to-any-file: 'pyproject.toml'
-
-python:
-- changed-files:
-  - all-globs-to-any-file: 
-    - 'invokeai/**'
-    - '!invokeai/frontend/web/**'
-
-python-tests:
-- changed-files:
-  - any-glob-to-any-file: 'tests/**'
-
-ci-cd:
-- changed-files:
-  - any-glob-to-any-file: .github/**
-
-docker:
-- changed-files:
-  - any-glob-to-any-file: docker/**
-
-installer:
-- changed-files:
-  - any-glob-to-any-file: installer/**
-
-docs:
-- changed-files:
-  - any-glob-to-any-file: docs/**
-
-invocations:
-- changed-files:
-  - any-glob-to-any-file: 'invokeai/app/invocations/**'
-
-backend:
-- changed-files:
-  - any-glob-to-any-file: 'invokeai/backend/**'
-
-api:
-- changed-files:
-  - any-glob-to-any-file: 'invokeai/app/api/**'
-
-services:
-- changed-files:
-  - any-glob-to-any-file: 'invokeai/app/services/**'
-
-frontend-deps:
-- changed-files:
-  - any-glob-to-any-file:
-    - '**/*/package.json'
-    - '**/*/pnpm-lock.yaml'
-
-frontend:
-- changed-files:
-  - any-glob-to-any-file: 'invokeai/frontend/web/**'

.github/pull_request_template.md

@@ -1,66 +0,0 @@
-## What type of PR is this? (check all applicable)
-
-- [ ] Refactor
-- [ ] Feature
-- [ ] Bug Fix
-- [ ] Optimization
-- [ ] Documentation Update
-- [ ] Community Node Submission
-
-
-## Have you discussed this change with the InvokeAI team?
-- [ ] Yes
-- [ ] No, because:
-
-      
-## Have you updated all relevant documentation?
-- [ ] Yes
-- [ ] No
-
-
-## Description
-
-
-## Related Tickets & Documents
-
-<!--
-For pull requests that relate or close an issue, please include them
-below. 
-
-For example having the text: "closes #1234" would connect the current pull
-request to issue 1234.  And when we merge the pull request, Github will
-automatically close the issue.
--->
-
-- Related Issue #
-- Closes #
-
-## QA Instructions, Screenshots, Recordings
-
-<!-- 
-Please provide steps on how to test changes, any hardware or 
-software specifications as well as any other pertinent information. 
--->
-
-## Merge Plan
-
-<!--
-A merge plan describes how this PR should be handled after it is approved.
-
-Example merge plans:
-- "This PR can be merged when approved"
-- "This must be squash-merged when approved"
-- "DO NOT MERGE - I will rebase and tidy commits before merging"
-- "#dev-chat on discord needs to be advised of this change when it is merged"
-
-A merge plan is particularly important for large PRs or PRs that touch the
-database in any way.
--->
-
-## Added/updated tests?
-
-- [ ] Yes
-- [ ] No : _please replace this line with details on why tests
-      have not been included_
-
-## [optional] Are there any post deployment tasks we need to perform?

.github/workflows/build-container.yml

@@ -11,7 +11,7 @@ on:
       - 'docker/docker-entrypoint.sh'
       - 'workflows/build-container.yml'
     tags:
-      - 'v*.*.*'
+      - 'v*'
   workflow_dispatch:
 
 permissions:
@@ -40,14 +40,10 @@ jobs:
       - 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"
           sudo swapoff /mnt/swapfile
           sudo rm -rf /mnt/swapfile
-          echo "----- Free space after cleanup"
-          df -h
 
       - name: Checkout
         uses: actions/checkout@v3
@@ -95,7 +91,6 @@ jobs:
       #     password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build container
-        timeout-minutes: 40
         id: docker_build
         uses: docker/build-push-action@v4
         with:

.github/workflows/build-installer.yml

@@ -1,45 +0,0 @@
-# Builds and uploads the installer and python build artifacts.
-
-name: build installer
-
-on:
-  workflow_dispatch:
-  workflow_call:
-
-jobs:
-  build-installer:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5 # expected run time: <2 min
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-
-      - name: setup python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-          cache: pip
-          cache-dependency-path: pyproject.toml
-
-      - name: install pypa/build
-        run: pip install --upgrade build
-
-      - name: setup frontend
-        uses: ./.github/actions/install-frontend-deps
-
-      - name: create installer
-        id: create_installer
-        run: ./create_installer.sh
-        working-directory: installer
-
-      - name: upload python distribution artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: dist
-          path: ${{ steps.create_installer.outputs.DIST_PATH }}
-
-      - name: upload installer artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ steps.create_installer.outputs.INSTALLER_FILENAME }}
-          path: ${{ steps.create_installer.outputs.INSTALLER_PATH }}

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

@@ -1,11 +1,11 @@
 name: Close inactive issues
 on:
   schedule:
-    - cron: "00 4 * * *"
+    - cron: "00 6 * * *"
 
 env:
-  DAYS_BEFORE_ISSUE_STALE: 30
-  DAYS_BEFORE_ISSUE_CLOSE: 14
+  DAYS_BEFORE_ISSUE_STALE: 14
+  DAYS_BEFORE_ISSUE_CLOSE: 28
 
 jobs:
   close-issues:
@@ -14,7 +14,7 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: actions/stale@v8
+      - uses: actions/stale@v5
         with:
           days-before-issue-stale: ${{ env.DAYS_BEFORE_ISSUE_STALE }}
           days-before-issue-close: ${{ env.DAYS_BEFORE_ISSUE_CLOSE }}
@@ -23,6 +23,5 @@ 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
-          exempt-issue-labels: "Active Issue"
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           operations-per-run: 500

.github/workflows/frontend-checks.yml

@@ -1,68 +0,0 @@
-# Runs frontend code quality checks.
-#
-# Checks for changes to frontend files before running the checks.
-# When manually triggered or when called from another workflow, always runs the checks.
-
-name: 'frontend checks'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-  workflow_call:
-
-defaults:
-  run:
-    working-directory: invokeai/frontend/web
-
-jobs:
-  frontend-checks:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10 # expected run time: <2 min
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: check for changed frontend files
-        if: ${{ github.event_name != 'workflow_dispatch' && github.event_name != 'workflow_call' }}
-        id: changed-files
-        uses: tj-actions/changed-files@v42
-        with:
-          files_yaml: |
-            frontend:
-              - 'invokeai/frontend/web/**'
-
-      - name: install dependencies
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        uses: ./.github/actions/install-frontend-deps
-
-      - name: tsc
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: 'pnpm lint:tsc'
-        shell: bash
-
-      - name: dpdm
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: 'pnpm lint:dpdm'
-        shell: bash
-
-      - name: eslint
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: 'pnpm lint:eslint'
-        shell: bash
-
-      - name: prettier
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: 'pnpm lint:prettier'
-        shell: bash
-
-      - name: knip
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: 'pnpm lint:knip'
-        shell: bash

.github/workflows/frontend-tests.yml

@@ -1,48 +0,0 @@
-# Runs frontend tests.
-#
-# Checks for changes to frontend files before running the tests.
-# When manually triggered or called from another workflow, always runs the tests.
-
-name: 'frontend tests'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-  workflow_call:
-
-defaults:
-  run:
-    working-directory: invokeai/frontend/web
-
-jobs:
-  frontend-tests:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10 # expected run time: <2 min
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: check for changed frontend files
-        if: ${{ github.event_name != 'workflow_dispatch' && github.event_name != 'workflow_call' }}
-        id: changed-files
-        uses: tj-actions/changed-files@v42
-        with:
-          files_yaml: |
-            frontend:
-              - 'invokeai/frontend/web/**'
-
-      - name: install dependencies
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        uses: ./.github/actions/install-frontend-deps
-
-      - name: vitest
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: 'pnpm test:no-watch'
-        shell: bash

.github/workflows/label-pr.yml

@@ -1,18 +0,0 @@
-name: 'label PRs'
-on:
-  - pull_request_target
-
-jobs:
-  labeler:
-    permissions:
-      contents: read
-      pull-requests: write
-    runs-on: ubuntu-latest
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-
-      - name: label PRs
-        uses: actions/labeler@v5
-        with:
-          configuration-path: .github/pr_labels.yml

.github/workflows/lint-frontend.yml

@@ -0,0 +1,37 @@
+name: Lint frontend
+
+on:
+  pull_request:
+    paths:
+      - 'invokeai/frontend/web/**'
+    types:
+      - 'ready_for_review'
+      - 'opened'
+      - 'synchronize'
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'invokeai/frontend/web/**'
+  merge_group:
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: invokeai/frontend/web
+
+jobs:
+  lint-frontend:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Setup Node 18
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - uses: actions/checkout@v3
+      - run: 'yarn install --frozen-lockfile'
+      - run: 'yarn run lint:tsc'
+      - run: 'yarn run lint:madge'
+      - run: 'yarn run lint:eslint'
+      - run: 'yarn run lint:prettier'

.github/workflows/mkdocs-material.yml

@@ -1,49 +1,51 @@
-# This is a mostly a copy-paste from https://github.com/squidfunk/mkdocs-material/blob/master/docs/publishing-your-site.md
-
-name: mkdocs
-
+name: mkdocs-material
 on:
   push:
     branches:
-      - main
-  workflow_dispatch:
+      - 'refs/heads/v2.3'
 
 permissions:
-  contents: write
+    contents: write
 
 jobs:
-  deploy:
+  mkdocs-material:
     if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     env:
       REPO_URL: '${{ github.server_url }}/${{ github.repository }}'
       REPO_NAME: '${{ github.repository }}'
       SITE_URL: 'https://${{ github.repository_owner }}.github.io/InvokeAI'
-
     steps:
-      - name: checkout
-        uses: actions/checkout@v4
+      - name: checkout sources
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: setup python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v4
         with:
           python-version: '3.10'
           cache: pip
           cache-dependency-path: pyproject.toml
 
-      - name: set cache id
-        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - name: install requirements
+        env:
+          PIP_USE_PEP517: 1
+        run: |
+          python -m \
+            pip install ".[docs]"
 
-      - name: use cache
-        uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
+      - name: confirm buildability
+        run: |
+          python -m \
+            mkdocs build \
+            --clean \
+            --verbose
 
-      - name: install dependencies
-        run: python -m pip install ".[docs]"
-
-      - name: build & deploy
-        run: mkdocs gh-deploy --force
+      - name: deploy to gh-pages
+        if: ${{ github.ref == 'refs/heads/v2.3' }}
+        run: |
+          python -m \
+            mkdocs gh-deploy \
+            --clean \
+            --force

.github/workflows/pyflakes.yml

@@ -0,0 +1,20 @@
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - development
+      - 'release-candidate-*'
+
+jobs:
+  pyflakes:
+    name: runner / pyflakes
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: pyflakes
+        uses: reviewdog/action-pyflakes@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-review

.github/workflows/pypi-release.yml

@@ -0,0 +1,41 @@
+name: PyPI Release
+
+on:
+  push:
+    paths:
+      - 'invokeai/version/invokeai_version.py'
+  workflow_dispatch:
+
+jobs:
+  release:
+    if: github.repository == 'invoke-ai/InvokeAI'
+    runs-on: ubuntu-22.04
+    env:
+      TWINE_USERNAME: __token__
+      TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      TWINE_NON_INTERACTIVE: 1
+    steps:
+      - name: checkout sources
+        uses: actions/checkout@v3
+
+      - name: install deps
+        run: pip install --upgrade build twine
+
+      - name: build package
+        run: python3 -m build
+
+      - name: check distribution
+        run: twine check dist/*
+
+      - name: check PyPI versions
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/v2.3'
+        run: |
+          pip install --upgrade requests
+          python -c "\
+          import scripts.pypi_helper; \
+          EXISTS=scripts.pypi_helper.local_on_pypi(); \
+          print(f'PACKAGE_EXISTS={EXISTS}')" >> $GITHUB_ENV
+
+      - name: upload package
+        if: env.PACKAGE_EXISTS == 'False' && env.TWINE_PASSWORD != ''
+        run: twine upload dist/*

.github/workflows/python-checks.yml

@@ -1,64 +0,0 @@
-# Runs python code quality checks.
-#
-# Checks for changes to python files before running the checks.
-# When manually triggered or called from another workflow, always runs the tests.
-#
-# TODO: Add mypy or pyright to the checks.
-
-name: 'python checks'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-  workflow_call:
-
-jobs:
-  python-checks:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5 # expected run time: <1 min
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-
-      - name: check for changed python files
-        if: ${{ github.event_name != 'workflow_dispatch' && github.event_name != 'workflow_call' }}
-        id: changed-files
-        uses: tj-actions/changed-files@v42
-        with:
-          files_yaml: |
-            python:
-              - 'pyproject.toml'
-              - 'invokeai/**'
-              - '!invokeai/frontend/web/**'
-              - 'tests/**'
-
-      - name: setup python
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-          cache: pip
-          cache-dependency-path: pyproject.toml
-
-      - name: install ruff
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: pip install ruff
-        shell: bash
-
-      - name: ruff check
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: ruff check --output-format=github .
-        shell: bash
-
-      - name: ruff format
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: ruff format --check .
-        shell: bash

.github/workflows/python-tests.yml

@@ -1,94 +0,0 @@
-# Runs python tests on a matrix of python versions and platforms.
-#
-# Checks for changes to python files before running the tests.
-# When manually triggered or called from another workflow, always runs the tests.
-
-name: 'python tests'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-  workflow_call:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  matrix:
-    strategy:
-      matrix:
-        python-version:
-          - '3.10'
-          - '3.11'
-        platform:
-          - linux-cuda-11_7
-          - linux-rocm-5_2
-          - linux-cpu
-          - macos-default
-          - windows-cpu
-        include:
-          - platform: linux-cuda-11_7
-            os: ubuntu-22.04
-            github-env: $GITHUB_ENV
-          - platform: linux-rocm-5_2
-            os: ubuntu-22.04
-            extra-index-url: 'https://download.pytorch.org/whl/rocm5.2'
-            github-env: $GITHUB_ENV
-          - platform: linux-cpu
-            os: ubuntu-22.04
-            extra-index-url: 'https://download.pytorch.org/whl/cpu'
-            github-env: $GITHUB_ENV
-          - platform: macos-default
-            os: macOS-12
-            github-env: $GITHUB_ENV
-          - platform: windows-cpu
-            os: windows-2022
-            github-env: $env:GITHUB_ENV
-    name: 'py${{ matrix.python-version }}: ${{ matrix.platform }}'
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 15 # expected run time: 2-6 min, depending on platform
-    env:
-      PIP_USE_PEP517: '1'
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-
-      - name: check for changed python files
-        if: ${{ github.event_name != 'workflow_dispatch' && github.event_name != 'workflow_call' }}
-        id: changed-files
-        uses: tj-actions/changed-files@v42
-        with:
-          files_yaml: |
-            python:
-              - 'pyproject.toml'
-              - 'invokeai/**'
-              - '!invokeai/frontend/web/**'
-              - 'tests/**'
-
-      - name: setup python
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
-          cache-dependency-path: pyproject.toml
-
-      - name: install dependencies
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        env:
-          PIP_EXTRA_INDEX_URL: ${{ matrix.extra-index-url }}
-        run: >
-          pip3 install --editable=".[test]"
-
-      - name: run pytest
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call' }}
-        run: pytest

.github/workflows/release.yml

@@ -1,96 +0,0 @@
-# Main release workflow. Triggered on tag push or manual trigger.
-#
-# - Runs all code checks and tests
-# - Verifies the app version matches the tag version.
-# - Builds the installer and build, uploading them as artifacts.
-# - Publishes to TestPyPI and PyPI. Both are conditional on the previous steps passing and require a manual approval.
-#
-# See docs/RELEASE.md for more information on the release process.
-
-name: release
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-jobs:
-  check-version:
-    runs-on: ubuntu-latest
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-
-      - name: check python version
-        uses: samuelcolvin/check-python-version@v4
-        id: check-python-version
-        with:
-          version_file_path: invokeai/version/invokeai_version.py
-
-  frontend-checks:
-    uses: ./.github/workflows/frontend-checks.yml
-
-  frontend-tests:
-    uses: ./.github/workflows/frontend-tests.yml
-
-  python-checks:
-    uses: ./.github/workflows/python-checks.yml
-
-  python-tests:
-    uses: ./.github/workflows/python-tests.yml
-
-  build:
-    uses: ./.github/workflows/build-installer.yml
-
-  publish-testpypi:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5 # expected run time: <1 min
-    needs:
-      [
-        check-version,
-        frontend-checks,
-        frontend-tests,
-        python-checks,
-        python-tests,
-        build,
-      ]
-    environment:
-      name: testpypi
-      url: https://test.pypi.org/p/invokeai
-    steps:
-      - name: download distribution from build job
-        uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-      - name: publish distribution to TestPyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          repository-url: https://test.pypi.org/legacy/
-
-  publish-pypi:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5 # expected run time: <1 min
-    needs:
-      [
-        check-version,
-        frontend-checks,
-        frontend-tests,
-        python-checks,
-        python-tests,
-        build,
-      ]
-    environment:
-      name: pypi
-      url: https://pypi.org/p/invokeai
-    steps:
-      - name: download distribution from build job
-        uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-      - name: publish distribution to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test-invoke-pip-skip.yml

@@ -0,0 +1,50 @@
+name: Test invoke.py pip
+
+# This is a dummy stand-in for the actual tests
+# we don't need to run python tests on non-Python changes
+# But PRs require passing tests to be mergeable
+
+on:
+  pull_request:
+    paths:
+      - '**'
+      - '!pyproject.toml'
+      - '!invokeai/**'
+      - '!tests/**'
+      - 'invokeai/frontend/web/**'
+  merge_group:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  matrix:
+    if: github.event.pull_request.draft == false
+    strategy:
+      matrix:
+        python-version:
+          - '3.10'
+        pytorch:
+          - linux-cuda-11_7
+          - linux-rocm-5_2
+          - linux-cpu
+          - macos-default
+          - windows-cpu
+        include:
+          - pytorch: linux-cuda-11_7
+            os: ubuntu-22.04
+          - pytorch: linux-rocm-5_2
+            os: ubuntu-22.04
+          - pytorch: linux-cpu
+            os: ubuntu-22.04
+          - pytorch: macos-default
+            os: macOS-12
+          - pytorch: windows-cpu
+            os: windows-2022
+    name: ${{ matrix.pytorch }} on ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: skip
+        run: echo "no build required"

.github/workflows/test-invoke-pip.yml

@@ -0,0 +1,123 @@
+name: Test invoke.py pip
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'pyproject.toml'
+      - 'invokeai/**'
+      - '!invokeai/frontend/web/**'
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'invokeai/**'
+      - 'tests/**'
+      - '!invokeai/frontend/web/**'
+    types:
+      - 'ready_for_review'
+      - 'opened'
+      - 'synchronize'
+  merge_group:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  matrix:
+    if: github.event.pull_request.draft == false
+    strategy:
+      matrix:
+        python-version:
+          # - '3.9'
+          - '3.10'
+        pytorch:
+          - linux-cuda-11_7
+          - linux-rocm-5_2
+          - linux-cpu
+          - macos-default
+          - windows-cpu
+        include:
+          - pytorch: linux-cuda-11_7
+            os: ubuntu-22.04
+            github-env: $GITHUB_ENV
+          - pytorch: linux-rocm-5_2
+            os: ubuntu-22.04
+            extra-index-url: 'https://download.pytorch.org/whl/rocm5.2'
+            github-env: $GITHUB_ENV
+          - pytorch: linux-cpu
+            os: ubuntu-22.04
+            extra-index-url: 'https://download.pytorch.org/whl/cpu'
+            github-env: $GITHUB_ENV
+          - pytorch: macos-default
+            os: macOS-12
+            github-env: $GITHUB_ENV
+          - pytorch: windows-cpu
+            os: windows-2022
+            github-env: $env:GITHUB_ENV
+    name: ${{ matrix.pytorch }} on ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    env:
+      PIP_USE_PEP517: '1'
+    steps:
+      - name: Checkout sources
+        id: checkout-sources
+        uses: actions/checkout@v3
+
+      - name: set test prompt to main branch validation
+        run: echo "TEST_PROMPTS=tests/validate_pr_prompt.txt" >> ${{ matrix.github-env }}
+
+      - name: setup python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: install invokeai
+        env:
+          PIP_EXTRA_INDEX_URL: ${{ matrix.extra-index-url }}
+        run: >
+          pip3 install
+          --editable=".[test]"
+
+      - name: run pytest
+        id: run-pytest
+        run: pytest
+
+      # - name: run invokeai-configure
+      #   env:
+      #     HUGGING_FACE_HUB_TOKEN: ${{ secrets.HUGGINGFACE_TOKEN }}
+      #   run: >
+      #     invokeai-configure
+      #     --yes
+      #     --default_only
+      #     --full-precision
+      #   # can't use fp16 weights without a GPU
+
+      # - name: run invokeai
+      #   id: run-invokeai
+      #   env:
+      #     # Set offline mode to make sure configure preloaded successfully.
+      #     HF_HUB_OFFLINE: 1
+      #     HF_DATASETS_OFFLINE: 1
+      #     TRANSFORMERS_OFFLINE: 1
+      #     INVOKEAI_OUTDIR: ${{ github.workspace }}/results
+      #   run: >
+      #     invokeai
+      #     --no-patchmatch
+      #     --no-nsfw_checker
+      #     --precision=float32
+      #     --always_use_cpu
+      #     --use_memory_db
+      #     --outdir ${{ env.INVOKEAI_OUTDIR }}/${{ matrix.python-version }}/${{ matrix.pytorch }}
+      #     --from_file ${{ env.TEST_PROMPTS }}
+
+      # - name: Archive results
+      #   env:
+      #     INVOKEAI_OUTDIR: ${{ github.workspace }}/results
+      #   uses: actions/upload-artifact@v3
+      #   with:
+      #     name: results
+      #     path: ${{ env.INVOKEAI_OUTDIR }}

.gitignore

@@ -1,4 +1,22 @@
+# ignore default image save location and model symbolic link
 .idea/
+embeddings/
+outputs/
+models/ldm/stable-diffusion-v1/model.ckpt
+**/restoration/codeformer/weights
+
+# ignore user models config
+configs/models.user.yaml
+config/models.user.yml
+invokeai.init
+.version
+.last_model
+
+# ignore the Anaconda/Miniconda installer used while building Docker image
+anaconda.sh
+
+# ignore a directory which serves as a place for initial images
+inputs/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -16,10 +34,11 @@ __pycache__/
 .Python
 build/
 develop-eggs/
-dist/
+# dist/
 downloads/
 eggs/
 .eggs/
+lib/
 lib64/
 parts/
 sdist/
@@ -133,10 +152,12 @@ celerybeat.pid
 
 # Environments
 .env
-.venv*
+.venv
 env/
 venv/
 ENV/
+env.bak/
+venv.bak/
 
 # Spyder project settings
 .spyderproject
@@ -169,17 +190,44 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
+src
 **/__pycache__/
+outputs
 
+# Logs and associated folders
+# created from generated embeddings.
+logs
+testtube
+checkpoints
 # If it's a Mac
 .DS_Store
 
+invokeai/frontend/yarn.lock
+invokeai/frontend/node_modules
+
 # Let the frontend manage its own gitignore
 !invokeai/frontend/web/*
 
 # Scratch folder
 .scratch/
 .vscode/
+gfpgan/
+models/ldm/stable-diffusion-v1/*.sha256
+
+
+# GFPGAN model files
+gfpgan/
+
+# config file (will be created by installer)
+configs/models.yaml
+
+# ignore initfile
+.invokeai
+
+# ignore environment.yml and requirements.txt
+# these are links to the real files in environments-and-requirements
+environment.yml
+requirements.txt
 
 # source installer files
 installer/*zip
@@ -187,4 +235,3 @@ installer/install.bat
 installer/install.sh
 installer/update.bat
 installer/update.sh
-installer/InvokeAI-Installer/

.pre-commit-config.yaml

@@ -1,24 +0,0 @@
-# See https://pre-commit.com/ for usage and config
-repos:
-- repo: local
-  hooks:
-  - id: black
-    name: black
-    stages: [commit]
-    language: system
-    entry: black
-    types: [python]
-
-  - id: flake8
-    name: flake8
-    stages: [commit]
-    language: system
-    entry: flake8
-    types: [python]
-
-  - id: isort
-    name: isort
-    stages: [commit]
-    language: system
-    entry: isort
-    types: [python]

.prettierrc.yaml

@@ -7,7 +7,7 @@ embeddedLanguageFormatting: auto
 overrides:
   - files: '*.md'
     options:
-      proseWrap: preserve
+      proseWrap: always
       printWidth: 80
       parser: markdown
       cursorOffset: -1

LICENSE-SDXL.txt

@@ -1,290 +0,0 @@
-Copyright (c) 2023 Stability AI
-CreativeML Open RAIL++-M License dated July 26, 2023
-
-Section I: PREAMBLE
-
-Multimodal generative models are being widely adopted and used, and
-have the potential to transform the way artists, among other
-individuals, conceive and benefit from AI or ML technologies as a tool
-for content creation.
-
-Notwithstanding the current and potential benefits that these
-artifacts can bring to society at large, there are also concerns about
-potential misuses of them, either due to their technical limitations
-or ethical considerations.
-
-In short, this license strives for both the open and responsible
-downstream use of the accompanying model. When it comes to the open
-character, we took inspiration from open source permissive licenses
-regarding the grant of IP rights. Referring to the downstream
-responsible use, we added use-based restrictions not permitting the
-use of the model in very specific scenarios, in order for the licensor
-to be able to enforce the license in case potential misuses of the
-Model may occur. At the same time, we strive to promote open and
-responsible research on generative models for art and content
-generation.
-
-Even though downstream derivative versions of the model could be
-released under different licensing terms, the latter will always have
-to include - at minimum - the same use-based restrictions as the ones
-in the original license (this license). We believe in the intersection
-between open and responsible AI development; thus, this agreement aims
-to strike a balance between both in order to enable responsible
-open-science in the field of AI.
-
-This CreativeML Open RAIL++-M License governs the use of the model
-(and its derivatives) and is informed by the model card associated
-with the model.
-
-NOW THEREFORE, You and Licensor agree as follows:
-
-Definitions
-
-"License" means the terms and conditions for use, reproduction, and
-Distribution as defined in this document.
-
-"Data" means a collection of information and/or content extracted from
-the dataset used with the Model, including to train, pretrain, or
-otherwise evaluate the Model. The Data is not licensed under this
-License.
-
-"Output" means the results of operating a Model as embodied in
-informational content resulting therefrom.
-
-"Model" means any accompanying machine-learning based assemblies
-(including checkpoints), consisting of learnt weights, parameters
-(including optimizer states), corresponding to the model architecture
-as embodied in the Complementary Material, that have been trained or
-tuned, in whole or in part on the Data, using the Complementary
-Material.
-
-"Derivatives of the Model" means all modifications to the Model, works
-based on the Model, or any other model which is created or initialized
-by transfer of patterns of the weights, parameters, activations or
-output of the Model, to the other model, in order to cause the other
-model to perform similarly to the Model, including - but not limited
-to - distillation methods entailing the use of intermediate data
-representations or methods based on the generation of synthetic data
-by the Model for training the other model.
-
-"Complementary Material" means the accompanying source code and
-scripts used to define, run, load, benchmark or evaluate the Model,
-and used to prepare data for training or evaluation, if any. This
-includes any accompanying documentation, tutorials, examples, etc, if
-any.
-
-"Distribution" means any transmission, reproduction, publication or
-other sharing of the Model or Derivatives of the Model to a third
-party, including providing the Model as a hosted service made
-available by electronic or other remote means - e.g. API-based or web
-access.
-
-"Licensor" means the copyright owner or entity authorized by the
-copyright owner that is granting the License, including the persons or
-entities that may have rights in the Model and/or distributing the
-Model.
-
-"You" (or "Your") means an individual or Legal Entity exercising
-permissions granted by this License and/or making use of the Model for
-whichever purpose and in any field of use, including usage of the
-Model in an end-use application - e.g. chatbot, translator, image
-generator.
-
-"Third Parties" means individuals or legal entities that are not under
-common control with Licensor or You.
-
-"Contribution" means any work of authorship, including the original
-version of the Model and any modifications or additions to that Model
-or Derivatives of the Model thereof, that is intentionally submitted
-to Licensor for inclusion in the Model by the copyright owner or by an
-individual or Legal Entity authorized to submit on behalf of the
-copyright owner. For the purposes of this definition, "submitted"
-means any form of electronic, verbal, or written communication sent to
-the Licensor or its representatives, including but not limited to
-communication on electronic mailing lists, source code control
-systems, and issue tracking systems that are managed by, or on behalf
-of, the Licensor for the purpose of discussing and improving the
-Model, but excluding communication that is conspicuously marked or
-otherwise designated in writing by the copyright owner as "Not a
-Contribution."
-
-"Contributor" means Licensor and any individual or Legal Entity on
-behalf of whom a Contribution has been received by Licensor and
-subsequently incorporated within the Model.
-
-Section II: INTELLECTUAL PROPERTY RIGHTS
-
-Both copyright and patent grants apply to the Model, Derivatives of
-the Model and Complementary Material. The Model and Derivatives of the
-Model are subject to additional terms as described in
-
-Section III.
-
-Grant of Copyright License. Subject to the terms and conditions of
-this License, each Contributor hereby grants to You a perpetual,
-worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-copyright license to reproduce, prepare, publicly display, publicly
-perform, sublicense, and distribute the Complementary Material, the
-Model, and Derivatives of the Model.
-
-Grant of Patent License. Subject to the terms and conditions of this
-License and where and as applicable, each Contributor hereby grants to
-You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
-irrevocable (except as stated in this paragraph) patent license to
-make, have made, use, offer to sell, sell, import, and otherwise
-transfer the Model and the Complementary Material, where such license
-applies only to those patent claims licensable by such Contributor
-that are necessarily infringed by their Contribution(s) alone or by
-combination of their Contribution(s) with the Model to which such
-Contribution(s) was submitted. If You institute patent litigation
-against any entity (including a cross-claim or counterclaim in a
-lawsuit) alleging that the Model and/or Complementary Material or a
-Contribution incorporated within the Model and/or Complementary
-Material constitutes direct or contributory patent infringement, then
-any patent licenses granted to You under this License for the Model
-and/or Work shall terminate as of the date such litigation is asserted
-or filed.
-
-Section III: CONDITIONS OF USAGE, DISTRIBUTION AND REDISTRIBUTION
-
-Distribution and Redistribution. You may host for Third Party remote
-access purposes (e.g. software-as-a-service), reproduce and distribute
-copies of the Model or Derivatives of the Model thereof in any medium,
-with or without modifications, provided that You meet the following
-conditions: Use-based restrictions as referenced in paragraph 5 MUST
-be included as an enforceable provision by You in any type of legal
-agreement (e.g. a license) governing the use and/or distribution of
-the Model or Derivatives of the Model, and You shall give notice to
-subsequent users You Distribute to, that the Model or Derivatives of
-the Model are subject to paragraph 5. This provision does not apply to
-the use of Complementary Material. You must give any Third Party
-recipients of the Model or Derivatives of the Model a copy of this
-License; You must cause any modified files to carry prominent notices
-stating that You changed the files; You must retain all copyright,
-patent, trademark, and attribution notices excluding those notices
-that do not pertain to any part of the Model, Derivatives of the
-Model. You may add Your own copyright statement to Your modifications
-and may provide additional or different license terms and conditions -
-respecting paragraph 4.a. - for use, reproduction, or Distribution of
-Your modifications, or for any such Derivatives of the Model as a
-whole, provided Your use, reproduction, and Distribution of the Model
-otherwise complies with the conditions stated in this License.
-
-Use-based restrictions. The restrictions set forth in Attachment A are
-considered Use-based restrictions. Therefore You cannot use the Model
-and the Derivatives of the Model for the specified restricted
-uses. You may use the Model subject to this License, including only
-for lawful purposes and in accordance with the License. Use may
-include creating any content with, finetuning, updating, running,
-training, evaluating and/or reparametrizing the Model. You shall
-require all of Your users who use the Model or a Derivative of the
-Model to comply with the terms of this paragraph (paragraph 5).
-
-The Output You Generate.  Except as set forth herein, Licensor claims
-no rights in the Output You generate using the Model. You are
-accountable for the Output you generate and its subsequent uses. No
-use of the output can contravene any provision as stated in the
-License.
-
-Section IV: OTHER PROVISIONS
-
-Updates and Runtime Restrictions. To the maximum extent permitted by
-law, Licensor reserves the right to restrict (remotely or otherwise)
-usage of the Model in violation of this License.
-
-Trademarks and related. Nothing in this License permits You to make
-use of Licensors’ trademarks, trade names, logos or to otherwise
-suggest endorsement or misrepresent the relationship between the
-parties; and any rights not expressly granted herein are reserved by
-the Licensors.
-
-Disclaimer of Warranty. Unless required by applicable law or agreed to
-in writing, Licensor provides the Model and the Complementary Material
-(and each Contributor provides its Contributions) on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-implied, including, without limitation, any warranties or conditions
-of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-PARTICULAR PURPOSE. You are solely responsible for determining the
-appropriateness of using or redistributing the Model, Derivatives of
-the Model, and the Complementary Material and assume any risks
-associated with Your exercise of permissions under this License.
-
-Limitation of Liability. In no event and under no legal theory,
-whether in tort (including negligence), contract, or otherwise, unless
-required by applicable law (such as deliberate and grossly negligent
-acts) or agreed to in writing, shall any Contributor be liable to You
-for damages, including any direct, indirect, special, incidental, or
-consequential damages of any character arising as a result of this
-License or out of the use or inability to use the Model and the
-Complementary Material (including but not limited to damages for loss
-of goodwill, work stoppage, computer failure or malfunction, or any
-and all other commercial damages or losses), even if such Contributor
-has been advised of the possibility of such damages.
-
-Accepting Warranty or Additional Liability. While redistributing the
-Model, Derivatives of the Model and the Complementary Material
-thereof, You may choose to offer, and charge a fee for, acceptance of
-support, warranty, indemnity, or other liability obligations and/or
-rights consistent with this License. However, in accepting such
-obligations, You may act only on Your own behalf and on Your sole
-responsibility, not on behalf of any other Contributor, and only if
-You agree to indemnify, defend, and hold each Contributor harmless for
-any liability incurred by, or claims asserted against, such
-Contributor by reason of your accepting any such warranty or
-additional liability.
-
-If any provision of this License is held to be invalid, illegal or
-unenforceable, the remaining provisions shall be unaffected thereby
-and remain valid as if such provision had not been set forth herein.
-
-
-END OF TERMS AND CONDITIONS
-
-Attachment A
-
-Use Restrictions
-
-You agree not to use the Model or Derivatives of the Model:
-
-* In any way that violates any applicable national, federal, state,
-local or international law or regulation;
-
-* For the purpose of exploiting, harming or attempting to exploit or
-harm minors in any way;
-
-* To generate or disseminate verifiably false information and/or
-  content with the purpose of harming others;
-
-* To generate or disseminate personal identifiable information that
-  can be used to harm an individual;
-
-* To defame, disparage or otherwise harass others;
-
-* For fully automated decision making that adversely impacts an
-  individual’s legal rights or otherwise creates or modifies a
-  binding, enforceable obligation;
-
-* For any use intended to or which has the effect of discriminating
-  against or harming individuals or groups based on online or offline
-  social behavior or known or predicted personal or personality
-  characteristics;
-
-* To exploit any of the vulnerabilities of a specific group of persons
-  based on their age, social, physical or mental characteristics, in
-  order to materially distort the behavior of a person pertaining to
-  that group in a manner that causes or is likely to cause that person
-  or another person physical or psychological harm;
-
-* For any use intended to or which has the effect of discriminating
-  against individuals or groups based on legally protected
-  characteristics or categories;
-
-* To provide medical advice and medical results interpretation;
-
-* To generate or disseminate information for the purpose to be used
-  for administration of justice, law enforcement, immigration or
-  asylum processes, such as predicting an individual will commit
-  fraud/crime commitment (e.g. by text profiling, drawing causal
-  relationships between assertions made in documents, indiscriminate
-  and arbitrarily-targeted use).
-

Makefile

@@ -1,63 +0,0 @@
-# simple Makefile with scripts that are otherwise hard to remember
-# to use, run from the repo root `make <command>`
-
-default: help
-
-help:
-	@echo Developer commands:
-	@echo
-	@echo "ruff              Run ruff, fixing any safely-fixable errors and formatting"
-	@echo "ruff-unsafe       Run ruff, fixing all fixable errors and formatting"
-	@echo "mypy              Run mypy using the config in pyproject.toml to identify type mismatches and other coding errors"
-	@echo "mypy-all          Run mypy ignoring the config in pyproject.tom but still ignoring missing imports"
-	@echo "test"             Run the unit tests.
-	@echo "frontend-install" Install the pnpm modules needed for the front end
-	@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 "installer-zip     Build the installer .zip file for the current version"
-	@echo "tag-release       Tag the GitHub repository with the current version (use at release time only!)"
-
-# Runs ruff, fixing any safely-fixable errors and formatting
-ruff:
-	ruff check . --fix
-	ruff format .
-
-# Runs ruff, fixing all errors it can fix and formatting
-ruff-unsafe:
-	ruff check . --fix --unsafe-fixes
-	ruff format .
-
-# Runs mypy, using the config in pyproject.toml
-mypy:
-	mypy scripts/invokeai-web.py
-
-# Runs mypy, ignoring the config in pyproject.toml but still ignoring missing (untyped) imports
-# (many files are ignored by the config, so this is useful for checking all files)
-mypy-all:
-	mypy scripts/invokeai-web.py --config-file= --ignore-missing-imports
-
-# Run the unit tests
-test:
-	pytest ./tests
-
-# Install the pnpm modules needed for the front end
-frontend-install:
-	rm -rf invokeai/frontend/web/node_modules
-	cd invokeai/frontend/web && pnpm install
-
-# Build the frontend
-frontend-build:
-	cd invokeai/frontend/web && pnpm build
-
-# Run the frontend in dev mode
-frontend-dev:
-	cd invokeai/frontend/web && pnpm dev
-
-# Installer zip file
-installer-zip:
-	cd installer && ./create_installer.sh
-
-# Tag the release
-tag-release:
-	cd installer && ./tag_release.sh
-

README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-![project hero](https://github.com/invoke-ai/InvokeAI/assets/31807370/6e3728c7-e90e-4711-905c-3b55844ff5be)
+![project hero](https://github.com/invoke-ai/InvokeAI/assets/31807370/1a917d94-e099-4fa1-a70f-7dd8d0691018)
 
-# Invoke - Professional Creative AI Tools for Visual Media 
-##  To learn more about Invoke, or implement our Business solutions, visit [invoke.com](https://www.invoke.com/about)
-  
+# Invoke AI - Generative AI for Professional Creatives
+## Professional Creative Tools for Stable Diffusion, Custom-Trained Models, and more. 
+  To learn more about Invoke AI, get started instantly, or implement our Business solutions, visit [invoke.ai](https://invoke.ai)
 
 
 [![discord badge]][discord link]
@@ -36,6 +36,15 @@
 
 </div>
 
+_**Note: This is an alpha release. Bugs are expected and not all
+features are fully implemented. Please use the GitHub [Issues
+pages](https://github.com/invoke-ai/InvokeAI/issues?q=is%3Aissue+is%3Aopen)
+to report unexpected problems. Also note that InvokeAI root directory
+which contains models, outputs and configuration files, has changed
+between the 2.x and 3.x release. If you wish to use your v2.3 root
+directory with v3.0, please follow the directions in [Migrating a 2.3
+root directory to 3.0](#migrating-to-3).**_
+
 InvokeAI is a leading creative engine built to empower professionals
 and enthusiasts alike. Generate and create stunning visual media using
 the latest AI-driven technologies. InvokeAI offers an industry leading
@@ -43,22 +52,20 @@ Web Interface, interactive Command Line Interface, and also serves as
 the foundation for multiple commercial products.
 
 **Quick links**: [[How to
-  Install](https://invoke-ai.github.io/InvokeAI/installation/INSTALLATION/)] [<a
+  Install](https://invoke-ai.github.io/InvokeAI/#installation)] [<a
   href="https://discord.gg/ZmtBAhwWhy">Discord Server</a>] [<a
   href="https://invoke-ai.github.io/InvokeAI/">Documentation and
-  Tutorials</a>]
-  [<a href="https://github.com/invoke-ai/InvokeAI/issues">Bug Reports</a>]
+  Tutorials</a>] [<a
+  href="https://github.com/invoke-ai/InvokeAI/">Code and
+  Downloads</a>] [<a
+  href="https://github.com/invoke-ai/InvokeAI/issues">Bug Reports</a>]
   [<a
   href="https://github.com/invoke-ai/InvokeAI/discussions">Discussion,
-  Ideas & Q&A</a>] 
-   [<a
-  href="https://invoke-ai.github.io/InvokeAI/contributing/CONTRIBUTING/">Contributing</a>] 
+  Ideas & Q&A</a>]
 
 <div align="center">
 
-
-![Highlighted Features - Canvas and Workflows](https://github.com/invoke-ai/InvokeAI/assets/31807370/708f7a82-084f-4860-bfbe-e2588c53548d)
-
+![canvas preview](https://github.com/invoke-ai/InvokeAI/raw/main/docs/assets/canvas_preview.png)
 
 </div>
 
@@ -83,7 +90,7 @@ Table of Contents 📝
 ## Quick Start
 
 For full installation and upgrade instructions, please see:
-[InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/INSTALLATION/)
+[InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/)
 
 If upgrading from version 2.3, please read [Migrating a 2.3 root
 directory to 3.0](#migrating-to-3) first.
@@ -125,10 +132,10 @@ and go to http://localhost:9090.
 
 ### Command-Line Installation (for developers and users familiar with Terminals)
 
-You must have Python 3.10 through 3.11 installed on your machine. Earlier or
+You must have Python 3.9 or 3.10 installed on your machine. Earlier or
 later versions are not supported.
-Node.js also needs to be installed along with `pnpm` (can be installed with
-the command `npm install -g pnpm` if needed)
+Node.js also needs to be installed along with yarn (can be installed with
+the command `npm install -g yarn` if needed)
 
 1. Open a command-line window on your machine. The PowerShell is recommended for Windows.
 2. Create a directory to install InvokeAI into. You'll need at least 15 GB of free space:
@@ -163,13 +170,13 @@ the command `npm install -g pnpm` if needed)
     _For Windows/Linux with an NVIDIA GPU:_
 
     ```terminal
-    pip install "InvokeAI[xformers]" --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu121
+    pip install "InvokeAI[xformers]" --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117
     ```
 
     _For Linux with an AMD GPU:_
 
     ```sh
-    pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.6
+    pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.4.2
     ```
 
     _For non-GPU systems:_
@@ -177,7 +184,7 @@ the command `npm install -g pnpm` if needed)
     pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/cpu
     ``` 
 
-    _For Macintoshes, either Intel or M1/M2/M3:_
+    _For Macintoshes, either Intel or M1/M2:_
 
     ```sh
     pip install InvokeAI --use-pep517
@@ -186,9 +193,8 @@ the command `npm install -g pnpm` if needed)
 6. Configure InvokeAI and install a starting set of image generation models (you only need to do this once):
 
     ```terminal
-    invokeai-configure --root .
+    invokeai-configure
     ```
-	Don't miss the dot at the end!
 
 7. Launch the web server (do it every time you run InvokeAI):
 
@@ -196,9 +202,15 @@ the command `npm install -g pnpm` if needed)
     invokeai-web
     ```
 
-8. Point your browser to http://localhost:9090 to bring up the web interface.
+8. Build Node.js assets
 
-9. Type `banana sushi` in the box on the top left and click `Invoke`.
+  ```terminal
+  cd invokeai/frontend/web/
+  yarn vite build
+  ```
+
+9. Point your browser to http://localhost:9090 to bring up the web interface.
+10. Type `banana sushi` in the box on the top left and click `Invoke`.
 
 Be sure to activate the virtual environment each time before re-launching InvokeAI,
 using `source .venv/bin/activate` or `.venv\Scripts\activate`.
@@ -252,27 +264,22 @@ old models directory (which contains the models selected at install
 time) will be renamed `models.orig` and can be deleted once you have
 confirmed that the migration was successful.
 
- If you wish, you can pass the 2.3 root directory to both `--from` and
-`--to` in order to update in place. Warning: this directory will no
-longer be usable with InvokeAI 2.3.
-
 #### Migrating in place
 
 For the adventurous, you may do an in-place upgrade from 2.3 to 3.0
-without touching the command line. ***This recipe does not work on
-Windows platforms due to a bug in the Windows version of the 2.3
-upgrade script.** See the next section for a Windows recipe.
-
-##### For Mac and Linux Users:
+without touching the command line. The recipe is as follows>
 
 1. Launch the InvokeAI launcher script in your current v2.3 root directory.
 
 2. Select option [9] "Update InvokeAI" to bring up the updater dialog.
 
-3. Select option [1] to upgrade to the latest release.
+3a. During the alpha release phase, select option [3] and manually
+enter the tag name `v3.0.0+a2`.
+
+3b. Once 3.0 is released, select option [1] to upgrade to the latest release.
 
 4. Once the upgrade is finished you will be returned to the launcher
-menu. Select option [6] "Re-run the configure script to fix a broken
+menu. Select option [7] "Re-run the configure script to fix a broken
 install or to complete a major upgrade".
 
 This will run the configure script against the v2.3 directory and
@@ -288,50 +295,14 @@ worked, you can safely remove these files. Alternatively you can
 restore a working v2.3 directory by removing the new files and
 restoring the ".orig" files' original names.
 
-##### For Windows Users:
-
-Windows Users can upgrade with the
-
-1. Enter the 2.3 root directory you wish to upgrade
-2. Launch `invoke.sh` or `invoke.bat`
-3. Select the "Developer's console" option [8]
-4. Type the following commands
-
-```
-pip install "invokeai @ https://github.com/invoke-ai/InvokeAI/archive/refs/tags/v3.0.0" --use-pep517 --upgrade
-invokeai-configure --root .
-```
-(Replace `v3.0.0` with the current release number if this document is out of date).
-
-The first command will install and upgrade new software to run
-InvokeAI. The second will prepare the 2.3 directory for use with 3.0.
-You may now launch the WebUI in the usual way, by selecting option [1]
-from the launcher script
-
-#### Migrating Images
+#### Migration Caveats
 
 The migration script will migrate your invokeai settings and models,
 including textual inversion models, LoRAs and merges that you may have
 installed previously. However it does **not** migrate the generated
-images stored in your 2.3-format outputs directory. To do this, you 
-need to run an additional step:
-
-1. From a working InvokeAI 3.0 root directory, start the launcher and
-enter menu option [8] to open the "developer's console".
-
-2. At the developer's console command line, type the command:
-
-```bash
-invokeai-import-images
-```
-
-3. This will lead you through the process of confirming the desired
-   source and destination for the imported images. The images will
-   appear in the gallery board of your choice, and contain the
-   original prompt, model name, and other parameters used to generate
-   the image.
-   
-(Many kudos to **techjedi** for contributing this script.)
+images stored in your 2.3-format outputs directory. The released
+version of 3.0 is expected to have an interface for importing an
+entire directory of image files as a batch.
 
 ## Hardware Requirements
 
@@ -343,12 +314,9 @@ AMD card (using the ROCm driver).
 
 You will need one of the following:
 
-- An NVIDIA-based graphics card with 4 GB or more VRAM memory. 6-8 GB
-  of VRAM is highly recommended for rendering using the Stable
-  Diffusion XL models
+- An NVIDIA-based graphics card with 4 GB or more VRAM memory.
 - An Apple computer with an M1 chip.
-- An AMD-based graphics card with 4GB or more VRAM memory (Linux
-  only), 6-8 GB for XL rendering.
+- An AMD-based graphics card with 4GB or more VRAM memory. (Linux only)
 
 We do not recommend the GTX 1650 or 1660 series video cards. They are
 unable to run in half-precision mode and do not have sufficient VRAM
@@ -370,9 +338,9 @@ InvokeAI offers a locally hosted Web Server & React Frontend, with an industry l
 
 The Unified Canvas is a fully integrated canvas implementation with support for all core generation capabilities, in/outpainting, brush tools, and more. This creative tool unlocks the capability for artists to create with AI as a creative collaborator, and can be used to augment AI-generated imagery, sketches, photography, renders, and more.
 
-### *Workflows & Nodes*
+### *Node Architecture & Editor (Beta)*
 
-InvokeAI offers a fully featured workflow management solution, enabling users to combine the power of nodes 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 AI's backend is built on a graph-based execution architecture. This allows for customizable generation pipelines to be developed by professional users looking to create specific workflows to support their production use-cases, and will be extended in the future with additional capabilities.
 
 ### *Board & Gallery Management*
 
@@ -381,13 +349,13 @@ Invoke AI provides an organized gallery system for easily storing, accessing, an
 ### Other features
 
 - *Support for both ckpt and diffusers models*
-- *SD 2.0, 2.1, XL support*
+- *SD 2.0, 2.1 support*
 - *Upscaling Tools*
 - *Embedding Manager & Support*
 - *Model Manager & Support*
-- *Workflow creation & management*
 - *Node-Based Architecture*
-
+- *Node-Based Plug-&-Play UI (Beta)*
+- *SDXL Support* (Coming soon)
 
 ### Latest Changes
 
@@ -397,19 +365,21 @@ Notes](https://github.com/invoke-ai/InvokeAI/releases) and the
 
 ### Troubleshooting
 
-Please check out our **[Troubleshooting Guide](https://invoke-ai.github.io/InvokeAI/installation/010_INSTALL_AUTOMATED/#troubleshooting)** to get solutions for common installation
-problems and other issues. For more help, please join our [Discord][discord link]
+Please check out our **[Q&A](https://invoke-ai.github.io/InvokeAI/help/TROUBLESHOOT/#faq)** to get solutions for common installation
+problems and other issues.
 
 ## Contributing
 
 Anyone who wishes to contribute to this project, whether documentation, features, bug fixes, code
 cleanup, testing, or code reviews, is very much encouraged to do so.
 
-Get started with contributing by reading our [Contribution documentation](https://invoke-ai.github.io/InvokeAI/contributing/CONTRIBUTING/), joining the [#dev-chat](https://discord.com/channels/1020123559063990373/1049495067846524939) or the GitHub discussion board.
+To join, just raise your hand on the InvokeAI Discord server (#dev-chat) or the GitHub discussion board.
+
+If you'd like to help with translation, please see our [translation guide](docs/other/TRANSLATION.md).
 
 If you are unfamiliar with how
-to contribute to GitHub projects, we have a new contributor checklist you can follow to get started contributing: 
-[New Contributor Checklist](https://invoke-ai.github.io/InvokeAI/contributing/contribution_guides/newContributorChecklist/).
+to contribute to GitHub projects, here is a
+[Getting Started Guide](https://opensource.com/article/19/7/create-pull-request-github). A full set of contribution guidelines, along with templates, are in progress. You can **make your pull request against the "main" branch**.
 
 We hope you enjoy using our software as much as we enjoy creating it,
 and we hope that some of those of you who are reading this will elect
@@ -425,7 +395,7 @@ their time, hard work and effort.
 
 ### Support
 
-For support, please use this repository's GitHub Issues tracking service, or join the [Discord][discord link].
+For support, please use this repository's GitHub Issues tracking service, or join the Discord.
 
 Original portions of the software are Copyright (c) 2023 by respective contributors.
 

docker/.env.sample

@@ -1,18 +1,13 @@
 ## Make a copy of this file named `.env` and fill in the values below.
-## Any environment variables supported by InvokeAI can be specified here,
-## in addition to the examples below.
+## Any environment variables supported by InvokeAI can be specified here.
 
-# HOST_INVOKEAI_ROOT is the path on the docker host's filesystem where InvokeAI will store data.
+# INVOKEAI_ROOT is the path to a path on the local filesystem where InvokeAI will store data.
 # Outputs will also be stored here by default.
-# If relative, it will be relative to the docker directory in which the docker-compose.yml file is located
-#HOST_INVOKEAI_ROOT=../../invokeai-data
+# This **must** be an absolute path.
+INVOKEAI_ROOT=
 
-# INVOKEAI_ROOT is the path to the root of the InvokeAI repository within the container.
-# INVOKEAI_ROOT=~/invokeai
+HUGGINGFACE_TOKEN=
 
-# Get this value from your HuggingFace account settings page.
-# HUGGING_FACE_HUB_TOKEN=
-
-## optional variables specific to the docker setup.
-# GPU_DRIVER=nvidia #| rocm
-# CONTAINER_UID=1000
+## optional variables specific to the docker setup
+# GPU_DRIVER=cuda
+# CONTAINER_UID=1000

docker/Dockerfile

@@ -2,7 +2,7 @@
 
 ## Builder stage
 
-FROM library/ubuntu:23.04 AS builder
+FROM library/ubuntu:22.04 AS builder
 
 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
@@ -10,7 +10,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     --mount=type=cache,target=/var/lib/apt,sharing=locked \
     apt update && apt-get install -y \
         git \
-        python3-venv \
+        python3.10-venv \
         python3-pip \
         build-essential
 
@@ -18,8 +18,8 @@ ENV INVOKEAI_SRC=/opt/invokeai
 ENV VIRTUAL_ENV=/opt/venv/invokeai
 
 ENV PATH="$VIRTUAL_ENV/bin:$PATH"
-ARG TORCH_VERSION=2.1.2
-ARG TORCHVISION_VERSION=0.16.2
+ARG TORCH_VERSION=2.0.1
+ARG TORCHVISION_VERSION=0.15.2
 ARG GPU_DRIVER=cuda
 ARG TARGETPLATFORM="linux/amd64"
 # unused but available
@@ -35,9 +35,9 @@ RUN --mount=type=cache,target=/root/.cache/pip \
     if [ "$TARGETPLATFORM" = "linux/arm64" ] || [ "$GPU_DRIVER" = "cpu" ]; then \
         extra_index_url_arg="--extra-index-url https://download.pytorch.org/whl/cpu"; \
     elif [ "$GPU_DRIVER" = "rocm" ]; then \
-        extra_index_url_arg="--extra-index-url https://download.pytorch.org/whl/rocm5.6"; \
+        extra_index_url_arg="--extra-index-url https://download.pytorch.org/whl/rocm5.4.2"; \
     else \
-        extra_index_url_arg="--extra-index-url https://download.pytorch.org/whl/cu121"; \
+        extra_index_url_arg="--extra-index-url https://download.pytorch.org/whl/cu118"; \
     fi &&\
     pip install $extra_index_url_arg \
         torch==$TORCH_VERSION \
@@ -54,25 +54,23 @@ RUN --mount=type=cache,target=/root/.cache/pip \
     if [ "$GPU_DRIVER" = "cuda" ] && [ "$TARGETPLATFORM" = "linux/amd64" ]; then \
         pip install -e ".[xformers]"; \
     else \
-        pip install $extra_index_url_arg -e "."; \
+        pip install -e "."; \
     fi
 
 # #### Build the Web UI ------------------------------------
 
-FROM node:20-slim AS web-builder
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-
+FROM node:18 AS web-builder
 WORKDIR /build
 COPY invokeai/frontend/web/ ./
-RUN --mount=type=cache,target=/pnpm/store \
-    pnpm install --frozen-lockfile
-RUN npx vite build
+RUN --mount=type=cache,target=/usr/lib/node_modules \
+    npm install --include dev
+RUN --mount=type=cache,target=/usr/lib/node_modules \
+    yarn vite build
+
 
 #### Runtime stage ---------------------------------------
 
-FROM library/ubuntu:23.04 AS runtime
+FROM library/ubuntu:22.04 AS runtime
 
 ARG DEBIAN_FRONTEND=noninteractive
 ENV PYTHONUNBUFFERED=1
@@ -87,7 +85,6 @@ RUN apt update && apt install -y --no-install-recommends \
         iotop \
         bzip2 \
         gosu \
-        magic-wormhole \
         libglib2.0-0 \
         libgl1-mesa-glx \
         python3-venv \
@@ -97,13 +94,15 @@ RUN apt update && apt install -y --no-install-recommends \
         libstdc++-10-dev &&\
     apt-get clean && apt-get autoclean
 
+# globally add magic-wormhole
+# for ease of transferring data to and from the container
+# when running in sandboxed cloud environments; e.g. Runpod etc.
+RUN pip install magic-wormhole
 
 ENV INVOKEAI_SRC=/opt/invokeai
 ENV VIRTUAL_ENV=/opt/venv/invokeai
 ENV INVOKEAI_ROOT=/invokeai
 ENV PATH="$VIRTUAL_ENV/bin:$INVOKEAI_SRC:$PATH"
-ENV CONTAINER_UID=${CONTAINER_UID:-1000}
-ENV CONTAINER_GID=${CONTAINER_GID:-1000}
 
 # --link requires buldkit w/ dockerfile syntax 1.4
 COPY --link --from=builder ${INVOKEAI_SRC} ${INVOKEAI_SRC}
@@ -121,7 +120,9 @@ WORKDIR ${INVOKEAI_SRC}
 RUN cd /usr/lib/$(uname -p)-linux-gnu/pkgconfig/ && ln -sf opencv4.pc opencv.pc
 RUN python3 -c "from patchmatch import patch_match"
 
-RUN mkdir -p ${INVOKEAI_ROOT} && chown -R ${CONTAINER_UID}:${CONTAINER_GID} ${INVOKEAI_ROOT}
+# Create unprivileged user and make the local dir
+RUN useradd --create-home --shell /bin/bash -u 1000 --comment "container local user" invoke
+RUN mkdir -p ${INVOKEAI_ROOT} && chown -R invoke:invoke ${INVOKEAI_ROOT}
 
 COPY docker/docker-entrypoint.sh ./
 ENTRYPOINT ["/opt/invokeai/docker-entrypoint.sh"]

docker/README.md

@@ -1,19 +1,11 @@
 # InvokeAI Containerized
 
-All commands should be run within the `docker` directory: `cd docker`
-
-## Quickstart :rocket:
-
-On a known working Linux+Docker+CUDA (Nvidia) system, execute `./run.sh` in this directory. It will take a few minutes - depending on your internet speed - to install the core models. Once the application starts up, open `http://localhost:9090` in your browser to Invoke!
-
-For more configuration options (using an AMD GPU, custom root directory location, etc): read on.
-
-## Detailed setup
+All commands are to be run from the `docker` directory: `cd docker`
 
 #### Linux
 
 1. Ensure builkit is enabled in the Docker daemon settings (`/etc/docker/daemon.json`)
-2. Install the `docker compose` plugin using your package manager, or follow a [tutorial](https://docs.docker.com/compose/install/linux/#install-using-the-repository).
+2. Install the `docker compose` plugin using your package manager, or follow a [tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-22-04).
     - The deprecated `docker-compose` (hyphenated) CLI continues to work for now.
 3. Ensure docker daemon is able to access the GPU.
     - You may need to install [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
@@ -26,12 +18,13 @@ For more configuration options (using an AMD GPU, custom root directory location
 
 This is done via Docker Desktop preferences
 
-### Configure Invoke environment
+## Quickstart
 
-1. Make a copy of `.env.sample` and name it `.env` (`cp .env.sample .env` (Mac/Linux) or `copy example.env .env` (Windows)). Make changes as necessary. Set `INVOKEAI_ROOT` to an absolute path to:
+
+1. Make a copy of `env.sample` and name it `.env` (`cp env.sample .env` (Mac/Linux) or `copy example.env .env` (Windows)). Make changes as necessary. Set `INVOKEAI_ROOT` to an absolute path to:
     a. the desired location of the InvokeAI runtime directory, or
     b. an existing, v3.0.0 compatible runtime directory.
-1. Execute `run.sh`
+1. `docker compose up`
 
 The image will be built automatically if needed.
 
@@ -45,28 +38,24 @@ The runtime directory (holding models and outputs) will be created in the locati
 
 The Docker daemon on the system must be already set up to use the GPU. In case of Linux, this involves installing `nvidia-docker-runtime` and configuring the `nvidia` runtime as default. Steps will be different for AMD. Please see Docker documentation for the most up-to-date instructions for using your GPU with Docker.
 
-To use an AMD GPU, set `GPU_DRIVER=rocm` in your `.env` file.
-
 ## Customize
 
-Check the `.env.sample` file. It contains some environment variables for running in Docker. Copy it, name it `.env`, and fill it in with your own values. Next time you run `run.sh`, your custom values will be used.
+Check the `.env.sample` file. It contains some environment variables for running in Docker. Copy it, name it `.env`, and fill it in with your own values. Next time you run `docker compose up`, your custom values will be used.
 
-You can also set these values in `docker-compose.yml` directly, but `.env` will help avoid conflicts when code is updated.
+You can also set these values in `docker compose.yml` directly, but `.env` will help avoid conflicts when code is updated.
 
-Values are optional, but setting `INVOKEAI_ROOT` is highly recommended. The default is `~/invokeai`. Example:
+Example (most values are optional):
 
-```bash
+```
 INVOKEAI_ROOT=/Volumes/WorkDrive/invokeai
 HUGGINGFACE_TOKEN=the_actual_token
 CONTAINER_UID=1000
-GPU_DRIVER=nvidia
+GPU_DRIVER=cuda
 ```
 
-Any environment variables supported by InvokeAI can be set here - please see the [Configuration docs](https://invoke-ai.github.io/InvokeAI/features/CONFIGURATION/) for further detail.
-
 ## Even Moar Customizing!
 
-See the `docker-compose.yml` file. The `command` instruction can be uncommented and used to run arbitrary startup commands. Some examples below.
+See the `docker compose.yaml` file. The `command` instruction can be uncommented and used to run arbitrary startup commands. Some examples below.
 
 ### Reconfigure the runtime directory
 
@@ -74,7 +63,7 @@ Can be used to download additional models from the supported model list
 
 In conjunction with `INVOKEAI_ROOT` can be also used to initialize a runtime directory
 
-```yaml
+```
 command:
   - invokeai-configure
   - --yes
@@ -82,7 +71,7 @@ command:
 
 Or install models:
 
-```yaml
+```
 command:
   - invokeai-model-install
-```
+```

docker/build.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+
+build_args=""
+
+[[ -f ".env" ]] && build_args=$(awk '$1 ~ /\=[^$]/ {print "--build-arg " $0 " "}' .env)
+
+echo "docker-compose build args:"
+echo $build_args
+
+docker-compose build $build_args

docker/docker-compose.yml

@@ -2,8 +2,19 @@
 
 version: '3.8'
 
-x-invokeai: &invokeai
+services:
+  invokeai:
     image: "local/invokeai:latest"
+    # edit below to run on a container runtime other than nvidia-container-runtime.
+    # not yet tested with rocm/AMD GPUs
+    # Comment out the "deploy" section to run on CPU only
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
     build:
       context: ..
       dockerfile: docker/Dockerfile
@@ -21,9 +32,7 @@ x-invokeai: &invokeai
     ports:
       - "${INVOKEAI_PORT:-9090}:9090"
     volumes:
-      - type: bind
-        source: ${HOST_INVOKEAI_ROOT:-${INVOKEAI_ROOT:-~/invokeai}}
-        target: ${INVOKEAI_ROOT:-/invokeai}
+      - ${INVOKEAI_ROOT:-~/invokeai}:${INVOKEAI_ROOT:-/invokeai}
       - ${HF_HOME:-~/.cache/huggingface}:${HF_HOME:-/invokeai/.cache/huggingface}
       # - ${INVOKEAI_MODELS_DIR:-${INVOKEAI_ROOT:-/invokeai/models}}
       # - ${INVOKEAI_MODELS_CONFIG_PATH:-${INVOKEAI_ROOT:-/invokeai/configs/models.yaml}}
@@ -37,27 +46,3 @@ x-invokeai: &invokeai
     #   - |
     #     invokeai-model-install --yes --default-only --config_file ${INVOKEAI_ROOT}/config_custom.yaml
     #     invokeai-nodes-web --host 0.0.0.0
-
-services:
-  invokeai-nvidia:
-    <<: *invokeai
-    deploy:
-      resources:
-        reservations:
-          devices:
-            - driver: nvidia
-              count: 1
-              capabilities: [gpu]
-
-  invokeai-cpu:
-    <<: *invokeai
-    profiles:
-      - cpu
-
-  invokeai-rocm:
-    <<: *invokeai
-    devices:
-      - /dev/kfd:/dev/kfd
-      - /dev/dri:/dev/dri
-    profiles:
-      - rocm

docker/docker-entrypoint.sh

@@ -19,7 +19,7 @@ set -e -o pipefail
 # Default UID: 1000 chosen due to popularity on Linux systems. Possibly 501 on MacOS.
 
 USER_ID=${CONTAINER_UID:-1000}
-USER=ubuntu
+USER=invoke
 usermod -u ${USER_ID} ${USER} 1>/dev/null
 
 configure() {
@@ -29,8 +29,8 @@ configure() {
         echo "To reconfigure InvokeAI, delete the above file."
         echo "======================================================================"
     else
-        mkdir -p "${INVOKEAI_ROOT}"
-        chown --recursive ${USER} "${INVOKEAI_ROOT}"
+        mkdir -p ${INVOKEAI_ROOT}
+        chown --recursive ${USER} ${INVOKEAI_ROOT}
         gosu ${USER} invokeai-configure --yes --default_only
     fi
 }
@@ -50,16 +50,16 @@ fi
 if [[ -v "PUBLIC_KEY" ]] && [[ ! -d "${HOME}/.ssh" ]]; then
     apt-get update
     apt-get install -y openssh-server
-    pushd "$HOME"
+    pushd $HOME
     mkdir -p .ssh
-    echo "${PUBLIC_KEY}" > .ssh/authorized_keys
+    echo ${PUBLIC_KEY} > .ssh/authorized_keys
     chmod -R 700 .ssh
     popd
     service ssh start
 fi
 
 
-cd "${INVOKEAI_ROOT}"
+cd ${INVOKEAI_ROOT}
 
 # Run the CMD as the Container User (not root).
 exec gosu ${USER} "$@"

docker/run.sh

@@ -1,32 +1,8 @@
 #!/usr/bin/env bash
-set -e -o pipefail
+set -e
 
-run() {
-  local scriptdir=$(dirname "${BASH_SOURCE[0]}")
-  cd "$scriptdir" || exit 1
+SCRIPTDIR=$(dirname "${BASH_SOURCE[0]}")
+cd "$SCRIPTDIR" || exit 1
 
-  local build_args=""
-  local profile=""
-
-  touch .env
-  build_args=$(awk '$1 ~ /=[^$]/ && $0 !~ /^#/ {print "--build-arg " $0 " "}' .env) &&
-  profile="$(awk -F '=' '/GPU_DRIVER/ {print $2}' .env)"
-
-  [[ -z "$profile" ]] && profile="nvidia"
-
-  local service_name="invokeai-$profile"
-
-  if [[ ! -z "$build_args" ]]; then
-    printf "%s\n" "docker compose build args:"
-    printf "%s\n" "$build_args"
-  fi
-
-  docker compose build $build_args $service_name
-  unset build_args
-
-  printf "%s\n" "starting service $service_name"
-  docker compose --profile "$profile" up -d "$service_name"
-  docker compose logs -f
-}
-
-run
+docker-compose up --build -d
+docker-compose logs -f

docs/CHANGELOG.md

@@ -488,7 +488,7 @@ sections describe what's new for InvokeAI.
 
 - A choice of installer scripts that automate installation and configuration.
   See
-  [Installation](installation/INSTALLATION.md).
+  [Installation](installation/index.md).
 - A streamlined manual installation process that works for both Conda and
   PIP-only installs. See
   [Manual Installation](installation/020_INSTALL_MANUAL.md).
@@ -617,6 +617,8 @@ sections describe what's new for InvokeAI.
 - `dream.py` script renamed `invoke.py`. A `dream.py` script wrapper remains for
   backward compatibility.
 - Completely new WebGUI - launch with `python3 scripts/invoke.py --web`
+- Support for [inpainting](deprecated/INPAINTING.md) and
+  [outpainting](features/OUTPAINTING.md)
 - img2img runs on all k\* samplers
 - Support for
   [negative prompts](features/PROMPTS.md#negative-and-unconditioned-prompts)
@@ -657,7 +659,7 @@ sections describe what's new for InvokeAI.
 
 ## v1.13 <small>(3 September 2022)</small>
 
-- Support image variations (see [VARIATIONS](deprecated/VARIATIONS.md)
+- Support image variations (see [VARIATIONS](features/VARIATIONS.md)
   ([Kevin Gibbons](https://github.com/bakkot) and many contributors and
   reviewers)
 - Supports a Google Colab notebook for a standalone server running on Google

docs/RELEASE.md

@@ -1,142 +0,0 @@
-# Release Process
-
-The app is published in twice, in different build formats.
-
-- A [PyPI] distribution. This includes both a source distribution and built distribution (a wheel). Users install with `pip install invokeai`. The updater uses this build.
-- An installer on the [InvokeAI Releases Page]. This is a zip file with install scripts and a wheel. This is only used for new installs.
-
-## General Prep
-
-Make a developer call-out for PRs to merge. Merge and test things out.
-
-While the release workflow does not include end-to-end tests, it does pause before publishing so you can download and test the final build.
-
-## Release Workflow
-
-The `release.yml` workflow runs a number of jobs to handle code checks, tests, build and publish on PyPI.
-
-It is triggered on **tag push**, when the tag matches `v*`. It doesn't matter if you've prepped a release branch like `release/v3.5.0` or are releasing from `main` - it works the same.
-
-> Because commits are reference-counted, it is safe to create a release branch, tag it, let the workflow run, then delete the branch. So long as the tag exists, that commit will exist.
-
-### Triggering the Workflow
-
-Run `make tag-release` to tag the current commit and kick off the workflow.
-
-The release may also be dispatched [manually].
-
-### Workflow Jobs and Process
-
-The workflow consists of a number of concurrently-run jobs, and two final publish jobs.
-
-The publish jobs require manual approval and are only run if the other jobs succeed.
-
-#### `check-version` Job
-
-This job checks that the git ref matches the app version. It matches the ref against the `__version__` variable in `invokeai/version/invokeai_version.py`.
-
-When the workflow is triggered by tag push, the ref is the tag. If the workflow is run manually, the ref is the target selected from the **Use workflow from** dropdown.
-
-This job uses [samuelcolvin/check-python-version].
-
-> Any valid [version specifier] works, so long as the tag matches the version. The release workflow works exactly the same for `RC`, `post`, `dev`, etc.
-
-#### Check and Test Jobs
-
-- **`python-tests`**: runs `pytest` on matrix of platforms
-- **`python-checks`**: runs `ruff` (format and lint)
-- **`frontend-tests`**: runs `vitest`
-- **`frontend-checks`**: runs `prettier` (format), `eslint` (lint), `dpdm` (circular refs), `tsc` (static type check) and `knip` (unused imports)
-
-> **TODO** We should add `mypy` or `pyright` to the **`check-python`** job.
-
-> **TODO** We should add an end-to-end test job that generates an image.
-
-#### `build-installer` Job
-
-This sets up both python and frontend dependencies and builds the python package. Internally, this runs `installer/create_installer.sh` and uploads two artifacts:
-
-- **`dist`**: the python distribution, to be published on PyPI
-- **`InvokeAI-installer-${VERSION}.zip`**: the installer to be included in the GitHub release
-
-#### Sanity Check & Smoke Test
-
-At this point, the release workflow pauses as the remaining publish jobs require approval.
-
-A maintainer should go to the **Summary** tab of the workflow, download the installer and test it. Ensure the app loads and generates.
-
-> The same wheel file is bundled in the installer and in the `dist` artifact, which is uploaded to PyPI. You should end up with the exactly the same installation of the `invokeai` package from any of these methods.
-
-#### PyPI Publish Jobs
-
-The publish jobs will run if any of the previous jobs fail.
-
-They use [GitHub environments], which are configured as [trusted publishers] on PyPI.
-
-Both jobs require a maintainer to approve them from the workflow's **Summary** tab.
-
-- Click the **Review deployments** button
-- Select the environment (either `testpypi` or `pypi`)
-- Click **Approve and deploy**
-
-> **If the version already exists on PyPI, the publish jobs will fail.** PyPI only allows a given version to be published once - you cannot change it. If version published on PyPI has a problem, you'll need to "fail forward" by bumping the app version and publishing a followup release.
-
-#### `publish-testpypi` Job
-
-Publishes the distribution on the [Test PyPI] index, using the `testpypi` GitHub environment.
-
-This job is not required for the production PyPI publish, but included just in case you want to test the PyPI release.
-
-If approved and successful, you could try out the test release like this:
-
-```sh
-# Create a new virtual environment
-python -m venv ~/.test-invokeai-dist --prompt test-invokeai-dist
-# Install the distribution from Test PyPI
-pip install --index-url https://test.pypi.org/simple/ invokeai
-# Run and test the app
-invokeai-web
-# Cleanup
-deactivate
-rm -rf ~/.test-invokeai-dist
-```
-
-#### `publish-pypi` Job
-
-Publishes the distribution on the production PyPI index, using the `pypi` GitHub environment.
-
-## Publish the GitHub Release with installer
-
-Once the release is published to PyPI, it's time to publish the GitHub release.
-
-1. [Draft a new release] on GitHub, choosing the tag that triggered the release.
-2. Write the release notes, describing important changes. The **Generate release notes** button automatically inserts the changelog and new contributors, and you can copy/paste the intro from previous releases.
-3. Upload the zip file created in **`build`** job into the Assets section of the release notes. You can also upload the zip into the body of the release notes, since it can be hard for users to find the Assets section.
-4. Check the **Set as a pre-release** and **Create a discussion for this release** checkboxes at the bottom of the release page.
-5. Publish the pre-release.
-6. Announce the pre-release in Discord.
-
-> **TODO** Workflows can create a GitHub release from a template and upload release assets. One popular action to handle this is [ncipollo/release-action]. A future enhancement to the release process could set this up.
-
-## Manual Build
-
-The `build installer` workflow can be dispatched manually. This is useful to test the installer for a given branch or tag.
-
-No checks are run, it just builds.
-
-## Manual Release
-
-The `release` workflow can be dispatched manually. You must dispatch the workflow from the right tag, else it will fail the version check.
-
-This functionality is available as a fallback in case something goes wonky. Typically, releases should be triggered via tag push as described above.
-
-[InvokeAI Releases Page]: https://github.com/invoke-ai/InvokeAI/releases
-[PyPI]: https://pypi.org/
-[Draft a new release]: https://github.com/invoke-ai/InvokeAI/releases/new
-[Test PyPI]: https://test.pypi.org/
-[version specifier]: https://packaging.python.org/en/latest/specifications/version-specifiers/
-[ncipollo/release-action]: https://github.com/ncipollo/release-action
-[GitHub environments]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment
-[trusted publishers]: https://docs.pypi.org/trusted-publishers/
-[samuelcolvin/check-python-version]: https://github.com/samuelcolvin/check-python-version
-[manually]: #manual-release

docs/contributing/CONTRIBUTING.md

@@ -1,43 +1,42 @@
-# Contributing
+## Welcome to Invoke AI
+
+We're thrilled to have you here and we're excited for you to contribute. 
 
 Invoke AI originated as a project built by the community, and that vision carries forward today as we aim to build the best pro-grade tools available. We work together to incorporate the latest in AI/ML research, making these tools available in over 20 languages to artists and creatives around the world as part of our fully permissive OSS project designed for individual users to self-host and use.
 
+Here are some guidelines to help you get started:
 
-# Methods of Contributing to Invoke AI
-Anyone who wishes to contribute to InvokeAI, whether features, bug fixes, code cleanup, testing, code reviews, documentation or translation is very much encouraged to do so.
+### Technical Prerequisites
 
-## Development
-If you’d like to help with development, please see our [development guide](contribution_guides/development.md). 
+Front-end: You'll need a working knowledge of React and TypeScript.
 
-**New Contributors:** If you’re unfamiliar with contributing to open source projects, take a look at our [new contributor guide](contribution_guides/newContributorChecklist.md).
+Back-end: Depending on the scope of your contribution, you may need to know SQLite, FastAPI, Python, and Socketio. Also, a good majority of the backend logic involved in processing images is built in a modular way using a concept called "Nodes", which are isolated functions that carry out individual, discrete operations. This design allows for easy contributions of novel pipelines and capabilities.
 
-## Nodes
-If you’d like to add a Node, please see our [nodes contribution guide](../nodes/contributingNodes.md).
+### How to Submit Contributions
 
-## Support and Triaging
-Helping support other users in [Discord](https://discord.gg/ZmtBAhwWhy) and on Github are valuable forms of contribution that we greatly appreciate. 
+To start contributing, please follow these steps:
 
-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. 
+1. Familiarize yourself with our roadmap and open projects to see where your skills and interests align. These documents can serve as a source of inspiration.
+2. Open a Pull Request (PR) with a clear description of the feature you're adding or the problem you're solving. Make sure your contribution aligns with the project's vision.
+3. Adhere to general best practices. This includes assuming interoperability with other nodes, keeping the scope of your functions as small as possible, and organizing your code according to our architecture documents.
 
-## Documentation
-If you’d like to help with documentation, please see our [documentation guide](contribution_guides/documentation.md).
+### Types of Contributions We're Looking For
 
-## Translation
-If you'd like to help with translation, please see our [translation guide](contribution_guides/translation.md).
+We welcome all contributions that improve the project. Right now, we're especially looking for:
 
-## Tutorials 
-Please reach out to @imic or @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) to help create tutorials for InvokeAI.
+1. Quality of life (QOL) enhancements on the front-end.
+2. New backend capabilities added through nodes.
+3. Incorporating additional optimizations from the broader open-source software community.
 
-We hope you enjoy using our software as much as we enjoy creating it, and we hope that some of those of you who are reading this will elect to become part of our contributor community.
+### Communication and Decision-making Process
 
+Project maintainers and code owners review PRs to ensure they align with the project's goals. They may provide design or architectural guidance, suggestions on user experience, or provide more significant feedback on the contribution itself. Expect to receive feedback on your submissions, and don't hesitate to ask questions or propose changes.
 
-# Contributors
+For more robust discussions, or if you're planning to add capabilities not currently listed on our roadmap, please reach out to us on our Discord server. That way, we can ensure your proposed contribution aligns with the project's direction before you start writing code.
 
-This project is a combined effort of dedicated people from across the world. [Check out the list of all these amazing people](https://invoke-ai.github.io/InvokeAI/other/CONTRIBUTORS/). We thank them for their time, hard work and effort.
+### Code of Conduct and Contribution Expectations
 
-# Code of Conduct
-
-The InvokeAI community is a welcoming place, and we want your help in maintaining that. Please review our [Code of Conduct](https://github.com/invoke-ai/InvokeAI/blob/main/CODE_OF_CONDUCT.md) to learn more - it's essential to maintaining a respectful and inclusive environment.
+We want everyone in our community to have a positive experience. To facilitate this, we've established a code of conduct and a statement of values that we expect all contributors to adhere to. Please take a moment to review these documents—they're essential to maintaining a respectful and inclusive environment.
 
 By making a contribution to this project, you certify that:
 
@@ -49,11 +48,6 @@ By making a contribution to this project, you certify that:
 This disclaimer is not a license and does not grant any rights or permissions. You must obtain necessary permissions and licenses, including from third parties, before contributing to this project.
 
 This disclaimer is provided "as is" without warranty of any kind, whether expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, or non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the contribution or the use or other dealings in the contribution.
-# Support
-
-For support, please use this repository's [GitHub Issues](https://github.com/invoke-ai/InvokeAI/issues), or join the [Discord](https://discord.gg/ZmtBAhwWhy).
-
-Original portions of the software are Copyright (c) 2023 by respective contributors.
 
 ---
 

docs/contributing/DOWNLOAD_QUEUE.md

@@ -1,277 +0,0 @@
-# The InvokeAI Download Queue
-
-The DownloadQueueService provides a multithreaded parallel download
-queue for arbitrary URLs, with queue prioritization, event handling,
-and restart capabilities.
-
-## Simple Example
-
-```
-from invokeai.app.services.download import DownloadQueueService, TqdmProgress
-
-download_queue = DownloadQueueService()
-for url in ['https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/assets/a-painting-of-a-fire.png?raw=true',
-            'https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/assets/birdhouse.png?raw=true',
-            'https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/assets/missing.png',
-            'https://civitai.com/api/download/models/152309?type=Model&format=SafeTensor',
-            ]:
-
-    # urls start downloading as soon as download() is called
-    download_queue.download(source=url,
-                            dest='/tmp/downloads',
-                            on_progress=TqdmProgress().update
-                            )
-
-download_queue.join()  # wait for all downloads to finish
-for job in download_queue.list_jobs():
-    print(job.model_dump_json(exclude_none=True, indent=4),"\n")
-```
-
-Output:
-
-```
-{
-    "source": "https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/assets/a-painting-of-a-fire.png?raw=true",
-    "dest": "/tmp/downloads",
-    "id": 0,
-    "priority": 10,
-    "status": "completed",
-    "download_path": "/tmp/downloads/a-painting-of-a-fire.png",
-    "job_started": "2023-12-04T05:34:41.742174",
-    "job_ended": "2023-12-04T05:34:42.592035",
-    "bytes": 666734,
-    "total_bytes": 666734
-} 
-
-{
-    "source": "https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/assets/birdhouse.png?raw=true",
-    "dest": "/tmp/downloads",
-    "id": 1,
-    "priority": 10,
-    "status": "completed",
-    "download_path": "/tmp/downloads/birdhouse.png",
-    "job_started": "2023-12-04T05:34:41.741975",
-    "job_ended": "2023-12-04T05:34:42.652841",
-    "bytes": 774949,
-    "total_bytes": 774949
-}
-
-{
-    "source": "https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/assets/missing.png",
-    "dest": "/tmp/downloads",
-    "id": 2,
-    "priority": 10,
-    "status": "error",
-    "job_started": "2023-12-04T05:34:41.742079",
-    "job_ended": "2023-12-04T05:34:42.147625",
-    "bytes": 0,
-    "total_bytes": 0,
-    "error_type": "HTTPError(Not Found)",
-    "error": "Traceback (most recent call last):\n  File \"/home/lstein/Projects/InvokeAI/invokeai/app/services/download/download_default.py\", line 182, in _download_next_item\n    self._do_download(job)\n  File \"/home/lstein/Projects/InvokeAI/invokeai/app/services/download/download_default.py\", line 206, in _do_download\n    raise HTTPError(resp.reason)\nrequests.exceptions.HTTPError: Not Found\n"
-}
-
-{
-    "source": "https://civitai.com/api/download/models/152309?type=Model&format=SafeTensor",
-    "dest": "/tmp/downloads",
-    "id": 3,
-    "priority": 10,
-    "status": "completed",
-    "download_path": "/tmp/downloads/xl_more_art-full_v1.safetensors",
-    "job_started": "2023-12-04T05:34:42.147645",
-    "job_ended": "2023-12-04T05:34:43.735990",
-    "bytes": 719020768,
-    "total_bytes": 719020768
-} 
-```
-
-##  The API
-
-The default download queue is `DownloadQueueService`, an
-implementation of ABC `DownloadQueueServiceBase`. It juggles multiple
-background download requests and provides facilities for interrogating
-and cancelling the requests. Access to a current or past download task
-is mediated via `DownloadJob` objects which report the current status
-of a job request
-
-### The Queue Object
-
-A default download queue is located in
-`ApiDependencies.invoker.services.download_queue`. However, you can
-create additional instances if you need to isolate your queue from the
-main one.
-
-```
-queue = DownloadQueueService(event_bus=events)
-```
-
-`DownloadQueueService()` takes three optional arguments:
-
-| **Argument** | **Type**          |  **Default**  | **Description** |
-|----------------|-----------------|---------------|-----------------|
-| `max_parallel_dl`  | int                         | 5    | Maximum number of simultaneous downloads allowed |
-| `event_bus` | EventServiceBase   | None | System-wide FastAPI event bus for reporting download events |
-| `requests_session` | requests.sessions.Session   | None | An alternative requests Session object to use for the download |
-
-`max_parallel_dl` specifies how many download jobs are allowed to run
-simultaneously. Each will run in a different thread of execution.
-
-`event_bus` is an EventServiceBase, typically the one created at
-InvokeAI startup. If present, download events are periodically emitted
-on this bus to allow clients to follow download progress.
-
-`requests_session` is a url library requests Session object. It is
-used for testing.
-
-### The Job object
-
-The queue operates on a series of download job objects. These objects
-specify the source and destination of the download, and keep track of
-the progress of the download.
-
-The only job type currently implemented is `DownloadJob`, a pydantic object with the
-following fields:
-
-| **Field**      | **Type**        |  **Default**  | **Description** |
-|----------------|-----------------|---------------|-----------------|
-| _Fields passed in at job creation time_                               |
-| `source`         | AnyHttpUrl      |               | Where to download from |
-| `dest`           | Path            |               | Where to download to              |
-| `access_token`   | str             |               | [optional] string containing authentication token for access |
-| `on_start`       | Callable        |               | [optional] callback when the download starts |
-| `on_progress`    | Callable        |               | [optional] callback called at intervals during download progress |
-| `on_complete`    | Callable        |               | [optional] callback called after successful download completion |
-| `on_error`       | Callable        |               | [optional] callback called after an error occurs  |
-| `id`             | int             | auto assigned | Job ID, an integer >= 0           |
-| `priority`       | int             | 10            | Job priority. Lower priorities run before higher priorities |
-|                                                                                                        |
-| _Fields updated over the course of the download task_
-| `status`         | DownloadJobStatus|              | Status code                                |
-| `download_path`  | Path |              | Path to the location of the downloaded file |
-| `job_started`    | float            |              | Timestamp for when the job started running |
-| `job_ended`      | float            |              | Timestamp for when the job completed or errored out |
-| `job_sequence`   | int              |              | A counter that is incremented each time a model is dequeued |
-| `bytes`          | int              | 0            | Bytes downloaded so far   |
-| `total_bytes`    | int              | 0            | Total size of the file at the remote site  |
-| `error_type`     | str              |              | String version of the exception that caused an error during download |
-| `error`          | str              |              | String version of the traceback associated with an error |
-| `cancelled`      | bool             | False        | Set to true if the job was cancelled by the caller|
-
-When you create a job, you can assign it a `priority`. If multiple
-jobs are queued, the job with the lowest priority runs first.
-
-Every job has a `source` and a `dest`. `source` is a pydantic.networks AnyHttpUrl object.
-The `dest` is a path on the local filesystem that specifies the
-destination for the downloaded object. Its semantics are
-described below.
-
-When the job is submitted, it is assigned a numeric `id`. The id can
-then be used to fetch the job object from the queue.
-
-The `status` field is updated by the queue to indicate where the job
-is in its lifecycle. Values are defined in the string enum
-`DownloadJobStatus`, a symbol available from
-`invokeai.app.services.download_manager`. Possible values are:
-
-| **Value**    |   **String Value**  | ** Description ** |
-|--------------|---------------------|-------------------|
-| `WAITING`      | waiting           | Job is on the queue but not yet running|
-| `RUNNING`      | running           | The download is started                |
-| `COMPLETED`    | completed         | Job has finished its work without an error |
-| `ERROR`        | error             | Job encountered an error and will not run again|
-
-`job_started` and `job_ended` indicate when the job
-was started (using a python timestamp) and when it completed.
-
-In case of an error, the job's status will be set to `DownloadJobStatus.ERROR`, the text of the
-Exception that caused the error will be placed in the `error_type`
-field and the traceback that led to the error will be in `error`.
-
-A cancelled job will have status `DownloadJobStatus.ERROR` and an
-`error_type` field of "DownloadJobCancelledException". In addition,
-the job's `cancelled` property will be set to True.
-
-### Callbacks
-
-Download jobs can be associated with a series of callbacks, each with
-the signature `Callable[["DownloadJob"], None]`. The callbacks are assigned
-using optional arguments `on_start`, `on_progress`, `on_complete` and
-`on_error`. When the corresponding event occurs, the callback wil be
-invoked and passed the job. The callback will be run in a `try:`
-context in the same thread as the download job. Any exceptions that
-occur during execution of the callback will be caught and converted
-into a log error message, thereby allowing the download to continue.
-
-#### `TqdmProgress`
-
-The `invokeai.app.services.download.download_default` module defines a
-class named `TqdmProgress` which can be used as an `on_progress`
-handler to display a completion bar in the console. Use as follows:
-
-```
-from invokeai.app.services.download import TqdmProgress
-
-download_queue.download(source='http://some.server.somewhere/some_file',
-                        dest='/tmp/downloads',
-                        on_progress=TqdmProgress().update
-                        )
-
-```
-
-### Events
-
-If the queue was initialized with the InvokeAI event bus (the case
-when using `ApiDependencies.invoker.services.download_queue`), then
-download events will also be issued on the bus. The events are:
-
-* `download_started` -- This is issued when a job is taken off the
-queue and a request is made to the remote server for the URL headers, but before any data
-has been downloaded. The event payload will contain the keys `source`
-and `download_path`. The latter contains the path that the URL will be
-downloaded to.
-
-* `download_progress -- This is issued periodically as the download
-runs. The payload contains the keys `source`, `download_path`,
-`current_bytes` and `total_bytes`. The latter two fields can be
-used to display the percent complete.
-
-* `download_complete` -- This is issued when the download completes
-successfully. The payload contains the keys `source`, `download_path`
-and `total_bytes`.
-
-* `download_error` -- This is issued when the download stops because
-of an error condition. The payload contains the fields `error_type`
-and `error`. The former is the text representation of the exception,
-and the latter is a traceback showing where the error occurred.
-
-### Job control
-
-To create a job call the queue's `download()` method. You can list all
-jobs using `list_jobs()`, fetch a single job by its with
-`id_to_job()`, cancel a running job with `cancel_job()`, cancel all
-running jobs with `cancel_all_jobs()`, and wait for all jobs to finish
-with `join()`.
-
-#### job = queue.download(source, dest, priority, access_token)
-
-Create a new download job and put it on the queue, returning the
-DownloadJob object.
-
-#### jobs = queue.list_jobs()
-
-Return a list of all active and inactive `DownloadJob`s.
-
-#### job = queue.id_to_job(id)
-
-Return the job corresponding to given ID.
-
-Return a list of all active and inactive `DownloadJob`s.
-
-#### queue.prune_jobs()
-
-Remove inactive (complete or errored) jobs from the listing returned
-by `list_jobs()`.
-
-#### queue.join()
-
-Block until all pending jobs have run to completion or errored out.
-

docs/contributing/INVOCATIONS.md

@@ -1,6 +1,6 @@
-# Nodes
+# Invocations
 
-Features in InvokeAI are added in the form of modular nodes systems called
+Features in InvokeAI are added in the form of modular node-like systems called
 **Invocations**.
 
 An Invocation is simply a single operation that takes in some inputs and gives
@@ -9,38 +9,13 @@ complex functionality.
 
 ## Invocations Directory
 
-InvokeAI Nodes can be found in the `invokeai/app/invocations` directory. These
-can be used as examples to create your own nodes.
+InvokeAI Invocations can be found in the `invokeai/app/invocations` directory.
 
-New nodes should be added to a subfolder in `nodes` direction found at the root
-level of the InvokeAI installation location. Nodes added to this folder will be
-able to be used upon application startup.
+You can add your new functionality to one of the existing Invocations in this
+directory or create a new file in this directory as per your needs.
 
-Example `nodes` subfolder structure:
-
-```py
-├── __init__.py # Invoke-managed custom node loader
-│
-├── cool_node
-│   ├── __init__.py # see example below
-│   └── cool_node.py
-│
-└── my_node_pack
-    ├── __init__.py # see example below
-    ├── tasty_node.py
-    ├── bodacious_node.py
-    ├── utils.py
-    └── extra_nodes
-        └── fancy_node.py
-```
-
-Each node folder must have an `__init__.py` file that imports its nodes. Only
-nodes imported in the `__init__.py` file are loaded. See the README in the nodes
-folder for more examples:
-
-```py
-from .cool_node import CoolInvocation
-```
+**Note:** _All Invocations must be inside this directory for InvokeAI to
+recognize them as valid Invocations._
 
 ## Creating A New Invocation
 
@@ -54,13 +29,12 @@ The first set of things we need to do when creating a new Invocation are -
 
 - Create a new class that derives from a predefined parent class called
   `BaseInvocation`.
+- The name of every Invocation must end with the word `Invocation` in order for
+  it to be recognized as an Invocation.
 - Every Invocation must have a `docstring` that describes what this Invocation
   does.
-- While not strictly required, we suggest every invocation class name ends in
-  "Invocation", eg "CropImageInvocation".
-- Every Invocation must use the `@invocation` decorator to provide its unique
-  invocation type. You may also provide its title, tags and category using the
-  decorator.
+- Every Invocation must have a unique `type` field defined which becomes its
+  indentifier.
 - Invocations are strictly typed. We make use of the native
   [typing](https://docs.python.org/3/library/typing.html) library and the
   installed [pydantic](https://pydantic-docs.helpmanual.io/) library for
@@ -69,11 +43,12 @@ The first set of things we need to do when creating a new Invocation are -
 So let us do that.
 
 ```python
-from invokeai.app.invocations.baseinvocation import BaseInvocation, invocation
+from typing import Literal
+from .baseinvocation import BaseInvocation
 
-@invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
 ```
 
 That's great.
@@ -87,10 +62,8 @@ our Invocation takes.
 
 ### **Inputs**
 
-Every Invocation input must be defined using the `InputField` function. This is
-a wrapper around the pydantic `Field` function, which handles a few extra things
-and provides type hints. Like everything else, this should be strictly typed and
-defined.
+Every Invocation input is a pydantic `Field` and like everything else should be
+strictly typed and defined.
 
 So let us create these inputs for our Invocation. First up, the `image` input we
 need. Generally, we can use standard variable types in Python but InvokeAI
@@ -103,50 +76,55 @@ create your own custom field types later in this guide. For now, let's go ahead
 and use it.
 
 ```python
-from invokeai.app.invocations.baseinvocation import BaseInvocation, InputField, invocation
-from invokeai.app.invocations.primitives import ImageField
+from typing import Literal, Union
+from pydantic import Field
+
+from .baseinvocation import BaseInvocation
+from ..models.image import ImageField
 
-@invocation('resize')
 class ResizeInvocation(BaseInvocation):
+    '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
 
     # Inputs
-    image: ImageField = InputField(description="The input image")
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
 ```
 
 Let us break down our input code.
 
 ```python
-image: ImageField = InputField(description="The input image")
+image: Union[ImageField, None] = Field(description="The input image", default=None)
 ```
 
-| Part      | Value                                       | Description                                                                     |
-| --------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
-| Name      | `image`                                     | The variable that will hold our image                                           |
-| Type Hint | `ImageField`                                | The types for our field. Indicates that the image must be an `ImageField` type. |
-| Field     | `InputField(description="The input image")` | The image variable is an `InputField` which needs a description.                |
+| Part      | Value                                                | Description                                                                                        |
+| --------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Name      | `image`                                              | The variable that will hold our image                                                              |
+| Type Hint | `Union[ImageField, None]`                            | The types for our field. Indicates that the image can either be an `ImageField` type or `None`     |
+| Field     | `Field(description="The input image", default=None)` | The image variable is a field which needs a description and a default value that we set to `None`. |
 
 Great. Now let us create our other inputs for `width` and `height`
 
 ```python
-from invokeai.app.invocations.baseinvocation import BaseInvocation, InputField, invocation
-from invokeai.app.invocations.primitives import ImageField
+from typing import Literal, Union
+from pydantic import Field
+
+from .baseinvocation import BaseInvocation
+from ..models.image import ImageField
 
-@invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
 
-    image: ImageField = InputField(description="The input image")
-    width: int = InputField(default=512, ge=64, le=2048, description="Width of the new image")
-    height: int = InputField(default=512, ge=64, le=2048, description="Height of the new image")
+    # Inputs
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
+    width: int = Field(default=512, ge=64, le=2048, description="Width of the new image")
+    height: int = Field(default=512, ge=64, le=2048, description="Height of the new image")
 ```
 
-As you might have noticed, we added two new arguments to the `InputField`
-definition for `width` and `height`, called `gt` and `le`. They stand for
-_greater than or equal to_ and _less than or equal to_.
-
-These impose contraints on those fields, and will raise an exception if the
-values do not meet the constraints. Field constraints are provided by
-**pydantic**, so anything you see in the **pydantic docs** will work.
+As you might have noticed, we added two new parameters to the field type for
+`width` and `height` called `gt` and `le`. These basically stand for _greater
+than or equal to_ and _less than or equal to_. There are various other param
+types for field that you can find on the **pydantic** documentation.
 
 **Note:** _Any time it is possible to define constraints for our field, we
 should do it so the frontend has more information on how to parse this field._
@@ -163,16 +141,20 @@ that are provided by it by InvokeAI.
 Let us create this function first.
 
 ```python
-from invokeai.app.invocations.baseinvocation import BaseInvocation, InputField, invocation, InvocationContext
-from invokeai.app.invocations.primitives import ImageField
+from typing import Literal, Union
+from pydantic import Field
+
+from .baseinvocation import BaseInvocation, InvocationContext
+from ..models.image import ImageField
 
-@invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
 
-    image: ImageField = InputField(description="The input image")
-    width: int = InputField(default=512, ge=64, le=2048, description="Width of the new image")
-    height: int = InputField(default=512, ge=64, le=2048, description="Height of the new image")
+    # Inputs
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
+    width: int = Field(default=512, ge=64, le=2048, description="Width of the new image")
+    height: int = Field(default=512, ge=64, le=2048, description="Height of the new image")
 
     def invoke(self, context: InvocationContext):
         pass
@@ -191,17 +173,21 @@ all the necessary info related to image outputs. So let us use that.
 We will cover how to create your own output types later in this guide.
 
 ```python
-from invokeai.app.invocations.baseinvocation import BaseInvocation, InputField, invocation, InvocationContext
-from invokeai.app.invocations.primitives import ImageField
-from invokeai.app.invocations.image import ImageOutput
+from typing import Literal, Union
+from pydantic import Field
+
+from .baseinvocation import BaseInvocation, InvocationContext
+from ..models.image import ImageField
+from .image import ImageOutput
 
-@invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
 
-    image: ImageField = InputField(description="The input image")
-    width: int = InputField(default=512, ge=64, le=2048, description="Width of the new image")
-    height: int = InputField(default=512, ge=64, le=2048, description="Height of the new image")
+    # Inputs
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
+    width: int = Field(default=512, ge=64, le=2048, description="Width of the new image")
+    height: int = Field(default=512, ge=64, le=2048, description="Height of the new image")
 
     def invoke(self, context: InvocationContext) -> ImageOutput:
         pass
@@ -209,38 +195,57 @@ class ResizeInvocation(BaseInvocation):
 
 Perfect. Now that we have our Invocation setup, let us do what we want to do.
 
-- We will first load the image using one of the services provided by InvokeAI to
-  load the image.
+- We will first load the image. Generally we do this using the `PIL` library but
+  we can use one of the services provided by InvokeAI to load the image.
 - We will resize the image using `PIL` to our input data.
 - We will output this image in the format we set above.
 
 So let's do that.
 
 ```python
-from invokeai.app.invocations.baseinvocation import BaseInvocation, InputField, invocation, InvocationContext
-from invokeai.app.invocations.primitives import ImageField
-from invokeai.app.invocations.image import ImageOutput, ResourceOrigin, ImageCategory
+from typing import Literal, Union
+from pydantic import Field
+
+from .baseinvocation import BaseInvocation, InvocationContext
+from ..models.image import ImageField, ResourceOrigin, ImageCategory
+from .image import ImageOutput
 
-@invocation("resize")
 class ResizeInvocation(BaseInvocation):
-    """Resizes an image"""
+    '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
 
-    image: ImageField = InputField(description="The input image")
-    width: int = InputField(default=512, ge=64, le=2048, description="Width of the new image")
-    height: int = InputField(default=512, ge=64, le=2048, description="Height of the new image")
+    # Inputs
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
+    width: int = Field(default=512, ge=64, le=2048, description="Width of the new image")
+    height: int = Field(default=512, ge=64, le=2048, description="Height of the new image")
 
     def invoke(self, context: InvocationContext) -> ImageOutput:
-        # Load the input image as a PIL image
-        image = context.images.get_pil(self.image.image_name)
+        # Load the image using InvokeAI's predefined Image Service.
+        image = context.services.images.get_pil_image(self.image.image_origin, self.image.image_name)
 
-        # Resize the image
+        # Resizing the image
+        # Because we used the above service, we already have a PIL image. So we can simply resize.
         resized_image = image.resize((self.width, self.height))
 
-        # Save the image
-        image_dto = context.images.save(image=resized_image)
+        # Preparing the image for output using InvokeAI's predefined Image Service.
+        output_image = context.services.images.create(
+            image=resized_image,
+            image_origin=ResourceOrigin.INTERNAL,
+            image_category=ImageCategory.GENERAL,
+            node_id=self.id,
+            session_id=context.graph_execution_state_id,
+            is_intermediate=self.is_intermediate,
+        )
 
-        # Return an ImageOutput
-        return ImageOutput.build(image_dto)
+        # Returning the Image
+        return ImageOutput(
+            image=ImageField(
+                image_name=output_image.image_name,
+                image_origin=output_image.image_origin,
+            ),
+            width=output_image.width,
+            height=output_image.height,
+        )
 ```
 
 **Note:** Do not be overwhelmed by the `ImageOutput` process. InvokeAI has a
@@ -248,24 +253,6 @@ certain way that the images need to be dispatched in order to be stored and read
 correctly. In 99% of the cases when dealing with an image output, you can simply
 copy-paste the template above.
 
-### Customization
-
-We can use the `@invocation` decorator to provide some additional info to the
-UI, like a custom title, tags and category.
-
-We also encourage providing a version. This must be a
-[semver](https://semver.org/) version string ("$MAJOR.$MINOR.$PATCH"). The UI
-will let users know if their workflow is using a mismatched version of the node.
-
-```python
-@invocation("resize", title="My Resizer", tags=["resize", "image"], category="My Invocations", version="1.0.0")
-class ResizeInvocation(BaseInvocation):
-    """Resizes an image"""
-
-    image: ImageField = InputField(description="The input image")
-    ...
-```
-
 That's it. You made your own **Resize Invocation**.
 
 ## Result
@@ -283,73 +270,27 @@ new Invocation ready to be used.
 
 ![resize node editor](../assets/contributing/resize_node_editor.png)
 
-## Contributing Nodes
+# Advanced
 
-Once you've created a Node, the next step is to share it with the community! The
-best way to do this is to submit a Pull Request to add the Node to the
-[Community Nodes](nodes/communityNodes) list. If you're not sure how to do that,
-take a look a at our [contributing nodes overview](contributingNodes).
-
-## Advanced
-
-### Custom Output Types
-
-Like with custom inputs, sometimes you might find yourself needing custom
-outputs that InvokeAI does not provide. We can easily set one up.
-
-Now that you are familiar with Invocations and Inputs, let us use that knowledge
-to create an output that has an `image` field, a `color` field and a `string`
-field.
-
-- An invocation output is a class that derives from the parent class of
-  `BaseInvocationOutput`.
-- All invocation outputs must use the `@invocation_output` decorator to provide
-  their unique output type.
-- Output fields must use the provided `OutputField` function. This is very
-  similar to the `InputField` function described earlier - it's a wrapper around
-  `pydantic`'s `Field()`.
-- It is not mandatory but we recommend using names ending with `Output` for
-  output types.
-- It is not mandatory but we highly recommend adding a `docstring` to describe
-  what your output type is for.
-
-Now that we know the basic rules for creating a new output type, let us go ahead
-and make it.
-
-```python
-from .baseinvocation import BaseInvocationOutput, OutputField, invocation_output
-from .primitives import ImageField, ColorField
-
-@invocation_output('image_color_string_output')
-class ImageColorStringOutput(BaseInvocationOutput):
-    '''Base class for nodes that output a single image'''
-
-    image: ImageField = OutputField(description="The image")
-    color: ColorField = OutputField(description="The color")
-    text: str = OutputField(description="The string")
-```
-
-That's all there is to it.
-
-### Custom Input Fields
+## Custom Input Fields
 
 Now that you know how to create your own Invocations, let us dive into slightly
 more advanced topics.
 
 While creating your own Invocations, you might run into a scenario where the
-existing fields in InvokeAI do not meet your requirements. In such cases, you
-can create your own fields.
+existing input types in InvokeAI do not meet your requirements. In such cases,
+you can create your own input types.
 
 Let us create one as an example. Let us say we want to create a color input
 field that represents a color code. But before we start on that here are some
 general good practices to keep in mind.
 
-### Best Practices
+**Good Practices**
 
 - There is no naming convention for input fields but we highly recommend that
   you name it something appropriate like `ColorField`.
 - It is not mandatory but it is heavily recommended to add a relevant
-  `docstring` to describe your field.
+  `docstring` to describe your input field.
 - Keep your field in the same file as the Invocation that it is made for or in
   another file where it is relevant.
 
@@ -364,13 +305,10 @@ class ColorField(BaseModel):
     pass
 ```
 
-Perfect. Now let us create the properties for our field. This is similar to how
-you created input fields for your Invocation. All the same rules apply. Let us
-create four fields representing the _red(r)_, _blue(b)_, _green(g)_ and
-_alpha(a)_ channel of the color.
-
-> Technically, the properties are _also_ called fields - but in this case, it
-> refers to a `pydantic` field.
+Perfect. Now let us create our custom inputs for our field. This is exactly
+similar how you created input fields for your Invocation. All the same rules
+apply. Let us create four fields representing the _red(r)_, _blue(b)_,
+_green(g)_ and _alpha(a)_ channel of the color.
 
 ```python
 class ColorField(BaseModel):
@@ -385,11 +323,468 @@ That's it. We now have a new input field type that we can use in our Invocations
 like this.
 
 ```python
-color: ColorField = InputField(default=ColorField(r=0, g=0, b=0, a=0), description='Background color of an image')
+color: ColorField = Field(default=ColorField(r=0, g=0, b=0, a=0), description='Background color of an image')
 ```
 
-### Using the custom field
+**Extra Config**
 
-When you start the UI, your custom field will be automatically recognized.
+All input fields also take an additional `Config` class that you can use to do
+various advanced things like setting required parameters and etc.
 
-Custom fields only support connection inputs in the Workflow Editor.
+Let us do that for our _ColorField_ and enforce all the values because we did
+not define any defaults for our fields.
+
+```python
+class ColorField(BaseModel):
+    '''A field that holds the rgba values of a color'''
+    r: int = Field(ge=0, le=255, description="The red channel")
+    g: int = Field(ge=0, le=255, description="The green channel")
+    b: int = Field(ge=0, le=255, description="The blue channel")
+    a: int = Field(ge=0, le=255, description="The alpha channel")
+
+    class Config:
+        schema_extra = {"required": ["r", "g", "b", "a"]}
+```
+
+Now it becomes mandatory for the user to supply all the values required by our
+input field.
+
+We will discuss the `Config` class in extra detail later in this guide and how
+you can use it to make your Invocations more robust.
+
+## Custom Output Types
+
+Like with custom inputs, sometimes you might find yourself needing custom
+outputs that InvokeAI does not provide. We can easily set one up.
+
+Now that you are familiar with Invocations and Inputs, let us use that knowledge
+to put together a custom output type for an Invocation that returns _width_,
+_height_ and _background_color_ that we need to create a blank image.
+
+- A custom output type is a class that derives from the parent class of
+  `BaseInvocationOutput`.
+- It is not mandatory but we recommend using names ending with `Output` for
+  output types. So we'll call our class `BlankImageOutput`
+- It is not mandatory but we highly recommend adding a `docstring` to describe
+  what your output type is for.
+- Like Invocations, each output type should have a `type` variable that is
+  **unique**
+
+Now that we know the basic rules for creating a new output type, let us go ahead
+and make it.
+
+```python
+from typing import Literal
+from pydantic import Field
+
+from .baseinvocation import BaseInvocationOutput
+
+class BlankImageOutput(BaseInvocationOutput):
+    '''Base output type for creating a blank image'''
+    type: Literal['blank_image_output'] = 'blank_image_output'
+
+    # Inputs
+    width: int = Field(description='Width of blank image')
+    height: int = Field(description='Height of blank image')
+    bg_color: ColorField = Field(description='Background color of blank image')
+
+    class Config:
+        schema_extra = {"required": ["type", "width", "height", "bg_color"]}
+```
+
+All set. We now have an output type that requires what we need to create a
+blank_image. And if you noticed it, we even used the `Config` class to ensure
+the fields are required.
+
+## Custom Configuration
+
+As you might have noticed when making inputs and outputs, we used a class called
+`Config` from _pydantic_ to further customize them. Because our inputs and
+outputs essentially inherit from _pydantic_'s `BaseModel` class, all
+[configuration options](https://docs.pydantic.dev/latest/usage/schema/#schema-customization)
+that are valid for _pydantic_ classes are also valid for our inputs and outputs.
+You can do the same for your Invocations too but InvokeAI makes our life a
+little bit easier on that end.
+
+InvokeAI provides a custom configuration class called `InvocationConfig`
+particularly for configuring Invocations. This is exactly the same as the raw
+`Config` class from _pydantic_ with some extra stuff on top to help faciliate
+parsing of the scheme in the frontend UI.
+
+At the current moment, tihs `InvocationConfig` class is further improved with
+the following features related the `ui`.
+
+| Config Option | Field Type                                                                                                    | Example                                                                                                               |
+| ------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| type_hints    | `Dict[str, Literal["integer", "float", "boolean", "string", "enum", "image", "latents", "model", "control"]]` | `type_hint: "model"` provides type hints related to the model like displaying a list of available models              |
+| tags          | `List[str]`                                                                                                   | `tags: ['resize', 'image']` will classify your invocation under the tags of resize and image.                         |
+| title         | `str`                                                                                                         | `title: 'Resize Image` will rename your to this custom title rather than infer from the name of the Invocation class. |
+
+So let us update your `ResizeInvocation` with some extra configuration and see
+how that works.
+
+```python
+from typing import Literal, Union
+from pydantic import Field
+
+from .baseinvocation import BaseInvocation, InvocationContext, InvocationConfig
+from ..models.image import ImageField, ResourceOrigin, ImageCategory
+from .image import ImageOutput
+
+class ResizeInvocation(BaseInvocation):
+    '''Resizes an image'''
+    type: Literal['resize'] = 'resize'
+
+    # Inputs
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
+    width: int = Field(default=512, ge=64, le=2048, description="Width of the new image")
+    height: int = Field(default=512, ge=64, le=2048, description="Height of the new image")
+
+    class Config(InvocationConfig):
+        schema_extra: {
+            ui: {
+                tags: ['resize', 'image'],
+                title: ['My Custom Resize']
+            }
+        }
+
+    def invoke(self, context: InvocationContext) -> ImageOutput:
+        # Load the image using InvokeAI's predefined Image Service.
+        image = context.services.images.get_pil_image(self.image.image_origin, self.image.image_name)
+
+        # Resizing the image
+        # Because we used the above service, we already have a PIL image. So we can simply resize.
+        resized_image = image.resize((self.width, self.height))
+
+        # Preparing the image for output using InvokeAI's predefined Image Service.
+        output_image = context.services.images.create(
+            image=resized_image,
+            image_origin=ResourceOrigin.INTERNAL,
+            image_category=ImageCategory.GENERAL,
+            node_id=self.id,
+            session_id=context.graph_execution_state_id,
+            is_intermediate=self.is_intermediate,
+        )
+
+        # Returning the Image
+        return ImageOutput(
+            image=ImageField(
+                image_name=output_image.image_name,
+                image_origin=output_image.image_origin,
+            ),
+            width=output_image.width,
+            height=output_image.height,
+        )
+```
+
+We now customized our code to let the frontend know that our Invocation falls
+under `resize` and `image` categories. So when the user searches for these
+particular words, our Invocation will show up too.
+
+We also set a custom title for our Invocation. So instead of being called
+`Resize`, it will be called `My Custom Resize`.
+
+As simple as that.
+
+As time goes by, InvokeAI will further improve and add more customizability for
+Invocation configuration. We will have more documentation regarding this at a
+later time.
+
+# **[TODO]**
+
+## Custom Components For Frontend
+
+Every backend input type should have a corresponding frontend component so the
+UI knows what to render when you use a particular field type.
+
+If you are using existing field types, we already have components for those. So
+you don't have to worry about creating anything new. But this might not always
+be the case. Sometimes you might want to create new field types and have the
+frontend UI deal with it in a different way.
+
+This is where we venture into the world of React and Javascript and create our
+own new components for our Invocations. Do not fear the world of JS. It's
+actually pretty straightforward.
+
+Let us create a new component for our custom color field we created above. When
+we use a color field, let us say we want the UI to display a color picker for
+the user to pick from rather than entering values. That is what we will build
+now.
+
+---
+
+# OLD -- TO BE DELETED OR MOVED LATER
+
+---
+
+## Creating a new invocation
+
+To create a new invocation, either find the appropriate module file in
+`/ldm/invoke/app/invocations` to add your invocation to, or create a new one in
+that folder. All invocations in that folder will be discovered and made
+available to the CLI and API automatically. Invocations make use of
+[typing](https://docs.python.org/3/library/typing.html) and
+[pydantic](https://pydantic-docs.helpmanual.io/) for validation and integration
+into the CLI and API.
+
+An invocation looks like this:
+
+```py
+class UpscaleInvocation(BaseInvocation):
+    """Upscales an image."""
+
+    # fmt: off
+    type: Literal["upscale"] = "upscale"
+
+    # Inputs
+    image: Union[ImageField, None] = Field(description="The input image", default=None)
+    strength: float                = Field(default=0.75, gt=0, le=1, description="The strength")
+    level: Literal[2, 4]           = Field(default=2, description="The upscale level")
+    # fmt: on
+
+    # Schema customisation
+    class Config(InvocationConfig):
+        schema_extra = {
+            "ui": {
+                "tags": ["upscaling", "image"],
+            },
+        }
+
+    def invoke(self, context: InvocationContext) -> ImageOutput:
+        image = context.services.images.get_pil_image(
+            self.image.image_origin, self.image.image_name
+        )
+        results = context.services.restoration.upscale_and_reconstruct(
+            image_list=[[image, 0]],
+            upscale=(self.level, self.strength),
+            strength=0.0,  # GFPGAN strength
+            save_original=False,
+            image_callback=None,
+        )
+
+        # Results are image and seed, unwrap for now
+        # TODO: can this return multiple results?
+        image_dto = context.services.images.create(
+            image=results[0][0],
+            image_origin=ResourceOrigin.INTERNAL,
+            image_category=ImageCategory.GENERAL,
+            node_id=self.id,
+            session_id=context.graph_execution_state_id,
+            is_intermediate=self.is_intermediate,
+        )
+
+        return ImageOutput(
+            image=ImageField(
+                image_name=image_dto.image_name,
+                image_origin=image_dto.image_origin,
+            ),
+            width=image_dto.width,
+            height=image_dto.height,
+        )
+
+```
+
+Each portion is important to implement correctly.
+
+### Class definition and type
+
+```py
+class UpscaleInvocation(BaseInvocation):
+    """Upscales an image."""
+    type: Literal['upscale'] = 'upscale'
+```
+
+All invocations must derive from `BaseInvocation`. They should have a docstring
+that declares what they do in a single, short line. They should also have a
+`type` with a type hint that's `Literal["command_name"]`, where `command_name`
+is what the user will type on the CLI or use in the API to create this
+invocation. The `command_name` must be unique. The `type` must be assigned to
+the value of the literal in the type hint.
+
+### Inputs
+
+```py
+    # Inputs
+    image: Union[ImageField,None] = Field(description="The input image")
+    strength: float               = Field(default=0.75, gt=0, le=1, description="The strength")
+    level: Literal[2,4]           = Field(default=2, description="The upscale level")
+```
+
+Inputs consist of three parts: a name, a type hint, and a `Field` with default,
+description, and validation information. For example:
+
+| Part      | Value                                                         | Description                                                                                                               |
+| --------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Name      | `strength`                                                    | This field is referred to as `strength`                                                                                   |
+| Type Hint | `float`                                                       | This field must be of type `float`                                                                                        |
+| Field     | `Field(default=0.75, gt=0, le=1, description="The strength")` | The default value is `0.75`, the value must be in the range (0,1], and help text will show "The strength" for this field. |
+
+Notice that `image` has type `Union[ImageField,None]`. The `Union` allows this
+field to be parsed with `None` as a value, which enables linking to previous
+invocations. All fields should either provide a default value or allow `None` as
+a value, so that they can be overwritten with a linked output from another
+invocation.
+
+The special type `ImageField` is also used here. All images are passed as
+`ImageField`, which protects them from pydantic validation errors (since images
+only ever come from links).
+
+Finally, note that for all linking, the `type` of the linked fields must match.
+If the `name` also matches, then the field can be **automatically linked** to a
+previous invocation by name and matching.
+
+### Config
+
+```py
+    # Schema customisation
+    class Config(InvocationConfig):
+        schema_extra = {
+            "ui": {
+                "tags": ["upscaling", "image"],
+            },
+        }
+```
+
+This is an optional configuration for the invocation. It inherits from
+pydantic's model `Config` class, and it used primarily to customize the
+autogenerated OpenAPI schema.
+
+The UI relies on the OpenAPI schema in two ways:
+
+- An API client & Typescript types are generated from it. This happens at build
+  time.
+- The node editor parses the schema into a template used by the UI to create the
+  node editor UI. This parsing happens at runtime.
+
+In this example, a `ui` key has been added to the `schema_extra` dict to provide
+some tags for the UI, to facilitate filtering nodes.
+
+See the Schema Generation section below for more information.
+
+### Invoke Function
+
+```py
+    def invoke(self, context: InvocationContext) -> ImageOutput:
+        image = context.services.images.get_pil_image(
+            self.image.image_origin, self.image.image_name
+        )
+        results = context.services.restoration.upscale_and_reconstruct(
+            image_list=[[image, 0]],
+            upscale=(self.level, self.strength),
+            strength=0.0,  # GFPGAN strength
+            save_original=False,
+            image_callback=None,
+        )
+
+        # Results are image and seed, unwrap for now
+        # TODO: can this return multiple results?
+        image_dto = context.services.images.create(
+            image=results[0][0],
+            image_origin=ResourceOrigin.INTERNAL,
+            image_category=ImageCategory.GENERAL,
+            node_id=self.id,
+            session_id=context.graph_execution_state_id,
+            is_intermediate=self.is_intermediate,
+        )
+
+        return ImageOutput(
+            image=ImageField(
+                image_name=image_dto.image_name,
+                image_origin=image_dto.image_origin,
+            ),
+            width=image_dto.width,
+            height=image_dto.height,
+        )
+```
+
+The `invoke` function is the last portion of an invocation. It is provided an
+`InvocationContext` which contains services to perform work as well as a
+`session_id` for use as needed. It should return a class with output values that
+derives from `BaseInvocationOutput`.
+
+Before being called, the invocation will have all of its fields set from
+defaults, inputs, and finally links (overriding in that order).
+
+Assume that this invocation may be running simultaneously with other
+invocations, may be running on another machine, or in other interesting
+scenarios. If you need functionality, please provide it as a service in the
+`InvocationServices` class, and make sure it can be overridden.
+
+### Outputs
+
+```py
+class ImageOutput(BaseInvocationOutput):
+    """Base class for invocations that output an image"""
+
+    # fmt: off
+    type: Literal["image_output"] = "image_output"
+    image:      ImageField = Field(default=None, description="The output image")
+    width:             int = Field(description="The width of the image in pixels")
+    height:            int = Field(description="The height of the image in pixels")
+    # fmt: on
+
+    class Config:
+        schema_extra = {"required": ["type", "image", "width", "height"]}
+```
+
+Output classes look like an invocation class without the invoke method. Prefer
+to use an existing output class if available, and prefer to name inputs the same
+as outputs when possible, to promote automatic invocation linking.
+
+## Schema Generation
+
+Invocation, output and related classes are used to generate an OpenAPI schema.
+
+### Required Properties
+
+The schema generation treat all properties with default values as optional. This
+makes sense internally, but when when using these classes via the generated
+schema, we end up with e.g. the `ImageOutput` class having its `image` property
+marked as optional.
+
+We know that this property will always be present, so the additional logic
+needed to always check if the property exists adds a lot of extraneous cruft.
+
+To fix this, we can leverage `pydantic`'s
+[schema customisation](https://docs.pydantic.dev/usage/schema/#schema-customization)
+to mark properties that we know will always be present as required.
+
+Here's that `ImageOutput` class, without the needed schema customisation:
+
+```python
+class ImageOutput(BaseInvocationOutput):
+    """Base class for invocations that output an image"""
+
+    # fmt: off
+    type: Literal["image_output"] = "image_output"
+    image:      ImageField = Field(default=None, description="The output image")
+    width:             int = Field(description="The width of the image in pixels")
+    height:            int = Field(description="The height of the image in pixels")
+    # fmt: on
+```
+
+The OpenAPI schema that results from this `ImageOutput` will have the `type`,
+`image`, `width` and `height` properties marked as optional, even though we know
+they will always have a value.
+
+```python
+class ImageOutput(BaseInvocationOutput):
+    """Base class for invocations that output an image"""
+
+    # fmt: off
+    type: Literal["image_output"] = "image_output"
+    image:      ImageField = Field(default=None, description="The output image")
+    width:             int = Field(description="The width of the image in pixels")
+    height:            int = Field(description="The height of the image in pixels")
+    # fmt: on
+
+    # Add schema customization
+    class Config:
+        schema_extra = {"required": ["type", "image", "width", "height"]}
+```
+
+With the customization in place, the schema will now show these properties as
+required, obviating the need for extensive null checks in client code.
+
+See this `pydantic` issue for discussion on this solution:
+<https://github.com/pydantic/pydantic/discussions/4577>

docs/contributing/LOCAL_DEVELOPMENT.md

@@ -35,244 +35,49 @@ access.
 
 ## Backend
 
-The backend is contained within the `./invokeai/backend` and `./invokeai/app` directories.
-To get started please install the development dependencies.
+The backend is contained within the `./invokeai/backend` folder structure. To
+get started however please install the development dependencies.
 
 From the root of the repository run the following command. Note the use of `"`.
 
 ```zsh
-pip install ".[dev,test]"
+pip install ".[test]"
 ```
 
-These are optional groups of packages which are defined within the `pyproject.toml`
-and will be required for testing the changes you make to the code.
+This in an optional group of packages which is defined within the
+`pyproject.toml` and will be required for testing the changes you make the the
+code.
 
-### Tests
+### Running Tests
 
-See the [tests documentation](./TESTS.md) for information about running and writing tests.
-### Reloading Changes
+We use [pytest](https://docs.pytest.org/en/7.2.x/) for our test suite. Tests can
+be found under the `./tests` folder and can be run with a single `pytest`
+command. Optionally, to review test coverage you can append `--cov`.
 
-Experimenting with changes to the Python source code is a drag if you have to re-start the server —
-and re-load those multi-gigabyte models —
-after every change.
+```zsh
+pytest --cov
+```
 
-For a faster development workflow, add the `--dev_reload` flag when starting the server.
-The server will watch for changes to all the Python files in the `invokeai` directory and apply those changes to the
-running server on the fly.
+Test outcomes and coverage will be reported in the terminal. In addition a more
+detailed report is created in both XML and HTML format in the `./coverage`
+folder. The HTML one in particular can help identify missing statements
+requiring tests to ensure coverage. This can be run by opening
+`./coverage/html/index.html`.
 
-This will allow you to avoid restarting the server (and reloading models) in most cases, but there are some caveats; see
-the [jurigged documentation](https://github.com/breuleux/jurigged#caveats) for details.
+For example.
 
+```zsh
+pytest --cov; open ./coverage/html/index.html
+```
+
+??? info "HTML coverage report output"
+
+    ![html-overview](../assets/contributing/html-overview.png)
+
+    ![html-detail](../assets/contributing/html-detail.png)
 
 ## Front End
 
 <!--#TODO: get input from blessedcoolant here, for the moment inserted the frontend README via snippets extension.-->
 
 --8<-- "invokeai/frontend/web/README.md"
-
-## Developing InvokeAI in VSCode
-
-VSCode offers some nice tools:
-
-- python debugger
-- automatic `venv` activation
-- remote dev (e.g. run InvokeAI on a beefy linux desktop while you type in
-  comfort on your macbook)
-
-### Setup
-
-You'll need the
-[Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-and
-[Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
-extensions installed first.
-
-It's also really handy to install the `Jupyter` extensions:
-
-- [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)
-- [Jupyter Cell Tags](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-cell-tags)
-- [Jupyter Notebook Renderers](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter-renderers)
-- [Jupyter Slide Show](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-slideshow)
-
-#### InvokeAI workspace
-
-Creating a VSCode workspace for working on InvokeAI is highly recommended. It
-can hold InvokeAI-specific settings and configs.
-
-To make a workspace:
-
-- Open the InvokeAI repo dir in VSCode
-- `File` > `Save Workspace As` > save it _outside_ the repo
-
-#### Default python interpreter (i.e. automatic virtual environment activation)
-
-- Use command palette to run command
-  `Preferences: Open Workspace Settings (JSON)`
-- Add `python.defaultInterpreterPath` to `settings`, pointing to your `venv`'s
-  python
-
-Should look something like this:
-
-```jsonc
-{
-  // I like to have all InvokeAI-related folders in my workspace
-  "folders": [
-    {
-      // repo root
-      "path": "InvokeAI"
-    },
-    {
-      // InvokeAI root dir, where `invokeai.yaml` lives
-      "path": "/path/to/invokeai_root"
-    }
-  ],
-  "settings": {
-    // Where your InvokeAI `venv`'s python executable lives
-    "python.defaultInterpreterPath": "/path/to/invokeai_root/.venv/bin/python"
-  }
-}
-```
-
-Now when you open the VSCode integrated terminal, or do anything that needs to
-run python, it will automatically be in your InvokeAI virtual environment.
-
-Bonus: When you create a Jupyter notebook, when you run it, you'll be prompted
-for the python interpreter to run in. This will default to your `venv` python,
-and so you'll have access to the same python environment as the InvokeAI app.
-
-This is _super_ handy.
-
-#### Enabling Type-Checking with Pylance
-
-We use python's typing system in InvokeAI. PR reviews will include checking that types are present and correct. We don't enforce types with `mypy` at this time, but that is on the horizon.
-
-Using a code analysis tool to automatically type check your code (and types) is very important when writing with types. These tools provide immediate feedback in your editor when types are incorrect, and following their suggestions lead to fewer runtime bugs.
-
-Pylance, installed at the beginning of this guide, is the de-facto python LSP (language server protocol). It provides type checking in the editor (among many other features). Once installed, you do need to enable type checking manually:
-
-- Open a python file
-- Look along the status bar in VSCode for `{ } Python`
-- Click the `{ }`
-- Turn type checking on - basic is fine
-
-You'll now see red squiggly lines where type issues are detected. Hover your cursor over the indicated symbols to see what's wrong.
-
-In 99% of cases when the type checker says there is a problem, there really is a problem, and you should take some time to understand and resolve what it is pointing out.
-
-#### Debugging configs with `launch.json`
-
-Debugging configs are managed in a `launch.json` file. Like most VSCode configs,
-these can be scoped to a workspace or folder.
-
-Follow the [official guide](https://code.visualstudio.com/docs/python/debugging)
-to set up your `launch.json` and try it out.
-
-Now we can create the InvokeAI debugging configs:
-
-```jsonc
-{
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      // Run the InvokeAI backend & serve the pre-built UI
-      "name": "InvokeAI Web",
-      "type": "python",
-      "request": "launch",
-      "program": "scripts/invokeai-web.py",
-      "args": [
-        // Your InvokeAI root dir (where `invokeai.yaml` lives)
-        "--root",
-        "/path/to/invokeai_root",
-        // Access the app from anywhere on your local network
-        "--host",
-        "0.0.0.0"
-      ],
-      "justMyCode": true
-    },
-    {
-      // Run the nodes-based CLI
-      "name": "InvokeAI CLI",
-      "type": "python",
-      "request": "launch",
-      "program": "scripts/invokeai-cli.py",
-      "justMyCode": true
-    },
-    {
-      // Run tests
-      "name": "InvokeAI Test",
-      "type": "python",
-      "request": "launch",
-      "module": "pytest",
-      "args": ["--capture=no"],
-      "justMyCode": true
-    },
-    {
-      // Run a single test
-      "name": "InvokeAI Single Test",
-      "type": "python",
-      "request": "launch",
-      "module": "pytest",
-      "args": [
-        // Change this to point to the specific test you are working on
-        "tests/nodes/test_invoker.py"
-      ],
-      "justMyCode": true
-    },
-    {
-      // This is the default, useful to just run a single file
-      "name": "Python: File",
-      "type": "python",
-      "request": "launch",
-      "program": "${file}",
-      "justMyCode": true
-    }
-  ]
-}
-```
-
-You'll see these configs in the debugging configs drop down. Running them will
-start InvokeAI with attached debugger, in the correct environment, and work just
-like the normal app.
-
-Enjoy debugging InvokeAI with ease (not that we have any bugs of course).
-
-#### Remote dev
-
-This is very easy to set up and provides the same very smooth experience as
-local development. Environments and debugging, as set up above, just work,
-though you'd need to recreate the workspace and debugging configs on the remote.
-
-Consult the
-[official guide](https://code.visualstudio.com/docs/remote/remote-overview) to
-get it set up.
-
-Suggest using VSCode's included settings sync so that your remote dev host has
-all the same app settings and extensions automagically.
-
-##### One remote dev gotcha
-
-I've found the automatic port forwarding to be very flakey. You can disable it
-in `Preferences: Open Remote Settings (ssh: hostname)`. Search for
-`remote.autoForwardPorts` and untick the box.
-
-To forward ports very reliably, use SSH on the remote dev client (e.g. your
-macbook). Here's how to forward both backend API port (`9090`) and the frontend
-live dev server port (`5173`):
-
-```bash
-ssh \
-    -L 9090:localhost:9090 \
-    -L 5173:localhost:5173 \
-    user@remote-dev-host
-```
-
-The forwarding stops when you close the terminal window, so suggest to do this
-_outside_ the VSCode integrated terminal in case you need to restart VSCode for
-an extension update or something
-
-Now, on your remote dev client, you can open `localhost:9090` and access the UI,
-now served from the remote dev host, just the same as if it was running on the
-client.

docs/contributing/TESTS.md

@@ -1,89 +0,0 @@
-# InvokeAI Backend Tests
-
-We use `pytest` to run the backend python tests. (See [pyproject.toml](/pyproject.toml) for the default `pytest` options.)
-
-## Fast vs. Slow
-All tests are categorized as either 'fast' (no test annotation) or 'slow' (annotated with the `@pytest.mark.slow` decorator).
-
-'Fast' tests are run to validate every PR, and are fast enough that they can be run routinely during development.
-
-'Slow' tests are currently only run manually on an ad-hoc basis. In the future, they may be automated to run nightly. Most developers are only expected to run the 'slow' tests that directly relate to the feature(s) that they are working on.
-
-As a rule of thumb, tests should be marked as 'slow' if there is a chance that they take >1s (e.g. on a CPU-only machine with slow internet connection). Common examples of slow tests are tests that depend on downloading a model, or running model inference.
-
-## Running Tests
-
-Below are some common test commands:
-```bash
-# Run the fast tests. (This implicitly uses the configured default option: `-m "not slow"`.)
-pytest tests/
-
-# Equivalent command to run the fast tests.
-pytest tests/ -m "not slow"
-
-# Run the slow tests.
-pytest tests/ -m "slow"
-
-# Run the slow tests from a specific file.
-pytest tests/path/to/slow_test.py -m "slow"
-
-# Run all tests (fast and slow).
-pytest tests -m ""
-```
-
-## Test Organization
-
-All backend tests are in the [`tests/`](/tests/) directory. This directory mirrors the organization of the `invokeai/` directory. For example, tests for `invokeai/model_management/model_manager.py` would be found in `tests/model_management/test_model_manager.py`.
-
-TODO: The above statement is aspirational. A re-organization of legacy tests is required to make it true.
-
-## Tests that depend on models
-
-There are a few things to keep in mind when adding tests that depend on models.
-
-1. If a required model is not already present, it should automatically be downloaded as part of the test setup.
-2. If a model is already downloaded, it should not be re-downloaded unnecessarily.
-3. Take reasonable care to keep the total number of models required for the tests low. Whenever possible, re-use models that are already required for other tests. If you are adding a new model, consider including a comment to explain why it is required/unique.
-
-There are several utilities to help with model setup for tests. Here is a sample test that depends on a model:
-```python
-import pytest
-import torch
-
-from invokeai.backend.model_management.models.base import BaseModelType, ModelType
-from invokeai.backend.util.test_utils import install_and_load_model
-
-@pytest.mark.slow
-def test_model(model_installer, torch_device):
-    model_info = install_and_load_model(
-        model_installer=model_installer,
-        model_path_id_or_url="HF/dummy_model_id",
-        model_name="dummy_model",
-        base_model=BaseModelType.StableDiffusion1,
-        model_type=ModelType.Dummy,
-    )
-
-    dummy_input = build_dummy_input(torch_device)
-
-    with torch.no_grad(), model_info as model:
-        model.to(torch_device, dtype=torch.float32)
-        output = model(dummy_input)
-
-    # Validate output...
-
-```
-
-## Test Coverage
-
-To review test coverage, append `--cov` to your pytest command:
-```bash
-pytest tests/ --cov
-```
-
-Test outcomes and coverage will be reported in the terminal. In addition, a more detailed report is created in both XML and HTML format in the `./coverage` folder. The HTML output is particularly helpful in identifying untested statements where coverage should be improved. The HTML report can be viewed by opening `./coverage/html/index.html`.
-
-??? info "HTML coverage report output"
-
-    ![html-overview](../assets/contributing/html-overview.png)
-
-    ![html-detail](../assets/contributing/html-detail.png)

docs/contributing/contribution_guides/development.md

@@ -1,49 +0,0 @@
-# Development
-
-## **What do I need to know to help?**
-
-If you are looking to help to with a code contribution, InvokeAI uses several different technologies under the hood: Python (Pydantic, FastAPI, diffusers) and Typescript (React, Redux Toolkit, ChakraUI, Mantine, Konva). Familiarity with StableDiffusion and image generation concepts is helpful, but not essential. 
-
-
-## **Get Started**
-
-To get started, take a look at our [new contributors checklist](newContributorChecklist.md)
-
-Once you're setup, for more information, you can review the documentation specific to your area of interest:
-
-* #### [InvokeAI Architecure](../ARCHITECTURE.md)
-* #### [Frontend Documentation](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web)
-* #### [Node Documentation](../INVOCATIONS.md)
-* #### [Local Development](../LOCAL_DEVELOPMENT.md)
-
-
-
-If you don't feel ready to make a code contribution yet, no problem! You can also help out in other ways, such as [documentation](documentation.md), [translation](translation.md) or helping support other users and triage issues as they're reported in GitHub.
-
-There are two paths to making a development contribution: 
-
-1. Choosing an open issue to address. Open issues can be found in the [Issues](https://github.com/invoke-ai/InvokeAI/issues?q=is%3Aissue+is%3Aopen) section of the InvokeAI repository. These are tagged by the issue type (bug, enhancement, etc.) along with the “good first issues” tag denoting if they are suitable for first time contributors.
-    1. Additional items can be found on our [roadmap](https://github.com/orgs/invoke-ai/projects/7). The roadmap is organized in terms of priority, and contains features of varying size and complexity. If there is an inflight item you’d like to help with, reach out to the contributor assigned to the item to see how you can help. 
-2. Opening a new issue or feature to add. **Please make sure you have searched through existing issues before creating new ones.**
-
-*Regardless of what you choose, please post in the  [#dev-chat](https://discord.com/channels/1020123559063990373/1049495067846524939) channel of the Discord before you start development in order to confirm that the issue or feature is aligned with the current direction of the project. We value our contributors time and effort and want to ensure that no one’s time is being misspent.*
-
-## Best Practices: 
-* Keep your pull requests small. Smaller pull requests are more likely to be accepted and merged
-* Comments! Commenting your code helps reviewers easily understand your contribution
-* Use Python and Typescript’s typing systems, and consider using an editor with [LSP](https://microsoft.github.io/language-server-protocol/) support to streamline development
-* Make all communications public. This ensure knowledge is shared with the whole community
-
-## **Where can I go for help?**
-
-If you need help, you can ask questions in the [#dev-chat](https://discord.com/channels/1020123559063990373/1049495067846524939) channel of the Discord.
-
-For frontend related work, **@psychedelicious** is the best person to reach out to. 
-
-For backend related work, please reach out to **@blessedcoolant**, **@lstein**, **@StAlKeR7779** or **@psychedelicious**.
-
-
-## **What does the Code of Conduct mean for me?**
-
-Our [Code of Conduct](../../CODE_OF_CONDUCT.md)  means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.
-

docs/contributing/contribution_guides/documentation.md

@@ -1,13 +0,0 @@
-# Documentation
-
-Documentation is an important part of any open source project. It provides a clear and concise way to communicate how the software works, how to use it, and how to troubleshoot issues. Without proper documentation, it can be difficult for users to understand the purpose and functionality of the project. 
-
-## Contributing
-
-All documentation is maintained in the InvokeAI GitHub repository. If you come across documentation that is out of date or incorrect, please submit a pull request with the necessary changes. 
-
-When updating or creating documentation, please keep in mind InvokeAI is a tool for everyone, not just those who have familiarity with generative art. 
-
-## Help & Questions
-
-Please ping @imic or @hipsterusername in the [Discord](https://discord.com/channels/1020123559063990373/1049495067846524939) if you have any questions.

docs/contributing/contribution_guides/newContributorChecklist.md

@@ -1,68 +0,0 @@
-# New Contributor Guide
-
-If you're a new contributor to InvokeAI or Open Source Projects, this is the guide for you. 
-
-## New Contributor Checklist
-- [x] Set up your local development environment & fork of InvokAI by following [the steps outlined here](../../installation/020_INSTALL_MANUAL.md#developer-install)
-- [x] Set up your local tooling with [this guide](InvokeAI/contributing/LOCAL_DEVELOPMENT/#developing-invokeai-in-vscode). Feel free to skip this step if you already have tooling you're comfortable with. 
-- [x] Familiarize yourself with [Git](https://www.atlassian.com/git) & our project structure by reading through the [development documentation](development.md)
-- [x] Join the [#dev-chat](https://discord.com/channels/1020123559063990373/1049495067846524939) channel of the Discord
-- [x] Choose an issue to work on! This can be achieved by asking in the #dev-chat channel, tackling a [good first issue](https://github.com/invoke-ai/InvokeAI/contribute) or finding an item on the [roadmap](https://github.com/orgs/invoke-ai/projects/7). If nothing in any of those places catches your eye, feel free to work on something of interest to you! 
-- [x] Make your first Pull Request with the guide below
-- [x] Happy development! Don't be afraid to ask for help - we're happy to help you contribute!
-
-
-## How do I make a contribution?
-
-Never made an open source contribution before? Wondering how contributions work in our project? Here's a quick rundown!
-
-Before starting these steps, ensure you have your local environment [configured for development](../LOCAL_DEVELOPMENT.md).
-
-1.  Find a [good first issue](https://github.com/invoke-ai/InvokeAI/contribute) that you are interested in addressing or a feature that you would like to add. Then, reach out to our team in the [#dev-chat](https://discord.com/channels/1020123559063990373/1049495067846524939) channel of the Discord to ensure you are  setup for success. 
-2. Fork the [InvokeAI](https://github.com/invoke-ai/InvokeAI) repository to your GitHub profile. This means that you will have a copy of the repository under **your-GitHub-username/InvokeAI**.
-3. Clone the repository to your local machine using:
-```bash
-git clone https://github.com/your-GitHub-username/InvokeAI.git
-```
-If you're unfamiliar with using Git through the commandline, [GitHub Desktop](https://desktop.github.com) is a easy-to-use alternative with a UI. You can do all the same steps listed here, but through the interface. 
-4. Create a new branch for your fix using:
-```bash
-git checkout -b branch-name-here
-```
-5. Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
-6. Add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index:
-```bash
-git add -A
-```
-7. Store the contents of the index with a descriptive message.
-```bash
-git commit -m "Insert a short message of the changes made here"
-```
-8. Push the changes to the remote repository using
-```bash
-git push origin branch-name-here
-```
-9. Submit a pull request to the **main** branch of the InvokeAI repository. If you're not sure how to, [follow this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
-10. Title the pull request with a short description of the changes made and the issue or bug number associated with your change. For example, you can title an issue like so "Added more log outputting to resolve #1234".
-11. In the description of the pull request, explain the changes that you made, any issues you think exist with the pull request you made, and any questions you have for the maintainer. It's OK if your pull request is not perfect (no pull request is), the reviewer will be able to help you fix any problems and improve it!
-12. Wait for the pull request to be reviewed by other collaborators.
-13. Make changes to the pull request if the reviewer(s) recommend them.
-14. Celebrate your success after your pull request is merged!
-
-If you’d like to learn more about contributing to Open Source projects, here is a [Getting Started Guide](https://opensource.com/article/19/7/create-pull-request-github). 
-
-
-## Best Practices: 
-* Keep your pull requests small. Smaller pull requests are more likely to be accepted and merged
-* Comments! Commenting your code helps reviewers easily understand your contribution
-* Use Python and Typescript’s typing systems, and consider using an editor with [LSP](https://microsoft.github.io/language-server-protocol/) support to streamline development
-* Make all communications public. This ensure knowledge is shared with the whole community
-
-
-## **Where can I go for help?**
-
-If you need help, you can ask questions in the [#dev-chat](https://discord.com/channels/1020123559063990373/1049495067846524939) channel of the Discord.
-
-For frontend related work, **@pyschedelicious** is the best person to reach out to. 
-
-For backend related work, please reach out to **@blessedcoolant**, **@lstein**, **@StAlKeR7779** or **@pyschedelicious**.

docs/contributing/contribution_guides/translation.md

@@ -1,19 +0,0 @@
-# Translation
-
-InvokeAI uses [Weblate](https://weblate.org/) for translation. Weblate is a FOSS project providing a scalable translation service. Weblate automates the tedious parts of managing translation of a growing project, and the service is generously provided at no cost to FOSS projects like InvokeAI.
-
-## Contributing
-
-If you'd like to contribute by adding or updating a translation, please visit our [Weblate project](https://hosted.weblate.org/engage/invokeai/). You'll need to sign in with your GitHub account (a number of other accounts are supported, including Google).
-
-Once signed in, select a language and then the Web UI component. From here you can Browse and Translate strings from English to your chosen language. Zen mode offers a simpler translation experience.
-
-Your changes will be attributed to you in the automated PR process; you don't need to do anything else.
-
-## Help & Questions
-
-Please check Weblate's [documentation](https://docs.weblate.org/en/latest/index.html) or ping @Harvestor on [Discord](https://discord.com/channels/1020123559063990373/1049495067846524939) if you have any questions.
-
-## Thanks
-
-Thanks to the InvokeAI community for their efforts to translate the project!

docs/contributing/contribution_guides/tutorials.md

@@ -1,11 +0,0 @@
-# Tutorials
-
-Tutorials help new & existing users expand their abilty to use InvokeAI to the full extent of our features and services.  
-
-Currently, we have a set of tutorials available on our [YouTube channel](https://www.youtube.com/@invokeai), but as InvokeAI continues to evolve with new updates, we want to ensure that we are giving our users the resources they need to succeed. 
-
-Tutorials can be in the form of videos or article walkthroughs on a subject of your choice. We recommend focusing tutorials on the key image generation methods, or on a specific component within one of the image generation methods.
-
-## Contributing
-
-Please reach out to @imic or @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) to help create tutorials for InvokeAI.

docs/deprecated/2to3.md

@@ -1,53 +0,0 @@
-## :octicons-log-16: Important Changes Since Version 2.3
-
-### Nodes
-
-Behind the scenes, InvokeAI has been completely rewritten to support
-"nodes," small unitary operations that can be combined into graphs to
-form arbitrary workflows. For example, there is a prompt node that
-processes the prompt string and feeds it to a text2latent node that
-generates a latent image. The latents are then fed to a latent2image
-node that translates the latent image into a PNG.
-
-The WebGUI has a node editor that allows you to graphically design and
-execute custom node graphs. The ability to save and load graphs is
-still a work in progress, but coming soon.
-
-### Command-Line Interface Retired
-
-All "invokeai" command-line interfaces have been retired as of version
-3.4.
-
-To launch the Web GUI from the command-line, use the command
-`invokeai-web` rather than the traditional `invokeai --web`.
-
-### ControlNet
-
-This version of InvokeAI features ControlNet, a system that allows you
-to achieve exact poses for human and animal figures by providing a
-model to follow. Full details are found in [ControlNet](features/CONTROLNET.md)
-
-### New Schedulers
-
-The list of schedulers has been completely revamped and brought up to date:
-
-| **Short Name** | **Scheduler**                   | **Notes**                   |
-|----------------|---------------------------------|-----------------------------|
-| **ddim**       | DDIMScheduler                   |                             |
-| **ddpm**       | DDPMScheduler                   |                             |
-| **deis**       | DEISMultistepScheduler          |                             |
-| **lms**        | LMSDiscreteScheduler            |                             |
-| **pndm**       | PNDMScheduler                   |                             |
-| **heun**       | HeunDiscreteScheduler           | original noise schedule     |
-| **heun_k**     | HeunDiscreteScheduler           | using karras noise schedule |
-| **euler**      | EulerDiscreteScheduler          | original noise schedule     |
-| **euler_k**    | EulerDiscreteScheduler          | using karras noise schedule |
-| **kdpm_2**     | KDPM2DiscreteScheduler          |                             |
-| **kdpm_2_a**   | KDPM2AncestralDiscreteScheduler |                             |
-| **dpmpp_2s**   | DPMSolverSinglestepScheduler    |                             |
-| **dpmpp_2m**   | DPMSolverMultistepScheduler     | original noise scnedule     |
-| **dpmpp_2m_k** | DPMSolverMultistepScheduler     | using karras noise schedule |
-| **unipc**      | UniPCMultistepScheduler         | CPU only                    |
-| **lcm**        | LCMScheduler                    |                             |
-
-Please see [3.0.0 Release Notes](https://github.com/invoke-ai/InvokeAI/releases/tag/v3.0.0) for further details.

docs/deprecated/CLI.md

@@ -211,8 +211,8 @@ Here are the invoke> command that apply to txt2img:
 | `--facetool <name>`                       | `-ft <name>`                              | `-ft gfpgan`                             | Select face restoration algorithm to use: gfpgan, codeformer                                                                                                                                                                                     |
 | `--codeformer_fidelity`                   | `-cf <float>`                             | `0.75`                                   | Used along with CodeFormer. Takes values between 0 and 1. 0 produces high quality but low accuracy. 1 produces high accuracy but low quality                                                                                                     |
 | `--save_original`                         | `-save_orig`                              | `False`                                  | When upscaling or fixing faces, this will cause the original image to be saved rather than replaced.                                                                                                                                             |
-| `--variation <float>`                     | `-v<float>`                               | `0.0`                                    | Add a bit of noise (0.0=none, 1.0=high) to the image in order to generate a series of variations. Usually used in combination with `-S<seed>` and `-n<int>` to generate a series a riffs on a starting image. See [Variations](VARIATIONS.md). |
-| `--with_variations <pattern>`             |                                           | `None`                                   | Combine two or more variations. See [Variations](VARIATIONS.md) for now to use this.                                                                                                                                                           |
+| `--variation <float>`                     | `-v<float>`                               | `0.0`                                    | Add a bit of noise (0.0=none, 1.0=high) to the image in order to generate a series of variations. Usually used in combination with `-S<seed>` and `-n<int>` to generate a series a riffs on a starting image. See [Variations](../features/VARIATIONS.md). |
+| `--with_variations <pattern>`             |                                           | `None`                                   | Combine two or more variations. See [Variations](../features/VARIATIONS.md) for now to use this.                                                                                                                                                           |
 | `--save_intermediates <n>`                |                                           | `None`                                   | Save the image from every nth step into an "intermediates" folder inside the output directory                                                                                                                                                    |
 | `--h_symmetry_time_pct <float>`           |                                           | `None`                                   | Create symmetry along the X axis at the desired percent complete of the generation process. (Must be between 0.0 and 1.0; set to a very small number like 0.0001 for just after the first step of generation.)                                   |
 | `--v_symmetry_time_pct <float>`           |                                           | `None`                                   | Create symmetry along the Y axis at the desired percent complete of the generation process. (Must be between 0.0 and 1.0; set to a very small number like 0.0001 for just after the first step of generation.)                                   |

docs/deprecated/VARIATIONS.md

@@ -1,131 +0,0 @@
----
-title: Variations
----
-
-# :material-tune-variant: Variations
-
-## Intro
-
-InvokeAI's support for variations enables you to do the following:
-
-1. Generate a series of systematic variations of an image, given a prompt. The
-   amount of variation from one image to the next can be controlled.
-
-2. Given two or more variations that you like, you can combine them in a
-   weighted fashion.
-
-!!! Information ""
-
-    This cheat sheet provides a quick guide for how this works in practice, using
-    variations to create the desired image of Xena, Warrior Princess.
-
-## Step 1 -- Find a base image that you like
-
-The prompt we will use throughout is:
-
-`#!bash "lucy lawless as xena, warrior princess, character portrait, high resolution."`
-
-This will be indicated as `#!bash "prompt"` in the examples below.
-
-First we let SD create a series of images in the usual way, in this case
-requesting six iterations.
-
-<figure markdown>
-![var1](../assets/variation_walkthru/000001.3357757885.png)
-<figcaption> Seed 3357757885 looks nice </figcaption>
-</figure>
-
----
-
-## Step 2 - Generating Variations
-
-Let's try to generate some variations on this image. We select the "*"
-symbol in the line of icons above the image in order to fix the prompt
-and seed. Then we open up the "Variations" section of the generation
-panel and use the slider to set the variation amount to 0.2. The
-higher this value, the more each generated image will differ from the
-previous one.
-
-Now we run the prompt a second time, requesting six iterations. You
-will see six images that are thematically related to each other. Try
-increasing and decreasing the variation amount and see what happens.
-
-### **Variation Sub Seeding**
-
-Note that the output for each image has a `-V` option giving the "variant
-subseed" for that image, consisting of a seed followed by the variation amount
-used to generate it.
-
-This gives us a series of closely-related variations, including the two shown
-here.
-
-<figure markdown>
-![var2](../assets/variation_walkthru/000002.3647897225.png)
-<figcaption>subseed 3647897225</figcaption>
-</figure>
-
-<figure markdown>
-![var3](../assets/variation_walkthru/000002.1614299449.png)
-<figcaption>subseed 1614299449</figcaption>
-</figure>
-
-I like the expression on Xena's face in the first one (subseed 3647897225), and
-the armor on her shoulder in the second one (subseed 1614299449). Can we combine
-them to get the best of both worlds?
-
-We combine the two variations using `-V` (`--with_variations`). Again, we must
-provide the seed for the originally-chosen image in order for this to work.
-
-```bash
-invoke> "prompt"  -S3357757885 -V3647897225,0.1,1614299449,0.1
-Outputs:
-./outputs/Xena/000003.1614299449.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1 -S3357757885
-```
-
-Here we are providing equal weights (0.1 and 0.1) for both the subseeds. The
-resulting image is close, but not exactly what I wanted:
-
-<figure markdown>
-![var4](../assets/variation_walkthru/000003.1614299449.png)
-<figcaption> subseed 1614299449 </figcaption>
-</figure>
-
-We could either try combining the images with different weights, or we can
-generate more variations around the almost-but-not-quite image. We do the
-latter, using both the `-V` (combining) and `-v` (variation strength) options.
-Note that we use `-n6` to generate 6 variations:
-
-```bash
-invoke> "prompt" -S3357757885 -V3647897225,0.1,1614299449,0.1 -v0.05 -n6
-Outputs:
-./outputs/Xena/000004.3279757577.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1,3279757577:0.05 -S3357757885
-./outputs/Xena/000004.2853129515.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1,2853129515:0.05 -S3357757885
-./outputs/Xena/000004.3747154981.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1,3747154981:0.05 -S3357757885
-./outputs/Xena/000004.2664260391.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1,2664260391:0.05 -S3357757885
-./outputs/Xena/000004.1642517170.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1,1642517170:0.05 -S3357757885
-./outputs/Xena/000004.2183375608.png: "prompt" -s50 -W512 -H512 -C7.5 -Ak_lms -V 3647897225:0.1,1614299449:0.1,2183375608:0.05 -S3357757885
-```
-
-This produces six images, all slight variations on the combination of the chosen
-two images. Here's the one I like best:
-
-<figure markdown>
-![var5](../assets/variation_walkthru/000004.3747154981.png)
-<figcaption> subseed 3747154981 </figcaption>
-</figure>
-
-As you can see, this is a very powerful tool, which when combined with subprompt
-weighting, gives you great control over the content and quality of your
-generated images.
-
-## Variations and Samplers
-
-The sampler you choose has a strong effect on variation strength. Some
-samplers, such as `k_euler_a` are very "creative" and produce significant
-amounts of image-to-image variation even when the seed is fixed and the
-`-v` argument is very low. Others are more deterministic. Feel free to
-experiment until you find the combination that you like.
-
-Also be aware of the [Perlin Noise](../features/OTHER.md#thresholding-and-perlin-noise-initialization-options)
-feature, which provides another way of introducing variability into your
-image generation requests.

docs/features/CONCEPTS.md

@@ -0,0 +1,84 @@
+---
+title: Concepts 
+---
+
+# :material-library-shelves: The Hugging Face Concepts Library and Importing Textual Inversion files
+
+With the advances in research, many new capabilities are available to customize the knowledge and understanding of novel concepts not originally contained in the base model. 
+
+
+## Using Textual Inversion Files
+
+Textual inversion (TI) files are small models that customize the output of
+Stable Diffusion image generation. They can augment SD with specialized subjects
+and artistic styles. They are also known as "embeds" in the machine learning
+world.
+
+Each TI file introduces one or more vocabulary terms to the SD model. These are
+known in InvokeAI as "triggers." Triggers are denoted using angle brackets 
+as in "<trigger-phrase>". The two most common type of
+TI files that you'll encounter are `.pt` and `.bin` files, which are produced by
+different TI training packages. InvokeAI supports both formats, but its
+[built-in TI training system](TRAINING.md) produces `.pt`.
+
+The [Hugging Face company](https://huggingface.co/sd-concepts-library) has
+amassed a large ligrary of >800 community-contributed TI files covering a
+broad range of subjects and styles. You can also install your own or others' TI files 
+by placing them in the designated directory for the compatible model type
+
+### An Example
+
+Here are a few examples to illustrate how it works. All these images were
+generated using the command-line client and the Stable Diffusion 1.5 model:
+
+|         Japanese gardener          | Japanese gardener <ghibli-face> | Japanese gardener <hoi4-leaders> | Japanese gardener <cartoona-animals> |
+| :--------------------------------: | :-----------------------------------: | :------------------------------------: | :----------------------------------------: |
+| ![](../assets/concepts/image1.png) |  ![](../assets/concepts/image2.png)   |   ![](../assets/concepts/image3.png)   |     ![](../assets/concepts/image4.png)     |
+
+You can also combine styles and concepts:
+
+<figure markdown>
+  | A portrait of &lt;alf&gt; in &lt;cartoona-animal&gt; style |
+  | :--------------------------------------------------------: |
+  | ![](../assets/concepts/image5.png)                         |
+</figure>
+
+
+## Installing your Own TI Files
+
+You may install any number of `.pt` and `.bin` files simply by copying them into
+the `embedding` directory of the corresponding InvokeAI models directory (usually `invokeai`
+in your home directory). For example, you can simply move a Stable Diffusion 1.5 embedding file to
+the `sd-1/embedding` folder. Be careful not to overwrite one file with another.
+For example, TI files generated by the Hugging Face toolkit share the named
+`learned_embedding.bin`. You can rename these, or use subdirectories to keep them distinct.
+
+At startup time, InvokeAI will scan the various `embedding` directories and load any TI
+files it finds there for compatible models. At startup you will see a message similar to this one:
+
+```bash
+>> Current embedding manager terms: <HOI4-Leader>, <princess-knight>
+```
+To use these when generating, simply type the `<` key in your prompt to open the Textual Inversion WebUI and 
+select the embedding you'd like to use. This UI has type-ahead support, so you can easily find supported embeddings.
+
+## Using LoRAs
+
+LoRA files are models that customize the output of Stable Diffusion image generation.
+Larger than embeddings, but much smaller than full models, they augment SD with improved
+understanding of subjects and artistic styles.
+
+Unlike TI files, LoRAs do not introduce novel vocabulary into the model's known tokens. Instead,
+LoRAs augment the model's weights that are applied to generate imagery. LoRAs may be supplied
+with a "trigger" word that they have been explicitly trained on, or may simply apply their 
+effect without being triggered.
+
+LoRAs are typically stored in .safetensors files, which are the most secure way to store and transmit
+these types of weights. You may install any number of `.safetensors` LoRA files simply by copying them into
+the `lora` directory of the corresponding InvokeAI models directory (usually `invokeai`
+in your home directory). For example, you can simply move a Stable Diffusion 1.5 LoRA file to
+the `sd-1/lora` folder.
+
+To use these when generating, open the LoRA menu item in the options panel, select the LoRAs you want to apply
+and ensure that they have the appropriate weight recommended by the model provider. Typically, most LoRAs perform best at a weight of .75-1. 
+

docs/features/CONFIGURATION.md

@@ -65,6 +65,7 @@ InvokeAI:
     esrgan: true
     internet_available: true
     log_tokenization: false
+    nsfw_checker: false
     patchmatch: true
     restore: true
 ...
@@ -82,7 +83,7 @@ format of YAML files can be found
 [here](https://circleci.com/blog/what-is-yaml-a-beginner-s-guide/).
 
 You can fix a broken `invokeai.yaml` by deleting it and running the
-configuration script again -- option [6] in the launcher, "Re-run the
+configuration script again -- option [7] in the launcher, "Re-run the
 configure script".
 
 #### Reading Environment Variables
@@ -135,16 +136,19 @@ command-line options by giving the `--help` argument:
 
 ```
 (.venv) > invokeai-web --help
-usage: InvokeAI [-h] [--host HOST] [--port PORT] [--allow_origins [ALLOW_ORIGINS ...]] [--allow_credentials | --no-allow_credentials] [--allow_methods [ALLOW_METHODS ...]]
-                [--allow_headers [ALLOW_HEADERS ...]] [--esrgan | --no-esrgan] [--internet_available | --no-internet_available] [--log_tokenization | --no-log_tokenization]
-                [--patchmatch | --no-patchmatch] [--restore | --no-restore]
-                [--always_use_cpu | --no-always_use_cpu] [--free_gpu_mem | --no-free_gpu_mem] [--max_loaded_models MAX_LOADED_MODELS] [--max_cache_size MAX_CACHE_SIZE]
-                [--max_vram_cache_size MAX_VRAM_CACHE_SIZE] [--gpu_mem_reserved GPU_MEM_RESERVED] [--precision {auto,float16,float32,autocast}]
-                [--sequential_guidance | --no-sequential_guidance] [--xformers_enabled | --no-xformers_enabled] [--tiled_decode | --no-tiled_decode] [--root ROOT]
-                [--autoimport_dir AUTOIMPORT_DIR] [--lora_dir LORA_DIR] [--embedding_dir EMBEDDING_DIR] [--controlnet_dir CONTROLNET_DIR] [--conf_path CONF_PATH]
-                [--models_dir MODELS_DIR] [--legacy_conf_dir LEGACY_CONF_DIR] [--db_dir DB_DIR] [--outdir OUTDIR] [--from_file FROM_FILE]
-                [--use_memory_db | --no-use_memory_db] [--model MODEL] [--log_handlers [LOG_HANDLERS ...]] [--log_format {plain,color,syslog,legacy}]
-                [--log_level {debug,info,warning,error,critical}] [--version | --no-version]
+usage: InvokeAI [-h] [--host HOST] [--port PORT] [--allow_origins [ALLOW_ORIGINS ...]] [--allow_credentials | --no-allow_credentials]
+                [--allow_methods [ALLOW_METHODS ...]] [--allow_headers [ALLOW_HEADERS ...]] [--esrgan | --no-esrgan]
+                [--internet_available | --no-internet_available] [--log_tokenization | --no-log_tokenization]
+                [--nsfw_checker | --no-nsfw_checker] [--patchmatch | --no-patchmatch] [--restore | --no-restore]
+                [--always_use_cpu | --no-always_use_cpu] [--free_gpu_mem | --no-free_gpu_mem] [--max_cache_size MAX_CACHE_SIZE]
+                [--max_vram_cache_size MAX_VRAM_CACHE_SIZE] [--precision {auto,float16,float32,autocast}]
+                [--sequential_guidance | --no-sequential_guidance] [--xformers_enabled | --no-xformers_enabled]
+                [--tiled_decode | --no-tiled_decode] [--root ROOT] [--autoimport_dir AUTOIMPORT_DIR] [--lora_dir LORA_DIR]
+                [--embedding_dir EMBEDDING_DIR] [--controlnet_dir CONTROLNET_DIR] [--conf_path CONF_PATH] [--models_dir MODELS_DIR]
+                [--legacy_conf_dir LEGACY_CONF_DIR] [--db_dir DB_DIR] [--outdir OUTDIR] [--from_file FROM_FILE]
+                [--use_memory_db | --no-use_memory_db] [--model MODEL] [--log_handlers [LOG_HANDLERS ...]]
+                [--log_format {plain,color,syslog,legacy}] [--log_level {debug,info,warning,error,critical}]
+...
 ```
 
 ## The Configuration Settings
@@ -154,16 +158,14 @@ groups in `invokeia.yaml`:
 
 ### Web Server
 
-| Setting             | Default Value | Description                                                                                                                |
-|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------------|
-| `host`              | `localhost`   | Name or IP address of the network interface that the web server will listen on                                             |
-| `port`              | `9090`        | Network port number that the web server will listen on                                                                     |
-| `allow_origins`     | `[]`          | A list of host names or IP addresses that are allowed to connect to the InvokeAI API in the format `['host1','host2',...]` |
-| `allow_credentials` | `true`        | Require credentials for a foreign host to access the InvokeAI API (don't change this)                                      |
-| `allow_methods`     | `*`           | List of HTTP methods ("GET", "POST") that the web server is allowed to use when accessing the API                          |
-| `allow_headers`     | `*`           | List of HTTP headers that the web server will accept when accessing the API                                                |
-| `ssl_certfile`      | null          | Path to an SSL certificate file, used to enable HTTPS.                                                                     |
-| `ssl_keyfile`       | null          | Path to an SSL keyfile, if the key is not included in the certificate file.                                                |
+| Setting  | Default Value  |  Description |
+|----------|----------------|--------------|
+| `host`     | `localhost`      | Name or IP address of the network interface that the web server will listen on  |
+| `port`     | `9090`           | Network port number that the web server will listen on  |
+| `allow_origins`  | `[]`       | A list of host names or IP addresses that are allowed to connect to the InvokeAI API in the format `['host1','host2',...]` |
+| `allow_credentials | `true`   | Require credentials for a foreign host to access the InvokeAI API (don't change this) |
+| `allow_methods` | `*`         | List of HTTP methods ("GET", "POST") that the web server is allowed to use when accessing the API  |
+| `allow_headers` | `*`         | List of HTTP headers that the web server will accept when accessing the API  |
 
 The documentation for InvokeAI's API can be accessed by browsing to the following URL: [http://localhost:9090/docs].
 
@@ -176,28 +178,24 @@ These configuration settings allow you to enable and disable various InvokeAI fe
 | `esrgan`     | `true`      | Activate the ESRGAN upscaling options|
 | `internet_available` | `true`     | When a resource is not available locally, try to fetch it via the internet |
 | `log_tokenization` | `false`      | Before each text2image generation, print a color-coded representation of the prompt to the console; this can help understand why a prompt is not working as expected |
+| `nsfw_checker` | `true`     | Activate the NSFW checker to blur out risque images |
 | `patchmatch` | `true`     | Activate the "patchmatch" algorithm for improved inpainting |
+| `restore`    | `true`     | Activate the facial restoration features (DEPRECATED; restoration features will be removed in 3.0.0) |
 
-### Generation
+### Memory/Performance
 
 These options tune InvokeAI's memory and performance characteristics.
 
-| Setting               | Default Value | Description                                                                                                                                                                                                                                                      |
-|-----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `sequential_guidance` | `false`       | Calculate guidance in serial rather than in parallel, lowering memory requirements at the cost of some performance loss                                                                                                                                          |
-| `attention_type`      | `auto`        | Select the type of attention to use. One of `auto`,`normal`,`xformers`,`sliced`, or `torch-sdp`                                                                                                                                                                  |
-| `attention_slice_size` | `auto`       | When "sliced" attention is selected, set the slice size. One of `auto`, `balanced`, `max` or the integers 1-8|
-| `force_tiled_decode`  | `false`       | Force the VAE step to decode in tiles, reducing memory consumption at the cost of performance |
-
-### Device
-
-These options configure the generation execution device.
-
-| Setting               | Default Value | Description                                                                                                                                                                                                                                                      |
-|-----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `device`           | `auto`        | Preferred execution device. One of `auto`, `cpu`, `cuda`, `cuda:1`, `mps`. `auto` will choose the device depending on the hardware platform and the installed torch capabilities. |
-| `precision`           | `auto`        | Floating point precision. One of `auto`, `float16` or `float32`. `float16` will consume half the memory of `float32` but produce slightly lower-quality images. The `auto` setting will guess the proper precision based on your video card and operating system |
-
+| Setting  | Default Value  |  Description |
+|----------|----------------|--------------|
+| `always_use_cpu`     | `false`      | Use the CPU to generate images, even if a GPU is available |
+| `free_gpu_mem`       | `false`      | Aggressively free up GPU memory after each operation; this will allow you to run in low-VRAM environments with some performance penalties |
+| `max_cache_size`       | `6`      | Amount of CPU RAM (in GB) to reserve for caching models in memory; more cache allows you to keep models in memory and switch among them quickly |
+| `max_vram_cache_size`  | `2.75`   | Amount of GPU VRAM (in GB) to reserve for caching models in VRAM; more cache speeds up generation but reduces the size of the images that can be generated. This can be set to zero to maximize the amount of memory available for generation. |
+| `precision`       | `auto`      | Floating point precision. One of `auto`, `float16` or `float32`. `float16` will consume half the memory of `float32` but produce slightly lower-quality images. The `auto` setting will guess the proper precision based on your video card and operating system |
+| `sequential_guidance`     | `false`      | Calculate guidance in serial rather than in parallel, lowering memory requirements at the cost of some performance loss |
+| `xformers_enabled`        | `true`      | If the x-formers memory-efficient attention module is installed, activate it for better memory usage and generation speed|
+| `tiled_decode`            | `false`     | If true, then during the VAE decoding phase the image will be decoded a section at a time, reducing memory consumption at the cost of a performance hit |
 
 ### Paths
 

docs/features/CONTROLNET.md

@@ -1,63 +1,27 @@
 ---
-title: Control Adapters
+title: ControlNet
 ---
 
-# :material-loupe: Control Adapters
+# :material-loupe: ControlNet
 
 ## ControlNet
 
-ControlNet is a powerful set of features developed by the open-source
-community (notably, Stanford researcher
-[**@ilyasviel**](https://github.com/lllyasviel)) that allows you to
-apply a secondary neural network model to your image generation
-process in Invoke.
+ControlNet
 
-With ControlNet, you can get more control over the output of your
-image generation, providing you with a way to direct the network
-towards generating images that better fit your desired style or
-outcome.
+ControlNet is a powerful set of features developed by the open-source community (notably, Stanford researcher [**@ilyasviel**](https://github.com/lllyasviel)) that allows you to apply a secondary neural network model to your image generation process in Invoke.
 
-ControlNet works by analyzing an input image, pre-processing that
-image to identify relevant information that can be interpreted by each
-specific ControlNet model, and then inserting that control information
-into the generation process. This can be used to adjust the style,
-composition, or other aspects of the image to better achieve a
-specific result.
-
-#### Installation
-
-InvokeAI provides access to a series of ControlNet models that provide
-different effects or styles in your generated images.
-
-To install ControlNet Models:
-
-1. The easiest way to install them is
-to use the InvokeAI model installer application. Use the
-`invoke.sh`/`invoke.bat` launcher to select item [4] and then navigate
-to the CONTROLNETS section. Select the models you wish to install and
-press "APPLY CHANGES". You may also enter additional HuggingFace
-repo_ids in the "Additional models" textbox. 
-2. Using the "Add Model" function of the  model manager, enter the HuggingFace Repo ID of the ControlNet. The ID is in the format "author/repoName"
+With ControlNet, you can get more control over the output of your image generation, providing you with a way to direct the network towards generating images that better fit your desired style or outcome.
 
 
-_Be aware that some ControlNet models require additional code
-functionality in order to work properly, so just installing a
-third-party ControlNet model may not have the desired effect._ Please
-read and follow the documentation for installing a third party model
-not currently included among InvokeAI's default list.
+### How it works
 
-Currently InvokeAI **only** supports 🤗 Diffusers-format ControlNet models. These are
-folders that contain the files `config.json` and/or
-`diffusion_pytorch_model.safetensors` and
-`diffusion_pytorch_model.fp16.safetensors`. The name of the folder is
-the name of the model.
+ControlNet works by analyzing an input image, pre-processing that image to identify relevant information that can be interpreted by each specific ControlNet model, and then inserting that control information into the generation process. This can be used to adjust the style, composition, or other aspects of the image to better achieve a specific result.
 
-🤗 Diffusers-format ControlNet models are available at HuggingFace
-(http://huggingface.co) and accessed via their repo IDs (identifiers
-in the format "author/modelname").
 
-#### ControlNet Models
-The models currently supported include:
+### Models
+
+As part of the model installation, ControlNet models can be selected including a variety of pre-trained models that have been added to achieve different effects or styles in your generated images. Further ControlNet models may require additional code functionality to also be incorporated into Invoke's Invocations folder. You should expect to follow any installation instructions for ControlNet models loaded  outside the default models provided by Invoke. The default models include:
+
 
 **Canny**:
 
@@ -88,19 +52,15 @@ A model that generates normal maps from input images, allowing for more realisti
 **Image Segmentation**: 
 A model that divides input images into segments or regions, each of which corresponds to a different object or part of the image. (More details coming soon)
 
-**QR Code Monster**:
-A model that helps generate creative QR codes that still scan. Can also be used to create images with text, logos or shapes within them. 
 
 **Openpose**: 
 The OpenPose control model allows for the identification of the general pose of a character by pre-processing an existing image with a clear human structure. With advanced options, Openpose can also detect the face or hands in the image. 
 
-*Note:* The DWPose Processor has replaced the OpenPose processor in Invoke. Workflows and generations that relied on the OpenPose Processor will need to be updated to use the DWPose Processor instead.
-
 **Mediapipe Face**:
 
 The MediaPipe Face identification processor is able to clearly identify facial features in order to capture vivid expressions of human faces.
 
-**Tile**:
+**Tile (experimental)**:
 
 The Tile model fills out details in the image to match the image, rather than the prompt. The Tile Model is a versatile tool that offers a range of functionalities. Its primary capabilities can be boiled down to two main behaviors:
 
@@ -113,10 +73,12 @@ The Tile Model can be a powerful tool in your arsenal for enhancing image qualit
 
 With Pix2Pix, you can input an image into the controlnet, and then "instruct" the model to change it using your prompt. For example, you can say "Make it winter" to add more wintry elements to a scene.
 
+**Inpaint**: Coming Soon - Currently this model is available but not functional on the Canvas. An upcoming release will provide additional capabilities for using this model when inpainting.
+
 Each of these models can be adjusted and combined with other ControlNet models to achieve different results, giving you even more control over your image generation process.
 
 
-### Using ControlNet
+## Using ControlNet
 
 To use ControlNet, you can simply select the desired model and adjust both the ControlNet and Pre-processor settings to achieve the desired result. You can also use multiple ControlNet models at the same time, allowing you to achieve even more complex effects or styles in your generated images.
 
@@ -128,54 +90,3 @@ Weight - Strength of the Controlnet model applied to the generation for the sect
 Start/End  - 0 represents the start of the generation, 1 represents the end. The Start/end setting controls what steps during the generation process have the ControlNet applied.
 
 Additionally, each ControlNet section can be expanded in order to manipulate settings for the image pre-processor that adjusts your uploaded image before using it in when you Invoke.
-
-## T2I-Adapter
-[T2I-Adapter](https://github.com/TencentARC/T2I-Adapter) is a tool similar to ControlNet that allows for control over the generation process by providing control information during the generation process. T2I-Adapter models tend to be smaller and more efficient than ControlNets. 
-
-##### Installation
-To install T2I-Adapter Models:
-
-1. The easiest way to install models is
-to use the InvokeAI model installer application. Use the
-`invoke.sh`/`invoke.bat` launcher to select item [5] and then navigate
-to the T2I-Adapters section. Select the models you wish to install and
-press "APPLY CHANGES". You may also enter additional HuggingFace
-repo_ids in the "Additional models" textbox. 
-2. Using the "Add Model" function of the  model manager, enter the HuggingFace Repo ID of the T2I-Adapter. The ID is in the format "author/repoName"
-
-#### Usage
-Each T2I Adapter has two settings that are applied.
-
-Weight - Strength of the model applied to the generation for the section, defined by start/end.
-
-Start/End  - 0 represents the start of the generation, 1 represents the end. The Start/end setting controls what steps during the generation process have the ControlNet applied.
-
-Additionally, each  section can be expanded with the "Show Advanced" button in order to manipulate settings for the image pre-processor that adjusts your uploaded image before using it in during the generation process.
-
-
-## IP-Adapter
-
-[IP-Adapter](https://ip-adapter.github.io) is a tooling that allows for image prompt capabilities with text-to-image diffusion models. IP-Adapter works by analyzing the given image prompt to extract features, then passing those features to the UNet along with any other conditioning provided. 
-
-![IP-Adapter + T2I](https://github.com/tencent-ailab/IP-Adapter/raw/main/assets/demo/ip_adpter_plus_multi.jpg)
-
-![IP-Adapter + IMG2IMG](https://raw.githubusercontent.com/tencent-ailab/IP-Adapter/main/assets/demo/image-to-image.jpg)
-
-#### Installation
-There are several ways to install IP-Adapter models with an existing InvokeAI installation:
-
-1. Through the command line interface launched from the invoke.sh / invoke.bat scripts, option [4] to download models.
-2. Through the Model Manager UI with models from the *Tools* section of [www.models.invoke.ai](https://www.models.invoke.ai). To do this, copy the repo ID from the desired model page, and paste it in the Add Model field of the model manager. **Note** Both the IP-Adapter and the Image Encoder must be installed for IP-Adapter to work. For example, the [SD 1.5 IP-Adapter](https://models.invoke.ai/InvokeAI/ip_adapter_plus_sd15) and [SD1.5 Image Encoder](https://models.invoke.ai/InvokeAI/ip_adapter_sd_image_encoder) must be installed to use IP-Adapter with SD1.5 based models.  
-3. **Advanced -- Not recommended ** Manually downloading the IP-Adapter and Image Encoder files - Image Encoder folders shouid be placed in the `models\any\clip_vision` folders. IP Adapter Model folders should be placed in the relevant `ip-adapter` folder of relevant base model folder of Invoke root directory. For example, for the SDXL IP-Adapter, files should be added to the `model/sdxl/ip_adapter/` folder. 
-
-#### Using IP-Adapter
-
-IP-Adapter can be used by navigating to the *Control Adapters* options and enabling IP-Adapter. 
-
-IP-Adapter requires an image to be used as the Image Prompt. It can also be used in conjunction with text prompts, Image-to-Image, Inpainting, Outpainting, ControlNets and LoRAs.
-
-
-Each IP-Adapter has two settings that are applied to the IP-Adapter:
-
-* Weight - Strength of the IP-Adapter model applied to the generation for the section, defined by start/end
-* Start/End  - 0 represents the start of the generation, 1 represents the end. The Start/end setting controls what steps during the generation process have the IP-Adapter applied.

docs/features/LORAS.md

@@ -1,53 +0,0 @@
----
-title: LoRAs & LCM-LoRAs
----
-
-# :material-library-shelves: LoRAs & LCM-LoRAs
-
-With the advances in research, many new capabilities are available to customize the knowledge and understanding of novel concepts not originally contained in the base model. 
-
-## LoRAs
-
-Low-Rank Adaptation (LoRA) files are models that customize the output of Stable Diffusion
-image generation.  Larger than embeddings, but much smaller than full
-models, they augment SD with improved understanding of subjects and
-artistic styles.
-
-Unlike TI files, LoRAs do not introduce novel vocabulary into the
-model's known tokens. Instead, LoRAs augment the model's weights that
-are applied to generate imagery. LoRAs may be supplied with a
-"trigger" word that they have been explicitly trained on, or may
-simply apply their effect without being triggered.
-
-LoRAs are typically stored in .safetensors files, which are the most
-secure way to store and transmit these types of weights. You may
-install any number of `.safetensors` LoRA files simply by copying them
-into the `autoimport/lora` directory of the corresponding InvokeAI models
-directory (usually `invokeai` in your home directory).
-
-To use these when generating, open the LoRA menu item in the options
-panel, select the LoRAs you want to apply and ensure that they have
-the appropriate weight recommended by the model provider. Typically,
-most LoRAs perform best at a weight of .75-1.
-
-
-## LCM-LoRAs
-Latent Consistency Models (LCMs) allowed a reduced number of steps to be used to generate images with Stable Diffusion. These are created by distilling base models, creating models that only require a small number of steps to generate images. However, LCMs require that any fine-tune of a base model be distilled to be used as an LCM. 
-
-LCM-LoRAs are models that provide the benefit of LCMs but are able to be used as LoRAs and applied to any fine tune of a base model. LCM-LoRAs are created by training a small number of adapters, rather than distilling the entire fine-tuned base model. The resulting LoRA can be used the same way as a standard LoRA, but with a greatly reduced step count. This enables SDXL images to be generated up to 10x faster than without the use of LCM-LoRAs. 
-
-
-**Using LCM-LoRAs**
-
-LCM-LoRAs are natively supported in InvokeAI throughout the application. To get started, install any diffusers format LCM-LoRAs using the model manager and select it in the LoRA field.
-
-There are a number parameter differences when using LCM-LoRAs and standard generation: 
-
-- When using LCM-LoRAs, the LoRA strength should be lower than if using a standard LoRA, with 0.35 recommended as a starting point.  
-- The LCM scheduler should be used for generation
-- CFG-Scale should be reduced to ~1
-- Steps should be reduced in the range of 4-8
-
-Standard LoRAs can also be used alongside LCM-LoRAs, but will also require a lower strength, with 0.45 being recommended as a starting point. 
-
-More information can be found here: https://huggingface.co/blog/lcm_lora#fast-inference-with-sdxl-lcm-loras

docs/features/MODEL_MERGING.md

@@ -2,51 +2,17 @@
 title: Model Merging
 ---
 
-InvokeAI provides the ability to merge two or three diffusers-type models into a new merged model. The
-resulting model will combine characteristics of the original, and can
-be used to teach an old model new tricks.
+# :material-image-off: Model Merging
 
 ## How to Merge Models
 
-Model Merging can be be done by navigating to the Model Manager and clicking the "Merge Models" tab. From there, you can select the models and settings you want to use to merge th models. 
-
-## Settings
-
-* Model Selection: there are three multiple choice fields that
-  display all the diffusers-style models that InvokeAI knows about.
-  If you do not see the model you are looking for, then it is probably
-  a legacy checkpoint model and needs to be converted using the
-  "Convert" option in the Web-based Model Manager tab.
-  
-  You must select at least two models to merge. The third can be left
-  at "None" if you desire.
-
-* Alpha: This is the ratio to use when combining models. It ranges
-  from 0 to 1. The higher the value, the more weight is given to the
-  2d and (optionally) 3d models. So if you have two models named "A"
-  and "B", an alpha value of 0.25 will give you a merged model that is
-  25% A and 75% B.
-
-* Interpolation Method: This is the method used to combine
-  weights. The options are "weighted_sum" (the default), "sigmoid",
-  "inv_sigmoid" and "add_difference". Each produces slightly different
-  results. When three models are in use, only "add_difference" is
-  available.
-
-* Save Location: The location you want the merged model to be saved in. Default is in the InvokeAI root folder
-
-* Name for merged model: This is the name for the new model. Please
-  use InvokeAI conventions - only alphanumeric letters and the
-  characters ".+-".
-
-* Ignore Mismatches / Force: Not all models are compatible with each other. The merge
-  script will check for compatibility and refuse to merge ones that
-  are incompatible. Set this checkbox to try merging anyway.
-
-
+As of version 2.3, InvokeAI comes with a script that allows you to
+merge two or three diffusers-type models into a new merged model. The
+resulting model will combine characteristics of the original, and can
+be used to teach an old model new tricks.
 
 You may run the merge script by starting the invoke launcher
-(`invoke.sh` or `invoke.bat`) and choosing the option (4) for _merge
+(`invoke.sh` or `invoke.bat`) and choosing the option for _merge
 models_. This will launch a text-based interactive user interface that
 prompts you to select the models to merge, how to merge them, and the
 merged model name.
@@ -74,4 +40,34 @@ this to get back.
 If the merge runs successfully, it will create a new diffusers model
 under the selected name and register it with InvokeAI.
 
+## The Settings
+
+* Model Selection -- there are three multiple choice fields that
+  display all the diffusers-style models that InvokeAI knows about.
+  If you do not see the model you are looking for, then it is probably
+  a legacy checkpoint model and needs to be converted using the
+  `invoke` command-line client and its `!optimize` command. You
+  must select at least two models to merge. The third can be left at
+  "None" if you desire.
+
+* Alpha -- This is the ratio to use when combining models. It ranges
+  from 0 to 1. The higher the value, the more weight is given to the
+  2d and (optionally) 3d models. So if you have two models named "A"
+  and "B", an alpha value of 0.25 will give you a merged model that is
+  25% A and 75% B.
+
+* Interpolation Method -- This is the method used to combine
+  weights. The options are "weighted_sum" (the default), "sigmoid",
+  "inv_sigmoid" and "add_difference". Each produces slightly different
+  results. When three models are in use, only "add_difference" is
+  available. (TODO: cite a reference that describes what these
+  interpolation methods actually do and how to decide among them).
+
+* Force -- Not all models are compatible with each other. The merge
+  script will check for compatibility and refuse to merge ones that
+  are incompatible. Set this checkbox to try merging anyway.
+
+* Name for merged model - This is the name for the new model. Please
+  use InvokeAI conventions - only alphanumeric letters and the
+  characters ".+-".
 

docs/features/NODES.md

@@ -0,0 +1,206 @@
+# Nodes Editor (Experimental)
+
+🚨
+*The node editor is experimental. We've made it accessible because we use it to develop the application, but we have not addressed the many known rough edges. It's very easy to shoot yourself in the foot, and we cannot offer support for it until it sees full release (ETA v3.1). Everything is subject to change without warning.* 
+🚨
+
+The nodes editor is a blank canvas allowing for the use of individual functions and image transformations to control the image generation workflow. The node processing flow is usually done from left (inputs) to right (outputs), though linearity can become abstracted the more complex the node graph becomes. Nodes inputs and outputs are connected by dragging connectors from node to node.
+
+To better understand how nodes are used, think of how an electric power bar works. It takes in one input (electricity from a wall outlet) and passes it to multiple devices through multiple outputs. Similarly, a node could have multiple inputs and outputs functioning at the same (or different) time, but all node outputs pass information onward like a power bar passes electricity. Not all outputs are compatible with all inputs, however - Each node has different constraints on how it is expecting to input/output information. In general, node outputs are colour-coded to match compatible inputs of other nodes.
+
+## Anatomy of a Node
+
+Individual nodes are made up of the following:
+
+- Inputs: Edge points on the left side of the node window where you connect outputs from other nodes.
+- Outputs: Edge points on the right side of the node window where you connect to inputs on other nodes.
+- Options: Various options which are either manually configured, or overridden by connecting an output from another node to the input.
+
+## Diffusion Overview
+
+Taking the time to understand the diffusion process will help you to understand how to set up your nodes in the nodes editor. 
+
+There are two main spaces Stable Diffusion works in: image space and latent space.
+
+Image space represents images in pixel form that you look at. Latent space represents compressed inputs. It’s in latent space that Stable Diffusion processes images. A VAE (Variational Auto Encoder) is responsible for compressing and encoding inputs into latent space, as well as decoding outputs back into image space.
+
+When you generate an image using text-to-image, multiple steps occur in latent space:
+1. Random noise is generated at the chosen height and width. The noise’s characteristics are dictated by the chosen (or not chosen) seed. This noise tensor is passed into latent space. We’ll call this noise A.
+1. Using a model’s U-Net, a noise predictor examines noise A, and the words tokenized by CLIP from your prompt (conditioning). It generates its own noise tensor to predict what the final image might look like in latent space. We’ll call this noise B.
+1. Noise B is subtracted from noise A in an attempt to create a final latent image indicative of the inputs. This step is repeated for the number of sampler steps chosen.
+1. The VAE decodes the final latent image from latent space into image space.
+
+image-to-image is a similar process, with only step 1 being different:
+1. The input image is decoded from image space into latent space by the VAE. Noise is then added to the input latent image. Denoising Strength dictates how much noise is added, 0 being none, and 1 being all-encompassing. We’ll call this noise A. The process is then the same as steps 2-4 in the text-to-image explanation above. 
+
+Furthermore, a model provides the CLIP prompt tokenizer, the VAE, and a U-Net (where noise prediction occurs given a prompt and initial noise tensor).
+
+A noise scheduler (eg. DPM++ 2M Karras) schedules the subtraction of noise from the latent image across the sampler steps chosen (step 3 above). Less noise is usually subtracted at higher sampler steps. 
+
+## Node Types (Base Nodes)
+
+| Node <img width=160 align="right"> | Function                                                                              |
+| ---------------------------------- | --------------------------------------------------------------------------------------|
+| Add                                | Adds two numbers |
+| CannyImageProcessor                | Canny edge detection for ControlNet |
+| ClipSkip                           | Skip layers in clip text_encoder model |
+| Collect                            | Collects values into a collection |
+| Prompt (Compel)                    | Parse prompt using compel package to conditioning |
+| ContentShuffleImageProcessor       | Applies content shuffle processing to image |
+| ControlNet                         | Collects ControlNet info to pass to other nodes |
+| CvInpaint                          | Simple inpaint using opencv |
+| Divide                             | Divides two numbers |
+| DynamicPrompt                      | Parses a prompt using adieyal/dynamic prompt's random or combinatorial generator |
+| FloatLinearRange                   | Creates a range |
+| HedImageProcessor                  | Applies HED edge detection to image |
+| ImageBlur                          | Blurs an image |
+| ImageChannel                       | Gets a channel from an image |
+| ImageCollection                    | Load a collection of images and provide it as output |
+| ImageConvert                       | Converts an image to a different mode |
+| ImageCrop                          | Crops an image to a specified box. The box can be outside of the image. |
+| ImageInverseLerp                   | Inverse linear interpolation of all pixels of an image |
+| ImageLerp                          | Linear interpolation of all pixels of an image |
+| ImageMultiply                      | Multiplies two images together using `PIL.ImageChops.Multiply()` |
+| ImagePaste                         | Pastes an image into another image |
+| ImageProcessor                     | Base class for invocations that reprocess images for ControlNet |
+| ImageResize                        | Resizes an image to specific dimensions |
+| ImageScale                         | Scales an image by a factor |
+| ImageToLatents                     | Scales latents by a given factor |
+| InfillColor                        | Infills transparent areas of an image with a solid color |
+| InfillPatchMatch                   | Infills transparent areas of an image using the PatchMatch algorithm |
+| InfillTile                         | Infills transparent areas of an image with tiles of the image |
+| Inpaint                            | Generates an image using inpaint |
+| Iterate                            | Iterates over a list of items |
+| LatentsToImage                     | Generates an image from latents |
+| LatentsToLatents                   | Generates latents using latents as base image |
+| LeresImageProcessor                | Applies leres processing to image |
+| LineartAnimeImageProcessor         | Applies line art anime processing to image |
+| LineartImageProcessor              | Applies line art processing to image |
+| LoadImage                          | Load an image and provide it as output |
+| Lora Loader                        | Apply selected lora to unet and text_encoder |
+| Model Loader                       | Loads a main model, outputting its submodels |
+| MaskFromAlpha                      | Extracts the alpha channel of an image as a mask |
+| MediapipeFaceProcessor             | Applies mediapipe face processing to image |
+| MidasDepthImageProcessor           | Applies Midas depth processing to image |
+| MlsdImageProcessor                 | Applied MLSD processing to image |
+| Multiply                           | Multiplies two numbers |
+| Noise                              | Generates latent noise |
+| NormalbaeImageProcessor            | Applies NormalBAE processing to image |
+| OpenposeImageProcessor             | Applies Openpose processing to image |
+| ParamFloat                         | A float parameter |
+| ParamInt                           | An integer parameter |
+| PidiImageProcessor                 | Applies PIDI processing to an image |
+| Progress Image                     | Displays the progress image in the Node Editor |
+| RandomInit                         | Outputs a single random integer |
+| RandomRange                        | Creates a collection of random numbers |
+| Range                              | Creates a range of numbers from start to stop with step |
+| RangeOfSize                        | Creates a range from start to start + size with step |
+| ResizeLatents                      | Resizes latents to explicit width/height (in pixels). Provided dimensions are floor-divided by 8. |
+| RestoreFace                        | Restores faces in the image |
+| ScaleLatents                       | Scales latents by a given factor |
+| SegmentAnythingProcessor           | Applies segment anything processing to image |
+| ShowImage                          | Displays a provided image, and passes it forward in the pipeline |
+| StepParamEasing                    | Experimental per-step parameter for easing for denoising steps |
+| Subtract                           | Subtracts two numbers |
+| TextToLatents                      | Generates latents from conditionings |
+| TileResampleProcessor              | Bass class for invocations that preprocess images for ControlNet |
+| Upscale                            | Upscales an image |
+| VAE Loader                         | Loads a VAE model, outputting a VaeLoaderOutput |
+| ZoeDepthImageProcessor             | Applies Zoe depth processing to image |
+
+## Node Grouping Concepts
+
+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
+
+As described, an initial noise tensor is necessary for the latent diffusion process. As a result, all non-image *ToLatents nodes require a noise node input.  
+
+<img width="654" alt="groupsnoise" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/2e8d297e-ad55-4d27-bc93-c119dad2a2c5">
+
+### Conditioning
+
+As described, conditioning is necessary for the latent diffusion process, whether empty or not. As a result, all non-image *ToLatents nodes require positive and negative conditioning inputs. Conditioning is reliant on a CLIP tokenizer provided by the Model Loader node.
+
+<img width="1024" alt="groupsconditioning" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/f8f7ad8a-8d9c-418e-b5ad-1437b774b27e">
+
+### Image Space & VAE
+
+The ImageToLatents node doesn't require a noise node input, but requires a VAE input to convert the image from image space into latent space. In reverse, the LatentsToImage node requires a VAE input to convert from latent space back into image space.
+
+<img width="637" alt="groupsimgvae" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/dd99969c-e0a8-4f78-9b17-3ffe179cef9a">
+
+### Defined & Random Seeds
+
+It is common to want to use both the same seed (for continuity) and random seeds (for variance). To define a seed, simply enter it into the 'Seed' field on a noise node. Conversely, the RandomInt node generates a random integer between 'Low' and 'High', and can be used as input to the 'Seed' edge point on a noise node to randomize your seed.
+
+<img width="922" alt="groupsrandseed" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/af55bc20-60f6-438e-aba5-3ec871443710">
+
+### Control
+
+Control means to guide the diffusion process to adhere to a defined input or structure. Control can be provided as input to non-image *ToLatents nodes from ControlNet nodes. ControlNet nodes usually require an image processor which converts an input image for use with ControlNet.
+
+<img width="805" alt="groupscontrol" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/cc9c5de7-23a7-46c8-bbad-1f3609d999a6">
+
+### LoRA
+
+The Lora Loader node lets you load a LoRA (say that ten times fast) and pass it as output to both the Prompt (Compel) and non-image *ToLatents nodes. A model's CLIP tokenizer is passed through the LoRA into Prompt (Compel), where it affects conditioning. A model's U-Net is also passed through the LoRA into a non-image *ToLatents node, where it affects noise prediction.
+
+<img width="993" alt="groupslora" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/630962b0-d914-4505-b3ea-ccae9b0269da">
+
+### Scaling
+
+Use the ImageScale, ScaleLatents, and Upscale nodes to upscale images and/or latent images. The chosen method differs across contexts. However, be aware that latents are already noisy and compressed at their original resolution; scaling an image could produce more detailed results.
+
+<img width="644" alt="groupsallscale" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/99314f05-dd9f-4b6d-b378-31de55346a13">
+
+### Iteration + Multiple Images as Input
+
+Iteration is a common concept in any processing, and means to repeat a process with given input. In nodes, you're able to use the Iterate node to iterate through collections usually gathered by the Collect node. The Iterate node has many potential uses, from processing a collection of images one after another, to varying seeds across multiple image generations and more. This screenshot demonstrates how to collect several images and pass them out one at a time.
+
+<img width="788" alt="groupsiterate" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/4af5ca27-82c9-4018-8c5b-024d3ee0a121">
+
+### Multiple Image Generation + Random Seeds
+
+Multiple image generation in the node editor is done using the RandomRange node. In this case, the 'Size' field represents the number of images to generate. As RandomRange produces a collection of integers, we need to add the Iterate node to iterate through the collection. 
+
+To control seeds across generations takes some care. The first row in the screenshot will generate multiple images with different seeds, but using the same RandomRange parameters across invocations will result in the same group of random seeds being used across the images, producing repeatable results. In the second row, adding the RandomInt node as input to RandomRange's 'Seed' edge point will ensure that seeds are varied across all images across invocations, producing varied results.
+
+<img width="1027" alt="groupsmultigenseeding" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/518d1b2b-fed1-416b-a052-ab06552521b3">
+
+## Examples
+
+With our knowledge of node grouping and the diffusion process, let’s break down some basic graphs in the nodes editor. Note that a node's options can be overridden by inputs from other nodes. These examples aren't strict rules to follow and only demonstrate some basic configurations.
+
+### Basic text-to-image Node Graph
+
+<img width="875" alt="nodest2i" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/17c67720-c376-4db8-94f0-5e00381a61ee">
+
+- Model Loader: A necessity to generating images (as we’ve read above). We choose our model from the dropdown. It outputs a U-Net, CLIP tokenizer, and VAE.
+- Prompt (Compel): Another necessity. Two prompt nodes are created. One will output positive conditioning (what you want, ‘dog’), one will output negative (what you don’t want, ‘cat’). They both input the CLIP tokenizer that the Model Loader node outputs.
+- Noise: Consider this noise A from step one of the text-to-image explanation above. Choose a seed number, width, and height.
+- TextToLatents: This node takes many inputs for converting and processing text & noise from image space into latent space, hence the name TextTo**Latents**. In this setup, it inputs positive and negative conditioning from the prompt nodes for processing (step 2 above). It inputs noise from the noise node for processing (steps 2 & 3 above). Lastly, it inputs a U-Net from the Model Loader node for processing (step 2 above). It outputs latents for use in the next LatentsToImage node. Choose number of sampler steps, CFG scale, and scheduler.
+- LatentsToImage: This node takes in processed latents from the TextToLatents node, and the model’s VAE from the Model Loader node which is responsible for decoding latents back into the image space, hence the name LatentsTo**Image**. This node is the last stop, and once the image is decoded, it is saved to the gallery.
+
+### Basic image-to-image Node Graph
+
+<img width="998" alt="nodesi2i" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/3f2c95d5-cee7-4415-9b79-b46ee60a92fe">
+
+- Model Loader: Choose a model from the dropdown.
+- Prompt (Compel): Two prompt nodes. One positive (dog), one negative (dog). Same CLIP inputs from the Model Loader node as before.
+- ImageToLatents: Upload a source image directly in the node window, via drag'n'drop from the gallery, or passed in as input. The ImageToLatents node inputs the VAE from the Model Loader node to decode the chosen image from image space into latent space, hence the name ImageTo**Latents**. It outputs latents for use in the next LatentsToLatents node. It also outputs the source image's width and height for use in the next Noise node if the final image is to be the same dimensions as the source image.
+- Noise: A noise tensor is created with the width and height of the source image, and connected to the next LatentsToLatents node. Notice the width and height fields are overridden by the input from the ImageToLatents width and height outputs.
+- LatentsToLatents: The inputs and options are nearly identical to TextToLatents, except that LatentsToLatents also takes latents as an input. Considering our source image is already converted to latents in the last ImageToLatents node, and text + noise are no longer the only inputs to process, we use the LatentsToLatents node. 
+- LatentsToImage: Like previously, the LatentsToImage node will use the VAE from the Model Loader as input to decode the latents from LatentsToLatents into image space, and save it to the gallery.
+
+### Basic ControlNet Node Graph
+
+<img width="703" alt="nodescontrol" src="https://github.com/ymgenesis/InvokeAI/assets/25252829/b02ded86-ceb4-44a2-9910-e19ad184d471">
+
+- Model Loader
+- Prompt (Compel)
+- Noise: Width and height of the CannyImageProcessor ControlNet image is passed in to set the dimensions of the noise passed to TextToLatents.
+- CannyImageProcessor: The CannyImageProcessor node is used to process the source image being used as a ControlNet. Each ControlNet processor node applies control in different ways, and has some different options to configure. Width and height are passed to noise, as mentioned. The processed ControlNet image is output to the ControlNet node.
+- ControlNet: Select the type of control model. In this case, canny is chosen as the CannyImageProcessor was used to generate the ControlNet image. Configure the control node options, and pass the control output to TextToLatents.
+- TextToLatents: Similar to the basic text-to-image example, except ControlNet is passed to the control input edge point.
+- LatentsToImage

docs/features/NSFW.md

@@ -0,0 +1,93 @@
+---
+title: The NSFW Checker
+---
+
+# :material-image-off: NSFW Checker
+
+## The NSFW ("Safety") Checker
+
+The Stable Diffusion image generation models will produce sexual
+imagery if deliberately prompted, and will occasionally produce such
+images when this is not intended. Such images are colloquially known
+as "Not Safe for Work" (NSFW). This behavior is due to the nature of
+the training set that Stable Diffusion was trained on, which culled
+millions of "aesthetic" images from the Internet.
+
+You may not wish to be exposed to these images, and in some
+jurisdictions it may be illegal to publicly distribute such imagery,
+including mounting a publicly-available server that provides
+unfiltered images to the public. Furthermore, the [Stable Diffusion
+weights
+License](https://github.com/invoke-ai/InvokeAI/blob/main/LICENSE-ModelWeights.txt)
+forbids the model from being used to "exploit any of the
+vulnerabilities of a specific group of persons."
+
+For these reasons Stable Diffusion offers a "safety checker," a
+machine learning model trained to recognize potentially disturbing
+imagery. When a potentially NSFW image is detected, the checker will
+blur the image and paste a warning icon on top. The checker can be
+turned on and off on the command line using `--nsfw_checker` and
+`--no-nsfw_checker`.
+
+At installation time, InvokeAI will ask whether the checker should be
+activated by default (neither argument given on the command line). The
+response is stored in the InvokeAI initialization file
+(`invokeai.yaml` in the InvokeAI root directory).  You can change the
+default at any time by opening this file in a text editor and
+changing the line `nsfw_checker:` from true to false or vice-versa:
+
+
+```
+...
+  Features:
+    esrgan: true
+    internet_available: true
+    log_tokenization: false
+    nsfw_checker: true
+    patchmatch: true
+    restore: true
+```
+
+## Caveats
+
+There are a number of caveats that you need to be aware of.
+
+### Accuracy
+
+The checker is [not perfect](https://arxiv.org/abs/2210.04610).It will
+occasionally flag innocuous images (false positives), and will
+frequently miss violent and gory imagery (false negatives). It rarely
+fails to flag sexual imagery, but this has been known to happen. For
+these reasons, the InvokeAI team prefers to refer to the software as a
+"NSFW Checker" rather than "safety checker."
+
+### Memory Usage and Performance
+
+The NSFW checker consumes an additional 1.2G of GPU VRAM on top of the
+3.4G of VRAM used by Stable Diffusion v1.5 (this is with
+half-precision arithmetic). This means that the checker will not run
+successfully on GPU cards with less than 6GB VRAM, and will reduce the
+size of the images that you can produce.
+
+The checker also introduces a slight performance penalty. Images will
+take ~1 second longer to generate when the checker is
+activated. Generally this is not noticeable.
+
+### Intermediate Images in the Web UI
+
+The checker only operates on the final image produced by the Stable
+Diffusion algorithm. If you are using the Web UI and have enabled the
+display of intermediate images, you will briefly be exposed to a
+low-resolution (mosaicized) version of the final image before it is
+flagged by the checker and replaced by a fully blurred version. You
+are encouraged to turn **off** intermediate image rendering when you
+are using the checker. Future versions of InvokeAI will apply
+additional blurring to intermediate images when the checker is active.
+
+### Watermarking
+
+InvokeAI does not apply any sort of watermark to images it
+generates. However, it does write metadata into the PNG data area,
+including the prompt used to generate the image and relevant parameter
+settings. These fields can be examined using the `sd-metadata.py`
+script that comes with the InvokeAI package.