Connect HF FLUX runtime

app.py

@@ -20,6 +20,7 @@ except Exception:  # pragma: no cover - local development does not require Space
     spaces = None
 
 from nexus_visual_weaver.catalog import catalog_summary
+from nexus_visual_weaver.hf_runtime import generate_flux_image
 from nexus_visual_weaver.model_relay import WeaverModelRelay
 from nexus_visual_weaver.planner import build_command_center_run
 from nexus_visual_weaver.render import render_catalog_table, render_command_header, render_dashboard_regions
@@ -129,11 +130,13 @@ def run_weave(
         adult_mode=adult_mode,
     )
     scan = scan_file(_file_path(upload))
+    generation = generate_flux_image(run.refined_prompt.refined, seed=int(run.checkpoint.checkpoint_id[-6:], 16) % 1_000_000)
     operator_state = {
-        "provider_state": "checkpointed",
+        "provider_state": generation.provider_state if generation.status in {"success", "error", "missing_runtime", "no_cuda"} else "checkpointed",
         "checkpoint": "pending_review",
         "export": scan.get("export_gate", "pending"),
-        "message": "Run packet generated. Human checkpoint required before provider promotion or export.",
+        "message": generation.message or "Run packet generated. Human checkpoint required before provider promotion or export.",
+        "generation": generation.to_dict(),
     }
     regions = _dashboard_regions(
         run=run,

requirements.txt

@@ -1,3 +1,7 @@
 gradio==6.12.0
 huggingface_hub==1.18.0
 pytest==9.0.3
+accelerate>=1.12.0
+transformers>=4.57.1
+Pillow>=11.1.0
+git+https://github.com/huggingface/diffusers.git

src/nexus_visual_weaver/hf_runtime.py

@@ -0,0 +1,126 @@
+"""HF-native model execution for the Space runtime."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any
+
+
+FLUX_REPO_ID = "black-forest-labs/FLUX.2-klein-9B"
+
+
+@dataclass(frozen=True)
+class HFGenerationResult:
+    status: str
+    provider_state: str
+    repo_id: str
+    output_path: str | None = None
+    message: str = ""
+    latency_seconds: float | None = None
+    width: int = 1024
+    height: int = 1024
+    steps: int = 4
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def hf_runtime_enabled() -> bool:
+    if os.environ.get("NEXUS_DISABLE_REAL_HF") == "1":
+        return False
+    if os.environ.get("NEXUS_ENABLE_REAL_HF") == "1":
+        return True
+    return bool(os.environ.get("SPACE_ID") or os.environ.get("HF_SPACE_ID"))
+
+
+def _output_dir() -> Path:
+    root = Path(os.environ.get("NEXUS_OUTPUT_DIR") or ("/data/nexus_visual_weaver" if Path("/data").exists() else "outputs/runtime"))
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _short_error(exc: BaseException) -> str:
+    text = str(exc).replace("\n", " ").strip()
+    if len(text) > 420:
+        text = text[:417] + "..."
+    return f"{exc.__class__.__name__}: {text}"
+
+
+def generate_flux_image(prompt: str, *, seed: int = 0, width: int = 1024, height: int = 1024, steps: int = 4) -> HFGenerationResult:
+    if not hf_runtime_enabled():
+        return HFGenerationResult(
+            status="disabled",
+            provider_state="dry-run",
+            repo_id=FLUX_REPO_ID,
+            message="Real HF generation disabled outside Space. Set NEXUS_ENABLE_REAL_HF=1 to force local execution.",
+            width=width,
+            height=height,
+            steps=steps,
+        )
+
+    started = time.perf_counter()
+    try:
+        import torch
+        from diffusers import Flux2KleinPipeline
+    except Exception as exc:  # pragma: no cover - depends on Space runtime packages.
+        return HFGenerationResult(
+            status="missing_runtime",
+            provider_state="blocked",
+            repo_id=FLUX_REPO_ID,
+            message=f"FLUX runtime import failed. Install diffusers main + torch. {_short_error(exc)}",
+            width=width,
+            height=height,
+            steps=steps,
+        )
+
+    if not torch.cuda.is_available():
+        return HFGenerationResult(
+            status="no_cuda",
+            provider_state="blocked",
+            repo_id=FLUX_REPO_ID,
+            message="CUDA is not available to the Space callback; FLUX.2 9B requires GPU execution.",
+            width=width,
+            height=height,
+            steps=steps,
+        )
+
+    try:
+        dtype = torch.bfloat16
+        pipe = Flux2KleinPipeline.from_pretrained(FLUX_REPO_ID, torch_dtype=dtype)
+        pipe.enable_model_cpu_offload()
+        generator = torch.Generator(device="cuda").manual_seed(seed)
+        image = pipe(
+            prompt=prompt,
+            height=height,
+            width=width,
+            guidance_scale=1.0,
+            num_inference_steps=steps,
+            generator=generator,
+        ).images[0]
+        output_path = _output_dir() / f"nexus_flux_{int(time.time())}_{seed}.png"
+        image.save(output_path)
+        return HFGenerationResult(
+            status="success",
+            provider_state="generated",
+            repo_id=FLUX_REPO_ID,
+            output_path=str(output_path),
+            message="FLUX.2 Klein generated a real image artifact on HF Space.",
+            latency_seconds=round(time.perf_counter() - started, 2),
+            width=width,
+            height=height,
+            steps=steps,
+        )
+    except Exception as exc:  # pragma: no cover - exercised on HF Space with gated/runtime conditions.
+        return HFGenerationResult(
+            status="error",
+            provider_state="blocked",
+            repo_id=FLUX_REPO_ID,
+            message=f"FLUX.2 generation failed. Check model license acceptance, HF_TOKEN/Space access, and runtime deps. {_short_error(exc)}",
+            latency_seconds=round(time.perf_counter() - started, 2),
+            width=width,
+            height=height,
+            steps=steps,
+        )

src/nexus_visual_weaver/render.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import os
+import base64
 from html import escape
+from pathlib import Path
 
 from .catalog import catalog_summary, parameter_budget
 from .schema import GenerationRun
@@ -51,6 +53,18 @@ def _space_runtime_status() -> dict[str, str]:
     }
 
 
+def _image_data_uri(path: str | None) -> str | None:
+    if not path:
+        return None
+    target = Path(path)
+    if not target.exists() or not target.is_file():
+        return None
+    suffix = target.suffix.lower()
+    mime = "image/png" if suffix == ".png" else "image/jpeg" if suffix in {".jpg", ".jpeg"} else "image/webp" if suffix == ".webp" else "application/octet-stream"
+    data = base64.b64encode(target.read_bytes()).decode("ascii")
+    return f"data:{mime};base64,{data}"
+
+
 def render_command_header() -> str:
     return f"""
     <section class="nw-command-header">
@@ -255,6 +269,10 @@ def render_artifact_lane(run: GenerationRun | None = None, scan: dict | None = N
     active_prompt = run.refined_prompt.refined[:150] if run else "Awaiting first weave. The preview stage shows dry-run handoff packets until provider output exists."
     checkpoint = operator_state.get("checkpoint", getattr(run.checkpoint, "recommendation", "pending") if run else "pending")
     provider_state = str(operator_state.get("provider_state", "dry-run" if run else "idle"))
+    generation = operator_state.get("generation") or {}
+    generated_uri = _image_data_uri(generation.get("output_path")) if isinstance(generation, dict) else None
+    generated_status = str(generation.get("status", "")) if isinstance(generation, dict) else ""
+    generated_message = str(generation.get("message", "")) if isinstance(generation, dict) else ""
     preview_mode = {
         "idle": "Idle",
         "dry-run": "Dry Run",
@@ -293,11 +311,11 @@ def render_artifact_lane(run: GenerationRun | None = None, scan: dict | None = N
       </div>
       <div class="nw-preview-stage">
         <div class="nw-preview-frame">
-          <i class="nw-preview-image"></i>
+          {'<img class="nw-preview-real-image" src="' + generated_uri + '" alt="Generated FLUX artifact" />' if generated_uri else '<i class="nw-preview-image"></i>'}
           <div class="nw-preview-caption">
-            <small>PRIMARY OUTPUT STAGE / JUDGE-SAFE DEMO OUTPUT / SEED {escape(demo_seed)}</small>
-            <strong>Deterministic Raven Chronicle proof frame</strong>
-            <span>{escape(active_prompt)}</span>
+            <small>PRIMARY OUTPUT STAGE / {escape(generated_status.upper() or "JUDGE-SAFE DEMO OUTPUT")} / SEED {escape(demo_seed)}</small>
+            <strong>{'Real FLUX.2 Klein artifact' if generated_uri else 'Deterministic Raven Chronicle proof frame'}</strong>
+            <span>{escape(generated_message or active_prompt)}</span>
           </div>
         </div>
         <div class="nw-preview-meta">

src/nexus_visual_weaver/styles.py

@@ -657,6 +657,15 @@ footer { display: none !important; }
     linear-gradient(155deg, #050608, #171d23 44%, #4f1020 45%, #07090c 63%);
   border-right: 1px solid rgba(255,255,255,.08);
 }
+.nw-preview-real-image {
+  width: 100%;
+  min-height: 190px;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+  border-right: 1px solid rgba(255,255,255,.08);
+  background: #050608;
+}
 .nw-preview-caption {
   display: grid;
   align-content: end;

tests/test_hf_runtime.py

@@ -0,0 +1,36 @@
+from PIL import Image
+
+from nexus_visual_weaver.hf_runtime import generate_flux_image, hf_runtime_enabled
+from nexus_visual_weaver.render import render_artifact_lane
+
+
+def test_hf_runtime_is_disabled_locally_by_default(monkeypatch) -> None:
+    monkeypatch.delenv("SPACE_ID", raising=False)
+    monkeypatch.delenv("HF_SPACE_ID", raising=False)
+    monkeypatch.delenv("NEXUS_ENABLE_REAL_HF", raising=False)
+    monkeypatch.delenv("NEXUS_DISABLE_REAL_HF", raising=False)
+
+    assert hf_runtime_enabled() is False
+    result = generate_flux_image("test prompt")
+    assert result.status == "disabled"
+    assert result.provider_state == "dry-run"
+
+
+def test_artifact_lane_embeds_generated_image() -> None:
+    image_path = "outputs/test-generated-artifact.png"
+    Image.new("RGB", (16, 16), color=(12, 16, 20)).save(image_path)
+
+    html = render_artifact_lane(
+        operator_state={
+            "provider_state": "generated",
+            "generation": {
+                "status": "success",
+                "output_path": str(image_path),
+                "message": "FLUX.2 generated a real artifact.",
+            },
+        }
+    )
+
+    assert "nw-preview-real-image" in html
+    assert "data:image/png;base64" in html
+    assert "Real FLUX.2 Klein artifact" in html