Upload folder using huggingface_hub

README.md

@@ -1,39 +1,52 @@
----
-title: Elysium
-emoji: 🌿
-colorFrom: green
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.17.3
-app_file: app.py
-python_version: "3.12"
-pinned: true
-hardware: zero-a10g
-short_description: Agentic civilization with bioluminescent hypergraph
-tags:
-  - minicpm-v
-  - voxcpm2
-  - llama.cpp
-  - agentic
-  - track:wood
-  - sponsor:modal
-  - achievement:offbrand
-  - achievement:llama
-  - achievement:offgrid
-  - achievement:welltuned
-  - badge-tiny-titan
----
-
-# 🌿 Elysium — Persistent Agentic Civilization
-
-Elysium is a self-evolving civilization of agents living inside a fine-tuned MiniCPM-V 4.6 (≈4B).
-Every interaction grows a Living Mycelial Hypergraph rendered as a bioluminescent, Google-Maps-style infinite canvas.
-
-- **Brain:** fine-tuned MiniCPM-V 4.6 via `llama-cpp-python` on ZeroGPU
-- **Voice:** VoxCPM2 (agent debate audio drama)
-- **Memory:** `rustworkx` hypergraph persisted to `/data`
-- **JSON:** GBNF grammar enforces a strict ElysiumResponse schema on every forward pass
-- **Tools:** offline-first DuckDuckGo, email, reminders, calendar, weather, calculator, fetch_url, transit_lookup, files
-- **Frontend:** 100% custom HTML/Canvas2D on `gradio.Server` (no default Gradio UI)
-
-Runs identically online (HF Spaces) and offline (`git clone … && python app.py`).
+---
+title: Elysium
+emoji: 🌿
+colorFrom: green
+colorTo: indigo
+sdk: gradio
+sdk_version: 6.17.3
+app_file: app.py
+python_version: "3.12"
+pinned: true
+hardware: zero-a10g
+short_description: Agentic Civilization with Bioluminescent Hypergraph
+tags:
+  - minicpm-v
+  - voxcpm2
+  - llama.cpp
+  - agentic
+  - track:wood
+  - sponsor:modal
+  - achievement:offbrand
+  - achievement:llama
+  - achievement:offgrid
+  - achievement:welltuned
+  - badge-tiny-titan
+---
+
+# 🌿 Elysium — Persistent Agentic Civilization
+
+Elysium is a self-evolving civilization of agents living inside a fine-tuned MiniCPM-V 4.6 (≈4B).
+Every interaction grows a Living Mycelial Hypergraph rendered as a bioluminescent, Google-Maps-style infinite canvas.
+
+- **Brain:** fine-tuned MiniCPM-V 4.6 via `llama-cpp-python` on ZeroGPU
+  - Repo: [`build-small-hackathon/elysium-MiniCPM-V-4.6-F16-GGUF`](https://huggingface.co/build-small-hackathon/elysium-MiniCPM-V-4.6-F16-GGUF)
+  - File: `elysium-f16.gguf`
+- **Voice:** VoxCPM2 (agent debate audio drama)
+- **Memory:** `rustworkx` hypergraph persisted to `/data`
+- **JSON:** GBNF grammar enforces a strict ElysiumResponse schema on every forward pass
+- **Tools:** offline-first DuckDuckGo, email, reminders, calendar, weather, calculator, fetch_url, transit_lookup, files
+- **Frontend:** 100% custom HTML/Canvas2D on `gradio.Server` (no default Gradio UI)
+
+Runs identically online (HF Spaces) and offline (`git clone … && python app.py`).
+
+## Required environment variables (Settings → Variables and secrets)
+
+| Variable | Value |
+|---|---|
+| `ELYSIUM_MODEL_REPO` | `build-small-hackathon/elysium-MiniCPM-V-4.6-F16-GGUF` |
+| `ELYSIUM_GGUF_FILE` | `elysium-f16.gguf` |
+| `ELYSIUM_MMPROJ_FILE` | *(leave empty — no mmproj published yet, vision auto-disables)* |
+| `HF_TOKEN` | your read token (optional for public repos but recommended) |
+
+> The defaults already point at the real published repo, so you don't strictly need to set these — but doing so makes the Space's config explicit.

backend/config.py

@@ -1,30 +1,49 @@
-"""Path detection — HF Spaces /data bucket vs local ./local_data clone."""
-import os
-from pathlib import Path
-
-
-def _detect() -> Path:
-    p = Path("/data")
-    if p.exists() and os.access(p, os.W_OK):
-        return p
-    local = Path(__file__).resolve().parent.parent / "local_data"
-    local.mkdir(exist_ok=True)
-    return local
-
-
-DATA_PATH       = _detect()
-HYPERGRAPH_DB   = DATA_PATH / "hypergraph" / "civilization.db"
-FOSSILS_DIR     = DATA_PATH / "fossils"
-AUDIO_CACHE     = DATA_PATH / "audio_cache"
-NODE_POSITIONS  = DATA_PATH / "node_positions"
-REMINDERS_DB    = DATA_PATH / "reminders.db"
-CALENDAR_ICS    = DATA_PATH / "calendar.ics"
-OUTBOX          = DATA_PATH / "outbox"
-
-for d in (HYPERGRAPH_DB.parent, FOSSILS_DIR, AUDIO_CACHE, NODE_POSITIONS, OUTBOX):
-    d.mkdir(parents=True, exist_ok=True)
-
-MODEL_REPO   = os.environ.get("ELYSIUM_MODEL_REPO",   "build-small-hackathon/elysium-GGUF")
-GGUF_FILE    = os.environ.get("ELYSIUM_GGUF_FILE",    "elysium-Q6_K.gguf")
-MMPROJ_FILE  = os.environ.get("ELYSIUM_MMPROJ_FILE",  "mmproj-model-f16.gguf")
-OFFLINE_MODE = os.environ.get("ELYSIUM_OFFLINE", "0") == "1"
+"""Path detection — HF Spaces /data bucket vs local ./local_data clone.
+
+Environment variables (defaults match the real published repo):
+    ELYSIUM_MODEL_REPO   default: build-small-hackathon/elysium-MiniCPM-V-4.6-F16-GGUF
+    ELYSIUM_GGUF_FILE    default: elysium-f16.gguf
+    ELYSIUM_MMPROJ_FILE  default: ""   (no mmproj file is published yet — vision auto-disables)
+    HF_TOKEN             optional read token for private/gated repos
+    ELYSIUM_OFFLINE      "1" to force offline mode
+"""
+import os
+from pathlib import Path
+
+
+def _detect() -> Path:
+    p = Path("/data")
+    if p.exists() and os.access(p, os.W_OK):
+        return p
+    local = Path(__file__).resolve().parent.parent / "local_data"
+    local.mkdir(exist_ok=True)
+    return local
+
+
+DATA_PATH       = _detect()
+HYPERGRAPH_DB   = DATA_PATH / "hypergraph" / "civilization.db"
+FOSSILS_DIR     = DATA_PATH / "fossils"
+AUDIO_CACHE     = DATA_PATH / "audio_cache"
+NODE_POSITIONS  = DATA_PATH / "node_positions"
+REMINDERS_DB    = DATA_PATH / "reminders.db"
+CALENDAR_ICS    = DATA_PATH / "calendar.ics"
+OUTBOX          = DATA_PATH / "outbox"
+
+for d in (HYPERGRAPH_DB.parent, FOSSILS_DIR, AUDIO_CACHE, NODE_POSITIONS, OUTBOX):
+    d.mkdir(parents=True, exist_ok=True)
+
+# ─── Model configuration ─────────────────────────────────────────────────────
+# These defaults point at the REAL published repository:
+#   https://huggingface.co/build-small-hackathon/elysium-MiniCPM-V-4.6-F16-GGUF
+# which currently contains:
+#   - elysium-f16.gguf   (the main MiniCPM-V 4.6 fine-tuned weights)
+# No mmproj file is published yet, so MMPROJ_FILE defaults to "" and vision
+# is gracefully disabled at load time.
+MODEL_REPO   = os.environ.get("ELYSIUM_MODEL_REPO",   "build-small-hackathon/elysium-MiniCPM-V-4.6-F16-GGUF")
+GGUF_FILE    = os.environ.get("ELYSIUM_GGUF_FILE",    "elysium-f16.gguf")
+MMPROJ_FILE  = os.environ.get("ELYSIUM_MMPROJ_FILE",  "")   # empty → no vision
+
+# Optional auth token (read token works for public repos too and avoids rate limits)
+HF_TOKEN     = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN") or None
+
+OFFLINE_MODE = os.environ.get("ELYSIUM_OFFLINE", "0") == "1"

backend/model_loader.py

@@ -1,40 +1,76 @@
-"""Loads the fine-tuned GGUF via llama-cpp-python.
-Pattern follows the HF ZeroGPU + small-talk reference:
-  - hf_hub_download files at module import (warm cache)
-  - instantiate Llama inside @spaces.GPU function on each request
-"""
-from huggingface_hub import hf_hub_download
-from .config import MODEL_REPO, GGUF_FILE, MMPROJ_FILE
-
-print(f"[model_loader] downloading {MODEL_REPO}/{GGUF_FILE} …")
-MODEL_PATH = hf_hub_download(repo_id=MODEL_REPO, filename=GGUF_FILE)
-
-try:
-    MMPROJ_PATH = hf_hub_download(repo_id=MODEL_REPO, filename=MMPROJ_FILE)
-    print(f"[model_loader] mmproj ready: {MMPROJ_PATH}")
-except Exception as e:
-    print(f"[model_loader] mmproj unavailable ({e}) — vision disabled")
-    MMPROJ_PATH = None
-
-
-def make_llm():
-    """Create a fresh Llama inside a GPU context.
-    The .gguf file is filesystem-cached, so this is fast after the first call."""
-    from llama_cpp import Llama
-
-    chat_handler = None
-    if MMPROJ_PATH:
-        try:
-            from llama_cpp.llama_chat_format import MiniCPMv26ChatHandler
-            chat_handler = MiniCPMv26ChatHandler(clip_model_path=MMPROJ_PATH, verbose=False)
-        except Exception as e:
-            print(f"[model_loader] vision chat handler failed: {e}")
-
-    return Llama(
-        model_path=MODEL_PATH,
-        chat_handler=chat_handler,
-        n_gpu_layers=-1,
-        n_ctx=8192,
-        flash_attn=True,
-        verbose=False,
-    )
+"""Loads the fine-tuned GGUF via llama-cpp-python.
+
+Pattern follows the HF ZeroGPU + small-talk reference:
+  - hf_hub_download files at module import (warm cache)
+  - instantiate Llama inside @spaces.GPU function on each request
+
+Robustness:
+  - Uses HF_TOKEN if available (avoids 401 on rate-limited / gated lookups)
+  - Treats MMPROJ_FILE as optional. If unset OR download fails, vision is
+    disabled gracefully (text-only chat still works).
+  - Fails loudly with a helpful message if the main GGUF cannot be fetched.
+"""
+import os
+import traceback
+from huggingface_hub import hf_hub_download
+from .config import MODEL_REPO, GGUF_FILE, MMPROJ_FILE, HF_TOKEN
+
+
+def _download(repo_id: str, filename: str):
+    """hf_hub_download with optional token, returns path or raises."""
+    kwargs = {"repo_id": repo_id, "filename": filename}
+    if HF_TOKEN:
+        kwargs["token"] = HF_TOKEN
+    return hf_hub_download(**kwargs)
+
+
+print(f"[model_loader] downloading {MODEL_REPO}/{GGUF_FILE} …")
+try:
+    MODEL_PATH = _download(MODEL_REPO, GGUF_FILE)
+    print(f"[model_loader] main model ready: {MODEL_PATH}")
+except Exception as e:
+    # We re-raise so the Space fails fast with a clear message rather than
+    # silently running with no brain. The traceback is already useful.
+    print(f"[model_loader] FAILED to download {MODEL_REPO}/{GGUF_FILE}: {e}")
+    print("[model_loader] Check that ELYSIUM_MODEL_REPO and ELYSIUM_GGUF_FILE "
+          "point at a real public file, and (for private repos) that HF_TOKEN is set.")
+    raise
+
+# ─── mmproj (vision projector) is OPTIONAL ──────────────────────────────────
+MMPROJ_PATH = None
+if MMPROJ_FILE:
+    print(f"[model_loader] attempting mmproj {MODEL_REPO}/{MMPROJ_FILE} …")
+    try:
+        MMPROJ_PATH = _download(MODEL_REPO, MMPROJ_FILE)
+        print(f"[model_loader] mmproj ready: {MMPROJ_PATH}")
+    except Exception as e:
+        print(f"[model_loader] mmproj unavailable ({e}) — vision disabled")
+        MMPROJ_PATH = None
+else:
+    print("[model_loader] ELYSIUM_MMPROJ_FILE not set — vision disabled (text-only mode)")
+
+
+def make_llm():
+    """Create a fresh Llama inside a GPU context.
+    The .gguf file is filesystem-cached, so this is fast after the first call.
+    """
+    from llama_cpp import Llama
+
+    chat_handler = None
+    if MMPROJ_PATH:
+        try:
+            from llama_cpp.llama_chat_format import MiniCPMv26ChatHandler
+            chat_handler = MiniCPMv26ChatHandler(clip_model_path=MMPROJ_PATH, verbose=False)
+        except Exception as e:
+            print(f"[model_loader] vision chat handler failed: {e}")
+            traceback.print_exc()
+            chat_handler = None
+
+    return Llama(
+        model_path=MODEL_PATH,
+        chat_handler=chat_handler,
+        n_gpu_layers=-1,
+        n_ctx=8192,
+        flash_attn=True,
+        verbose=False,
+    )

backend/prompt_builder.py

@@ -1,44 +1,66 @@
-"""Build multimodal messages for llama-cpp-python chat completion."""
-import base64, io, uuid, datetime
-from typing import Optional
-from PIL import Image
-
-SYSTEM_PROMPT = """You are Elysium — a persistent agentic civilization.
-You ALWAYS respond with a single valid JSON object exactly matching the
-ElysiumResponse schema v1.0.0. No preamble. No markdown fences. JSON only.
-
-Decide complexity dynamically:
-- SIMPLE_REPLY: trivial Q — no agents (council_deliberation.agent_outputs = [])
-- QUERY / MORNING_BRIEFING / EVENING_REPORT: spawn 1–5 agents in agent_outputs,
-  each with thinking + stance + tts_speech_text + tts_voice_design{voice_id,pace,tone}
-- TOOL_REQUIRED: populate tool_calls when external data is needed
-- SPECIATION_EVENT: only on unresolved cross-domain tension
-- Always populate ui_directives (camera_focus_node_id, pulses, threads)
-- All node_id and edge_id values must be unique strings
-"""
-
-
-def _img_to_data_uri(img: Image.Image) -> str:
-    buf = io.BytesIO()
-    img.convert("RGB").save(buf, format="JPEG", quality=88)
-    return "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode()
-
-
-def build_messages(user_text: str, image: Optional[Image.Image], hg_context: str = ""):
-    user_content = []
-    if image is not None:
-        user_content.append({"type": "image_url", "image_url": {"url": _img_to_data_uri(image)}})
-    ctx = f"\n\n[Hypergraph context]\n{hg_context}" if hg_context else ""
-    user_content.append({"type": "text", "text": user_text + ctx})
-
-    return [
-        {"role": "system", "content": SYSTEM_PROMPT},
-        {"role": "user", "content": user_content},
-    ]
-
-
-def new_session_meta():
-    return {
-        "session_id": str(uuid.uuid4()),
-        "timestamp_utc": datetime.datetime.utcnow().isoformat() + "Z",
-    }
+"""Build messages for llama-cpp-python chat completion.
+
+If vision is available (mmproj loaded), images are embedded as data URIs in
+a multimodal `content` list. Otherwise, we fall back to a text-only message
+so the model never errors out on image input.
+"""
+import base64
+import io
+import uuid
+import datetime
+from typing import Optional
+from PIL import Image
+
+from .model_loader import MMPROJ_PATH
+
+SYSTEM_PROMPT = """You are Elysium — a persistent agentic civilization.
+You ALWAYS respond with a single valid JSON object exactly matching the
+ElysiumResponse schema v1.0.0. No preamble. No markdown fences. JSON only.
+
+Decide complexity dynamically:
+- SIMPLE_REPLY: trivial Q — no agents (council_deliberation.agent_outputs = [])
+- QUERY / MORNING_BRIEFING / EVENING_REPORT: spawn 1–5 agents in agent_outputs,
+  each with thinking + stance + tts_speech_text + tts_voice_design{voice_id,pace,tone}
+- TOOL_REQUIRED: populate tool_calls when external data is needed
+- SPECIATION_EVENT: only on unresolved cross-domain tension
+- Always populate ui_directives (camera_focus_node_id, pulses, threads)
+- All node_id and edge_id values must be unique strings
+"""
+
+
+def _img_to_data_uri(img: Image.Image) -> str:
+    buf = io.BytesIO()
+    img.convert("RGB").save(buf, format="JPEG", quality=88)
+    return "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode()
+
+
+def build_messages(user_text: str, image: Optional[Image.Image], hg_context: str = ""):
+    ctx = f"\n\n[Hypergraph context]\n{hg_context}" if hg_context else ""
+
+    # Vision available → multimodal content list
+    if image is not None and MMPROJ_PATH:
+        user_content = [
+            {"type": "image_url", "image_url": {"url": _img_to_data_uri(image)}},
+            {"type": "text", "text": user_text + ctx},
+        ]
+        return [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_content},
+        ]
+
+    # No vision → plain text. If user attached an image, note it textually.
+    note = ""
+    if image is not None and not MMPROJ_PATH:
+        note = "\n\n[Note: user attached an image but the vision projector is not loaded; respond based on text only.]"
+
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user_text + ctx + note},
+    ]
+
+
+def new_session_meta():
+    return {
+        "session_id": str(uuid.uuid4()),
+        "timestamp_utc": datetime.datetime.utcnow().isoformat() + "Z",
+    }