feat(backend): test node cache selective invalidation

invoking needs access to `node_cache_size` to occur

.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,5 +1,5 @@
 # continuous integration
-/.github/workflows/  @lstein @blessedcoolant @hipsterusername @ebr
+/.github/workflows/  @lstein @blessedcoolant @hipsterusername
 
 # documentation
 /docs/ @lstein @blessedcoolant @hipsterusername @Millu
@@ -10,7 +10,7 @@
 
 # installation and configuration
 /pyproject.toml  @lstein @blessedcoolant @hipsterusername
-/docker/  @lstein @blessedcoolant @hipsterusername @ebr
+/docker/  @lstein @blessedcoolant @hipsterusername
 /scripts/ @ebr @lstein @hipsterusername
 /installer/ @lstein @ebr @hipsterusername
 /invokeai/assets @lstein @ebr @hipsterusername
@@ -26,7 +26,9 @@
 
 # front ends
 /invokeai/frontend/CLI @lstein @hipsterusername
-/invokeai/frontend/install @lstein @ebr @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
+
+

.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/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@v4
-      with:
-        version: 8.15.6
-        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,22 +1,51 @@
-## Summary
+## What type of PR is this? (check all applicable)
 
-<!--A description of the changes in this PR. Include the kind of change (fix, feature, docs, etc), the "why" and the "how". Screenshots or videos are useful for frontend changes.-->
+- [ ] Refactor
+- [ ] Feature
+- [ ] Bug Fix
+- [ ] Optimization
+- [ ] Documentation Update
+- [ ] Community Node Submission
 
-## Related Issues / Discussions
 
-<!--WHEN APPLICABLE: List any related issues or discussions on github or discord. If this PR closes an issue, please use the "Closes #1234" format, so that the issue will be automatically closed when the PR merges.-->
+## Have you discussed this change with the InvokeAI team?
+- [ ] Yes
+- [ ] No, because:
 
-## QA Instructions
+      
+## Have you updated all relevant documentation?
+- [ ] Yes
+- [ ] No
 
-<!--WHEN APPLICABLE: Describe how you have tested the changes in this PR. Provide enough detail that a reviewer can reproduce your tests.-->
 
-## Merge Plan
+## Description
 
-<!--WHEN APPLICABLE: Large PRs, or PRs that touch sensitive things like DB schemas, may need some care when merging. For example, a careful rebase by the change author, timing to not interfere with a pending release, or a message to contributors on discord after merging.-->
 
-## Checklist
+## Related Tickets & Documents
 
-- [ ] _The PR has a short but descriptive title, suitable for a changelog_
-- [ ] _Tests added / updated (if applicable)_
-- [ ] _Documentation added / updated (if applicable)_
-- [ ] _Updated `What's New` copy (if doing a release after this PR)_
+<!--
+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. 
+-->
+
+## 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,14 +11,8 @@ on:
       - 'docker/docker-entrypoint.sh'
       - 'workflows/build-container.yml'
     tags:
-      - 'v*.*.*'
+      - 'v*'
   workflow_dispatch:
-    inputs:
-      push-to-registry:
-        description: Push the built image to the container registry
-        required: false
-        type: boolean
-        default: false
 
 permissions:
   contents: write
@@ -46,25 +40,22 @@ 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@v4
+        uses: actions/checkout@v3
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v4
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           images: |
             ghcr.io/${{ github.repository }}
+            ${{ env.DOCKERHUB_REPOSITORY }}
           tags: |
             type=ref,event=branch
             type=ref,event=tag
@@ -77,33 +68,48 @@ jobs:
             suffix=-${{ matrix.gpu-driver }},onlatest=false
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v2
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v2
         with:
           platforms: ${{ env.PLATFORMS }}
 
       - name: Login to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@v3
+        uses: docker/login-action@v2
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # - name: Login to Docker Hub
+      #   if: github.event_name != 'pull_request' && vars.DOCKERHUB_REPOSITORY != ''
+      #   uses: docker/login-action@v2
+      #   with:
+      #     username: ${{ secrets.DOCKERHUB_USERNAME }}
+      #     password: ${{ secrets.DOCKERHUB_TOKEN }}
+
       - name: Build container
-        timeout-minutes: 40
         id: docker_build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v4
         with:
           context: .
           file: docker/Dockerfile
           platforms: ${{ env.PLATFORMS }}
-          push: ${{ github.ref == 'refs/heads/main' || github.ref_type == 'tag' || github.event.inputs.push-to-registry }}
+          push: ${{ github.ref == 'refs/heads/main' || github.ref_type == 'tag' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: |
             type=gha,scope=${{ github.ref_name }}-${{ matrix.gpu-driver }}
             type=gha,scope=main-${{ matrix.gpu-driver }}
           cache-to: type=gha,mode=max,scope=${{ github.ref_name }}-${{ matrix.gpu-driver }}
+
+      # - name: Docker Hub Description
+      #   if: github.ref == 'refs/heads/main' || github.ref == 'refs/tags/*' && vars.DOCKERHUB_REPOSITORY != ''
+      #   uses: peter-evans/dockerhub-description@v3
+      #   with:
+      #     username: ${{ secrets.DOCKERHUB_USERNAME }}
+      #     password: ${{ secrets.DOCKERHUB_TOKEN }}
+      #     repository: ${{ vars.DOCKERHUB_REPOSITORY }}
+      #     short-description: ${{ github.event.repository.description }}

.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: installer
-          path: ${{ steps.create_installer.outputs.INSTALLER_PATH }}

.github/workflows/frontend-checks.yml

@@ -1,80 +0,0 @@
-# Runs frontend code quality checks.
-#
-# Checks for changes to frontend files before running the checks.
-# If always_run is true, always runs the checks.
-
-name: 'frontend checks'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-    inputs:
-      always_run:
-        description: 'Always run the checks'
-        required: true
-        type: boolean
-        default: true
-  workflow_call:
-    inputs:
-      always_run:
-        description: 'Always run the checks'
-        required: true
-        type: boolean
-        default: true
-
-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: ${{ inputs.always_run != true }}
-        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' || inputs.always_run == true }}
-        uses: ./.github/actions/install-frontend-deps
-
-      - name: tsc
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
-        run: 'pnpm lint:tsc'
-        shell: bash
-
-      - name: dpdm
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
-        run: 'pnpm lint:dpdm'
-        shell: bash
-
-      - name: eslint
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
-        run: 'pnpm lint:eslint'
-        shell: bash
-
-      - name: prettier
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
-        run: 'pnpm lint:prettier'
-        shell: bash
-
-      - name: knip
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
-        run: 'pnpm lint:knip'
-        shell: bash

.github/workflows/frontend-tests.yml

@@ -1,60 +0,0 @@
-# Runs frontend tests.
-#
-# Checks for changes to frontend files before running the tests.
-# If always_run is true, always runs the tests.
-
-name: 'frontend tests'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-    inputs:
-      always_run:
-        description: 'Always run the tests'
-        required: true
-        type: boolean
-        default: true
-  workflow_call:
-    inputs:
-      always_run:
-        description: 'Always run the tests'
-        required: true
-        type: boolean
-        default: true
-
-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: ${{ inputs.always_run != true }}
-        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' || inputs.always_run == true }}
-        uses: ./.github/actions/install-frontend-deps
-
-      - name: vitest
-        if: ${{ steps.changed-files.outputs.frontend_any_changed == 'true' || inputs.always_run == true }}
-        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,33 @@
+name: Lint frontend
+
+on:
+  pull_request:
+    types:
+      - 'ready_for_review'
+      - 'opened'
+      - 'synchronize'
+  push:
+    branches:
+      - 'main'
+  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/main'
 
 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/main' }}
+        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,76 +0,0 @@
-# Runs python code quality checks.
-#
-# Checks for changes to python files before running the checks.
-# If always_run is true, always runs the checks.
-#
-# 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:
-    inputs:
-      always_run:
-        description: 'Always run the checks'
-        required: true
-        type: boolean
-        default: true
-  workflow_call:
-    inputs:
-      always_run:
-        description: 'Always run the checks'
-        required: true
-        type: boolean
-        default: true
-
-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: ${{ inputs.always_run != true }}
-        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' || inputs.always_run == true }}
-        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' || inputs.always_run == true }}
-        run: pip install ruff==0.6.0
-        shell: bash
-
-      - name: ruff check
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || inputs.always_run == true }}
-        run: ruff check --output-format=github .
-        shell: bash
-
-      - name: ruff format
-        if: ${{ steps.changed-files.outputs.python_any_changed == 'true' || inputs.always_run == true }}
-        run: ruff format --check .
-        shell: bash

.github/workflows/python-tests.yml

@@ -1,106 +0,0 @@
-# Runs python tests on a matrix of python versions and platforms.
-#
-# Checks for changes to python files before running the tests.
-# If always_run is true, always runs the tests.
-
-name: 'python tests'
-
-on:
-  push:
-    branches:
-      - 'main'
-  pull_request:
-    types:
-      - 'ready_for_review'
-      - 'opened'
-      - 'synchronize'
-  merge_group:
-  workflow_dispatch:
-    inputs:
-      always_run:
-        description: 'Always run the tests'
-        required: true
-        type: boolean
-        default: true
-  workflow_call:
-    inputs:
-      always_run:
-        description: 'Always run the tests'
-        required: true
-        type: boolean
-        default: true
-
-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-14
-            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: ${{ inputs.always_run != true }}
-        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' || inputs.always_run == true }}
-        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' || inputs.always_run == true }}
-        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' || inputs.always_run == true }}
-        run: pytest

.github/workflows/release.yml

@@ -1,108 +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
-    with:
-      always_run: true
-
-  frontend-tests:
-    uses: ./.github/workflows/frontend-tests.yml
-    with:
-      always_run: true
-
-  python-checks:
-    uses: ./.github/workflows/python-checks.yml
-    with:
-      always_run: true
-
-  python-tests:
-    uses: ./.github/workflows/python-tests.yml
-    with:
-      always_run: true
-
-  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
-    permissions:
-      id-token: write
-    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
-    permissions:
-      id-token: write
-    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/style-checks.yml

@@ -0,0 +1,25 @@
+name: style checks
+
+on:
+  pull_request:
+  push:
+    branches: main
+
+jobs:
+  black:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies with pip
+        run: |
+          pip install black flake8 Flake8-pyproject isort
+
+      - run: isort --check-only .
+      - run: black --check .
+      - run: flake8

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

@@ -0,0 +1,129 @@
+name: Test invoke.py pip
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    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: Check for changed python files
+        id: changed-files
+        uses: tj-actions/changed-files@v37
+        with:
+          files_yaml: |
+            python:
+              - 'pyproject.toml'
+              - 'invokeai/**'
+              - '!invokeai/frontend/web/**'
+              - 'tests/**'
+
+      - name: set test prompt to main branch validation
+        if: steps.changed-files.outputs.python_any_changed == 'true'
+        run: echo "TEST_PROMPTS=tests/validate_pr_prompt.txt" >> ${{ matrix.github-env }}
+
+      - name: setup python
+        if: steps.changed-files.outputs.python_any_changed == 'true'
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: install invokeai
+        if: steps.changed-files.outputs.python_any_changed == 'true'
+        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'
+        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,5 +1,8 @@
 .idea/
 
+# ignore the Anaconda/Miniconda installer used while building Docker image
+anaconda.sh
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -16,7 +19,7 @@ __pycache__/
 .Python
 build/
 develop-eggs/
-dist/
+# dist/
 downloads/
 eggs/
 .eggs/
@@ -133,10 +136,12 @@ celerybeat.pid
 
 # Environments
 .env
-.venv*
+.venv
 env/
 venv/
 ENV/
+env.bak/
+venv.bak/
 
 # Spyder project settings
 .spyderproject
@@ -181,10 +186,14 @@ cython_debug/
 .scratch/
 .vscode/
 
+# 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
 installer/install.bat
 installer/install.sh
 installer/update.bat
 installer/update.sh
-installer/InvokeAI-Installer/

.prettierrc.yaml

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

Makefile

@@ -1,82 +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 "update-config-docstring  Update the app's config docstring so mkdocs can autogenerate it correctly."
-	@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 "frontend-typegen         Generate types for the frontend from the OpenAPI schema"
-	@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!)"
-	@echo "openapi                  Generate the OpenAPI schema for the app, outputting to stdout"
-	@echo "docs                     Serve the mkdocs site with live reload"
-
-# Runs ruff, fixing any safely-fixable errors and formatting
-ruff:
-	ruff check . --fix
-	ruff format .
-
-# 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
-
-# Update config docstring
-update-config-docstring:
-	python scripts/update_config_docstring.py
-
-# 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
-
-frontend-typegen:
-	cd invokeai/frontend/web && python ../../../scripts/generate_openapi_schema.py | pnpm typegen
-
-# Installer zip file
-installer-zip:
-	cd installer && ./create_installer.sh
-
-# Tag the release
-tag-release:
-	cd installer && ./tag_release.sh
-
-# Generate the OpenAPI Schema for the app
-openapi:
-	python scripts/generate_openapi_schema.py
-
-# Serve the mkdocs site w/ live reload
-.PHONY: docs
-docs:
-	mkdocs serve

README.md

@@ -1,142 +1,22 @@
 <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]
