Upload 4 files

README.md

@@ -1,25 +1,114 @@
----
-title: HUDA-Net
-emoji: 🕋
-colorFrom: green
-colorTo: blue
-sdk: gradio
-sdk_version: 6.20.0
-hardware: cpu-basic
-app_file: app.py
-python_version: 3.10
-fullWidth: true
-header: mini
-pinned: false
-license: cc-by-sa-4.0
-datasets:
-  - dakheel/hudanet-knowledge-base-v1
-  - dakheel/hudanet-runtime
----
-
-# HUDA-Net
-
-Bilingual Hajj and Umrah evidence-based research assistant. v41.0.1 is Knowledge-Base native: 3,067 KB records are searched, 2,799 answer records may support answers, and 268 index-only records are exploration/routing aids only.
-
-## v41.0.1
-Fixes Hugging Face startup when the legacy Runtime model assets are stored in the repository flat layout. Only E5/BGE model files are selected and reconstructed; legacy records/indexes are not downloaded.
+# HUDA-Net v41.0.2 Prebuilt Retrieval Fix
+
+This package fixes the Hugging Face Space startup timeout caused by rebuilding
+the full bilingual hybrid retrieval stack on every restart.
+
+## Files
+
+- `hudanet_prebuilt_guard.py`
+  - Production runtime guard.
+  - Downloads a prebuilt retrieval bundle.
+  - Verifies HUDA-Net's own KB fingerprint and every SHA-256.
+  - Restores the final runtime files.
+  - Refuses to rebuild in production if assets are missing or stale.
+
+- `build_prebuilt_assets.py`
+  - One-time builder/publisher.
+  - Imports the CURRENT `app.py` with `HUDANET_SKIP_APP_INIT=1`.
+  - Runs `_prepare_kb_native_runtime_ui()` once.
+  - Packages `HYBRID_FILES` and Arabic/English embedding indexes.
+  - Creates/updates a private Hugging Face Dataset.
+
+- `patch_app_v41_0_2.py`
+  - Safely patches the CURRENT `app.py`.
+  - Makes a backup.
+  - Inserts the guard immediately before `HUDA_DEMO`.
+  - Changes 41.0.1 strings to 41.0.2.
+  - Compile-checks and restores backup if patching fails.
+
+## Recommended repository
+
+Default:
+`dakheel/hudanet-v41-prebuilt-retrieval`
+
+Override everywhere with:
+`HUDANET_PREBUILT_REPO_ID`
+
+## One-time setup
+
+Place these three `.py` files beside the CURRENT `app.py`.
+
+Patch the current app:
+
+```bash
+python patch_app_v41_0_2.py
+```
+
+Build and publish the retrieval bundle in Kaggle/local/build environment:
+
+Linux/macOS:
+
+```bash
+export HF_TOKEN="READ_TOKEN"
+export HF_WRITE_TOKEN="WRITE_TOKEN"
+export HUDANET_PREBUILT_REPO_ID="dakheel/hudanet-v41-prebuilt-retrieval"
+python build_prebuilt_assets.py
+```
+
+PowerShell:
+
+```powershell
+$env:HF_TOKEN="READ_TOKEN"
+$env:HF_WRITE_TOKEN="WRITE_TOKEN"
+$env:HUDANET_PREBUILT_REPO_ID="dakheel/hudanet-v41-prebuilt-retrieval"
+python build_prebuilt_assets.py
+```
+
+If the same token has both read and write permission, `HF_WRITE_TOKEN` can be
+omitted and the builder will use `HF_TOKEN`.
+
+## Production Space
+
+Commit these files to the Space:
+
+- patched `app.py`
+- `hudanet_prebuilt_guard.py`
+
+`build_prebuilt_assets.py` and `patch_app_v41_0_2.py` may remain in the repo,
+but they are not run automatically.
+
+Space secrets/variables:
+
+- `HF_TOKEN`: read access to all private HUDA-Net datasets, including the new
+  prebuilt retrieval dataset.
+- optional `HUDANET_PREBUILT_REPO_ID` if you used a different repo id.
+
+Do NOT put a write token in the production Space unless you genuinely need it.
+
+## Expected startup
+
+You should see something similar to:
+
+```text
+🔒 HUDA-Net v41.0.2 prebuilt retrieval guard active | production rebuild fallback disabled
+⬇️ Loading HUDA-Net prebuilt retrieval assets from dakheel/hudanet-v41-prebuilt-retrieval...
+⚡ HUDA-Net prebuilt retrieval restored | ... files | fingerprint=...
+✅ HUDA-Net v41 KB-native Runtime ready
+```
+
+You should NOT see:
+
+```text
+💾 ar: completed batch 1/384
+...
+💾 en: completed batch 1/384
+...
+```
+
+## When the Knowledge Base changes
+
+Run `build_prebuilt_assets.py` again.
+
+The production guard compares the bundle fingerprint with the current KB. A
+mismatch fails fast with a clear "STALE" message instead of silently using old
+embeddings or spending ~30 minutes rebuilding during Space startup.

