shivvr 🔪 v0.6.1

Capabilities

API

API requests require a nuts-auth bearer token. The GPU backend starts on demand, so the first request can take longer.

Request limits: 32 MiB bodies on image, audio and ingest routes, 8 MiB on /embed, 2 MiB elsewhere; 120 s server timeout on inference routes, 30 s on the rest.

Quick start

# Ingest into session
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/sessions/my-session/ingest \
  -H "Content-Type: application/json" \
  -d '{"text": "Supreme Raven is protected by Known Opossum.", "source": "vault_specs"}'

# Autonomous Agent Conversational Chat (Streams Thoughts, ToolCalls, & Answer via SSE)
curl -H "Authorization: Bearer <nuts-auth-token>" -i -X POST https://shivvr.nuts.services/sessions/my-session/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Who protects the Supreme Raven?"}'

# Vector-Lexical Hybrid RRF Search
curl -H "Authorization: Bearer <nuts-auth-token>" "https://shivvr.nuts.services/sessions/my-session/search?q=Known+Opossum&hybrid=true"

# High-speed Lexical-Only BM25 Search (Bypasses ONNX embedder)
curl -H "Authorization: Bearer <nuts-auth-token>" "https://shivvr.nuts.services/sessions/my-session/search?q=Opossum&lexical_only=true"

# Ingest and get each chunk's GTR vector too, then invert it back to text
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/sessions/my-session/ingest \
  -H "Content-Type: application/json" \
  -d '{"text": "The harbor was quiet at dawn.", "return_vectors": ["gtr-t5-base"]}'
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/invert \
  -H "Content-Type: application/json" \
  -d '{"embedding": [/* chunks[0].embeddings["gtr-t5-base"] */], "model": "gtr-t5-base"}'

# Text vectors with EmbeddingGemma 2 (query prefix, 256d)
curl -X POST https://shivvr.nuts.services/embed \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Who protects the Supreme Raven?"], "model": "embeddinggemma-2", "task": "query", "dimensions": 256}'

# Upload an image: base64 the file into a JSON body, then ingest it (stored as an [image] chunk, searchable by text)
printf '{"image_base64": "%s", "text": "boat at the fuel dock"}' "$(base64 -w0 photo.jpg)" > image.json
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/sessions/my-session/ingest \
  -H "Content-Type: application/json" --data @image.json

# Or just get the image vector back (768d), nothing stored
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/image/embed \
  -H "Content-Type: application/json" --data @image.json

# Upload a voice file (WAV): it is transcribed, then the transcript is chunked and embedded
printf '{"audio_base64": "%s"}' "$(base64 -w0 note.wav)" > voice.json
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/sessions/my-session/ingest \
  -H "Content-Type: application/json" --data @voice.json

# Or get the transcript and its vector back, nothing stored
curl -H "Authorization: Bearer <nuts-auth-token>" -X POST https://shivvr.nuts.services/audio/embed \
  -H "Content-Type: application/json" --data @voice.json

# Synchronize Claude Code or Antigravity with shivvr's Native MCP Server
nemesis8 mcp add https://shivvr.nuts.services/mcp/sse

Search parameters

Ingest request (POST /sessions/:id/ingest, /temp/:name/ingest)

Response: {"chunks_created", "tokens_processed", "time_ms", "model", "chunks"}; each chunk's embedding is the store's search vector.

Embed request (POST /embed)

Response: {"model", "dim", "vectors"}, unit-length vectors. Use task=query for search queries and task=document for the passages they search.

Image and voice requests

Bodies up to 32 MiB, so about 24 MB of file after base64. Build the JSON in a file and send it with --data @file.json; a large base64 string is too long for a command-line argument.

Environment

Images

Run it yourself

# GPU: all models are in the image (~4.4 GB pull)
docker run -d --name shivvr --gpus all -p 127.0.0.1:8080:8080 deepbluedynamics/shivvr

# CPU (amd64/arm64, incl. Raspberry Pi 5):
# 1. a volume for the models
docker volume create shivvr-models
# 2. copy the int8 models (440 MB) into it; this fills /target, replacing what's there, and exits
docker run --rm -v shivvr-models:/target deepbluedynamics/shivvr-models:int8
# 3. start shivvr with the models mounted read-only
docker run -d --name shivvr -p 127.0.0.1:8080:8080 -v shivvr-models:/models:ro deepbluedynamics/shivvr:latest-cpu

Stack