-
-[![discord badge]][discord link] [![latest release badge]][latest release link] [![github stars badge]][github stars link] [![github forks badge]][github forks link] [![CI checks on main badge]][CI checks on main link] [![latest commit to main badge]][latest commit to main link] [![github open issues badge]][github open issues link] [![github open prs badge]][github open prs link] [![translation status badge]][translation status link]
-
-</div>
-
-Invoke is a leading creative engine built to empower professionals and enthusiasts alike. Generate and create stunning visual media using the latest AI-driven technologies. Invoke offers an industry leading web-based UI, and serves as the foundation for multiple commercial products.
-
-Invoke is available in two editions:
-
-| **Community Edition**                                                                                                      | **Professional Edition**                                                                            |
-|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
-| **For users looking for a locally installed, self-hosted and self-managed service**                                         | **For users or teams looking for a cloud-hosted, fully managed service**                            |
-| - Free to use under a commercially-friendly license                                                                         | - Monthly subscription fee with three different plan levels                                         |
-| - Download and install on compatible hardware                                                                               | - Offers additional benefits, including multi-user support, improved model training, and more                          |
-| - Includes all core studio features: generate, refine, iterate on images, and build workflows                               | - Hosted in the cloud for easy, secure model access and scalability                                               |
-| Quick Start -> [Installation and Updates][installation docs]                                                                     | More Information -> [www.invoke.com/pricing](https://www.invoke.com/pricing)                        |
+# 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)
 
 
-![Highlighted Features - Canvas and Workflows](https://github.com/invoke-ai/InvokeAI/assets/31807370/708f7a82-084f-4860-bfbe-e2588c53548d)
+[![discord badge]][discord link]
 
-# Documentation
-| **Quick Links**                                                                                                      | 
-|----------------------------------------------------------------------------------------------------------------------------|
-|  [Installation and Updates][installation docs] - [Documentation and Tutorials][docs home] - [Bug Reports][github issues] - [Contributing][contributing docs]  | 
+[![latest release badge]][latest release link] [![github stars badge]][github stars link] [![github forks badge]][github forks link]
 
-</div>
+[![CI checks on main badge]][CI checks on main link] [![latest commit to main badge]][latest commit to main link]
 
-## Quick Start
+[![github open issues badge]][github open issues link] [![github open prs badge]][github open prs link] [![translation status badge]][translation status link]
 
-1. Download and unzip the installer from the bottom of the [latest release][latest release link].
-2. Run the installer script.
-
-   - **Windows**: Double-click on the `install.bat` script.
-   - **macOS**: Open a Terminal window, drag the file `install.sh` from Finder into the Terminal, and press enter.
-   - **Linux**: Run `install.sh`.
-
-3. When prompted, enter a location for the install and select your GPU type.
-4. Once the install finishes, find the directory you selected during install. The default location is `C:\Users\Username\invokeai` for Windows or `~/invokeai` for Linux/macOS.
-5. Run the launcher script (`invoke.bat` for Windows, `invoke.sh` for macOS and Linux) the same way you ran the installer script in step 2.
-6. Select option 1 to start the application. Once it starts up, open your browser and go to <http://localhost:9090>.
-7. Open the model manager tab to install a starter model and then you'll be ready to generate.
-
-More detail, including hardware requirements and manual install instructions, are available in the [installation documentation][installation docs].
-
-## Docker Container
-
-We publish official container images in Github Container Registry: https://github.com/invoke-ai/InvokeAI/pkgs/container/invokeai. Both CUDA and ROCm images are available. Check the above link for relevant tags.
-
-> [!IMPORTANT]
-> Ensure that Docker is set up to use the GPU. Refer to [NVIDIA][nvidia docker docs] or [AMD][amd docker docs] documentation.
-
-### Generate!
-
-Run the container, modifying the command as necessary:
-
-```bash
-docker run --runtime=nvidia --gpus=all --publish 9090:9090 ghcr.io/invoke-ai/invokeai
-```
-
-Then open `http://localhost:9090` and install some models using the Model Manager tab to begin generating.
-
-For ROCm, add `--device /dev/kfd --device /dev/dri` to the `docker run` command.
-
-### Persist your data
-
-You will likely want to persist your workspace outside of the container. Use the `--volume /home/myuser/invokeai:/invokeai` flag to mount some local directory (using its **absolute** path) to the `/invokeai` path inside the container. Your generated images and models will reside there. You can use this directory with other InvokeAI installations, or switch between runtime directories as needed.
-
-### DIY
-
-Build your own image and customize the environment to match your needs using our `docker-compose` stack. See [README.md](./docker/README.md) in the [docker](./docker) directory.
-
-## Troubleshooting, FAQ and Support
-
-Please review our [FAQ][faq] for solutions to common installation problems and other issues.
-
-For more help, please join our [Discord][discord link].
-
-## Features
-
-Full details on features can be found in [our documentation][features docs].
-
-### Web Server & UI
-
-Invoke runs a locally hosted web server & React UI with an industry-leading user experience.
-
-### Unified Canvas
-
-The Unified Canvas is a fully integrated canvas implementation with support for all core generation capabilities, in/out-painting, 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
-
-Invoke offers a fully featured workflow management solution, enabling users to combine the power of node-based workflows with the easy of a UI. This allows for customizable generation pipelines to be developed and shared by users looking to create specific workflows to support their production use-cases.
-
-### Board & Gallery Management
-
-Invoke features an organized gallery system for easily storing, accessing, and remixing your content in the Invoke workspace. Images can be dragged/dropped onto any Image-base UI element in the application, and rich metadata within the Image allows for easy recall of key prompts or settings used in your workflow.
-
-### Other features
-
-- Support for both ckpt and diffusers models
-- SD1.5, SD2.0, SDXL, and FLUX support
-- Upscaling Tools
-- Embedding Manager & Support
-- Model Manager & Support
-- Workflow creation & management
-- Node-Based Architecture
-
-## 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][contributing docs], joining the [#dev-chat] or the GitHub discussion board.
-
-We hope you enjoy using Invoke as much as we enjoy creating it, and we hope you will elect to become part of our community.
-
-## Thanks
-
-Invoke is a combined effort of [passionate and talented people from across the world][contributors]. We thank them for their time, hard work and effort.
-
-Original portions of the software are Copyright © 2024 by respective contributors.
-
-[features docs]: https://invoke-ai.github.io/InvokeAI/features/database/
-[faq]: https://invoke-ai.github.io/InvokeAI/faq/
-[contributors]: https://invoke-ai.github.io/InvokeAI/contributing/contributors/
-[invoke.com]: https://www.invoke.com/about
-[github issues]: https://github.com/invoke-ai/InvokeAI/issues
-[docs home]: https://invoke-ai.github.io/InvokeAI
-[installation docs]: https://invoke-ai.github.io/InvokeAI/installation/
-[#dev-chat]: https://discord.com/channels/1020123559063990373/1049495067846524939
-[contributing docs]: https://invoke-ai.github.io/InvokeAI/contributing/
 [CI checks on main badge]: https://flat.badgen.net/github/checks/invoke-ai/InvokeAI/main?label=CI%20status%20on%20main&cache=900&icon=github
-[CI checks on main link]: https://github.com/invoke-ai/InvokeAI/actions?query=branch%3Amain
+[CI checks on main link]:https://github.com/invoke-ai/InvokeAI/actions?query=branch%3Amain
 [discord badge]: https://flat.badgen.net/discord/members/ZmtBAhwWhy?icon=discord
 [discord link]: https://discord.gg/ZmtBAhwWhy
 [github forks badge]: https://flat.badgen.net/github/forks/invoke-ai/InvokeAI?icon=github
@@ -150,8 +30,400 @@ Original portions of the software are Copyright © 2024 by respective contributo
 [latest commit to main badge]: https://flat.badgen.net/github/last-commit/invoke-ai/InvokeAI/main?icon=github&color=yellow&label=last%20dev%20commit&cache=900
 [latest commit to main link]: https://github.com/invoke-ai/InvokeAI/commits/main
 [latest release badge]: https://flat.badgen.net/github/release/invoke-ai/InvokeAI/development?icon=github
-[latest release link]: https://github.com/invoke-ai/InvokeAI/releases/latest
+[latest release link]: https://github.com/invoke-ai/InvokeAI/releases
 [translation status badge]: https://hosted.weblate.org/widgets/invokeai/-/svg-badge.svg
 [translation status link]: https://hosted.weblate.org/engage/invokeai/
-[nvidia docker docs]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
-[amd docker docs]: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html
+
+</div>
+
+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
+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
+  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>]
+  [<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>] 
+
+<div align="center">
+
+![canvas preview](https://github.com/invoke-ai/InvokeAI/raw/main/docs/assets/canvas_preview.png)
+
+</div>
+
+## Table of Contents
+
+Table of Contents 📝
+
+**Getting Started**
+1. 🏁 [Quick Start](#quick-start) 
+3. 🖥️ [Hardware Requirements](#hardware-requirements) 
+
+**More About Invoke**
+1. 🌟 [Features](#features) 
+2. 📣 [Latest Changes](#latest-changes) 
+3. 🛠️ [Troubleshooting](#troubleshooting) 
+
+**Supporting the Project**
+1. 🤝 [Contributing](#contributing) 
+2. 👥 [Contributors](#contributors) 
+3. 💕 [Support](#support) 
+
+## Quick Start
+
+For full installation and upgrade instructions, please see:
+[InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/INSTALLATION/)
+
+If upgrading from version 2.3, please read [Migrating a 2.3 root
+directory to 3.0](#migrating-to-3) first.
+
+### Automatic Installer (suggested for 1st time users)
+
+1. Go to the bottom of the [Latest Release Page](https://github.com/invoke-ai/InvokeAI/releases/latest)
+
+2. Download the .zip file for your OS (Windows/macOS/Linux).
+
+3. Unzip the file.
+
+4. **Windows:** double-click on the `install.bat` script. **macOS:** Open a Terminal window, drag the file `install.sh` from Finder
+into the Terminal, and press return. **Linux:** run `install.sh`.
+
+5. You'll be asked to confirm the location of the folder in which
+to install InvokeAI and its image generation model files. Pick a
+location with at least 15 GB of free memory. More if you plan on
+installing lots of models.
+
+6. Wait while the installer does its thing. After installing the software,
+the installer will launch a script that lets you configure InvokeAI and
+select a set of starting image generation models.
+
+7. Find the folder that InvokeAI was installed into (it is not the
+same as the unpacked zip file directory!) The default location of this
+folder (if you didn't change it in step 5) is `~/invokeai` on
+Linux/Mac systems, and `C:\Users\YourName\invokeai` on Windows. This directory will contain launcher scripts named `invoke.sh` and `invoke.bat`.
+
+8. On Windows systems, double-click on the `invoke.bat` file. On
+macOS, open a Terminal window, drag `invoke.sh` from the folder into
+the Terminal, and press return. On Linux, run `invoke.sh`
+
+9. Press 2 to open the "browser-based UI", press enter/return, wait a
+minute or two for Stable Diffusion to start up, then open your browser
+and go to http://localhost:9090.
+
+10. Type `banana sushi` in the box on the top left and click `Invoke`
+
+### Command-Line Installation (for developers and users familiar with Terminals)
+
+You must have Python 3.9 through 3.11 installed on your machine. Earlier or
+later versions are not supported.
+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:
+
+    ```terminal
+    mkdir invokeai
+    ````
+
+3. Create a virtual environment named `.venv` inside this directory and activate it:
+
+    ```terminal
+    cd invokeai
+    python -m venv .venv --prompt InvokeAI
+    ```
+
+4. Activate the virtual environment (do it every time you run InvokeAI)
+
+    _For Linux/Mac users:_
+
+    ```sh
+    source .venv/bin/activate
+    ```
+
+    _For Windows users:_
+
+    ```ps
+    .venv\Scripts\activate
+    ```
+
+5. Install the InvokeAI module and its dependencies. Choose the command suited for your platform & GPU.
+
+    _For Windows/Linux with an NVIDIA GPU:_
+
+    ```terminal
+    pip install "InvokeAI[xformers]" --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu118
+    ```
+
+    _For Linux with an AMD GPU:_
+
+    ```sh
+    pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.4.2
+    ```
+
+    _For non-GPU systems:_
+    ```terminal
+    pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/cpu
+    ``` 
+
+    _For Macintoshes, either Intel or M1/M2:_
+
+    ```sh
+    pip install InvokeAI --use-pep517
+    ```
+
+6. Configure InvokeAI and install a starting set of image generation models (you only need to do this once):
+
+    ```terminal
+    invokeai-configure --root .
+    ```
+	Don't miss the dot at the end!
+
+7. Launch the web server (do it every time you run InvokeAI):
+
+    ```terminal
+    invokeai-web
+    ```
+
+8. Point your browser to http://localhost:9090 to bring up the web interface.
+
+9. 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`.
+
+## Detailed Installation Instructions
+
+This fork is supported across Linux, Windows and Macintosh. Linux
+users can use either an Nvidia-based card (with CUDA support) or an
+AMD card (using the ROCm driver). For full installation and upgrade
+instructions, please see:
+[InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/INSTALL_SOURCE/)
+
+<a name="migrating-to-3"></a>
+### Migrating a v2.3 InvokeAI root directory
+
+The InvokeAI root directory is where the InvokeAI startup file,
+installed models, and generated images are stored. It is ordinarily
+named `invokeai` and located in your home directory. The contents and
+layout of this directory has changed between versions 2.3 and 3.0 and
+cannot be used directly.
+
+We currently recommend that you use the installer to create a new root
+directory named differently from the 2.3 one, e.g. `invokeai-3` and
+then use a migration script to copy your 2.3 models into the new
+location. However, if you choose, you can upgrade this directory in
+place.  This section gives both recipes.
+
+#### Creating a new root directory and migrating old models
+
+This is the safer recipe because it leaves your old root directory in
+place to fall back on.
+
+1. Follow the instructions above to create and install InvokeAI in a
+directory that has a different name from the 2.3 invokeai directory.
+In this example, we will use "invokeai-3"
+
+2. When you are prompted to select models to install, select a minimal
+set of models, such as stable-diffusion-v1.5 only.
+
+3. After installation is complete launch `invokeai.sh` (Linux/Mac) or
+`invokeai.bat` and select option 8 "Open the developers console". This
+will take you to the command line.
+
+4. Issue the command `invokeai-migrate3 --from /path/to/v2.3-root --to
+/path/to/invokeai-3-root`. Provide the correct `--from` and `--to`
+paths for your v2.3 and v3.0 root directories respectively.
+
+This will copy and convert your old models from 2.3 format to 3.0
+format and create a new `models` directory in the 3.0 directory. The
+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:
+
+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.
+
+4. Once the upgrade is finished you will be returned to the launcher
+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
+update it to the 3.0 format. The following files will be replaced:
+
+  - The invokeai.init file, replaced by invokeai.yaml
+  - The models directory
+  - The configs/models.yaml model index
+  
+The original versions of these files will be saved with the suffix
+".orig" appended to the end. Once you have confirmed that the upgrade
+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
+
+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.)
+
+## Hardware Requirements
+
+InvokeAI is supported across Linux, Windows and macOS. Linux
+users can use either an Nvidia-based card (with CUDA support) or an
+AMD card (using the ROCm driver).
+
+### System
+
+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 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.
+
+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
+to render 512x512 images.
+
+**Memory** - At least 12 GB Main Memory RAM.
+
+**Disk** - At least 12 GB of free disk space for the machine learning model, Python, and all its dependencies.
+
+## Features
+
+Feature documentation can be reviewed by navigating to [the InvokeAI Documentation page](https://invoke-ai.github.io/InvokeAI/features/)
+
+### *Web Server & UI*
+
+InvokeAI offers a locally hosted Web Server & React Frontend, with an industry leading user experience. The Web-based UI allows for simple and intuitive workflows, and is responsive for use on mobile devices and tablets accessing the web server.
+
+### *Unified Canvas*
+
+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*
+
+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.
+
+### *Board & Gallery Management*
+
+Invoke AI provides an organized gallery system for easily storing, accessing, and remixing your content in the Invoke workspace. Images can be dragged/dropped onto any Image-base UI element in the application, and rich metadata within the Image allows for easy recall of key prompts or settings used in your workflow. 
+
+### Other features
+
+- *Support for both ckpt and diffusers models*
+- *SD 2.0, 2.1, XL support*
+- *Upscaling Tools*
+- *Embedding Manager & Support*
+- *Model Manager & Support*
+- *Workflow creation & management*
+- *Node-Based Architecture*
+
+
+### Latest Changes
+
+For our latest changes, view our [Release
+Notes](https://github.com/invoke-ai/InvokeAI/releases) and the
+[CHANGELOG](docs/CHANGELOG.md).
+
+### Troubleshooting
+
+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. For more help, please join our [Discord][discord link]
+
+## 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.
+
+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/).
+
+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 community.
+
+Welcome to InvokeAI!
+
+### Contributors
+
+This fork is a combined effort of various 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.
+
+### Support
+
+For support, please use this repository's GitHub Issues tracking service, or join the [Discord][discord link].
+
+Original portions of the software are Copyright (c) 2023 by respective contributors.
+

SECURITY.md

@@ -1,14 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Only the latest version of Invoke will receive security updates. 
-We do not currently maintain multiple versions of the application with updates.
-
-## Reporting a Vulnerability
-
-To report a vulnerability, contact the Invoke team directly at security@invoke.ai
-
-At this time, we do not maintain a formal bug bounty program. 
-
-You can also share identified security issues with our team on huntr.com

docker/.env.sample

@@ -1,27 +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.
 
-## INVOKEAI_ROOT is the path *on the host system* where Invoke will store its data.
-## It is mounted into the container and allows both containerized and non-containerized usage of Invoke.
-# Usually this is the only variable you need to set. It can be relative or absolute.
-# INVOKEAI_ROOT=~/invokeai
+# 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.
+# This **must** be an absolute path.
+INVOKEAI_ROOT=
 
-## HOST_INVOKEAI_ROOT and CONTAINER_INVOKEAI_ROOT can be used to control the on-host
-## and in-container paths separately, if needed.
-## HOST_INVOKEAI_ROOT is the path on the docker host's filesystem where Invoke will store data.
-## If relative, it will be relative to the docker directory in which the docker-compose.yml file is located
-## CONTAINER_INVOKEAI_ROOT is the path within the container where Invoke will expect to find the runtime directory.
-## It MUST be absolute. There is usually no need to change this.
-# HOST_INVOKEAI_ROOT=../../invokeai-data
-# CONTAINER_INVOKEAI_ROOT=/invokeai
+HUGGINGFACE_TOKEN=
 
-## INVOKEAI_PORT is the port on which the InvokeAI web interface will be available
-# INVOKEAI_PORT=9090
-
-## GPU_DRIVER can be set to either `cuda` or `rocm` to enable GPU support in the container accordingly.
-# GPU_DRIVER=cuda #| rocm
-
-## CONTAINER_UID can be set to the UID of the user on the host system that should own the files in the container.
-## It is usually not necessary to change this. Use `id -u` on the host system to find the UID.
-# CONTAINER_UID=1000
+## optional variables specific to the docker setup
+# GPU_DRIVER=cuda
+# CONTAINER_UID=1000

docker/Dockerfile

@@ -2,77 +2,75 @@
 
 ## Builder stage
 
-FROM library/ubuntu:24.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
 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 \
-        build-essential \
-        git
+        git \
+        python3.10-venv \
+        python3-pip \
+        build-essential
 
-# Install `uv` for package management
-COPY --from=ghcr.io/astral-sh/uv:0.5.5 /uv /uvx /bin/
-
-ENV VIRTUAL_ENV=/opt/venv
-ENV PATH="$VIRTUAL_ENV/bin:$PATH"
 ENV INVOKEAI_SRC=/opt/invokeai
-ENV PYTHON_VERSION=3.11
-ENV UV_COMPILE_BYTECODE=1
-ENV UV_LINK_MODE=copy
+ENV VIRTUAL_ENV=/opt/venv/invokeai
 
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+ARG TORCH_VERSION=2.0.1
+ARG TORCHVISION_VERSION=0.15.2
 ARG GPU_DRIVER=cuda
 ARG TARGETPLATFORM="linux/amd64"
 # unused but available
 ARG BUILDPLATFORM
 
-# Switch to the `ubuntu` user to work around dependency issues with uv-installed python
-RUN mkdir -p ${VIRTUAL_ENV} && \
-    mkdir -p ${INVOKEAI_SRC} && \
-    chmod -R a+w /opt
-USER ubuntu
-
-# Install python and create the venv
-RUN uv python install ${PYTHON_VERSION} && \
-    uv venv --relocatable --prompt "invoke" --python ${PYTHON_VERSION} ${VIRTUAL_ENV}
-
 WORKDIR ${INVOKEAI_SRC}
-COPY invokeai ./invokeai
-COPY pyproject.toml ./
 
-# Editable mode helps use the same image for development:
-# the local working copy can be bind-mounted into the image
-# at path defined by ${INVOKEAI_SRC}
+# Install pytorch before all other pip packages
 # NOTE: there are no pytorch builds for arm64 + cuda, only cpu
-# x86_64/CUDA is the default
-RUN --mount=type=cache,target=/home/ubuntu/.cache/uv,uid=1000,gid=1000 \
+# x86_64/CUDA is default
+RUN --mount=type=cache,target=/root/.cache/pip \
+    python3 -m venv ${VIRTUAL_ENV} &&\
     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/rocm6.1"; \
+        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/cu124"; \
-    fi && \
-    uv pip install --python ${PYTHON_VERSION} $extra_index_url_arg -e "."
+        extra_index_url_arg="--extra-index-url https://download.pytorch.org/whl/cu118"; \
+    fi &&\
+    pip install $extra_index_url_arg \
+        torch==$TORCH_VERSION \
+        torchvision==$TORCHVISION_VERSION
 
-#### Build the Web UI ------------------------------------
+# Install the local package.
+# Editable mode helps use the same image for development:
+# the local working copy can be bind-mounted into the image
+# at path defined by ${INVOKEAI_SRC}
+COPY invokeai ./invokeai
+COPY pyproject.toml ./
+RUN --mount=type=cache,target=/root/.cache/pip \
+    # xformers + triton fails to install on arm64
+    if [ "$GPU_DRIVER" = "cuda" ] && [ "$TARGETPLATFORM" = "linux/amd64" ]; then \
+        pip install -e ".[xformers]"; \
+    else \
+        pip install -e "."; \
+    fi
 
-FROM node:20-slim AS web-builder
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack use pnpm@8.x
-RUN corepack enable
+# #### Build the Web UI ------------------------------------
 
+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:24.04 AS runtime
+FROM library/ubuntu:22.04 AS runtime
 
 ARG DEBIAN_FRONTEND=noninteractive
 ENV PYTHONUNBUFFERED=1
@@ -87,32 +85,24 @@ RUN apt update && apt install -y --no-install-recommends \
         iotop \
         bzip2 \
         gosu \
-        magic-wormhole \
         libglib2.0-0 \
-        libgl1 \
-        libglx-mesa0 \
+        libgl1-mesa-glx \
+        python3-venv \
+        python3-pip \
         build-essential \
         libopencv-dev \
         libstdc++-10-dev &&\
     apt-get clean && apt-get autoclean
 
-ENV INVOKEAI_SRC=/opt/invokeai
-ENV VIRTUAL_ENV=/opt/venv
-ENV PYTHON_VERSION=3.11
-ENV INVOKEAI_ROOT=/invokeai
-ENV INVOKEAI_HOST=0.0.0.0
-ENV INVOKEAI_PORT=9090
-ENV PATH="$VIRTUAL_ENV/bin:$INVOKEAI_SRC:$PATH"
-ENV CONTAINER_UID=${CONTAINER_UID:-1000}
-ENV CONTAINER_GID=${CONTAINER_GID:-1000}
+# 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
 
-# Install `uv` for package management
-# and install python for the ubuntu user (expected to exist on ubuntu >=24.x)
-# this is too tiny to optimize with multi-stage builds, but maybe we'll come back to it
-COPY --from=ghcr.io/astral-sh/uv:0.5.5 /uv /uvx /bin/
-USER ubuntu
-RUN uv python install ${PYTHON_VERSION}
-USER root
+ENV INVOKEAI_SRC=/opt/invokeai
+ENV VIRTUAL_ENV=/opt/venv/invokeai
+ENV INVOKEAI_ROOT=/invokeai
+ENV PATH="$VIRTUAL_ENV/bin:$INVOKEAI_SRC:$PATH"
 
 # --link requires buldkit w/ dockerfile syntax 1.4
 COPY --link --from=builder ${INVOKEAI_SRC} ${INVOKEAI_SRC}
@@ -128,10 +118,12 @@ WORKDIR ${INVOKEAI_SRC}
 
 # build patchmatch
 RUN cd /usr/lib/$(uname -p)-linux-gnu/pkgconfig/ && ln -sf opencv4.pc opencv.pc
-RUN python -c "from patchmatch import patch_match"
+RUN 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"]
-CMD ["invokeai-web"]
+CMD ["invokeai-web", "--host", "0.0.0.0"]

docker/README.md

@@ -1,88 +1,34 @@
-# Invoke in Docker
+# InvokeAI Containerized
 
-First things first:
-
-- Ensure that Docker can use your [NVIDIA][nvidia docker docs] or [AMD][amd docker docs] GPU.
-- This document assumes a Linux system, but should work similarly under Windows with WSL2.
-- We don't recommend running Invoke in Docker on macOS at this time. It works, but very slowly.
-
-## Quickstart
-
-No `docker compose`, no persistence, single command, using the official images:
-
-**CUDA (NVIDIA GPU):**
-
-```bash
-docker run --runtime=nvidia --gpus=all --publish 9090:9090 ghcr.io/invoke-ai/invokeai
-```
-
-**ROCm (AMD GPU):**
-
-```bash
-docker run --device /dev/kfd --device /dev/dri --publish 9090:9090 ghcr.io/invoke-ai/invokeai:main-rocm
-```
-
-Open `http://localhost:9090` in your browser once the container finishes booting, install some models, and generate away!
-
-### Data persistence
-
-To persist your generated images and downloaded models outside of the container, add a `--volume/-v` flag to the above command, e.g.:
-
-```bash
-docker run --volume /some/local/path:/invokeai {...etc...}
-```
-
-`/some/local/path/invokeai` will contain all your data.
-It can *usually* be reused between different installs of Invoke. Tread with caution and read the release notes!
-
-## Customize the container
-
-The included `run.sh` script is a convenience wrapper around `docker compose`. It can be helpful for passing additional build arguments to `docker compose`. Alternatively, the familiar `docker compose` commands work just as well.
-
-```bash
-cd docker
-cp .env.sample .env
-# edit .env to your liking if you need to; it is well commented.
-./run.sh
-```
-
-It will take a few minutes to build the image the first time. Once the application starts up, open `http://localhost:9090` in your browser to invoke!
-
->[!TIP]
->When using the `run.sh` script, the container will continue running after Ctrl+C. To shut it down, use the `docker compose down` command.
-
-## Docker setup in detail
+All commands are to be run from the `docker` directory: `cd docker`
 
 #### Linux
 
-1. Ensure buildkit 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).
-    - The deprecated `docker-compose` (hyphenated) CLI probably won't work. Update to a recent version.
+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://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.
-    - [NVIDIA docs](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
-    - [AMD docs](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html)
+    - You may need to install [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
 
 #### macOS
 
-> [!TIP]
-> You'll be better off installing Invoke directly on your system, because Docker can not use the GPU on macOS.
-
-If you are still reading:
-
 1. Ensure Docker has at least 16GB RAM
 2. Enable VirtioFS for file sharing
 3. Enable `docker compose` V2 support
 
-This is done via Docker Desktop preferences.
+This is done via Docker Desktop preferences
 
-### Configure the 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 the desired location of the InvokeAI runtime directory. It may be an existing directory from a previous installation (post 4.0.0).
-1. Execute `run.sh`
+
+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. `docker compose up`
 
 The image will be built automatically if needed.
 
-The runtime directory (holding models and outputs) will be created in the location specified by `INVOKEAI_ROOT`. The default location is `~/invokeai`. Navigate to the Model Manager tab and install some models before generating.
+The runtime directory (holding models and outputs) will be created in the location specified by `INVOKEAI_ROOT`. The default location is `~/invokeai`. The runtime directory will be populated with the base configs and models necessary to start generating.
 
 ### Use a GPU
 
@@ -90,28 +36,42 @@ The runtime directory (holding models and outputs) will be created in the locati
 - WSL2 is *required* for Windows.
 - only `x86_64` architecture is supported.
 
-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/NVIDIA/AMD 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 before running `./run.sh`.
+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.
 
 ## 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=cuda
 ```
 
-Any environment variables supported by InvokeAI can be set here. See the [Configuration docs](https://invoke-ai.github.io/InvokeAI/features/CONFIGURATION/) for further detail.
+## Even Moar Customizing!
 
----
+See the `docker compose.yaml` file. The `command` instruction can be uncommented and used to run arbitrary startup commands. Some examples below.
 
-[nvidia docker docs]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
-[amd docker docs]: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html
+### Reconfigure the runtime directory
+
+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
+
+```
+command:
+  - invokeai-configure
+  - --yes
+```
+
+Or install models:
+
+```
+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

@@ -1,37 +1,13 @@
 # Copyright (c) 2023 Eugene Brodsky https://github.com/ebr
 
-x-invokeai: &invokeai
-    image: "ghcr.io/invoke-ai/invokeai:latest"
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-
-    # Create a .env file in the same directory as this docker-compose.yml file
-    # and populate it with environment variables. See .env.sample
-    env_file:
-      - .env
-
-    # variables without a default will automatically inherit from the host environment
-    environment:
-      # if set, CONTAINER_INVOKEAI_ROOT will override the Invoke runtime directory location *inside* the container
-      - INVOKEAI_ROOT=${CONTAINER_INVOKEAI_ROOT:-/invokeai}
-      - HF_HOME
-    ports:
-      - "${INVOKEAI_PORT:-9090}:${INVOKEAI_PORT:-9090}"
-    volumes:
-      - type: bind
-        source: ${HOST_INVOKEAI_ROOT:-${INVOKEAI_ROOT:-~/invokeai}}
-        target: ${CONTAINER_INVOKEAI_ROOT:-/invokeai}
-        bind:
-          create_host_path: true
-      - ${HF_HOME:-~/.cache/huggingface}:${HF_HOME:-/invokeai/.cache/huggingface}
-    tty: true
-    stdin_open: true
-
+version: '3.8'
 
 services:
-  invokeai-cuda:
-    <<: *invokeai
+  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:
@@ -39,16 +15,34 @@ services:
             - driver: nvidia
               count: 1
               capabilities: [gpu]
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
 
-  invokeai-cpu:
-    <<: *invokeai
-    profiles:
-      - cpu
+    # variables without a default will automatically inherit from the host environment
+    environment:
+      - INVOKEAI_ROOT
+      - HF_HOME
 
-  invokeai-rocm:
-    <<: *invokeai
-    devices:
-      - /dev/kfd:/dev/kfd
-      - /dev/dri:/dev/dri
-    profiles:
-      - rocm
+    # Create a .env file in the same directory as this docker-compose.yml file
+    # and populate it with environment variables. See .env.sample
+    env_file:
+      - .env
+
+    ports:
+      - "${INVOKEAI_PORT:-9090}:9090"
+    volumes:
+      - ${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}}
+    tty: true
+    stdin_open: true
+
+    # # Example of running alternative commands/scripts in the container
+    # command:
+    #   - bash
+    #   - -c
+    #   - |
+    #     invokeai-model-install --yes --default-only --config_file ${INVOKEAI_ROOT}/config_custom.yaml
+    #     invokeai-nodes-web --host 0.0.0.0

docker/docker-entrypoint.sh

@@ -9,38 +9,57 @@ set -e -o pipefail
 ### Set INVOKEAI_ROOT pointing to a valid runtime directory
 # Otherwise configure the runtime dir first.
 
+### Configure the InvokeAI runtime directory (done by default)):
+# docker run --rm -it <this image> --configure
+# or skip with --no-configure
+
 ### Set the CONTAINER_UID envvar to match your user.
 # Ensures files created in the container are owned by you:
 #   docker run --rm -it -v /some/path:/invokeai -e CONTAINER_UID=$(id -u) <this image>
 # Default UID: 1000 chosen due to popularity on Linux systems. Possibly 501 on MacOS.
 
 USER_ID=${CONTAINER_UID:-1000}
-USER=ubuntu
-# if the user does not exist, create it. It is expected to be present on ubuntu >=24.x
-_=$(id ${USER} 2>&1) || useradd -u ${USER_ID} ${USER}
-# ensure the UID is correct
+USER=invoke
 usermod -u ${USER_ID} ${USER} 1>/dev/null
 
+configure() {
+    # Configure the runtime directory
+    if [[ -f ${INVOKEAI_ROOT}/invokeai.yaml ]]; then
+        echo "${INVOKEAI_ROOT}/invokeai.yaml exists. InvokeAI is already configured."
+        echo "To reconfigure InvokeAI, delete the above file."
+        echo "======================================================================"
+    else
+        mkdir -p "${INVOKEAI_ROOT}"
+        chown --recursive ${USER} "${INVOKEAI_ROOT}"
+        gosu ${USER} invokeai-configure --yes --default_only
+    fi
+}
+
+## Skip attempting to configure.
+## Must be passed first, before any other args.
+if [[ $1 != "--no-configure" ]]; then
+    configure
+else
+    shift
+fi
+
 ### Set the $PUBLIC_KEY env var to enable SSH access.
 # We do not install openssh-server in the image by default to avoid bloat.
 # but it is useful to have the full SSH server e.g. on Runpod.
 # (use SCP to copy files to/from the image, etc)
 if [[ -v "PUBLIC_KEY" ]] && [[ ! -d "${HOME}/.ssh" ]]; then
-  apt-get update
-  apt-get install -y openssh-server
-  pushd "$HOME"
-  mkdir -p .ssh
-  echo "${PUBLIC_KEY}" >.ssh/authorized_keys
-  chmod -R 700 .ssh
-  popd
-  service ssh start
+    apt-get update
+    apt-get install -y openssh-server
+    pushd "$HOME"
+    mkdir -p .ssh
+    echo "${PUBLIC_KEY}" > .ssh/authorized_keys
+    chmod -R 700 .ssh
+    popd
+    service ssh start
 fi
 
-mkdir -p "${INVOKEAI_ROOT}"
-chown --recursive ${USER} "${INVOKEAI_ROOT}" || true
+
 cd "${INVOKEAI_ROOT}"
-export HF_HOME=${HF_HOME:-$INVOKEAI_ROOT/.cache/huggingface}
-export MPLCONFIGDIR=${MPLCONFIGDIR:-$INVOKEAI_ROOT/.matplotlib}
 
 # Run the CMD as the Container User (not root).
 exec gosu ${USER} "$@"

docker/run.sh

@@ -1,36 +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=""
-
-  # create .env file if it doesn't exist, otherwise docker compose will fail
-  touch .env
-
-  # parse .env file for build args
-  build_args=$(awk '$1 ~ /=[^$]/ && $0 !~ /^#/ {print "--build-arg " $0 " "}' .env) &&
-  profile="$(awk -F '=' '/GPU_DRIVER/ {print $2}' .env)"
-
-  # default to 'cuda' profile
-  [[ -z "$profile" ]] && profile="cuda"
-
-  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

@@ -0,0 +1,815 @@
+---
+title: Changelog
+---
+
+# :octicons-log-16: **Changelog**
+
+## v2.3.5 <small>(22 May 2023)</small>
+
+This release (along with the post1 and post2 follow-on releases) expands support for additional LoRA and LyCORIS models, upgrades diffusers versions, and fixes a few bugs.
+
+### LoRA and LyCORIS Support Improvement
+
+    A number of LoRA/LyCORIS fine-tune files (those which alter the text encoder as well as the unet model) were not having the desired effect in InvokeAI. This bug has now been fixed. Full documentation of LoRA support is available at InvokeAI LoRA Support.
+    Previously, InvokeAI did not distinguish between LoRA/LyCORIS models based on Stable Diffusion v1.5 vs those based on v2.0 and 2.1, leading to a crash when an incompatible model was loaded. This has now been fixed. In addition, the web pulldown menus for LoRA and Textual Inversion selection have been enhanced to show only those files that are compatible with the currently-selected Stable Diffusion model.
+    Support for the newer LoKR LyCORIS files has been added.
+
+### Library Updates and Speed/Reproducibility Advancements
+The major enhancement in this version is that NVIDIA users no longer need to decide between speed and reproducibility. Previously, if you activated the Xformers library, you would see improvements in speed and memory usage, but multiple images generated with the same seed and other parameters would be slightly different from each other. This is no longer the case. Relative to 2.3.5 you will see improved performance when running without Xformers, and even better performance when Xformers is activated. In both cases, images generated with the same settings will be identical.
+
+Here are the new library versions:
+Library 	Version
+Torch 	2.0.0
+Diffusers 	0.16.1
+Xformers 	0.0.19
+Compel 	1.1.5
+Other Improvements
+
+### Performance Improvements
+
+    When a model is loaded for the first time, InvokeAI calculates its checksum for incorporation into the PNG metadata. This process could take up to a minute on network-mounted disks and WSL mounts. This release noticeably speeds up the process.
+
+### Bug Fixes
+
+    The "import models from directory" and "import from URL" functionality in the console-based model installer has now been fixed.
+    When running the WebUI, we have reduced the number of times that InvokeAI reaches out to HuggingFace to fetch the list of embeddable Textual Inversion models. We have also caught and fixed a problem with the updater not correctly detecting when another instance of the updater is running 
+
+
+## v2.3.4 <small>(7 April 2023)</small>
+
+What's New in 2.3.4
+
+This features release adds support for LoRA (Low-Rank Adaptation) and LyCORIS (Lora beYond Conventional) models, as well as some minor bug fixes.
+### LoRA and LyCORIS Support
+
+LoRA files contain fine-tuning weights that enable particular styles, subjects or concepts to be applied to generated images. LyCORIS files are an extended variant of LoRA. InvokeAI supports the most common LoRA/LyCORIS format, which ends in the suffix .safetensors. You will find numerous LoRA and LyCORIS models for download at Civitai, and a small but growing number at Hugging Face. Full documentation of LoRA support is available at InvokeAI LoRA Support.( Pre-release note: this page will only be available after release)
+
+To use LoRA/LyCORIS models in InvokeAI:
+
+    Download the .safetensors files of your choice and place in /path/to/invokeai/loras. This directory was not present in earlier version of InvokeAI but will be created for you the first time you run the command-line or web client. You can also create the directory manually.
+
+    Add withLora(lora-file,weight) to your prompts. The weight is optional and will default to 1.0. A few examples, assuming that a LoRA file named loras/sushi.safetensors is present:
+
+family sitting at dinner table eating sushi withLora(sushi,0.9)
+family sitting at dinner table eating sushi withLora(sushi, 0.75)
+family sitting at dinner table eating sushi withLora(sushi)
+
+Multiple withLora() prompt fragments are allowed. The weight can be arbitrarily large, but the useful range is roughly 0.5 to 1.0. Higher weights make the LoRA's influence stronger. Negative weights are also allowed, which can lead to some interesting effects.
+
+    Generate as you usually would! If you find that the image is too "crisp" try reducing the overall CFG value or reducing individual LoRA weights. As is the case with all fine-tunes, you'll get the best results when running the LoRA on top of the model similar to, or identical with, the one that was used during the LoRA's training. Don't try to load a SD 1.x-trained LoRA into a SD 2.x model, and vice versa. This will trigger a non-fatal error message and generation will not proceed.
+
+    You can change the location of the loras directory by passing the --lora_directory option to `invokeai.
+
+### New WebUI LoRA and Textual Inversion Buttons
+
+This version adds two new web interface buttons for inserting LoRA and Textual Inversion triggers into the prompt as shown in the screenshot below.
+
+Clicking on one or the other of the buttons will bring up a menu of available LoRA/LyCORIS or Textual Inversion trigger terms. Select a menu item to insert the properly-formatted withLora() or <textual-inversion> prompt fragment into the positive prompt. The number in parentheses indicates the number of trigger terms currently in the prompt. You may click the button again and deselect the LoRA or trigger to remove it from the prompt, or simply edit the prompt directly.
+
+Currently terms are inserted into the positive prompt textbox only. However, some textual inversion embeddings are designed to be used with negative prompts. To move a textual inversion trigger into the negative prompt, simply cut and paste it.
+
+By default the Textual Inversion menu only shows locally installed models found at startup time in /path/to/invokeai/embeddings. However, InvokeAI has the ability to dynamically download and install additional Textual Inversion embeddings from the HuggingFace Concepts Library. You may choose to display the most popular of these (with five or more likes) in the Textual Inversion menu by going to Settings and turning on "Show Textual Inversions from HF Concepts Library." When this option is activated, the locally-installed TI embeddings will be shown first, followed by uninstalled terms from Hugging Face. See The Hugging Face Concepts Library and Importing Textual Inversion files for more information.
+### Minor features and fixes
+
+This release changes model switching behavior so that the command-line and Web UIs save the last model used and restore it the next time they are launched. It also improves the behavior of the installer so that the pip utility is kept up to date.
+  
+### Known Bugs in 2.3.4
+
+These are known bugs in the release.
+
+    The Ancestral DPMSolverMultistepScheduler (k_dpmpp_2a) sampler is not yet implemented for diffusers models and will disappear from the WebUI Sampler menu when a diffusers model is selected.
+    Windows Defender will sometimes raise Trojan or backdoor alerts for the codeformer.pth face restoration model, as well as the CIDAS/clipseg and runwayml/stable-diffusion-v1.5 models. These are false positives and can be safely ignored. InvokeAI performs a malware scan on all models as they are loaded. For additional security, you should use safetensors models whenever they are available.
+
+
+## v2.3.3 <small>(28 March 2023)</small>
+
+This is a bugfix and minor feature release.
+### Bugfixes
+
+Since version 2.3.2 the following bugs have been fixed:
+Bugs
+
+    When using legacy checkpoints with an external VAE, the VAE file is now scanned for malware prior to loading. Previously only the main model weights file was scanned.
+    Textual inversion will select an appropriate batchsize based on whether xformers is active, and will default to xformers enabled if the library is detected.
+    The batch script log file names have been fixed to be compatible with Windows.
+    Occasional corruption of the .next_prefix file (which stores the next output file name in sequence) on Windows systems is now detected and corrected.
+    Support loading of legacy config files that have no personalization (textual inversion) section.
+    An infinite loop when opening the developer's console from within the invoke.sh script has been corrected.
+    Documentation fixes, including a recipe for detecting and fixing problems with the AMD GPU ROCm driver.
+
+Enhancements
+
+    It is now possible to load and run several community-contributed SD-2.0 based models, including the often-requested "Illuminati" model.
+    The "NegativePrompts" embedding file, and others like it, can now be loaded by placing it in the InvokeAI embeddings directory.
+    If no --model is specified at launch time, InvokeAI will remember the last model used and restore it the next time it is launched.
+    On Linux systems, the invoke.sh launcher now uses a prettier console-based interface. To take advantage of it, install the dialog package using your package manager (e.g. sudo apt install dialog).
+    When loading legacy models (safetensors/ckpt) you can specify a custom config file and/or a VAE by placing like-named files in the same directory as the model following this example:
+
+my-favorite-model.ckpt
+my-favorite-model.yaml
+my-favorite-model.vae.pt      # or my-favorite-model.vae.safetensors
+
+### Known Bugs in 2.3.3
+
+These are known bugs in the release.
+
+    The Ancestral DPMSolverMultistepScheduler (k_dpmpp_2a) sampler is not yet implemented for diffusers models and will disappear from the WebUI Sampler menu when a diffusers model is selected.
+    Windows Defender will sometimes raise Trojan or backdoor alerts for the codeformer.pth face restoration model, as well as the CIDAS/clipseg and runwayml/stable-diffusion-v1.5 models. These are false positives and can be safely ignored. InvokeAI performs a malware scan on all models as they are loaded. For additional security, you should use safetensors models whenever they are available.
+
+
+## v2.3.2 <small>(11 March 2023)</small>
+This is a bugfix and minor feature release.
+
+### Bugfixes
+
+Since version 2.3.1 the following bugs have been fixed:
+
+    Black images appearing for potential NSFW images when generating with legacy checkpoint models and both --no-nsfw_checker and --ckpt_convert turned on.
+    Black images appearing when generating from models fine-tuned on Stable-Diffusion-2-1-base. When importing V2-derived models, you may be asked to select whether the model was derived from a "base" model (512 pixels) or the 768-pixel SD-2.1 model.
+    The "Use All" button was not restoring the Hi-Res Fix setting on the WebUI
+    When using the model installer console app, models failed to import correctly when importing from directories with spaces in their names. A similar issue with the output directory was also fixed.
+    Crashes that occurred during model merging.
+    Restore previous naming of Stable Diffusion base and 768 models.
+    Upgraded to latest versions of diffusers, transformers, safetensors and accelerate libraries upstream. We hope that this will fix the assertion NDArray > 2**32 issue that MacOS users have had when generating images larger than 768x768 pixels. Please report back.
+
+As part of the upgrade to diffusers, the location of the diffusers-based models has changed from models/diffusers to models/hub. When you launch InvokeAI for the first time, it will prompt you to OK a one-time move. This should be quick and harmless, but if you have modified your models/diffusers directory in some way, for example using symlinks, you may wish to cancel the migration and make appropriate adjustments.
+New "Invokeai-batch" script
+
+### Invoke AI Batch
+2.3.2 introduces a new command-line only script called invokeai-batch that can be used to generate hundreds of images from prompts and settings that vary systematically. This can be used to try the same prompt across multiple combinations of models, steps, CFG settings and so forth. It also allows you to template prompts and generate a combinatorial list like:
+
+a shack in the mountains, photograph
+a shack in the mountains, watercolor
+a shack in the mountains, oil painting
+a chalet in the mountains, photograph
+a chalet in the mountains, watercolor
+a chalet in the mountains, oil painting
+a shack in the desert, photograph
+...
+
+If you have a system with multiple GPUs, or a single GPU with lots of VRAM, you can parallelize generation across the combinatorial set, reducing wait times and using your system's resources efficiently (make sure you have good GPU cooling).
+
+To try invokeai-batch out. Launch the "developer's console" using the invoke launcher script, or activate the invokeai virtual environment manually. From the console, give the command invokeai-batch --help in order to learn how the script works and create your first template file for dynamic prompt generation.
+
+
+### Known Bugs in 2.3.2
+
+These are known bugs in the release.
+
+    The Ancestral DPMSolverMultistepScheduler (k_dpmpp_2a) sampler is not yet implemented for diffusers models and will disappear from the WebUI Sampler menu when a diffusers model is selected.
+    Windows Defender will sometimes raise a Trojan alert for the codeformer.pth face restoration model. As far as we have been able to determine, this is a false positive and can be safely whitelisted.
+
+
+## v2.3.1 <small>(22 February 2023)</small>
+This is primarily a bugfix release, but it does provide several new features that will improve the user experience.
+
+### Enhanced support for model management
+
+InvokeAI now makes it convenient to add, remove and modify models. You can individually import models that are stored on your local system, scan an entire folder and its subfolders for models and import them automatically, and even directly import models from the internet by providing their download URLs. You also have the option of designating a local folder to scan for new models each time InvokeAI is restarted.
+
+There are three ways of accessing the model management features:
+
+    From the WebUI, click on the cube to the right of the model selection menu. This will bring up a form that allows you to import models individually from your local disk or scan a directory for models to import.
+
+    Using the Model Installer App
+
+Choose option (5) download and install models from the invoke launcher script to start a new console-based application for model management. You can use this to select from a curated set of starter models, or import checkpoint, safetensors, and diffusers models from a local disk or the internet. The example below shows importing two checkpoint URLs from popular SD sites and a HuggingFace diffusers model using its Repository ID. It also shows how to designate a folder to be scanned at startup time for new models to import.
+
+Command-line users can start this app using the command invokeai-model-install.
+
+    Using the Command Line Client (CLI)
+
+The !install_model and !convert_model commands have been enhanced to allow entering of URLs and local directories to scan and import. The first command installs .ckpt and .safetensors files as-is. The second one converts them into the faster diffusers format before installation.
+
+Internally InvokeAI is able to probe the contents of a .ckpt or .safetensors file to distinguish among v1.x, v2.x and inpainting models. This means that you do not need to include "inpaint" in your model names to use an inpainting model. Note that Stable Diffusion v2.x models will be autoconverted into a diffusers model the first time you use it.
+
+Please see INSTALLING MODELS for more information on model management.
+
+### An Improved Installer Experience
+
+The installer now launches a console-based UI for setting and changing commonly-used startup options:
+
+After selecting the desired options, the installer installs several support models needed by InvokeAI's face reconstruction and upscaling features and then launches the interface for selecting and installing models shown earlier. At any time, you can edit the startup options by launching invoke.sh/invoke.bat and entering option (6) change InvokeAI startup options
+
+Command-line users can launch the new configure app using invokeai-configure.
+
+This release also comes with a renewed updater. To do an update without going through a whole reinstallation, launch invoke.sh or invoke.bat and choose option (9) update InvokeAI . This will bring you to a screen that prompts you to update to the latest released version, to the most current development version, or any released or unreleased version you choose by selecting the tag or branch of the desired version.
+
+Command-line users can run this interface by typing invokeai-configure
+
+### Image Symmetry Options
+
+There are now features to generate horizontal and vertical symmetry during generation. The way these work is to wait until a selected step in the generation process and then to turn on a mirror image effect. In addition to generating some cool images, you can also use this to make side-by-side comparisons of how an image will look with more or fewer steps. Access this option from the WebUI by selecting Symmetry from the image generation settings, or within the CLI by using the options --h_symmetry_time_pct and --v_symmetry_time_pct (these can be abbreviated to --h_sym and --v_sym like all other options).
+
+### A New Unified Canvas Look
+
+This release introduces a beta version of the WebUI Unified Canvas. To try it out, open up the settings dialogue in the WebUI (gear icon) and select Use Canvas Beta Layout:
+
+Refresh the screen and go to to Unified Canvas (left side of screen, third icon from the top). The new layout is designed to provide more space to work in and to keep the image controls close to the image itself:
+
+Model conversion and merging within the WebUI
+
+The WebUI now has an intuitive interface for model merging, as well as for permanent conversion of models from legacy .ckpt/.safetensors formats into diffusers format. These options are also available directly from the invoke.sh/invoke.bat scripts.
+An easier way to contribute translations to the WebUI
+
+We have migrated our translation efforts to Weblate, a FOSS translation product. Maintaining the growing project's translations is now far simpler for the maintainers and community. Please review our brief translation guide for more information on how to contribute.
+Numerous internal bugfixes and performance issues
+
+### Bug Fixes
+This releases quashes multiple bugs that were reported in 2.3.0. Major internal changes include upgrading to diffusers 0.13.0, and using the compel library for prompt parsing. See Detailed Change Log for a detailed list of bugs caught and squished.
+Summary of InvokeAI command line scripts (all accessible via the launcher menu)
+Command 	Description
+invokeai 	Command line interface
+invokeai --web 	Web interface
+invokeai-model-install 	Model installer with console forms-based front end
+invokeai-ti --gui 	Textual inversion, with a console forms-based front end
+invokeai-merge --gui 	Model merging, with a console forms-based front end
+invokeai-configure 	Startup configuration; can also be used to reinstall support models
+invokeai-update 	InvokeAI software updater
+
+### Known Bugs in 2.3.1
+
+These are known bugs in the release.
+    MacOS users generating 768x768 pixel images or greater using diffusers models may experience a hard crash with assertion NDArray > 2**32 This appears to be an issu...
+
+
+
+## v2.3.0 <small>(15 January 2023)</small>
+
+**Transition to diffusers
+
+Version 2.3 provides support for both the traditional `.ckpt` weight
+checkpoint files as well as the HuggingFace `diffusers` format. This
+introduces several changes you should know about.
+
+1. The models.yaml format has been updated. There are now two
+   different type of configuration stanza. The traditional ckpt
+   one will look like this, with a `format` of `ckpt` and a
+   `weights` field that points to the absolute or ROOTDIR-relative
+   location of the ckpt file.
+
+   ```
+   inpainting-1.5:
+      description: RunwayML SD 1.5 model optimized for inpainting (4.27 GB)
+      repo_id: runwayml/stable-diffusion-inpainting
+      format: ckpt
+      width: 512
+      height: 512
+      weights: models/ldm/stable-diffusion-v1/sd-v1-5-inpainting.ckpt
+      config: configs/stable-diffusion/v1-inpainting-inference.yaml
+      vae: models/ldm/stable-diffusion-v1/vae-ft-mse-840000-ema-pruned.ckpt
+   ```
+
+  A configuration stanza for a diffusers model hosted at HuggingFace will look like this,
+  with a `format` of `diffusers` and a `repo_id` that points to the
+  repository ID of the model on HuggingFace:
+
+  ```
+  stable-diffusion-2.1:
+  description: Stable Diffusion version 2.1 diffusers model (5.21 GB)
+  repo_id: stabilityai/stable-diffusion-2-1
+  format: diffusers
+  ```
+
+  A configuration stanza for a diffuers model stored locally should
+  look like this, with a `format` of `diffusers`, but a `path` field
+  that points at the directory that contains `model_index.json`:
+
+  ```
+  waifu-diffusion:
+  description: Latest waifu diffusion 1.4
+  format: diffusers
+  path: models/diffusers/hakurei-haifu-diffusion-1.4
+  ```
+
+2. In order of precedence, InvokeAI will now use HF_HOME, then
+   XDG_CACHE_HOME, then finally default to `ROOTDIR/models` to
+   store HuggingFace diffusers models.
+
+   Consequently, the format of the models directory has changed to
+   mimic the HuggingFace cache directory. When HF_HOME and XDG_HOME
+   are not set, diffusers models are now automatically downloaded
+   and retrieved from the directory `ROOTDIR/models/diffusers`,
+   while other models are stored in the directory
+   `ROOTDIR/models/hub`. This organization is the same as that used
+   by HuggingFace for its cache management.
+
+   This allows you to share diffusers and ckpt model files easily with
+   other machine learning applications that use the HuggingFace
+   libraries. To do this, set the environment variable HF_HOME
+   before starting up InvokeAI to tell it what directory to
+   cache models in. To tell InvokeAI to use the standard HuggingFace
+   cache directory, you would set HF_HOME like this (Linux/Mac):
+
+   `export HF_HOME=~/.cache/huggingface`
+
+   Both HuggingFace and InvokeAI will fall back to the XDG_CACHE_HOME
+   environment variable if HF_HOME is not set; this path
+   takes precedence over `ROOTDIR/models` to allow for the same sharing
+   with other machine learning applications that use HuggingFace
+   libraries.
+
+3. If you upgrade to InvokeAI 2.3.* from an earlier version, there
+   will be a one-time migration from the old models directory format
+   to the new one. You will see a message about this the first time
+   you start `invoke.py`.
+
+4. Both the front end back ends of the model manager have been
+   rewritten to accommodate diffusers. You can import models using
+   their local file path, using their URLs, or their HuggingFace
+   repo_ids. On the command line, all these syntaxes work:
+
+   ```
+   !import_model stabilityai/stable-diffusion-2-1-base
+   !import_model /opt/sd-models/sd-1.4.ckpt
+   !import_model https://huggingface.co/Fictiverse/Stable_Diffusion_PaperCut_Model/blob/main/PaperCut_v1.ckpt
+   ```
+
+**KNOWN BUGS (15 January 2023)
+
+1. On CUDA systems, the 768 pixel stable-diffusion-2.0 and
+   stable-diffusion-2.1 models can only be run as `diffusers` models
+   when the `xformer` library is installed and configured. Without
+   `xformers`, InvokeAI returns black images.
+
+2. Inpainting and outpainting have regressed in quality.
+
+Both these issues are being actively worked on.
+
+## v2.2.4 <small>(11 December 2022)</small>
+
+**the `invokeai` directory**
+
+Previously there were two directories to worry about, the directory that
+contained the InvokeAI source code and the launcher scripts, and the `invokeai`
+directory that contained the models files, embeddings, configuration and
+outputs. With the 2.2.4 release, this dual system is done away with, and
+everything, including the `invoke.bat` and `invoke.sh` launcher scripts, now
+live in a directory named `invokeai`. By default this directory is located in
+your home directory (e.g. `\Users\yourname` on Windows), but you can select
+where it goes at install time.
+
+After installation, you can delete the install directory (the one that the zip
+file creates when it unpacks). Do **not** delete or move the `invokeai`
+directory!
+
+**Initialization file `invokeai/invokeai.init`**
+
+You can place frequently-used startup options in this file, such as the default
+number of steps or your preferred sampler. To keep everything in one place, this
+file has now been moved into the `invokeai` directory and is named
+`invokeai.init`.
+
+**To update from Version 2.2.3**
+
+The easiest route is to download and unpack one of the 2.2.4 installer files.
+When it asks you for the location of the `invokeai` runtime directory, respond
+with the path to the directory that contains your 2.2.3 `invokeai`. That is, if
+`invokeai` lives at `C:\Users\fred\invokeai`, then answer with `C:\Users\fred`
+and answer "Y" when asked if you want to reuse the directory.
+
+The `update.sh` (`update.bat`) script that came with the 2.2.3 source installer
+does not know about the new directory layout and won't be fully functional.
+
+**To update to 2.2.5 (and beyond) there's now an update path**
+
+As they become available, you can update to more recent versions of InvokeAI
+using an `update.sh` (`update.bat`) script located in the `invokeai` directory.
+Running it without any arguments will install the most recent version of
+InvokeAI. Alternatively, you can get set releases by running the `update.sh`
+script with an argument in the command shell. This syntax accepts the path to
+the desired release's zip file, which you can find by clicking on the green
+"Code" button on this repository's home page.
+
+**Other 2.2.4 Improvements**
+
+- Fix InvokeAI GUI initialization by @addianto in #1687
+- fix link in documentation by @lstein in #1728
+- Fix broken link by @ShawnZhong in #1736
+- Remove reference to binary installer by @lstein in #1731
+- documentation fixes for 2.2.3 by @lstein in #1740
+- Modify installer links to point closer to the source installer by @ebr in
+  #1745
+- add documentation warning about 1650/60 cards by @lstein in #1753
+- Fix Linux source URL in installation docs by @andybearman in #1756
+- Make install instructions discoverable in readme by @damian0815 in #1752
+- typo fix by @ofirkris in #1755
+- Non-interactive model download (support HUGGINGFACE_TOKEN) by @ebr in #1578
+- fix(srcinstall): shell installer - cp scripts instead of linking by @tildebyte
+  in #1765
+- stability and usage improvements to binary & source installers by @lstein in
+  #1760
+- fix off-by-one bug in cross-attention-control by @damian0815 in #1774
+- Eventually update APP_VERSION to 2.2.3 by @spezialspezial in #1768
+- invoke script cds to its location before running by @lstein in #1805
+- Make PaperCut and VoxelArt models load again by @lstein in #1730
+- Fix --embedding_directory / --embedding_path not working by @blessedcoolant in
+  #1817
+- Clean up readme by @hipsterusername in #1820
+- Optimized Docker build with support for external working directory by @ebr in
+  #1544
+- disable pushing the cloud container by @mauwii in #1831
+- Fix docker push github action and expand with additional metadata by @ebr in
+  #1837
+- Fix Broken Link To Notebook by @VedantMadane in #1821
+- Account for flat models by @spezialspezial in #1766
+- Update invoke.bat.in isolate environment variables by @lynnewu in #1833
+- Arch Linux Specific PatchMatch Instructions & fixing conda install on linux by
+  @SammCheese in #1848
+- Make force free GPU memory work in img2img by @addianto in #1844
+- New installer by @lstein
+
+## v2.2.3 <small>(2 December 2022)</small>
+
+!!! Note
+
+    This point release removes references to the binary installer from the
+    installation guide. The binary installer is not stable at the current
+    time. First time users are encouraged to use the "source" installer as
+    described in [Installing InvokeAI with the Source Installer](installation/deprecated_documentation/INSTALL_SOURCE.md)
+
+With InvokeAI 2.2, this project now provides enthusiasts and professionals a
+robust workflow solution for creating AI-generated and human facilitated
+compositions. Additional enhancements have been made as well, improving safety,
+ease of use, and installation.
+
+Optimized for efficiency, InvokeAI needs only ~3.5GB of VRAM to generate a
+512x768 image (and less for smaller images), and is compatible with
+Windows/Linux/Mac (M1 & M2).
+
+You can see the [release video](https://youtu.be/hIYBfDtKaus) here, which
+introduces the main WebUI enhancement for version 2.2 -
+[The Unified Canvas](features/UNIFIED_CANVAS.md). This new workflow is the
+biggest enhancement added to the WebUI to date, and unlocks a stunning amount of
+potential for users to create and iterate on their creations. The following
+sections describe what's new for InvokeAI.
+
+## v2.2.2 <small>(30 November 2022)</small>
+
+!!! note
+
+    The binary installer is not ready for prime time. First time users are recommended to install via the "source" installer accessible through the links at the bottom of this page.****
+
+With InvokeAI 2.2, this project now provides enthusiasts and professionals a
+robust workflow solution for creating AI-generated and human facilitated
+compositions. Additional enhancements have been made as well, improving safety,
+ease of use, and installation.
+
+Optimized for efficiency, InvokeAI needs only ~3.5GB of VRAM to generate a
+512x768 image (and less for smaller images), and is compatible with
+Windows/Linux/Mac (M1 & M2).
+
+You can see the [release video](https://youtu.be/hIYBfDtKaus) here, which
+introduces the main WebUI enhancement for version 2.2 -
+[The Unified Canvas](https://invoke-ai.github.io/InvokeAI/features/UNIFIED_CANVAS/).
+This new workflow is the biggest enhancement added to the WebUI to date, and
+unlocks a stunning amount of potential for users to create and iterate on their
+creations. The following sections describe what's new for InvokeAI.
+
+## v2.2.0 <small>(2 December 2022)</small>
+
+With InvokeAI 2.2, this project now provides enthusiasts and professionals a
+robust workflow solution for creating AI-generated and human facilitated
+compositions. Additional enhancements have been made as well, improving safety,
+ease of use, and installation.
+
+Optimized for efficiency, InvokeAI needs only ~3.5GB of VRAM to generate a
+512x768 image (and less for smaller images), and is compatible with
+Windows/Linux/Mac (M1 & M2).
+
+You can see the [release video](https://youtu.be/hIYBfDtKaus) here, which
+introduces the main WebUI enhancement for version 2.2 -
+[The Unified Canvas](features/UNIFIED_CANVAS.md). This new workflow is the
+biggest enhancement added to the WebUI to date, and unlocks a stunning amount of
+potential for users to create and iterate on their creations. The following
+sections describe what's new for InvokeAI.
+
+## v2.1.3 <small>(13 November 2022)</small>
+
+- A choice of installer scripts that automate installation and configuration.
+  See
+  [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).
+- The ability to save frequently-used startup options (model to load, steps,
+  sampler, etc) in a `.invokeai` file. See
+  [Client](deprecated/CLI.md)
+- Support for AMD GPU cards (non-CUDA) on Linux machines.
+- Multiple bugs and edge cases squashed.
+
+## v2.1.0 <small>(2 November 2022)</small>
+
+- update mac instructions to use invokeai for env name by @willwillems in #1030
+- Update .gitignore by @blessedcoolant in #1040
+- reintroduce fix for m1 from #579 missing after merge by @skurovec in #1056
+- Update Stable_Diffusion_AI_Notebook.ipynb (Take 2) by @ChloeL19 in #1060
+- Print out the device type which is used by @manzke in #1073
+- Hires Addition by @hipsterusername in #1063
+- fix for "1 leaked semaphore objects to clean up at shutdown" on M1 by
+  @skurovec in #1081
+- Forward dream.py to invoke.py using the same interpreter, add deprecation
+  warning by @db3000 in #1077
+- fix noisy images at high step counts by @lstein in #1086
+- Generalize facetool strength argument by @db3000 in #1078
+- Enable fast switching among models at the invoke> command line by @lstein in
+  #1066
+- Fix Typo, committed changing ldm environment to invokeai by @jdries3 in #1095
+- Update generate.py by @unreleased in #1109
+- Update 'ldm' env to 'invokeai' in troubleshooting steps by @19wolf in #1125
+- Fixed documentation typos and resolved merge conflicts by @rupeshs in #1123
+- Fix broken doc links, fix malaprop in the project subtitle by @majick in #1131
+- Only output facetool parameters if enhancing faces by @db3000 in #1119
+- Update gitignore to ignore codeformer weights at new location by
+  @spezialspezial in #1136
+- fix links to point to invoke-ai.github.io #1117 by @mauwii in #1143
+- Rework-mkdocs by @mauwii in #1144
+- add option to CLI and pngwriter that allows user to set PNG compression level
+  by @lstein in #1127
+- Fix img2img DDIM index out of bound by @wfng92 in #1137
+- Fix gh actions by @mauwii in #1128
+- update mac instructions to use invokeai for env name by @willwillems in #1030
+- Update .gitignore by @blessedcoolant in #1040
+- reintroduce fix for m1 from #579 missing after merge by @skurovec in #1056
+- Update Stable_Diffusion_AI_Notebook.ipynb (Take 2) by @ChloeL19 in #1060
+- Print out the device type which is used by @manzke in #1073
+- Hires Addition by @hipsterusername in #1063
+- fix for "1 leaked semaphore objects to clean up at shutdown" on M1 by
+  @skurovec in #1081
+- Forward dream.py to invoke.py using the same interpreter, add deprecation
+  warning by @db3000 in #1077
+- fix noisy images at high step counts by @lstein in #1086
+- Generalize facetool strength argument by @db3000 in #1078
+- Enable fast switching among models at the invoke> command line by @lstein in
+  #1066
+- Fix Typo, committed changing ldm environment to invokeai by @jdries3 in #1095
+- Fixed documentation typos and resolved merge conflicts by @rupeshs in #1123
+- Only output facetool parameters if enhancing faces by @db3000 in #1119
+- add option to CLI and pngwriter that allows user to set PNG compression level
+  by @lstein in #1127
+- Fix img2img DDIM index out of bound by @wfng92 in #1137
+- Add text prompt to inpaint mask support by @lstein in #1133
+- Respect http[s] protocol when making socket.io middleware by @damian0815 in
+  #976
+- WebUI: Adds Codeformer support by @psychedelicious in #1151
+- Skips normalizing prompts for web UI metadata by @psychedelicious in #1165
+- Add Asymmetric Tiling by @carson-katri in #1132
+- Web UI: Increases max CFG Scale to 200 by @psychedelicious in #1172
+- Corrects color channels in face restoration; Fixes #1167 by @psychedelicious
+  in #1175
+- Flips channels using array slicing instead of using OpenCV by @psychedelicious
+  in #1178
+- Fix typo in docs: s/Formally/Formerly by @noodlebox in #1176
+- fix clipseg loading problems by @lstein in #1177
+- Correct color channels in upscale using array slicing by @wfng92 in #1181
+- Web UI: Filters existing images when adding new images; Fixes #1085 by
+  @psychedelicious in #1171
+- fix a number of bugs in textual inversion by @lstein in #1190
+- Improve !fetch, add !replay command by @ArDiouscuros in #882
+- Fix generation of image with s>1000 by @holstvoogd in #951
+- Web UI: Gallery improvements by @psychedelicious in #1198
+- Update CLI.md by @krummrey in #1211
+- outcropping improvements by @lstein in #1207
+- add support for loading VAE autoencoders by @lstein in #1216
+- remove duplicate fix_func for MPS by @wfng92 in #1210
+- Metadata storage and retrieval fixes by @lstein in #1204
+- nix: add shell.nix file by @Cloudef in #1170
+- Web UI: Changes vite dist asset paths to relative by @psychedelicious in #1185
+- Web UI: Removes isDisabled from PromptInput by @psychedelicious in #1187
+- Allow user to generate images with initial noise as on M1 / mps system by
+  @ArDiouscuros in #981
+- feat: adding filename format template by @plucked in #968
+- Web UI: Fixes broken bundle by @psychedelicious in #1242
+- Support runwayML custom inpainting model by @lstein in #1243
+- Update IMG2IMG.md by @talitore in #1262
+- New dockerfile - including a build- and a run- script as well as a GH-Action
+  by @mauwii in #1233
+- cut over from karras to model noise schedule for higher steps by @lstein in
+  #1222
+- Prompt tweaks by @lstein in #1268
+- Outpainting implementation by @Kyle0654 in #1251
+- fixing aspect ratio on hires by @tjennings in #1249
+- Fix-build-container-action by @mauwii in #1274
+- handle all unicode characters by @damian0815 in #1276
+- adds models.user.yml to .gitignore by @JakeHL in #1281
+- remove debug branch, set fail-fast to false by @mauwii in #1284
+- Protect-secrets-on-pr by @mauwii in #1285
+- Web UI: Adds initial inpainting implementation by @psychedelicious in #1225
+- fix environment-mac.yml - tested on x64 and arm64 by @mauwii in #1289
+- Use proper authentication to download model by @mauwii in #1287
+- Prevent indexing error for mode RGB by @spezialspezial in #1294
+- Integrate sd-v1-5 model into test matrix (easily expandable), remove
+  unecesarry caches by @mauwii in #1293
+- add --no-interactive to configure_invokeai step by @mauwii in #1302
+- 1-click installer and updater. Uses micromamba to install git and conda into a
+  contained environment (if necessary) before running the normal installation
+  script by @cmdr2 in #1253
+- configure_invokeai.py script downloads the weight files by @lstein in #1290
+
+## v2.0.1 <small>(13 October 2022)</small>
+
+- fix noisy images at high step count when using k\* samplers
+- dream.py script now calls invoke.py module directly rather than via a new
+  python process (which could break the environment)
+
+## v2.0.0 <small>(9 October 2022)</small>
+
+- `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`
+- img2img runs on all k\* samplers
+- Support for
+  [negative prompts](features/PROMPTS.md#negative-and-unconditioned-prompts)
+- Support for CodeFormer face reconstruction
+- Support for Textual Inversion on Macintoshes
+- Support in both WebGUI and CLI for
+  [post-processing of previously-generated images](features/POSTPROCESS.md)
+  using facial reconstruction, ESRGAN upscaling, outcropping (similar to DALL-E
+  infinite canvas), and "embiggen" upscaling. See the `!fix` command.
+- New `--hires` option on `invoke>` line allows
+  [larger images to be created without duplicating elements](deprecated/CLI.md#this-is-an-example-of-txt2img),
+  at the cost of some performance.
+- New `--perlin` and `--threshold` options allow you to add and control
+  variation during image generation (see
+  [Thresholding and Perlin Noise Initialization](features/OTHER.md#thresholding-and-perlin-noise-initialization-options))
+- Extensive metadata now written into PNG files, allowing reliable regeneration
+  of images and tweaking of previous settings.
+- Command-line completion in `invoke.py` now works on Windows, Linux and Mac
+  platforms.
+- Improved [command-line completion behavior](deprecated/CLI.md) New commands
+  added:
+  - List command-line history with `!history`
+  - Search command-line history with `!search`
+  - Clear history with `!clear`
+- Deprecated `--full_precision` / `-F`. Simply omit it and `invoke.py` will auto
+  configure. To switch away from auto use the new flag like
+  `--precision=float32`.
+
+## v1.14 <small>(11 September 2022)</small>
+
+- Memory optimizations for small-RAM cards. 512x512 now possible on 4 GB GPUs.
+- Full support for Apple hardware with M1 or M2 chips.
+- Add "seamless mode" for circular tiling of image. Generates beautiful effects.
+  ([prixt](https://github.com/prixt)).
+- Inpainting support.
+- Improved web server GUI.
+- Lots of code and documentation cleanups.
+
+## v1.13 <small>(3 September 2022)</small>
+
+- 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
+  hardware [Arturo Mendivil](https://github.com/artmen1516)
+- WebUI supports GFPGAN/ESRGAN facial reconstruction and upscaling
+  [Kevin Gibbons](https://github.com/bakkot)
+- WebUI supports incremental display of in-progress images during generation
+  [Kevin Gibbons](https://github.com/bakkot)
+- A new configuration file scheme that allows new models (including upcoming
+  stable-diffusion-v1.5) to be added without altering the code.
+  ([David Wager](https://github.com/maddavid12))
+- Can specify --grid on invoke.py command line as the default.
+- Miscellaneous internal bug and stability fixes.
+- Works on M1 Apple hardware.
+- Multiple bug fixes.
+
+---
+
+## v1.12 <small>(28 August 2022)</small>
+
+- Improved file handling, including ability to read prompts from standard input.
+  (kudos to [Yunsaki](https://github.com/yunsaki)
+- The web server is now integrated with the invoke.py script. Invoke by adding
+  --web to the invoke.py command arguments.
+- Face restoration and upscaling via GFPGAN and Real-ESGAN are now automatically
+  enabled if the GFPGAN directory is located as a sibling to Stable Diffusion.
+  VRAM requirements are modestly reduced. Thanks to both
+  [Blessedcoolant](https://github.com/blessedcoolant) and
+  [Oceanswave](https://github.com/oceanswave) for their work on this.
+- You can now swap samplers on the invoke> command line.
+  [Blessedcoolant](https://github.com/blessedcoolant)
+
+---
+
+## v1.11 <small>(26 August 2022)</small>
+
+- NEW FEATURE: Support upscaling and face enhancement using the GFPGAN module.
+  (kudos to [Oceanswave](https://github.com/Oceanswave)
+- You now can specify a seed of -1 to use the previous image's seed, -2 to use
+  the seed for the image generated before that, etc. Seed memory only extends
+  back to the previous command, but will work on all images generated with the
+  -n# switch.
+- Variant generation support temporarily disabled pending more general solution.
+- Created a feature branch named **yunsaki-morphing-invoke** which adds
+  experimental support for iteratively modifying the prompt and its parameters.
+  Please
+  see[Pull Request #86](https://github.com/lstein/stable-diffusion/pull/86) for
+  a synopsis of how this works. Note that when this feature is eventually added
+  to the main branch, it will may be modified significantly.
+
+---
+
+## v1.10 <small>(25 August 2022)</small>
+
+- A barebones but fully functional interactive web server for online generation
+  of txt2img and img2img.
+
+---
+
+## v1.09 <small>(24 August 2022)</small>
+
+- A new -v option allows you to generate multiple variants of an initial image
+  in img2img mode. (kudos to [Oceanswave](https://github.com/Oceanswave).
+  [ See this discussion in the PR for examples and details on use](https://github.com/lstein/stable-diffusion/pull/71#issuecomment-1226700810))
+- Added ability to personalize text to image generation (kudos to
+  [Oceanswave](https://github.com/Oceanswave) and
+  [nicolai256](https://github.com/nicolai256))
+- Enabled all of the samplers from k_diffusion
+
+---
+
+## v1.08 <small>(24 August 2022)</small>
+
+- Escape single quotes on the invoke> command before trying to parse. This
+  avoids parse errors.
+- Removed instruction to get Python3.8 as first step in Windows install.
+  Anaconda3 does it for you.
+- Added bounds checks for numeric arguments that could cause crashes.
+- Cleaned up the copyright and license agreement files.
+
+---
+
+## v1.07 <small>(23 August 2022)</small>
+
+- Image filenames will now never fill gaps in the sequence, but will be assigned
+  the next higher name in the chosen directory. This ensures that the alphabetic
+  and chronological sort orders are the same.
+
+---
+
+## v1.06 <small>(23 August 2022)</small>
+
+- Added weighted prompt support contributed by
+  [xraxra](https://github.com/xraxra)
+- Example of using weighted prompts to tweak a demonic figure contributed by
+  [bmaltais](https://github.com/bmaltais)
+
+---
+
+## v1.05 <small>(22 August 2022 - after the drop)</small>
+
+- Filenames now use the following formats: 000010.95183149.png -- Two files
+  produced by the same command (e.g. -n2), 000010.26742632.png -- distinguished
+  by a different seed.
+
+  000011.455191342.01.png -- Two files produced by the same command using
+  000011.455191342.02.png -- a batch size>1 (e.g. -b2). They have the same seed.
+
+  000011.4160627868.grid#1-4.png -- a grid of four images (-g); the whole grid
+  can be regenerated with the indicated key
+
+- It should no longer be possible for one image to overwrite another
+- You can use the "cd" and "pwd" commands at the invoke> prompt to set and
+  retrieve the path of the output directory.
+
+---
+
+## v1.04 <small>(22 August 2022 - after the drop)</small>
+
+- Updated README to reflect installation of the released weights.
+- Suppressed very noisy and inconsequential warning when loading the frozen CLIP
+  tokenizer.
+
+---
+
+## v1.03 <small>(22 August 2022)</small>
+
+- The original txt2img and img2img scripts from the CompViz repository have been
+  moved into a subfolder named "orig_scripts", to reduce confusion.
+
+---
+
+## v1.02 <small>(21 August 2022)</small>
+
+- A copy of the prompt and all of its switches and options is now stored in the
+  corresponding image in a tEXt metadata field named "Dream". You can read the
+  prompt using scripts/images2prompt.py, or an image editor that allows you to
+  explore the full metadata. **Please run "conda env update" to load the k_lms
+  dependencies!!**
+
+---
+
+## v1.01 <small>(21 August 2022)</small>
+
+- added k_lms sampling. **Please run "conda env update" to load the k_lms
+  dependencies!!**
+- use half precision arithmetic by default, resulting in faster execution and
+  lower memory requirements Pass argument --full_precision to invoke.py to get
+  slower but more accurate image generation
+
+---
+
+## Links
+
+- **[Read Me](index.md)**

docs/RELEASE.md

@@ -1,173 +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. Time to test the installer.
-
-Because the installer pulls from PyPI, and we haven't published to PyPI yet, you will need to install from the wheel:
-
-- Download and unzip `dist.zip` and the installer from the **Summary** tab of the workflow
-- Run the installer script using the `--wheel` CLI arg, pointing at the wheel:
-
-  ```sh
-  ./install.sh --wheel ../InvokeAI-4.0.0rc6-py3-none-any.whl
-  ```
-
-- Install to a temporary directory so you get the new user experience
-- Download a model and generate
-
-> 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 as if the installer got the wheel from PyPI.
-
-##### Something isn't right
-
-If testing reveals any issues, no worries. Cancel the workflow, which will cancel the pending publish jobs (you didn't approve them prematurely, right?).
-
-Now you can start from the top:
-
-- Fix the issues and PR the fixes per usual
-- Get the PR approved and merged per usual
-- Switch to `main` and pull in the fixes
-- Run `make tag-release` to move the tag to `HEAD` (which has the fixes) and kick off the release workflow again
-- Re-do the sanity check
-
-#### 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.
-
-##### Failing PyPI Publish
-
-Check the [python infrastructure status page] for incidents.
-
-If there are no incidents, contact @hipsterusername or @lstein, who have owner access to GH and PyPI, to see if access has expired or something like that.
-
-#### `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.
-1. 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.
-1. Use `scripts/get_external_contributions.py` to get a list of external contributions to shout out in the release notes.
-1. Upload the zip file created in **`build`** job into the Assets section of the release notes.
-1. Check **Set as a pre-release** if it's a pre-release.
-1. Check **Create a discussion for this release**.
-1. Publish the release.
-1. Announce the 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
-[python infrastructure status page]: https://status.python.org/

docs/configuration.md

@@ -1,183 +0,0 @@
----
-title: Configuration
----
-
-# :material-tune-variant: InvokeAI Configuration
-
-## Intro
-
-Runtime settings, including the location of files and
-directories, memory usage, and performance, are managed via the
-`invokeai.yaml` config file or environment variables. A subset
-of settings may be set via commandline arguments.
-
-Settings sources are used in this order:
-
-- CLI args
-- Environment variables
-- `invokeai.yaml` settings
-- Fallback: defaults
-
-### InvokeAI Root Directory
-
-On startup, InvokeAI searches for its "root" directory. This is the directory
-that contains models, images, the database, and so on. It also contains
-a configuration file called `invokeai.yaml`.
-
-InvokeAI searches for the root directory in this order:
-
-1. The `--root <path>` CLI arg.
-2. The environment variable INVOKEAI_ROOT.
-3. The directory containing the currently active virtual environment.
-4. Fallback: a directory in the current user's home directory named `invokeai`.
-
-### InvokeAI Configuration File
-
-Inside the root directory, we read settings from the `invokeai.yaml` file.
-
-It has two sections - one for internal use and one for user settings:
-
-```yaml
-# Internal metadata - do not edit:
-schema_version: 4
-
-# Put user settings here - see https://invoke-ai.github.io/InvokeAI/features/CONFIGURATION/:
-host: 0.0.0.0 # serve the app on your local network
-models_dir: D:\invokeai\models # store models on an external drive
-precision: float16 # always use fp16 precision
-```
-
-The settings in this file will override the defaults. You only need
-to change this file if the default for a particular setting doesn't
-work for you.
-
-You'll find an example file next to `invokeai.yaml` that shows the default values.
-
-Some settings, like [Model Marketplace API Keys], require the YAML
-to be formatted correctly. Here is a [basic guide to YAML files].
-
-#### Custom Config File Location
-
-You can use any config file with the `--config` CLI arg. Pass in the path to the `invokeai.yaml` file you want to use.
-
-Note that environment variables will trump any settings in the config file.
-
-### Environment Variables
-
-All settings may be set via environment variables by prefixing `INVOKEAI_`
-to the variable name. For example, `INVOKEAI_HOST` would set the `host`
-setting.
-
-For non-primitive values, pass a JSON-encoded string:
-
-```sh
-export INVOKEAI_REMOTE_API_TOKENS='[{"url_regex":"modelmarketplace", "token": "12345"}]'
-```
-
-We suggest using `invokeai.yaml`, as it is more user-friendly.
-
-### CLI Args
-
-A subset of settings may be specified using CLI args:
-
-- `--root`: specify the root directory
-- `--config`: override the default `invokeai.yaml` file location
-
-### All Settings
-
-Following the table are additional explanations for certain settings.
-
-<!-- prettier-ignore-start -->
-::: invokeai.app.services.config.config_default.InvokeAIAppConfig
-    options:
-        show_root_heading: false
-        members: false
-        show_docstring_description: false
-        show_category_heading: false
-<!-- prettier-ignore-end -->
-
-#### Model Marketplace API Keys
-
-Some model marketplaces require an API key to download models. You can provide a URL pattern and appropriate token in your `invokeai.yaml` file to provide that API key.
-
-The pattern can be any valid regex (you may need to surround the pattern with quotes):
-
-```yaml
-remote_api_tokens:
-  # Any URL containing `models.com` will automatically use `your_models_com_token`
-  - url_regex: models.com
-    token: your_models_com_token
-  # Any URL matching this contrived regex will use `some_other_token`
-  - url_regex: '^[a-z]{3}whatever.*\.com$'
-    token: some_other_token
-```
-
-The provided token will be added as a `Bearer` token to the network requests to download the model files. As far as we know, this works for all model marketplaces that require authorization.
-
-#### Model Hashing
-
-Models are hashed during installation, providing a stable identifier for models across all platforms. Hashing is a one-time operation.
-
-```yaml
-hashing_algorithm: blake3_single # default value
-```
-
-You might want to change this setting, depending on your system:
-
-- `blake3_single` (default): Single-threaded - best for spinning HDDs, still OK for SSDs
-- `blake3_multi`: Parallelized, memory-mapped implementation - best for SSDs, terrible for spinning disks
-- `random`: Skip hashing entirely - fastest but of course no hash
-
-During the first startup after upgrading to v4, all of your models will be hashed. This can take a few minutes.
-
-Most common algorithms are supported, like `md5`, `sha256`, and `sha512`. These are typically much, much slower than either of the BLAKE3 variants.
-
-#### Path Settings
-
-These options set the paths of various directories and files used by InvokeAI. Any user-defined paths should be absolute paths.
-
-#### Logging
-
-Several different log handler destinations are available, and multiple destinations are supported by providing a list:
-
-```yaml
-log_handlers:
-  - console
-  - syslog=localhost
-  - file=/var/log/invokeai.log
-```
-
-- `console` is the default. It prints log messages to the command-line window from which InvokeAI was launched.
-
-- `syslog` is only available on Linux and Macintosh systems. It uses
-  the operating system's "syslog" facility to write log file entries
-  locally or to a remote logging machine. `syslog` offers a variety
-  of configuration options:
-
-```yaml
-syslog=/dev/log`      - log to the /dev/log device
-syslog=localhost`     - log to the network logger running on the local machine
-syslog=localhost:512` - same as above, but using a non-standard port
-syslog=fredserver,facility=LOG_USER,socktype=SOCK_DRAM`
-- Log to LAN-connected server "fredserver" using the facility LOG_USER and datagram packets.
-```
-
-- `http` can be used to log to a remote web server. The server must be
-  properly configured to receive and act on log messages. The option
-  accepts the URL to the web server, and a `method` argument
-  indicating whether the message should be submitted using the GET or
-  POST method.
-
-```yaml
-http=http://my.server/path/to/logger,method=POST
-```
-
-The `log_format` option provides several alternative formats:
-
-- `color` - default format providing time, date and a message, using text colors to distinguish different log severities
-- `plain` - same as above, but monochrome text only
-- `syslog` - the log level and error message only, allowing the syslog system to attach the time and date
-- `legacy` - a format similar to the one used by the legacy 2.3 InvokeAI releases.
-
-[basic guide to yaml files]: https://circleci.com/blog/what-is-yaml-a-beginner-s-guide/
-[Model Marketplace API Keys]: #model-marketplace-api-keys

docs/contributing/ARCHITECTURE.md

@@ -50,7 +50,7 @@ Applications are built on top of the invoke framework. They should construct `in
 
 ### Web UI
 
-The Web UI is built on top of an HTTP API built with [FastAPI](https://fastapi.tiangolo.com/) and [Socket.IO](https://socket.io/). The frontend code is found in `/invokeai/frontend` and the backend code is found in `/invokeai/app/api_app.py` and `/invokeai/app/api/`. The code is further organized as such:
+The Web UI is built on top of an HTTP API built with [FastAPI](https://fastapi.tiangolo.com/) and [Socket.IO](https://socket.io/). The frontend code is found in `/frontend` and the backend code is found in `/ldm/invoke/app/api_app.py` and `/ldm/invoke/app/api/`. The code is further organized as such:
 
 | Component | Description |
 | --- | --- |
@@ -62,7 +62,7 @@ The Web UI is built on top of an HTTP API built with [FastAPI](https://fastapi.t
 
 ### CLI
 
-The CLI is built automatically from invocation metadata, and also supports invocation piping and auto-linking. Code is available in `/invokeai/frontend/cli`.
+The CLI is built automatically from invocation metadata, and also supports invocation piping and auto-linking. Code is available in `/ldm/invoke/app/cli_app.py`.
 
 ## Invoke
 
@@ -70,7 +70,7 @@ The Invoke framework provides the interface to the underlying AI systems and is
 
 ### Invoker
 
-The invoker (`/invokeai/app/services/invoker.py`) is the primary interface through which applications interact with the framework. Its primary purpose is to create, manage, and invoke sessions. It also maintains two sets of services:
+The invoker (`/ldm/invoke/app/services/invoker.py`) is the primary interface through which applications interact with the framework. Its primary purpose is to create, manage, and invoke sessions. It also maintains two sets of services:
 - **invocation services**, which are used by invocations to interact with core functionality.
 - **invoker services**, which are used by the invoker to manage sessions and manage the invocation queue.
 
@@ -82,12 +82,12 @@ The session graph does not support looping. This is left as an application probl
 
 ### Invocations
 
-Invocations represent individual units of execution, with inputs and outputs. All invocations are located in `/invokeai/app/invocations`, and are all automatically discovered and made available in the applications. These are the primary way to expose new functionality in Invoke.AI, and the [implementation guide](INVOCATIONS.md) explains how to add new invocations.
+Invocations represent individual units of execution, with inputs and outputs. All invocations are located in `/ldm/invoke/app/invocations`, and are all automatically discovered and made available in the applications. These are the primary way to expose new functionality in Invoke.AI, and the [implementation guide](INVOCATIONS.md) explains how to add new invocations.
 
 ### Services
 
-Services provide invocations access AI Core functionality and other necessary functionality (e.g. image storage). These are available in `/invokeai/app/services`. As a general rule, new services should provide an interface as an abstract base class, and may provide a lightweight local implementation by default in their module. The goal for all services should be to enable the usage of different implementations (e.g. using cloud storage for image storage), but should not load any module dependencies unless that implementation has been used (i.e. don't import anything that won't be used, especially if it's expensive to import).
+Services provide invocations access AI Core functionality and other necessary functionality (e.g. image storage). These are available in `/ldm/invoke/app/services`. As a general rule, new services should provide an interface as an abstract base class, and may provide a lightweight local implementation by default in their module. The goal for all services should be to enable the usage of different implementations (e.g. using cloud storage for image storage), but should not load any module dependencies unless that implementation has been used (i.e. don't import anything that won't be used, especially if it's expensive to import).
 
 ## AI Core
 
-The AI Core is represented by the rest of the code base (i.e. the code outside of `/invokeai/app/`).
+The AI Core is represented by the rest of the code base (i.e. the code outside of `/ldm/invoke/app/`).

docs/contributing/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+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.
+
+
+# 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.
+
+## Development
+If you’d like to help with development, please see our [development guide](contribution_guides/development.md). 
+
+**New Contributors:** If you’re unfamiliar with contributing to open source projects, take a look at our [new contributor guide](contribution_guides/newContributorChecklist.md).
+
+## Nodes
+If you’d like to add a Node, please see our [nodes contribution guide](../nodes/contributingNodes.md).
+
+## 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. 
+
+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. 
+
+## Documentation
+If you’d like to help with documentation, please see our [documentation guide](contribution_guides/documentation.md).
+
+## Translation
+If you'd like to help with translation, please see our [translation guide](contribution_guides/translation.md).
+
+## Tutorials 
+Please reach out to @imic or @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) to help create tutorials for InvokeAI.
+
+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.
+
+
+# Contributors
+
+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
+
+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.
+
+By making a contribution to this project, you certify that:
+
+1. The contribution was created in whole or in part by you and you have the right to submit it under the open-source license indicated in this project’s GitHub repository; or
+2. The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open-source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, under the same open-source license (unless you are permitted to submit under a different license); or
+3. The contribution was provided directly to you by some other person who certified (1) or (2) and you have not modified it; or
+4. You understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information you submit with it, including your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open-source license(s) involved.
+
+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.
+
+---
+
+Remember, your contributions help make this project great. We're excited to see what you'll bring to our community!

docs/contributing/DOWNLOAD_QUEUE.md

@@ -1,334 +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.
-
-Two job types are defined. `DownloadJob` and
-`MultiFileDownloadJob`. The former is 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.
-
-The `MultiFileDownloadJob` is used for diffusers model downloads,
-which contain multiple files and directories under a common root:
-
-| **Field**      | **Type**        |  **Default**  | **Description** |
-|----------------|-----------------|---------------|-----------------|
-| _Fields passed in at job creation time_                               |
-| `download_parts` | Set[DownloadJob]|               | Component download jobs |
-| `dest`           | Path            |               | Where to download to              |
-| `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           |
-| _Fields updated over the course of the download task_
-| `status`         | DownloadJobStatus|              | Status code                                |
-| `download_path`  | Path |              | Path to the root of the downloaded files |
-| `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|
-
-Note that the MultiFileDownloadJob does not support the `priority`,
-`job_started`, `job_ended` or `content_type` attributes. You can get
-these from the individual download jobs in `download_parts`.
-
-
-### 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, on_start, on_progress, on_complete, on_cancelled, on_error)
-
-Create a new download job and put it on the queue, returning the
-DownloadJob object.
-
-#### multifile_job = queue.multifile_download(parts, dest, access_token, on_start, on_progress, on_complete, on_cancelled, on_error)
-
-This is similar to download(), but instead of taking a single source,
-it accepts a `parts` argument consisting of a list of
-`RemoteModelFile` objects. Each part corresponds to a URL/Path pair,
-where the URL is the location of the remote file, and the Path is the
-destination.
-
-`RemoteModelFile` can be imported from `invokeai.backend.model_manager.metadata`, and
-consists of a url/path pair. Note that the path *must* be relative.
-
-The method returns a `MultiFileDownloadJob`.
-
-
-```
-from invokeai.backend.model_manager.metadata import RemoteModelFile
-remote_file_1 = RemoteModelFile(url='http://www.foo.bar/my/pytorch_model.safetensors'',
-                                path='my_model/textencoder/pytorch_model.safetensors'
-			 			  )
-remote_file_2 = RemoteModelFile(url='http://www.bar.baz/vae.ckpt',
-                                path='my_model/vae/diffusers_model.safetensors'
-			 			  )
-job = queue.multifile_download(parts=[remote_file_1, remote_file_2],
-                               dest='/tmp/downloads',
-                               on_progress=TqdmProgress().update)
-queue.wait_for_job(job)
-print(f"The files were downloaded to {job.download_path}")
-```
-
-#### 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
 
@@ -69,7 +44,7 @@ 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 .baseinvocation import BaseInvocation, invocation
 
 @invocation('resize')
 class ResizeInvocation(BaseInvocation):
@@ -103,8 +78,8 @@ 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 .baseinvocation import BaseInvocation, InputField, invocation
+from .primitives import ImageField
 
 @invocation('resize')
 class ResizeInvocation(BaseInvocation):
@@ -128,13 +103,14 @@ image: ImageField = InputField(description="The input image")
 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 .baseinvocation import BaseInvocation, InputField, invocation
+from .primitives import ImageField
 
 @invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
 
+    # Inputs
     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")
@@ -144,7 +120,7 @@ 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 constraints on those fields, and will raise an exception if the
+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.
 
@@ -163,13 +139,14 @@ 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 .baseinvocation import BaseInvocation, InputField, invocation
+from .primitives import ImageField
 
 @invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
 
+    # Inputs
     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")
@@ -191,14 +168,15 @@ 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 .baseinvocation import BaseInvocation, InputField, invocation
+from .primitives import ImageField
+from .image import ImageOutput
 
 @invocation('resize')
 class ResizeInvocation(BaseInvocation):
     '''Resizes an image'''
 
+    # Inputs
     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")
@@ -217,9 +195,9 @@ Perfect. Now that we have our Invocation setup, let us do what we want to do.
 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 .baseinvocation import BaseInvocation, InputField, invocation
+from .primitives import ImageField
+from .image import ImageOutput
 
 @invocation("resize")
 class ResizeInvocation(BaseInvocation):
@@ -230,17 +208,30 @@ class ResizeInvocation(BaseInvocation):
     height: int = InputField(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. Returns the PIL image.
+        image = context.services.images.get_pil_image(self.image.image_name)
 
-        # Resize the image
+        # Resizing the image
         resized_image = image.resize((self.width, self.height))
 
-        # Save the image
-        image_dto = context.images.save(image=resized_image)
+        # Save the image using InvokeAI's predefined Image Service. Returns the prepared PIL image.
+        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,
+            ),
+            width=output_image.width,
+            height=output_image.height,
+        )
 ```
 
 **Note:** Do not be overwhelmed by the `ImageOutput` process. InvokeAI has a
@@ -287,8 +278,8 @@ new Invocation ready to be used.
 
 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.md) list. If you're not sure how to do that,
-take a look a at our [contributing nodes overview](../nodes/contributingNodes.md).
+[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
 
@@ -331,25 +322,27 @@ class ImageColorStringOutput(BaseInvocationOutput):
 
 That's all there is to it.
 
+<!-- TODO: DANGER - we probably do not want people to create their own field types, because this requires a lot of work on the frontend to accomodate.
+
 ### 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 +357,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 +375,25 @@ 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
+### Custom Components For Frontend
 
-When you start the UI, your custom field will be automatically recognized.
+Every backend input type should have a corresponding frontend component so the
+UI knows what to render when you use a particular field type.
 
-Custom fields only support connection inputs in the Workflow Editor.
+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.
+-->

docs/contributing/LOCAL_DEVELOPMENT.md

@@ -1,10 +1,21 @@
 # Local Development
 
-If you want to contribute, you will need to set up a [local development environment](./dev-environment.md).
+If you are looking to contribute you will need to have a local development
+environment. See the
+[Developer Install](../installation/020_INSTALL_MANUAL.md#developer-install) for
+full details.
+
+Broadly this involves cloning the repository, installing the pre-reqs, and
+InvokeAI (in editable form). Assuming this is working, choose your area of
+focus.
 
 ## Documentation
 
-We use [mkdocs](https://www.mkdocs.org) for our documentation with the [material theme](https://squidfunk.github.io/mkdocs-material/). Documentation is written in markdown files under the `./docs` folder and then built into a static website for hosting with GitHub Pages at [invoke-ai.github.io/InvokeAI](https://invoke-ai.github.io/InvokeAI).
+We use [mkdocs](https://www.mkdocs.org) for our documentation with the
+[material theme](https://squidfunk.github.io/mkdocs-material/). Documentation is
+written in markdown files under the `./docs` folder and then built into a static
+website for hosting with GitHub Pages at
+[invoke-ai.github.io/InvokeAI](https://invoke-ai.github.io/InvokeAI).
 
 To contribute to the documentation you'll need to install the dependencies. Note
 the use of `"`.
@@ -36,9 +47,33 @@ pip install ".[dev,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.
 
-### Tests
+### Running Tests
 
-See the [tests documentation](./TESTS.md) for information about running and writing tests.
+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`.
+
+```zsh
+pytest --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 one in particular can help identify missing statements
+requiring tests to ensure coverage. This can be run by opening
+`./coverage/html/index.html`.
+
+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)
 
 ### Reloading Changes
 
@@ -53,6 +88,7 @@ running server on the fly.
 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.
 
+
 ## Front End
 
 <!--#TODO: get input from blessedcoolant here, for the moment inserted the frontend README via snippets extension.-->
@@ -131,23 +167,6 @@ 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,
@@ -239,7 +258,7 @@ Consult the
 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 automatically.
+all the same app settings and extensions automagically.
 
 ##### One remote dev gotcha
 

docs/contributing/TESTS.md

@@ -1,89 +0,0 @@
-# InvokeAI Backend Tests
-
-We use `pytest` to run the backend python tests. (See [pyproject.toml](https://github.com/invoke-ai/InvokeAI/blob/main/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/`](https://github.com/invoke-ai/InvokeAI/tree/main/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/contributingToFrontend.md

@@ -0,0 +1,75 @@
+# Contributing to the Frontend
+
+# InvokeAI Web UI
+
+- [InvokeAI Web UI](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web/docs#invokeai-web-ui)
+    - [Stack](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web/docs#stack)
+    - [Contributing](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web/docs#contributing)
+        - [Dev Environment](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web/docs#dev-environment)
+        - [Production builds](https://github.com/invoke-ai/InvokeAI/tree/main/invokeai/frontend/web/docs#production-builds)
+
+The UI is a fairly straightforward Typescript React app, with the Unified Canvas being more complex.
+
+Code is located in `invokeai/frontend/web/` for review.
+
+## Stack
+
+State management is Redux via [Redux Toolkit](https://github.com/reduxjs/redux-toolkit). We lean heavily on RTK:
+
+- `createAsyncThunk` for HTTP requests
+- `createEntityAdapter` for fetching images and models
+- `createListenerMiddleware` for workflows
+
+The API client and associated types are generated from the OpenAPI schema. See API_CLIENT.md.
+
+Communication with server is a mix of HTTP and [socket.io](https://github.com/socketio/socket.io-client) (with a simple socket.io redux middleware to help).
+
+[Chakra-UI](https://github.com/chakra-ui/chakra-ui) & [Mantine](https://github.com/mantinedev/mantine) for components and styling.
+
+[Konva](https://github.com/konvajs/react-konva) for the canvas, but we are pushing the limits of what is feasible with it (and HTML canvas in general). We plan to rebuild it with [PixiJS](https://github.com/pixijs/pixijs) to take advantage of WebGL's improved raster handling.
+
+[Vite](https://vitejs.dev/) for bundling.
+
+Localisation is via [i18next](https://github.com/i18next/react-i18next), but translation happens on our [Weblate](https://hosted.weblate.org/engage/invokeai/) project. Only the English source strings should be changed on this repo.
+
+## Contributing
+
+Thanks for your interest in contributing to the InvokeAI Web UI!
+
+We encourage you to ping @psychedelicious and @blessedcoolant on [Discord](https://discord.gg/ZmtBAhwWhy) if you want to contribute, just to touch base and ensure your work doesn't conflict with anything else going on. The project is very active.
+
+### Dev Environment
+
+**Setup** 
+
+1. Install [node](https://nodejs.org/en/download/). You can confirm node is installed with:
+```bash
+node --version
+```
+2. Install [yarn classic](https://classic.yarnpkg.com/lang/en/) and confirm it is installed by running this:
+```bash
+npm install --global yarn
+yarn --version
+```
+
+From `invokeai/frontend/web/` run `yarn install` to get everything set up.
+
+Start everything in dev mode:
+1. Ensure your virtual environment is running
+2. Start the dev server: `yarn dev`
+3. Start the InvokeAI Nodes backend: `python scripts/invokeai-web.py # run from the repo root`
+4. Point your browser to the dev server address e.g. [http://localhost:5173/](http://localhost:5173/)
+
+### VSCode Remote Dev
+
+We've noticed an intermittent issue with the VSCode Remote Dev port forwarding. If you use this feature of VSCode, you may intermittently click the Invoke button and then get nothing until the request times out. Suggest disabling the IDE's port forwarding feature and doing it manually via SSH:
+
+`ssh -L 9090:localhost:9090 -L 5173:localhost:5173 user@host`
+
+### Production builds
+
+For a number of technical and logistical reasons, we need to commit UI build artefacts to the repo.
+
+If you submit a PR, there is a good chance we will ask you to include a separate commit with a build of the app.
+
+To build for production, run `yarn build`.

docs/contributing/contribution_guides/development.md

@@ -2,7 +2,7 @@
 
 ## **What do I need to know to help?**
 
-If you are looking to help 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.
+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**
@@ -12,7 +12,7 @@ To get started, take a look at our [new contributors checklist](newContributorCh
 Once you're setup, for more information, you can review the documentation specific to your area of interest:
 
 * #### [InvokeAI Architecure](../ARCHITECTURE.md)
-* #### [Frontend Documentation](../frontend/index.md)
+* #### [Frontend Documentation](development_guides/contributingToFrontend.md)
 * #### [Node Documentation](../INVOCATIONS.md)
 * #### [Local Development](../LOCAL_DEVELOPMENT.md)
 
@@ -20,15 +20,15 @@ Once you're setup, for more information, you can review the documentation specif
 
 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:
+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.
+    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:
+## 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
@@ -38,12 +38,12 @@ There are two paths to making a development contribution:
 
 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 frontend related work, **@pyschedelicious** is the best person to reach out to. 
 
-For backend related work, please reach out to **@blessedcoolant**, **@lstein**, **@StAlKeR7779** or **@psychedelicious**.
+For backend related work, please reach out to **@blessedcoolant**, **@lstein**, **@StAlKeR7779** or **@pyschedelicious**.
 
 
 ## **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.
+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 +1,13 @@
 # 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.
+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 our [GitHub repository](https://github.com/invoke-ai/InvokeAI). If you come across documentation that is out of date or incorrect, please submit a pull request with the necessary changes.
+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 Invoke is a tool for everyone, not just those who have familiarity with generative art.
+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 @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) if you have any questions.
+Please ping @imic1 or @hipsterusername in the [Discord](https://discord.com/channels/1020123559063990373/1049495067846524939) if you have any questions.

docs/contributing/contribution_guides/newContributorChecklist.md

@@ -1,56 +1,47 @@
 # New Contributor Guide
 
-If you're a new contributor to InvokeAI or Open Source Projects, this is the guide for you.
+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](../dev-environment.md)
-- [x] Set up your local tooling with [this guide](../LOCAL_DEVELOPMENT.md). Feel free to skip this step if you already have tooling you're comfortable with.
+- [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] 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.
+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
-  ```
-
+```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
-    ```
-
+```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"
-    ```
-
+```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
-    ```
-
+```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!
@@ -58,20 +49,20 @@ If you're unfamiliar with using Git through the commandline, [GitHub Desktop](ht
 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).
+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
+## 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
 
-- 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 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

@@ -16,4 +16,4 @@ Please check Weblate's [documentation](https://docs.weblate.org/en/latest/index
 
 ## Thanks
 
-Thanks to the InvokeAI community for their efforts to translate the project!
+Thanks to the InvokeAI community for their efforts to translate the project!

docs/contributing/contribution_guides/tutorials.md

@@ -1,6 +1,6 @@
 # Tutorials
 
-Tutorials help new & existing users expand their ability to use InvokeAI to the full extent of our features and services.  
+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. 
 
@@ -8,4 +8,4 @@ Tutorials can be in the form of videos or article walkthroughs on a subject of y
 
 ## Contributing
 
-Please reach out to @imic or @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) to help create tutorials for InvokeAI.
+Please reach out to @imic or @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) to help create tutorials for InvokeAI.

docs/contributing/contributors.md

@@ -1,54 +0,0 @@
----
-title: Contributors
----
-
-We thank [all contributors](https://github.com/invoke-ai/InvokeAI/graphs/contributors) for their time and hard work!
-
-## **Original Author**
-
-- [Lincoln D. Stein](mailto:lincoln.stein@gmail.com)
-
-## **Current Core Team**
-
-- @lstein (Lincoln Stein) - Co-maintainer
-- @blessedcoolant - Co-maintainer
-- @hipsterusername (Kent Keirsey) - Co-maintainer, CEO, Positive Vibes
-- @psychedelicious (Spencer Mabrito) - Web Team Leader
-- @joshistoast (Josh Corbett) - Web Development
-- @cheerio (Mary Rogers) - Lead Engineer & Web App Development
-- @ebr (Eugene Brodsky) - Cloud/DevOps/Sofware engineer; your friendly neighbourhood cluster-autoscaler
-- @sunija - Standalone version
-- @brandon (Brandon Rising) - Platform, Infrastructure, Backend Systems
-- @ryanjdick (Ryan Dick) - Machine Learning & Training
-- @JPPhoto - Core image generation nodes
-- @dunkeroni - Image generation backend
-- @SkunkWorxDark - Image generation backend
-- @glimmerleaf (Devon Hopkins) - Community Wizard
-- @gogurt enjoyer - Discord moderator and end user support
-- @whosawhatsis - Discord moderator and end user support
-- @dwringer - Discord moderator and end user support
-- @526christian - Discord moderator and end user support
-- @harvester62 - Discord moderator and end user support
-
-## **Honored Team Alumni**
-
-- @StAlKeR7779 (Sergey Borisov) - Torch stack, ONNX, model management, optimization
-- @damian0815 - Attention Systems and Compel Maintainer
-- @netsvetaev (Artur) - Localization support
-- @Kyle0654 (Kyle Schouviller) - Node Architect and General Backend Wizard
-- @tildebyte - Installation and configuration
-- @mauwii (Matthias Wilde) - Installation, release, continuous integration
-- @chainchompa (Jennifer Player) - Web Development & Chain-Chomping
-- @millu (Millun Atluri) - Community Wizard, Documentation, Node-wrangler,
-- @genomancer (Gregg Helt) - Controlnet support
-- @keturn (Kevin Turner) - Diffusers
-
-## **Original CompVis (Stable Diffusion) Authors**
-
-- [Robin Rombach](https://github.com/rromb)
-- [Patrick von Platen](https://github.com/patrickvonplaten)
-- [ablattmann](https://github.com/ablattmann)
-- [Patrick Esser](https://github.com/pesser)
-- [owenvincent](https://github.com/owenvincent)
-- [apolinario](https://github.com/apolinario)
-- [Charles Packer](https://github.com/cpacker)

docs/contributing/dev-environment.md

@@ -1,102 +0,0 @@
-# Dev Environment
-
-To make changes to Invoke's backend, frontend, or documentation, you'll need to set up a dev environment.
-
-If you just want to use Invoke, you should use the [installer][installer link].
-
-!!! info "Why do I need the frontend toolchain?"
-
-    The repo doesn't contain a build of the frontend. You'll be responsible for rebuilding it every time you pull in new changes, or run it in dev mode (which incurs a substantial performance penalty).
-
-!!! warning
-
-    Invoke uses a SQLite database. When you run the application as a dev install, you accept responsibility for your database. This means making regular backups (especially before pulling) and/or fixing it yourself in the event that a PR introduces a schema change.
-
-    If you don't need to persist your db, you can use an ephemeral in-memory database by setting `use_memory_db: true` in your `invokeai.yaml` file. You'll also want to set `scan_models_on_startup: true` so that your models are registered on startup.
-
-## Setup
-
-1. Run through the [requirements][requirements link].
-2. [Fork and clone][forking link] the [InvokeAI repo][repo link].
-3. Create an directory for user data (images, models, db, etc). This is typically at `~/invokeai`, but if you already have a non-dev install, you may want to create a separate directory for the dev install.
-4. Create a python virtual environment inside the directory you just created:
-
-      ```sh
-      python3 -m venv .venv --prompt InvokeAI-Dev
-      ```
-
-5. Activate the venv (you'll need to do this every time you want to run the app):
-
-      ```sh
-      source .venv/bin/activate
-      ```
-
-6. Install the repo as an [editable install][editable install link]:
-
-      ```sh
-      pip install -e ".[dev,test,xformers]" --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu121
-      ```
-
-      Refer to the [manual installation][manual install link] instructions for more determining the correct install options. `xformers` is optional, but `dev` and `test` are not.
-
-7. Install the frontend dev toolchain:
-
-   - [`nodejs`](https://nodejs.org/) (recommend v20 LTS)
-   - [`pnpm`](https://pnpm.io/8.x/installation) (must be v8 - not v9!)
-
-8. Do a production build of the frontend:
-
-      ```sh
-      cd PATH_TO_INVOKEAI_REPO/invokeai/frontend/web
-      pnpm i
-      pnpm build
-      ```
-
-9. Start the application:
-
-      ```sh
-      cd PATH_TO_INVOKEAI_REPO
-      python scripts/invokeai-web.py
-      ```
-
-10. Access the UI at `localhost:9090`.
-
-## Updating the UI
-
-You'll need to run `pnpm build` every time you pull in new changes. Another option is to skip the build and instead run the app in dev mode:
-
-```sh
-pnpm dev
-```
-
-This starts a dev server at `localhost:5173`, which you will use instead of `localhost:9090`.
-
-The dev mode is substantially slower than the production build but may be more convenient if you just need to test things out.
-
-## Documentation
-
-The documentation is built with `mkdocs`. To preview it locally, you need a additional set of packages installed.
-
-```sh
-# after activating the venv
-pip install -e ".[docs]"
-```
-
-Then, you can start a live docs dev server, which will auto-refresh when you edit the docs:
-
-```sh
-mkdocs serve
-```
-
-On macOS and Linux, there is a `make` target for this:
-
-```sh
-make docs
-```
-
-[installer link]: ../installation/installer.md
-[forking link]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
-[requirements link]: ../installation/requirements.md
-[repo link]: https://github.com/invoke-ai/InvokeAI
-[manual install link]: ../installation/manual.md
-[editable install link]: https://pip.pypa.io/en/latest/cli/pip_install/#cmdoption-e

docs/contributing/frontend/index.md

@@ -1,128 +0,0 @@
-# Invoke UI
-
-Invoke's UI is made possible by many contributors and open-source libraries. Thank you!
-
-## Dev environment
-
-Follow the [dev environment](../dev-environment.md) guide to get set up. Run the UI using `pnpm dev`.
-
-## Package scripts
-
-- `dev`: run the frontend in dev mode, enabling hot reloading
-- `build`: run all checks (dpdm, eslint, prettier, tsc, knip) and then build the frontend
-- `lint:dpdm`: check circular dependencies
-- `lint:eslint`: check code quality
-- `lint:prettier`: check code formatting
-- `lint:tsc`: check type issues
-- `lint:knip`: check for unused exports or objects
-- `lint`: run all checks concurrently
-- `fix`: run `eslint` and `prettier`, fixing fixable issues
-- `test:ui`: run `vitest` with the fancy web UI
-
-## Type generation
-
-We use [openapi-typescript] to generate types from the app's OpenAPI schema. The generated types are committed to the repo in [schema.ts].
-
-If you make backend changes, it's important to regenerate the frontend types:
-
-```sh
-cd invokeai/frontend/web && python ../../../scripts/generate_openapi_schema.py | pnpm typegen
-```
-
-On macOS and Linux, you can run `make frontend-typegen` as a shortcut for the above snippet.
-
-## Localization
-
-We use [i18next] for localization, but translation to languages other than English happens on our [Weblate] project.
-
-Only the English source strings (i.e. `en.json`) should be changed on this repo.
-
-## VSCode
-
-### Example debugger config
-
-```jsonc
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "chrome",
-      "request": "launch",
-      "name": "Invoke UI",
-      "url": "http://localhost:5173",
-      "webRoot": "${workspaceFolder}/invokeai/frontend/web"
-    }
-  ]
-}
-```
-
-### Remote dev
-
-We've noticed an intermittent timeout issue with the VSCode remote dev port forwarding.
-
-We suggest disabling the editor's port forwarding feature and doing it manually via SSH:
-
-```sh
-ssh -L 9090:localhost:9090 -L 5173:localhost:5173 user@host
-```
-
-## Contributing Guidelines
-
-Thanks for your interest in contributing to the Invoke Web UI!
-
-Please follow these guidelines when contributing.
-
-## Check in before investing your time
-
-Please check in before you invest your time on anything besides a trivial fix, in case it conflicts with ongoing work or isn't aligned with the vision for the app.
-
-If a feature request or issue doesn't already exist for the thing you want to work on, please create one.
-
-Ping `@psychedelicious` on [discord] in the `#frontend-dev` channel or in the feature request / issue you want to work on - we're happy to chat.
-
-## Code conventions
-
-- This is a fairly complex app with a deep component tree. Please use memoization (`useCallback`, `useMemo`, `memo`) with enthusiasm.
-- If you need to add some global, ephemeral state, please use [nanostores] if possible.
-- Be careful with your redux selectors. If they need to be parameterized, consider creating them inside a `useMemo`.
-- Feel free to use `lodash` (via `lodash-es`) to make the intent of your code clear.
-- Please add comments describing the "why", not the "how" (unless it is really arcane).
-
-## Commit format
-
-Please use the [conventional commits] spec for the web UI, with a scope of "ui":
-
-- `chore(ui): bump deps`
-- `chore(ui): lint`
-- `feat(ui): add some cool new feature`
-- `fix(ui): fix some bug`
-
-## Tests
-
-We don't do any UI testing at this time, but consider adding tests for sensitive logic.
-
-We use `vitest`, and tests should be next to the file they are testing. If the logic is in `something.ts`, the tests should be in `something.test.ts`.
-
-In some situations, we may want to test types. For example, if you use `zod` to create a schema that should match a generated type, it's best to add a test to confirm that the types match. Use `tsafe`'s assert for this.
-
-## Submitting a PR
-
-- Ensure your branch is tidy. Use an interactive rebase to clean up the commit history and reword the commit messages if they are not descriptive.
-- Run `pnpm lint`. Some issues are auto-fixable with `pnpm fix`.
-- Fill out the PR form when creating the PR.
-  - It doesn't need to be super detailed, but a screenshot or video is nice if you changed something visually.
-  - If a section isn't relevant, delete it.
-
-## Other docs
-
-- [Workflows - Design and Implementation]
-- [State Management]
-
-[discord]: https://discord.gg/ZmtBAhwWhy
-[i18next]: https://github.com/i18next/react-i18next
-[Weblate]: https://hosted.weblate.org/engage/invokeai/
-[openapi-typescript]: https://github.com/openapi-ts/openapi-typescript
-[schema.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/services/api/schema.ts
-[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
-[Workflows - Design and Implementation]: ./workflows.md
-[State Management]: ./state-management.md

docs/contributing/frontend/state-management.md

@@ -1,38 +0,0 @@
-# State Management
-
-The app makes heavy use of Redux Toolkit, its Query library, and `nanostores`.
-
-## Redux
-
-We use RTK extensively - slices, entity adapters, queries, reselect, the whole 9 yards. Their [docs](https://redux-toolkit.js.org/) are excellent.
-
-## `nanostores`
-
-[nanostores] is a tiny state management library. It provides both imperative and declarative APIs.
-
-### Example
-
-```ts
-export const $myStringOption = atom<string | null>(null);
-
-// Outside a component, or within a callback for performance-critical logic
-$myStringOption.get();
-$myStringOption.set('new value');
-
-// Inside a component
-const myStringOption = useStore($myStringOption);
-```
-
-### Where to put nanostores
-
-- For global application state, export your stores from `invokeai/frontend/web/src/app/store/nanostores/`.
-- For feature state, create a file for the stores next to the redux slice definition (e.g. `invokeai/frontend/web/src/features/myFeature/myFeatureNanostores.ts`).
-- For hooks with global state, export the store from the same file the hook is in, or put it next to the hook.
-
-### When to use nanostores
-
-- For non-serializable data that needs to be available throughout the app, use `nanostores` instead of a global.
-- For ephemeral global state (i.e. state that does not need to be persisted), use `nanostores` instead of redux.
-- For performance-critical code and in callbacks, redux selectors can be problematic due to the declarative reactivity system. Consider refactoring to use `nanostores` if there's a **measurable** performance issue.
-
-[nanostores]: https://github.com/nanostores/nanostores/

docs/contributing/frontend/workflows.md

@@ -1,314 +0,0 @@
-# Workflows - Design and Implementation
-
-> This document describes, at a high level, the design and implementation of workflows in the InvokeAI frontend. There are a substantial number of implementation details not included, but which are hopefully clear from the code.
-
-InvokeAI's backend uses graphs, composed of **nodes** and **edges**, to process data and generate images.
-
-Nodes have any number of **input fields** and **output fields**. Edges connect nodes together via their inputs and outputs. Fields have data types which dictate how they may be connected.
-
-During execution, a nodes' outputs may be passed along to any number of other nodes' inputs.
-
-Workflows are an enriched abstraction over a graph.
-
-## Design
-
-InvokeAI provide two ways to build graphs in the frontend: the [Linear UI](#linear-ui) and [Workflow Editor](#workflow-editor).
-
-To better understand the use case and challenges related to workflows, we will review both of these modes.
-
-### Linear UI
-
-This includes the **Text to Image**, **Image to Image** and **Unified Canvas** tabs.
-
-The user-managed parameters on these tabs are stored as simple objects in the application state. When the user invokes, adding a generation to the queue, we internally build a graph from these parameters.
-
-This logic can be fairly complex due to the range of features available and their interactions. Depending on the parameters selected, the graph may be very different. Building graphs in code can be challenging - you are trying to construct a non-linear structure in a linear context.
-
-The simplest graph building logic is for **Text to Image** with a SD1.5 model: [buildLinearTextToImageGraph.ts]
-
-There are many other graph builders in the same directory for different tabs or base models (e.g. SDXL). Some are pretty hairy.
-
-In the Linear UI, we go straight from **simple application state** to **graph** via these builders.
-
-### Workflow Editor
-
-The Workflow Editor is a visual graph editor, allowing users to draw edges from node to node to construct a graph. This _far_ more approachable way to create complex graphs.
-
-InvokeAI uses the [reactflow] library to power the Workflow Editor. It provides both a graph editor UI and manages its own internal graph state.
-
-#### Workflows
-
-A workflow is a representation of a graph plus additional metadata:
-
-- Name
-- Description
-- Version
-- Notes
-- [Exposed fields](#workflow-linear-view)
-- Author, tags, category, etc.
-
-Workflows should have other qualities:
-
-- Portable: you should be able to load a workflow created by another person.
-- Resilient: you should be able to "upgrade" a workflow as the application changes.
-- Abstract: as much as is possible, workflows should not be married to the specific implementation details of the application.
-
-To support these qualities, workflows are serializable, have a versioned schemas, and represent graphs as minimally as possible. Fortunately, the reactflow state for nodes and edges works perfectly for this.
-
-##### Workflow -> reactflow state -> InvokeAI graph
-
-Given a workflow, we need to be able to derive reactflow state and/or an InvokeAI graph from it.
-
-The first step - workflow to reactflow state - is very simple. The logic is in [nodesSlice.ts], in the `workflowLoaded` reducer.
-
-The reactflow state is, however, structurally incompatible with our backend's graph structure. When a user invokes on a Workflow, we need to convert the reactflow state into an InvokeAI graph. This is far simpler than the graph building logic from the Linear UI:
-[buildNodesGraph.ts]
-
-##### Nodes vs Invocations
-
-We often use the terms "node" and "invocation" interchangeably, but they may refer to different things in the frontend.
-
-reactflow [has its own definitions][reactflow-concepts] of "node", "edge" and "handle" which are closely related to InvokeAI graph concepts.
-
-- A reactflow node is related to an InvokeAI invocation. It has a "data" property, which holds the InvokeAI-specific invocation data.
-- A reactflow edge is roughly equivalent to an InvokeAI edge.
-- A reactflow handle is roughly equivalent to an InvokeAI input or output field.
-
-##### Workflow Linear View
-
-Graphs are very capable data structures, but not everyone wants to work with them all the time.
-
-To allow less technical users - or anyone who wants a less visually noisy workspace - to benefit from the power of nodes, InvokeAI has a workflow feature called the Linear View.
-
-A workflow input field can be added to this Linear View, and its input component can be presented similarly to the Linear UI tabs. Internally, we add the field to the workflow's list of exposed fields.
-
-#### OpenAPI Schema
-
-OpenAPI is a schema specification that can represent complex data structures and relationships. The backend is capable of generating an OpenAPI schema for all invocations.
-
-When the UI connects, it requests this schema and parses each invocation into an **invocation template**. Invocation templates have a number of properties, like title, description and type, but the most important ones are their input and output **field templates**.
-
-Invocation and field templates are the "source of truth" for graphs, because they indicate what the backend is able to process.
-
-When a user adds a new node to their workflow, these templates are used to instantiate a node with fields instantiated from the input and output field templates.
-
-##### Field Instances and Templates
-
-Field templates consist of:
-
-- Name: the identifier of the field, its variable name in python
-- Type: derived from the field's type annotation in python (e.g. IntegerField, ImageField, MainModelField)
-- Constraints: derived from the field's creation args in python (e.g. minimum value for an integer)
-- Default value: optionally provided in the field's creation args (e.g. 42 for an integer)
-
-Field instances are created from the templates and have name, type and optionally a value.
-
-The type of the field determines the UI components that are rendered for it.
-
-A field instance's name associates it with its template.
-
-##### Stateful vs Stateless Fields
-
-**Stateful** fields store their value in the frontend graph. Think primitives, model identifiers, images, etc. Fields are only stateful if the frontend allows the user to directly input a value for them.
-
-Many field types, however, are **stateless**. An example is a `UNetField`, which contains some data describing a UNet. Users cannot directly provide this data - it is created and consumed in the backend.
-
-Stateless fields do not store their value in the node, so their field instances do not have values.
-
-"Custom" fields will always be treated as stateless fields.
-
-##### Single and Collection Fields
-
-Field types have a name and cardinality property which may identify it as a **SINGLE**, **COLLECTION** or **SINGLE_OR_COLLECTION** field.
-
-- If a field is annotated in python as a singular value or class, its field type is parsed as a **SINGLE** type (e.g. `int`, `ImageField`, `str`).
-- If a field is annotated in python as a list, its field type is parsed as a **COLLECTION** type (e.g. `list[int]`).
-- If it is annotated as a union of a type and list, the type will be parsed as a **SINGLE_OR_COLLECTION** type (e.g. `Union[int, list[int]]`). Fields may not be unions of different types (e.g. `Union[int, list[str]]` and `Union[int, str]` are not allowed).
-
-## Implementation
-
-The majority of data structures in the backend are [pydantic] models. Pydantic provides OpenAPI schemas for all models and we then generate TypeScript types from those.
-
-The OpenAPI schema is parsed at runtime into our invocation templates.
-
-Workflows and all related data are modeled in the frontend using [zod]. Related types are inferred from the zod schemas.
-
-> In python, invocations are pydantic models with fields. These fields become node inputs. The invocation's `invoke()` function returns a pydantic model - its output. Like the invocation itself, the output model has any number of fields, which become node outputs.
-
-### zod Schemas and Types
-
-The zod schemas, inferred types, and type guards are in [types/].
-
-Roughly order from lowest-level to highest:
-
-- `common.ts`: stateful field data, and couple other misc types
-- `field.ts`: fields - types, values, instances, templates
-- `invocation.ts`: invocations and other node types
-- `workflow.ts`: workflows and constituents
-
-We customize the OpenAPI schema to include additional properties on invocation and field schemas. To facilitate parsing this schema into templates, we modify/wrap the types from [openapi-types] in `openapi.ts`.
-
-### OpenAPI Schema Parsing
-
-The entrypoint for OpenAPI schema parsing is [parseSchema.ts].
-
-General logic flow:
-
-- Iterate over all invocation schema objects
-  - Extract relevant invocation-level attributes (e.g. title, type, version, etc)
-  - Iterate over the invocation's input fields
-    - [Parse each field's type](#parsing-field-types)
-    - [Build a field input template](#building-field-input-templates) from the type - either a stateful template or "generic" stateless template
-  - Iterate over the invocation's output fields
-    - Parse the field's type (same as inputs)
-    - [Build a field output template](#building-field-output-templates)
-  - Assemble the attributes and fields into an invocation template
-
-Most of these involve very straightforward `reduce`s, but the less intuitive steps are detailed below.
-
-#### Parsing Field Types
-
-Field types are represented as structured objects:
-
-```ts
-type FieldType = {
-  name: string;
-  cardinality: 'SINGLE' | 'COLLECTION' | 'SINGLE_OR_COLLECTION';
-};
-```
-
-The parsing logic is in `parseFieldType.ts`.
-
-There are 4 general cases for field type parsing.
-
-##### Primitive Types
-
-When a field is annotated as a primitive values (e.g. `int`, `str`, `float`), the field type parsing is fairly straightforward. The field is represented by a simple OpenAPI **schema object**, which has a `type` property.
-
-We create a field type name from this `type` string (e.g. `string` -> `StringField`). The cardinality is `"SINGLE"`.
-
-##### Complex Types
-
-When a field is annotated as a pydantic model (e.g. `ImageField`, `MainModelField`, `ControlField`), it is represented as a **reference object**. Reference objects are pointers to another schema or reference object within the schema.
-
-We need to **dereference** the schema to pull these out. Dereferencing may require recursion. We use the reference object's name directly for the field type name.
-
-> Unfortunately, at this time, we've had limited success using external libraries to deference at runtime, so we do this ourselves.
-
-##### Collection Types
-
-When a field is annotated as a list of a single type, the schema object has an `items` property. They may be a schema object or reference object and must be parsed to determine the item type.
-
-We use the item type for field type name. The cardinality is `"COLLECTION"`.
-
-##### Single or Collection Types
-
-When a field is annotated as a union of a type and list of that type, the schema object has an `anyOf` property, which holds a list of valid types for the union.
-
-After verifying that the union has two members (a type and list of the same type), we use the type for field type name, with cardinality `"SINGLE_OR_COLLECTION"`.
-
-##### Optional Fields
-
-In OpenAPI v3.1, when an object is optional, it is put into an `anyOf` along with a primitive schema object with `type: 'null'`.
-
-Handling this adds a fair bit of complexity, as we now must filter out the `'null'` types and work with the remaining types as described above.
-
-If there is a single remaining schema object, we must recursively call to `parseFieldType()` to get parse it.
-
-#### Building Field Input Templates
-
-Now that we have a field type, we can build an input template for the field.
-
-Stateful fields all get a function to build their template, while stateless fields are constructed directly. This is possible because stateless fields have no default value or constraints.
-
-See [buildFieldInputTemplate.ts].
-
-#### Building Field Output Templates
-
-Field outputs are similar to stateless fields - they do not have any value in the frontend. When building their templates, we don't need a special function for each field type.
-
-See [buildFieldOutputTemplate.ts].
-
-### Managing reactflow State
-
-As described above, the workflow editor state is the essentially the reactflow state, plus some extra metadata.
-
-We provide reactflow with an array of nodes and edges via redux, and a number of [event handlers][reactflow-events]. These handlers dispatch redux actions, managing nodes and edges.
-
-The pieces of redux state relevant to workflows are:
-
-- `state.nodes.nodes`: the reactflow nodes state
-- `state.nodes.edges`: the reactflow edges state
-- `state.nodes.workflow`: the workflow metadata
-
-#### Building Nodes and Edges
-
-A reactflow node has a few important top-level properties:
-
-- `id`: unique identifier
-- `type`: a string that maps to a react component to render the node
-- `position`: XY coordinates
-- `data`: arbitrary data
-
-When the user adds a node, we build **invocation node data**, storing it in `data`. Invocation properties (e.g. type, version, label, etc.) are copied from the invocation template. Inputs and outputs are built from the invocation template's field templates.
-
-See [buildInvocationNode.ts].
-
-Edges are managed by reactflow, but briefly, they consist of:
-
-- `source`: id of the source node
-- `sourceHandle`: id of the source node handle (output field)
-- `target`: id of the target node
-- `targetHandle`: id of the target node handle (input field)
-
-> Edge creation is gated behind validation logic. This validation compares the input and output field types and overall graph state.
-
-#### Building a Workflow
-
-Building a workflow entity is as simple as dropping the nodes, edges and metadata into an object.
-
-Each node and edge is parsed with a zod schema, which serves to strip out any unneeded data.
-
-See [buildWorkflow.ts].
-
-#### Loading a Workflow
-
-Workflows may be loaded from external sources or the user's local instance. In all cases, the workflow needs to be handled with care, as an untrusted object.
-
-Loading has a few stages which may throw or warn if there are problems:
-
-- Parsing the workflow data structure itself, [migrating](#workflow-migrations) it if necessary (throws)
-- Check for a template for each node (warns)
-- Check each node's version against its template (warns)
-- Validate the source and target of each edge (warns)
-
-This validation occurs in [validateWorkflow.ts].
-
-If there are no fatal errors, the workflow is then stored in redux state.
-
-### Workflow Migrations
-
-When the workflow schema changes, we may need to perform some data migrations. This occurs as workflows are loaded. zod schemas for each workflow schema version is retained to facilitate migrations.
-
-Previous schemas are in folders in `invokeai/frontend/web/src/features/nodes/types/`, eg `v1/`.
-
-Migration logic is in [migrations.ts].
-
-<!-- links -->
-
-[pydantic]: https://github.com/pydantic/pydantic 'pydantic'
-[zod]: https://github.com/colinhacks/zod 'zod'
-[openapi-types]: https://github.com/kogosoftwarellc/open-api/tree/main/packages/openapi-types 'openapi-types'
-[reactflow]: https://github.com/xyflow/xyflow 'reactflow'
-[reactflow-concepts]: https://reactflow.dev/learn/concepts/terms-and-definitions
-[reactflow-events]: https://reactflow.dev/api-reference/react-flow#event-handlers
-[buildWorkflow.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/workflow/buildWorkflow.ts
-[nodesSlice.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/store/nodesSlice.ts
-[buildLinearTextToImageGraph.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/graph/buildLinearTextToImageGraph.ts
-[buildNodesGraph.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/graph/buildNodesGraph.ts
-[buildInvocationNode.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/node/buildInvocationNode.ts
-[validateWorkflow.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/workflow/validateWorkflow.ts
-[migrations.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/workflow/migrations.ts
-[parseSchema.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/schema/parseSchema.ts
-[buildFieldInputTemplate.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/schema/buildFieldInputTemplate.ts
-[buildFieldOutputTemplate.ts]: https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/schema/buildFieldOutputTemplate.ts

docs/contributing/index.md

@@ -1,52 +0,0 @@
-# Contributing
-
-Invoke 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.
-
-We welcome contributions, whether features, bug fixes, code cleanup, testing, code reviews, documentation or translation. Please check in with us before diving in to code to ensure your work aligns with our vision.
-
-## Development
-
-If you’d like to help with development, please see our [development guide](contribution_guides/development.md).
-
-**New Contributors:** If you’re unfamiliar with contributing to open source projects, take a look at our [new contributor guide](contribution_guides/newContributorChecklist.md).
-
-## Nodes
-
-If you’d like to add a Node, please see our [nodes contribution guide](../nodes/contributingNodes.md).
-
-## 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.
-
-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.
-
-## Documentation
-
-If you’d like to help with documentation, please see our [documentation guide](contribution_guides/documentation.md).
-
-## Translation
-
-If you'd like to help with translation, please see our [translation guide](contribution_guides/translation.md).
-
-## Tutorials
-
-Please reach out to @hipsterusername on [Discord](https://discord.gg/ZmtBAhwWhy) to help create tutorials for InvokeAI.
-
-## Contributors
-
-This project is a combined effort of dedicated people from across the world. [Check out the list of all these amazing people](contributors.md). We thank them for their time, hard work and effort.
-
-## Code of Conduct
-
-The InvokeAI community is a welcoming place, and we want your help in maintaining that. Please review our [Code of Conduct](../CODE_OF_CONDUCT.md) to learn more - it's essential to maintaining a respectful and inclusive environment.
-
-By making a contribution to this project, you certify that:
-
-1. The contribution was created in whole or in part by you and you have the right to submit it under the open-source license indicated in this project’s GitHub repository; or
-2. The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open-source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, under the same open-source license (unless you are permitted to submit under a different license); or
-3. The contribution was provided directly to you by some other person who certified (1) or (2) and you have not modified it; or
-4. You understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information you submit with it, including your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open-source license(s) involved.
-
-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.

docs/deprecated/CLI.md

@@ -0,0 +1,589 @@
+---
+title: Command-Line Interface
+---
+
+# :material-bash: CLI
+
+## **Interactive Command Line Interface**
+
+The InvokeAI command line interface (CLI) provides scriptable access
+to InvokeAI's features.Some advanced features are only available
+through the CLI, though they eventually find their way into the WebUI.
+
+The CLI is accessible from the `invoke.sh`/`invoke.bat` launcher by
+selecting option (1). Alternatively, it can be launched directly from
+the command line by activating the InvokeAI environment and giving the
+command:
+
+```bash
+invokeai
+```
+
+After some startup messages, you will be presented with the `invoke> `
+prompt. Here you can type prompts to generate images and issue other
+commands to load and manipulate generative models. The CLI has a large
+number of command-line options that control its behavior. To get a
+concise summary of the options, call `invokeai` with the `--help` argument:
+
+```bash
+invokeai --help
+```
+
+The script uses the readline library to allow for in-line editing, command
+history (++up++ and ++down++), autocompletion, and more. To help keep track of
+which prompts generated which images, the script writes a log file of image
+names and prompts to the selected output directory.
+
+Here is a typical session
+
+```bash
+PS1:C:\Users\fred> invokeai
+* Initializing, be patient...
+* Initializing, be patient...
+>> Initialization file /home/lstein/invokeai/invokeai.init found. Loading...
+>> Internet connectivity is True
+>> InvokeAI, version 2.3.0-rc5
+>> InvokeAI runtime directory is "/home/lstein/invokeai"
+>> GFPGAN Initialized
+>> CodeFormer Initialized
+>> ESRGAN Initialized
+>> Using device_type cuda
+>> xformers memory-efficient attention is available and enabled
+     (...more initialization messages...)
+* Initialization done! Awaiting your command (-h for help, 'q' to quit)
+invoke> ashley judd riding a camel -n2 -s150
+Outputs:
+   outputs/img-samples/00009.png: "ashley judd riding a camel" -n2 -s150 -S 416354203
+   outputs/img-samples/00010.png: "ashley judd riding a camel" -n2 -s150 -S 1362479620
+
+invoke> "there's a fly in my soup" -n6 -g
+    outputs/img-samples/00011.png: "there's a fly in my soup" -n6 -g -S 2685670268
+    seeds for individual rows: [2685670268, 1216708065, 2335773498, 822223658, 714542046, 3395302430]
+invoke> q
+```
+
+![invoke-py-demo](../assets/dream-py-demo.png)
+
+## Arguments
+
+The script recognizes a series of command-line switches that will
+change important global defaults, such as the directory for image
+outputs and the location of the model weight files.
+
+### List of arguments recognized at the command line
+
+These command-line arguments can be passed to `invoke.py` when you first run it
+from the Windows, Mac or Linux command line. Some set defaults that can be
+overridden on a per-prompt basis (see
+[List of prompt arguments](#list-of-prompt-arguments). Others
+
+| Argument <img width="240" align="right"/> | Shortcut <img width="100" align="right"/> | Default <img width="320" align="right"/>       | Description                                                                                          |
+| ----------------------------------------- | ----------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `--help`                                  | `-h`                                      |                                                | Print a concise help message.                                                                        |
+| `--outdir <path>`                         | `-o<path>`                                | `outputs/img_samples`                          | Location for generated images.                                                                       |
+| `--prompt_as_dir`                         | `-p`                                      | `False`                                        | Name output directories using the prompt text.                                                       |
+| `--from_file <path>`                      |                                           | `None`                                         | Read list of prompts from a file. Use `-` to read from standard input                                |
+| `--model <modelname>`                     |                                           | `stable-diffusion-1.5`                         | Loads the initial model specified in configs/models.yaml. |
+| `--ckpt_convert `           |                                                         | `False`                                        | If provided both .ckpt and .safetensors files will be auto-converted into diffusers format in memory |
+| `--autoconvert <path>`                    |                          | `None`                                        | On startup, scan the indicated directory for new .ckpt/.safetensor files and automatically convert and import them |
+| `--precision`                             |                                           | `fp16`                                         | Provide `fp32` for full precision mode, `fp16` for half-precision. `fp32` needed for Macintoshes and some NVidia cards. |
+| `--png_compression <0-9>`                 | `-z<0-9>`                                 | `6`                                            | Select level of compression for output files, from 0 (no compression) to 9 (max compression)         |
+| `--safety-checker`                        |                                           | `False`                                        | Activate safety checker for NSFW and other potentially disturbing imagery                            |
+| `--patchmatch`, `--no-patchmatch`                 |                                   | `--patchmatch`                                        | Load/Don't load the PatchMatch inpainting extension    |
+| `--xformers`, `--no-xformers`                 |                                   | `--xformers`                                        | Load/Don't load the Xformers memory-efficient attention module (CUDA only)    |
+| `--web`                                   |                                           | `False`                                        | Start in web server mode                                                                             |
+| `--host <ip addr>`                        |                                           | `localhost`                                    | Which network interface web server should listen on. Set to 0.0.0.0 to listen on any.                |
+| `--port <port>`                           |                                           | `9090`                                         | Which port web server should listen for requests on.                                                 |
+| `--config <path>`                         |                                           | `configs/models.yaml`                          | Configuration file for models and their weights.                                                     |
+| `--iterations <int>`                      | `-n<int>`                                 | `1`                                            | How many images to generate per prompt.                                                              |
+| `--width <int>`                           | `-W<int>`                                 | `512`                                    | Width of generated image                                                                                                                                                                                                                         |
+| `--height <int>`                          | `-H<int>`                                 | `512`                                    | Height of generated image                                                                                                        | `--steps <int>`                           | `-s<int>`                                 | `50`                                     | How many steps of refinement to apply                                                                                                                                                                                                            |
+| `--strength <float>`                      | `-s<float>` | `0.75`  | For img2img: how hard to try to match the prompt to the initial image. Ranges from 0.0-0.99, with higher values replacing the initial image completely. |
+| `--fit`                                   | `-F`        | `False` | For img2img: scale the init image to fit into the specified -H and -W dimensions                                                                             |
+| `--grid`                                  | `-g`                                      | `False`                                        | Save all image series as a grid rather than individually.                                            |
+| `--sampler <sampler>`                     | `-A<sampler>`                             | `k_lms`                                        | Sampler to use. Use `-h` to get list of available samplers.                                          |
+| `--seamless`                              |                                           | `False`                                        | Create interesting effects by tiling elements of the image.                                          |
+| `--embedding_path <path>`                 |                                           | `None`                                         | Path to pre-trained embedding manager checkpoints, for custom models                                 |
+| `--gfpgan_model_path`                     |                                           | `experiments/pretrained_models/GFPGANv1.4.pth` | Path to GFPGAN model file.                                              |
+| `--free_gpu_mem`                          |                                           | `False`                                        | Free GPU memory after sampling, to allow image decoding and saving in low VRAM conditions            |
+| `--precision`                             |                                           | `auto`                                         | Set model precision, default is selected by device. Options: auto, float32, float16, autocast        |
+
+!!! warning "These arguments are deprecated but still work"
+
+    <div align="center" markdown>
+
+    | Argument           |  Shortcut  |  Default            |  Description |
+    |--------------------|------------|---------------------|--------------|
+    | `--full_precision`  |             | `False`                | Same as `--precision=fp32`|
+    | `--weights <path>`   |            | `None`                | Path to weights file; use `--model stable-diffusion-1.4` instead |
+    | `--laion400m`        | `-l`         | `False`               | Use older LAION400m weights; use `--model=laion400m` instead |
+
+    </div>
+
+!!! tip
+
+      On Windows systems, you may run into
+      problems when passing the invoke script standard backslashed path
+      names because the Python interpreter treats "\" as an escape.
+      You can either double your slashes (ick): `C:\\path\\to\\my\\file`, or
+      use Linux/Mac style forward slashes (better): `C:/path/to/my/file`.
+
+## The .invokeai initialization file
+
+To start up invoke.py with your preferred settings, place your desired
+startup options in a file in your home directory named `.invokeai` The
+file should contain the startup options as you would type them on the
+command line (`--steps=10 --grid`), one argument per line, or a
+mixture of both using any of the accepted command switch formats:
+
+!!! example "my unmodified initialization file"
+
+    ```bash title="~/.invokeai" linenums="1"
+    # InvokeAI initialization file
+    # This is the InvokeAI initialization file, which contains command-line default values.
+    # Feel free to edit. If anything goes wrong, you can re-initialize this file by deleting
+    # or renaming it and then running invokeai-configure again.
+
+    # The --root option below points to the folder in which InvokeAI stores its models, configs and outputs.
+    --root="/Users/mauwii/invokeai"
+
+    # the --outdir option controls the default location of image files.
+    --outdir="/Users/mauwii/invokeai/outputs"
+
+    # You may place other  frequently-used startup commands here, one or more per line.
+    # Examples:
+    # --web --host=0.0.0.0
+    # --steps=20
+    # -Ak_euler_a -C10.0
+    ```
+
+!!! note
+
+    The  initialization file only accepts the command line arguments.
+    There are additional arguments that you can provide on the `invoke>` command
+    line (such as `-n` or `--iterations`) that cannot be entered into this file.
+    Also be alert for empty blank lines at the end of the file, which will cause
+    an arguments error at startup time.
+
+## List of prompt arguments
+
+After the invoke.py script initializes, it will present you with a `invoke>`
+prompt. Here you can enter information to generate images from text
+([txt2img](#txt2img)), to embellish an existing image or sketch
+([img2img](#img2img)), or to selectively alter chosen regions of the image
+([inpainting](#inpainting)).
+
+### txt2img
+
+!!! example ""
+
+    ```bash
+    invoke> waterfall and rainbow -W640 -H480
+    ```
+
+    This will create the requested image with the dimensions 640 (width)
+    and 480 (height).
+
+Here are the invoke> command that apply to txt2img:
+
+| Argument <img width="680" align="right"/> | Shortcut <img width="420" align="right"/> | Default <img width="480" align="right"/> | Description                                                                                                                                                                                                                                      |
+| ----------------------------------------- | ----------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "my prompt"                               |                                           |                                          | Text prompt to use. The quotation marks are optional.                                                                                                                                                                                            |
+| `--width <int>`                           | `-W<int>`                                 | `512`                                    | Width of generated image                                                                                                                                                                                                                         |
+| `--height <int>`                          | `-H<int>`                                 | `512`                                    | Height of generated image                                                                                                                                                                                                                        |
+| `--iterations <int>`                      | `-n<int>`                                 | `1`                                      | How many images to generate from this prompt                                                                                                                                                                                                     |
+| `--steps <int>`                           | `-s<int>`                                 | `50`                                     | How many steps of refinement to apply                                                                                                                                                                                                            |
+| `--cfg_scale <float>`                     | `-C<float>`                               | `7.5`                                    | How hard to try to match the prompt to the generated image; any number greater than 1.0 works, but the useful range is roughly 5.0 to 20.0                                                                                                       |
+| `--seed <int>`                            | `-S<int>`                                 | `None`                                   | Set the random seed for the next series of images. This can be used to recreate an image generated previously.                                                                                                                                   |
+| `--sampler <sampler>`                     | `-A<sampler>`                             | `k_lms`                                  | Sampler to use. Use -h to get list of available samplers.                                                                                                                                                                                        |
+| `--karras_max <int>`                      |                                           | `29`                                     | When using k\_\* samplers, set the maximum number of steps before shifting from using the Karras noise schedule (good for low step counts) to the LatentDiffusion noise schedule (good for high step counts) This value is sticky. [29]          |
+| `--hires_fix`                             |                                           |                                          | Larger images often have duplication artefacts. This option suppresses duplicates by generating the image at low res, and then using img2img to increase the resolution                                                                          |
+| `--png_compression <0-9>`                 | `-z<0-9>`                                 | `6`                                      | Select level of compression for output files, from 0 (no compression) to 9 (max compression)                                                                                                                                                     |
+| `--grid`                                  | `-g`                                      | `False`                                  | Turn on grid mode to return a single image combining all the images generated by this prompt                                                                                                                                                     |
+| `--individual`                            | `-i`                                      | `True`                                   | Turn off grid mode (deprecated; leave off --grid instead)                                                                                                                                                                                        |
+| `--outdir <path>`                         | `-o<path>`                                | `outputs/img_samples`                    | Temporarily change the location of these images                                                                                                                                                                                                  |
+| `--seamless`                              |                                           | `False`                                  | Activate seamless tiling for interesting effects                                                                                                                                                                                                 |
+| `--seamless_axes`                         |                                           | `x,y`                                    | Specify which axes to use circular convolution on.                                                                                                                                                                                               |
+| `--log_tokenization`                      | `-t`                                      | `False`                                  | Display a color-coded list of the parsed tokens derived from the prompt                                                                                                                                                                          |
+| `--skip_normalization`                    | `-x`                                      | `False`                                  | Weighted subprompts will not be normalized. See [Weighted Prompts](../features/OTHER.md#weighted-prompts)                                                                                                                                                  |
+| `--upscale <int> <float>`                 | `-U <int> <float>`                        | `-U 1 0.75`                              | Upscale image by magnification factor (2, 4), and set strength of upscaling (0.0-1.0). If strength not set, will default to 0.75.                                                                                                                |
+| `--facetool_strength <float>`             | `-G <float> `                             | `-G0`                                    | Fix faces (defaults to using the GFPGAN algorithm); argument indicates how hard the algorithm should try (0.0-1.0)                                                                                                                               |
+| `--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](../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.)                                   |
+
+!!! note
+
+    the width and height of the image must be multiples of 64. You can
+    provide different values, but they will be rounded down to the nearest multiple
+    of 64.
+
+!!! example "This is a example of img2img"
+
+    ```bash
+    invoke> waterfall and rainbow -I./vacation-photo.png -W640 -H480 --fit
+    ```
+
+This will modify the indicated vacation photograph by making it more like the
+prompt. Results will vary greatly depending on what is in the image. We also ask
+to --fit the image into a box no bigger than 640x480. Otherwise the image size
+will be identical to the provided photo and you may run out of memory if it is
+large.
+
+In addition to the command-line options recognized by txt2img, img2img accepts
+additional options:
+
+| Argument <img width="160" align="right"/> | Shortcut    | Default | Description                                                                                                                                |
+| ----------------------------------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--init_img <path>`                       | `-I<path>`  | `None`  | Path to the initialization image                                                                                                           |
+| `--fit`                                   | `-F`        | `False` | Scale the image to fit into the specified -H and -W dimensions                                                                             |
+| `--strength <float>`                      | `-s<float>` | `0.75`  | How hard to try to match the prompt to the initial image. Ranges from 0.0-0.99, with higher values replacing the initial image completely. |
+
+### inpainting
+
+!!! example ""
+
+    ```bash
+    invoke> waterfall and rainbow -I./vacation-photo.png -M./vacation-mask.png -W640 -H480 --fit
+    ```
+
+    This will do the same thing as img2img, but image alterations will
+    only occur within transparent areas defined by the mask file specified
+    by `-M`. You may also supply just a single initial image with the areas
+    to overpaint made transparent, but you must be careful not to destroy
+    the pixels underneath when you create the transparent areas. See
+    [Inpainting](INPAINTING.md) for details.
+
+inpainting accepts all the arguments used for txt2img and img2img, as well as
+the --mask (-M) and --text_mask (-tm) arguments:
+
+| Argument <img width="100" align="right"/> | Shortcut                 | Default | Description                                                                                      |
+| ----------------------------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------ |
+| `--init_mask <path>`                      | `-M<path>`               | `None`  | Path to an image the same size as the initial_image, with areas for inpainting made transparent. |
+| `--invert_mask `                          |                          | False   | If true, invert the mask so that transparent areas are opaque and vice versa.                    |
+| `--text_mask <prompt> [<float>]`          | `-tm <prompt> [<float>]` | <none>  | Create a mask from a text prompt describing part of the image                                    |
+
+The mask may either be an image with transparent areas, in which case the
+inpainting will occur in the transparent areas only, or a black and white image,
+in which case all black areas will be painted into.
+
+`--text_mask` (short form `-tm`) is a way to generate a mask using a text
+description of the part of the image to replace. For example, if you have an
+image of a breakfast plate with a bagel, toast and scrambled eggs, you can
+selectively mask the bagel and replace it with a piece of cake this way:
+
+```bash
+invoke> a piece of cake -I /path/to/breakfast.png -tm bagel
+```
+
+The algorithm uses <a
+href="https://github.com/timojl/clipseg">clipseg</a> to classify different
+regions of the image. The classifier puts out a confidence score for each region
+it identifies. Generally regions that score above 0.5 are reliable, but if you
+are getting too much or too little masking you can adjust the threshold down (to
+get more mask), or up (to get less). In this example, by passing `-tm` a higher
+value, we are insisting on a more stringent classification.
+
+```bash
+invoke> a piece of cake -I /path/to/breakfast.png -tm bagel 0.6
+```
+
+### Custom Styles and Subjects
+
+You can load and use hundreds of community-contributed Textual
+Inversion models just by typing the appropriate trigger phrase. Please
+see [Concepts Library](../features/CONCEPTS.md) for more details.
+
+## Other Commands
+
+The CLI offers a number of commands that begin with "!".
+
+### Postprocessing images
+
+To postprocess a file using face restoration or upscaling, use the `!fix`
+command.
+
+#### `!fix`
+
+This command runs a post-processor on a previously-generated image. It takes a
+PNG filename or path and applies your choice of the `-U`, `-G`, or `--embiggen`
+switches in order to fix faces or upscale. If you provide a filename, the script
+will look for it in the current output directory. Otherwise you can provide a
+full or partial path to the desired file.
+
+Some examples:
+
+!!! example "Upscale to 4X its original size and fix faces using codeformer"
+
+    ```bash
+    invoke> !fix 0000045.4829112.png -G1 -U4 -ft codeformer
+    ```
+
+!!! example "Use the GFPGAN algorithm to fix faces, then upscale to 3X using --embiggen"
+
+    ```bash
+    invoke> !fix 0000045.4829112.png -G0.8 -ft gfpgan
+    >> fixing outputs/img-samples/0000045.4829112.png
+    >> retrieved seed 4829112 and prompt "boy enjoying a banana split"
+    >> GFPGAN - Restoring Faces for image seed:4829112
+    Outputs:
+    [1] outputs/img-samples/000017.4829112.gfpgan-00.png: !fix "outputs/img-samples/0000045.4829112.png" -s 50 -S  -W 512 -H 512 -C 7.5 -A k_lms -G 0.8
+    ```
+
+#### `!mask`
+
+This command takes an image, a text prompt, and uses the `clipseg` algorithm to
+automatically generate a mask of the area that matches the text prompt. It is
+useful for debugging the text masking process prior to inpainting with the
+`--text_mask` argument. See [INPAINTING.md] for details.
+
+### Model selection and importation
+
+The CLI allows you to add new models on the fly, as well as to switch
+among them rapidly without leaving the script. There are several
+different model formats, each described in the [Model Installation
+Guide](../installation/050_INSTALLING_MODELS.md).
+
+#### `!models`
+
+This prints out a list of the models defined in `config/models.yaml'. The active
+model is bold-faced
+
+Example:
+
+<pre>
+inpainting-1.5            not loaded  Stable Diffusion inpainting model
+<b>stable-diffusion-1.5          active  Stable Diffusion v1.5</b>
+waifu-diffusion           not loaded  Waifu Diffusion v1.4
+</pre>
+
+#### `!switch <model>`
+
+This quickly switches from one model to another without leaving the CLI script.
+`invoke.py` uses a memory caching system; once a model has been loaded,
+switching back and forth is quick. The following example shows this in action.
+Note how the second column of the `!models` table changes to `cached` after a
+model is first loaded, and that the long initialization step is not needed when
+loading a cached model.
+
+#### `!import_model <hugging_face_repo_ID>`
+
+This imports and installs a `diffusers`-style model that is stored on
+the [HuggingFace Web Site](https://huggingface.co). You can look up
+any [Stable Diffusion diffusers
+model](https://huggingface.co/models?library=diffusers) and install it
+with a command like the following:
+
+```bash
+!import_model prompthero/openjourney
+```
+
+#### `!import_model <path/to/diffusers/directory>`
+
+If you have a copy of a `diffusers`-style model saved to disk, you can
+import it by passing the path to model's top-level directory.
+
+#### `!import_model <url>`
+
+For a `.ckpt` or `.safetensors` file, if you have a direct download
+URL for the file, you can provide it to `!import_model` and the file
+will be downloaded and installed for you.
+
+#### `!import_model <path/to/model/weights.ckpt>`
+
+This command imports a new model weights file into InvokeAI, makes it available
+for image generation within the script, and writes out the configuration for the
+model into `config/models.yaml` for use in subsequent sessions.
+
+Provide `!import_model` with the path to a weights file ending in `.ckpt`. If
+you type a partial path and press tab, the CLI will autocomplete. Although it
+will also autocomplete to `.vae` files, these are not currenty supported (but
+will be soon).
+
+When you hit return, the CLI will prompt you to fill in additional information
+about the model, including the short name you wish to use for it with the
+`!switch` command, a brief description of the model, the default image width and
+height to use with this model, and the model's configuration file. The latter
+three fields are automatically filled with reasonable defaults. In the example
+below, the bold-faced text shows what the user typed in with the exception of
+the width, height and configuration file paths, which were filled in
+automatically.
+
+#### `!import_model <path/to/directory_of_models>`
+
+If you provide the path of a directory that contains one or more
+`.ckpt` or `.safetensors` files, the CLI will scan the directory and
+interactively offer to import the models it finds there. Also see the
+`--autoconvert` command-line option.
+
+#### `!edit_model <name_of_model>`
+
+The `!edit_model` command can be used to modify a model that is already defined
+in `config/models.yaml`. Call it with the short name of the model you wish to
+modify, and it will allow you to modify the model's `description`, `weights` and
+other fields.
+
+Example:
+
+<pre>
+invoke> <b>!edit_model waifu-diffusion</b>
+>> Editing model waifu-diffusion from configuration file ./configs/models.yaml
+description: <b>Waifu diffusion v1.4beta</b>
+weights: models/ldm/stable-diffusion-v1/<b>model-epoch10-float16.ckpt</b>
+config: configs/stable-diffusion/v1-inference.yaml
+width: 512
+height: 512
+
+>> New configuration:
+waifu-diffusion:
+  config: configs/stable-diffusion/v1-inference.yaml
+  description: Waifu diffusion v1.4beta
+  weights: models/ldm/stable-diffusion-v1/model-epoch10-float16.ckpt
+  height: 512
+  width: 512
+
+OK to import [n]? y
+>> Caching model stable-diffusion-1.4 in system RAM
+>> Loading waifu-diffusion from models/ldm/stable-diffusion-v1/model-epoch10-float16.ckpt
+...
+</pre>
+
+### History processing
+
+The CLI provides a series of convenient commands for reviewing previous actions,
+retrieving them, modifying them, and re-running them.
+
+#### `!history`
+
+The invoke script keeps track of all the commands you issue during a session,
+allowing you to re-run them. On Mac and Linux systems, it also writes the
+command-line history out to disk, giving you access to the most recent 1000
+commands issued.
+
+The `!history` command will return a numbered list of all the commands issued
+during the session (Windows), or the most recent 1000 commands (Mac|Linux). You
+can then repeat a command by using the command `!NNN`, where "NNN" is the
+history line number. For example:
+
+!!! example ""
+
+    ```bash
+    invoke> !history
+    ...
+    [14] happy woman sitting under tree wearing broad hat and flowing garment
+    [15] beautiful woman sitting under tree wearing broad hat and flowing garment
+    [18] beautiful woman sitting under tree wearing broad hat and flowing garment -v0.2 -n6
+    [20] watercolor of beautiful woman sitting under tree wearing broad hat and flowing garment -v0.2 -n6 -S2878767194
+    [21] surrealist painting of beautiful woman sitting under tree wearing broad hat and flowing garment -v0.2 -n6 -S2878767194
+    ...
+    invoke> !20
+    invoke> watercolor of beautiful woman sitting under tree wearing broad hat and flowing garment -v0.2 -n6 -S2878767194
+    ```
+
+####`!fetch`
+
+This command retrieves the generation parameters from a previously generated
+image and either loads them into the command line (Linux|Mac), or prints them
+out in a comment for copy-and-paste (Windows). You may provide either the name
+of a file in the current output directory, or a full file path. Specify path to
+a folder with image png files, and wildcard \*.png to retrieve the dream command
+used to generate the images, and save them to a file commands.txt for further
+processing.
+
+!!! example "load the generation command for a single png file"
+
+    ```bash
+    invoke> !fetch 0000015.8929913.png
+    # the script returns the next line, ready for editing and running:
+    invoke> a fantastic alien landscape -W 576 -H 512 -s 60 -A plms -C 7.5
+    ```
+
+!!! example "fetch the generation commands from a batch of files and store them into `selected.txt`"
+
+    ```bash
+    invoke> !fetch outputs\selected-imgs\*.png selected.txt
+    ```
+
+#### `!replay`
+
+This command replays a text file generated by !fetch or created manually
+
+!!! example
+
+    ```bash
+    invoke> !replay outputs\selected-imgs\selected.txt
+    ```
+
+!!! note
+
+    These commands may behave unexpectedly if given a PNG file that was
+    not generated by InvokeAI.
+
+#### `!search <search string>`
+
+This is similar to !history but it only returns lines that contain
+`search string`. For example:
+
+```bash
+invoke> !search surreal
+[21] surrealist painting of beautiful woman sitting under tree wearing broad hat and flowing garment -v0.2 -n6 -S2878767194
+```
+
+#### `!clear`
+
+This clears the search history from memory and disk. Be advised that this
+operation is irreversible and does not issue any warnings!
+
+## Command-line editing and completion
+
+The command-line offers convenient history tracking, editing, and command
+completion.
+
+- To scroll through previous commands and potentially edit/reuse them, use the
+  ++up++ and ++down++ keys.
+- To edit the current command, use the ++left++ and ++right++ keys to position
+  the cursor, and then ++backspace++, ++delete++ or insert characters.
+- To move to the very beginning of the command, type ++ctrl+a++ (or
+  ++command+a++ on the Mac)
+- To move to the end of the command, type ++ctrl+e++.
+- To cut a section of the command, position the cursor where you want to start
+  cutting and type ++ctrl+k++
+- To paste a cut section back in, position the cursor where you want to paste,
+  and type ++ctrl+y++
+
+Windows users can get similar, but more limited, functionality if they launch
+`invoke.py` with the `winpty` program and have the `pyreadline3` library
+installed:
+
+```batch
+> winpty python scripts\invoke.py
+```
+
+On the Mac and Linux platforms, when you exit invoke.py, the last 1000 lines of
+your command-line history will be saved. When you restart `invoke.py`, you can
+access the saved history using the ++up++ key.
+
+In addition, limited command-line completion is installed. In various contexts,
+you can start typing your command and press ++tab++. A list of potential
+completions will be presented to you. You can then type a little more, hit
+++tab++ again, and eventually autocomplete what you want.
+
+When specifying file paths using the one-letter shortcuts, the CLI will attempt
+to complete pathnames for you. This is most handy for the `-I` (init image) and
+`-M` (init mask) paths. To initiate completion, start the path with a slash
+(`/`) or `./`. For example:
+
+```bash
+invoke> zebra with a mustache -I./test-pictures<TAB>
+-I./test-pictures/Lincoln-and-Parrot.png  -I./test-pictures/zebra.jpg        -I./test-pictures/madonna.png
+-I./test-pictures/bad-sketch.png          -I./test-pictures/man_with_eagle/
+```
+
+You can then type ++z++, hit ++tab++ again, and it will autofill to `zebra.jpg`.
+
+More text completion features (such as autocompleting seeds) are on their way.

docs/deprecated/EMBIGGEN.md

@@ -0,0 +1,167 @@
+---
+title: Embiggen
+---
+
+# :material-loupe: Embiggen
+
+**upscale your images on limited memory machines**
+
+GFPGAN and Real-ESRGAN are both memory intensive. In order to avoid
+crashes and memory overloads during the Stable Diffusion process,
+these effects are applied after Stable Diffusion has completed its
+work.
+
+In single image generations, you will see the output right away but
+when you are using multiple iterations, the images will first be
+generated and then upscaled and face restored after that process is
+complete. While the image generation is taking place, you will still
+be able to preview the base images.
+
+If you wish to stop during the image generation but want to upscale or
+face restore a particular generated image, pass it again with the same
+prompt and generated seed along with the `-U` and `-G` prompt
+arguments to perform those actions.
+
+## Embiggen
+
+If you wanted to be able to do more (pixels) without running out of VRAM,
+or you want to upscale with details that couldn't possibly appear
+without the context of a prompt, this is the feature to try out.
+
+Embiggen automates the process of taking an init image, upscaling it,
+cutting it into smaller tiles that slightly overlap, running all the
+tiles through img2img to refine details with respect to the prompt,
+and "stitching" the tiles back together into a cohesive image.
+
+It automatically computes how many tiles are needed, and so it can be fed
+*ANY* size init image and perform Img2Img on it (though it will be run only
+one tile at a time, which can cause problems, see the Note at the end).
+
+If you're familiar with "GoBig" (ala [progrock-stable](https://github.com/lowfuel/progrock-stable))
+it's similar to that, except it can work up to an arbitrarily large size
+(instead of just 2x), with tile overlaps configurable as a ratio, and
+has extra logic to re-run any number of the tile sub-sections of the image
+if for example a small part of a huge run got messed up.
+
+### Usage
+
+`-embiggen <scaling_factor> <esrgan_strength> <overlap_ratio OR overlap_pixels>`
+
+Takes a scaling factor relative to the size of the `--init_img` (`-I`), followed by
+ESRGAN upscaling strength (0 - 1.0), followed by minimum amount of overlap
+between tiles as a decimal ratio (0 - 1.0) *OR* a number of pixels.
+
+The scaling factor is how much larger than the `--init_img` the output
+should be, and will multiply both x and y axis, so an image that is a
+scaling factor of 3.0 has 3*3= 9 times as many pixels, and will take
+(at least) 9 times as long (see overlap for why it might be
+longer). If the `--init_img` is already the right size `-embiggen 1`,
+and it can also be less than one if the init_img is too big.
+
+Esrgan_strength defaults to 0.75, and the overlap_ratio defaults to
+0.25, both are optional.
+
+Unlike Img2Img, the `--width` (`-W`) and `--height` (`-H`) arguments
+do not control the size of the image as a whole, but the size of the
+tiles used to Embiggen the image.
+
+ESRGAN is used to upscale the `--init_img` prior to cutting it into
+tiles/pieces to run through img2img and then stitch back
+together. Embiggen can be run without ESRGAN; just set the strength to
+zero (e.g. `-embiggen 1.75 0`). The output of Embiggen can also be
+upscaled after it's finished (`-U`).
+
+The overlap is the minimum that tiles will overlap with adjacent
+tiles, specified as either a ratio or a number of pixels. How much the
+tiles overlap determines the likelihood the tiling will be noticable,
+really small overlaps (e.g. a couple of pixels) may produce noticeable
+grid-like fuzzy distortions in the final stitched image. Though, as
+the overlapping space doesn't contribute to making the image bigger,
+and the larger the overlap the more tiles (and the more time) it will
+take to finish.
+
+Because the overlapping parts of tiles don't "contribute" to
+increasing size, every tile after the first in a row or column
+effectively only covers an extra `1 - overlap_ratio` on each axis. If
+the input/`--init_img` is same size as a tile, the ideal (for time)
+scaling factors with the default overlap (0.25) are 1.75, 2.5, 3.25,
+4.0, etc.
+
+`-embiggen_tiles <spaced list of tiles>`
+
+An advanced usage useful if you only want to alter parts of the image
+while running Embiggen. It takes a list of tiles by number to run and
+replace onto the initial image e.g. `1 3 5`. It's useful for either
+fixing problem spots from a previous Embiggen run, or selectively
+altering the prompt for sections of an image - for creative or
+coherency reasons.
+
+Tiles are numbered starting with one, and left-to-right,
+top-to-bottom.  So, if you are generating a 3x3 tiled image, the
+middle row would be `4 5 6`.
+
+`-embiggen_strength <strength>`
+
+Another advanced option if you want to experiment with the strength parameter
+that embiggen uses when it calls Img2Img. Values range from 0.0 to 1.0
+and lower values preserve more of the character of the initial image.
+Values that are too high will result in a completely different end image,
+while values that are too low will result in an image not dissimilar to one
+you would get with ESRGAN upscaling alone. The default value is 0.4.
+
+### Examples
+
+!!! example ""
+
+    Running Embiggen with 512x512 tiles on an existing image, scaling up by a factor of 2.5x;
+    and doing the same again (default ESRGAN strength is 0.75, default overlap between tiles is 0.25):
+
+    ```bash
+    invoke > a photo of a forest at sunset -s 100 -W 512 -H 512 -I outputs/forest.png -f 0.4 -embiggen 2.5
+    invoke > a photo of a forest at sunset -s 100 -W 512 -H 512 -I outputs/forest.png -f 0.4 -embiggen 2.5 0.75 0.25
+    ```
+
+    If your starting image was also 512x512 this should have taken 9 tiles.
+
+!!! example ""
+
+    If there weren't enough clouds in the sky of that forest you just made
+    (and that image is about 1280 pixels (512*2.5) wide A.K.A. three
+    512x512 tiles with 0.25 overlaps wide) we can replace that top row of
+    tiles:
+
+    ```bash
+    invoke> a photo of puffy clouds over a forest at sunset -s 100 -W 512 -H 512 -I outputs/000002.seed.png -f 0.5 -embiggen_tiles 1 2 3
+    ```
+
+## Fixing Previously-Generated Images
+
+It is easy to apply embiggen to any previously-generated file without having to
+look up the original prompt and provide an initial image. Just use the
+syntax `!fix path/to/file.png <embiggen>`. For example, you can rewrite the
+previous command to look like this:
+
+```bash
+invoke> !fix ./outputs/000002.seed.png -embiggen_tiles 1 2 3
+```
+
+A new file named `000002.seed.fixed.png` will be created in the output directory. Note that
+the `!fix` command does not replace the original file, unlike the behavior at generate time.
+You do not need to provide the prompt, and `!fix` automatically selects a good strength for
+embiggen-ing.
+
+!!! note
+
+    Because the same prompt is used on all the tiled images, and the model
+    doesn't have the context of anything outside the tile being run - it
+    can end up creating repeated pattern (also called 'motifs') across all
+    the tiles based on that prompt. The best way to combat this is
+    lowering the `--strength` (`-f`) to stay more true to the init image,
+    and increasing the number of steps so there is more compute-time to
+    create the detail.  Anecdotally `--strength` 0.35-0.45 works pretty
+    well on most things. It may also work great in some examples even with
+    the `--strength` set high for patterns, landscapes, or subjects that
+    are more abstract. Because this is (relatively) fast, you can also
+    preserve the best parts from each.
+
+Author: [Travco](https://github.com/travco)

docs/deprecated/INPAINTING.md

@@ -0,0 +1,310 @@
+---
+title: Inpainting
+---
+
+# :octicons-paintbrush-16: Inpainting
+
+## **Creating Transparent Regions for Inpainting**
+
+Inpainting is really cool. To do it, you start with an initial image and use a
+photoeditor to make one or more regions transparent (i.e. they have a "hole" in
+them). You then provide the path to this image at the dream> command line using
+the `-I` switch. Stable Diffusion will only paint within the transparent region.
+
+There's a catch. In the current implementation, you have to prepare the initial
+image correctly so that the underlying colors are preserved under the
+transparent area. Many imaging editing applications will by default erase the
+color information under the transparent pixels and replace them with white or
+black, which will lead to suboptimal inpainting. It often helps to apply
+incomplete transparency, such as any value between 1 and 99%
+
+You also must take care to export the PNG file in such a way that the color
+information is preserved. There is often an option in the export dialog that
+lets you specify this.
+
+If your photoeditor is erasing the underlying color information, `dream.py` will
+give you a big fat warning. If you can't find a way to coax your photoeditor to
+retain color values under transparent areas, then you can combine the `-I` and
+`-M` switches to provide both the original unedited image and the masked
+(partially transparent) image:
+
+```bash
+invoke> "man with cat on shoulder" -I./images/man.png -M./images/man-transparent.png
+```
+
+## **Masking using Text**
+
+You can also create a mask using a text prompt to select the part of the image
+you want to alter, using the [clipseg](https://github.com/timojl/clipseg)
+algorithm. This works on any image, not just ones generated by InvokeAI.
+
+The `--text_mask` (short form `-tm`) option takes two arguments. The first
+argument is a text description of the part of the image you wish to mask (paint
+over). If the text description contains a space, you must surround it with
+quotation marks. The optional second argument is the minimum threshold for the
+mask classifier's confidence score, described in more detail below.
+
+To see how this works in practice, here's an image of a still life painting that
+I got off the web.
+
+<figure markdown>
+![still life scaled](../assets/still-life-scaled.jpg)
+</figure>
+
+You can selectively mask out the orange and replace it with a baseball in this
+way:
+
+```bash
+invoke> a baseball -I /path/to/still_life.png -tm orange
+```
+
+<figure markdown>
+![](../assets/still-life-inpainted.png)
+</figure>
+
+The clipseg classifier produces a confidence score for each region it
+identifies. Generally regions that score above 0.5 are reliable, but if you are
+getting too much or too little masking you can adjust the threshold down (to get
+more mask), or up (to get less). In this example, by passing `-tm` a higher
+value, we are insisting on a tigher mask. However, if you make it too high, the
+orange may not be picked up at all!
+
+```bash
+invoke> a baseball -I /path/to/breakfast.png -tm orange 0.6
+```
+
+The `!mask` command may be useful for debugging problems with the text2mask
+feature. The syntax is `!mask /path/to/image.png -tm <text> <threshold>`
+
+It will generate three files:
+
+- The image with the selected area highlighted.
+  - it will be named XXXXX.<imagename>.<prompt>.selected.png
+- The image with the un-selected area highlighted.
+  - it will be named XXXXX.<imagename>.<prompt>.deselected.png
+- The image with the selected area converted into a black and white image
+  according to the threshold level
+  - it will be named XXXXX.<imagename>.<prompt>.masked.png
+
+The `.masked.png` file can then be directly passed to the `invoke>` prompt in
+the CLI via the `-M` argument. Do not attempt this with the `selected.png` or
+`deselected.png` files, as they contain some transparency throughout the image
+and will not produce the desired results.
+
+Here is an example of how `!mask` works:
+
+```bash
+invoke> !mask ./test-pictures/curly.png -tm hair 0.5
+>> generating masks from ./test-pictures/curly.png
+>> Initializing clipseg model for text to mask inference
+Outputs:
+[941.1] outputs/img-samples/000019.curly.hair.deselected.png: !mask ./test-pictures/curly.png -tm hair 0.5
+[941.2] outputs/img-samples/000019.curly.hair.selected.png: !mask ./test-pictures/curly.png -tm hair 0.5
+[941.3] outputs/img-samples/000019.curly.hair.masked.png: !mask ./test-pictures/curly.png -tm hair 0.5
+```
+
+<figure markdown>
+![curly](../assets/outpainting/curly.png)
+<figcaption>Original image "curly.png"</figcaption>
+</figure>
+
+<figure markdown>
+![curly hair selected](../assets/inpainting/000019.curly.hair.selected.png)
+<figcaption>000019.curly.hair.selected.png</figcaption>
+</figure>
+
+<figure markdown>
+![curly hair deselected](../assets/inpainting/000019.curly.hair.deselected.png)
+<figcaption>000019.curly.hair.deselected.png</figcaption>
+</figure>
+
+<figure markdown>
+![curly hair masked](../assets/inpainting/000019.curly.hair.masked.png)
+<figcaption>000019.curly.hair.masked.png</figcaption>
+</figure>
+
+It looks like we selected the hair pretty well at the 0.5 threshold (which is
+the default, so we didn't actually have to specify it), so let's have some fun:
+
+```bash
+invoke> medusa with cobras -I ./test-pictures/curly.png -M 000019.curly.hair.masked.png -C20
+>> loaded input image of size 512x512 from ./test-pictures/curly.png
+...
+Outputs:
+[946] outputs/img-samples/000024.801380492.png: "medusa with cobras" -s 50 -S 801380492 -W 512 -H 512 -C 20.0 -I ./test-pictures/curly.png -A k_lms -f 0.75
+```
+
+<figure markdown>
+![](../assets/inpainting/000024.801380492.png)
+</figure>
+
+You can also skip the `!mask` creation step and just select the masked
+
+region directly:
+
+```bash
+invoke> medusa with cobras -I ./test-pictures/curly.png -tm hair -C20
+```
+
+## Using the RunwayML inpainting model
+
+The
+[RunwayML Inpainting Model v1.5](https://huggingface.co/runwayml/stable-diffusion-inpainting)
+is a specialized version of
+[Stable Diffusion v1.5](https://huggingface.co/spaces/runwayml/stable-diffusion-v1-5)
+that contains extra channels specifically designed to enhance inpainting and
+outpainting. While it can do regular `txt2img` and `img2img`, it really shines
+when filling in missing regions. It has an almost uncanny ability to blend the
+new regions with existing ones in a semantically coherent way.
+
+To install the inpainting model, follow the
+[instructions](../installation/050_INSTALLING_MODELS.md) for installing a new model.
+You may use either the CLI (`invoke.py` script) or directly edit the
+`configs/models.yaml` configuration file to do this. The main thing to watch out
+for is that the the model `config` option must be set up to use
+`v1-inpainting-inference.yaml` rather than the `v1-inference.yaml` file that is
+used by Stable Diffusion 1.4 and 1.5.
+
+After installation, your `models.yaml` should contain an entry that looks like
+this one:
+
+```yml
+inpainting-1.5:
+  weights: models/ldm/stable-diffusion-v1/sd-v1-5-inpainting.ckpt
+  description: SD inpainting v1.5
+  config: configs/stable-diffusion/v1-inpainting-inference.yaml
+  vae: models/ldm/stable-diffusion-v1/vae-ft-mse-840000-ema-pruned.ckpt
+  width: 512
+  height: 512
+```
+
+As shown in the example, you may include a VAE fine-tuning weights file as well.
+This is strongly recommended.
+
+To use the custom inpainting model, launch `invoke.py` with the argument
+`--model inpainting-1.5` or alternatively from within the script use the
+`!switch inpainting-1.5` command to load and switch to the inpainting model.
+
+You can now do inpainting and outpainting exactly as described above, but there
+will (likely) be a noticeable improvement in coherence. Txt2img and Img2img will
+work as well.
+
+There are a few caveats to be aware of:
+
+1. The inpainting model is larger than the standard model, and will use nearly 4
+   GB of GPU VRAM. This makes it unlikely to run on a 4 GB graphics card.
+
+2. When operating in Img2img mode, the inpainting model is much less steerable
+   than the standard model. It is great for making small changes, such as
+   changing the pattern of a fabric, or slightly changing a subject's expression
+   or hair, but the model will resist making the dramatic alterations that the
+   standard model lets you do.
+
+3. While the `--hires` option works fine with the inpainting model, some special
+   features, such as `--embiggen` are disabled.
+
+4. Prompt weighting (`banana++ sushi`) and merging work well with the inpainting
+   model, but prompt swapping
+   (`a ("fluffy cat").swap("smiling dog") eating a hotdog`) will not have any
+   effect due to the way the model is set up. You may use text masking (with
+   `-tm thing-to-mask`) as an effective replacement.
+
+5. The model tends to oversharpen image if you use high step or CFG values. If
+   you need to do large steps, use the standard model.
+
+6. The `--strength` (`-f`) option has no effect on the inpainting model due to
+   its fundamental differences with the standard model. It will always take the
+   full number of steps you specify.
+
+## Troubleshooting
+
+Here are some troubleshooting tips for inpainting and outpainting.
+
+## Inpainting is not changing the masked region enough!
+
+One of the things to understand about how inpainting works is that it is
+equivalent to running img2img on just the masked (transparent) area. img2img
+builds on top of the existing image data, and therefore will attempt to preserve
+colors, shapes and textures to the best of its ability. Unfortunately this means
+that if you want to make a dramatic change in the inpainted region, for example
+replacing a red wall with a blue one, the algorithm will fight you.
+
+You have a couple of options. The first is to increase the values of the
+requested steps (`-sXXX`), strength (`-f0.XX`), and/or condition-free guidance
+(`-CXX.X`). If this is not working for you, a more extreme step is to provide
+the `--inpaint_replace 0.X` (`-r0.X`) option. This value ranges from 0.0 to 1.0.
+The higher it is the less attention the algorithm will pay to the data
+underneath the masked region. At high values this will enable you to replace
+colored regions entirely, but beware that the masked region mayl not blend in
+with the surrounding unmasked regions as well.
+
+---
+
+## Recipe for GIMP
+
+[GIMP](https://www.gimp.org/) is a popular Linux photoediting tool.
+
+1. Open image in GIMP.
+2. Layer->Transparency->Add Alpha Channel
+3. Use lasso tool to select region to mask
+4. Choose Select -> Float to create a floating selection
+5. Open the Layers toolbar (^L) and select "Floating Selection"
+6. Set opacity to a value between 0% and 99%
+7. Export as PNG
+8. In the export dialogue, Make sure the "Save colour values from transparent
+   pixels" checkbox is selected.
+
+---
+
+## Recipe for Adobe Photoshop
+
+1. Open image in Photoshop
+
+    <figure markdown>
+    ![step1](../assets/step1.png)
+    </figure>
+
+2. Use any of the selection tools (Marquee, Lasso, or Wand) to select the area
+   you desire to inpaint.
+
+    <figure markdown>
+    ![step2](../assets/step2.png)
+    </figure>
+
+3. Because we'll be applying a mask over the area we want to preserve, you
+   should now select the inverse by using the ++shift+ctrl+i++ shortcut, or
+   right clicking and using the "Select Inverse" option.
+
+4. You'll now create a mask by selecting the image layer, and Masking the
+   selection. Make sure that you don't delete any of the underlying image, or
+   your inpainting results will be dramatically impacted.
+
+    <figure markdown>
+    ![step4](../assets/step4.png)
+    </figure>
+
+5. Make sure to hide any background layers that are present. You should see the
+   mask applied to your image layer, and the image on your canvas should display
+   the checkered background.
+
+    <figure markdown>
+    ![step5](../assets/step5.png)
+    </figure>
+
+6. Save the image as a transparent PNG by using `File`-->`Save a Copy` from the
+   menu bar, or by using the keyboard shortcut ++alt+ctrl+s++
+
+    <figure markdown>
+    ![step6](../assets/step6.png)
+    </figure>
+
+7. After following the inpainting instructions above (either through the CLI or
+   the Web UI), marvel at your newfound ability to selectively invoke. Lookin'
+   good!
+
+    <figure markdown>
+   ![step7](../assets/step7.png)
+    </figure>
+
+8. In the export dialogue, Make sure the "Save colour values from transparent
+   pixels" checkbox is selected.

docs/deprecated/OUTPAINTING.md

@@ -0,0 +1,171 @@
+---
+title: Outpainting
+---
+
+# :octicons-paintbrush-16: Outpainting
+
+## Outpainting and outcropping
+
+Outpainting is a process by which the AI generates parts of the image that are
+outside its original frame. It can be used to fix up images in which the subject
+is off center, or when some detail (often the top of someone's head!) is cut
+off.
+
+InvokeAI supports two versions of outpainting, one called "outpaint" and the
+other "outcrop." They work slightly differently and each has its advantages and
+drawbacks.
+
+### Outpainting
+
+Outpainting is the same as inpainting, except that the painting occurs in the
+regions outside of the original image. To outpaint using the `invoke.py` command
+line script, prepare an image in which the borders to be extended are pure
+black. Add an alpha channel (if there isn't one already), and make the borders
+completely transparent and the interior completely opaque. If you wish to modify
+the interior as well, you may create transparent holes in the transparency
+layer, which `img2img` will paint into as usual.
+
+Pass the image as the argument to the `-I` switch as you would for regular
+inpainting:
+
+```bash
+invoke> a stream by a river -I /path/to/transparent_img.png
+```
+
+You'll likely be delighted by the results.
+
+### Tips
+
+1. Do not try to expand the image too much at once. Generally it is best to
+   expand the margins in 64-pixel increments. 128 pixels often works, but your
+   mileage may vary depending on the nature of the image you are trying to
+   outpaint into.
+
+2. There are a series of switches that can be used to adjust how the inpainting
+   algorithm operates. In particular, you can use these to minimize the seam
+   that sometimes appears between the original image and the extended part.
+   These switches are:
+
+| switch                     | default | description                                                            |
+| -------------------------- | ------- | ---------------------------------------------------------------------- |
+| `--seam_size SEAM_SIZE `   | `0`     | Size of the mask around the seam between original and outpainted image |
+| `--seam_blur SEAM_BLUR`    | `0`     | The amount to blur the seam inwards                                    |
+| `--seam_strength STRENGTH` | `0.7`   | The img2img strength to use when filling the seam                      |
+| `--seam_steps SEAM_STEPS`  | `10`    | The number of steps to use to fill the seam.                           |
+| `--tile_size TILE_SIZE`    | `32`    | The tile size to use for filling outpaint areas                        |
+
+### Outcrop
+
+The `outcrop` extension gives you a convenient `!fix` postprocessing command
+that allows you to extend a previously-generated image in 64 pixel increments in
+any direction. You can apply the module to any image previously-generated by
+InvokeAI. Note that it works with arbitrary PNG photographs, but not currently
+with JPG or other formats. Outcropping is particularly effective when combined
+with the
+[runwayML custom inpainting model](INPAINTING.md#using-the-runwayml-inpainting-model).
+
+Consider this image:
+
+<figure markdown>
+![curly_woman](../assets/outpainting/curly.png)
+</figure>
+
+Pretty nice, but it's annoying that the top of her head is cut off. She's also a
+bit off center. Let's fix that!
+
+```bash
+invoke> !fix images/curly.png --outcrop top 128 right 64 bottom 64
+```
+
+This is saying to apply the `outcrop` extension by extending the top of the
+image by 128 pixels, and the right and bottom of the image by 64 pixels. You can
+use any combination of top|left|right|bottom, and specify any number of pixels
+to extend. You can also abbreviate `--outcrop` to `-c`.
+
+The result looks like this:
+
+<figure markdown>
+![curly_woman_outcrop](../assets/outpainting/curly-outcrop-2.png)
+</figure>
+
+The new image is larger than the original (576x704) because 64 pixels were added
+to the top and right sides. You will need enough VRAM to process an image of
+this size.
+
+#### Outcropping non-InvokeAI images
+
+You can outcrop an arbitrary image that was not generated by InvokeAI,
+but your results will vary. The `inpainting-1.5` model is highly
+recommended, but if not feasible, then you may be able to improve the
+output by conditioning the outcropping with a text prompt that
+describes the scene using the `--new_prompt` argument:
+
+```bash
+invoke> !fix images/vacation.png --outcrop top 128 --new_prompt "family vacation"
+```
+
+You may also provide a different seed for outcropping to use by passing
+`-S<seed>`. A negative seed will generate a new random seed.
+
+A number of caveats:
+
+1. Although you can specify any pixel values, they will be rounded up to the
+   nearest multiple of 64. Smaller values are better. Larger extensions are more
+   likely to generate artefacts. However, if you wish you can run the !fix
+   command repeatedly to cautiously expand the image.
+
+2. The extension is stochastic, meaning that each time you run it you'll get a
+   slightly different result. You can run it repeatedly until you get an image
+   you like. Unfortunately `!fix` does not currently respect the `-n`
+   (`--iterations`) argument.
+
+3. Your results will be _much_ better if you use the `inpaint-1.5` model
+   released by runwayML and installed by default by `invokeai-configure`.
+   This model was trained specifically to harmoniously fill in image gaps. The
+   standard model will work as well, but you may notice color discontinuities at
+   the border.
+
+4. When using the `inpaint-1.5` model, you may notice subtle changes to the area
+   outside the masked region. This is because the model performs an
+   encoding/decoding on the image as a whole. This does not occur with the
+   standard model.
+
+## Outpaint
+
+The `outpaint` extension does the same thing, but with subtle differences.
+Starting with the same image, here is how we would add an additional 64 pixels
+to the top of the image:
+
+```bash
+invoke> !fix images/curly.png --out_direction top 64
+```
+
+(you can abbreviate `--out_direction` as `-D`.
+
+The result is shown here:
+
+<figure markdown>
+![curly_woman_outpaint](../assets/outpainting/curly-outpaint.png)
+</figure>
+
+Although the effect is similar, there are significant differences from
+outcropping:
+
+- You can only specify one direction to extend at a time.
+- The image is **not** resized. Instead, the image is shifted by the specified
+  number of pixels. If you look carefully, you'll see that less of the lady's
+  torso is visible in the image.
+- Because the image dimensions remain the same, there's no rounding to multiples
+  of 64.
+- Attempting to outpaint larger areas will frequently give rise to ugly ghosting
+  effects.
+- For best results, try increasing the step number.
+- If you don't specify a pixel value in `-D`, it will default to half of the
+  whole image, which is likely not what you want.
+
+!!! tip
+
+    Neither `outpaint` nor `outcrop` are perfect, but we continue to tune
+    and improve them. If one doesn't work, try the other. You may also
+    wish to experiment with other `img2img` arguments, such as `-C`, `-f`
+    and `-s`.

docs/faq.md

@@ -1,260 +0,0 @@
-# FAQ
-
-!!! info "How to Reinstall"
-
-    Many issues can be resolved by re-installing the application. You won't lose any data by re-installing. We suggest downloading the [latest release](https://github.com/invoke-ai/InvokeAI/releases/latest) and using it to re-install the application. Consult the [installer guide](./installation/installer.md) for more information.
-
-    When you run the installer, you'll have an option to select the version to install. If you aren't ready to upgrade, you choose the current version to fix a broken install.
-
-If the troubleshooting steps on this page don't get you up and running, please either [create an issue] or hop on [discord] for help.
-
-## How to Install
-
-You can download the latest installers [here](https://github.com/invoke-ai/InvokeAI/releases).
-
-Note that any releases marked as _pre-release_ are in a beta state. You may experience some issues, but we appreciate your help testing those! For stable/reliable installations, please install the [latest release].
-
-## Downloading models and using existing models
-
-The Model Manager tab in the UI provides a few ways to install models, including using your already-downloaded models. You'll see a popup directing you there on first startup. For more information, see the [model install docs].
-
-## Missing models after updating to v4
-
-If you find some models are missing after updating to v4, it's likely they weren't correctly registered before the update and didn't get picked up in the migration.
-
-You can use the `Scan Folder` tab in the Model Manager UI to fix this. The models will either be in the old, now-unused `autoimport` folder, or your `models` folder.
-
-- Find and copy your install's old `autoimport` folder path, install the main install folder.
-- Go to the Model Manager and click `Scan Folder`.
-- Paste the path and scan.
-- IMPORTANT: Uncheck `Inplace install`.
-- Click `Install All` to install all found models, or just install the models you want.
-
-Next, find and copy your install's `models` folder path (this could be your custom models folder path, or the `models` folder inside the main install folder).
-
-Follow the same steps to scan and import the missing models.
-
-## Slow generation
-
-- Check the [system requirements] to ensure that your system is capable of generating images.
-- Check the `ram` setting in `invokeai.yaml`. This setting tells Invoke how much of your system RAM can be used to cache models. Having this too high or too low can slow things down. That said, it's generally safest to not set this at all and instead let Invoke manage it.
-- Check the `vram` setting in `invokeai.yaml`. This setting tells Invoke how much of your GPU VRAM can be used to cache models. Counter-intuitively, if this setting is too high, Invoke will need to do a lot of shuffling of models as it juggles the VRAM cache and the currently-loaded model. The default value of 0.25 is generally works well for GPUs without 16GB or more VRAM. Even on a 24GB card, the default works well.
-- Check that your generations are happening on your GPU (if you have one). InvokeAI will log what is being used for generation upon startup. If your GPU isn't used, re-install to ensure the correct versions of torch get installed.
-- If you are on Windows, you may have exceeded your GPU's VRAM capacity and are using slower [shared GPU memory](#shared-gpu-memory-windows). There's a guide to opt out of this behaviour in the linked FAQ entry.
-
-## Shared GPU Memory (Windows)
-
-!!! tip "Nvidia GPUs with driver 536.40"
-
-    This only applies to current Nvidia cards with driver 536.40 or later, released in June 2023.
-
-When the GPU doesn't have enough VRAM for a task, Windows is able to allocate some of its CPU RAM to the GPU. This is much slower than VRAM, but it does allow the system to generate when it otherwise might no have enough VRAM.
-
-When shared GPU memory is used, generation slows down dramatically - but at least it doesn't crash.
-
-If you'd like to opt out of this behavior and instead get an error when you exceed your GPU's VRAM, follow [this guide from Nvidia](https://nvidia.custhelp.com/app/answers/detail/a_id/5490).
-
-Here's how to get the python path required in the linked guide:
-
-- Run `invoke.bat`.
-- Select option 2 for developer console.
-- At least one python path will be printed. Copy the path that includes your invoke installation directory (typically the first).
-
-## Installer cannot find python (Windows)
-
-Ensure that you checked **Add python.exe to PATH** when installing Python. This can be found at the bottom of the Python Installer window. If you already have Python installed, you can re-run the python installer, choose the Modify option and check the box.
-
-## Triton error on startup
-
-This can be safely ignored. InvokeAI doesn't use Triton, but if you are on Linux and wish to dismiss the error, you can install Triton.
-
-## Updated to 3.4.0 and xformers can’t load C++/CUDA
-
-An issue occurred with your PyTorch update. Follow these steps to fix :
-
-1. Launch your invoke.bat / invoke.sh and select the option to open the developer console
-2. Run:`pip install ".[xformers]" --upgrade --force-reinstall --extra-index-url https://download.pytorch.org/whl/cu121`
-   - If you run into an error with `typing_extensions`, re-open the developer console and run: `pip install -U typing-extensions`
-
-Note that v3.4.0 is an old, unsupported version. Please upgrade to the [latest release].
-
-## Install failed and says `pip` is out of date
-
-An out of date `pip` typically won't cause an installation to fail. The cause of the error can likely be found above the message that says `pip` is out of date.
-
-If you saw that warning but the install went well, don't worry about it (but you can update `pip` afterwards if you'd like).
-
-## Replicate image found online
-
-Most example images with prompts that you'll find on the internet have been generated using different software, so you can't expect to get identical results. In order to reproduce an image, you need to replicate the exact settings and processing steps, including (but not limited to) the model, the positive and negative prompts, the seed, the sampler, the exact image size, any upscaling steps, etc.
-
-## OSErrors on Windows while installing dependencies
-
-During a zip file installation or an update, installation stops with an error like this:
-
-![broken-dependency-screenshot](./assets/troubleshooting/broken-dependency.png){:width="800px"}
-
-To resolve this, re-install the application as described above.
-
-## HuggingFace install failed due to invalid access token
-
-Some HuggingFace models require you to authenticate using an [access token].
-
-Invoke doesn't manage this token for you, but it's easy to set it up:
-
-- Follow the instructions in the link above to create an access token. Copy it.
-- Run the launcher script.
-- Select option 2 (developer console).
-- Paste the following command:
-
-  ```sh
-  python -c "import huggingface_hub; huggingface_hub.login()"
-  ```
-
-- Paste your access token when prompted and press Enter. You won't see anything when you paste it.
-- Type `n` if prompted about git credentials.
-
-If you get an error, try the command again - maybe the token didn't paste correctly.
-
-Once your token is set, start Invoke and try downloading the model again. The installer will automatically use the access token.
-
-If the install still fails, you may not have access to the model.
-
-## Stable Diffusion XL generation fails after trying to load UNet
-
-InvokeAI is working in other respects, but when trying to generate
-images with Stable Diffusion XL you get a "Server Error". The text log
-in the launch window contains this log line above several more lines of
-error messages:
-
-`INFO --> Loading model:D:\LONG\PATH\TO\MODEL, type sdxl:main:unet`
-
-This failure mode occurs when there is a network glitch during
-downloading the very large SDXL model.
-
-To address this, first go to the Model Manager and delete the
-Stable-Diffusion-XL-base-1.X model. Then, click the HuggingFace tab,
-paste the Repo ID stabilityai/stable-diffusion-xl-base-1.0 and install
-the model.
-
-## Package dependency conflicts during installation or update
-
-If you have previously installed InvokeAI or another Stable Diffusion
-package, the installer may occasionally pick up outdated libraries and
-either the installer or `invoke` will fail with complaints about
-library conflicts.
-
-To resolve this, re-install the application as described above.
-
-## Invalid configuration file
-
-Everything seems to install ok, you get a `ValidationError` when starting up the app.
-
-This is caused by an invalid setting in the `invokeai.yaml` configuration file. The error message should tell you what is wrong.
-
-Check the [configuration docs] for more detail about the settings and how to specify them.
-
-## `ModuleNotFoundError: No module named 'controlnet_aux'`
-
-`controlnet_aux` is a dependency of Invoke and appears to have been packaged or distributed strangely. Sometimes, it doesn't install correctly. This is outside our control.
-
-If you encounter this error, the solution is to remove the package from the `pip` cache and re-run the Invoke installer so a fresh, working version of `controlnet_aux` can be downloaded and installed:
-
-- Run the Invoke launcher
-- Choose the developer console option
-- Run this command: `pip cache remove controlnet_aux`
-- Close the terminal window
-- Download and run the [installer][latest release], selecting your current install location
-
-## Out of Memory Issues
-
-The models are large, VRAM is expensive, and you may find yourself
-faced with Out of Memory errors when generating images. Here are some
-tips to reduce the problem:
-
-!!! info "Optimizing for GPU VRAM"
-
-    === "4GB VRAM GPU"
-
-        This should be adequate for 512x512 pixel images using Stable Diffusion 1.5
-        and derived models, provided that you do not use the NSFW checker. It won't be loaded unless you go into the UI settings and turn it on.
-
-        If you are on a CUDA-enabled GPU, we will automatically use xformers or torch-sdp to reduce VRAM requirements, though you can explicitly configure this. See the [configuration docs].
-
-    === "6GB VRAM GPU"
-
-        This is a border case. Using the SD 1.5 series you should be able to
-        generate images up to 640x640 with the NSFW checker enabled, and up to
-        1024x1024 with it disabled.
-
-        If you run into persistent memory issues there are a series of
-        environment variables that you can set before launching InvokeAI that
-        alter how the PyTorch machine learning library manages memory. See
-        <https://pytorch.org/docs/stable/notes/cuda.html#memory-management> for
-        a list of these tweaks.
-
-    === "12GB VRAM GPU"
-
-        This should be sufficient to generate larger images up to about 1280x1280.
-  
-## Checkpoint Models Load Slowly or Use Too Much RAM
-
-The difference between diffusers models (a folder containing multiple
-subfolders) and checkpoint models (a file ending with .safetensors or
-.ckpt) is that InvokeAI is able to load diffusers models into memory
-incrementally, while checkpoint models must be loaded all at
-once. With very large models, or systems with limited RAM, you may
-experience slowdowns and other memory-related issues when loading
-checkpoint models.
-
-To solve this, go to the Model Manager tab (the cube), select the
-checkpoint model that's giving you trouble, and press the "Convert"
-button in the upper right of your browser window. This will convert the
-checkpoint into a diffusers model, after which loading should be
-faster and less memory-intensive.
-
-## Memory Leak (Linux)
-
-If you notice a memory leak, it could be caused to memory fragmentation as models are loaded and/or moved from CPU to GPU.
-
-A workaround is to tune memory allocation with an environment variable:
-
-```bash
-# Force blocks >1MB to be allocated with `mmap` so that they are released to the system immediately when they are freed.
-MALLOC_MMAP_THRESHOLD_=1048576
-```
-
-!!! warning "Speed vs Memory Tradeoff"
-
-    Your generations may be slower overall when setting this environment variable.
-
-!!! info "Possibly dependent on `libc` implementation"
-
-    It's not known if this issue occurs with other `libc` implementations such as `musl`.
-
-    If you encounter this issue and your system uses a different implementation, please try this environment variable and let us know if it fixes the issue.
-
-<h3>Detailed Discussion</h3>
-
-Python (and PyTorch) relies on the memory allocator from the C Standard Library (`libc`). On linux, with the GNU C Standard Library implementation (`glibc`), our memory access patterns have been observed to cause severe memory fragmentation.
-
-This fragmentation results in large amounts of memory that has been freed but can't be released back to the OS. Loading models from disk and moving them between CPU/CUDA seem to be the operations that contribute most to the fragmentation.
-
-This memory fragmentation issue can result in OOM crashes during frequent model switching, even if `ram` (the max RAM cache size) is set to a reasonable value (e.g. a OOM crash with `ram=16` on a system with 32GB of RAM).
-
-This problem may also exist on other OSes, and other `libc` implementations. But, at the time of writing, it has only been investigated on linux with `glibc`.
-
-To better understand how the `glibc` memory allocator works, see these references:
-
-- Basics: <https://www.gnu.org/software/libc/manual/html_node/The-GNU-Allocator.html>
-- Details: <https://sourceware.org/glibc/wiki/MallocInternals>
-
-Note the differences between memory allocated as chunks in an arena vs. memory allocated with `mmap`. Under `glibc`'s default configuration, most model tensors get allocated as chunks in an arena making them vulnerable to the problem of fragmentation.
-
-[model install docs]: ./installation/models.md
-[system requirements]: ./installation/requirements.md
-[latest release]: https://github.com/invoke-ai/InvokeAI/releases/latest
-[create an issue]: https://github.com/invoke-ai/InvokeAI/issues
-[discord]: https://discord.gg/ZmtBAhwWhy
-[configuration docs]: ./configuration.md
-[access token]: https://huggingface.co/docs/hub/security-tokens#how-to-manage-user-access-tokens

docs/features/CONCEPTS.md

@@ -0,0 +1,88 @@
+---
+title: Textual Inversion Embeddings and LoRAs
+---
+
+# :material-library-shelves: Textual Inversions and 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. 
+
+
+## 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`.
+
+[Hugging Face](https://huggingface.co/sd-concepts-library) has
+amassed a large library 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 `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.
+

docs/features/CONFIGURATION.md

@@ -0,0 +1,287 @@
+---
+title: Configuration
+---
+
+# :material-tune-variant: InvokeAI Configuration
+
+## Intro
+
+InvokeAI has numerous runtime settings which can be used to adjust
+many aspects of its operations, including the location of files and
+directories, memory usage, and performance. These settings can be
+viewed and customized in several ways:
+
+1. By editing settings in the `invokeai.yaml` file.
+2. By setting environment variables.
+3. On the command-line, when InvokeAI is launched.
+
+In addition, the most commonly changed settings are accessible
+graphically via the `invokeai-configure` script.
+
+### How the Configuration System Works
+
+When InvokeAI is launched, the very first thing it needs to do is to
+find its "root" directory, which contains its configuration files,
+installed models, its database of images, and the folder(s) of
+generated images themselves. In this document, the root directory will
+be referred to as ROOT.
+
+#### Finding the Root Directory
+
+To find its root directory, InvokeAI uses the following recipe:
+
+1. It first looks for the argument `--root <path>` on the command line
+it was launched from, and uses the indicated path if present.
+
+2. Next it looks for the environment variable INVOKEAI_ROOT, and uses
+the directory path found there if present.
+
+3. If neither of these are present, then InvokeAI looks for the
+folder containing the `.venv` Python virtual environment directory for
+the currently active environment. This directory is checked for files
+expected inside the InvokeAI root before it is used.
+
+4. Finally, InvokeAI looks for a directory in the current user's home
+directory named `invokeai`.
+
+#### Reading the InvokeAI Configuration File
+
+Once the root directory has been located, InvokeAI looks for a file
+named `ROOT/invokeai.yaml`, and if present reads configuration values
+from it. The top of this file looks like this:
+
+```
+InvokeAI:
+  Web Server:
+    host: localhost
+    port: 9090
+    allow_origins: []
+    allow_credentials: true
+    allow_methods:
+    - '*'
+    allow_headers:
+    - '*'
+  Features:
+    esrgan: true
+    internet_available: true
+    log_tokenization: false
+    patchmatch: true
+    restore: true
+...
+```
+
+This lines in this file are used to establish default values for
+Invoke's settings. In the above fragment, the Web Server's listening
+port is set to 9090 by the `port` setting.
+
+You can edit this file with a text editor such as "Notepad" (do not
+use Word or any other word processor). When editing, be careful to
+maintain the indentation, and do not add extraneous text, as syntax
+errors will prevent InvokeAI from launching. A basic guide to the
+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 [7] in the launcher, "Re-run the
+configure script".
+
+#### Reading Environment Variables
+
+Next InvokeAI looks for defined environment variables in the format
+`INVOKEAI_<setting_name>`, for example `INVOKEAI_port`. Environment
+variable values take precedence over configuration file variables. On
+a Macintosh system, for example, you could change the port that the
+web server listens on by setting the environment variable this way:
+
+```
+export INVOKEAI_port=8000
+invokeai-web
+```
+
+Please check out these
+[Macintosh](https://phoenixnap.com/kb/set-environment-variable-mac)
+and
+[Windows](https://phoenixnap.com/kb/windows-set-environment-variable)
+guides for setting temporary and permanent environment variables.
+
+#### Reading the Command Line
+
+Lastly, InvokeAI takes settings from the command line, which override
+everything else. The command-line settings have the same name as the
+corresponding configuration file settings, preceded by a `--`, for
+example `--port 8000`.
+
+If you are using the launcher (`invoke.sh` or `invoke.bat`) to launch
+InvokeAI, then just pass the command-line arguments to the launcher:
+
+```
+invoke.bat --port 8000 --host 0.0.0.0
+```
+
+The arguments will be applied when you select the web server option
+(and the other options as well).
+
+If, on the other hand, you prefer to launch InvokeAI directly from the
+command line, you would first activate the virtual environment (known
+as the "developer's console" in the launcher), and run `invokeai-web`:
+
+```
+> C:\Users\Fred\invokeai\.venv\scripts\activate
+(.venv) > invokeai-web --port 8000 --host 0.0.0.0
+```
+
+You can get a listing and brief instructions for each of the
+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]
+```
+
+## The Configuration Settings
+
+The configuration settings are divided into several distinct
+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  |
+
+The documentation for InvokeAI's API can be accessed by browsing to the following URL: [http://localhost:9090/docs].
+
+### Features
+
+These configuration settings allow you to enable and disable various InvokeAI features:
+
+| Setting  | Default Value  |  Description |
+|----------|----------------|--------------|
+| `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 |
+| `patchmatch` | `true`     | Activate the "patchmatch" algorithm for improved inpainting |
+
+### Generation
+
+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 |
+
+
+### Paths
+
+These options set the paths of various directories and files used by
+InvokeAI. Relative paths are interpreted relative to INVOKEAI_ROOT, so
+if INVOKEAI_ROOT is `/home/fred/invokeai` and the path is
+`autoimport/main`, then the corresponding directory will be located at
+`/home/fred/invokeai/autoimport/main`.
+
+| Setting  | Default Value  |  Description |
+|----------|----------------|--------------|
+| `autoimport_dir` | `autoimport/main`     | At startup time, read and import any main model files found in this directory |
+| `lora_dir` | `autoimport/lora`     | At startup time, read and import any LoRA/LyCORIS models found in this directory |
+| `embedding_dir` | `autoimport/embedding`  | At startup time, read and import any textual inversion (embedding) models found in this directory |
+| `controlnet_dir` | `autoimport/controlnet`  | At startup time, read and import any ControlNet models found in this directory |
+| `conf_path` | `configs/models.yaml`  | Location of the `models.yaml` model configuration file |
+| `models_dir` | `models`  | Location of the directory containing models installed by InvokeAI's model manager |
+| `legacy_conf_dir` | `configs/stable-diffusion`  | Location of the directory containing the .yaml configuration files for legacy checkpoint models |
+| `db_dir` | `databases`  | Location of the directory containing InvokeAI's image, schema and session database |
+| `outdir` | `outputs`  | Location of the directory in which the gallery of generated and uploaded images will be stored |
+| `use_memory_db` | `false`  | Keep database information in memory rather than on disk; this will not preserve image gallery information across restarts |
+
+Note that the autoimport directories will be searched recursively,
+allowing you to organize the models into folders and subfolders in any
+way you wish. In addition, while we have split up autoimport
+directories by the type of model they contain, this isn't
+necessary. You can combine different model types in the same folder
+and InvokeAI will figure out what they are. So you can easily use just
+one autoimport directory by commenting out the unneeded paths:
+
+```
+Paths:
+  autoimport_dir: autoimport
+#  lora_dir: null
+#  embedding_dir: null
+#  controlnet_dir: null
+```
+
+### Logging
+
+These settings control the information, warning, and debugging
+messages printed to the console log while InvokeAI is running:
+
+| Setting  | Default Value  |  Description |
+|----------|----------------|--------------|
+| `log_handlers` | `console` | This controls where log messages are sent, and can be a list of one or more destinations. Values include `console`, `file`, `syslog` and `http`. These are described in more detail below |
+| `log_format` | `color` | This controls the formatting of the log messages. Values are `plain`, `color`, `legacy` and `syslog` |
+| `log_level`  | `debug` | This filters messages according to the level of severity and can be one of `debug`, `info`, `warning`, `error` and `critical`. For example, setting to `warning` will display all messages at the warning level or higher, but won't display "debug" or "info" messages |
+
+Several different log handler destinations are available, and multiple destinations are supported by providing a list:
+
+```
+  log_handlers:
+     - console
+     - syslog=localhost
+     - file=/var/log/invokeai.log
+```
+
+* `console` is the default. It prints log messages to the command-line window from which InvokeAI was launched.
+
+* `syslog` is only available on Linux and Macintosh systems. It uses
+  the operating system's "syslog" facility to write log file entries
+  locally or to a remote logging machine. `syslog` offers a variety
+  of configuration options:
+
+```
+  syslog=/dev/log`      - log to the /dev/log device
+  syslog=localhost`     - log to the network logger running on the local machine
+  syslog=localhost:512` - same as above, but using a non-standard port
+  syslog=fredserver,facility=LOG_USER,socktype=SOCK_DRAM`
+                        - Log to LAN-connected server "fredserver" using the facility LOG_USER and datagram packets.
+```
+
+* `http` can be used to log to a remote web server. The server must be
+  properly configured to receive and act on log messages. The option
+  accepts the URL to the web server, and a `method` argument
+  indicating whether the message should be submitted using the GET or
+  POST method.
+
+```
+ http=http://my.server/path/to/logger,method=POST
+```
+
+The `log_format` option provides several alternative formats:
+
+* `color`    - default format providing time, date and a message, using text colors to distinguish different log severities
+* `plain`    - same as above, but monochrome text only
+* `syslog`   - the log level and error message only, allowing the syslog system to attach the time and date
+* `legacy`   - a format similar to the one used by the legacy 2.3 InvokeAI releases.

docs/features/CONTROLNET.md

@@ -0,0 +1,134 @@
+---
+title: ControlNet
+---
+
+# :material-loupe: ControlNet
+
+## 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.
+
+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.
+
+
+### How it works
+
+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.
+
+
+### Models
+
+InvokeAI provides access to a series of ControlNet models that provide
+different effects or styles in your generated images.  Currently
+InvokeAI only supports "diffuser" style 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.
+
+***InvokeAI does not currently support checkpoint-format
+ControlNets. These come in the form of a single file with the
+extension `.safetensors`.***
+
+Diffuser-style ControlNet models are available at HuggingFace
+(http://huggingface.co) and accessed via their repo IDs (identifiers
+in the format "author/modelname"). The easiest way to install them is
+to use the InvokeAI model installer application. Use the
+`invoke.sh`/`invoke.bat` launcher to select item [5] 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:
+
+![Model Installer -
+Controlnetl](../assets/installing-models/model-installer-controlnet.png){:width="640px"}
+
+Command-line users can launch the model installer using the command
+`invokeai-model-install`.
+
+_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.
+
+The models currently supported include:
+
+**Canny**:
+
+When the Canny model is used in ControlNet, Invoke will attempt to generate images that match the edges detected. 
+
+Canny edge detection works by detecting the edges in an image by looking for abrupt changes in intensity. It is known for its ability to detect edges accurately while reducing noise and false edges, and the preprocessor can identify more information by decreasing the thresholds.
+
+**M-LSD**: 
+
+M-LSD is another edge detection algorithm used in ControlNet. It stands for Multi-Scale Line Segment Detector. 
+
+It detects straight line segments in an image by analyzing the local structure of the image at multiple scales.  It can be useful for architectural imagery, or anything where straight-line structural information is needed for the resulting output. 
+
+**Lineart**: 
+
+The Lineart model in ControlNet generates line drawings from an input image. The resulting pre-processed image is a simplified version of the original, with only the outlines of objects visible.The Lineart model in ControlNet is known for its ability to accurately capture the contours of the objects in an input sketch. 
+
+**Lineart Anime**: 
+
+A variant of the Lineart model that generates line drawings with a distinct style inspired by anime and manga art styles.
+
+**Depth**: 
+A model that generates depth maps of images, allowing you to create more realistic 3D models or to simulate depth effects in post-processing.
+
+**Normal Map (BAE):** 
+A model that generates normal maps from input images, allowing for more realistic lighting effects in 3D rendering.
+		
+**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)
+
+
+**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. 
+
+**Mediapipe Face**:
+
+The MediaPipe Face identification processor is able to clearly identify facial features in order to capture vivid expressions of human faces.
+
+**Tile**:
+
+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:
+
+- It can reinterpret specific details within an image and create fresh, new elements.
+- It has the ability to disregard global instructions if there's a discrepancy between them and the local context or specific parts of the image. In such cases, it uses the local context to guide the process.
+
+The Tile Model can be a powerful tool in your arsenal for enhancing image quality and details. If there are undesirable elements in your images, such as blurriness caused by resizing, this model can effectively eliminate these issues, resulting in cleaner, crisper images. Moreover, it can generate and add refined details to your images, improving their overall quality and appeal. 
+
+**Pix2Pix (experimental)**
+
+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.
+
+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
+
+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.
+
+
+Each ControlNet has two settings that are applied to the ControlNet.
+
+Weight - Strength of the Controlnet 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 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.

docs/features/IMG2IMG.md

@@ -0,0 +1,151 @@
+---
+title: Image-to-Image
+---
+
+# :material-image-multiple: Image-to-Image
+
+InvokeAI provides an "img2img" feature that lets you seed your
+creations with an initial drawing or photo. This is a really cool
+feature that tells stable diffusion to build the prompt on top of the
+image you provide, preserving the original's basic shape and layout.
+
+For a walkthrough of using Image-to-Image in the Web UI, see [InvokeAI
+Web Server](./WEB.md#image-to-image).
+
+The main difference between `img2img` and `prompt2img` is the starting point.
+While `prompt2img` always starts with pure gaussian noise and progressively
+refines it over the requested number of steps, `img2img` skips some of these
+earlier steps (how many it skips is indirectly controlled by the `--strength`
+parameter), and uses instead your initial image mixed with gaussian noise as the
+starting image.
+
+**Let's start** by thinking about vanilla `prompt2img`, just generating an image
+from a prompt. If the step count is 10, then the "latent space" (Stable
+Diffusion's internal representation of the image) for the prompt "fire" with
+seed `1592514025` develops something like this:
+
+!!! example ""
+
+    <figure markdown>
+    ![latent steps](../assets/img2img/000019.steps.png){ width=720 }
+    </figure>
+
+Put simply: starting from a frame of fuzz/static, SD finds details in each frame
+that it thinks look like "fire" and brings them a little bit more into focus,
+gradually scrubbing out the fuzz until a clear image remains.
+
+**When you use `img2img`** some of the earlier steps are cut, and instead an
+initial image of your choice is used. But because of how the maths behind Stable
+Diffusion works, this image needs to be mixed with just the right amount of
+noise (fuzz/static) for where it is being inserted. This is where the strength
+parameter comes in. Depending on the set strength, your image will be inserted
+into the sequence at the appropriate point, with just the right amount of noise.
+
+### A concrete example
+
+!!! example "I want SD to draw a fire based on this hand-drawn image"
+
+    ![drawing of a fireplace](../assets/img2img/fire-drawing.png){ align=left }
+
+    Let's only do 10 steps, to make it easier to see what's happening. If strength
+    is `0.7`, this is what the internal steps the algorithm has to take will look
+    like:
+
+    <figure markdown>
+    ![gravity32](../assets/img2img/000032.steps.gravity.png)
+    </figure>
+
+    With strength `0.4`, the steps look more like this:
+
+    <figure markdown>
+    ![gravity30](../assets/img2img/000030.steps.gravity.png)
+    </figure>
+
+Notice how much more fuzzy the starting image is for strength `0.7` compared to
+`0.4`, and notice also how much longer the sequence is with `0.7`:
+
+|                             | strength = 0.7                                                | strength = 0.4                                                |
+| --------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
+| initial image that SD sees  | ![step-0](../assets/img2img/000032.step-0.png)                | ![step-0](../assets/img2img/000030.step-0.png)                |
+| steps argument to `invoke>` | `-S10`                                                        | `-S10`                                                        |
+| steps actually taken        | `7`                                                           | `4`                                                           |
+| latent space at each step   | ![gravity32](../assets/img2img/000032.steps.gravity.png)      | ![gravity30](../assets/img2img/000030.steps.gravity.png)      |
+| output                      | ![000032.1592514025](../assets/img2img/000032.1592514025.png) | ![000030.1592514025](../assets/img2img/000030.1592514025.png) |
+
+Both of the outputs look kind of like what I was thinking of. With the strength
+higher, my input becomes more vague, _and_ Stable Diffusion has more steps to
+refine its output. But it's not really making what I want, which is a picture of
+cheery open fire. With the strength lower, my input is more clear, _but_ Stable
+Diffusion has less chance to refine itself, so the result ends up inheriting all
+the problems of my bad drawing.
+
+If you want to try this out yourself, all of these are using a seed of
+`1592514025` with a width/height of `384`, step count `10`, the
+`k_lms` sampler, and the single-word prompt `"fire"`.
+
+### Compensating for the reduced step count
+
+After putting this guide together I was curious to see how the difference would
+be if I increased the step count to compensate, so that SD could have the same
+amount of steps to develop the image regardless of the strength. So I ran the
+generation again using the same seed, but this time adapting the step count to
+give each generation 20 steps.
+
+Here's strength `0.4` (note step count `50`, which is `20 ÷ 0.4` to make sure SD
+does `20` steps from my image):
+
+<figure markdown>
+![000035.1592514025](../assets/img2img/000035.1592514025.png)
+</figure>
+
+and here is strength `0.7` (note step count `30`, which is roughly `20 ÷ 0.7` to
+make sure SD does `20` steps from my image):
+
+<figure markdown>
+![000046.1592514025](../assets/img2img/000046.1592514025.png)
+</figure>
+
+In both cases the image is nice and clean and "finished", but because at
+strength `0.7` Stable Diffusion has been give so much more freedom to improve on
+my badly-drawn flames, they've come out looking much better. You can really see
+the difference when looking at the latent steps. There's more noise on the first
+image with strength `0.7`:
+
+<figure markdown>
+![gravity46](../assets/img2img/000046.steps.gravity.png)
+</figure>
+
+than there is for strength `0.4`:
+
+<figure markdown>
+![gravity35](../assets/img2img/000035.steps.gravity.png)
+</figure>
+
+and that extra noise gives the algorithm more choices when it is evaluating how
+to denoise any particular pixel in the image.
+
+Unfortunately, it seems that `img2img` is very sensitive to the step count.
+Here's strength `0.7` with a step count of `29` (SD did 19 steps from my image):
+
+<figure markdown>
+![gravity45](../assets/img2img/000045.1592514025.png)
+</figure>
+
+By comparing the latents we can sort of see that something got interpreted
+differently enough on the third or fourth step to lead to a rather different
+interpretation of the flames.
+
+<figure markdown>
+![gravity46](../assets/img2img/000046.steps.gravity.png)
+</figure>
+
+<figure markdown>
+![gravity45](../assets/img2img/000045.steps.gravity.png)
+</figure>
+
+This is the result of a difference in the de-noising "schedule" - basically the
+noise has to be cleaned by a certain degree each step or the model won't
+"converge" on the image properly (see
+[stable diffusion blog](https://huggingface.co/blog/stable_diffusion) for more
+about that). A different step count means a different schedule, which means
+things get interpreted slightly differently at every step.

docs/features/LOGGING.md

@@ -0,0 +1,171 @@
+---
+title: Controlling Logging
+---
+
+# :material-image-off: Controlling Logging
+
+## Controlling How InvokeAI Logs Status Messages
+
+InvokeAI logs status messages using a configurable logging system. You
+can log to the terminal window, to a designated file on the local
+machine, to the syslog facility on a Linux or Mac, or to a properly
+configured web server. You can configure several logs at the same
+time, and control the level of message logged and the logging format
+(to a limited extent).
+
+Three command-line options control logging:
+
+### `--log_handlers <handler1> <handler2> ...`
+
+This option activates one or more log handlers. Options are "console",
+"file", "syslog" and "http". To specify more than one, separate them
+by spaces:
+
+```bash
+invokeai-web --log_handlers console syslog=/dev/log file=C:\Users\fred\invokeai.log
+```
+
+The format of these options is described below.
+
+### `--log_format {plain|color|legacy|syslog}`
+
+This controls the format of log messages written to the console. Only
+the "console" log handler is currently affected by this setting.
+
+* "plain" provides formatted messages like this:
+
+```bash
+
+[2023-05-24 23:18:2[2023-05-24 23:18:50,352]::[InvokeAI]::DEBUG --> this is a debug message
+[2023-05-24 23:18:50,352]::[InvokeAI]::INFO --> this is an informational messages
+[2023-05-24 23:18:50,352]::[InvokeAI]::WARNING --> this is a warning
+[2023-05-24 23:18:50,352]::[InvokeAI]::ERROR --> this is an error
+[2023-05-24 23:18:50,352]::[InvokeAI]::CRITICAL --> this is a critical error
+```
+
+* "color" produces similar output, but the text will be color coded to
+indicate the severity of the message.
+
+* "legacy" produces output similar to InvokeAI versions 2.3 and earlier:
+
+```bash
+### this is a critical error
+*** this is an error
+** this is a warning
+>> this is an informational messages
+   | this is a debug message
+```
+
+* "syslog" produces messages suitable for syslog entries:
+
+```bash
+InvokeAI [2691178] <CRITICAL> this is a critical error
+InvokeAI [2691178] <ERROR> this is an error
+InvokeAI [2691178] <WARNING> this is a warning
+InvokeAI [2691178] <INFO> this is an informational messages
+InvokeAI [2691178] <DEBUG> this is a debug message
+```
+
+(note that the date, time and hostname will be added by the syslog
+system)
+
+### `--log_level {debug|info|warning|error|critical}`
+
+Providing this command-line option will cause only messages at the
+specified level or above to be emitted.
+
+## Console logging
+
+When "console" is provided to `--log_handlers`, messages will be
+written to the command line window in which InvokeAI was launched. By
+default, the color formatter will be used unless overridden by
+`--log_format`.
+
+## File logging
+
+When "file" is provided to `--log_handlers`, entries will be written
+to the file indicated in the path argument. By default, the "plain"
+format will be used:
+
+```bash
+invokeai-web --log_handlers file=/var/log/invokeai.log
+```
+
+## Syslog logging
+
+When "syslog" is requested, entries will be sent to the syslog
+system. There are a variety of ways to control where the log message
+is sent:
+
+* Send to the local machine using the `/dev/log` socket:
+
+```
+invokeai-web --log_handlers syslog=/dev/log
+```
+
+* Send to the local machine using a UDP message:
+
+```
+invokeai-web --log_handlers syslog=localhost
+```
+
+* Send to the local machine using a UDP message on a nonstandard
+  port:
+
+```
+invokeai-web --log_handlers syslog=localhost:512
+```
+
+* Send to a remote machine named "loghost" on the local LAN using
+  facility LOG_USER and UDP packets:
+
+```
+invokeai-web --log_handlers syslog=loghost,facility=LOG_USER,socktype=SOCK_DGRAM
+```
+
+This can be abbreviated `syslog=loghost`, as LOG_USER and SOCK_DGRAM
+are defaults.
+
+* Send to a remote machine named "loghost" using the facility LOCAL0
+  and using a TCP socket:
+
+```
+invokeai-web --log_handlers syslog=loghost,facility=LOG_LOCAL0,socktype=SOCK_STREAM
+```
+
+If no arguments are specified (just a bare "syslog"), then the logging
+system will look for a UNIX socket named `/dev/log`, and if not found
+try to send a UDP message to `localhost`. The Macintosh OS used to
+support logging to a socket named `/var/run/syslog`, but this feature
+has since been disabled.
+
+## Web logging
+
+If you have access to a web server that is configured to log messages
+when a particular URL is requested, you can log using the "http"
+method:
+
+```
+invokeai-web --log_handlers http=http://my.server/path/to/logger,method=POST
+```
+
+The optional [,method=] part can be used to specify whether the URL
+accepts GET (default) or POST messages.
+
+Currently password authentication and SSL are not supported.
+
+## Using the configuration file
+
+You can set and forget logging options by adding a "Logging" section
+to `invokeai.yaml`:
+
+```
+InvokeAI:
+  [... other settings...]
+  Logging:
+    log_handlers:
+       - console
+       - syslog=/dev/log
+    log_level: info
+    log_format: color
+```

docs/features/MODEL_MERGING.md

@@ -0,0 +1,76 @@
+---
+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.
+
+## 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
+  `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.
+
+* 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.
+
+
+
+You may run the merge script by starting the invoke launcher
+(`invoke.sh` or `invoke.bat`) and choosing the option (4) 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.
+
+Alternatively you may activate InvokeAI's virtual environment from the
+command line, and call the script via `merge_models --gui` to open up
+a version that has a nice graphical front end. To get the commandline-
+only version, omit `--gui`.
+
+The user interface for the text-based interactive script is
+straightforward. It shows you a series of setting fields. Use control-N (^N)
+to move to the next field, and control-P (^P) to move to the previous
+one. You can also use TAB and shift-TAB to move forward and
+backward. Once you are in a multiple choice field, use the up and down
+cursor arrows to move to your desired selection, and press <SPACE> or
+<ENTER> to select it. Change text fields by typing in them, and adjust
+scrollbars using the left and right arrow keys.
+
+Once you are happy with your settings, press the OK button. Note that
+there may be two pages of settings, depending on the height of your
+screen, and the OK button may be on the second page. Advance past the
+last field of the first page to get to the second page, and reverse
+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.
+
+

docs/features/OTHER.md

@@ -0,0 +1,51 @@
+---
+title: Others
+---
+
+# :fontawesome-regular-share-from-square: Others
+
+## **Google Colab**
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg){ align="right" }](https://colab.research.google.com/github/lstein/stable-diffusion/blob/main/notebooks/Stable_Diffusion_AI_Notebook.ipynb)
+
+Open and follow instructions to use an isolated environment running Dream.
+
+Output Example:
+
+![Colab Notebook](../assets/colab_notebook.png)
+
+---
+
+## **Invisible Watermark**
+
+In keeping with the principles for responsible AI generation, and to
+help AI researchers avoid synthetic images contaminating their
+training sets, InvokeAI adds an invisible watermark to each of the
+final images it generates. The watermark consists of the text
+"InvokeAI" and can be viewed using the
+[invisible-watermarks](https://github.com/ShieldMnt/invisible-watermark)
+tool.
+
+Watermarking is controlled using the `invisible-watermark` setting in
+`invokeai.yaml`. To turn it off, add the following line under the `Features`
+category.
+
+```
+invisible_watermark: false
+```
+
+
+## **Weighted Prompts**
+
+You may weight different sections of the prompt to tell the sampler to attach different levels of
+priority to them, by adding `:<percent>` to the end of the section you wish to up- or downweight. For
+example consider this prompt:
+
+```bash
+(tabby cat):0.25 (white duck):0.75 hybrid
+```
+
+This will tell the sampler to invest 25% of its effort on the tabby cat aspect of the image and 75%
+on the white duck aspect (surprisingly, this example actually works). The prompt weights can use any
+combination of integers and floating point numbers, and they do not need to add up to 1.
+

docs/features/POSTPROCESS.md

@@ -0,0 +1,41 @@
+---
+title: Postprocessing
+---
+
+# :material-image-edit: Postprocessing
+
+This sections details the ability to improve faces and upscale images.
+
+## Face Fixing
+
+As of InvokeAI 3.0, the easiest way to improve faces created during image generation is through the Inpainting functionality of the Unified Canvas. Simply add the image containing the faces that you would like to improve to the canvas, mask the face to be improved and run the invocation. For best results, make sure to use an inpainting specific model; these are usually identified by the "-inpainting" term in the model name. 
+
+## Upscaling
+
+Open the upscaling dialog by clicking on the "expand" icon located
+above the image display area in the Web UI:
+
+<figure markdown>
+![upscale1](../assets/features/upscale-dialog.png)
+</figure>
+
+The default upscaling option is Real-ESRGAN x2 Plus, which will scale your image by a factor of two. This means upscaling a 512x512 image will result in a new 1024x1024 image.
+
+Other options are the x4 upscalers, which will scale your image by a factor of 4. 
+
+
+!!! note
+
+    Real-ESRGAN is memory intensive. In order to avoid crashes and memory overloads
+    during the Stable Diffusion process, these effects are applied after Stable Diffusion has completed
+    its work.
+
+    In single image generations, you will see the output right away but when you are using multiple
+    iterations, the images will first be generated and then upscaled after that
+    process is complete. While the image generation is taking place, you will still be able to preview
+    the base images.
+
+## How to disable
+
+If, for some reason, you do not wish to load the ESRGAN libraries,
+you can disable them on the invoke.py command line with the `--no_esrgan` options.

docs/features/PROMPTS.md

@@ -0,0 +1,308 @@
+---
+title: Prompting-Features
+---
+
+# :octicons-command-palette-24: Prompting-Features
+
+## **Prompt Syntax Features**
+
+The InvokeAI prompting language has the following features:
+
+### Attention weighting
+
+Append a word or phrase with `-` or `+`, or a weight between `0` and `2`
+(`1`=default), to decrease or increase "attention" (= a mix of per-token CFG
+weighting multiplier and, for `-`, a weighted blend with the prompt without the
+term).
+
+The following syntax is recognised:
+
+- single words without parentheses: `a tall thin man picking apricots+`
+- single or multiple words with parentheses:
+  `a tall thin man picking (apricots)+` `a tall thin man picking (apricots)-`
+  `a tall thin man (picking apricots)+` `a tall thin man (picking apricots)-`
+- more effect with more symbols `a tall thin man (picking apricots)++`
+- nesting `a tall thin man (picking apricots+)++` (`apricots` effectively gets
+  `+++`)
+- all of the above with explicit numbers `a tall thin man picking (apricots)1.1`
+  `a tall thin man (picking (apricots)1.3)1.1`. (`+` is equivalent to 1.1, `++`
+  is pow(1.1,2), `+++` is pow(1.1,3), etc; `-` means 0.9, `--` means pow(0.9,2),
+  etc.)
+
+You can use this to increase or decrease the amount of something. Starting from
+this prompt of `a man picking apricots from a tree`, let's see what happens if
+we increase and decrease how much attention we want Stable Diffusion to pay to
+the word `apricots`:
+
+<figure markdown>
+
+![an AI generated image of a man picking apricots from a tree](../assets/prompt_syntax/apricots-0.png)
+
+</figure>
+
+Using `-` to reduce apricot-ness:
+
+| `a man picking apricots- from a tree`                                                                                          | `a man picking apricots-- from a tree`                                                                                                        | `a man picking apricots--- from a tree`                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| ![an AI generated image of a man picking apricots from a tree, with smaller apricots](../assets/prompt_syntax/apricots--1.png) | ![an AI generated image of a man picking apricots from a tree, with even smaller and fewer apricots](../assets/prompt_syntax/apricots--2.png) | ![an AI generated image of a man picking apricots from a tree, with very few very small apricots](../assets/prompt_syntax/apricots--3.png) |
+
+Using `+` to increase apricot-ness:
+
+| `a man picking apricots+ from a tree`                                                                                                      | `a man picking apricots++ from a tree`                                                                                                              | `a man picking apricots+++ from a tree`                                                                                                                     | `a man picking apricots++++ from a tree`                                                                                                                                           | `a man picking apricots+++++ from a tree`                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ![an AI generated image of a man picking apricots from a tree, with larger, more vibrant apricots](../assets/prompt_syntax/apricots-1.png) | ![an AI generated image of a man picking apricots from a tree with even larger, even more vibrant apricots](../assets/prompt_syntax/apricots-2.png) | ![an AI generated image of a man picking apricots from a tree, but the man has been replaced by a pile of apricots](../assets/prompt_syntax/apricots-3.png) | ![an AI generated image of a man picking apricots from a tree, but the man has been replaced by a mound of giant melting-looking apricots](../assets/prompt_syntax/apricots-4.png) | ![an AI generated image of a man picking apricots from a tree, but the man and the leaves and parts of the ground have all been replaced by giant melting-looking apricots](../assets/prompt_syntax/apricots-5.png) |
+
+You can also change the balance between different parts of a prompt. For
+example, below is a `mountain man`:
+
+<figure markdown>
+
+![an AI generated image of a mountain man](../assets/prompt_syntax/mountain-man.png)
+
+</figure>
+
+And here he is with more mountain:
+
+| `mountain+ man`                                | `mountain++ man`                               | `mountain+++ man`                              |
+| ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
+| ![](../assets/prompt_syntax/mountain1-man.png) | ![](../assets/prompt_syntax/mountain2-man.png) | ![](../assets/prompt_syntax/mountain3-man.png) |
+
+Or, alternatively, with more man:
+
+| `mountain man+`                                | `mountain man++`                               | `mountain man+++`                              | `mountain man++++`                             |
+| ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
+| ![](../assets/prompt_syntax/mountain-man1.png) | ![](../assets/prompt_syntax/mountain-man2.png) | ![](../assets/prompt_syntax/mountain-man3.png) | ![](../assets/prompt_syntax/mountain-man4.png) |
+
+### Prompt Blending
+
+- `("a tall thin man picking apricots", "a tall thin man picking pears").blend(1,1)`
+- The existing prompt blending using `:<weight>` will continue to be supported -
+  `("a tall thin man picking apricots", "a tall thin man picking pears").blend(1,1)`
+  is equivalent to
+  `a tall thin man picking apricots:1 a tall thin man picking pears:1` in the
+  old syntax.
+- Attention weights can be nested inside blends.
+- Non-normalized blends are supported by passing `no_normalize` as an additional
+  argument to the blend weights, eg
+  `("a tall thin man picking apricots", "a tall thin man picking pears").blend(1,-1,no_normalize)`.
+  very fun to explore local maxima in the feature space, but also easy to
+  produce garbage output.
+
+See the section below on "Prompt Blending" for more information about how this
+works.
+
+### Prompt Conjunction  
+Join multiple clauses together to create a conjoined prompt. Each clause will be passed to CLIP separately. 
+
+For example, the prompt: 
+
+```bash
+"A mystical valley surround by towering granite cliffs, watercolor, warm"
+```
+
+Can be used with .and():
+```bash
+("A mystical valley", "surround by towering granite cliffs", "watercolor", "warm").and()
+```
+
+Each will give you different results - try them out and see what you prefer!
+
+
+
+### Cross-Attention Control ('prompt2prompt')
+
+Sometimes an image you generate is almost right, and you just want to change one
+detail without affecting the rest. You could use a photo editor and inpainting
+to overpaint the area, but that's a pain. Here's where `prompt2prompt` comes in
+handy.
+
+Generate an image with a given prompt, record the seed of the image, and then
+use the `prompt2prompt` syntax to substitute words in the original prompt for
+words in a new prompt. This works for `img2img` as well.
+
+For example, consider the prompt `a cat.swap(dog) playing with a ball in the forest`. Normally, because of the word words interact with each other when doing a stable diffusion image generation, these two prompts would generate different compositions:
+  - `a cat playing with a ball in the forest`
+  - `a dog playing with a ball in the forest`
+
+| `a cat playing with a ball in the forest` | `a dog playing with a ball in the forest` |
+| --- | --- |
+| img | img |
+
+
+      - For multiple word swaps, use parentheses: `a (fluffy cat).swap(barking dog) playing with a ball in the forest`.
+      - To swap a comma, use quotes: `a ("fluffy, grey cat").swap("big, barking dog") playing with a ball in the forest`.
+- Supports options `t_start` and `t_end` (each 0-1) loosely corresponding to (bloc97's)[(https://github.com/bloc97/CrossAttentionControl)] `prompt_edit_tokens_start/_end` but with the math swapped to make it easier to
+  intuitively understand. `t_start` and `t_end` are used to control on which steps cross-attention control should run. With the default values `t_start=0` and `t_end=1`, cross-attention control is active on every step of image generation. Other values can be used to turn cross-attention control off for part of the image generation process.
+    - For example, if doing a diffusion with 10 steps for the prompt is `a cat.swap(dog, t_start=0.3, t_end=1.0) playing with a ball in the forest`, the first 3 steps will be run as `a cat playing with a ball in the forest`, while the last 7 steps will run as `a dog playing with a ball in the forest`, but the pixels that represent `dog` will be locked to the pixels that would have represented `cat` if the `cat` prompt had been used instead.
+    - Conversely, for `a cat.swap(dog, t_start=0, t_end=0.7) playing with a ball in the forest`, the first 7 steps will run as `a dog playing with a ball in the forest` with the pixels that represent `dog` locked to the same pixels that would have represented `cat` if the `cat` prompt was being used instead. The final 3 steps will just run `a cat playing with a ball in the forest`.
+    > For img2img, the step sequence does not start at 0 but instead at `(1.0-strength)` - so if the img2img `strength` is `0.7`, `t_start` and `t_end` must both be greater than `0.3` (`1.0-0.7`) to have any effect.
+
+Prompt2prompt `.swap()` is not compatible with xformers, which will be temporarily disabled when doing a `.swap()` - so you should expect to use more VRAM and run slower that with xformers enabled.
+
+The `prompt2prompt` code is based off
+[bloc97's colab](https://github.com/bloc97/CrossAttentionControl).
+
+### Escaping parentheses and speech marks 
+
+If the model you are using has parentheses () or speech marks "" as part of its
+syntax, you will need to "escape" these using a backslash, so that`(my_keyword)`
+becomes `\(my_keyword\)`. Otherwise, the prompt parser will attempt to interpret
+the parentheses as part of the prompt syntax and it will get confused.
+
+---
+
+## **Prompt Blending**
+
+You may blend together prompts to explore the AI's
+latent semantic space and generate interesting (and often surprising!)
+variations. The syntax is:
+
+```bash
+("prompt #1", "prompt #2").blend(0.25, 0.75)
+```
+
+This will tell the sampler to blend 25% of the concept of prompt #1 with 75%
+of the concept of prompt #2. It is recommended to keep the sum of the weights to around 1.0, but interesting things might happen if you go outside of this range.
+
+Because you are exploring the "mind" of the AI, the AI's way of mixing two
+concepts may not match yours, leading to surprising effects. To illustrate, here
+are three images generated using various combinations of blend weights. As
+usual, unless you fix the seed, the prompts will give you different results each
+time you run them.
+
+Let's examine how this affects image generation results:
+
+
+```bash
+"blue sphere, red cube, hybrid"
+```
+
+This example doesn't use blending at all and represents the default way of mixing
+concepts.
+
+<figure markdown>
+
+![blue-sphere-red-cube-hyprid](../assets/prompt-blending/blue-sphere-red-cube-hybrid.png)
+
+</figure>
+
+It's interesting to see how the AI expressed the concept of "cube" within the sphere. If you look closely, there is depth there, so the enclosing frame is actually a cube.
+
+<figure markdown>
+
+```bash
+("blue sphere", "red cube").blend(0.25, 0.75)
+```
+
+![blue-sphere-25-red-cube-75](../assets/prompt-blending/blue-sphere-0.25-red-cube-0.75-hybrid.png)
+
+</figure>
+
+Now that's interesting. We get an image with a resemblance of a red cube, with a hint of blue shadows which represents a melding of concepts within the AI's "latent space" of semantic representations. 
+
+<figure markdown>
+
+```bash
+("blue sphere", "red cube").blend(0.75, 0.25)
+```
+
+![blue-sphere-75-red-cube-25](../assets/prompt-blending/blue-sphere-0.75-red-cube-0.25-hybrid.png)
+
+</figure>
+
+Definitely more blue-spherey. 
+
+<figure markdown>
+
+```bash
+("blue sphere", "red cube").blend(0.5, 0.5)
+```
+</figure>
+
+<figure markdown>
+![blue-sphere-5-red-cube-5-hybrid](../assets/prompt-blending/blue-sphere-0.5-red-cube-0.5-hybrid.png)
+</figure>
+
+
+Whoa...! I see blue and red, and if I squint, spheres and cubes.
+
+
+
+## Dynamic Prompts
+
+Dynamic Prompts are a powerful feature designed to produce a variety of prompts based on user-defined options. Using a special syntax, you can construct a prompt with multiple possibilities, and the system will automatically generate a series of permutations based on your settings. This is extremely beneficial for ideation, exploring various scenarios, or testing different concepts swiftly and efficiently.
+
+### Structure of a Dynamic Prompt
+
+A Dynamic Prompt comprises of regular text, supplemented with alternatives enclosed within curly braces {} and separated by a vertical bar |. For example: {option1|option2|option3}. The system will then select one of the options to include in the final prompt. This flexible system allows for options to be placed throughout the text as needed.
+
+Furthermore, Dynamic Prompts can designate multiple selections from a single group of options. This feature is triggered by prefixing the options with a numerical value followed by $$. For example, in {2$$option1|option2|option3}, the system will select two distinct options from the set.
+### Creating Dynamic Prompts
+
+To create a Dynamic Prompt, follow these steps:
+
+    Draft your sentence or phrase, identifying words or phrases with multiple possible options.
+    Encapsulate the different options within curly braces {}.
+    Within the braces, separate each option using a vertical bar |.
+    If you want to include multiple options from a single group, prefix with the desired number and $$.
+
+For instance: A {house|apartment|lodge|cottage} in {summer|winter|autumn|spring} designed in {style1|style2|style3}.
+### How Dynamic Prompts Work
+
+Once a Dynamic Prompt is configured, the system generates an array of combinations using the options provided. Each group of options in curly braces is treated independently, with the system selecting one option from each group. For a prefixed set (e.g., 2$$), the system will select two distinct options.
+
+For example, the following prompts could be generated from the above Dynamic Prompt:
+
+    A house in summer designed in style1, style2
+    A lodge in autumn designed in style3, style1
+    A cottage in winter designed in style2, style3
+    And many more!
+
+When the `Combinatorial` setting is on, Invoke will disable the "Images" selection, and generate every combination up until the setting for Max Prompts is reached.
+When the `Combinatorial` setting is off, Invoke will randomly generate combinations up until the setting for Images has been reached.
+
+
+
+### Tips and Tricks for Using Dynamic Prompts
+
+Below are some useful strategies for creating Dynamic Prompts:
+
+    Utilize Dynamic Prompts to generate a wide spectrum of prompts, perfect for brainstorming and exploring diverse ideas.
+    Ensure that the options within a group are contextually relevant to the part of the sentence where they are used. For instance, group building types together, and seasons together.
+    Apply the 2$$ prefix when you want to incorporate more than one option from a single group. This becomes quite handy when mixing and matching different elements.
+    Experiment with different quantities for the prefix. For example, 3$$ will select three distinct options.
+    Be aware of coherence in your prompts. Although the system can generate all possible combinations, not all may semantically make sense. Therefore, carefully choose the options for each group.
+    Always review and fine-tune the generated prompts as needed. While Dynamic Prompts can help you generate a multitude of combinations, the final polishing and refining remain in your hands.
+
+
+## SDXL Prompting
+
+Prompting with SDXL is slightly different than prompting with SD1.5 or SD2.1 models - SDXL expects a prompt _and_ a style. 
+
+
+### Prompting 
+<figure markdown>
+
+![SDXL prompt boxes in InvokeAI](../assets/prompt_syntax/sdxl-prompt.png)
+
+</figure>
+
+In the prompt box, enter a positive or negative prompt as you normally would. 
+
+For the style box you can enter a style that you want the image to be generated in. You can use styles from this example list, or any other style you wish: anime, photographic, digital art, comic book, fantasy art, analog film, neon punk, isometric, low poly, origami, line art, cinematic, 3d model, pixel art, etc.
+
+
+### Concatenated Prompts
+
+
+InvokeAI also has the option to concatenate the prompt and style inputs, by pressing the "link" button in the Positive Prompt box. 
+
+This concatenates the prompt & style inputs, and passes the joined prompt and style to the SDXL model. 
+![SDXL concatenated prompt boxes in InvokeAI](../assets/prompt_syntax/sdxl-prompt-concatenated.png)
+
+
+
+
+
+
+

docs/features/TRAINING.md

@@ -0,0 +1,281 @@
+---
+title: Training
+---
+
+# :material-file-document: Training
+
+# Textual Inversion Training
+## **Personalizing Text-to-Image Generation**
+
+You may personalize the generated images to provide your own styles or objects
+by training a new LDM checkpoint and introducing a new vocabulary to the fixed
+model as a (.pt) embeddings file. Alternatively, you may use or train
+HuggingFace Concepts embeddings files (.bin) from
+<https://huggingface.co/sd-concepts-library> and its associated
+notebooks.
+
+## **Hardware and Software Requirements**
+
+You will need a GPU to perform training in a reasonable length of
+time, and at least 12 GB of VRAM. We recommend using the [`xformers`
+library](../installation/070_INSTALL_XFORMERS.md) to accelerate the
+training process further. During training, about ~8 GB is temporarily
+needed in order to store intermediate models, checkpoints and logs.
+
+## **Preparing for Training**
+
+To train, prepare a folder that contains 3-5 images that illustrate
+the object or concept. It is good to provide a variety of examples or
+poses to avoid overtraining the system. Format these images as PNG
+(preferred) or JPG. You do not need to resize or crop the images in
+advance, but for more control you may wish to do so.
+
+Place the training images in a directory on the machine InvokeAI runs
+on. We recommend placing them in a subdirectory of the
+`text-inversion-training-data` folder located in the InvokeAI root
+directory, ordinarily `~/invokeai` (Linux/Mac), or
+`C:\Users\your_name\invokeai` (Windows). For example, to create an
+embedding for the "psychedelic" style, you'd place the training images
+into the directory
+`~invokeai/text-inversion-training-data/psychedelic`.
+
+## **Launching Training Using the Console Front End**
+
+InvokeAI 2.3 and higher comes with a text console-based training front
+end. From within the `invoke.sh`/`invoke.bat` Invoke launcher script,
+start training tool selecting choice (3):
+
+```sh
+1 "Generate images with a browser-based interface"
+2 "Explore InvokeAI nodes using a command-line interface"
+3 "Textual inversion training"
+4 "Merge models (diffusers type only)"
+5 "Download and install models"
+6 "Change InvokeAI startup options"
+7 "Re-run the configure script to fix a broken install or to complete a major upgrade"
+8 "Open the developer console"
+9 "Update InvokeAI"
+```
+
+Alternatively, you can select option (8) or from the command line, with the InvokeAI virtual environment active,
+you can then launch the front end with the command `invokeai-ti --gui`.
+
+This will launch a text-based front end that will look like this:
+
+<figure markdown>
+![ti-frontend](../assets/textual-inversion/ti-frontend.png)
+</figure>
+
+The interface is keyboard-based. Move from field to field using
+control-N (^N) to move to the next field and control-P (^P) to the
+previous one. <Tab> and <shift-TAB> work as well. Once a field is
+active, use the cursor keys. In a checkbox group, use the up and down
+cursor keys to move from choice to choice, and <space> to select a
+choice. In a scrollbar, use the left and right cursor keys to increase
+and decrease the value of the scroll. In textfields, type the desired
+values.
+
+The number of parameters may look intimidating, but in most cases the
+predefined defaults work fine. The red circled fields in the above
+illustration are the ones you will adjust most frequently.
+
+### Model Name
+
+This will list all the diffusers models that are currently
+installed. Select the one you wish to use as the basis for your
+embedding. Be aware that if you use a SD-1.X-based model for your
+training, you will only be able to use this embedding with other
+SD-1.X-based models. Similarly, if you train on SD-2.X, you will only
+be able to use the embeddings with models based on SD-2.X.
+
+### Trigger Term
+
+This is the prompt term you will use to trigger the embedding. Type a
+single word or phrase you wish to use as the trigger, example
+"psychedelic" (without angle brackets). Within InvokeAI, you will then
+be able to activate the trigger using the syntax `<psychedelic>`.
+
+### Initializer
+
+This is a single character that is used internally during the training
+process as a placeholder for the trigger term. It defaults to "*" and
+can usually be left alone.
+
+### Resume from last saved checkpoint
+
+As training proceeds, textual inversion will write a series of
+intermediate files that can be used to resume training from where it
+was left off in the case of an interruption. This checkbox will be
+automatically selected if you provide a previously used trigger term
+and at least one checkpoint file is found on disk.
+
+Note that as of 20 January 2023, resume does not seem to be working
+properly due to an issue with the upstream code.
+
+### Data Training Directory
+
+This is the location of the images to be used for training. When you
+select a trigger term like "my-trigger", the frontend will prepopulate
+this field with `~/invokeai/text-inversion-training-data/my-trigger`,
+but you can change the path to wherever you want.
+
+### Output Destination Directory
+
+This is the location of the logs, checkpoint files, and embedding
+files created during training. When you select a trigger term like
+"my-trigger", the frontend will prepopulate this field with
+`~/invokeai/text-inversion-output/my-trigger`, but you can change the
+path to wherever you want.
+
+### Image resolution
+
+The images in the training directory will be automatically scaled to
+the value you use here. For best results, you will want to use the
+same default resolution of the underlying model (512 pixels for
+SD-1.5, 768 for the larger version of SD-2.1).
+
+### Center crop images
+
+If this is selected, your images will be center cropped to make them
+square before resizing them to the desired resolution. Center cropping
+can indiscriminately cut off the top of subjects' heads for portrait
+aspect images, so if you have images like this, you may wish to use a
+photoeditor to manually crop them to a square aspect ratio.
+
+### Mixed precision
+
+Select the floating point precision for the embedding. "no" will
+result in a full 32-bit precision, "fp16" will provide 16-bit
+precision, and "bf16" will provide mixed precision (only available
+when XFormers is used).
+
+### Max training steps
+
+How many steps the training will take before the model converges. Most
+training sets will converge with 2000-3000 steps.
+
+### Batch size
+
+This adjusts how many training images are processed simultaneously in
+each step. Higher values will cause the training process to run more
+quickly, but use more memory. The default size will run with GPUs with
+as little as 12 GB.
+
+### Learning rate
+
+The rate at which the system adjusts its internal weights during
+training. Higher values risk overtraining (getting the same image each
+time), and lower values will take more steps to train a good
+model. The default of 0.0005 is conservative; you may wish to increase
+it to 0.005 to speed up training.
+
+### Scale learning rate by number of GPUs, steps and batch size
+
+If this is selected (the default) the system will adjust the provided
+learning rate to improve performance.
+
+### Use xformers acceleration
+
+This will activate XFormers memory-efficient attention. You need to
+have XFormers installed for this to have an effect.
+
+### Learning rate scheduler
+
+This adjusts how the learning rate changes over the course of
+training. The default "constant" means to use a constant learning rate
+for the entire training session. The other values scale the learning
+rate according to various formulas.
+
+Only "constant" is supported by the XFormers library.
+
+### Gradient accumulation steps
+
+This is a parameter that allows you to use bigger batch sizes than
+your GPU's VRAM would ordinarily accommodate, at the cost of some
+performance.
+
+### Warmup steps
+
+If "constant_with_warmup" is selected in the learning rate scheduler,
+then this provides the number of warmup steps. Warmup steps have a
+very low learning rate, and are one way of preventing early
+overtraining.
+
+## The training run
+
+Start the training run by advancing to the OK button (bottom right)
+and pressing <enter>. A series of progress messages will be displayed
+as the training process proceeds. This may take an hour or two,
+depending on settings and the speed of your system. Various log and
+checkpoint files will be written into the output directory (ordinarily
+`~/invokeai/text-inversion-output/my-model/`)
+
+At the end of successful training, the system will copy the file
+`learned_embeds.bin` into the InvokeAI root directory's `embeddings`
+directory, using a subdirectory named after the trigger token. For
+example, if the trigger token was `psychedelic`, then look for the
+embeddings file in
+`~/invokeai/embeddings/psychedelic/learned_embeds.bin`
+
+You may now launch InvokeAI and try out a prompt that uses the trigger
+term. For example `a plate of banana sushi in <psychedelic> style`.
+
+## **Training with the Command-Line Script**
+
+Training can also be done using a traditional command-line script. It
+can be launched from within the "developer's console", or from the
+command line after activating InvokeAI's virtual environment.
+
+It accepts a large number of arguments, which can be summarized by
+passing the `--help` argument:
+
+```sh
+invokeai-ti --help
+```
+
+Typical usage is shown here:
+```sh
+invokeai-ti \
+       --model=stable-diffusion-1.5 \
+       --resolution=512 \
+       --learnable_property=style \
+       --initializer_token='*' \
+       --placeholder_token='<psychedelic>' \
+       --train_data_dir=/home/lstein/invokeai/training-data/psychedelic \
+       --output_dir=/home/lstein/invokeai/text-inversion-training/psychedelic \
+       --scale_lr \
+       --train_batch_size=8 \
+       --gradient_accumulation_steps=4 \
+       --max_train_steps=3000 \
+       --learning_rate=0.0005 \
+       --resume_from_checkpoint=latest \
+       --lr_scheduler=constant \
+       --mixed_precision=fp16 \
+       --only_save_embeds
+```
+
+## Troubleshooting
+
+### `Cannot load embedding for <trigger>. It was trained on a model with token dimension 1024, but the current model has token dimension 768`
+
+Messages like this indicate you trained the embedding on a different base model than the currently selected one.
+
+For example, in the error above, the training was done on SD2.1 (768x768) but it was used on SD1.5 (512x512).
+
+## Reading
+
+For more information on textual inversion, please see the following
+resources:
+
+* The [textual inversion repository](https://github.com/rinongal/textual_inversion) and
+  associated paper for details and limitations.
+* [HuggingFace's textual inversion training
+  page](https://huggingface.co/docs/diffusers/training/text_inversion)
+* [HuggingFace example script
+  documentation](https://github.com/huggingface/diffusers/tree/main/examples/textual_inversion)
+  (Note that this script is similar to, but not identical, to
+  `textual_inversion`, but produces embed files that are completely compatible.
+
+---
+
+copyright (c) 2023, Lincoln Stein and the InvokeAI Development Team

docs/features/UNIFIED_CANVAS.md

@@ -0,0 +1,284 @@
+---
+title: Unified Canvas
+---
+
+The Unified Canvas is a tool designed to streamline and simplify the process of
+composing an image using Stable Diffusion. It offers artists all of the
+available Stable Diffusion generation modes (Text To Image, Image To Image,
+Inpainting, and Outpainting) as a single unified workflow. The flexibility of
+the tool allows you to tweak and edit image generations, extend images beyond
+their initial size, and to create new content in a freeform way both inside and
+outside of existing images.
+
+This document explains the basics of using the Unified Canvas, introducing you
+to its features and tools one by one. It also describes some of the more
+advanced tools available to power users of the Canvas.
+
+## Basics
+
+The Unified Canvas consists of two layers: the **Base Layer** and the **Mask
+Layer**. You can swap from one layer to the other by selecting the layer you
+want in the drop-down menu on the top left corner of the Unified Canvas, or by
+pressing the (Q) hotkey.
+
+### Base Layer
+
+The **Base Layer** is the image content currently managed by the Canvas, and can
+be exported at any time to the gallery by using the **Save to Gallery** option.
+When the Base Layer is selected, the Brush (B) and Eraser (E) tools will
+directly manipulate the base layer. Any images uploaded to the Canvas, or sent
+to the Unified Canvas from the gallery, will clear out all existing content and
+set the Base layer to the new image.
+
+### Staging Area
+
+When you generate images, they will display in the Canvas's **Staging Area**,
+alongside the Staging Area toolbar buttons. While the Staging Area is active,
+you cannot interact with the Canvas itself.
+
+<figure markdown>
+
+![staging area](../assets/canvas/staging_area.png)
+
+</figure>
+
+Accepting generations will commit the new generation to the **Base Layer**. You
+can review all generated images using the Prev/Next arrows, save any individual
+generations to your gallery (without committing to the Base layer) or discard
+generations. While you can Undo a discard in an individual Canvas session, any
+generations that are not saved will be lost when the Canvas resets.
+
+### Mask Layer
+
+The **Mask Layer** consists of any masked sections that have been created to
+inform Inpainting generations. You can paint a new mask, or edit an existing
+mask, using the Brush tool and the Eraser with the Mask layer set as your Active
+layer. Any masked areas will only affect generation inside of the current
+bounding box.
+
+### Bounding Box
+
+When generating a new image, Invoke will process and apply new images within the
+area denoted by the **Bounding Box**. The Width & Height settings of the
+Bounding Box, as well as its location within the Unified Canvas and pixels or
+empty space that it encloses, determine how new invocations are generated - see
+[Inpainting & Outpainting](#inpainting-and-outpainting) below. The Bounding Box
+can be moved and resized using the Move (V) tool. It can also be resized using
+the Bounding Box options in the Options Panel. By using these controls you can
+generate larger or smaller images, control which sections of the image are being
+processed, as well as control Bounding Box tools like the Bounding Box
+fill/erase.
+
+### <a name="inpainting-and-outpainting"></a> Inpainting & Outpainting
+
+"Inpainting" means asking the AI to refine part of an image while leaving the
+rest alone. For example, updating a portrait of your grandmother to have her
+wear a biker's jacket.
+
+|                         masked original                         |                                       inpaint result                                       |
+| :-------------------------------------------------------------: | :----------------------------------------------------------------------------------------: |
+| ![granny with a mask applied](../assets/canvas/mask_granny.png) | ![just like magic, granny with a biker's jacket](../assets/canvas/biker_jacket_granny.png) |
+
+"Outpainting" means asking the AI to expand the original image beyond its
+original borders, making a bigger image that's still based on the original. For
+example, extending the above image of your Grandmother in a biker's jacket to
+include her wearing jeans (and while we're at it, a motorcycle!)
+
+<figure markdown>
+
+![more magic - granny with a tattooed arm, denim pants, and an obscured motorcycle](../assets/canvas/biker_granny.png)
+
+</figure>
+
+When you are using the Unified Canvas, Invoke decides automatically whether to
+do Inpainting, Outpainting, ImageToImage, or TextToImage by looking inside the
+area enclosed by the Bounding Box. It chooses the appropriate type of generation
+based on whether the Bounding Box contains empty (transparent) areas on the Base
+layer, or whether it contains colored areas from previous generations (or from
+painted brushstrokes) on the Base layer, and/or whether the Mask layer contains
+any brushstrokes. See [Generation Methods](#generation-methods) below for more
+information.
+
+## Getting Started
+
+To get started with the Unified Canvas, you will want to generate a new base
+layer using Txt2Img or importing an initial image. We'll refer to either of
+these methods as the "initial image" in the below guide.
+
+From there, you can consider the following techniques to augment your image:
+
+- **New Images**: Move the bounding box to an empty area of the Canvas, type in
+  your prompt, and Invoke, to generate a new image using the Text to Image
+  function.
+- **Image Correction**: Use the color picker and brush tool to paint corrections
+  on the image, switch to the Mask layer, and brush a mask over your painted
+  area to use **Inpainting**. You can also use the **ImageToImage** generation
+  method to invoke new interpretations of the image.
+- **Image Expansion**: Move the bounding box to include a portion of your
+  initial image, and a portion of transparent/empty pixels, then Invoke using a
+  prompt that describes what you'd like to see in that area. This will Outpaint
+  the image. You'll typically find more coherent results if you keep about
+  50-60% of the original image in the bounding box. Make sure that the Image To
+  Image Strength slider is set to a high value - you may need to set it higher
+  than you are used to.
+- **New Content on Existing Images**: If you want to add new details or objects
+  into your image, use the brush tool to paint a sketch of what you'd like to
+  see on the image, switch to the Mask layer, and brush a mask over your painted
+  area to use **Inpainting**. If the masked area is small, consider using a
+  smaller bounding box to take advantage of Invoke's automatic Scaling features,
+  which can help to produce better details.
+- **And more**: There are a number of creative ways to use the Canvas, and the
+  above are just starting points. We're excited to see what you come up with!
+
+## <a name="generation-methods"></a> Generation Methods
+
+The Canvas can use all generation methods available (Txt2Img, Img2Img,
+Inpainting, and Outpainting), and these will be automatically selected and used
+based on the current selection area within the Bounding Box.
+
+### Text to Image
+
+If the Bounding Box is placed over an area of Canvas with an **empty Base
+Layer**, invoking a new image will use **TextToImage**. This generates an
+entirely new image based on your prompt.
+
+### Image to Image
+
+If the Bounding Box is placed over an area of Canvas with an **existing Base
+Layer area with no transparent pixels or masks**, invoking a new image will use
+**ImageToImage**. This uses the image within the bounding box and your prompt to
+interpret a new image. The image will be closer to your original image at lower
+Image to Image strengths.
+
+### Inpainting
+
+If the Bounding Box is placed over an area of Canvas with an **existing Base
+Layer and any pixels selected using the Mask layer**, invoking a new image will
+use **Inpainting**. Inpainting uses the existing colors/forms in the masked area
+in order to generate a new image for the masked area only. The unmasked portion
+of the image will remain the same. Image to Image strength applies to the
+inpainted area.
+
+If you desire something completely different from the original image in your new
+generation (i.e., if you want Invoke to ignore existing colors/forms), consider
+toggling the Inpaint Replace setting on, and use high values for both Inpaint
+Replace and Image To Image Strength.
+
+!!! note
+
+    By default, the **Scale Before Processing** option &mdash; which
+    inpaints more coherent details by generating at a larger resolution and then
+    scaling &mdash; is only activated when the Bounding Box is relatively small.
+    To get the best inpainting results you should therefore resize your Bounding
+    Box to the smallest area that contains your mask and enough surrounding detail
+    to help Stable Diffusion understand the context of what you want it to draw.
+    You should also update your prompt so that it describes _just_ the area within
+    the Bounding Box.
+
+### Outpainting
+
+If the Bounding Box is placed over an area of Canvas partially filled by an
+existing Base Layer area and partially by transparent pixels or masks, invoking
+a new image will use **Outpainting**, as well as **Inpainting** any masked
+areas.
+
+---
+
+## Advanced Features
+
+Features with non-obvious behavior are detailed below, in order to provide
+clarity on the intent and common use cases we expect for utilizing them.
+
+### Toolbar
+
+#### Mask Options
+
+- **Enable Mask** - This flag can be used to Enable or Disable the currently
+  painted mask. If you have painted a mask, but you don't want it affect the
+  next invocation, but you _also_ don't want to delete it, then you can set this
+  option to Disable. When you want the mask back, set this back to Enable.
+- **Preserve Masked Area** - When enabled, Preserve Masked Area inverts the
+  effect of the Mask on the Inpainting process. Pixels in masked areas will be
+  kept unchanged, and unmasked areas will be regenerated.
+
+#### Creative Tools
+
+- **Brush - Base/Mask Modes** - The Brush tool switches automatically between
+  different modes of operation for the Base and Mask layers respectively.
+    - On the Base layer, the brush will directly paint on the Canvas using the
+      color selected on the Brush Options menu.
+    - On the Mask layer, the brush will create a new mask. If you're finding the
+      mask difficult to see over the existing content of the Unified Canvas, you
+      can change the color it is drawn with using the color selector on the Mask
+      Options dropdown.
+- **Erase Bounding Box** - On the Base layer, erases all pixels within the
+  Bounding Box.
+- **Fill Bounding Box** - On the Base layer, fills all pixels within the
+  Bounding Box with the currently selected color.
+
+#### Canvas Tools
+
+- **Move Tool** - Allows for manipulation of the Canvas view (by dragging on the
+  Canvas, outside the bounding box), the Bounding Box (by dragging the edges of
+  the box), or the Width/Height of the Bounding Box (by dragging one of the 9
+  directional handles).
+- **Reset View** - Click to re-orients the view to the center of the Bounding
+  Box.
+- **Merge Visible** - If your browser is having performance problems drawing the
+  image in the Unified Canvas, click this to consolidate all of the information
+  currently being rendered by your browser into a merged copy of the image. This
+  lowers the resource requirements and should improve performance.
+
+### Seam Correction
+
+When doing Inpainting or Outpainting, Invoke needs to merge the pixels generated
+by Stable Diffusion into your existing image. To do this, the area around the
+`seam` at the boundary between your image and the new generation is
+automatically blended to produce a seamless output. In a fully automatic
+process, a mask is generated to cover the seam, and then the area of the seam is
+Inpainted.
+
+Although the default options should work well most of the time, sometimes it can
+help to alter the parameters that control the seam Inpainting. A wider seam and
+a blur setting of about 1/3 of the seam have been noted as producing
+consistently strong results (e.g. 96 wide and 16 blur - adds up to 32 blur with
+both sides). Seam strength of 0.7 is best for reducing hard seams.
+
+- **Seam Size** - The size of the seam masked area. Set higher to make a larger
+  mask around the seam.
+- **Seam Blur** - The size of the blur that is applied on _each_ side of the
+  masked area.
+- **Seam Strength** - The Image To Image Strength parameter used for the
+  Inpainting generation that is applied to the seam area.
+- **Seam Steps** - The number of generation steps that should be used to Inpaint
+  the seam.
+
+### Infill & Scaling
+
+- **Scale Before Processing & W/H**: When generating images with a bounding box
+  smaller than the optimized W/H of the model (e.g., 512x512 for SD1.5), this
+  feature first generates at a larger size with the same aspect ratio, and then
+  scales that image down to fill the selected area. This is particularly useful
+  when inpainting very small details. Scaling is optional but is enabled by
+  default.
+- **Inpaint Replace**: When Inpainting, the default method is to utilize the
+  existing RGB values of the Base layer to inform the generation process. If
+  Inpaint Replace is enabled, noise is generated and blended with the existing
+  pixels (completely replacing the original RGB values at an Inpaint Replace
+  value of 1). This can help generate more variation from the pixels on the Base
+  layers.
+    - When using Inpaint Replace you should use a higher Image To Image Strength
+      value, especially at higher Inpaint Replace values
+- **Infill Method**: Invoke currently supports two methods for producing RGB
+  values for use in the Outpainting process: Patchmatch and Tile. We believe
+  that Patchmatch is the superior method, however we provide support for Tile in
+  case Patchmatch cannot be installed or is unavailable on your computer.
+- **Tile Size**: The Tile method for Outpainting sources small portions of the
+  original image and randomly place these into the areas being Outpainted. This
+  value sets the size of those tiles.
+
+## Hot Keys
+
+The Unified Canvas is a tool that excels when you use hotkeys. You can view the
+full list of keyboard shortcuts, updated with all new features, by clicking the
+Keyboard Shortcuts icon at the top right of the InvokeAI WebUI.

docs/features/VARIATIONS.md

@@ -0,0 +1,131 @@
+---
+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](OTHER.md#thresholding-and-perlin-noise-initialization-options)
+feature, which provides another way of introducing variability into your
+image generation requests.

docs/features/WATERMARK+NSFW.md

@@ -0,0 +1,96 @@
+---
+title: Watermarking, NSFW Image Checking
+---
+
+# :material-image-off: Invisible Watermark and the NSFW Checker
+
+## Watermarking
+
+InvokeAI does not apply watermarking to images by default. However,
+many computer scientists working in the field of generative AI worry
+that a flood of computer-generated imagery will contaminate the image
+data sets needed to train future generations of generative models.
+
+InvokeAI offers an optional watermarking mode that writes a small bit
+of text, **InvokeAI**, into each image that it generates using an
+"invisible" watermarking library that spreads the information
+throughout the image in a way that is not perceptible to the human
+eye. If you are planning to share your generated images on
+internet-accessible services, we encourage you to activate the
+invisible watermark mode in order to help preserve the digital image
+environment.
+
+The downside of watermarking is that it increases the size of the
+image moderately, and has been reported by some individuals to degrade
+image quality. Your mileage may vary.
+
+To read the watermark in an image, activate the InvokeAI virtual
+environment (called the "developer's console" in the launcher) and run
+the command:
+
+```
+invisible-watermark -a decode -t bytes -m dwtDct -l 64 /path/to/image.png
+```
+
+## The NSFW ("Safety") Checker
+
+Stable Diffusion 1.5-based 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-SD1+SD2.txt),
+and the [Stable Diffusion XL
+License][https://github.com/invoke-ai/InvokeAI/blob/main/LICENSE-SDXL.txt]
+both forbid the models 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 in the Web interface under Settings.
+
+## 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.
+

docs/features/WEB.md

@@ -0,0 +1,325 @@
+---
+title: InvokeAI Web Server
+---
+
+# :material-web: InvokeAI Web Server
+
+## Quick guided walkthrough of the WebUI's features
+
+While most of the WebUI's features are intuitive, here is a guided walkthrough
+through its various components.
+
+### Launching the WebUI
+
+To run the InvokeAI web server, start the `invoke.sh`/`invoke.bat`
+script and select option (1). Alternatively, with the InvokeAI
+environment active, run `invokeai-web`:
+
+```bash
+invokeai-web
+```
+
+You can then connect to the server by pointing your web browser at
+http://localhost:9090. To reach the server from a different machine on your LAN,
+you may launch the web server with the `--host` argument and either the IP
+address of the host you are running it on, or the wildcard `0.0.0.0`. For
+example:
+
+```bash
+invoke.sh --host 0.0.0.0
+```
+
+or
+
+```bash
+invokeai-web --host 0.0.0.0
+```
+
+### The InvokeAI Web Interface
+
+![Invoke Web Server - Major Components](../assets/invoke-web-server-1.png){:width="640px"}
+
+The screenshot above shows the Text to Image tab of the WebUI. There are three
+main sections:
+
+1. A **control panel** on the left, which contains various settings
+   for text to image generation. The most important part is the text
+   field (currently showing `fantasy painting, horned demon`) for
+   entering the positive text prompt, another text field right below it for an
+   optional negative text prompt (concepts to exclude), and a _Invoke_ button 
+   to begin the image rendering process.
+
+2. The **current image** section in the middle, which shows a large
+   format version of the image you are currently working on. A series
+   of buttons at the top lets you modify and manipulate the image in
+   various ways.
+
+3. A **gallery** section on the left that contains a history of the images you
+   have generated. These images are read and written to the directory specified
+   in the `INVOKEAIROOT/invokeai.yaml` initialization file, usually a directory
+   named `outputs` in `INVOKEAIROOT`.
+
+In addition to these three elements, there are a series of icons for changing
+global settings, reporting bugs, and changing the theme on the upper right.
+
+There are also a series of icons to the left of the control panel (see
+highlighted area in the screenshot below) which select among a series of tabs
+for performing different types of operations.
+
+<figure markdown>
+![Invoke Web Server - Control Panel](../assets/invoke-web-server-2.png){:width="512px"}
+</figure>
+
+From top to bottom, these are:
+
+1. Text to Image - generate images from text
+2. Image to Image - from an uploaded starting image (drawing or photograph)
+   generate a new one, modified by the text prompt
+3. Unified Canvas - Interactively combine multiple images, extend them
+   with outpainting,and modify interior portions of the image with
+   inpainting, erase portions of a starting image and have the AI fill in
+   the erased region from a text prompt.
+4. Node Editor - (experimental) this panel allows you to create
+   pipelines of common operations and combine them into workflows.
+5. Model Manager - this panel allows you to import and configure new
+   models using URLs, local paths, or HuggingFace diffusers repo_ids.
+
+## Walkthrough
+
+The following walkthrough will exercise most (but not all) of the WebUI's
+feature set.
+
+### Text to Image
+
+1. Launch the WebUI using launcher option [1] and connect to it with
+   your browser by accessing `http://localhost:9090`. If the browser
+   and server are running on different machines on your LAN, add the
+   option `--host 0.0.0.0` to the `invoke.sh` launch command line and connect to
+   the machine hosting the web server using its IP address or domain
+   name.
+
+2. If all goes well, the WebUI should come up and you'll see a green dot
+   meaning `connected`  on the upper right.
+
+![Invoke Web Server - Control Panel](../assets/invoke-control-panel-1.png){ align=right width=300px }
+
+#### Basics
+
+1.  Generate an image by typing _bluebird_ into the large prompt field
+    on the upper left and then clicking on the Invoke button or pressing
+	the return button.
+	After a short wait, you'll see a large image of a bluebird in the
+    image panel, and a new thumbnail in the gallery on the right.
+
+    If you need more room on the screen, you can turn the gallery off
+    by typing the **g** hotkey. You can turn it back on later by clicking the
+    image icon that appears in the gallery's place. The list of hotkeys can
+	be found by clicking on the keyboard icon above the image gallery.
+
+2.  Generate a bunch of bluebird images by increasing the number of
+    requested images by adjusting the Images counter just below the Invoke
+    button. As each is generated, it will be added to the gallery. You can
+    switch the active image by clicking on the gallery thumbnails.
+	
+	If you'd like to watch the image generation progress, click the hourglass
+	icon above the main image area. As generation progresses, you'll see
+	increasingly detailed versions of the ultimate image.
+
+3.  Try playing with different settings, including changing the main
+    model, the image width and height, the Scheduler, the Steps and
+    the CFG scale.
+	
+	The _Model_ changes the main model. Thousands of custom models are
+	now available, which generate a variety of image styles and
+	subjects. While InvokeAI comes with a few starter models, it is
+	easy to import new models into the application. See [Installing
+	Models](../installation/050_INSTALLING_MODELS.md) for more details.
+
+    Image _Width_ and _Height_ do what you'd expect. However, be aware that
+    larger images consume more VRAM memory and take longer to generate.
+
+    The _Scheduler_ controls how the AI selects the image to display. Some
+    samplers are more "creative" than others and will produce a wider range of
+    variations (see next section). Some samplers run faster than others.
+
+    _Steps_ controls how many noising/denoising/sampling steps the AI will take.
+    The higher this value, the more refined the image will be, but the longer
+    the image will take to generate. A typical strategy is to generate images
+    with a low number of steps in order to select one to work on further, and
+    then regenerate it using a higher number of steps.
+
+    The _CFG Scale_ controls how hard the AI tries to match the generated image
+    to the input prompt. You can go as high or low as you like, but generally
+    values greater than 20 won't improve things much, and values lower than 5
+    will produce unexpected images. There are complex interactions between
+    _Steps_, _CFG Scale_ and the _Scheduler_, so experiment to find out what works
+    for you.
+	
+	The _Seed_ controls the series of values returned by InvokeAI's
+    random number generator. Each unique seed value will generate a different
+	image. To regenerate a previous image, simply use the original image's
+	seed value. A slider to the right of the _Seed_ field will change the
+	seed each time an image is generated.
+
+![Invoke Web Server - Control Panel 2](../assets/control-panel-2.png){ align=right width=400px }
+
+4.  To regenerate a previously-generated image, select the image you
+    want and click the asterisk ("*") button at the top of the
+    image. This loads the text prompt and other original settings into
+    the control panel. If you then press _Invoke_ it will regenerate
+    the image exactly. You can also selectively modify the prompt or
+    other settings to tweak the image.
+
+    Alternatively, you may click on the "sprouting plant icon" to load
+    just the image's seed, and leave other settings unchanged or the
+    quote icon to load just the positive and negative prompts.
+
+5.  To regenerate a Stable Diffusion image that was generated by another SD
+    package, you need to know its text prompt and its _Seed_. Copy-paste the
+    prompt into the prompt box, unset the _Randomize Seed_ control in the
+    control panel, and copy-paste the desired _Seed_ into its text field. When
+    you Invoke, you will get something similar to the original image. It will
+    not be exact unless you also set the correct values for the original
+    sampler, CFG, steps and dimensions, but it will (usually) be close.
+	
+6.  To save an image, right click on it to bring up a menu that will
+	let you download the image, save it to a named image gallery, and
+	copy it to the clipboard, among other things.
+
+#### Upscaling
+
+![Invoke Web Server - Upscaling](../assets/upscaling.png){ align=right width=400px }
+
+"Upscaling" is the process of increasing the size of an image while
+    retaining the sharpness. InvokeAI uses an external library called
+    "ESRGAN" to do this. To invoke upscaling, simply select an image
+    and press the "expanding arrows" button above it. You can select
+    between 2X and 4X upscaling, and adjust the upscaling strength,
+    which has much the same meaning as in facial reconstruction. Try
+    running this on one of your previously-generated images.
+
+### Image to Image
+
+InvokeAI lets you take an existing image and use it as the basis for a new
+creation. You can use any sort of image, including a photograph, a scanned
+sketch, or a digital drawing, as long as it is in PNG or JPEG format.
+
+For this tutorial, we'll use the file named
+[Lincoln-and-Parrot-512.png](../assets/Lincoln-and-Parrot-512.png).
+
+1.  Click on the _Image to Image_ tab icon, which is the second icon
+    from the top on the left-hand side of the screen. This will bring
+    you to a screen similar to the one shown here:
+
+    ![Invoke Web Server - Image to Image Tab](../assets/invoke-web-server-6.png){ width="640px" }
+
+2.  Drag-and-drop the Lincoln-and-Parrot image into the Image panel, or click
+    the blank area to get an upload dialog. The image will load into an area
+    marked _Initial Image_. (The WebUI will also load the most
+    recently-generated image from the gallery into a section on the left, but
+    this image will be replaced in the next step.)
+
+3.  Go to the prompt box and type _old sea captain with raven on shoulder_ and
+    press Invoke. A derived image will appear to the right of the original one:
+
+    ![Invoke Web Server - Image to Image example](../assets/invoke-web-server-7.png){:width="640px"}
+
+4.  Experiment with the different settings. The most influential one in Image to
+    Image is _Denoising Strength_ located about midway down the control
+    panel. By default it is set to 0.75, but can range from 0.0 to 0.99. The
+    higher the value, the more of the original image the AI will replace. A
+    value of 0 will leave the initial image completely unchanged, while 0.99
+    will replace it completely. However, the _Scheduler_ and _CFG Scale_ also
+    influence the final result. You can also generate variations in the same way
+    as described in Text to Image.
+
+5.  What if we only want to change certain part(s) of the image and
+    leave the rest intact? This is called Inpainting, and you can do
+    it in the [Unified Canvas](UNIFIED_CANVAS.md). The Unified Canvas
+    also allows you to extend borders of the image and fill in the
+    blank areas, a process called outpainting.
+
+6.  Would you like to modify a previously-generated image using the Image to
+    Image facility? Easy! While in the Image to Image panel, drag and drop any
+	image in the gallery into the Initial Image area, and it will be ready for
+	use. You can do the same thing with the main image display. Click on the
+	_Send to_ icon to get a menu of
+	commands and choose "Send to Image to Image".
+	
+	![Send To Icon](../assets/send-to-icon.png) 
+
+### Textual Inversion, LoRA and ControlNet
+
+InvokeAI supports several different types of model files that
+extending the capabilities of the main model by adding artistic
+styles, special effects, or subjects. By mixing and matching textual
+inversion, LoRA and ControlNet models, you can achieve many
+interesting and beautiful effects.
+
+We will give an example using a LoRA model named "Ink Scenery". This
+LoRA, which can be downloaded from Civitai (civitai.com), is
+specialized to paint landscapes that look like they were made with
+dripping india ink. To install this LoRA, we first download it and 
+put it into the `autoimport/lora` folder located inside the
+`invokeai` root directory. After restarting the web server, the
+LoRA will now become available for use.
+
+To see this LoRA at work, we'll first generate an image without it
+using the standard `stable-diffusion-v1-5` model. Choose this
+model and enter the prompt "mountains, ink". Here is a typical
+generated image, a mountain range rendered in ink and watercolor
+wash:
+
+![Ink Scenery without LoRA](../assets/lora-example-0.png){ width=512px }
+
+Now let's install and activate the Ink Scenery LoRA. Go to
+https://civitai.com/models/78605/ink-scenery-or and download the LoRA
+model file to `invokeai/autoimport/lora` and restart the web
+server. (Alternatively, you can use [InvokeAI's Web Model
+Manager](../installation/050_INSTALLING_MODELS.md) to download and
+install the LoRA directly by typing its URL into the _Import
+Models_->_Location_ field).
+
+Scroll down the control panel until you get to the LoRA accordion
+section, and open it:
+
+![LoRA Section](../assets/lora-example-1.png){ width=512px }
+
+Click the popup menu and select "Ink scenery". (If it isn't there, then
+the model wasn't installed to the right place, or perhaps you forgot
+to restart the web server.) The LoRA section will change to look like this:
+
+![LoRA Section Loaded](../assets/lora-example-2.png){ width=512px }
+
+Note that there is now a slider control for _Ink scenery_. The slider
+controls how much influence the LoRA model will have on the generated
+image.
+
+Run the "mountains, ink" prompt again and observe the change in style:
+
+![Ink Scenery](../assets/lora-example-3.png){ width=512px }
+
+Try adjusting the weight slider for larger and smaller weights and
+generate the image after each adjustment. The higher the weight, the
+more influence the LoRA will have.
+
+To remove the LoRA completely, just click on its trash can icon.
+
+Multiple LoRAs can be added simultaneously and combined with textual
+inversions and ControlNet models. Please see [Textual Inversions and
+LoRAs](CONCEPTS.md) and [Using ControlNet](CONTROLNET.md) for details.
+
+## Summary
+
+This walkthrough just skims the surface of the many things InvokeAI
+can do. Please see [Features](index.md) for more detailed reference
+guides.
+
+## Acknowledgements
+
+A huge shout-out to the core team working to make the Web GUI a reality,
+including [psychedelicious](https://github.com/psychedelicious),
+[Kyle0654](https://github.com/Kyle0654) and
+[blessedcoolant](https://github.com/blessedcoolant).
+[hipsterusername](https://github.com/hipsterusername) was the team's unofficial
+cheerleader and added tooltips/docs.

docs/features/WEBUIHOTKEYS.md

@@ -0,0 +1,75 @@
+---
+title: WebUI Hotkey List
+---
+
+# :material-keyboard: **WebUI Hotkey List**
+
+## App Hotkeys
+
+| Setting         | Hotkey             |
+| --------------- | ------------------ |
+| ++ctrl+enter++  | Invoke             |
+| ++shift+x++     | Cancel             |
+| ++alt+a++       | Focus Prompt       |
+| ++o++           | Toggle Options     |
+| ++shift+o++     | Pin Options        |
+| ++z++           | Toggle Viewer      |
+| ++g++           | Toggle Gallery     |
+| ++f++           | Maximize Workspace |
+| ++1++ - ++5++   | Change Tabs        |
+| ++"`"++         | Toggle Console     |
+
+## General Hotkeys
+
+| Setting        | Hotkey                 |
+| -------------- | ---------------------- |
+| ++p++          | Set Prompt             |
+| ++s++          | Set Seed               |
+| ++a++          | Set Parameters         |
+| ++shift+r++    | Restore Faces          |
+| ++shift+u++    | Upscale                |
+| ++i++          | Show Info              |
+| ++shift+i++    | Send To Image To Image |
+| ++del++        | Delete Image           |
+| ++esc++        | Close Panels           |
+
+## Gallery Hotkeys
+
+| Setting               | Hotkey                      |
+| ----------------------| --------------------------- |
+| ++arrow-left++        | Previous Image              |
+| ++arrow-right++       | Next Image                  |
+| ++shift+g++           | Toggle Gallery Pin          |
+| ++shift+arrow-up++    | Increase Gallery Image Size |
+| ++shift+arrow-down++  | Decrease Gallery Image Size |
+
+## Unified Canvas Hotkeys
+
+| Setting                           | Hotkey                 |
+| --------------------------------- | ---------------------- |
+| ++b++                             | Select Brush           |
+| ++e++                             | Select Eraser          |
+| ++bracket-left++                  | Decrease Brush Size    |
+| ++bracket-right++                 | Increase Brush Size    |
+| ++shift+bracket-left++            | Decrease Brush Opacity |
+| ++shift+bracket-right++           | Increase Brush Opacity |
+| ++v++                             | Move Tool              |
+| ++shift+f++                       | Fill Bounding Box      |
+| ++del++ / ++backspace++           | Erase Bounding Box     |
+| ++c++                             | Select Color Picker    |
+| ++n++                             | Toggle Snap            |
+| ++"Hold Space"++                  | Quick Toggle Move      |
+| ++q++                             | Toggle Layer           |
+| ++shift+c++                       | Clear Mask             |
+| ++h++                             | Hide Mask              |
+| ++shift+h++                       | Show/Hide Bounding Box |
+| ++shift+m++                       | Merge Visible          |
+| ++shift+s++                       | Save To Gallery        |
+| ++ctrl+c++                        | Copy To Clipboard      |
+| ++shift+d++                       | Download Image         |
+| ++ctrl+z++                        | Undo                   |
+| ++ctrl+y++ / ++ctrl+shift+z++     | Redo                   |
+| ++r++                             | Reset View             |
+| ++arrow-left++                    | Previous Staging Image |
+| ++arrow-right++                   | Next Staging Image     |
+| ++enter++                         | Accept Staging Image   |

docs/features/database.md

@@ -1,31 +0,0 @@
----
-title: Database
----
-
-Invoke uses a SQLite database to store image, workflow, model, and execution data.
-
-We take great care to ensure your data is safe, by utilizing transactions and a database migration system.
-
-Even so, when testing a prerelease version of the app, we strongly suggest either backing up your database or using an in-memory database. This ensures any prelease hiccups or databases schema changes will not cause problems for your data.
-
-## Database Backup
-
-Backing up your database is very simple. Invoke's data is stored in an `$INVOKEAI_ROOT` directory - where your `invoke.sh`/`invoke.bat` and `invokeai.yaml` files live.
-
-To back up your database, copy the `invokeai.db` file from `$INVOKEAI_ROOT/databases/invokeai.db` to somewhere safe.
-
-If anything comes up during prelease testing, you can simply copy your backup back into `$INVOKEAI_ROOT/databases/`.
-
-## In-Memory Database
-
-SQLite can run on an in-memory database. Your existing database is untouched when this mode is enabled, but your existing data won't be accessible.
-
-This is very useful for testing, as there is no chance of a database change modifying your "physical" database.
-
-To run Invoke with a memory database, edit your `invokeai.yaml` file and add `use_memory_db: true`:
-
-```yaml
-use_memory_db: true
-```
-
-Delete this line (or set it to `false`) to use your main database.

docs/features/gallery.md

@@ -1,92 +0,0 @@
----
-title: InvokeAI Gallery Panel
----
-
-# :material-web: InvokeAI Gallery Panel
-
-## Quick guided walkthrough of the Gallery Panel's features
-
-The Gallery Panel is a fast way to review, find, and make use of images you've
-generated and loaded. The Gallery is divided into Boards. The Uncategorized board is always 
-present but you can create your own for better organization.
-
-![image](../assets/gallery/gallery.png)
-
-### Board Display and Settings
-
-At the very top of the Gallery Panel are the boards disclosure and settings buttons.
-
-![image](../assets/gallery/top_controls.png)
-
-The disclosure button shows the name of the currently selected board and allows you to show and hide the board thumbnails (shown in the image below).
-
-![image](../assets/gallery/board_thumbnails.png)
-
-The settings button opens a list of options.
-
-![image](../assets/gallery/board_settings.png)
-
-- ***Image Size*** this slider lets you control the size of the image previews (images of three different sizes).
-- ***Auto-Switch to New Images*** if you turn this on, whenever a new image is generated, it will automatically be loaded into the current image panel on the Text to Image tab and into the result panel on the [Image to Image](IMG2IMG.md) tab. This will happen invisibly if you are on any other tab when the image is generated.
-- ***Auto-Assign Board on Click*** whenever an image is generated or saved, it always gets put in a board. The board it gets put into is marked with AUTO (image of board marked). Turning on Auto-Assign Board on Click will make whichever board you last selected be the destination when you click Invoke. That means you can click Invoke, select a different board, and then click Invoke again and the two images will be put in two different boards. (bold)It's the board selected when Invoke is clicked that's used, not the board that's selected when the image is finished generating.(bold) Turning this off, enables the Auto-Add Board drop down which lets you set one specific board to always put generated images into. This also enables and disables the Auto-add to this Board menu item described below.
-- ***Always Show Image Size Badge*** this toggles whether to show image sizes for each image preview (show two images, one with sizes shown, one without)
-
-Below these two buttons, you'll see the Search Boards text entry area. You use this to search for specific boards by the name of the board.
-Next to it is the Add Board (+) button which lets you add new boards. Boards can be renamed by clicking on the name of the board under its thumbnail and typing in the new name.
-
-### Board Thumbnail Menu
-
-Each board has a context menu (ctrl+click / right-click).
-
-![image](../assets/gallery/thumbnail_menu.png)
-
-- ***Auto-add to this Board*** if you've disabled Auto-Assign Board on Click in the board settings, you can use this option to set this board to be where new images are put.
-- ***Download Board*** this will add all the images in the board into a zip file and provide a link to it in a notification (image of notification)
-- ***Delete Board*** this will delete the board
-> [!CAUTION]
-> This will delete all the images in the board and the board itself.
-
-### Board Contents
-
-Every board is organized by two tabs, Images and Assets.
-
-![image](../assets/gallery/board_tabs.png)
-
-Images are the Invoke-generated images that are placed into the board. Assets are images that you upload into Invoke to be used as an [Image Prompt](https://support.invoke.ai/support/solutions/articles/151000159340-using-the-image-prompt-adapter-ip-adapter-) or in the [Image to Image](IMG2IMG.md) tab.
-
-### Image Thumbnail Menu
-
-Every image generated by Invoke has its generation information stored as text inside the image file itself. This can be read directly by selecting the image and clicking on the Info button ![image](../assets/gallery/info_button.png) in any of the image result panels. 
-
-Each image also has a context menu (ctrl+click / right-click).
-
-![image](../assets/gallery/image_menu.png)
-
- The options are (items marked with an * will not work with images that lack generation information):
-- ***Open in New Tab*** this will open the image alone in a new browser tab, separate from the Invoke interface.
-- ***Download Image*** this will trigger your browser to download the image.
-- ***Load Workflow **** this will load any workflow settings into the Workflow tab and automatically open it.
-- ***Remix Image **** this will load all of the image's generation information, (bold)excluding its Seed, into the left hand control panel
-- ***Use Prompt **** this will load only the image's text prompts into the left-hand control panel
-- ***Use Seed **** this will load only the image's Seed into the left-hand control panel
-- ***Use All **** this will load all of the image's generation information into the left-hand control panel
-- ***Send to Image to Image*** this will put the image into the left-hand panel in the Image to Image tab and automatically open it
-- ***Send to Unified Canvas*** This will (bold)replace whatever is already present(bold) in the Unified Canvas tab with the image and automatically open the tab
-- ***Change Board*** this will oipen a small window that will let you move the image to a different board. This is the same as dragging the image to that board's thumbnail.
-- ***Star Image*** this will add the image to the board's list of starred images that are always kept at the top of the gallery. This is the same as clicking on the star on the top right-hand side of the image that appears when you hover over the image with the mouse
-- ***Delete Image*** this will delete the image from the board
-> [!CAUTION] 
-> This will delete the image entirely from Invoke.
-
-## Summary
-
-This walkthrough only covers the Gallery interface and Boards. Actually generating images is handled by [Prompts](PROMPTS.md), the [Image to Image](IMG2IMG.md) tab, and the [Unified Canvas](UNIFIED_CANVAS.md).
-
-## Acknowledgements
-
-A huge shout-out to the core team working to make the Web GUI a reality,
-including [psychedelicious](https://github.com/psychedelicious),
-[Kyle0654](https://github.com/Kyle0654) and
-[blessedcoolant](https://github.com/blessedcoolant).
-[hipsterusername](https://github.com/hipsterusername) was the team's unofficial
-cheerleader and added tooltips/docs.

docs/features/index.md

@@ -0,0 +1,59 @@
+---
+title: Overview
+---
+
+Here you can find the documentation for InvokeAI's various features.
+
+## The [Getting Started Guide](../help/gettingStartedWithAI) 
+A getting started guide for those new to AI image generation. 
+
+## The Basics
+### * The [Web User Interface](WEB.md)
+Guide to the Web interface. Also see the [WebUI Hotkeys Reference Guide](WEBUIHOTKEYS.md)
+
+### * The [Unified Canvas](UNIFIED_CANVAS.md)
+Build complex scenes by combine and modifying multiple images in a stepwise
+fashion. This feature combines img2img, inpainting and outpainting in
+a single convenient digital artist-optimized user interface.
+
+## Image Generation
+### * [Prompt Engineering](PROMPTS.md)
+Get the images you want with the InvokeAI  prompt engineering language.
+
+### * The [LoRA, LyCORIS and Textual Inversion Models](CONCEPTS.md)
+Add custom subjects and styles using a variety of fine-tuned models.
+
+### * [ControlNet](CONTROLNET.md)
+Learn how to install and use ControlNet models for fine control over
+image output.
+
+### * [Image-to-Image Guide](IMG2IMG.md)
+Use a seed image to build new creations in the CLI.
+
+## Model Management
+
+### * [Model Installation](../installation/050_INSTALLING_MODELS.md)
+Learn how to import third-party models and switch among them. This
+guide also covers optimizing models to load quickly.
+
+### * [Merging Models](MODEL_MERGING.md)
+Teach an old model new tricks. Merge 2-3 models together to create a
+new model that combines characteristics of the originals.
+
+### * [Textual Inversion](TRAINING.md)
+Personalize models by adding your own style or subjects.
+
+## Other Features
+
+### * [The NSFW Checker](WATERMARK+NSFW.md)
+Prevent InvokeAI from displaying unwanted racy images.
+
+### * [Controlling Logging](LOGGING.md)
+Control how InvokeAI logs status messages.
+
+<!-- OUT OF DATE
+### * [Miscellaneous](OTHER.md)
+Run InvokeAI on Google Colab, generate images with repeating patterns,
+batch process a file of prompts, increase the "creativity" of image
+generation by adding initial noise, and more!
+-->

docs/help/deprecated/TROUBLESHOOT.md

@@ -0,0 +1,128 @@
+---
+title: F.A.Q.
+---
+
+# :material-frequently-asked-questions: F.A.Q.
+
+## **Frequently-Asked-Questions**
+
+Here are a few common installation problems and their solutions. Often these are
+caused by incomplete installations or crashes during the install process.
+
+---
+
+### During `conda env create`, conda hangs indefinitely
+
+If it is because of the last PIP step (usually stuck in the Git Clone step, you
+can check the detailed log by this method):
+
+```bash
+export PIP_LOG="/tmp/pip_log.txt"
+touch ${PIP_LOG}
+tail -f ${PIP_LOG} &
+conda env create -f environment-mac.yaml --debug --verbose
+killall tail
+rm ${PIP_LOG}
+```
+
+**SOLUTION**
+
+Conda sometimes gets stuck at the last PIP step, in which several git
+repositories are cloned and built.
+
+Enter the stable-diffusion directory and completely remove the `src` directory
+and all its contents. The safest way to do this is to enter the stable-diffusion
+directory and give the command `git clean -f`. If this still doesn't fix the
+problem, try "conda clean -all" and then restart at the `conda env create` step.
+
+To further understand the problem to checking the install lot using this method:
+
+```bash
+export PIP_LOG="/tmp/pip_log.txt"
+touch ${PIP_LOG}
+tail -f ${PIP_LOG} &
+conda env create -f environment-mac.yaml --debug --verbose
+killall tail
+rm ${PIP_LOG}
+```
+
+---
+
+### `invoke.py` crashes with the complaint that it can't find `ldm.simplet2i.py`
+
+Or it complains that function is being passed incorrect parameters.
+
+**SOLUTION**
+
+Reinstall the stable diffusion modules. Enter the `stable-diffusion` directory
+and give the command `pip install -e .`
+
+---
+
+### Missing modules
+
+`invoke.py` dies, complaining of various missing modules, none of which starts
+with `ldm`.
+
+**SOLUTION**
+
+From within the `InvokeAI` directory, run `conda env update` This is also
+frequently the solution to complaints about an unknown function in a module.
+
+---
+
+### How can I try new features
+
+There's a feature or bugfix in the Stable Diffusion GitHub that you want to try
+out.
+
+**SOLUTIONS**
+
+#### **Main Branch**
+
+If the fix/feature is on the `main` branch, enter the stable-diffusion directory
+and do a `git pull`.
+
+Usually this will be sufficient, but if you start to see errors about missing or
+incorrect modules, use the command `pip install -e .` and/or `conda env update`
+(These commands won't break anything.)
+
+`pip install -e .` and/or `conda env update -f environment.yaml`
+
+(These commands won't break anything.)
+
+#### **Sub Branch**
+
+If the feature/fix is on a branch (e.g. "_foo-bugfix_"), the recipe is similar,
+but do a `git pull <name of branch>`.
+
+#### **Not Committed**
+
+If the feature/fix is in a pull request that has not yet been made part of the
+main branch or a feature/bugfix branch, then from the page for the desired pull
+request, look for the line at the top that reads "_xxxx wants to merge xx
+commits into lstein:main from YYYYYY_". Copy the URL in YYYY. It should have the
+format
+
+`https://github.com/<name of contributor>/stable-diffusion/tree/<name of branch>`
+
+Then **go to the directory above stable-diffusion** and rename the directory to
+"_stable-diffusion.lstein_", "_stable-diffusion.old_", or anything else. You can
+then git clone the branch that contains the pull request:
+
+`git clone https://github.com/<name of contributor>/stable-diffusion/tree/<name of branch>`
+
+You will need to go through the install procedure again, but it should be fast
+because all the dependencies are already loaded.
+
+---
+
+### CUDA out of memory
+
+Image generation crashed with CUDA out of memory error after successful
+sampling.
+
+**SOLUTION**
+
+Try to run script with option `--free_gpu_mem` This will free memory before
+image decoding step.