KippieSearch

Lokale, privacy-first semantic search + RAG-chat. Draait als Home Assistant add-on op een Raspberry Pi 5 (8 GB, aarch64, HA OS): één container, één proces (FastAPI + chat-UI + REST + MCP + scheduler). Bestanden blijven op je LAN. Embeddings en het chatmodel draaien op de Pi, niet in de cloud.

Poort 8765 (configureerbaar; vrij ten opzichte van HA 8123, Radarr 7878, Sonarr 8989, qBittorrent 8082, Jellyfin 8096, Portainer 9000, Fladder 8098). Ingress in Home Assistant zit erbij.

Architectuur

Browser / Grok Bot
        │  HTTP 8765
        ▼
┌──────────────────────────────────────────┐
│  FastAPI (één proces)                    │
│  /           chat-UI (zoeken + RAG)      │
│  /api/*      search, chat SSE, status    │
│  /mcp        Streamable HTTP MCP         │
│  APScheduler dagelijkse schoolsync + NAS │
└──────────────┬───────────────────────────┘
               │
     ┌─────────┴──────────┐
     │ LanceDB (/data)    │  embedded, geen extra service
     │ EmbeddingGemma 2   │  ONNX q4, text-only, offline na 1e start
     │ Gemma 3 GGUF       │  llama-cpp-python, lazy load, unload na idle
     └─────────┬──────────┘
               │
     nas_roots (expliciet, bv. /share/<naam>) ── NAS (SMB)
     SMB-fallback (smbprotocol, read-only)
     /data/itslearning  ← dagelijkse sync (requests, geen Chromium)

Keuzes

Mapstructuur

repository.yaml                 HA add-on repository
kippiesearch/                   de add-on (build-context)
  config.yaml                   Supervisor-config, opties, ingress
  Dockerfile
  run.sh
  requirements.txt
  translations/{en,nl}.yaml
  src/kippiesearch/             Python-pakket
    main.py                     FastAPI
    embeddings.py / indexer.py / store.py / search.py / chat.py
    itslearning.py / nas.py / mcp_server.py
    static/                     chat-UI HTML/CSS/JS (geen build-stap)
tests/  fixtures/  docker-compose.yml  .github/workflows/ci.yml

Persistent op de Pi (/data van de add-on): lancedb/, models/ (EmbeddingGemma + GGUF, éénmalige download), itslearning/, nas-cache/.

Related MCP server: rag-retriever-mcp

Installatie op Home Assistant OS

HA OS heeft geen vrije Docker Compose en geen systemd-units voor extra stacks. Daarom is dit een custom add-on. Deze GitHub-repo is public; Supervisor kan hem dus als add-on-repository clonen.

Primair — custom repository (aanbevolen)

1. HA → Instellingen → Add-ons → Add-on Store → ⋮ (rechtsboven) → Repositories.

2. Voeg toe: https://github.com/KippenBoutske/kippiesearch

3. Ververs de store. KippieSearch verschijnt in de lijst.

4. Installeren (eerste build op de Pi duurt even: Python-deps + later het model).

5. Configuratie: zet een api_token, koppel de NAS (zie hieronder) en eventueel it's learning, daarna Start.

6. Sidebar KippieSearch (ingress) of http://<pi-ip>:8765/.

De repository-root bevat repository.yaml; de add-on zelf staat in kippiesearch/ (config.yaml + Dockerfile). Dat is het formaat dat de Supervisor verwacht.

Alternatief — lokale add-on via /addons

Handig voor ontwikkeling of als de store de repo niet pakt:

1. Installeer de Samba- of SSH-add-on in HA.

2. Kopieer de map kippiesearch/ uit deze repo als /addons/kippiesearch/ (daarin moeten config.yaml en Dockerfile staan).

3. HA → Instellingen → Add-ons → ⋮ → Check for updates / ververs.

4. Onder Local add-ons verschijnt KippieSearch. Verder hetzelfde als hierboven.

Eerste start

• Health: http://<pi-ip>:8765/health

• Eerste keer met embedder: onnx downloadt EmbeddingGemma 2 q4 naar /data/models (honderden MB, eenmalig, daarna offline).

• Daarna Status → Index opnieuw.

NAS-koppeling

Wachtwoorden horen alleen in de HA-opties, nooit in git. Host, share en inlog zijn leeg tot je ze invult; zonder die waarden blijft SMB uit (zichtbaar in status/logs).

Voorkeur — HA-netwerkopslag (add-on mount /share)

Een add-on kan op HA OS niet zelf SMB-mounten. Laat Home Assistant dat doen:

1. HA → Instellingen → Systeem → Opslag → netwerkopslag toevoegen.

2. Server: het LAN-adres van je NAS, bijvoorbeeld 192.168.1.x

3. Protocol: Share (SMB/CIFS)

4. Share: de sharenaam op de NAS, bijvoorbeeld home of documents

5. Gebruikersnaam + wachtwoord van dat NAS-account (in HA, niet in deze repo).

6. Kies een naam, bijvoorbeeld nas. HA mount de share dan onder /share/<naam> (dus /share/nas als je hem nas noemt).

7. In KippieSearch: zet nas_roots op dat pad, bijvoorbeeld /share/nas. Laat het niet op heel /share staan: daar zet HA app-data van andere add-ons (caches, plugins, JS-bundles). Default is leeg tot je een pad invult.

Alleen lezen is genoeg.

Alternatief — SMB-fallback in de add-on

Als er geen HA-mount is: nas_smb_enabled: true en vul nas_smb_host (bijv. 192.168.1.x), nas_smb_shares (bijv. home), nas_smb_username en nas_smb_password in. Poort default 445. De add-on leest via smbprotocol (read-only) en cachet naar /data/nas-cache. Ontbreekt host, share of gebruiker, dan wordt SMB overgeslagen.

Credentials veilig zetten

• Zet nooit wachtwoorden in git of in de UI-zoekbalk.

• HA-opties van het type password (API-token, SMB, it's learning) staan in /data/options.json van de add-on, niet in de repo.

• Logs redacteren password / token / authorization.

• Kies een lang api_token. Stuur het alleen als Authorization: Bearer ….

• Ingress (sidebar) heeft geen token nodig.

Index opnieuw bouwen

• UI → Status → Index opnieuw (incrementeel: mtime+size, daarna content-hash) of Volledige herindex.

• POST /api/reindex met {"full": false, "itslearning": false}

• POST /api/reindex met {"itslearning": true} triggert eerst schoolsync.

Incrementeel slaat ongewijzigde bestanden over, herindexeert bij hash-wijziging, en gooit verwijderde paden uit de index.

Ondersteunde formaten: txt/md/html/json, code-extensies, PDF (pypdf), DOCX, PPTX. Afbeeldingen: overgeslagen (EmbeddingGemma text-only; OCR-optie bestaat maar staat uit vanwege RAM).

MCP toevoegen aan Grok Bot

Endpoint: Streamable HTTP op hetzelfde proces.

• URL: http://<pi-ip>:8765/mcp (LAN of Tailscale)

• Auth: Authorization: Bearer <api_token>

• Tools: search(query, top_k, source?, file_type?), ask(question, top_k, source?, file_type?) (RAG-antwoord + bronnen), list_sources(), get_file_content(path, max_chars) (alleen tekst, alleen geïndexeerde roots, path-traversal geblokkeerd)

In Grok / Cursor: custom MCP-server, transport Streamable HTTP, URL hierboven, header Bearer. HA-ingress is niet nodig voor MCP; Grok praat rechtstreeks naar poort 8765.

it's learning

• Zet itslearning_enabled: true en vul URL, gebruikersnaam en wachtwoord in (geen SSO).

• URL-voorbeeld: https://<school>.itslearning.com — er is geen default-school in de repo.

• Organisatienaam is optioneel (alleen ter herkenning in de UI).

• Dagelijks (cron 0 3 * * *, Europe/Amsterdam): login → cursusbestanden naar /data/itslearning → index.

• Rate-limit standaard 0,75 s. Alleen wat jíj mag zien.

• Zonder URL of credentials blijft sync uit; status en logs zeggen wat er ontbreekt.

Playwright zit er bewust niet in (Chromium-RAM op de Pi).

Lokaal testen (gewone machine)

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
KIPPIESEARCH_EMBEDDER=hash pytest -q
KIPPIESEARCH_DATA_DIR=./data KIPPIESEARCH_NAS_ROOTS=./fixtures/corpus \
  KIPPIESEARCH_EMBEDDER=hash KIPPIESEARCH_AUTH_DISABLED=true \
  python -m kippiesearch

Of: docker compose up --build → http://127.0.0.1:8765 (hash-embedder, fixtures als /share).

API: GET /api/search?q=…, POST /api/chat (SSE), /api/sources, /api/status, POST /api/reindex, /health.

Pi-tuning

RAG-chat

Flow: vraag → EmbeddingGemma-retrieval (top-k chunks) → prompt met bronnen → gestreamd antwoord, met [1] / [2] die naar bronkaarten wijzen. Staat het niet in de bestanden, dan zegt het model dat eerlijk.

• POST /api/chat — SSE (sources, token, done, error)

• MCP-tool ask — zelfde flow, zonder stream

• Model-download bij eerste chat, daarna offline in /data/models

• Lazy load; na chat_idle_unload_minutes (default 15) gaat het GGUF uit RAM

Runtime: llama-cpp-python in hetzelfde proces (CPU-wheels via de extra-index van het project, aarch64 + amd64). Lichter dan een aparte llama.cpp-server: geen tweede proces, unload is del + gc.

RAM / snelheid

Gemeten op de ontwikkel-VM (x86_64, hash-embedder + mock-LLM, kleine testdocs via python scripts/benchmark.py en pytest):

• index/search: honderden ms / enkele ms (hash, geen ONNX)

• mock-chat SSE: tokens meteen, geen GGUF-RAM

Realistische Pi 5 (8 GB, naast Home Assistant):

1B is de default omdat 4B naast HA + *arr + Jellyfin krap wordt op 8 GB. Idle-unload (15 min) geeft het geheugen terug. Zet chat_enabled: false als je het model helemaal niet wilt.

Houd headroom voor Home Assistant. Begin met de defaults (gemma3-1b, 2 threads, ctx 2048).

Troubleshooting

Licentie

MIT. EmbeddingGemma 2: Apache 2.0 (Google).