Upload 7 files

.gitignore

@@ -1,2 +1,5 @@
-# OpenMemory - IDE/Assistant specific rules
-.windsurf\rules\openmemory.md
+# Baked into the Docker image at build time — do not commit.
+models/
+.cache/
+__pycache__/
+*.pyc

Dockerfile

@@ -1,81 +1,59 @@
-# Ornith-1.0-9B on a Hugging Face Space (Docker SDK) — OpenAI-compatible API.
+# CPU + FREE-tier RAG Space (Docker SDK).
+#   Embeddings : BAAI/bge-small-en-v1.5  (fastembed / ONNX, no torch)
+#   Vector DB  : FAISS (in-memory)
+#   LLM        : Qwen2.5-1.5B-Instruct   (llama.cpp GGUF, fast on CPU)
+#   API        : OpenAI-compatible  ->  /v1/chat/completions  (+ web UI at /)
 #
-# This is the CPU build: it runs on the FREE tier (2 vCPU / 16 GB, no GPU).
-# A 9B model on CPU is usable, not fast (~5-10 tok/s). For real speed, use GPU
-# hardware — see the notes at the bottom of this file.
-#
-# Speed/robustness choices:
-#   * llama.cpp OpenAI-compatible server (prebuilt CPU wheel -> fast build).
-#   * Model GGUF baked into the image  -> instant cold start (no re-download,
-#     which matters because free Spaces have only ephemeral disk).
-#   * --chat_format chatml             -> applies a proper template, which
-#     kills the repetition loop AND enforces <|im_end|> as a stop (no more
-#     duplicated answers).
+# Everything is CPU-only. No GPU, no paid hardware required.
+# Models are baked into the image so the Space cold-starts instantly.
 
 FROM python:3.11-slim
 
-# build-essential + cmake so llama-cpp-python compiles from source if no
-# prebuilt wheel matches (python:slim has no compiler -> CMake "gcc not found").
+# build-essential + cmake so llama-cpp-python can compile if no prebuilt wheel
+# matches (python:slim has no compiler otherwise -> CMake "gcc not found").
 RUN apt-get update && apt-get install -y --no-install-recommends \
