ScaleForge

Fast, portable AI upscaler/resizer powered by Real-ESRGAN — with smart GPU detection and a single pipeline for CLI and GUI.

---

Why ScaleForge?

• Smart backend selection with fallbacks:
  • NVIDIA → PyTorch CUDA
  • AMD (Linux ROCm-capable) → PyTorch ROCm
  • Intel/AMD (no CUDA/ROCm) → NCNN/Vulkan
  • Else → PyTorch CPU
• No-drama install (venv or portable build).
• Model manager: list, fetch, cache, resume.
• One simple CLI with a single pipeline.
• Works in a venv; friendly to CI.
• Batteries included: tiny sample + CPU-only demo to verify your setup (no GPU toolchains required).

---

Quick start (from source)

# 1) Clone and enter
git clone https://github.com/3-0-0/ScaleForge.git
cd ScaleForge

# 2) Create an isolated env (Python 3.10–3.12)
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows (PowerShell)
# .\.venv\Scripts\Activate.ps1

# 3) Install
pip install -U pip
pip install -e ".[demo]" pytest

GUI

To use the graphical interface, install the optional GUI dependencies:

pip install -e ".[gui]"

This pulls in Kivy and Watchdog for desktop UI and file-system monitoring.

---

GPU Detection & Capability Cache

ScaleForge automatically detects your GPU capabilities and caches the results for optimal performance.

• Cache location: ${APP_ROOT}/gpu_caps.json

• Key information:

  • GPU vendor (Nvidia / AMD / Intel)
  • Recommended backend (e.g. torch-eager-cuda, torch-eager-rocm, torch-eager-cpu, ncnn-ncnn-vulkan)
  • Performance capabilities (e.g., max tile size, megapixels)
  • Detection timestamp

Commands

# Show current backend choice
scaleforge detect-backend

# Force a fresh probe / show details
scaleforge detect-backend --debug

Backends & env overrides

Canonical backend IDs include cpu-pillow, torch-eager-cpu, torch-eager-cuda, torch-eager-rocm, torch-eager-mps, and ncnn-ncnn-vulkan.

Set SCALEFORGE_BACKEND to force one of these; use SCALEFORGE_DEVICE to override only the device portion during auto-detect.

---

CLI overview

scaleforge --help

Main commands implemented today:

• detect-backend — detect/print the selected backend (see above)
• run — run the pipeline (options vary by build)
• demo upscale — Pillow-only single image upscale (CPU)

---

Demo (Pillow-only)

A quick CPU-only way to try ScaleForge without GPU toolchains.

# Single image
python -m scaleforge.cli demo upscale --in input.png --out out@2x.png --scale 2

See docs/DEMO.md for more examples and notes on --mode, --suffix, --include/--exclude, --limit, --overwrite, --dry-run, and debug output.

---

Roadmap (short)

• Backend fallback polish & logging ✅
• Demo CLI (demo upscale) ✅
• Docs site & richer examples ⏳
• Packaging improvements and presets ⏳

---

Development

# Lint / tests (if configured in your environment)
pytest -q

Project layout:

src/            # library + CLI
tests/          # unit tests (demo tests included)
docs/           # docs/DEMO.md quickstart

---

Contributing

Issues and PRs welcome! Please keep diffs minimal and add tests when behavior changes.

---

📜 CREDITS

🧠 Core Contributors

• 300
  Project creator, visionary, and development lead; coordinated AI-agent workflows and oversaw project management.

• Nexus (ChatGPT)
  Partner AI; architectural co-designer & planner, strategic guidance, troubleshooting, documentation, and quality assurance.
  → Powered by GPT-5, GPT-4o, GPT-4.5, GPT-4-turbo (o3), and o4-mini-high from OpenAI.

• OpenHands Agent
  Autonomous software engineer; responsible for the majority of the ScaleForge codebase, including initial backend and frontend implementations.
  → Uses OpenHands runtime with GPT APIs to operate independently.

• Deepseek-Coder
  Auxiliary agent used to reduce compute costs during development.
  → Powered by DeepSeek-Coder 1.5, a distilled model trained on GPT-3.5 and GPT-4 via OpenAI API.

---

⚙️ Upstream Projects & Libraries

ScaleForge is made possible by the incredible open-source ecosystem. Huge thanks to the following projects:

🔮 Image Upscaling

• Real-ESRGAN – super-resolution model for photo-realistic image enhancement, by Xintao Wang et al.
• ncnn – fast neural-network inference framework by Tencent.
• PyTorch – deep-learning framework by Meta AI.

🖼️ UI / Frontend

• Kivy – cross-platform UI framework for Python.

🧪 Tooling & Developer Experience

• ruff – fast Python linter
• black – Python code formatter
• mypy – static type checker
• pytest – unit-testing framework
• mkdocs – documentation generator
• mkdocs-material – beautiful docs theme
• EditorConfig – consistent coding styles across editors

---

🤝 Community Contributions

We welcome feedback, bug reports, and pull requests from the broader community. Join us on GitHub to help improve ScaleForge!

---

🌐 Project Resources

• GitHub Repository: ScaleForge on GitHub
• Documentation: (coming soon) :contentReference[oaicite:7]{index=7}

---

💡 Inspiration

• NASA / JWST Wallpapers – Webb Telescope
• NASA / JWST Wallpapers – Flickr
  The beauty of the cosmos inspired the first use case that led to the creation of ScaleForge.

---

🛠️ Infrastructure & CI/CD

• GitHub Actions – continuous integration and delivery

---

📄 License

ScaleForge is released under the MIT License.

---

🙏 Thanks

To all maintainers, researchers, and contributors—your dedication makes ScaleForge possible.
We stand on your shoulders.