Kami Image Search

A skill by Kami SmartHome. Capture frames from your camera, describe them with AI, and search your visual history using natural language.

Search your camera's visual history with natural language.

Monitor your camera feed, capture frames automatically, and retrieve matching images by simply describing what you're looking for. Powered by the Kamivision cloud API for AI description and embedding generation.

Features

• 🔍 Natural language image search
• 📸 Automatic frame capture from video streams
• 🧠 AI-powered image description (Kamivision API)
• 📁 Manual image import (JPEG / PNG / BMP / WebP)
• 🔁 Built-in duplicate frame detection
• ⏱ Time-range filtering
• 🏠 Designed for Kami SmartHome ecosystem

Scenarios

• Doorstep delivery verification
• Home activity review
• Pet or child monitoring playback
• Batch photo indexing and retrieval

Installation

bash setup.sh

Checks for python3 and ffmpeg, creates .venv/, and installs opencv-python-headless, numpy, requests, Pillow, faiss-cpu. Idempotent.

Prerequisites

• python3 and python3-venv installed
• ffmpeg installed (setup.sh will attempt to install it)
• image_config.json configured with your stream URL and Kamivision API key
• RTSP/RTMP camera online and reachable (for capture mode)

Kamivision API Key Setup

This skill requires a KAMIVISION_API_KEY to access the Kamivision cloud API. The key is NOT included in the skill package — you must provide your own.

Ask the user: Do you already have a KAMIVISION_API_KEY?

• Yes → Enter the key directly. It will be saved to image_config.json.
• No → Register at Kamivision Flow to obtain your API key. 🎁 New users get 200 free credits on first registration.

Parameter Confirmation

Before running, confirm these key settings in image_config.json:

Parameter	Default	Description
STREAM_URL	—	RTSP/RTMP/HTTP camera stream URL
DEVICE_ID	CAM-001	Camera device identifier
KAMIVISION_API_KEY	—	Your Kamivision API key
CAPTURE_INTERVAL	10	Seconds between frame captures
SIMILARITY_THRESHOLD	0.35	Search similarity threshold (0.0–1.0)
SEARCH_TOP_K	5	Max results per search
TIME_ZONE_OFFSET	0	UTC offset in hours for local time display (e.g. -12 for UTC+12, 8 for UTC+8)

Ask the user: do any parameters need to be changed?

Usage

Start Capture

.venv/bin/python image_search.py --start-capture

Stop Capture

.venv/bin/python image_search.py --stop-capture

Check Status

.venv/bin/python image_search.py --status

Import Images

# Single image
.venv/bin/python image_search.py --import /path/to/photo.jpg --json

# Entire directory (recursive)
.venv/bin/python image_search.py --import /path/to/photos/ --json

Search

.venv/bin/python image_search.py --search "keys on the table" --json

Search with Time Range

.venv/bin/python image_search.py \
  --search "person in blue jacket" \
  --time-start 1754538000 --time-end 1754541600 \
  --json

Output (stdout JSON)

{
  "status": "ok",
  "query": "keys on the table",
  "count": 1,
  "results": [
    {
      "image_name": "CAM-001_1754538507.jpg",
      "image_path": "/opt/image_data/CAM-001/20250815/CAM-001_1754538507.jpg",
      "description": "A set of keys and a wallet on a table",
      "timestamp": 1754538507,
      "time": "2025-08-15 10:00:07 AM",
      "score": 0.7823
    }
  ]
}

Exit Codes

Code	Meaning
0	Success
1	Error (config issue, stream failure, API error, runtime exception)

Troubleshooting

• bash: .venv/bin/python: No such file or directory → Run bash setup.sh
• OpenCV cannot open stream → Check camera is online and STREAM_URL is correct
• Kamivision API error → Verify KAMIVISION_API_KEY and network connectivity
• Unsupported file format → Only JPEG, PNG, BMP, WebP are supported
• No search results → Ensure images have been captured/imported; try lowering SIMILARITY_THRESHOLD
• FAISS index load failed → Index may be corrupted; system rebuilds automatically, re-import data if needed