Switch to HF Space as default backend, make Ollama optional

README.md

@@ -0,0 +1,44 @@
+---
+title: KnowLedge Inference API
+emoji: 📖
+colorFrom: yellow
+colorTo: green
+sdk: gradio
+python_version: 3.10.16
+sdk_version: 4.44.1
+app_file: app.py
+pinned: true
+license: apache-2.0
+tags:
+  - gemma
+  - gemma-4
+  - education
+  - inference-api
+  - knowledge
+  - hackathon
+---
+
+# KnowLedge Inference API
+
+Gemma 4 E2B + E4B inference backend for the
+[KnowLedge](https://github.com/Charan-suresh/KnowLedge) learning ledger.
+
+Part of the Kaggle Gemma 4 Good Hackathon submission.
+
+## Endpoints
+
+| Endpoint | Model | Used by |
+|---|---|---|
+| `/api/generate` | E2B or E4B | Scout (concept tagging), Sage (Socratic dialogue) |
+| `/api/generate_vision` | E4B vision | Lens (handwriting verification) |
+| `/api/health` | - | FastAPI health check |
+
+## Not for direct use
+
+This Space is called programmatically by the KnowLedge FastAPI backend
+deployed on Render. It is not a chat interface.
+
+## Deployment note
+
+Deploy these files to a separate Hugging Face Space repository.
+Do not import from the `knowledge/` package inside the Space app.

app.py

@@ -0,0 +1,62 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+import uvicorn
+
+try:
+    from inference import generate_text, generate_with_image, health_check
+except ModuleNotFoundError:
+    from .inference import generate_text, generate_with_image, health_check
+
+app = FastAPI()
+
+
+class GenerateRequest(BaseModel):
+    prompt: str
+    model: str = "e2b"
+    max_tokens: int = 512
+
+
+class VisionRequest(BaseModel):
+    prompt: str
+    image_base64: str
+    max_tokens: int = 512
+
+
+@app.get("/")
+def root():
+    return {"message": "KnowLedge Inference API is running"}
+
+
+@app.get("/api/health")
+def health():
+    try:
+        return health_check()
+    except Exception as exc:
+        return {"status": "error", "error": str(exc)}
+
+
+@app.post("/api/generate")
+def generate(req: GenerateRequest):
+    try:
+        model_name = "e2b" if "e2b" in req.model.lower() else "e4b"
+        response = generate_text(model_name, req.prompt, req.max_tokens)
+        return {"response": response}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+@app.post("/api/generate_vision")
+def generate_vision(req: VisionRequest):
+    try:
+        response = generate_with_image(
+            req.prompt,
+            req.image_base64,
+            req.max_tokens,
+        )
+        return {"response": response}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)

deploy.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# KnowLedge - Hugging Face Space deployment guide
+# Run each block manually in sequence.
+# Prerequisites: huggingface_hub installed, HF account created
+
+# -- Step 1: Install HF CLI -------------------------------------------------
+pip install huggingface_hub
+
+# -- Step 2: Login to Hugging Face ------------------------------------------
+huggingface-cli login
+# Paste your HF token when prompted
+# Get token at: https://huggingface.co/settings/tokens
+# Token needs "write" permission
+
+# -- Step 3: Create the Space ------------------------------------------------
+python3 - << 'EOF'
+from huggingface_hub import HfApi
+api = HfApi()
+api.create_repo(
+    repo_id="knowledge-inference",   # becomes: your-username/knowledge-inference
+    repo_type="space",
+    space_sdk="gradio",
+    private=False,                    # must be public for free ZeroGPU
+    exist_ok=True,
+)
+print("Space created successfully")
+EOF
+
+# -- Step 4: Upload Space files ----------------------------------------------
+python3 - << 'EOF'
+from huggingface_hub import HfApi
+import os
+
+api = HfApi()
+space_id = f"{api.whoami()['name']}/knowledge-inference"
+base_dir = os.getcwd()
+
+files = ["app.py", "inference.py", "requirements.txt", "README.md"]
+for f in files:
+    path = os.path.join(base_dir, f)
+    api.upload_file(
+        path_or_fileobj=path,
+        path_in_repo=f,
+        repo_id=space_id,
+        repo_type="space",
+    )
+    print(f"Uploaded: {f}")
+
+print(f"\nSpace URL: https://huggingface.co/spaces/{space_id}")
+print(f"API URL:   https://{space_id.replace('/', '-')}.hf.space")
+EOF
+
+# -- Step 5: Enable ZeroGPU --------------------------------------------------
+# Go to: https://huggingface.co/spaces/YOUR-USERNAME/knowledge-inference/settings
+# Under "Space Hardware" -> select "ZeroGPU (NVIDIA H200)"
+# This cannot be done via API - must be done in the HF web UI
+echo "-> Manually enable ZeroGPU in Space settings:"
+echo "  https://huggingface.co/spaces/$(huggingface-cli whoami)/knowledge-inference/settings"
+
+# -- Step 6: Get your Space API URL ------------------------------------------
+# After deployment (~3-5 minutes for build), your endpoints are:
+# Text:   POST https://your-username-knowledge-inference.hf.space/api/generate
+# Vision: POST https://your-username-knowledge-inference.hf.space/api/generate_vision
+# Health: GET  https://your-username-knowledge-inference.hf.space/api/health
+
+# -- Step 7: Set Render env vars ---------------------------------------------
+# In Render dashboard -> your service -> Environment:
+# INFERENCE_BACKEND = hf_space
+# HF_SPACE_URL      = your-username/knowledge-inference
+# Then trigger a manual redeploy on Render.
+
+echo "Deployment complete. Set HF_SPACE_URL in Render and redeploy."

