---
name: kami-smarthome-suite
description: "Kami SmartHome skill bundle. One-click installer for the entire Kami SmartHome ecosystem with centralized configuration (API key, cameras, notifications) — no more configuring each skill individually."
version: 1.0.0
author: kami-smarthome
tags:
  - smart-home
  - kami
  - smarthome
  - suite
  - bundle
  - camera
  - rtsp
  - detect
  - video
  - image-search
  - package-detection
  - fall-detection
  - conflict-detection
  - face-recognition
  - surveillance
  - security
triggers:
  - kami smart home
  - kami smarthome suite
  - install kami skills
  - install all kami
  - smart home suite
  - kami home assistant
  - install kami suite
  - kami all skills
  - smart home bundle
metadata:
  openclaw:
    requires:
      bins:
        - python3.10
      hardware:
        cpu: "4+ cores (x86_64 / ARM64)"
        memory: "8 GB+"
        storage: "20 GB+"
        gpu: "optional (speeds up ONNX inference)"
      network:
        - "RTSP camera access (LAN)"
        - "Internet (KamiClaw API)"
      devices:
        - "RTSP IP camera"
    emoji: "🏠"
---

# Kami SmartHome Suite

## Overview

Kami SmartHome Suite is the one-stop installer for the **kami-smarthome** ecosystem. By installing this single skill, users get:

1. **Batch download** — install all 6 ecosystem skills from ClawHub in one go
2. **Guided configuration** — interactive setup for API key and notification channels; **all skills are ready to use immediately after configuration**
3. **Centralized config management** — to change anything later, edit one file and run `configure.sh --distribute` to sync

> Design principle: **Single Source of Truth** — one config file controls all skills.
> Core promise: **configure once, run everywhere** — once API key and notification channels are set, all 6 skills work out of the box.

## Included Skills

This suite bundles the following 6 standalone skills:

| # | Skill | Emoji | Description | Use case |
|---|-------|-------|-------------|----------|
| 1 | **kami-package-detection**   | 📦 | Real-time package/parcel detection on RTSP streams using YOLO-World ONNX | Doorstep delivery alerts |
| 2 | **kami-image-search**        | 🔍 | Periodic frame capture + VLM captioning + FAISS index for natural-language image search | Search historical frames |
| 3 | **kami-video-search**        | 📹 | Continuous video segmentation + VLM scene description + natural-language clip search | Search historical clips |
| 4 | **kami-fall-detection**      | 🚨 | Frame-difference detection + KamiClaw cloud inference for fall events | Elder / lone-resident care |
| 5 | **kami-conflict-detection**  | 🥊 | Multi-person physical conflict (fight/shove) detection with event-driven alarm JSON | Security alerting |
| 6 | **kami-suspicious-person**   | 🕵️ | Stranger recognition via SCRFD + ArcFace, detects unregistered face loitering | Doorway / stranger-loiter alerts |

### Skill Map

```
kami-smarthome-suite (this skill — installer entry point)
├── kami-package-detection    ── Package / delivery detection
├── kami-image-search         ── Image search
├── kami-video-search         ── Video recording & search
├── kami-fall-detection       ── Fall detection (cloud API)
├── kami-conflict-detection   ── Conflict / fight detection
└── kami-suspicious-person    ── Stranger / suspicious-person detection
```

## Installation

All Kami SmartHome skills are published on **ClawHub** and installed via `clawhub install`.

### Option 1: One-click install (recommended)

```bash
# Install the suite
clawhub install kami-smarthome-suite

# Run setup.sh — auto-installs all 6 skills + guides centralized config
bash {baseDir}/setup.sh
```

`setup.sh` performs:
1. One-shot install of all 6 Kami ecosystem skills from ClawHub
2. Detect / install Python 3.10:
   - **Debian/Ubuntu**: prefer conda → pyenv → system python3.10 (avoids `python3.10-venv` sudo dependency)
   - **Other systems**: prefer system python3.10 → pyenv → conda
   - If none found: auto-install (conda preferred → pyenv as fallback), no sudo required; only pyenv source build will ask for sudo when build-deps are missing
