\r \r

Kami SmartHome Suite\r

\r

Overview\r

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

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

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

Included Skills\r

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

Skill Map\r

\r

kami-smarthome-suite (this skill — installer entry point)\r
├── kami-package-detection    ── Package / delivery detection\r
├── kami-image-search         ── Image search\r
├── kami-video-search         ── Video recording & search\r
├── kami-fall-detection       ── Fall detection (cloud API)\r
├── kami-conflict-detection   ── Conflict / fight detection\r
└── kami-suspicious-person    ── Stranger / suspicious-person detection\r
```\r
\r
## Installation\r
\r
All Kami SmartHome skills are published on **ClawHub** and installed via `clawhub install`.\r
\r
### Option 1: One-click install (recommended)\r
\r
```bash\r
# Install the suite\r
clawhub install kami-smarthome-suite\r
\r
# Run setup.sh — auto-installs all 6 skills + guides centralized config\r
bash {baseDir}/setup.sh\r
```\r
\r
`setup.sh` performs:\r
1. One-shot install of all 6 Kami ecosystem skills from ClawHub\r
2. Detect / install Python 3.10:\r
   - **Debian/Ubuntu**: prefer conda → pyenv → system python3.10 (avoids `python3.10-venv` sudo dependency)\r
   - **Other systems**: prefer system python3.10 → pyenv → conda\r
   - 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\r
3. Interactive prompts for centralized config (API key, camera URL, notifications)\r
4. Auto-distribute the centralized config to each skill's local config files\r
\r
> Idempotent — re-running will not reinstall skills that are already present.\r
\r
### Option 2: Install individually\r
\r
You can also install specific skills directly from ClawHub:\r
\r
```bash\r
clawhub install kami-package-detection\r
clawhub install kami-image-search\r
clawhub install kami-video-search\r
clawhub install kami-fall-detection\r
clawhub install kami-conflict-detection\r
clawhub install kami-suspicious-person\r
```\r
\r
After individual installs, run `bash {baseDir}/configure.sh` to apply unified configuration.\r
\r
## Guided Setup (read this on first use)\r
\r
> **Agent behavior**: when this skill is triggered, follow this order:\r
> 1. Check whether sub-skills are installed (any missing sub-skill directory means "not installed") → if missing, run `bash {baseDir}/setup.sh`\r
> 2. Check whether `kamiclaw_api_key` is empty in `{baseDir}/kami_config.json` → if so, prompt the user\r
> 3. If both checks pass, skip the wizard and execute the user's request directly\r
\r
### Step 0: Install sub-skills\r
\r
- **Check**: look for sibling directories `kami-image-search`, `kami-video-search`, etc. next to `{baseDir}`\r
- **If missing**: run the one-click install:\r
  ```bash\r
  bash {baseDir}/setup.sh\r
  ```\r
  This script will: download all 6 sub-skills from ClawHub + create venvs + install dependencies\r
- **If present**: skip and proceed to config check\r
\r
### Step 1: Configure KamiClaw API key\r
\r
- **Check**: read the `kamiclaw_api_key` field from `{baseDir}/kami_config.json`\r
- **If empty**: tell the user 4 of the 6 skills require an API key, and prompt for one\r
- **How to obtain**: register at https://kamiclaw-skill.kamihome.com (free 200 credits)\r
- API-dependent skills: image-search, video-search, fall-detection, conflict-detection\r
- 2 fully-local skills (package-detection, suspicious-person) do not need an API key\r
\r
### Step 2: Configure notification channels\r
\r
- **Check**: read the `notifications` section of `{baseDir}/kami_config.json`\r
- **If all empty**: ask the user whether to set up alarm push (any combination is allowed)\r
- **Supported channels** (alarm skills `fall-detection` / `conflict-detection` / `suspicious-person` push automatically when events fire):\r
  - **Feishu Webhook**: `feishu_webhook_url` (+ optional `feishu_webhook_secret` for signed webhooks) — supported by all 3 alarm skills\r
  - **Telegram Bot**: `telegram_bot_token` + `telegram_chat_id` — supported by all 3 alarm skills\r
  - **Discord Webhook**: `discord_webhook_url` (push-only) — supported by all 3 alarm skills\r
  - **Discord Bot**: `discord_bot_token` + `discord_channel_id` (two-way) — **fall-detection only**\r
- All channels are optional; skipped channels just fall back to JSON output without push\r
- ⚠️ 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**\r
\r
### Configuration complete → all skills ready\r
\r
After the user provides values:\r
\r
1. Write the values back into the corresponding fields of `{baseDir}/kami_config.json`\r
2. Run distribution:\r
   ```bash\r
   bash {baseDir}/configure.sh --distribute\r
   ```\r
3. After distribution: tell the user that all skills are ready to use\r
\r
### Updating configuration later\r
\r
To change the API key or notification channels later:\r
\r
```bash\r
# Re-run the interactive wizard\r
bash {baseDir}/configure.sh\r
\r
# Or edit directly and redistribute\r
vim {baseDir}/kami_config.json\r
bash {baseDir}/configure.sh --distribute\r
```\r
\r
## Prerequisites\r
\r
- `clawhub` CLI installed (used to pull skills from ClawHub)\r
- Network access (for skill download + KamiClaw API calls from some skills)\r
\r
> **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.\r
\r
## Hardware Requirements\r
\r
Recommended minimum hardware for each skill:\r
\r
| Skill | CPU | Memory (RAM) | Storage | GPU | Notes |\r
|-------|-----|--------------|---------|-----|-------|\r
| kami-package-detection | 2+ cores | 2 GB | 500 MB | not required | YOLO-World ONNX, CPU-only |\r
| kami-image-search | 2+ cores | 2 GB | 5 GB+ | not required | FAISS index + SQLite frame history |\r
| kami-video-search | 2+ cores | 2 GB | 10 GB+ | not required | Stores video segments, scales with retention |\r
| kami-fall-detection | 1+ core | 1 GB | 200 MB | not required | Local does frame-diff only; inference runs in cloud |\r
| kami-conflict-detection | 4+ cores | 4 GB | 1 GB | optional (accelerates) | Local YOLO person detection + multi-frame analysis |\r
| kami-suspicious-person | 4+ cores | 4 GB | 1.5 GB | optional (accelerates) | SCRFD + ArcFace ONNX (~1 GB) |\r
\r
**Recommended config to run all 6 skills concurrently**:\r
- CPU: 4+ cores (x86_64 / ARM64)\r
- Memory: 8 GB+\r
- Storage: 20 GB+ free space\r
- Network: stable connection (RTSP pull + API calls)\r
- OS: Linux (Ubuntu 20.04+ recommended)\r
\r
> If you only enable a subset of skills, refer to the corresponding rows above.\r
\r
## Centralized Configuration\r
\r
### Design\r
\r
The suite uses a **central config + auto-distribute** model:\r
\r
```\r
kami_config.json (Single Source of Truth)\r
       │\r
       ▼  configure.py --distribute\r
       ├── kami-image-search/image_config.json\r
       ├── kami-video-search/stream_config.json\r
       ├── kami-fall-detection/config.json\r
       ├── kami-package-detection/config.json\r
       ├── ~/.kami/kami.env (env-based skills)\r
       └── ~/.kami/credentials.json (credential cache)\r
