1580158
/
automatic
mirror of https://github.com/vladmandic/automatic
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
automatic/.github/copilot-instructions.md

5.8 KiB
Raw Blame History

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.

Repo-Local Skills

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.

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