inference.py

@@ -0,0 +1,108 @@
+"""
+KnowLedge Inference — inference.py
+
+Runs entirely on CPU on the standard free HF Spaces tier (no ZeroGPU).
+
+Model backends
+--------------
+E4B  : unsloth/gemma-4-4b-it-GGUF loaded via llama-cpp-python (CPU, n_gpu_layers=0).
+"""
+
+import logging
+
+from huggingface_hub import hf_hub_download
+
+# ── spaces stub — GPU decorator is a no-op on the free CPU tier ───────────────
+try:
+    import spaces
+except ModuleNotFoundError:
+    class _SpacesStub:
+        @staticmethod
+        def GPU(duration: int = 0):
+            def decorator(fn):
+                return fn
+            return decorator
+
+    spaces = _SpacesStub()
+
+# ── llama-cpp-python ──────────────────────────────────────────────────────────
+try:
+    from llama_cpp import Llama
+except ModuleNotFoundError:
+    Llama = None
+
+
+MODEL_REPO = "unsloth/gemma-4-4b-it-GGUF"
+MODEL_FILE = "gemma-4-4b-it-Q4_K_M.gguf"
+
+_llm = None
+logger = logging.getLogger(__name__)
+
+
+def load_model():
+    global _llm
+    if _llm is None:
+        if Llama is None:
+            raise RuntimeError(
+                "llama-cpp-python is not installed. "
+                "Add it to hf_space/requirements.txt."
+            )
+        model_path = str(hf_hub_download(
+            repo_id=MODEL_REPO,
+            filename=MODEL_FILE
+        ))
+
+        _llm = Llama(
+            model_path=model_path,
+            n_ctx=4096,
+            n_threads=4
+        )
+    return _llm
+
+
+@spaces.GPU(duration=90)
+def generate_text(model_name: str, prompt: str, max_new_tokens: int = 512) -> str:
+    try:
+        llm = load_model()
+
+        output = llm(
+            str(prompt),
+            max_tokens=max_new_tokens,
+            temperature=0.7,
+            top_p=0.95
+        )
+
+        return output["choices"][0]["text"]
+
+    except Exception:
+        logger.exception("Text generation failed")
+        raise
+
+
+@spaces.GPU(duration=120)
+def generate_with_image(prompt: str, image_base64: str, max_new_tokens: int = 512) -> str:
+    try:
+        llm = load_model()
+
+        text_prompt = f"{prompt}\n\n[Image provided]"
+
+        output = llm(
+            str(text_prompt),
+            max_tokens=max_new_tokens,
+            temperature=0.7,
+            top_p=0.95
+        )
+
+        return output["choices"][0]["text"]
+
+    except Exception:
+        logger.exception("Vision generation failed")
+        raise
+
+
+@spaces.GPU(duration=60)
+def health_check() -> dict:
+    return {
+        "status": "ok",
+        "model_loaded": _llm is not None,
+    }

requirements.txt

@@ -0,0 +1,11 @@
+fastapi==0.112.2
+uvicorn==0.30.6
+gradio==4.44.1
+
+# Inference - E4B via llama-cpp-python (GGUF, CPU-only, no ZeroGPU needed)
+--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+llama-cpp-python==0.2.90
+
+# Utilities
+Pillow
+huggingface_hub==0.25.2

runtime.txt

@@ -0,0 +1 @@
+python-3.10.16