From 0ee5fb2c25f48ad21342a07ee9dd482c88c07e7e Mon Sep 17 00:00:00 2001
From: xavix-yo <daniele.guiducci@gmail.com>
Date: Tue, 21 Jul 2026 00:26:34 +0100
Subject: [PATCH] Move heavy GPU deps (torch, bitsandbytes) to
 requirements-optional.txt

torch and bitsandbytes pull in hundreds of MB of CUDA libraries
(nvidia_cublas ~423 MB) which are useless on headless servers
without an NVIDIA GPU like the NiPoGi.

- requirements.txt: keep only lightweight essential dependencies
- requirements-optional.txt (new): Orpheus TTS deps (torch, transformers,
  bitsandbytes, snac, huggingface_hub)
- Installers and update.sh: show hint about optional deps after install
- ci/package.sh: include requirements-optional.txt in tarball
---
 ci/package.sh             |  4 +++-
 install-nightly.sh        |  9 +++++++++
 install.sh                |  9 +++++++++
 requirements-optional.txt | 13 +++++++++++++
 requirements.txt          |  8 ++------
 update.sh                 |  9 +++++++++
 6 files changed, 45 insertions(+), 7 deletions(-)
 create mode 100644 requirements-optional.txt

diff --git a/ci/package.sh b/ci/package.sh
index 98fed42..d4696b6 100755
--- a/ci/package.sh
+++ b/ci/package.sh
@@ -17,7 +17,8 @@
 #
 # The tarball contains everything needed to run (or uninstall) Skald Circle:
 #   bin/skald, bin/skald-setup, web/, agents/, skills/,
-#   default.config.yaml, providers.yaml, requirements.txt, run.sh, update.sh, uninstall.sh
+#   default.config.yaml, providers.yaml, requirements.txt,
+#   requirements-optional.txt, run.sh, update.sh, uninstall.sh
 
 set -eu
 
@@ -95,6 +96,7 @@ cp -r skills           "$STAGING/skills"
 cp default.config.yaml "$STAGING/default.config.yaml"
 cp providers.yaml      "$STAGING/providers.yaml"
 cp requirements.txt    "$STAGING/requirements.txt"
+cp requirements-optional.txt "$STAGING/requirements-optional.txt"
 cp run.sh              "$STAGING/run.sh"
 cp update.sh            "$STAGING/update.sh"
 cp uninstall.sh         "$STAGING/uninstall.sh"
diff --git a/install-nightly.sh b/install-nightly.sh
index aaeb75a..98dbcca 100755
--- a/install-nightly.sh
+++ b/install-nightly.sh
@@ -397,6 +397,15 @@ echo ""
 # Write channel tag for future updates
 echo "$CHANNEL" > "$INSTALL_DIR/.release-channel"
 
+# ── Hint about optional deps ──────────────────────────────────────────────────
+if [ -f "${INSTALL_DIR}/requirements-optional.txt" ]; then
+    echo ""
+    info "💡 Optional GPU/ML dependencies available:"
+    info "   ${INSTALL_DIR}/requirements-optional.txt"
+    echo "   Install them manually if you use the Orpheus TTS plugin:"
+    echo "     cd ${INSTALL_DIR} && .venv/bin/pip install -r requirements-optional.txt"
+fi
+
 echo "  Server : ${INSTALL_DIR}/run.sh"
 echo "  Binary : ${INSTALL_DIR}/bin/skald"
 echo "  Setup  : ${INSTALL_DIR}/bin/skald-setup"
diff --git a/install.sh b/install.sh
index 84b3208..01b8273 100755
--- a/install.sh
+++ b/install.sh
@@ -403,6 +403,15 @@ echo ""
 echo "release" > "$INSTALL_DIR/.release-channel"
 echo "$VERSION" > "$INSTALL_DIR/.release-version"
 
+# ── Hint about optional deps ──────────────────────────────────────────────────
+if [ -f "${INSTALL_DIR}/requirements-optional.txt" ]; then
+    echo ""
+    info "💡 Optional GPU/ML dependencies available:"
+    info "   ${INSTALL_DIR}/requirements-optional.txt"
+    echo "   Install them manually if you use the Orpheus TTS plugin:"
+    echo "     cd ${INSTALL_DIR} && .venv/bin/pip install -r requirements-optional.txt"
+fi
+
 echo "  Server : ${INSTALL_DIR}/run.sh"
 echo "  Binary : ${INSTALL_DIR}/bin/skald"
 echo "  Setup  : ${INSTALL_DIR}/bin/skald-setup"
diff --git a/requirements-optional.txt b/requirements-optional.txt
new file mode 100644
index 0000000..4c7a446
--- /dev/null
+++ b/requirements-optional.txt
@@ -0,0 +1,13 @@
+# Orpheus TTS 3B (plugin-tts-orpheus-3b) — GPU-heavy dependencies
+# Install only if you enable the Orpheus TTS plugin:
+#   pip install -r requirements-optional.txt
+#
+# NOTE: torch and bitsandbytes pull in CUDA libraries (~GB). On a headless
+# server (no NVIDIA GPU) these are completely unnecessary, so they are kept
+# in a separate file.
+
+torch
+transformers
+snac
+bitsandbytes
+huggingface_hub
diff --git a/requirements.txt b/requirements.txt
index 00224be..20ad8ff 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -16,12 +16,8 @@ trendspyg>=0.7.0
 kokoro-onnx
 soundfile
 
-# Orpheus TTS 3B (plugin-tts-orpheus-3b) — heavy deps, only needed when plugin is enabled
-torch
-transformers
-snac
-bitsandbytes
-huggingface_hub
+# Orpheus TTS 3B (plugin-tts-orpheus-3b) — heavy deps moved to requirements-optional.txt
+# See requirements-optional.txt if you need the Orpheus TTS plugin.
 fastapi
 uvicorn
 scipy
diff --git a/update.sh b/update.sh
index 1c7d0e5..c0adbaa 100755
--- a/update.sh
+++ b/update.sh
@@ -207,6 +207,15 @@ fi
 
 start_service
 
+# ── Hint about optional deps ──────────────────────────────────────────────────
+if [ -f "${INSTALL_DIR}/requirements-optional.txt" ]; then
+    info "💡 Optional GPU/ML dependencies available:"
+    info "   ${INSTALL_DIR}/requirements-optional.txt"
+    echo "   Install them manually if you use the Orpheus TTS plugin:"
+    echo "     cd ${INSTALL_DIR} && .venv/bin/pip install -r requirements-optional.txt"
+    echo ""
+fi
+
 # ── Done ──────────────────────────────────────────────────────────────────────
 echo ""
 info "✅ Skald Circle updated to ${DISPLAY_VERSION}!"