-        build-essential cmake git curl ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
+        build-essential cmake git curl ca-certificates && rm -rf /var/lib/apt/lists/*
 
-# Hugging Face Spaces run the container as a non-root user with UID 1000.
+# Hugging Face Spaces run the container as non-root UID 1000.
 RUN useradd -m -u 1000 user
 USER user
 ENV HOME=/home/user \
     PATH=/home/user/.local/bin:$PATH
-
-# --- Python deps. GGML_NATIVE=OFF -> portable CPU binary (no -march=native),
-# so it can't crash with "illegal instruction" if build CPU != runtime CPU. ---
+WORKDIR /home/user/app
+
+# --- Python deps ---
+# --prefer-binary is the key: it makes pip pick a PREBUILT llama-cpp-python
+# wheel from the CPU index (a ~10s download) instead of compiling the newer
+# source release for minutes. build-essential/cmake stay only as a fallback
+# in the rare case no wheel matches (then CMAKE_ARGS keeps the build portable).
+COPY --chown=user requirements.txt .
 ENV CMAKE_ARGS="-DGGML_NATIVE=OFF" FORCE_CMAKE=1
-RUN pip install --no-cache-dir --user "llama-cpp-python[server]" huggingface_hub
+RUN pip install --no-cache-dir --user --prefer-binary -r requirements.txt
 
-# --- Model: which GGUF to serve ---------------------------------------------
-# Q4_K_M = good quality/size. For a bit more CPU speed swap to ornith-1.0-9b-Q4_0.gguf
-# (simpler kernels, faster on CPU) or ornith-1.0-9b-Q3_K_M.gguf (smaller, faster).
-# Confirm exact filenames on the repo's "Files" tab before changing.
-ENV MODEL_REPO=deepreinforce-ai/Ornith-1.0-9B-GGUF \
-    MODEL_FILE=ornith-1.0-9b-Q4_K_M.gguf \
-    MODEL_DIR=/home/user/models
+# --- Model config ------------------------------------------------------------
+ENV LLM_REPO=Qwen/Qwen2.5-1.5B-Instruct-GGUF \
+    LLM_FILE=qwen2.5-1.5b-instruct-q4_k_m.gguf \
+    MODEL_DIR=/home/user/models \
+    EMBED_MODEL=BAAI/bge-small-en-v1.5 \
+    FASTEMBED_CACHE=/home/user/.cache/fastembed \
+    HF_HOME=/home/user/.cache/huggingface
 
-# Bake the weights into the image so the Space starts instantly.
+# Bake the LLM (~1 GB) into the image -> instant cold start.
 RUN python -c "from huggingface_hub import hf_hub_download; \
-    hf_hub_download(repo_id='${MODEL_REPO}', filename='${MODEL_FILE}', local_dir='${MODEL_DIR}')"
+    hf_hub_download(repo_id='${LLM_REPO}', filename='${LLM_FILE}', local_dir='${MODEL_DIR}')"
+
+# Bake the embedding model (ONNX ~130 MB) into the image too.
+RUN python -c "import os; from fastembed import TextEmbedding; \
+    TextEmbedding(os.environ['EMBED_MODEL'], cache_dir=os.environ['FASTEMBED_CACHE'])"
 
-# --- Serving params ----------------------------------------------------------
-# Free tier = 2 vCPU, so 2 threads. n_ctx kept modest to save CPU RAM.
+# --- App ---------------------------------------------------------------------
+COPY --chown=user . .
+
+# Runtime knobs (free tier = 2 vCPU).
 ENV N_CTX=8192 \
     N_THREADS=2 \
-    OMP_NUM_THREADS=2
+    TOP_K=4 \
+    DOCS_DIR=documents
 
-# HF routes external traffic to this single port.
 EXPOSE 7860
-
-# OpenAI-compatible API at http://<space>.hf.space/v1  (chat/completions, models).
-CMD python -m llama_cpp.server \
-        --model ${MODEL_DIR}/${MODEL_FILE} \
-        --host 0.0.0.0 --port 7860 \
-        --n_ctx ${N_CTX} \
-        --n_threads ${N_THREADS} \
-        --n_batch 512 \
-        --chat_format chatml
-
-# -----------------------------------------------------------------------------
-# WANT IT ACTUALLY FAST?  Free HF has no GPU. Two options:
-#
-# 1) HF GPU hardware (paid, e.g. "T4 small"): change the base image to a CUDA
-#    one and install the CUDA wheel, then set --n_gpu_layers -1:
-#
-#        FROM nvidia/cuda:12.4.1-runtime-ubuntu22.04
-#        ... install python3 ...
-#        RUN pip install "llama-cpp-python[server]" \
-#              --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
-#        CMD python3 -m llama_cpp.server --model ... --n_gpu_layers -1 \
-#              --host 0.0.0.0 --port 7860 --n_ctx 16384 --chat_format chatml
-#
-#    On a T4 this jumps to ~40-70 tok/s.
-#
-# 2) ZeroGPU Space (free-ish, needs PRO): that path uses the Gradio SDK +
-#    @spaces.GPU with transformers/vLLM — NOT this llama.cpp Dockerfile.
-# -----------------------------------------------------------------------------
+CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,67 @@
 ---
-title: Ornith
-emoji: 👀
-colorFrom: green
-colorTo: yellow
+title: CPU RAG Space
+emoji: 🦅
+colorFrom: indigo
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CPU RAG Space — Qwen2.5-1.5B + FAISS (free tier, no GPU)
+
+A self-contained Retrieval-Augmented Generation service that runs **entirely on
+CPU** and fits the Hugging Face **free tier** (2 vCPU / 16 GB).
+
+| Component | What | Why |
+|-----------|------|-----|
+| Embeddings | `BAAI/bge-small-en-v1.5` via `fastembed` (ONNX) | fast on CPU, no PyTorch, ~130 MB |
+| Vector DB | **FAISS** (in-memory) | tiny, instant search |
+| LLM | `Qwen2.5-1.5B-Instruct` GGUF Q4_K_M via llama.cpp | fast on CPU (~12–20 tok/s), ~1 GB |
+| API | OpenAI-compatible `/v1/chat/completions` + web UI | drop-in for any client |
+
+Total footprint ≈ 1.5–2 GB RAM. Retrieval adds ~20 ms; the LLM is the only
+real latency.
+
+## Deploy (drag & drop)
+
+1. Create a new Space → **Docker** (blank template).
+2. Drag **all files in this folder** into the Space repo (keep the structure —
+   `documents/` included).
+3. Push. First build takes a few minutes (it bakes the ~1 GB LLM and the
+   embedder into the image so cold starts are instant).
+
+## Use it
+
+Web UI: open the Space URL. Upload `.txt`/`.md` files and ask questions.
+
+API (OpenAI-compatible):
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="https://<user>-<space>.hf.space/v1", api_key="x")
+r = client.chat.completions.create(
+    model="cpu-rag",
+    messages=[{"role": "user", "content": "How does retrieval work here?"}],
+)
+print(r.choices[0].message.content)
+```
+
+Extra endpoints: `POST /ingest` (upload a doc), `GET /stats`.
+
+## Add your own knowledge
+
+- Put `.txt`/`.md` files in `documents/` before pushing (indexed at startup), or
+- Upload them at runtime via the UI / `POST /ingest`.
+
+> Note: the free tier has ephemeral storage, so runtime-uploaded docs are lost
+> on restart. For a permanent corpus, commit files into `documents/`.
+
+## Swap the model
+
+Change these in the `Dockerfile` (confirm exact filenames on the repo's *Files*
+tab):
+
+- Faster / smaller: `Qwen/Qwen2.5-0.5B-Instruct-GGUF`
+- Coding-focused: `Qwen/Qwen2.5-Coder-1.5B-Instruct-GGUF`

app.py

@@ -0,0 +1,208 @@
+"""
+CPU RAG Space — bge-small (fastembed) + FAISS + Qwen2.5-1.5B (llama.cpp),
+served as an OpenAI-compatible API with a small web UI.
+
+Everything runs on CPU and fits the Hugging Face free tier (2 vCPU / 16 GB).
+"""
+
+import glob
+import json
+import os
+
+import faiss
+import numpy as np
+from fastapi import FastAPI, File, UploadFile
+from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
+from fastembed import TextEmbedding
+from llama_cpp import Llama
+from pydantic import BaseModel
+
+# --------------------------------------------------------------------------- #
+# Config (all overridable via Space "Variables")
+# --------------------------------------------------------------------------- #
+MODEL_DIR = os.environ.get("MODEL_DIR", "models")
+LLM_FILE = os.environ.get("LLM_FILE", "qwen2.5-1.5b-instruct-q4_k_m.gguf")
+LLM_PATH = os.path.join(MODEL_DIR, LLM_FILE)
+EMBED_MODEL = os.environ.get("EMBED_MODEL", "BAAI/bge-small-en-v1.5")
+FASTEMBED_CACHE = os.environ.get("FASTEMBED_CACHE")
+N_CTX = int(os.environ.get("N_CTX", "8192"))
+N_THREADS = int(os.environ.get("N_THREADS", str(os.cpu_count() or 2)))
+TOP_K = int(os.environ.get("TOP_K", "4"))
+DOCS_DIR = os.environ.get("DOCS_DIR", "documents")
+
+CHUNK_SIZE = 800        # characters per chunk
+CHUNK_OVERLAP = 120
+
+RAG_SYSTEM = (
+    "You are a helpful assistant. Answer the user's question using ONLY the "
+    "context below. If the answer is not in the context, say you don't know. "
+    "Cite the source of each fact in square brackets like [filename].\n\n"
+    "Context:\n{context}"
+)
+
+# --------------------------------------------------------------------------- #
+# Lazily-initialised singletons
+# --------------------------------------------------------------------------- #
+app = FastAPI(title="CPU RAG Space")
+
+_embedder = None
+_llm = None
+_index = None            # faiss.IndexFlatIP
+_chunks = []             # list[{"text": str, "source": str}]
+
+
+def embedder():
+    global _embedder
+    if _embedder is None:
+        _embedder = TextEmbedding(EMBED_MODEL, cache_dir=FASTEMBED_CACHE)
+    return _embedder
+
+
+def embed(texts):
+    vecs = np.array(list(embedder().embed(list(texts))), dtype="float32")
+    faiss.normalize_L2(vecs)          # cosine similarity via inner product
+    return vecs
+
+
+def llm():
+    global _llm
+    if _llm is None:
+        _llm = Llama(model_path=LLM_PATH, n_ctx=N_CTX, n_threads=N_THREADS,
+                     n_batch=512, verbose=False)
+    return _llm
+
+
+# --------------------------------------------------------------------------- #
+# Indexing / retrieval
+# --------------------------------------------------------------------------- #
+def chunk_text(text, source):
+    out, i, n = [], 0, len(text)
+    step = max(CHUNK_SIZE - CHUNK_OVERLAP, 1)
+    while i < n:
+        piece = text[i:i + CHUNK_SIZE].strip()
+        if piece:
+            out.append({"text": piece, "source": source})
+        i += step
+    return out
+
+
+def add_chunks(new_chunks):
+    global _index, _chunks
+    if not new_chunks:
+        return 0
+    vecs = embed([c["text"] for c in new_chunks])
+    if _index is None:
+        _index = faiss.IndexFlatIP(vecs.shape[1])
+    _index.add(vecs)
+    _chunks.extend(new_chunks)
+    return len(new_chunks)
+
+
+def build_index():
+    patterns = ("*.txt", "*.md")
+    files = []
+    for p in patterns:
+        files += glob.glob(os.path.join(DOCS_DIR, "**", p), recursive=True)
+    all_chunks = []
+    for f in files:
+        try:
+            with open(f, encoding="utf-8") as fh:
+                all_chunks += chunk_text(fh.read(), os.path.basename(f))
+        except Exception as exc:
+            print(f"[rag] skip {f}: {exc}")
+    add_chunks(all_chunks)
+
+
+def retrieve(query, k=TOP_K):
+    if _index is None or _index.ntotal == 0:
+        return []
+    scores, ids = _index.search(embed([query]), min(k, _index.ntotal))
+    hits = []
+    for score, idx in zip(scores[0], ids[0]):
+        if idx < 0:
+            continue
+        c = _chunks[idx]
+        hits.append({"text": c["text"], "source": c["source"], "score": float(score)})
+    return hits
+
+
+# --------------------------------------------------------------------------- #
+# Startup
+# --------------------------------------------------------------------------- #
+@app.on_event("startup")
+def _startup():
+    print("[rag] loading embedder + llm ...")
+    embedder()
+    llm()
+    build_index()
+    print(f"[rag] ready. indexed_chunks={len(_chunks)}")
+
+
+# --------------------------------------------------------------------------- #
+# OpenAI-compatible chat endpoint (with RAG)
+# --------------------------------------------------------------------------- #
+class ChatMessage(BaseModel):
+    role: str
+    content: str
+
+
+class ChatRequest(BaseModel):
+    model: str = "cpu-rag"
+    messages: list[ChatMessage]
+    temperature: float = 0.3
+    top_p: float = 0.9
+    max_tokens: int = 512
+    stream: bool = False
+    use_rag: bool = True
+
+
+def _augment(req: ChatRequest):
+    msgs = [m.model_dump() for m in req.messages]
+    users = [m for m in msgs if m["role"] == "user"]
+    query = users[-1]["content"] if users else ""
+    ctxs = retrieve(query) if req.use_rag else []
+    if ctxs:
+        context = "\n\n".join(f"[{c['source']}] {c['text']}" for c in ctxs)
+        system = {"role": "system", "content": RAG_SYSTEM.format(context=context)}
+        msgs = [system] + [m for m in msgs if m["role"] != "system"]
+    return msgs, ctxs
+
+
+@app.post("/v1/chat/completions")
+def chat_completions(req: ChatRequest):
+    messages, ctxs = _augment(req)
+    params = dict(messages=messages, temperature=req.temperature, top_p=req.top_p,
+                  max_tokens=req.max_tokens, stop=["<|im_end|>", "<|endoftext|>"])
+
+    if req.stream:
+        def gen():
+            for chunk in llm().create_chat_completion(**params, stream=True):
+                yield f"data: {json.dumps(chunk)}\n\n"
+            yield "data: [DONE]\n\n"
+        return StreamingResponse(gen(), media_type="text/event-stream")
+
+    resp = llm().create_chat_completion(**params)
+    resp["sources"] = [{"source": c["source"], "score": round(c["score"], 3)} for c in ctxs]
+    return JSONResponse(resp)
+
+
+# --------------------------------------------------------------------------- #
+# Ingest / stats / UI
+# --------------------------------------------------------------------------- #
+@app.post("/ingest")
+async def ingest(file: UploadFile = File(...)):
+    text = (await file.read()).decode("utf-8", "ignore")
+    added = add_chunks(chunk_text(text, file.filename))
+    return {"file": file.filename, "added_chunks": added, "total_chunks": len(_chunks)}
+
+
+@app.get("/stats")
+def stats():
+    return {"indexed_chunks": len(_chunks), "embed_model": EMBED_MODEL,
+            "llm": LLM_FILE, "n_ctx": N_CTX, "threads": N_THREADS, "top_k": TOP_K}
+
+
+@app.get("/", response_class=HTMLResponse)
+def home():
+    with open(os.path.join(os.path.dirname(__file__), "index.html"), encoding="utf-8") as f:
+        return f.read()

documents/sample.txt

@@ -0,0 +1,25 @@
+CPU RAG Space — sample knowledge document.
+
+This Space is a fully CPU, free-tier Retrieval-Augmented Generation service.
+
+Architecture:
+- Embedding model: BAAI/bge-small-en-v1.5, run via fastembed (ONNX). It turns
+  text into 384-dimensional vectors and needs no GPU or PyTorch.
+- Vector store: FAISS (IndexFlatIP) holds the document vectors in memory and
+  returns the most similar chunks for a query using cosine similarity.
+- Language model: Qwen2.5-1.5B-Instruct in GGUF Q4_K_M form, served by
+  llama.cpp. It reads the retrieved chunks and writes a grounded answer.
+
+How retrieval works:
+1. Your question is embedded into a vector.
+2. FAISS finds the top-K most similar document chunks (default K = 4).
+3. Those chunks are inserted into the model's system prompt as context.
+4. The model answers using only that context and cites the source file.
+
+Why a small model is fine here:
+RAG moves knowledge out of the model's weights and into the retriever, so the
+model only needs to read and summarise the provided context rather than
+memorise facts. That makes a fast 1.5B model a good fit for CPU serving.
+
+Replace this file with your own .txt or .md documents, or upload files at
+runtime through the web UI, and the Space will answer questions about them.

index.html

@@ -0,0 +1,97 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>CPU RAG · Qwen2.5-1.5B + FAISS</title>
+<style>
+  :root { color-scheme: light dark; --bg:#0f1220; --panel:#1a1e33; --acc:#7c8cff; --mut:#8b90a8; }
+  * { box-sizing: border-box; }
+  body { margin:0; font-family: system-ui, sans-serif; background:var(--bg); color:#e7e9f3; }
+  header { padding:14px 18px; border-bottom:1px solid #2a2f4a; display:flex; gap:12px; align-items:center; }
+  header h1 { font-size:15px; margin:0; font-weight:600; }
+  header .tag { font-size:11px; color:var(--mut); background:var(--panel); padding:3px 8px; border-radius:20px; }
+  main { max-width:820px; margin:0 auto; padding:18px; }
+  #chat { display:flex; flex-direction:column; gap:12px; min-height:50vh; }
+  .msg { padding:11px 14px; border-radius:12px; max-width:88%; white-space:pre-wrap; line-height:1.45; font-size:14px; }
+  .user { align-self:flex-end; background:var(--acc); color:#fff; }
+  .bot  { align-self:flex-start; background:var(--panel); }
+  .src  { align-self:flex-start; font-size:11px; color:var(--mut); margin-top:-6px; }
+  form { display:flex; gap:8px; margin-top:16px; }
+  textarea { flex:1; resize:none; padding:11px; border-radius:10px; border:1px solid #2a2f4a; background:#12152a; color:#e7e9f3; font-size:14px; }
+  button { padding:0 16px; border:0; border-radius:10px; background:var(--acc); color:#fff; font-weight:600; cursor:pointer; }
+  button:disabled { opacity:.5; cursor:default; }
+  .bar { display:flex; gap:10px; align-items:center; margin-bottom:14px; font-size:12px; color:var(--mut); }
+  .bar input[type=file] { font-size:12px; color:var(--mut); }
+</style>
+</head>
+<body>
+<header>
+  <h1>🦅 CPU RAG</h1>
+  <span class="tag">Qwen2.5-1.5B · bge-small · FAISS</span>
+  <span class="tag" id="stat">…</span>
+</header>
+<main>
+  <div class="bar">
+    <label>Add a document (.txt/.md):</label>
+    <input type="file" id="file" accept=".txt,.md" />
+    <button id="up" type="button">Upload</button>
+    <span id="upmsg"></span>
+  </div>
+  <div id="chat"></div>
+  <form id="form">
+    <textarea id="q" rows="2" placeholder="Ask about your documents…"></textarea>
+    <button id="send" type="submit">Send</button>
+  </form>
+</main>
+<script>
+const chat = document.getElementById('chat');
+const stat = document.getElementById('stat');
+
+function add(cls, text) {
+  const d = document.createElement('div');
+  d.className = 'msg ' + cls; d.textContent = text;
+  chat.appendChild(d); chat.scrollIntoView({block:'end'}); return d;
+}
+async function refreshStats(){
+  try { const s = await (await fetch('/stats')).json();
+        stat.textContent = s.indexed_chunks + ' chunks indexed'; } catch(e){}
+}
+refreshStats();
+
+document.getElementById('up').onclick = async () => {
+  const f = document.getElementById('file').files[0];
+  if (!f) return;
+  document.getElementById('upmsg').textContent = 'uploading…';
+  const fd = new FormData(); fd.append('file', f);
+  const r = await (await fetch('/ingest', {method:'POST', body:fd})).json();
+  document.getElementById('upmsg').textContent = '+' + r.added_chunks + ' chunks';
+  refreshStats();
+};
+
+document.getElementById('form').onsubmit = async (e) => {
+  e.preventDefault();
+  const q = document.getElementById('q').value.trim();
+  if (!q) return;
+  document.getElementById('q').value = '';
+  document.getElementById('send').disabled = true;
+  add('user', q);
+  const thinking = add('bot', '…');
+  try {
+    const r = await fetch('/v1/chat/completions', {
+      method:'POST', headers:{'Content-Type':'application/json'},
+      body: JSON.stringify({ messages:[{role:'user', content:q}], temperature:0.3 })
+    });
+    const data = await r.json();
+    thinking.textContent = data.choices?.[0]?.message?.content ?? '(no answer)';
+    if (data.sources && data.sources.length) {
+      add('src', 'sources: ' + data.sources.map(s => s.source + ' (' + s.score + ')').join(', '));
+    }
+  } catch (err) {
+    thinking.textContent = 'Error: ' + err;
+  }
+  document.getElementById('send').disabled = false;
+};
+</script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,15 @@
+# Try a prebuilt CPU wheel first (fast); if none matches, the Dockerfile's
+# build-essential/cmake lets it compile from source instead of failing.
+--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+llama-cpp-python
+
+# Lightweight CPU embeddings via ONNX (no PyTorch -> small image, fast).
+fastembed
+faiss-cpu
+
+# API + serving
+fastapi
+uvicorn[standard]
+python-multipart
+huggingface_hub
+numpy