refactor: overhaul architecture for Forge Neo, add ADetailer Neo & Anima (DiT) support, ControlNet handoff, & quality tooling

[soficis]

Summary

This PR merges the refactor branch into main, completing a major architectural overhaul of RanbooruX. The extension is now exclusively targeted at Forge Neo and introduces native support for ADetailer Neo, Anima (2B DiT) models, ControlNet Unit 0 handoff, and the Danbooru Tag Catalog system, backed by a modular ranboorux/ core and automated CI testing.

---

🌟 Key Features & Improvements

1. 🚀 Forge Neo & ADetailer Neo Exclusivity

• Refactored runtime and script discovery (ranboorux/integrations/adetailer_runtime.py, adetailer_orchestration.py) to auto-detect both standard ADetailer and ADetailer Neo scripts at gather and removal stages.
• Added guarded execution to prevent script collisions during multi-pass workflows.

2. 🌀 Anima (2B DiT) Model Support & ControlNet LLLite

• Added auto-detection module (ranboorux/anima_detect.py) for Anima models by filename tokens or architecture metadata.
• Implemented automatic flow-matching scheduler tuning, step caps, resolution defaults, and space-separated tag conversion (_ → spaces) for Qwen3.
• Added Anima ControlNet-LLLite handoff support (anima-lllite-lineart-1, anima-lllite-depth-1, anima-lllite-inpainting-v2).
• Included Auto-tune Img2Img parameters for Anima (anima_tune_img2img) UI toggle allowing manual WebUI sampler overrides when unchecked.

3. 🎯 Forge Neo ControlNet Unit 0 Integration

• Replaced legacy external_code API calls and flat-index hacks with native Forge Neo script runner integration (p.scripts.alwayson_scripts -> ControlNetForForgeOfficial slice).
• Automatically passes fetched booru reference images directly into ControlNet Unit 0.
• Added p.resize_mode = 1 (ResizeMode.INNER_FIT) safeguard to eliminate initial-pass rendering errors.

4. 🏷️ Danbooru Tag Catalog System

• Integrated bundled catalog (data/catalogs/danbooru_tags.csv) supporting alias normalization, category-aware filtering, custom CSV import, and hair/eye color preservation.
• Added UI import, validation, and catalog management controls.

5. 🌐 HTTP Resilience & Gelbooru CDN Fixes

• Fixed Gelbooru image fetching by setting browser-like headers with explicit Referer headers to resolve CDN request blocks.
• Added exponential backoff retry loop (3 attempts: 1s/2s/4s) in _fetch_data() to recover from transient HTTP 5xx errors and connection drops.

6. 🏗️ Modular Package & Quality Tooling

• Refactored monolithic scripts/ranbooru.py into a clean, typed ranboorux/ package.
• Added automated unit tests (pytest), strict type checking (mypy), linting (ruff), and code formatting (black).
• Updated GitHub Actions CI pipeline (.github/workflows/ci.yml) with fetch-depth: 0 and safe.directory "*" to ensure clean automated builds.

---

⚠️ Breaking Changes & Disclaimers

• Forge Neo Exclusive: RanbooruX is now strictly built and tested for Forge Neo. Legacy SD WebUI / A1111 support and Deepbooru have been removed.
• Environment Overrides: Added SD_FORGE_CONTROLNET_PATH and RANBOORUX_CN_PATH env variable overrides for custom ControlNet installations (documented in README).

---

✅ Verification & Testing

• Unit Tests: 187 passing unit tests (python -m pytest tests/ -q).
• Code Quality: Clean checks across ruff, black, and mypy (18 source files).
• Manual Verification: Verified on Forge Neo with Anima (2B DiT) models, ControlNet Unit 0 handoff, and ADetailer Neo postprocessing.

[soficis]

@copilot resolve the merge conflicts in this pull request

[Copilot]

Pull request overview

This PR completes a large refactor that moves RanbooruX from a monolithic script toward a modular ranboorux/ core, adds Forge Neo–specific integrations (ADetailer Neo, ControlNet Unit 0 handoff, Anima model detection/tuning), and introduces CI + local tooling to enforce quality and release hygiene.

Changes:

