RingGuard

AI-assisted Ring camera event triage for Home Assistant.

RingGuard listens for Ring motion events from Home Assistant, downloads the recent Ring recording, runs visual analysis, and can place a Twilio voice call when an event crosses your alert threshold.

RingGuard is experimental. It is not a security system, alarm system, emergency response system, professional monitoring service, or substitute for human review. See Safety Disclaimer and DISCLAIMER.md.

What It Does

• Receives Ring motion events from Home Assistant.
• Downloads short-lived Ring MP4 recording URLs locally.
• Samples video frames for OpenAI vision analysis.
• Optionally escalates ambiguous cases to TwelveLabs Pegasus full-video analysis.
• Places Twilio voice calls only when configured thresholds are met.
• Stores event logs and analysis artifacts locally under data/.
• Defaults to dry-run calls for safer first-time setup.

Architecture

Ring camera
  -> Home Assistant Ring integration
  -> Home Assistant automation
  -> ringguard-api
  -> ringguard-worker
  -> OpenAI frame analysis
  -> optional TwelveLabs video analysis
  -> optional Twilio voice call

Signed Ring URLs are used only to download the MP4. They are not passed to OpenAI or TwelveLabs.

Quick Start

From the repository root:

cp .env.example .env
docker compose up -d --build

Open Home Assistant:

http://localhost:8123

Add the Ring integration in Home Assistant, then configure your .env camera map and Home Assistant automations.

Services

Service	URL / Role
Home Assistant	http://localhost:8123
RingGuard API	http://localhost:8787
RingGuard worker	Background Docker service

Event Flow

1. Home Assistant receives a Ring motion event.
2. Home Assistant posts event metadata to ringguard-api.
3. ringguard-api writes the event to data/events/events.jsonl and queues it.
4. ringguard-worker waits briefly for the Ring recording URL to refresh.
5. The worker reads the signed Ring MP4 URL from Home Assistant state and downloads the video locally.
6. The worker samples frames and runs OpenAI image analysis.
7. If OpenAI confidence is low or the score is in the medium range, the worker runs TwelveLabs Pegasus on the full MP4.
8. If the final decision crosses call thresholds, the worker places a Twilio voice call.

Configuration

Create .env in the repository root. Start from:

cp .env.example .env

Fill in the values:

OPENAI_API_KEY=...
TWELVELABS_API_KEY=...
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_FROM_NUMBER=+1...
ALERT_TO_NUMBER=+1...
TWILIO_TTS_VOICE=Google.en-US-Chirp3-HD-Aoede
TWILIO_TTS_LANGUAGE=en-US
TWILIO_CALL_PAUSE_SECONDS=1
RINGGUARD_CAMERA_ENTITY_MAP={"example_camera":"camera.example_camera_live_view"}

.env is ignored by git.

Ring Camera Mapping

RingGuard needs a stable camera key from Home Assistant automations and a matching Ring camera entity that exposes video_url.

Configure the mapping in .env:

RINGGUARD_CAMERA_ENTITY_MAP={"front_door":"camera.front_door_live_view","driveway":"camera.driveway_live_view"}

Then create Home Assistant automations that post matching camera keys to rest_command.ringguard_event. See homeassistant/config/automations.example.yaml for a template. Copy the example into homeassistant/config/automations.yaml and update the entity IDs/camera keys for your Ring devices.

Thresholds

Current defaults:

RINGGUARD_TWELVELABS_LOW_CONFIDENCE=70
RINGGUARD_TWELVELABS_MEDIUM_SCORE_MIN=35
RINGGUARD_TWELVELABS_MEDIUM_SCORE_MAX=75
RINGGUARD_CALL_HIGH_SCORE=80
RINGGUARD_CALL_AMBIGUOUS_SCORE=65
RINGGUARD_CALL_DEDUPE_SECONDS=600
RINGGUARD_CALL_DRY_RUN=true
RINGGUARD_CALL_ALWAYS=false

Interpretation:

• Run TwelveLabs when OpenAI confidence is under 70.
• Run TwelveLabs when OpenAI score is 35-75.
• Place a call when any model returns should_text=true.
• Place a call when max score is at least 80.
• Place a call when score is at least 65 and confidence is low enough to need escalation.
• Deduplicate calls per camera for 10 minutes.
• Keep calls in dry-run mode until RINGGUARD_CALL_DRY_RUN=false is set explicitly.

Operations

Check recent events:

curl "http://localhost:8787/events/recent?limit=5"

Follow worker logs:

docker compose logs -f ringguard-worker

Stop services:

docker compose down

Run artifacts are written under:

data/analysis-runs

Safety Disclaimer

RingGuard is an experimental personal automation project for summarizing Ring camera motion events and testing AI-assisted notifications.

RingGuard is not a security system, alarm system, emergency response system, professional monitoring service, law-enforcement tool, medical/safety device, or substitute for professional security, emergency services, or human review.

It may fail to detect suspicious, dangerous, illegal, emergency, or safety-critical situations. It may also generate false alarms, delayed alerts, incomplete alerts, misleading summaries, incorrect scores, or no alert at all.

Do not rely on RingGuard to protect people, property, pets, valuables, premises, or any other safety-critical interest. See DISCLAIMER.md.

License

Apache License 2.0. See LICENSE.