fix: Make the Space a Gradio app, which is what ZeroGPU requires

ZeroGPU assumes the Gradio app *is* the Space: it schedules GPU workers by
forking the server process, and its startup validation looks for a @spaces.GPU
function wired to a Gradio event handler. Keeping FastAPI on the public port
with Gradio as a hidden side-car was the seventh and last incompatibility -- the
GPU was scheduled and acquired and the forked worker still died in torch.init(),
while the platform probed the public port for /api/predict and got 404. A no-op
@spaces.GPU function failed the same way, so it was never the model.

So Gradio owns the port and ControlAgent runs inside @spaces.GPU. The web/
console is lost on the Space only; the agent, the 29 solvers, the verifier and
the 80,370-chunk retriever are unchanged, and app.py keeps the console locally.

The turn is the unit wrapped by @spaces.GPU, not each generation: a turn is
several generations sharing one KV cache. Tool activity is streamed as it
happens so a multi-step turn does not look like a hang, and plots and sources
are appended when it finishes.

The other six constraints are all still respected -- import-scope build, no
device_map, agent via module global, embedder warmed in the same window, no
upper bounds in requirements, and no pinning torch below CUDA 12.8 (ZeroGPU is
Blackwell, sm_120). All seven are written up in CLAUDE.md.

engine_api.py stays, unused: it works and only needs a token permission, and it
is the fallback for a demo with no GPU at all.

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

CLAUDE.md

@@ -179,53 +179,47 @@ formats correctly. `CONTROLAI_ADAPTER=<path>` loads one anyway for A/B work.
 discovery → extraction → dataset generation → training → evaluation). That pipeline is independent
 of the serving path and uses `requirements-training.txt`/`requirements-corpus.txt`.
 
-### Deployment (`app_space.py`, `engine_api.py`, `requirements-space.txt`)
-The demo Space runs **plain CPU hardware with hosted generation**, not ZeroGPU.
-`CONTROLAI_BACKEND=api` makes `app.py::_make_engine` build `RemoteEngine`; everything else —
-all 29 solvers, the verifier, the full 80,370-chunk retriever — runs in-process on the Space's CPU,
-where it costs milliseconds. Only token generation leaves the machine. The Space page says so
-plainly, because the local app's whole point is that nothing does.
-
-`engine_api.py` renders the tool schemas through the model's own chat template locally and hands
-the result over as an ordinary **system message** — never as a `tools=` argument, which would make
-the provider apply its own template and return structured `tool_calls` the agent does not speak.
-Every provider serving Qwen3 offers `conversational` only, not raw text-generation, so `render()`
-returns a *message list* rather than a string; the agent treats that value as opaque, so nothing
-downstream cares. Thinking is disabled with Qwen3's `/no_think` soft switch rather than
-`chat_template_kwargs`, which is an `extra_body` passthrough not every provider forwards.
-
-`HF_TOKEN` must be a Space secret with **two** permissions: read on the private index dataset repo,
-and *Make calls to Inference Providers*. Missing the first disables retrieval silently; missing the
-second fails generation with `403 ... does not have sufficient permissions to call Inference
-Providers`.
-
-**ZeroGPU was tried at length and abandoned.** `engine_torch.py` is kept and works on an ordinary
-CUDA box; it is ZeroGPU specifically that does not fit. Seven distinct problems, recorded so the
-attempt is not repeated blind:
-1. **Dependency resolution.** The platform appends its own `gradio[oauth,mcp]`, `spaces`, `uvicorn`
-   and a `torch` ceiling to `requirements.txt`. Any upper bound of your own can make the resolve
-   impossible — `transformers<4.56` did, because gradio 6 needs `huggingface-hub>=1.16` and every
-   `transformers<4.56` needs `<1.0`.
-2. **Import-window loading.** ZeroGPU patches torch during the entry module's import and only
-   intercepts CUDA inside that window. Building the model in FastAPI's `lifespan`, on a worker
-   thread, reaches real CUDA init and raises.
-3. **`device_map` and bitsandbytes.** `device_map` routes transformers through
+### Deployment (`app_space.py`, `engine_torch.py`, `requirements-space.txt`)
+The demo Space is a **Gradio app on ZeroGPU**, not the FastAPI console. That is not a preference:
+**ZeroGPU assumes the Gradio app is the Space.** It schedules GPU workers by forking the server
+process, and its startup validation looks for a `@spaces.GPU` function wired to a Gradio event
+handler. Keeping FastAPI on the public port with Gradio as a hidden side-car was tried at length and
+does not work — see the list below. `app_space.py` therefore gives Gradio the port and drives
+`ControlAgent` from inside `@spaces.GPU`. The `web/` console is lost on the Space only; the agent,
+the 29 solvers, the verifier and the 80,370-chunk retriever are all the same.
+
+Seven ZeroGPU constraints, each found the hard way. Read these before changing anything here:
+1. **No upper bounds in `requirements-space.txt`.** The platform appends its own
+   `gradio[oauth,mcp]`, `spaces`, `uvicorn` and a `torch` ceiling; one extra constraint can make the
+   resolve impossible. `transformers<4.56` did, because gradio 6 needs `huggingface-hub>=1.16` and
+   every `transformers<4.56` needs `<1.0`. **And do not pin torch down to CUDA 12** — ZeroGPU is
+   backed by Blackwell (sm_120), which needs CUDA 12.8+; an older wheel has no kernels for it.
+2. **Build the model at import scope.** ZeroGPU patches torch during the entry module's import and
+   only intercepts CUDA inside that window. Building it in a lifespan or a request reaches real CUDA
+   init and raises `Low-level CUDA init (torch._C._cuda_init) reached`.
+3. **No `device_map`, no bitsandbytes.** `device_map` routes transformers through
    `caching_allocator_warmup`'s direct `torch.empty(..., device="cuda")`, which trips the same