3. Interactive prompts for centralized config (API key, camera URL, notifications)
4. Auto-distribute the centralized config to each skill's local config files

> Idempotent — re-running will not reinstall skills that are already present.

### Option 2: Install individually

You can also install specific skills directly from ClawHub:

```bash
clawhub install kami-package-detection
clawhub install kami-image-search
clawhub install kami-video-search
clawhub install kami-fall-detection
clawhub install kami-conflict-detection
clawhub install kami-suspicious-person
```

After individual installs, run `bash {baseDir}/configure.sh` to apply unified configuration.

## Guided Setup (read this on first use)

> **Agent behavior**: when this skill is triggered, follow this order:
> 1. Check whether sub-skills are installed (any missing sub-skill directory means "not installed") → if missing, run `bash {baseDir}/setup.sh`
> 2. Check whether `kamiclaw_api_key` is empty in `{baseDir}/kami_config.json` → if so, prompt the user
> 3. If both checks pass, skip the wizard and execute the user's request directly

### Step 0: Install sub-skills

- **Check**: look for sibling directories `kami-image-search`, `kami-video-search`, etc. next to `{baseDir}`
- **If missing**: run the one-click install:
  ```bash
  bash {baseDir}/setup.sh
  ```
  This script will: download all 6 sub-skills from ClawHub + create venvs + install dependencies
- **If present**: skip and proceed to config check

### Step 1: Configure KamiClaw API key

- **Check**: read the `kamiclaw_api_key` field from `{baseDir}/kami_config.json`
- **If empty**: tell the user 4 of the 6 skills require an API key, and prompt for one
- **How to obtain**: register at https://kamiclaw-skill.kamihome.com (free 200 credits)
- API-dependent skills: image-search, video-search, fall-detection, conflict-detection
- 2 fully-local skills (package-detection, suspicious-person) do not need an API key

### Step 2: Configure notification channels

- **Check**: read the `notifications` section of `{baseDir}/kami_config.json`
- **If all empty**: ask the user whether to set up alarm push (any combination is allowed)
- **Supported channels** (alarm skills `fall-detection` / `conflict-detection` / `suspicious-person` push automatically when events fire):
  - **Feishu Webhook**: `feishu_webhook_url` (+ optional `feishu_webhook_secret` for signed webhooks) — supported by all 3 alarm skills
  - **Telegram Bot**: `telegram_bot_token` + `telegram_chat_id` — supported by all 3 alarm skills
  - **Discord Webhook**: `discord_webhook_url` (push-only) — supported by all 3 alarm skills
  - **Discord Bot**: `discord_bot_token` + `discord_channel_id` (two-way) — **fall-detection only**
- All channels are optional; skipped channels just fall back to JSON output without push
- ⚠️ Discord / Telegram may be unreachable from some regions. If a proxy is needed, set `HTTPS_PROXY` in your shell rc (e.g. `~/.bashrc`) yourself — **the suite intentionally does NOT manage proxy settings**

### Configuration complete → all skills ready

After the user provides values:

1. Write the values back into the corresponding fields of `{baseDir}/kami_config.json`
2. Run distribution:
   ```bash
   bash {baseDir}/configure.sh --distribute
   ```
3. After distribution: tell the user that all skills are ready to use

### Updating configuration later

To change the API key or notification channels later:

```bash
# Re-run the interactive wizard
bash {baseDir}/configure.sh

# Or edit directly and redistribute
vim {baseDir}/kami_config.json
bash {baseDir}/configure.sh --distribute
```

## Prerequisites

- `clawhub` CLI installed (used to pull skills from ClawHub)
- Network access (for skill download + KamiClaw API calls from some skills)

> **Python 3.10 is required**. `setup.sh` selects detection priority by OS family (Debian/Ubuntu prefers conda/pyenv; other systems prefer system python3.10) and auto-installs via conda when missing. Other dependencies are managed by each sub-skill.

## Hardware Requirements

Recommended minimum hardware for each skill:

| Skill | CPU | Memory (RAM) | Storage | GPU | Notes |
|-------|-----|--------------|---------|-----|-------|
| kami-package-detection | 2+ cores | 2 GB | 500 MB | not required | YOLO-World ONNX, CPU-only |
| kami-image-search | 2+ cores | 2 GB | 5 GB+ | not required | FAISS index + SQLite frame history |
| kami-video-search | 2+ cores | 2 GB | 10 GB+ | not required | Stores video segments, scales with retention |
| kami-fall-detection | 1+ core | 1 GB | 200 MB | not required | Local does frame-diff only; inference runs in cloud |
| kami-conflict-detection | 4+ cores | 4 GB | 1 GB | optional (accelerates) | Local YOLO person detection + multi-frame analysis |
| kami-suspicious-person | 4+ cores | 4 GB | 1.5 GB | optional (accelerates) | SCRFD + ArcFace ONNX (~1 GB) |

**Recommended config to run all 6 skills concurrently**:
- CPU: 4+ cores (x86_64 / ARM64)
- Memory: 8 GB+
- Storage: 20 GB+ free space
- Network: stable connection (RTSP pull + API calls)
- OS: Linux (Ubuntu 20.04+ recommended)

> If you only enable a subset of skills, refer to the corresponding rows above.

## Centralized Configuration

### Design

The suite uses a **central config + auto-distribute** model:

```
kami_config.json (Single Source of Truth)
       │
       ▼  configure.py --distribute
       ├── kami-image-search/image_config.json
       ├── kami-video-search/stream_config.json
       ├── kami-fall-detection/config.json
       ├── kami-package-detection/config.json
       ├── kami-conflict-detection/config.json
       ├── kami-suspicious-person/config.json
       └── ~/.kami/credentials.json (credential cache)
```

### Central config file `kami_config.json`

Located in the suite directory, it contains the following sections:

