Cute DB

Indexes a folder of cute-animal images and video clips with a vision-language model, stores descriptions in SQLite, and serves keyword search over MCP.

How it works

source/  ──►  [scan]  ──►  [describe via VLM]  ──►  [safety check]
                                                         │
                         ┌───────────────────────────────┤
                      reject                          accept
                         │                               │
                 log + leave in source/       re-encode → cuteness/<hash>.<ext>
                                               + insert row in cuteness.sqlite

The MCP server reads cuteness.sqlite only and exposes two tools — search_cute (FTS keyword search) and get_cute (direct lookup) — so an AI assistant can fetch and display cute media on demand.

Requirements

• Python 3.12+, managed by uv
• ffmpeg and ffprobe on PATH (for video/GIF re-encoding)
• A running vLLM instance serving an OpenAI-compatible API with a vision model

Setup

uv sync

Configure via environment variables (all optional):

Variable	Default
CUTE_DB_VLM_URL	http://burgundy:8191/v1
CUTE_DB_VLM_MODEL	google/gemma-4-e4b-it
CUTE_DB_SOURCE	./source
CUTE_DB_TARGET	./cuteness
CUTE_DB_SQLITE	./cuteness.sqlite
CUTE_DB_CONCURRENCY	8
CUTE_DB_MAX_VIDEO_MB	8
CUTE_DB_COMPRESS_IMAGES	1
CUTE_DB_COMPRESS_VIDEOS	1

Usage

Ingest — scan source/, describe each file with the VLM, accept or reject:

cute-db ingest                    # process everything
cute-db ingest --limit 20         # test run, first 20 files
cute-db ingest --concurrency 4    # fewer parallel VLM calls
cute-db ingest --no-compress-videos  # skip ffmpeg re-encoding

Reindex — rebuild the FTS index without touching the VLM:

cute-db reindex

Serve — start the MCP stdio server:

cute-db serve

Storage

Accepted files are re-encoded for compactness (disable with flags above):

• Images → WebP, lossy q85 (lossless for PNG). Fallback to original if the encoded file is larger.
• Videos / GIFs → H.264 MP4, long-edge ≤ 720 px, CRF 28. Fallback to original if larger.

Files are named <sha256[:16]>.<ext> in cuteness/. The hash is taken over the original source bytes so re-runs are idempotent.

Rejected files stay in source/ and are recorded in rejected.txt (one line per file) so they are skipped on the next run without an extra VLM call.

MCP tools

search_cute(query, limit=8)

Full-text search over descriptions, animal names, and tags using FTS5 + BM25 ranking. Returns a list of results, each with:

{
  "id": "7dc5995c58c88196",
  "path": "/abs/path/to/cuteness/7dc5995c58c88196.webp",
  "description": "Several small dogs lounging on a red velvet couch.",
  "animals": ["dog"],
  "tags": ["puppies", "couch", "cute"],
  "kind": "image",
  "is_cute": true,
  "is_funny": false
}

path is the absolute path on disk so the client can open or display the file directly.

get_cute(id)

Direct lookup by id. Returns the same shape as a search result, or null if not found.

Both tools lazily purge rows whose files have been deleted from disk.

Project layout

src/cute_db/
├── config.py        # env-var config
├── db.py            # SQLite schema, FTS triggers, helpers
├── media.py         # ext detection, hashing, image/video encoding
├── vlm.py           # OpenAI-compatible VLM client, response parsing
├── pipeline.py      # ingest orchestration (async, concurrent)
├── cli.py           # cute-db ingest / reindex / serve
└── mcp_server.py    # FastMCP stdio server