build_prebuilt_assets.py

@@ -0,0 +1,324 @@
+# -*- coding: utf-8 -*-
+"""
+HUDA-Net v41.0.2 One-Time Prebuilt Retrieval Builder
+====================================================
+
+Run this file OUTSIDE the production Space, for example in Kaggle, a local
+machine, or another build environment.
+
+Requirements
+------------
+1. Put this file beside the CURRENT v41 app.py.
+2. app.py must support HUDANET_SKIP_APP_INIT=1 (v41.0.1 already does).
+3. Set:
+     HF_TOKEN=<token that can read the private HUDA-Net source datasets>
+     HF_WRITE_TOKEN=<token that can create/write the prebuilt dataset>
+   If one token has both permissions, HF_WRITE_TOKEN may be omitted.
+4. Optional:
+     HUDANET_PREBUILT_REPO_ID=dakheel/hudanet-v41-prebuilt-retrieval
+
+What it does
+------------
+- Imports the CURRENT app.py without starting Gradio.
+- Runs HUDA-Net's own KB-native runtime preparation ONCE.
+- Lets the original hybrid builder calculate BM25, E5 dense vectors and
+  calibration exactly as HUDA-Net already does.
+- Packages the final runtime retrieval files plus Arabic/English embedding
+  indexes.
+- Writes a fingerprinted SHA-256 manifest.
+- Creates/updates a private Hugging Face Dataset and uploads the bundle.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Mapping, Set
+
+from huggingface_hub import HfApi
+
+
+BUNDLE_MANIFEST = "hudanet_prebuilt_bundle_v41.json"
+DEFAULT_REPO_ID = "dakheel/hudanet-v41-prebuilt-retrieval"
+
+
+def _sha256_file(path: Path, chunk_size: int = 8 * 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        while True:
+            chunk = handle.read(chunk_size)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _copy_file_preserve_relative(root: Path, source: Path, stage: Path) -> str:
+    root = Path(root).resolve()
+    source = Path(source).resolve()
+    stage = Path(stage)
+
+    try:
+        rel = source.relative_to(root)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Refusing to package file outside runtime root: {source}"
+        ) from exc
+
+    dst = stage / rel
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, dst)
+    return rel.as_posix()
+
+
+def _collect_runtime_files(hudanet: Any, runtime_root: Path) -> List[Path]:
+    runtime_root = Path(runtime_root)
+    files: Set[Path] = set()
+
+    hybrid_files = getattr(hudanet, "HYBRID_FILES", None)
+    if not isinstance(hybrid_files, Mapping):
+        raise RuntimeError("Current app.py has no HYBRID_FILES mapping.")
+
+    for filename in hybrid_files.values():
+        path = runtime_root / str(filename)
+        if not path.is_file():
+            raise RuntimeError(f"Required hybrid runtime file is missing: {path}")
+        files.add(path)
+
+    embedding_index_fn = getattr(hudanet, "_embedding_index_path", None)
+    if callable(embedding_index_fn):
+        for lang in ("ar", "en"):
+            path = Path(embedding_index_fn(runtime_root, lang))
+            if path.is_file():
+                files.add(path)
+            else:
+                raise RuntimeError(
+                    f"Final {lang} embedding index is missing: {path}"
+                )
+
+    return sorted(files, key=lambda p: str(p))
+
+
+def main() -> None:
+    # Critical: allow the original expensive builder only in this one-time build.
+    os.environ["HUDANET_SKIP_APP_INIT"] = "1"
+    os.environ["HUDANET_PREBUILT_BUILD_MODE"] = "1"
+
+    repo_id = os.getenv(
+        "HUDANET_PREBUILT_REPO_ID",
+        DEFAULT_REPO_ID,
+    ).strip()
+
+    read_token = os.getenv("HF_TOKEN", "").strip()
+    write_token = os.getenv("HF_WRITE_TOKEN", "").strip() or read_token
+
+    if not read_token:
+        raise RuntimeError(
+            "HF_TOKEN is missing. It must be able to read HUDA-Net private datasets."
+        )
+    if not write_token:
+        raise RuntimeError(
+            "HF_WRITE_TOKEN is missing. It must be able to create/write the "
+            "prebuilt retrieval dataset."
+        )
+
+    print("=" * 88)
+    print("🕋 HUDA-Net v41.0.2 ONE-TIME PREBUILT RETRIEVAL BUILD")
+    print("=" * 88)
+    print(f"Target dataset: {repo_id}")
+
+    # Import CURRENT app.py, but do not create the Gradio app.
+    hudanet = importlib.import_module("app")
+
+    prepare_fn = getattr(hudanet, "_prepare_kb_native_runtime_ui", None)
+    if not callable(prepare_fn):
+        raise RuntimeError(
+            "Current app.py does not expose _prepare_kb_native_runtime_ui()."
+        )
+
+    print("🧠 Running the original KB-native builder once...")
+    runtime_root, runtime_manifest = prepare_fn()
+    runtime_root = Path(runtime_root)
+
+    if not runtime_root.exists():
+        raise RuntimeError(f"Builder returned missing runtime root: {runtime_root}")
+
+    fingerprint_fn = getattr(hudanet, "_hybrid_fingerprint", None)
+    if not callable(fingerprint_fn):
+        raise RuntimeError("Current app.py has no _hybrid_fingerprint(df).")
+
+    # Resolve the dataframe from the current runtime without guessing schema.
+    # First try well-known module-level dataframe holders, then load the runtime records.
+    df = None
+    for candidate_name in (
+        "RUNTIME_DF",
+        "KB_DF",
+        "KNOWLEDGE_BASE_DF",
+        "DF",
+        "df",
+    ):
+        candidate = getattr(hudanet, candidate_name, None)
+        if candidate is not None and hasattr(candidate, "__len__") and hasattr(candidate, "columns"):
+            try:
+                if len(candidate) > 0:
+                    df = candidate
+                    break
+            except Exception:
+                pass
+
+    if df is None:
+        import pandas as pd
+
+        candidates = [
+            runtime_root / "records.parquet",
+            runtime_root / "records.csv.gz",
+            runtime_root / "records.csv",
+        ]
+        for path in candidates:
+            if not path.exists():
+                continue
+            if path.suffix == ".parquet":
+                df = pd.read_parquet(path)
+            else:
+                df = pd.read_csv(path, dtype=str, keep_default_na=False)
+            break
+
+    if df is None:
+        # v41 KB-native runtime may expose a dedicated loader.
+        loader_candidates = [
+            "_load_kb_native_dataframe",
+            "_load_knowledge_base_dataframe",
+            "load_knowledge_base",
+        ]
+        for name in loader_candidates:
+            fn = getattr(hudanet, name, None)
+            if callable(fn):
+                try:
+                    loaded = fn()
+                    if hasattr(loaded, "columns"):
+                        df = loaded
+                        break
+                    if isinstance(loaded, tuple):
+                        for item in loaded:
+                            if hasattr(item, "columns"):
+                                df = item
+                                break
+                except TypeError:
+                    continue
+
+    if df is None:
+        # Final reliable source: hybrid_manifest.json already contains the exact
+        # fingerprint produced by HUDA-Net's own build. We don't need to invent
+        # a second fingerprint implementation.
+        hybrid_manifest_name = str(
+            hudanet.HYBRID_FILES.get("hybrid_manifest", "hybrid_manifest.json")
+        )
+        hm_path = runtime_root / hybrid_manifest_name
+        if not hm_path.exists():
+            raise RuntimeError(
+                "Could not resolve the KB dataframe and hybrid_manifest.json is missing."
+            )
+        hybrid_meta = json.loads(hm_path.read_text(encoding="utf-8"))
+        fingerprint = str(hybrid_meta.get("fingerprint", ""))
+        records = int(hybrid_meta.get("records", 0))
+    else:
+        fingerprint = str(fingerprint_fn(df))
+        records = int(len(df))
+
+    if not fingerprint:
+        raise RuntimeError("Could not resolve HUDA-Net hybrid fingerprint.")
+
+    files = _collect_runtime_files(hudanet, runtime_root)
+
+    stage = Path(tempfile.mkdtemp(prefix="hudanet_v41_prebuilt_stage_"))
+    print(f"📦 Staging bundle at: {stage}")
+
+    try:
+        packaged_files: Dict[str, Dict[str, Any]] = {}
+
+        for source in files:
+            rel = _copy_file_preserve_relative(runtime_root, source, stage)
+            staged = stage / rel
+            packaged_files[rel] = {
+                "size": int(staged.stat().st_size),
+                "sha256": _sha256_file(staged),
+            }
+
+        hybrid_manifest_name = str(
+            hudanet.HYBRID_FILES.get("hybrid_manifest", "hybrid_manifest.json")
+        )
+
+        bundle_manifest = {
+            "schema_version": 1,
+            "created_at": _utc_now(),
+            "hudanet_version": str(getattr(hudanet, "VERSION", "unknown")),
+            "hybrid_asset_version": str(
+                getattr(hudanet, "HYBRID_ASSET_VERSION", "unknown")
+            ),
+            "fingerprint": fingerprint,
+            "records": records,
+            "hybrid_manifest_file": hybrid_manifest_name,
+            "source_runtime_root_name": runtime_root.name,
+            "files": packaged_files,
+        }
+
+        (stage / BUNDLE_MANIFEST).write_text(
+            json.dumps(bundle_manifest, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+        print(
+            f"✅ Bundle ready | {len(packaged_files)} runtime files | "
+            f"records={records} | fingerprint={fingerprint[:16]}..."
+        )
+
+        api = HfApi(token=write_token)
+        api.create_repo(
+            repo_id=repo_id,
+            repo_type="dataset",
+            private=True,
+            exist_ok=True,
+            token=write_token,
+        )
+
+        print("⬆️ Uploading prebuilt retrieval bundle to Hugging Face...")
+        api.upload_folder(
+            repo_id=repo_id,
+            repo_type="dataset",
+            folder_path=str(stage),
+            path_in_repo=".",
+            token=write_token,
+            commit_message=(
+                f"HUDA-Net prebuilt retrieval "
+                f"{getattr(hudanet, 'VERSION', 'v41')} "
+                f"{fingerprint[:12]}"
+            ),
+        )
+
+        print("=" * 88)
+        print("✅ PREBUILT RETRIEVAL DATASET PUBLISHED SUCCESSFULLY")
+        print(f"Repo       : {repo_id}")
+        print(f"Fingerprint: {fingerprint}")
+        print(f"Files      : {len(packaged_files)}")
+        print("=" * 88)
+
+    finally:
+        if os.getenv("HUDANET_KEEP_PREBUILT_STAGE", "0").strip().casefold() not in {
+            "1", "true", "yes", "on"
+        }:
+            shutil.rmtree(stage, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

hudanet_prebuilt_guard.py

@@ -0,0 +1,325 @@
+# -*- coding: utf-8 -*-
+"""
+HUDA-Net v41.0.2 Prebuilt Retrieval Guard
+=========================================
+
+Purpose
+-------
+Prevent Hugging Face Space startup from rebuilding BM25, dense E5 embeddings,
+and calibration assets for the full KB on every restart.
+
+Production behavior
+-------------------
+- Download one prebuilt retrieval bundle from a private Hugging Face Dataset.
+- Verify the bundle fingerprint against the CURRENT KB using HUDA-Net's own
+  _hybrid_fingerprint(df) function.
+- Verify every file SHA-256.
+- Restore the packaged hybrid files into the runtime target directory.
+- NEVER fall back to expensive production-time rebuilding.
+
+Build behavior
+--------------
+When HUDANET_PREBUILT_BUILD_MODE=1, this module does nothing so the original
+HUDA-Net builder can run once in an offline/build environment.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict, Mapping, MutableMapping, Optional, Tuple
+
+from huggingface_hub import snapshot_download
+
+
+BUNDLE_MANIFEST = "hudanet_prebuilt_bundle_v41.json"
+DEFAULT_REPO_ID = "dakheel/hudanet-v41-prebuilt-retrieval"
+DEFAULT_LOCAL_ROOT = Path("/tmp/hudanet_v41_prebuilt_retrieval")
+
+_BUNDLE_ROOT: Optional[Path] = None
+_INSTALLED = False
+
+
+def _truthy(value: Any) -> bool:
+    return str(value or "").strip().casefold() in {"1", "true", "yes", "on"}
+
+
+def _sha256_file(path: Path, chunk_size: int = 8 * 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        while True:
+            chunk = handle.read(chunk_size)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _safe_relative_path(value: str) -> Path:
+    rel = Path(str(value).replace("\\", "/"))
+    if rel.is_absolute() or ".." in rel.parts:
+        raise RuntimeError(f"Unsafe path in prebuilt bundle: {value!r}")
+    return rel
+
+
+def _link_or_copy(src: Path, dst: Path) -> None:
+    src = Path(src)
+    dst = Path(dst)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    if dst.exists() or dst.is_symlink():
+        if dst.is_dir() and not dst.is_symlink():
+            shutil.rmtree(dst)
+        else:
+            dst.unlink()
+
+    try:
+        os.link(src, dst)
+    except Exception:
+        shutil.copy2(src, dst)
+
+
+def _download_bundle() -> Path:
+    global _BUNDLE_ROOT
+
+    if _BUNDLE_ROOT is not None:
+        manifest = _BUNDLE_ROOT / BUNDLE_MANIFEST
+        if manifest.exists():
+            return _BUNDLE_ROOT
+
+    repo_id = os.getenv("HUDANET_PREBUILT_REPO_ID", DEFAULT_REPO_ID).strip()
+    token = os.getenv("HF_TOKEN", "").strip() or None
+    local_root = Path(
+        os.getenv("HUDANET_PREBUILT_LOCAL_ROOT", str(DEFAULT_LOCAL_ROOT))
+    )
+
+    local_root.mkdir(parents=True, exist_ok=True)
+
+    print(f"⬇️ Loading HUDA-Net prebuilt retrieval assets from {repo_id}...")
+
+    snapshot_download(
+        repo_id=repo_id,
+        repo_type="dataset",
+        token=token,
+        local_dir=str(local_root),
+        max_workers=8,
+    )
+
+    manifest = local_root / BUNDLE_MANIFEST
+    if not manifest.exists():
+        raise RuntimeError(
+            f"Prebuilt retrieval bundle is missing {BUNDLE_MANIFEST} in {repo_id}. "
+            "Run build_prebuilt_assets.py once before starting the Space."
+        )
+
+    _BUNDLE_ROOT = local_root
+    return local_root
+
+
+def _read_bundle_manifest(bundle_root: Path) -> Dict[str, Any]:
+    path = Path(bundle_root) / BUNDLE_MANIFEST
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise RuntimeError(f"Could not read prebuilt bundle manifest: {path}") from exc
+
+    if int(data.get("schema_version", 0)) != 1:
+        raise RuntimeError(
+            f"Unsupported HUDA-Net prebuilt schema: {data.get('schema_version')!r}"
+        )
+
+    files = data.get("files")
+    if not isinstance(files, dict) or not files:
+        raise RuntimeError("Prebuilt retrieval manifest has no files.")
+
+    return data
+
+
+def _validate_bundle(
+    ns: Mapping[str, Any],
+    df: Any,
+    bundle_root: Path,
+    bundle_meta: Mapping[str, Any],
+) -> str:
+    fingerprint_fn = ns.get("_hybrid_fingerprint")
+    if not callable(fingerprint_fn):
+        raise RuntimeError(
+            "HUDA-Net _hybrid_fingerprint(df) is unavailable. "
+            "The prebuilt guard must be installed after hybrid functions are defined."
+        )
+
+    current_fingerprint = str(fingerprint_fn(df))
+    packaged_fingerprint = str(bundle_meta.get("fingerprint", ""))
+
+    if not packaged_fingerprint:
+        raise RuntimeError("Prebuilt retrieval bundle does not contain a fingerprint.")
+
+    if packaged_fingerprint != current_fingerprint:
+        raise RuntimeError(
+            "HUDA-Net prebuilt retrieval assets are STALE for the current Knowledge Base.\n"
+            f"Current KB fingerprint : {current_fingerprint}\n"
+            f"Packaged fingerprint   : {packaged_fingerprint}\n"
+            "Run build_prebuilt_assets.py again and publish the new bundle. "
+            "Production-time rebuilding is intentionally disabled."
+        )
+
+    files = bundle_meta["files"]
+    for rel_text, file_meta in files.items():
+        rel = _safe_relative_path(rel_text)
+        src = Path(bundle_root) / rel
+
+        if not src.is_file():
+            raise RuntimeError(f"Missing prebuilt retrieval file: {rel}")
+
+        expected_size = int(file_meta.get("size", -1))
+        actual_size = src.stat().st_size
+        if expected_size >= 0 and actual_size != expected_size:
+            raise RuntimeError(
+                f"Prebuilt file size mismatch for {rel}: "
+                f"expected={expected_size}, actual={actual_size}"
+            )
+
+        expected_sha = str(file_meta.get("sha256", "")).strip().lower()
+        if expected_sha:
+            actual_sha = _sha256_file(src)
+            if actual_sha.lower() != expected_sha:
+                raise RuntimeError(
+                    f"Prebuilt file SHA-256 mismatch for {rel}: "
+                    f"expected={expected_sha}, actual={actual_sha}"
+                )
+
+    return current_fingerprint
+
+
+def _restore_bundle_to_target(
+    ns: Mapping[str, Any],
+    df: Any,
+    target_root: Path,
+) -> Tuple[Path, Dict[str, Any]]:
+    target_root = Path(target_root)
+    target_root.mkdir(parents=True, exist_ok=True)
+
+    bundle_root = _download_bundle()
+    bundle_meta = _read_bundle_manifest(bundle_root)
+    fingerprint = _validate_bundle(ns, df, bundle_root, bundle_meta)
+
+    copied = 0
+    for rel_text in bundle_meta["files"].keys():
+        rel = _safe_relative_path(rel_text)
+        src = bundle_root / rel
+        dst = target_root / rel
+        _link_or_copy(src, dst)
+        copied += 1
+
+    hybrid_files = ns.get("HYBRID_FILES")
+    if not isinstance(hybrid_files, Mapping):
+        raise RuntimeError("HUDA-Net HYBRID_FILES mapping is unavailable.")
+
+    hybrid_manifest_name = str(
+        bundle_meta.get(
+            "hybrid_manifest_file",
+            hybrid_files.get("hybrid_manifest", "hybrid_manifest.json"),
+        )
+    )
+    hybrid_manifest_path = target_root / _safe_relative_path(hybrid_manifest_name)
+
+    if not hybrid_manifest_path.exists():
+        raise RuntimeError(
+            f"Restored prebuilt bundle but hybrid manifest is missing: "
+            f"{hybrid_manifest_path}"
+        )
+
+    try:
+        hybrid_meta = json.loads(hybrid_manifest_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise RuntimeError(
+            f"Could not parse restored hybrid manifest: {hybrid_manifest_path}"
+        ) from exc
+
+    if str(hybrid_meta.get("fingerprint", "")) != fingerprint:
+        raise RuntimeError(
+            "Restored hybrid_manifest.json fingerprint does not match the current KB."
+        )
+
+    required_names = list(hybrid_files.values())
+    missing = [
+        name for name in required_names
+        if not (target_root / str(name)).exists()
+    ]
+    if missing:
+        raise RuntimeError(
+            "Prebuilt retrieval bundle is incomplete. Missing runtime files: "
+            + ", ".join(map(str, missing))
+        )
+
+    print(
+        f"⚡ HUDA-Net prebuilt retrieval restored | "
+        f"{copied} files | fingerprint={fingerprint[:16]}..."
+    )
+    return target_root, hybrid_meta
+
+
+def install_prebuilt_guard(ns: MutableMapping[str, Any]) -> None:
+    """
+    Install production-only wrappers into app.py globals().
+
+    Call this ONCE near the bottom of app.py, immediately before HUDA_DEMO is
+    created. In build mode the wrappers are intentionally not installed.
+    """
+    global _INSTALLED
+
+    if _INSTALLED:
+        return
+
+    if _truthy(os.getenv("HUDANET_PREBUILT_BUILD_MODE", "0")):
+        print("🛠️ HUDA-Net prebuilt BUILD MODE: original hybrid builder remains enabled.")
+        _INSTALLED = True
+        return
+
+    original_build = ns.get("build_hybrid_runtime_assets")
+    if not callable(original_build):
+        raise RuntimeError(
+            "build_hybrid_runtime_assets is not defined yet. "
+            "Install the prebuilt guard near the bottom of app.py."
+        )
+
+    def build_hybrid_runtime_assets_prebuilt(
+        df: Any,
+        sparse_assets: Mapping[str, Any],
+        target_root: Path,
+        *,
+        force: bool = False,
+        previous_root: Optional[Path] = None,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        del sparse_assets, force, previous_root, kwargs
+        _, meta = _restore_bundle_to_target(ns, df, Path(target_root))
+        return meta
+
+    ns["_build_hybrid_runtime_assets_original_v41_0_1"] = original_build
+    ns["build_hybrid_runtime_assets"] = build_hybrid_runtime_assets_prebuilt
+
+    original_ensure = ns.get("ensure_hybrid_runtime_assets")
+    if callable(original_ensure):
+        def ensure_hybrid_runtime_assets_prebuilt(
+            df: Any,
+            sparse_assets: Mapping[str, Any],
+            runtime_root: Path,
+            *args: Any,
+            **kwargs: Any,
+        ) -> Tuple[Path, Dict[str, Any]]:
+            del sparse_assets, args, kwargs
+            root, meta = _restore_bundle_to_target(ns, df, Path(runtime_root))
+            return root, meta
+
+        ns["_ensure_hybrid_runtime_assets_original_v41_0_1"] = original_ensure
+        ns["ensure_hybrid_runtime_assets"] = ensure_hybrid_runtime_assets_prebuilt
+
+    _INSTALLED = True
+    print(
+        "🔒 HUDA-Net v41.0.2 prebuilt retrieval guard active | "
+        "production rebuild fallback disabled"
+    )

patch_app_v41_0_2.py

@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+"""
+HUDA-Net v41.0.2 app.py Patcher
+===============================
+
+Run once in the SAME folder as the CURRENT v41.0.1 app.py:
+
+    python patch_app_v41_0_2.py
+
+It will:
+- create a backup of app.py,
+- change visible 41.0.1 version strings to 41.0.2,
+- install hudanet_prebuilt_guard immediately before HUDA_DEMO creation,
+- compile-check the modified app.py,
+- restore the backup automatically if syntax validation fails.
+
+This patcher does NOT replace your v41 logic and does NOT overwrite the
+10,000+ line application with an older copy.
+"""
+
+from __future__ import annotations
+
+import py_compile
+import re
+import shutil
+from pathlib import Path
+
+
+APP = Path("app.py")
+GUARD = Path("hudanet_prebuilt_guard.py")
+BACKUP = Path("app.py.v41_0_1.backup")
+
+MARKER = "# HUDA-Net v41.0.2 prebuilt retrieval startup guard"
+INJECTION = f"""
+{MARKER}
+from hudanet_prebuilt_guard import install_prebuilt_guard as _install_hudanet_prebuilt_guard
+_install_hudanet_prebuilt_guard(globals())
+
+"""
+
+
+def main() -> None:
+    if not APP.is_file():
+        raise RuntimeError("app.py was not found in the current folder.")
+
+    if not GUARD.is_file():
+        raise RuntimeError(
+            "hudanet_prebuilt_guard.py was not found beside app.py."
+        )
+
+    original = APP.read_text(encoding="utf-8")
+
+    if MARKER in original:
+        print("ℹ️ v41.0.2 prebuilt guard is already installed.")
+        py_compile.compile(str(APP), doraise=True)
+        print("✅ app.py syntax check passed.")
+        return
+
+    # The v41.0.1 logs prove this startup assignment exists.
+    match = re.search(
+        r"(?m)^(?P<indent>[ \t]*)HUDA_DEMO\s*=\s*None\s+if\s+os\.getenv\("
+        r"[\"']HUDANET_SKIP_APP_INIT[\"']",
+        original,
+    )
+
+    if not match:
+        # Fallback for formatting changes while keeping the same variable.
+        match = re.search(r"(?m)^(?P<indent>[ \t]*)HUDA_DEMO\s*=", original)
+
+    if not match:
+        raise RuntimeError(
+            "Could not find the HUDA_DEMO startup assignment. "
+            "No changes were made."
+        )
+
+    if BACKUP.exists():
+        raise RuntimeError(
+            f"Backup already exists: {BACKUP}. "
+            "Move/delete it only if you intentionally want a new backup."
+        )
+
+    shutil.copy2(APP, BACKUP)
+
+    try:
+        updated = original.replace("41.0.1", "41.0.2")
+        insertion_at = match.start()
+
+        # Because version replacement does not change text length for 41.0.1 -> 41.0.2,
+        # the original match offset remains correct.
+        updated = updated[:insertion_at] + INJECTION + updated[insertion_at:]
+
+        APP.write_text(updated, encoding="utf-8")
+        py_compile.compile(str(APP), doraise=True)
+
+    except Exception:
+        shutil.copy2(BACKUP, APP)
+        raise
+
+    print("✅ app.py patched to HUDA-Net v41.0.2.")
+    print(f"✅ Backup created: {BACKUP}")
+    print("✅ Prebuilt retrieval guard inserted before HUDA_DEMO creation.")
+    print("✅ Python syntax validation passed.")
+
+
+if __name__ == "__main__":
+    main()