| Section | Description | Skills affected |
|---------|-------------|-----------------|
| `kamiclaw_api_key` | KamiClaw API key | The 4 cloud-API skills |
| `cameras.default` | Camera RTSP URL / device ID | All 6 skills (auto-distributed to each skill's local config) |
| `notifications` | Feishu / Telegram / Discord push settings | fall-detection, conflict-detection, suspicious-person |
| `skills.<name>` | Per-skill tuning parameters | The corresponding skill |

Edit this file once and every skill is configured.

### Usage

```bash
# Mode 1: interactive wizard (prompts each field)
bash {baseDir}/configure.sh

# Mode 2: set API key directly
bash {baseDir}/configure.sh sk_live_xxxxxxxx

# Mode 3: edit manually then distribute
vim {baseDir}/kami_config.json
bash {baseDir}/configure.sh --distribute

# Mode 4: show current config
bash {baseDir}/configure.sh --show
```

### Distribution Map

**All skills use a local `config.json`-style file (auto-patched on `configure.sh --distribute`)**

| Skill | Target file | Distributed fields |
|-------|-------------|--------------------|
| `kami-fall-detection`     | `config.json`        | `api_key`, `rtsp_url`, `feishu_webhook_url`, `telegram_bot_token`, `telegram_chat_id`, `discord_webhook_url`, `discord_bot_token`, `discord_channel_id` |
| `kami-video-search`       | `stream_config.json` | `KAMI_API_KEY`, `STREAM_URL`, `DEVICE_ID` |
| `kami-image-search`       | `image_config.json`  | `KAMIVISION_API_KEY`, `STREAM_URL`, `DEVICE_ID` |
| `kami-package-detection`  | `config.json`        | `rtsp_url`, `conf_threshold`, `run_time` (pure local inference, no API key, `class_names` is NOT distributed) |
| `kami-conflict-detection` | `config.json`        | `kami_api_key`, `rtsp_url`, `feishu_webhook`, `discord_webhook`, `telegram_bot_token`, `telegram_chat_id` |
| `kami-suspicious-person`  | `config.json`        | `rtsp_url`, `feishu_webhook`, `discord_webhook`, `telegram_bot_token`, `telegram_chat_id` (pure local inference, no API key) |

> Each skill's argparse still keeps `os.environ.get(...)` fallbacks for `KAMI_API_KEY`, `FEISHU_WEBHOOK_URL`, `TELEGRAM_*`, `DISCORD_WEBHOOK_URL`, `HTTPS_PROXY`. So power users can still export env vars manually — but the suite no longer manages `~/.kami/kami.env` itself.
>
> ⚠️ `HTTPS_PROXY` is **not** part of `kami_config.json`. If you need a proxy to reach Discord / Telegram, set it in your shell rc yourself.

### Integration with setup.sh

After installing all skills, `setup.sh` automatically enters the centralized config flow:
- Prompts for API key, camera URL, notification webhooks
- Saves to `kami_config.json` and distributes to each skill
- If skipped, run `bash configure.sh` later anytime
- Credentials are cached to `~/.kami/credentials.json` and reused on subsequent installs

## Per-skill Quick Reference

| Skill | Local config file | Source | API key | Camera URL | Webhook |
|-------|-------------------|--------|---------|------------|---------|
| kami-package-detection  | `config.json` | ← auto-distributed from `kami_config.json` | not needed | ✅ auto-distributed | not needed |
| kami-image-search       | `image_config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | not needed |
| kami-video-search       | `stream_config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | not needed |
| kami-fall-detection     | `config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | ✅ auto-distributed |
| kami-conflict-detection | `config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | ✅ auto-distributed |
| kami-suspicious-person  | `config.json` + `face_db/` | ← auto-distributed from `kami_config.json` | not needed | ✅ auto-distributed | ✅ auto-distributed |

## Privacy Notice

This suite involves camera streams, image capture and face recognition. Please review the following privacy notes before use:

### Data handling

| Skill | Processing | Data sent to cloud | Data stored locally |
|-------|-----------|--------------------|---------------------|
| kami-package-detection | Pure local inference | none | no persistent storage |
| kami-image-search | Capture → cloud VLM captioning | image frames (for description and embedding generation) | captured frames, captions, FAISS index |
| kami-video-search | Recording → cloud VLM captioning | key frames of clips (for description and embedding generation) | video segments, captions |
| kami-fall-detection | Local frame-diff → cloud AI judgment | changed frames (only when motion is detected) | alarm clips (configurable) |
| kami-conflict-detection | Local person detection → cloud conflict analysis | multi-frame snapshots (only when multiple people are present) | no persistent storage |
| kami-suspicious-person | Pure local inference | none | face feature DB (user-built) |

### Cloud API calls

- 4 skills depend on **KamiClaw API** (image-search, video-search, fall-detection, conflict-detection)
- Data sent to the cloud is used only for real-time inference and is **not persisted nor used for model training**
- API traffic uses HTTPS encryption

### Local data storage

- Captured frames, video segments, etc. are stored under each skill's working directory and can be cleaned manually
- `image-search` and `video-search` honor a `retention_days` parameter for automatic expiry
- The API key is cached in `~/.kami/credentials.json` (mode 600, current user only)

### Face data (kami-suspicious-person)

- The face feature database is built and matched fully locally — **nothing is uploaded to any server**
- Files are stored under `face_db/`, fully under user control
- Removing the `face_db/` directory wipes all face data

### User control

- Users freely choose which skills to enable; disabled skills collect nothing
- All camera URLs are user-supplied; skills do not auto-discover or auto-connect cameras
- Users can stop a skill, delete local data, or revoke the API key at any time

> Privacy policy details: https://kamiclaw-skill.kamihome.com/privacy

## Exit Codes

| Exit code | Meaning |
|-----------|---------|
| `0` | All skills installed successfully |
| `1` | Some skills failed to install (check logs) |
| `2` | Prerequisite missing (no `clawhub`, or neither conda nor pyenv is usable and Python 3.10 cannot be installed) |

## Troubleshooting

**`clawhub` CLI not available**
```
clawhub: command not found
```
→ Install the ClawHub CLI first.

**A skill failed to install**
```
[!] kami-xxx (failed, exit 1)
```
→ Retry: `clawhub install kami-xxx`

**KamiClaw API key not configured**
→ Run `bash configure.sh` or register at https://kamiclaw-skill.kamihome.com

**Config changes have no effect**
→ After editing `kami_config.json`, run `bash configure.sh --distribute` to push the changes to each skill.