fix: Unpin the Space's transformers -- the pin made the build unsolvable

The Space build failed with ResolutionImpossible. The platform appends its own
gradio[oauth,mcp]==6.25.0 to whatever requirements.txt asks for, gradio 6.x
requires huggingface-hub>=1.16, and every transformers<4.56 requires <1.0. The
only reason for that pin was engine_torch passing torch_dtype=, which
transformers renamed to dtype= in 4.56.

dtype_kwarg() picks the spelling from the installed version instead, so nothing
needs pinning; embeddings.py carries the same two-line check rather than
importing it, to keep controlai_rag from depending on controlai_agent. gradio,
spaces and huggingface-hub are dropped from the file entirely -- the platform
injects all three, and listing them only adds constraints to conflict with.

Since the file no longer pins transformers at all, _align_cache now tolerates a
DynamicCache without crop(): it re-prefills the whole prompt instead, losing the
prefix reuse but not correctness.

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

CLAUDE.md

@@ -207,6 +207,14 @@ and silently offloads to CPU.
   with `_share_cuda_: only available on CUDA` after emitting nothing — which reads exactly like
   "just slow". Reach the agent through the module global.
 
+**Do not put an upper bound in `requirements-space.txt`.** The platform appends its own
+`gradio[oauth,mcp]`, `spaces`, `uvicorn` and a `torch` ceiling to whatever that file asks for, and
+one extra constraint can make the resolve impossible. Pinning `transformers<4.56` — to keep using
+the `torch_dtype=` kwarg it renamed — failed the build outright, because gradio 6.x requires
+`huggingface-hub>=1.16` and every `transformers<4.56` requires `<1.0`. `engine_torch.dtype_kwarg()`
+detects the spelling instead, and `_align_cache` falls back to a full re-prefill if `DynamicCache`
+has no `crop()`, so an unpinned transformers costs speed rather than correctness.
+
 The Space needs `HF_TOKEN` as a secret: the retrieval index is in a private dataset repo and
 `app_space.py::_fetch_index` pulls it at startup. Without it the Space still boots, and answers
 from model knowledge alone.

controlai_agent/engine_torch.py

@@ -34,6 +34,22 @@ from typing import Any, Generator, Iterable, Sequence
 
 from controlai_agent.engine import Chunk, SamplingConfig, Stats
 
+
+def dtype_kwarg(dtype: Any) -> dict[str, Any]:
+    """`{"dtype": ...}` or `{"torch_dtype": ...}`, whichever this release takes.
+
+    transformers renamed the argument in 4.56 and the old spelling is gone in
+    recent releases. Pinning below 4.56 to keep using it is what broke the Space
+    build: the platform force-installs gradio 6.x, which requires
+    huggingface-hub >= 1.16, while every transformers < 4.56 requires < 1.0.
+    Detecting the spelling costs two lines and pins nothing.
+    """
+    import transformers
+
+    major, minor = (int(x) for x in transformers.__version__.split(".")[:2])
+    key = "dtype" if (major, minor) >= (4, 56) else "torch_dtype"
+    return {key: dtype}
+
 # The MLX default is a 4-bit MLX conversion, which transformers cannot read.
 # This is the same weights in a format it can, already quantised to NF4: ~9GB to
 # download rather than the ~28GB of the bf16 Qwen/Qwen3-14B, and no quantisation
@@ -67,10 +83,8 @@ class TorchEngine:
         # module docstring. The CPU branch exists only so the decode loop can be
         # exercised on a small model off a GPU box; it is far too slow to serve.
         cuda = torch.cuda.is_available()
-        # `torch_dtype`, not `dtype`: the newer spelling only exists from
-        # transformers 4.56, and requirements-space.txt pins older than that.
         kwargs: dict[str, Any] = {
-            "torch_dtype": torch.bfloat16 if cuda else torch.float32,
+            **dtype_kwarg(torch.bfloat16 if cuda else torch.float32),
             "device_map": {"": 0} if cuda else "cpu",
         }
         if load_in_4bit and not cuda:
@@ -203,6 +217,14 @@ class TorchEngine:
             return list(tokens)
 
         if shared < len(self._cache_tokens):
+            # crop() is what makes prefix reuse possible. It has moved around
+            # between transformers releases and this file no longer pins a
+            # version, so losing it costs speed, not correctness: fall back to
+            # re-prefilling the whole prompt.
+            if not hasattr(self._cache, "crop"):
+                self._cache = DynamicCache()
+                self._cache_tokens = []
+                return list(tokens)
             self._cache.crop(shared)
         self._cache_tokens = list(tokens[:shared])
         return list(tokens[shared:])

controlai_rag/embeddings.py

@@ -60,9 +60,16 @@ class Embedder:
             from transformers import AutoModel, AutoTokenizer
 
             self._tokenizer = AutoTokenizer.from_pretrained(self.model_id)
+            # transformers renamed torch_dtype -> dtype in 4.56; the Space
+            # resolves to whatever gradio's huggingface-hub floor allows, so
+            # detect rather than pin. See engine_torch.dtype_kwarg.
+            import transformers
+
+            _v = tuple(int(x) for x in transformers.__version__.split(".")[:2])
+            _key = "dtype" if _v >= (4, 56) else "torch_dtype"
             self._model = AutoModel.from_pretrained(
                 self.model_id,
-                torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32,
+                **{_key: torch.float16 if torch.cuda.is_available() else torch.float32},
             )
             self._model = self._model.to("cuda" if torch.cuda.is_available() else "cpu")
             self._model.eval()

requirements-space.txt

@@ -4,16 +4,19 @@
 # through controlai_agent/engine_torch.py instead. Do NOT install this file
 # locally: requirements.txt is the Apple Silicon runtime and is MLX-only.
 
+# Deliberately unpinned above the floor. The Space platform force-installs its
+# own gradio, spaces, uvicorn and a torch ceiling on top of this file, and any
+# upper bound here can make the resolve impossible -- pinning transformers <4.56
+# did exactly that, because gradio 6.x needs huggingface-hub >=1.16 and every
+# transformers <4.56 needs <1.0.
 torch>=2.4.0
-# <4.56: engine_torch passes `torch_dtype=`, which the newer releases renamed.
-transformers>=4.51.0,<4.56
+transformers>=4.51.0
 accelerate>=0.30.0
 bitsandbytes>=0.43.0          # 4-bit NF4; CUDA-only
 sentencepiece>=0.2.0
 
-gradio>=4.44.0                # only for the ZeroGPU probe
-spaces>=0.30.0
-huggingface-hub>=0.23.0
+# gradio, spaces and huggingface-hub are injected by the platform at build
+# time; listing them here only adds constraints that can conflict with it.
 
 # Everything below is shared with requirements.txt (minus mlx-lm).
 numpy>=1.24.0