moorcheh-edge

Python package and CLI for running moorcheh-edge locally and calling its API.

• CLI: moorcheh-edge
• Package: moorcheh-edge
• Python import: moorcheh_edge

Requires Docker (Docker Desktop or Docker Engine).

Install

pip install moorcheh-edge

Quick start

Start the local edge runtime. Default up starts Docker + warm BGE embedding only (no Ollama download).

On first run this automatically:

• pulls the moorcheh-edge Docker image and starts the search server
• starts a background embedding daemon that keeps BGE loaded in RAM (stopped by moorcheh-edge down)
• downloads BGE-small-en-v1.5 (~67 MB) for text search/upload

Ollama / AI answer is opt-in — not downloaded by default.

moorcheh-edge up

Interactive prompts (embedding yes/no, AI answer yes/no, keep LLM in RAM yes/no) appear in a terminal. Use -y to skip prompts and accept defaults.

moorcheh-edge up -y

Enable AI answer (install Ollama + pull model; loads on first answer, not kept in RAM):

moorcheh-edge up --with-llm

Enable AI answer and keep LLM warm in RAM (~1.1 GB, default 24h):

moorcheh-edge up --with-llm --warm-llm

Skip Moorcheh embedding (your own vectors only):

moorcheh-edge up --skip-embedding

Docker only (no embed, no LLM):

moorcheh-edge up --skip-embedding -y

Default API:

http://localhost:8080

Default data directory:

~/.moorcheh-edge/data

Check health/status:

moorcheh-edge status

Stop the runtime:

moorcheh-edge down

Commands

• moorcheh-edge up / down / status
• moorcheh-edge upload-documents — embed text locally (384-dim text store)
• moorcheh-edge upload-vectors — upload pre-computed vectors (vector store)
• moorcheh-edge search — --query-text or --query-vector-json
• moorcheh-edge answer — RAG via server POST /answer (embeds locally, LLM on server)
• moorcheh-edge voice setup — full voice install (packages, Whisper, Piper, ALSA config)
• moorcheh-edge voice listen — record mic → Whisper → print text
• moorcheh-edge voice speak --text "..." — Piper TTS (or espeak-ng) → speaker
• moorcheh-edge voice ask — push-to-talk kiosk: record → RAG answer → speak
• moorcheh-edge delete — delete items by id
• moorcheh-edge clear-store — wipe all items and reset dimension/mode (prompts for confirmation; use -y to skip)

All API commands accept --base-url, for example:

moorcheh-edge status --base-url http://localhost:8081

Use --skip-embedding on up to skip BGE entirely (no download, no warm daemon). Use --with-llm to install Ollama and pull the answer model (~400 MB). Use --warm-llm with --with-llm to preload the LLM into RAM (default keep-alive 24h).

Answer uses local Ollama with fixed model qwen2.5:0.5b-instruct on the host; the Docker server reaches it at http://host.docker.internal:11434/v1.

When search returns no passages, /answer returns I don't have enough information to answer that question. without calling the LLM.

Voice (UNO Q kiosk)

One command installs system packages, Whisper STT, Piper TTS, models, and auto-configures ALSA (no env vars needed):

moorcheh-edge up --server-image moorcheh-edge:uno-q
moorcheh-edge voice setup

moorcheh-edge voice check
moorcheh-edge voice ask --kiosk-mode

Offline pipeline: ALSA → Whisper tiny.en → RAG answer → Piper TTS (fallback espeak-ng).

Audio device defaults are saved to ~/.moorcheh-edge/voice/audio.json. Optional overrides: MOORCHEH_AUDIO_CAPTURE, MOORCHEH_AUDIO_PLAYBACK.

Bluetooth speakers (e.g. Arduino UNO Q): pair manually with bluetoothctl, then set "playback": "bluetooth" in ~/.moorcheh-edge/voice/audio.json.

Example ~/.moorcheh-edge/voice/audio.json for USB mic + Bluetooth out:

{
  "capture": "plughw:0,0",
  "playback": "bluetooth",
  "bt_device": "BC:87:FA:55:1A:47"
}

Pair the speaker first — see docs CLI → Voice → Bluetooth (manual setup).

Notes

• Answer / RAG: client embeds the question, server searches + builds prompt + calls LLM
• One flat store per container (no namespaces)
• Text mode: client embeds with BGE-small-en-v1.5 (384 dimensions); set on first upload
• Vector mode: client sends pre-computed vectors; dimension locked on first upload (128–1536)
• Cannot mix text and vector modes in the same store
• Global item cap: 10,000
• Model cache: ~/.moorcheh-edge/models