fix: Accept the Space's existing CONTROLAI_BACKEND spelling, and stop guessing

The Space boots with CONTROLAI_BACKEND=pytorch, a variable left over from the
old orchestrator's escape hatch (dfe7123). _make_engine tested for "torch"
exactly, so it did not match, fell through to LocalEngine on a machine with no
MLX, and failed with ModuleNotFoundError: mlx_lm several frames below the actual
cause. app_space.py's os.environ.setdefault could not correct it either, since
the variable was already set.

Three changes, because the silent fallback was the real defect:
- "pytorch" and "cuda" are accepted alongside "torch".
- An unrecognised value now raises instead of quietly selecting MLX. A misspelt
backend should fail at the point of the mistake, naming the variable.
- app_space.py assigns CONTROLAI_BACKEND rather than setdefault-ing it. That
module is the CUDA entry point by definition; a stale Space variable must not
be able to select something else.

The rest of the boot was clean: the build resolved, the private index downloaded
in about three seconds, and the ZeroGPU probe came up on its own port.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md

@@ -181,9 +181,13 @@ of the serving path and uses `requirements-training.txt`/`requirements-corpus.tx
 
 ### Deployment (`app_space.py`, `engine_torch.py`, `requirements-space.txt`)
 The demo Space (huggingface.co/spaces/atakankahya/ControlAI-Agent) runs Linux/NVIDIA on ZeroGPU,
-where MLX does not exist. `CONTROLAI_BACKEND=torch` makes `app.py::_make_engine` build
+where MLX does not exist. `CONTROLAI_BACKEND` makes `app.py::_make_engine` build
 `TorchEngine` instead of `LocalEngine`; `Embedder` switches on the same variable. That is the whole
-switch — two branches, no orchestrator.
+switch — two branches, no orchestrator. It accepts `torch`, `pytorch` or `cuda`, and **raises on
+anything it does not recognise rather than falling back to MLX**. The deployed Space still carries
+`CONTROLAI_BACKEND=pytorch` as a variable from the old orchestrator; a check for `"torch"` alone
+silently selected MLX on a box with no MLX, and the failure surfaced as `ModuleNotFoundError:
+mlx_lm` several frames from the real cause.
 
 `engine_torch.py` mirrors `engine.py` rather than calling `model.generate`, because `generate`
 cannot express either of the two things that matter: `DynamicCache.crop()` for prefix reuse across

app.py

@@ -66,10 +66,22 @@ def _make_engine():
     never needs torch installed. Everything downstream -- the agent loop, the
     registry, every tool -- is identical either way.
     """
-    if os.environ.get("CONTROLAI_BACKEND", "mlx").lower() == "torch":
+    backend = os.environ.get("CONTROLAI_BACKEND", "mlx").strip().lower()
+    # "pytorch" is what the old orchestrator called this and it survives as a
+    # variable on the deployed Space; "cuda" is the obvious other guess.
+    if backend in ("torch", "pytorch", "cuda"):
         from controlai_agent.engine_torch import TorchEngine
 
         return TorchEngine()
+    if backend not in ("mlx", ""):
+        # Never fall through to MLX because a variable was misspelt. That is
+        # exactly what happened on the Space: CONTROLAI_BACKEND=pytorch did not
+        # match a check for "torch", so it built LocalEngine on a box with no
+        # MLX and died in an import several frames deeper than the real cause.
+        raise ValueError(
+            f"CONTROLAI_BACKEND={backend!r} is not a known backend "
+            f"(expected one of: mlx, torch/pytorch/cuda)"
+        )
     return None  # ControlAgent's own default, LocalEngine
 
 

app_space.py

@@ -29,8 +29,11 @@ from __future__ import annotations
 
 import os
 
-# Must be set before app.py is imported: it decides which engine gets built.
-os.environ.setdefault("CONTROLAI_BACKEND", "torch")
+# Assigned, not setdefault: this module is the CUDA entry point by definition,
+# and a stale Space variable must not be able to select something else. One did
+# -- CONTROLAI_BACKEND=pytorch, left over from the old orchestrator -- and the
+# Space booted into the MLX engine and died on `import mlx_lm`.
+os.environ["CONTROLAI_BACKEND"] = "torch"
 # Qwen3-14B in 4-bit NF4. Override with CONTROLAI_MODEL_TORCH in Space settings.
 
 import gradio as gr