Imported from UselessToys/Ecosystem_WebUI (AGENTS.md). Install upstream with npx skills add UselessToys/Ecosystem_WebUI. Copyright stays with the author.

AGENTS.md — Project Guide for AI Coding Agents

This is the primary reference for any AI agent working in this repository. Agent-specific files (CLAUDE.md, GEMINI.md, QWEN.md) point here and add per-agent notes on top.

CRITICAL RULES — Read These First

This is a WEB UI Project (NOT Jupyter Notebooks)

This project uses FastAPI + Next.js for the interface, not Jupyter notebooks.

• NO .ipynb files, notebook cells, or ipywidgets — ever
• YES FastAPI backend (Python) + Next.js frontend (React/TypeScript)
• Access via web browser at http://localhost:3000
• If you see references to "notebooks" or "Jupyter" in existing code, they are outdated

Vendored Backend — No Submodules

trainer/derrian_backend/ is committed directly into the repository.

• DO treat it as regular source code
• DO NOT run git submodule commands — there are no submodules
• DO NOT add git submodules to this repository
• TRY NOT TO modify vendored backend files casually, but editing them to fix or improve something we need is expected — we carry a live patch-set on this tree (see upstream_sync_methodology). Preserve existing patches when you touch it.

Do Not Change Server Bindings

Do not change 0.0.0.0 to localhost or 127.0.0.1:

uvicorn.run(app, host="0.0.0.0", port=8000)  # correct — leave as-is

This application deploys to VastAI and RunPod cloud GPU instances. 0.0.0.0 is required for external access. Security is handled by the platform firewall and Cloudflare proxy. Do not change this even if a security scanner flags it.

Do Not Modify Git Remotes

Never run commands that change remote configuration:

# Never run:
git remote set-url origin ...
git remote add ...
git remote remove ...

Do Not Create Audit Files

Do not create markdown audit files (API_AUDIT.md, ENDPOINT_AUDIT.md, etc.) unless the user specifically asks for one. Report findings directly in the conversation instead.

Repository Overview

A web-based LoRA training environment for training LoRA models for Stable Diffusion image generation. Uses a FastAPI backend and Next.js frontend, designed to run cross-platform.

Architecture: FastAPI (Python) + Next.js 15 (React/TypeScript) + Kohya SS

Deployment targets (all equally supported):

• Windows local — primary development environment; code must work here first
• VastAI — Linux cloud GPU instances with auto-provisioning and supervisor
• RunPod — Linux cloud GPU instances via provision_runpod.sh
• Training requirement — NVIDIA GPU with CUDA 12.1+

Not supported: macOS. Do not write Mac-specific code or instructions.

Key Components

Backend — api/

FastAPI route handlers:

Deprecated routes (code moved to *deprecated/ but endpoints still work): | POST /checkpoint/merge-weighted | services/deprecated/block_weight_merge.py | | POST /lora/merge-to-checkpoint (Anima bake) | custom/deprecated/anima_merge_lora.py |

Service Layer — services/

Business logic. Route handlers call services; services call the training backend. Never call Kohya scripts directly from routes.

Frontend — frontend/

Next.js 15 with React 19, TypeScript, and Tailwind CSS v4.

All backend communication goes through frontend/lib/api.ts. Do not fetch the backend directly from components.

Training Backend — trainer/derrian_backend/

Vendored Kohya SS distribution (committed directly, not a submodule):

Startup Scripts

Development Commands

Installation

# Linux
chmod +x ./install.sh && ./install.sh

# Windows
install.bat

# Or directly
python installer.py

Start the Application

Linux:

chmod +x ./start_services_local.sh
./start_services_local.sh

Windows:

start_services_local.bat

Access:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Run Tests

pip install -r requirements_dev.txt
pytest tests/test_api_plumbing.py -v

Tests are GPU-free and mock all ML dependencies. tests/conftest.py stubs missing production packages so tests run without the full venv.

Platform and Path Rules

• Never hardcode paths — use sys.executable and os.path.join()
• Primary dev OS is Windows 10 — do not write Unix-only solutions
• Deploy target is Linux (VastAI / RunPod) — code must work on both
• Do not target macOS — not a supported platform
• Use asyncio.create_subprocess_exec for async subprocesses (not subprocess.Popen with shell)
• api/main.py sets asyncio.WindowsProactorEventLoopPolicy() on Windows — do not remove

Configuration System

Training uses two TOML files generated by the backend API:

• trainer/runtime_store/dataset.toml — dataset config (paths, resolution, batch size)
• trainer/runtime_store/config.toml — training hyperparameters

These are auto-generated from web UI form inputs. Check git history before modifying TOML generation logic — mistakes here affect real training runs.

Frontend Rules

Use shadcn/ui Components — Mandatory

Never use raw HTML form elements. This project uses shadcn/ui for all UI:

TypeScript and Patterns

• TypeScript everywhere — no plain .js files in frontend/
• Use the @/ path alias, not relative paths
• Mark components that use hooks or browser APIs with 'use client'
• Prefer server components when no client-side features are needed
• Accessibility is mandatory — semantic HTML, keyboard navigation, ARIA attributes

Code Quality Rules

• Complete functions — never leave methods incomplete during refactoring
• Preserve all functionality — UI changes are fine; business logic must stay intact
• Reference old code when refactoring — compare with working versions before changing
• Ask before removing — if unsure about a method's purpose, ask rather than delete
• Refactor incrementally — test each step; do not do massive changes at once
• Compare method counts before and after large refactors to catch missing functions
• Add docstrings inline — when writing or modifying a function, update its docstring then and there

What NOT to Do

• Add Jupyter references to any file
• Run git submodule commands
• Modify git remotes
• Change 0.0.0.0 server bindings
• Hardcode absolute paths
• Write macOS-only or Unix-only code
• Edit trainer/derrian_backend/ without explicit instruction
• Add platform-specific npm packages directly (causes EBADPLATFORM on other OSes)
• Create markdown audit files unless explicitly asked
• Create new code in custom/ or services/deprecated/ — these directories are for legacy reference only
• Remove files from custom/deprecated/ or services/deprecated/ without explicit instruction

Supported Model Types

• Stable Diffusion 1.5 (LoRA, LoCon, LoHa, LoKR)
• SDXL (LoRA, LoCon, LoHa, LoKR)
• Flux (experimental)
• SD 3.5 (experimental)

Not yet supported: Qwen Image LoRA — the vendored sd-scripts has the autoencoder but no training script. Do not add UI for it until upstream ships the training script.

Current Status

• Backend refactored to use Kohya's library system with strategy pattern
• Frontend ~99% migrated to Next.js 15 + React 19 routes
• Core training functionality works; in beta / bug-squashing phase
• Flux and SD3 should work based on Kohya backend; needs real-world testing
• Chattiori integration (Phase 1 complete): Vendored trainer/chattiori/, service layer, API endpoints (POST /checkpoint/merge-advanced, POST /lora/bake-chattiori), and frontend API functions. Old block-weight merge code moved to services/deprecated/.