• Added a typed core package (ranboorux/) covering run options, HTTP hardening, user storage, booru clients, and integration runtimes (ControlNet, Img2Img lifecycle, ADetailer runtime).
• Expanded automated tests to lock UI argument contract ordering, lifecycle invariants, integration behavior, and release hygiene.
• Introduced developer/release tooling (tools/*.py) plus GitHub Actions CI for tests + formatting + linting + type checks.

Reviewed changes

Copilot reviewed 46 out of 51 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tools/verify.py	Adds a local “run the full verification suite” script (tests + ruff/black/mypy).
tools/repo_guard.py	Adds a guard tool to detect forbidden modified paths by mode.
tools/inspect_ui.py	Adds a UI contract extractor tool for Script.ui() positional return order.
tools/build_release.py	Adds an allowlist-based release zip builder with archive hygiene checks.
tests/test_wrappers.py	Updates wrapper tests to match refactored tag pipeline locations.
tests/test_user_store.py	Adds unit coverage for new user storage helpers (credentials, lists, logs, prefs).
tests/test_ui_contract.py	Locks the UI contract length/order via RunComponents + UI_ARGUMENT_FIELDS.
tests/test_tag_pipeline.py	Adds comprehensive unit tests for tag parsing/dedup/filtering/synonyms.
tests/test_tag_catalog.py	Adjusts catalog behavior expectations and adds config-loading coverage.
tests/test_run_options.py	Adds tests that freeze UI argument field order and mapping into RunOptions.
tests/test_requesting.py	Adds extensive HTTP client hardening tests (redaction, SSRF defenses, bounds).
tests/test_repo_guard.py	Adds tests for repo guard behavior with/without git metadata.
tests/test_release_hygiene.py	Adds tests for allowlist staging and archive hygiene rejection rules.
tests/test_prompt_and_parsing.py	Updates tests to use ranboorux modules instead of monolithic wrappers.
tests/test_modules.py	Updates import smoke tests to new module structure (tag_pipeline, user_store).
tests/test_loranado.py	Adds tests for LoRA normalization/selection/formatting helpers.
tests/test_lifecycle_contract.py	Adds lifecycle tests ensuring guards/state cleanup across runs/errors.
tests/test_img2img_lifecycle.py	Adds tests for processed-result replacement helpers.
tests/test_host_state.py	Adds tests for mutation scope restoration and temp-path ownership cleanup.
tests/test_helpers.py	Adds snapshot helper tests for detecting host state leakage.
tests/test_controlnet.py	Expands tests around ControlNet import failure redaction/diagnostics.
tests/test_anima_detect.py	Adds tests for Anima model detection and tuning toggles.
tests/test_adetailer.py	Expands ADetailer integration tests around isolation/guards/manual execution.
tests/test_adetailer_runtime.py	Adds unit tests for the refactored ADetailer runtime utilities.
tests/host_snapshot.py	Introduces helper for capturing host processing state for leak detection.
tests/conftest.py	Extends stubs/mocks for requests + adapters to support new HTTP client behaviors.
README.md	Updates docs to Forge Neo exclusivity and describes new features/tooling/workflows.
ranboorux/user_store.py	Adds user-data storage utilities (atomic write, credential/prefs handling, logs).
ranboorux/run_options.py	Adds frozen UI argument schema and mapping helpers (RunOptions, RunComponents).
ranboorux/prompting.py	Removes legacy prompting module (superseded by tag_pipeline).
ranboorux/mutation_scope.py	Adds mutation scope utilities for safe host state patching/restoration.
ranboorux/loranado.py	Adds LoRA selection utilities with deterministic RNG support.
ranboorux/io_lists.py	Removes legacy list file helpers (superseded by user_store).
ranboorux/integrations/img2img_lifecycle.py	Adds helpers for consistent processed-object result replacement.
ranboorux/integrations/controlnet.py	Refactors ControlNet external_code loading with better redaction/logging.
ranboorux/integrations/adetailer_runtime.py	Adds reusable runtime utilities for ADetailer discovery/isolation/guards.
ranboorux/image_ops.py	Tightens typing for image resize helper signature/return type.
ranboorux/http_client.py	Adds hardened HTTP client (SSRF protections, redaction, bounded streaming, caching rules).
ranboorux/boorus/simple.py	Adds config-driven simple booru subclasses.
ranboorux/boorus/gelbooru.py	Adds Gelbooru + Gelbooru-compatible implementations with retry/diagnostics.
ranboorux/boorus/init.py	Adds shared Booru base class with fetch + standardization logic.
ranboorux/anima_detect.py	Adds Anima model detection utilities.
pyproject.toml	Updates mypy config (e.g., follow_imports=skip).
.gitignore	Updates ignore patterns for tooling/user data.
.github/workflows/ci.yml	Adds CI workflow running tests on 3.10–3.12 plus ruff/black/mypy checks.

Comments suppressed due to low confidence (2)

ranboorux/boorus/simple.py:240

• base_api_url already contains ?limit=..., but get_posts() appends ?page=... which results in an invalid query string (two ?). This should be &page=....

        page = random.randint(1, max_pages)
        query_url = f"{self.base_api_url}?page={page}{tags_query}"
        fetched_data = self._fetch_data(query_url)

tools/inspect_ui.py:231

• The contract text written to docs/handoff/UI_ARGUMENT_CONTRACT.md still claims there are 62 positional arguments, but Script.ui() and UI_ARGUMENT_FIELDS define 64. The generated docs should reflect the correct frozen contract size.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved in commit 8a8be80 by merging main into refactor and fixing all merge conflicts.