-   guard; bitsandbytes requires `device_map`, so 4-bit is unavailable.
+   guard; bitsandbytes requires `device_map`, so 4-bit is unavailable and the model must fit in bf16.
 4. **Inference must be inside `@spaces.GPU`.** Otherwise the packed tensors are never materialised
    and forward passes return fluent multilingual noise at ~15 min/turn — up, responsive, and
-   confidently wrong.
-5. **Thread context.** `spaces` intercepts CUDA only in the context it manages; a call from a
-   custom `ThreadPoolExecutor` thread fails with `No CUDA GPUs are available` even with a GPU
-   attached. Found and fixed once before in 4de16e3, then reintroduced by the MLX rewrite.
-6. **The probe must be `launch()`ed, not mounted.** `gr.mount_gradio_app` fails startup with
-   "No @spaces.GPU function detected". Launch it on its own port with `ssr_mode=False` (Gradio 6's
-   SSR spawns a Node subprocess into the process ZeroGPU forks from).
-7. **The structural one.** With all six fixed, the GPU is scheduled and acquired and ZeroGPU's own
-   forked worker still dies in `torch.init()`. A no-op `@spaces.GPU` function fails identically, so
-   it is not the model or the payload. Meanwhile the platform probes the public port for Gradio's
-   `/api/predict` and gets 404, because FastAPI owns it. ZeroGPU assumes the Gradio app *is* the
-   Space; this one is not.
+   confidently wrong. Wrap the whole *turn*: a turn is several generations sharing one KV cache.
+5. **Never pass the agent as an argument** to a `@spaces.GPU` function; reach it through a module
+   global. ZeroGPU marshals arguments across a process boundary and tries to share CUDA tensors,
+   hanging with no output.
+6. **The embedder is a second model** with the same import-window problem. It loads lazily on the
+   first query, so `_build()` embeds one throwaway string to force it in. Without that the Space
+   starts fine and every answer carries `[agent] retrieval failed`.
+7. **Gradio must own the public port.** With all of the above fixed but FastAPI on the port, the GPU
+   was scheduled and acquired and ZeroGPU's own forked worker still died in `torch.init()`, while
+   the platform probed the public port for `/api/predict` and got 404. A no-op `@spaces.GPU`
+   function failed identically, so it was not the model or the payload.
+
+`HF_TOKEN` must be a Space secret with read access to the private index dataset repo, or retrieval
+is silently disabled.
+
+`engine_api.py` is an unused-but-working alternative: `CONTROLAI_BACKEND=api` runs generation over
+Inference Providers with everything else local. It needs a token carrying *Make calls to Inference
+Providers*. Kept for anyone who wants a demo without a GPU at all.
 
 ### Benchmark (`benchmarks/`)
 `controlbench_v1.jsonl` is the eval set; `SCOPE.md` defines the taxonomy and `README.md` the

app_space.py

