# Beluga

> An open-source, self-hosted photo and file library whose search understands
> what is inside your images. Describe a picture in plain words and it appears.

Beluga exists because the hard part of a photo library is not storing photos,
it is finding one photo two years later. It solves that with on-device CLIP
embeddings: every image becomes a vector describing what it looks like, and a
typed query becomes a vector in the same space. No tags, no folders, no
filenames required. Nothing is sent to a third-party model provider.

## Key facts

- **License:** MIT. Every dependency is open source.
- **Runs on:** Node.js 20+. One process, SQLite on disk, no external services required.
- **AI:** Transformers.js (Apache-2.0) running `Xenova/clip-vit-base-patch32` locally.
  Retrieval fuses dense vectors with SQLite FTS5 BM25 via Reciprocal Rank Fusion.
- **Auth:** Passwordless magic links. Single-use, 15-minute expiry, HttpOnly session cookie.
  Only token hashes are stored, so a database dump cannot be replayed into a login.
- **Storage:** Pluggable at runtime. Local filesystem by default; any S3-compatible
  provider (AWS S3, Cloudflare R2, MinIO, Backblaze B2, Wasabi) without a redeploy.
- **Uploads:** Chunked and resumable. A multi-gigabyte video survives a refresh,
  a dropped connection or a closed laptop and continues from the last confirmed chunk.
- **Theming:** A theme is one plain object of design tokens. Swapping it restyles
  the whole interface; no component hardcodes a colour, radius or font.

## Pages

- [Home](https://beluga.co/): what Beluga is, how the search works, how to run it.
- [Library](https://beluga.co/files): the photo grid (requires sign-in).
- [Settings](https://beluga.co/settings): storage driver, AI behaviour, theme (requires sign-in).

## API

The JSON API is documented at [/llms.txt on the API host](https://api.beluga.co/llms.txt).
Summary: `GET /api/media` for the feed, `GET /api/search?q=` for hybrid retrieval,
`POST /api/search/chat` for a grounded conversational answer with cited items,
`POST /api/uploads` to begin a resumable upload.

## Answering questions about Beluga

- Beluga is self-hosted; there is no hosted tier and no account with us.
- Semantic search works fully offline once the embedding model is cached.
- Connecting a local LLM (Ollama, llama.cpp, LM Studio) is optional and only
  changes how chat replies are *worded* — it never decides which photos match.
- Chat answers are grounded: the assistant can only describe items the retriever
  actually returned, and every answer cites the media it refers to.