automatic/.github/copilot-instructions.md

SD.Next: AGENTS.md Project Guidelines

SD.Next is a complex codebase with specific patterns and conventions. General app structure is:

• Python backend server
  Uses Torch for model inference, FastAPI for API routes and Gradio for creation of UI components.
• JavaScript/CSS frontend

Tools

• venv for Python environment management, activated with source venv/bin/activate (Linux) or venv\Scripts\activate (Windows).
  venv MUST be activated before running any Python commands or scripts to ensure correct dependencies and environment variables.
• python 3.10+.
• pyproject.toml for Python configuration, including linting and type checking settings.
• eslint configured for both core and UI code.
• pnpm for managing JavaScript dependencies and scripts, with key commands defined in package.json.
• ruff and pylint for Python linting, with configurations in pyproject.toml and executed via pnpm ruff and pnpm pylint.
• pre-commit hooks which also check line-endings and other formatting issues, configured in .pre-commit-config.yaml.

Project Structure

• Entry/startup flow: webui.sh -> launch.py -> webui.py -> modules under modules/.
• Install: installer.py takes care of installing dependencies and setting up the environment.
• Core runtime state is centralized in modules/shared.py (shared.opts, model state, backend/device state).
• API/server routes are under modules/api/.
• UI codebase is split between base JS in javascript/ and actual UI in extensions-builtin/sdnext-modernui/.
• Model and pipeline logic is split between modules/sd_* and pipelines/.
• Additional plug-ins live in scripts/ and are used only when specified.
• Extensions live in extensions-builtin/ and extensions/ and are loaded dynamically.
• Tests and CLI scripts are under test/ and cli/, with some API smoke checks in test/full-test.sh.

Code Style

• Prefer existing project patterns over strict generic style rules;
  this codebase intentionally allows patterns often flagged in default linters such as allowing long lines, etc.

Build And Test

• Activate environment: source venv/bin/activate (always ensure this is active when working with Python code).
• Test startup: python launch.py --test
• Full startup: python launch.py
• Full lint sequence: pnpm lint
• Python checks individually: pnpm ruff, pnpm pylint
• JS checks: pnpm eslint and pnpm eslint-ui

Conventions

• Keep PR-ready changes targeted to dev branch.
• Use conventions from CONTRIBUTING.
• Do not include unrelated edits or submodule changes when preparing contributions.
• Use existing CLI/API tool patterns in cli/ and test/ when adding automation scripts.
• Respect environment-driven behavior (SD_* flags and options) instead of hardcoding platform/model assumptions.
• For startup/init edits, preserve error handling and partial-failure tolerance in parallel scans and extension loading.

Pitfalls

• Initialization order matters: startup paths in launch.py and webui.py are sensitive to import/load timing.
• Shared mutable global state can create subtle regressions; prefer narrow, explicit changes.
• Device/backend-specific code paths (CUDA/ROCm/IPEX/DirectML/OpenVINO) should not assume one platform.
• Scripts and extension loading is dynamic; failures may appear only when specific extensions or models are present.

File Creation

• Any temporary scripts or markdown reports must be stored in tmp/ folder
• Any reusable test scripts must be stored in test/ folder

Repo-Local Skills

All skills are defined in .github/skills/ and indexed in .github/skills/README.md. Use these repo-local skills for recurring SD.Next model integration work:

• port-model
  File: .github/skills/port-model/SKILL.md
  Use when adding a new model family, porting a standalone script into a Diffusers pipeline, or wiring an upstream Diffusers model into SD.Next.

• debug-model
  File: .github/skills/debug-model/SKILL.md
  Use when a new or existing SD.Next/Diffusers model integration fails during detection, loading, prompt encoding, sampling, or output handling.

• check-api
  File: .github/skills/check-api/SKILL.md
  Use when auditing API routes in modules/api/api.py and validating endpoint parameters plus request/response signatures.

• check-schedulers
  File: .github/skills/check-schedulers/SKILL.md
  Use when auditing scheduler registrations in modules/sd_samplers_diffusers.py for class loadability, config validity, and SamplerData mapping correctness.

• check-models
  File: .github/skills/check-models/SKILL.md
  Use when running end-to-end model integration audits across loaders, detect/routing parity, reference catalogs, and pipeline API contracts.

• check-processing
  File: .github/skills/check-processing/SKILL.md
  Use when validating txt2img/img2img/control processing workflows from UI submit definitions through backend processing and Diffusers execution, including parameter, type, and initialization checks.

• check-scripts
  File: .github/skills/check-scripts/SKILL.md
  Use when auditing scripts in scripts/*.py for standard Script overrides (__init__, title, show) and validating ui() output against run() or process() parameters.

• github-issues
  File: .github/skills/github-issues/SKILL.md
  Use when reading SD.Next GitHub issues with [Issues] in title and producing a markdown report with short summary, status, and suggested next steps for each issue.

• github-features
  File: .github/skills/github-features/SKILL.md
  Use when reading SD.Next GitHub issues with [Feature] in title and producing a markdown report with short summary, status, and suggested next steps for each issue.

• analyze-model
  File: .github/skills/analyze-model/SKILL.md
  Use when analyzing an external model URL to identify implementation style and estimate how difficult it is to port into SD.Next.

• diffusers-code
  File: .github/skills/diffusers-code/SKILL.md
  Use when creating or editing code that must comply with Hugging Face diffusers conventions, including preparing PR-ready changes targeting diffusers.

• reference-catalog
  File: .github/skills/reference-catalog/SKILL.md
  Use when maintaining and validating model reference catalogs in data/reference*.json, including duplicate checks and thumbnail alignment.

• fix-lint
  File: .github/skills/fix-lint/SKILL.md
  Use when running the full lint workflow in required order (pre-commit, eslint, ruff, pylint) and fixing findings as needed, while ignoring lint issues explicitly marked with TODO.

• todo
  File: .github/skills/todo/SKILL.md
  Use when searching the full codebase for TODO markers and producing a markdown document with proposed next steps for each item.

When creating and updating skills, update this file and the index in .github/skills/README.md accordingly.