```\r
\r
### Central config file `kami_config.json`\r
\r
Located in the suite directory, it contains the following sections:\r
\r
| Section | Description | Skills affected |\r
|---------|-------------|-----------------|\r
| `kamiclaw_api_key` | KamiClaw API key | The 4 cloud-API skills |\r
| `cameras.default` | Camera RTSP URL / device ID | 4 JSON-config skills (auto-distributed) + others via env vars / CLI |\r
| `notifications` | Feishu / Telegram / Discord push settings | fall-detection, conflict-detection, suspicious-person |\r
| `skills.\x3Cname>` | Per-skill tuning parameters | The corresponding skill |\r
\r
Edit this file once and every skill is configured.\r
\r
### Usage\r
\r
```bash\r
# Mode 1: interactive wizard (prompts each field)\r
bash {baseDir}/configure.sh\r
\r
# Mode 2: set API key directly\r
bash {baseDir}/configure.sh sk_live_xxxxxxxx\r
\r
# Mode 3: edit manually then distribute\r
vim {baseDir}/kami_config.json\r
bash {baseDir}/configure.sh --distribute\r
\r
# Mode 4: show current config\r
bash {baseDir}/configure.sh --show\r
```\r
\r
### Distribution Map\r
\r
**A. JSON config files (auto-patched)**\r
\r
| Skill | Target file | Distributed fields |\r
|-------|-------------|--------------------|\r
| `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` |\r
| `kami-video-search`       | `stream_config.json` | `KAMI_API_KEY`, `STREAM_URL`, `DEVICE_ID` |\r
| `kami-image-search`       | `image_config.json`  | `KAMIVISION_API_KEY`, `STREAM_URL`, `DEVICE_ID` |\r
| `kami-package-detection`  | `config.json`        | `rtsp_url`, `conf_threshold`, `run_time` (pure local inference, no API key, `class_names` is NOT distributed) |\r
\r
**B. Environment variable file `~/.kami/kami.env`**\r
\r
| Skill | Variables |\r
|-------|-----------|\r
| `kami-conflict-detection` | `KAMI_API_KEY`, `FEISHU_WEBHOOK_URL`, `FEISHU_WEBHOOK_SECRET`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `DISCORD_WEBHOOK_URL` (run `source ~/.kami/kami.env` before launch) |\r
| `kami-suspicious-person`  | `FEISHU_WEBHOOK_URL`, `FEISHU_WEBHOOK_SECRET`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `DISCORD_WEBHOOK_URL` (run `source ~/.kami/kami.env` before launch) |\r
\r
> ⚠️ `HTTPS_PROXY` is **not** written into `~/.kami/kami.env`. If you need a proxy to reach Discord / Telegram, configure it in your shell rc yourself.\r
\r
**C. No cloud config needed (pure local inference)**\r
\r
| Skill | Notes |\r
|-------|-------|\r
| `kami-suspicious-person` | Pure local ONNX (SCRFD + ArcFace), no API key required; webhook env vars are still distributed via Type B above |\r
\r
### Integration with setup.sh\r
\r
After installing all skills, `setup.sh` automatically enters the centralized config flow:\r
- Prompts for API key, camera URL, notification webhooks\r
- Saves to `kami_config.json` and distributes to each skill\r
- If skipped, run `bash configure.sh` later anytime\r
- Credentials are cached to `~/.kami/credentials.json` and reused on subsequent installs\r
\r
## Per-skill Quick Reference\r
\r
| Skill | Local config file | Source | API key | Camera URL | Webhook |\r
|-------|-------------------|--------|---------|------------|---------|\r
| kami-package-detection  | `config.json` | ← auto-distributed from `kami_config.json` | not needed | ✅ auto-distributed | not needed |\r
| kami-image-search       | `image_config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | not needed |\r
| kami-video-search       | `stream_config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | not needed |\r
| kami-fall-detection     | `config.json` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | ✅ auto-distributed | ✅ auto-distributed |\r
| kami-conflict-detection | `~/.kami/kami.env` | ← auto-distributed from `kami_config.json` | ✅ auto-distributed | `--rtsp_url` | ✅ auto-distributed |\r
| kami-suspicious-person  | `~/.kami/kami.env` + `face_db/` | ← auto-distributed from `kami_config.json` | not needed | `--rtsp_url` | ✅ auto-distributed |\r
\r
## Privacy Notice\r
\r
This suite involves camera streams, image capture and face recognition. Please review the following privacy notes before use:\r
\r
### Data handling\r
\r
| Skill | Processing | Data sent to cloud | Data stored locally |\r
|-------|-----------|--------------------|---------------------|\r
| kami-package-detection | Pure local inference | none | no persistent storage |\r
| kami-image-search | Capture → cloud VLM captioning | image frames (for description and embedding generation) | captured frames, captions, FAISS index |\r
| kami-video-search | Recording → cloud VLM captioning | key frames of clips (for description and embedding generation) | video segments, captions |\r
| kami-fall-detection | Local frame-diff → cloud AI judgment | changed frames (only when motion is detected) | alarm clips (configurable) |\r
| kami-conflict-detection | Local person detection → cloud conflict analysis | multi-frame snapshots (only when multiple people are present) | no persistent storage |\r
| kami-suspicious-person | Pure local inference | none | face feature DB (user-built) |\r
\r
### Cloud API calls\r
\r
- 4 skills depend on **KamiClaw API** (image-search, video-search, fall-detection, conflict-detection)\r
- Data sent to the cloud is used only for real-time inference and is **not persisted nor used for model training**\r
- API traffic uses HTTPS encryption\r
\r
### Local data storage\r
\r
- Captured frames, video segments, etc. are stored under each skill's working directory and can be cleaned manually\r
- `image-search` and `video-search` honor a `retention_days` parameter for automatic expiry\r
- The API key is cached in `~/.kami/credentials.json` (mode 600, current user only)\r
\r
### Face data (kami-suspicious-person)\r
\r
- The face feature database is built and matched fully locally — **nothing is uploaded to any server**\r
- Files are stored under `face_db/`, fully under user control\r
- Removing the `face_db/` directory wipes all face data\r
\r
### User control\r
\r
- Users freely choose which skills to enable; disabled skills collect nothing\r
- All camera URLs are user-supplied; skills do not auto-discover or auto-connect cameras\r
- Users can stop a skill, delete local data, or revoke the API key at any time\r
\r
> Privacy policy details: https://kamiclaw-skill.kamihome.com/privacy\r
\r
## Exit Codes\r
\r
| Exit code | Meaning |\r
|-----------|---------|\r
| `0` | All skills installed successfully |\r
| `1` | Some skills failed to install (check logs) |\r
| `2` | Prerequisite missing (no `clawhub`, or neither conda nor pyenv is usable and Python 3.10 cannot be installed) |\r
\r
## Troubleshooting\r
\r
**`clawhub` CLI not available**\r
```\r
clawhub: command not found\r
```\r
→ Install the ClawHub CLI first.\r
\r
**A skill failed to install**\r
```\r
[!] kami-xxx (failed, exit 1)\r
```\r
→ Retry: `clawhub install kami-xxx`\r
\r
**KamiClaw API key not configured**\r
→ Run `bash configure.sh` or register at https://kamiclaw-skill.kamihome.com\r
\r
**Config changes have no effect**\r
→ After editing `kami_config.json`, run `bash configure.sh --distribute` to push the changes to each skill.\r