@@ -1,43 +1,50 @@
-"""Hugging Face Space entry point: FastAPI, CPU hardware, hosted generation.
-
-`./run.sh` runs `app.py` directly; this exists only for the Space.
-
-**This deliberately does not use ZeroGPU.** Seven separate incompatibilities came
-out of trying to, and the last one is structural rather than a bug: ZeroGPU is
-built around "the Gradio app *is* the Space", scheduling GPU workers by forking
-the Gradio server process, while ControlAI is a FastAPI app with its own console
-that merely borrows the process. The findings are catalogued in CLAUDE.md so the
-attempt is not repeated blind, and `engine_torch.py` is kept for anyone running
-this on an ordinary CUDA box, where all of it works.
-
-What runs where: everything that makes ControlAI what it is stays in-process on
-the Space's CPU -- all 29 deterministic solvers, the verifier, the full
-80,370-chunk hybrid retriever. Those cost milliseconds. Only token generation
-leaves, to a GPU behind an API, via `RemoteEngine`.
-
-The Space needs `HF_TOKEN` as a secret, with **two** permissions: read access to
-the private dataset repo holding the index, and "Make calls to Inference
-Providers". Without the first, retrieval is silently disabled; without the
-second, generation fails with 403.
+"""Hugging Face Space entry point: a Gradio app on ZeroGPU.
+
+`./run.sh` runs `app.py` -- FastAPI plus the `web/` console -- and that is the
+real product. This file is a *different front end over the same agent*, and it
+exists because of one hard platform constraint:
+
+**ZeroGPU assumes the Gradio app is the Space.** It schedules GPU workers by
+forking the server process, and its startup validation looks for a `@spaces.GPU`
+function wired to a Gradio event handler. An earlier version of this file kept
+FastAPI on the public port and ran Gradio as a hidden side-car; the GPU was
+scheduled and acquired and the forked worker still died in `torch.init()`, while
+the platform probed the public port for `/api/predict` and got 404. Six other
+incompatibilities were fixed before that one; all seven are in CLAUDE.md.
+
+So here Gradio owns the port and the agent runs inside `@spaces.GPU`. What is
+lost is the `web/` console, on the Space only. What is kept is everything that
+matters: the same `ControlAgent`, the same 29 deterministic solvers, the same
+verifier, the same 80,370-chunk hybrid retriever, the same model.
+
+Two ordering rules, both learned the hard way:
+*   The model is built at **import scope**. ZeroGPU patches torch during the
+    entry module's import and only intercepts CUDA inside that window; building
+    it later reaches real CUDA init and raises.
+*   The agent is reached from inside the GPU function through a **module
+    global**, never passed as an argument. ZeroGPU marshals arguments across a
+    process boundary and would try to share the model's CUDA tensors, hanging
+    with no output.
 """
 
 from __future__ import annotations
 
 import os
+from pathlib import Path
+from typing import Iterator
 
-# Must precede the `app` import: it decides which engine gets built. Assigned,
-# not setdefault-ed, because a stale Space variable must not select something
-# else -- CONTROLAI_BACKEND=pytorch, left from the old orchestrator, once did.
-os.environ["CONTROLAI_BACKEND"] = "api"
+# Must precede the `controlai_agent` imports below.
+os.environ["CONTROLAI_BACKEND"] = "torch"
 
-import uvicorn
+import gradio as gr
+import spaces
 
-import app as app_module
-from app import app
+PLOTS_DIR = Path("outputs/plots")
+
+AGENT = None
 
 
 def _fetch_index() -> None:
-    """Pull the retrieval index in before the agent starts."""
     from controlai_rag.fetch_index import fetch
 
     if not os.environ.get("HF_TOKEN"):
@@ -50,11 +57,94 @@ def _fetch_index() -> None:
         print(f"[space] could not fetch the index ({exc}); retrieval disabled")
 
 
-def main() -> None:
-    _fetch_index()
-    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 7860)),
-                log_level="info")
+def _build() -> None:
+    """Build the agent while ZeroGPU is still watching for CUDA calls."""
+    global AGENT
+    from controlai_agent.agent import ControlAgent
+    from controlai_agent.engine_torch import TorchEngine
+    from controlai_rag.embeddings import get_embedder
+
+    print("[space] building agent at import scope (ZeroGPU CUDA window)")
+    AGENT = ControlAgent(engine=TorchEngine())
+    # The retrieval embedder is a second model and loads lazily on first query --
+    # a request, outside the window. Embedding one string forces it in here too.
+    get_embedder().encode_query("warmup")
+    print("[space] agent and embedder ready")
+
+
+@spaces.GPU(duration=300)
+def respond(message: str, history: list) -> Iterator[str]:
+    """One agent turn, streamed. Runs with real hardware attached.
+
+    Wraps the whole turn rather than each generation: a turn is several
+    generations sharing one KV cache, and splitting them across separate
+    @spaces.GPU calls would put that shared state across a process boundary on
+    every tool step.
+    """
+    if AGENT is None:  # pragma: no cover - import always builds it
+        yield "Agent failed to start; check the Space logs."
+        return
 
+    turns = [
+        {"role": m["role"], "content": m["content"]}
+        for m in (history or [])
+        if isinstance(m, dict) and m.get("role") in ("user", "assistant") and m.get("content")
+    ]
+
+    answer, tools, sources, plots = "", [], [], []
+    for event in AGENT.stream(message, turns):
+        kind = event["type"]
+        if kind == "text":
+            answer += event["text"]
+            yield answer
+        elif kind == "tool_end":
+            tools.append(event.get("tool"))
+            # Show tool activity while the model is still thinking, so a
+            # multi-step turn does not look like a hang.
+            yield answer + f"\n\n*running `{event.get('tool')}`…*"
+        elif kind == "done":
+            answer = event["answer"]
+            sources = event.get("sources") or []
+            plots = event.get("plots") or []
+
+    footer = ""
+    for plot in plots:
+        name = Path(plot).name
+        footer += f"\n\n![{name}](/gradio_api/file={PLOTS_DIR / name})"
+    if tools:
+        footer += "\n\n---\n*Computed with: " + ", ".join(f"`{t}`" for t in dict.fromkeys(tools)) + "*"
+    if sources:
+        footer += "\n\n*Sources: " + "; ".join(str(s) for s in sources[:4]) + "*"
+    yield answer + footer
+
+
+with gr.Blocks(title="ControlAI", fill_height=True) as demo:
+    gr.Markdown(
+        "# ControlAI\n"
+        "Control-systems assistant. Every number in an answer comes from a deterministic "
+        "solver — SciPy/LAPACK/CVXPY behind a validated tool registry — never from the "
+        "model's own arithmetic, and conceptual answers are grounded in a local "
+        "control-theory corpus.\n\n"
+        "*This hosted demo runs on Hugging Face's hardware, so the offline guarantee of a "
+        "local install does not apply here — don't enter anything confidential. The full "
+        "app, with its own console, runs on Apple Silicon: see the repository.*"
+    )
+    gr.ChatInterface(
+        fn=respond,
+        type="messages",
+        examples=[
+            "Design an LQR for A=[[0,1],[-2,-3]], B=[[0],[1]], Q=eye(2), R=1.",
+            "What is the phase margin of G(s) = 10/(s(s+1)(s+5))?",
+            "Explain the Bode sensitivity integral and what it implies for loop shaping.",
+            "Place the poles of A=[[0,1],[0,0]], B=[[0],[1]] at -2 and -3.",
+        ],
+        cache_examples=False,
+    )
+
+
+_fetch_index()
+_build()
 
 if __name__ == "__main__":
-    main()
+    PLOTS_DIR.mkdir(parents=True, exist_ok=True)
+    demo.launch(allowed_paths=[str(PLOTS_DIR)])

requirements-space.txt

@@ -1,25 +1,24 @@
 # Hugging Face Space dependencies -- see app_space.py.
 #
-# The Space runs on plain CPU hardware. Token generation is remote (RemoteEngine
-# -> Inference Providers), so there is no CUDA and no local LLM here. torch is
-# still needed, on CPU, for the 0.6B retrieval embedder: one query is a few
-# hundred milliseconds, which is fine.
-#
-# Do NOT install this locally: requirements.txt is the Apple Silicon MLX runtime.
+# The Space is a Gradio app on ZeroGPU (Linux/NVIDIA), where MLX does not exist,
+# so inference goes through controlai_agent/engine_torch.py. Do NOT install this
+# locally: requirements.txt on `main` is the Apple Silicon MLX runtime.
 
-# CPU wheels only. The default PyPI torch wheel drags several GB of CUDA
-# libraries that would never be used here.
---extra-index-url https://download.pytorch.org/whl/cpu
+# Unconstrained on purpose. The platform appends its own gradio, spaces, uvicorn
+# and a `torch<=2.11.0` ceiling to this file, and one extra bound of ours can
+# make the resolve impossible -- `transformers<4.56` did exactly that, because
+# gradio 6 needs huggingface-hub>=1.16 and every transformers<4.56 needs <1.0.
+#
+# Do not pin torch down to CUDA 12 either: ZeroGPU is backed by Blackwell
+# (sm_120), which needs CUDA 12.8+, so an older wheel has no kernels for it.
 torch>=2.4.0
-
-# No upper bound: the platform appends its own gradio/spaces/uvicorn on top of
-# this file, and one extra constraint can make the resolve impossible. Pinning
-# transformers<4.56 did exactly that once -- gradio 6 needs huggingface-hub>=1.16
-# and every transformers<4.56 needs <1.0.
 transformers>=4.51.0
-huggingface-hub>=0.34.0        # InferenceClient.chat_completion
+accelerate>=0.30.0
 
-# Deterministic numerics -- every number in an answer comes from these, locally.
+# gradio, spaces and huggingface-hub are injected by the platform at build time;
+# listing them here only adds constraints to conflict with it.
+
+# Deterministic numerics -- every number in an answer comes from these.
 numpy>=1.24.0
 scipy>=1.11.0
 control>=0.9.4
@@ -31,9 +30,3 @@ jsonschema>=4.20.0
 rank-bm25>=0.2.2
 pypdf>=3.17.0
 pymupdf>=1.23.0
-
-# Web console.
-fastapi>=0.110.0
-uvicorn>=0.28.0
-python-multipart>=0.0.9
-pydantic>=2.0.0