stoop 0.1.0__py3-none-any.whl

stoop/__init__.py

@@ -0,0 +1,55 @@
+"""stoop: turn front-door events into decisions a person can act on.
+
+Ingest events from Ring (or anything else), remember who is expected and what is normal,
+decide whether to ignore, log, notify or escalate, and keep every sensitive action behind
+a human confirmation.
+"""
+
+from stoop.events import Detected, Event, EventKind, MediaRef
+from stoop.memory import (
+    Action,
+    Decision,
+    ExpectedVisit,
+    Person,
+    Role,
+    Severity,
+    Site,
+    SiteKind,
+    Store,
+    SuggestedAction,
+    Visit,
+)
+from stoop.pipeline import CallbackSink, LogSink, Pipeline, Sink
+from stoop.policy import PolicyConfig, PolicyEngine, RoutineModel
+from stoop.reasoning import DeterministicReasoner, Reasoner, ReasoningContext, Refinement
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Action",
+    "CallbackSink",
+    "Decision",
+    "Detected",
+    "DeterministicReasoner",
+    "Event",
+    "EventKind",
+    "ExpectedVisit",
+    "LogSink",
+    "MediaRef",
+    "Person",
+    "Pipeline",
+    "PolicyConfig",
+    "PolicyEngine",
+    "Reasoner",
+    "ReasoningContext",
+    "Refinement",
+    "Role",
+    "RoutineModel",
+    "Severity",
+    "Sink",
+    "Site",
+    "SiteKind",
+    "Store",
+    "SuggestedAction",
+    "Visit",
+]

stoop/events.py

@@ -0,0 +1,93 @@
+"""Normalized front-door events.
+
+Every source (Ring webhooks, Ring history, synthetic scenarios, other devices) is
+converted into :class:`Event` so the memory, policy and reasoning layers never see
+vendor-specific shapes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class EventKind(StrEnum):
+    MOTION = "motion"
+    BUTTON_PRESS = "button_press"
+    LIVE_VIEW = "live_view"
+    DOOR_OPENED = "door_opened"
+    DOOR_CLOSED = "door_closed"
+    DEVICE_ONLINE = "device_online"
+    DEVICE_OFFLINE = "device_offline"
+    SENSOR_ALERT = "sensor_alert"
+    SENSOR_CLEARED = "sensor_cleared"
+    ACCOUNT = "account"  # link/unlink, devices shared or removed, subscription changes: not door activity
+    OTHER = "other"
+
+
+class Detected(StrEnum):
+    """What a camera believes it saw. Only motion events carry this."""
+
+    HUMAN = "human"
+    VEHICLE = "vehicle"
+    ANIMAL = "animal"
+    PACKAGE = "package"
+    MOTION = "motion"
+    UNKNOWN = "unknown"
+
+
+class MediaRef(BaseModel):
+    """Pointer to media that an app can fetch later (never the bytes themselves)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: str  # snapshot | clip | live
+    device_id: str
+    at: datetime | None = None
+    url: str | None = None
+    content_type: str | None = None
+
+
+class Event(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    site_id: str
+    source: str
+    kind: EventKind
+    device_id: str
+    occurred_at: datetime
+    detected: Detected | None = None
+    device_name: str | None = None
+    sensor: str | None = None  # flood, freeze, tamper, co, ... for SENSOR_* kinds
+    media: list[MediaRef] = Field(default_factory=list)
+    dedupe_key: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("occurred_at")
+    @classmethod
+    def _aware(cls, value: datetime) -> datetime:
+        if value.tzinfo is None:
+            raise ValueError("occurred_at must be timezone-aware")
+        return value.astimezone(UTC)
+
+    @property
+    def key(self) -> str:
+        """Routine-model bucket key, e.g. ``motion:human`` or ``button_press``."""
+        if self.kind is EventKind.MOTION:
+            return f"motion:{(self.detected or Detected.UNKNOWN).value}"
+        return self.kind.value
+
+    @property
+    def is_presence(self) -> bool:
+        """True when a person is plausibly at the door."""
+        return self.kind is EventKind.BUTTON_PRESS or (self.kind is EventKind.MOTION and self.detected is Detected.HUMAN)
+
+
+def make_event_id(source: str, dedupe_key: str) -> str:
+    """Stable id derived from the source's own unique key, so replays never duplicate."""
+    return hashlib.sha1(f"{source}:{dedupe_key}".encode()).hexdigest()[:20]

stoop/memory/__init__.py

@@ -0,0 +1,31 @@
+from stoop.memory.models import (
+    SEVERITY_ORDER,
+    Action,
+    Decision,
+    ExpectedVisit,
+    Person,
+    Role,
+    Severity,
+    Site,
+    SiteKind,
+    SuggestedAction,
+    Visit,
+    VisitStatus,
+)
+from stoop.memory.store import Store
+
+__all__ = [
+    "SEVERITY_ORDER",
+    "Action",
+    "Decision",
+    "ExpectedVisit",
+    "Person",
+    "Role",
+    "Severity",
+    "Site",
+    "SiteKind",
+    "Store",
+    "SuggestedAction",
+    "Visit",
+    "VisitStatus",
+]

stoop/memory/models.py

@@ -0,0 +1,193 @@
+"""Context memory: who is expected, what a site is, what happened, what was decided."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, date, datetime, time, timedelta
+from enum import StrEnum
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid.uuid4().hex[:12]}"
+
+
+def utcnow() -> datetime:
+    return datetime.now(tz=UTC)
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SiteKind(StrEnum):
+    HOME = "home"
+    RENTAL = "rental"
+    OFFICE = "office"
+    CLINIC = "clinic"
+
+
+class Site(_Model):
+    id: str
+    name: str
+    timezone: str = "America/New_York"
+    kind: SiteKind = SiteKind.HOME
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def zone(self) -> ZoneInfo:
+        return ZoneInfo(self.timezone)
+
+
+class Role(StrEnum):
+    FAMILY = "family"
+    AIDE = "aide"
+    NURSE = "nurse"
+    NEIGHBOR = "neighbor"
+    COURIER = "courier"
+    CLEANER = "cleaner"
+    CONTRACTOR = "contractor"
+    GUEST = "guest"
+    OTHER = "other"
+
+
+class Person(_Model):
+    id: str = Field(default_factory=lambda: new_id("per"))
+    site_id: str
+    name: str
+    role: Role = Role.OTHER
+    phone: str | None = None
+    email: str | None = None
+    notes: str | None = None
+    trusted: bool = True
+    # App-level preferences (notification channels, thresholds, ...). Free-form on purpose.
+    preferences: dict[str, Any] = Field(default_factory=dict)
+
+
+class ExpectedVisit(_Model):
+    """A visit window. Either one-off (``window_start``/``window_end``) or recurring
+    (``days_of_week`` + ``local_start``/``local_end``)."""
+
+    id: str = Field(default_factory=lambda: new_id("exp"))
+    site_id: str
+    label: str
+    person_id: str | None = None
+    window_start: datetime | None = None
+    window_end: datetime | None = None
+    days_of_week: list[int] | None = None  # 0 = Monday
+    local_start: time | None = None
+    local_end: time | None = None
+    expected_duration_min: int | None = None
+    origin: str = "manual"  # manual | calendar | booking
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("window_start", "window_end")
+    @classmethod
+    def _aware(cls, value: datetime | None) -> datetime | None:
+        if value is not None and value.tzinfo is None:
+            raise ValueError("expected-visit windows must be timezone-aware")
+        return value
+
+    @property
+    def recurring(self) -> bool:
+        return bool(self.days_of_week) and self.local_start is not None and self.local_end is not None
+
+    def windows_between(self, t0: datetime, t1: datetime, zone: ZoneInfo) -> list[tuple[datetime, datetime]]:
+        """Concrete windows overlapping [t0, t1]."""
+        if not self.recurring:
+            if self.window_start and self.window_end and self.window_end >= t0 and self.window_start <= t1:
+                return [(self.window_start, self.window_end)]
+            return []
+        assert self.days_of_week is not None and self.local_start and self.local_end
+        out: list[tuple[datetime, datetime]] = []
+        day: date = (t0.astimezone(zone) - timedelta(days=1)).date()
+        last: date = (t1.astimezone(zone) + timedelta(days=1)).date()
+        while day <= last:
+            if day.weekday() in self.days_of_week:
+                ws = datetime.combine(day, self.local_start, tzinfo=zone)
+                we = datetime.combine(day, self.local_end, tzinfo=zone)
+                if we < ws:
+                    we += timedelta(days=1)
+                if we >= t0 and ws <= t1:
+                    out.append((ws.astimezone(UTC), we.astimezone(UTC)))
+            day += timedelta(days=1)
+        return out
+
+
+class VisitStatus(StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+class Visit(_Model):
+    """A cluster of events close in time at one site (someone came to the door)."""
+
+    id: str = Field(default_factory=lambda: new_id("vis"))
+    site_id: str
+    started_at: datetime
+    last_event_at: datetime
+    ended_at: datetime | None = None
+    status: VisitStatus = VisitStatus.OPEN
+    event_ids: list[str] = Field(default_factory=list)
+    presence_count: int = 0
+    rang: bool = False
+    door_opened: bool = False
+    package: bool = False
+    expected_visit_id: str | None = None
+    person_id: str | None = None
+    summary: str | None = None
+
+
+class Action(StrEnum):
+    IGNORE = "ignore"
+    LOG = "log"
+    NOTIFY = "notify"
+    ESCALATE = "escalate"
+
+
+class Severity(StrEnum):
+    INFO = "info"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+SEVERITY_ORDER = [Severity.INFO, Severity.LOW, Severity.MEDIUM, Severity.HIGH]
+
+
+class SuggestedAction(_Model):
+    kind: str  # e.g. call_person, message_person, view_live, mark_expected, contact_emergency
+    label: str
+    sensitive: bool = False
+    target_person_id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class Decision(_Model):
+    id: str = Field(default_factory=lambda: new_id("dec"))
+    site_id: str
+    event_id: str | None
+    visit_id: str | None = None
+    created_at: datetime = Field(default_factory=utcnow)
+    action: Action
+    severity: Severity
+    rule: str
+    reason: str
+    message: str
+    confidence: float = 0.7
+    anomaly_score: float | None = None
+    requires_confirmation: bool = False
+    suggested_actions: list[SuggestedAction] = Field(default_factory=list)
+    matched_person_id: str | None = None
+    matched_expected_visit_id: str | None = None
+    refined_by: str | None = None
+    acknowledged_at: datetime | None = None
+    acknowledged_by: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def needs_attention(self) -> bool:
+        return self.action in (Action.NOTIFY, Action.ESCALATE) and self.acknowledged_at is None

stoop/memory/store.py

@@ -0,0 +1,295 @@
+"""SQLite-backed store. Standard library only, one file per deployment, safe to vendor.
+
+All rows keep the pydantic JSON as the source of truth plus a few indexed columns for
+queries. Timestamps are stored as ISO-8601 UTC strings so lexical order == time order.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import Any
+
+from stoop.events import Event, EventKind
+from stoop.memory.models import Decision, ExpectedVisit, Person, Site, Visit, VisitStatus
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS sites (id TEXT PRIMARY KEY, json TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS events (
+  id TEXT PRIMARY KEY, site_id TEXT NOT NULL, kind TEXT NOT NULL, device_id TEXT NOT NULL,
+  occurred_at TEXT NOT NULL, dedupe_key TEXT, json TEXT NOT NULL,
+  UNIQUE(site_id, dedupe_key)
+);
+CREATE INDEX IF NOT EXISTS ix_events_site_time ON events(site_id, occurred_at);
+CREATE TABLE IF NOT EXISTS persons (id TEXT PRIMARY KEY, site_id TEXT NOT NULL, json TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS expected_visits (id TEXT PRIMARY KEY, site_id TEXT NOT NULL, json TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS visits (
+  id TEXT PRIMARY KEY, site_id TEXT NOT NULL, started_at TEXT NOT NULL, status TEXT NOT NULL, json TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_visits_site_time ON visits(site_id, started_at);
+CREATE TABLE IF NOT EXISTS decisions (
+  id TEXT PRIMARY KEY, site_id TEXT NOT NULL, event_id TEXT, created_at TEXT NOT NULL,
+  action TEXT NOT NULL, severity TEXT NOT NULL, acknowledged_at TEXT, json TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_decisions_site_time ON decisions(site_id, created_at);
+CREATE TABLE IF NOT EXISTS kv (site_id TEXT NOT NULL, key TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY(site_id, key));
+"""
+
+
+def _iso(dt: datetime) -> str:
+    return dt.astimezone(UTC).isoformat()
+
+
+class Store:
+    """Thread-safe SQLite store. Use ``":memory:"`` for tests."""
+
+    def __init__(self, path: str = ":memory:") -> None:
+        self._conn = sqlite3.connect(path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._lock = threading.RLock()
+        with self._lock:
+            self._conn.executescript(_SCHEMA)
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def _exec(self, sql: str, params: Iterable[Any] = ()) -> sqlite3.Cursor:
+        with self._lock:
+            cur = self._conn.execute(sql, tuple(params))
+            self._conn.commit()
+            return cur
+
+    def _rows(self, sql: str, params: Iterable[Any] = ()) -> list[sqlite3.Row]:
+        with self._lock:
+            return self._conn.execute(sql, tuple(params)).fetchall()
+
+    # Public escape hatches for apps that keep their own tables in the same database
+    # (accounts, token links). Same connection, same lock, same file.
+    def execute(self, sql: str, params: Iterable[Any] = ()) -> sqlite3.Cursor:
+        return self._exec(sql, params)
+
+    def query(self, sql: str, params: Iterable[Any] = ()) -> list[sqlite3.Row]:
+        return self._rows(sql, params)
+
+    # ------------------------------------------------------------------ sites
+    def put_site(self, site: Site) -> Site:
+        self._exec("INSERT OR REPLACE INTO sites(id, json) VALUES (?, ?)", (site.id, site.model_dump_json()))
+        return site
+
+    def get_site(self, site_id: str) -> Site | None:
+        rows = self._rows("SELECT json FROM sites WHERE id=?", (site_id,))
+        return Site.model_validate_json(rows[0]["json"]) if rows else None
+
+    def delete_site(self, site_id: str) -> None:
+        """Remove a site and everything recorded for it."""
+        with self._lock:
+            for table in ("events", "persons", "expected_visits", "visits", "decisions", "kv"):
+                self._conn.execute(f"DELETE FROM {table} WHERE site_id=?", (site_id,))
+            self._conn.execute("DELETE FROM sites WHERE id=?", (site_id,))
+            self._conn.commit()
+
+    def list_sites(self) -> list[Site]:
+        return [Site.model_validate_json(r["json"]) for r in self._rows("SELECT json FROM sites ORDER BY id")]
+
+    # ----------------------------------------------------------------- events
+    def put_event(self, event: Event) -> bool:
+        """Insert; returns False when the event (by id or dedupe key) already exists."""
+        with self._lock:
+            cur = self._conn.execute(
+                "INSERT OR IGNORE INTO events(id, site_id, kind, device_id, occurred_at, dedupe_key, json) VALUES (?,?,?,?,?,?,?)",
+                (
+                    event.id,
+                    event.site_id,
+                    event.kind.value,
+                    event.device_id,
+                    _iso(event.occurred_at),
+                    event.dedupe_key,
+                    event.model_dump_json(),
+                ),
+            )
+            self._conn.commit()
+            return cur.rowcount == 1
+
+    def get_event(self, event_id: str) -> Event | None:
+        rows = self._rows("SELECT json FROM events WHERE id=?", (event_id,))
+        return Event.model_validate_json(rows[0]["json"]) if rows else None
+
+    def events(
+        self,
+        site_id: str,
+        *,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        kinds: Iterable[EventKind] | None = None,
+        limit: int | None = None,
+        newest_first: bool = False,
+    ) -> list[Event]:
+        sql = "SELECT json FROM events WHERE site_id=?"
+        params: list[Any] = [site_id]
+        if since is not None:
+            sql += " AND occurred_at>=?"
+            params.append(_iso(since))
+        if until is not None:
+            sql += " AND occurred_at<=?"
+            params.append(_iso(until))
+        if kinds:
+            ks = [k.value for k in kinds]
+            sql += f" AND kind IN ({','.join('?' * len(ks))})"
+            params.extend(ks)
+        sql += " ORDER BY occurred_at " + ("DESC" if newest_first else "ASC")
+        if limit:
+            sql += " LIMIT ?"
+            params.append(limit)
+        return [Event.model_validate_json(r["json"]) for r in self._rows(sql, params)]
+
+    def last_event(self, site_id: str) -> Event | None:
+        evs = self.events(site_id, limit=1, newest_first=True)
+        return evs[0] if evs else None
+
+    # ---------------------------------------------------------------- persons
+    def put_person(self, person: Person) -> Person:
+        self._exec(
+            "INSERT OR REPLACE INTO persons(id, site_id, json) VALUES (?,?,?)",
+            (person.id, person.site_id, person.model_dump_json()),
+        )
+        return person
+
+    def get_person(self, person_id: str) -> Person | None:
+        rows = self._rows("SELECT json FROM persons WHERE id=?", (person_id,))
+        return Person.model_validate_json(rows[0]["json"]) if rows else None
+
+    def delete_person(self, person_id: str) -> None:
+        self._exec("DELETE FROM persons WHERE id=?", (person_id,))
+
+    def persons(self, site_id: str) -> list[Person]:
+        return [
+            Person.model_validate_json(r["json"]) for r in self._rows("SELECT json FROM persons WHERE site_id=? ORDER BY id", (site_id,))
+        ]
+
+    # ------------------------------------------------------- expected visits
+    def put_expected(self, ev: ExpectedVisit) -> ExpectedVisit:
+        self._exec(
+            "INSERT OR REPLACE INTO expected_visits(id, site_id, json) VALUES (?,?,?)",
+            (ev.id, ev.site_id, ev.model_dump_json()),
+        )
+        return ev
+
+    def delete_expected(self, expected_id: str) -> None:
+        self._exec("DELETE FROM expected_visits WHERE id=?", (expected_id,))
+
+    def expected(self, site_id: str) -> list[ExpectedVisit]:
+        return [
+            ExpectedVisit.model_validate_json(r["json"])
+            for r in self._rows("SELECT json FROM expected_visits WHERE site_id=? ORDER BY id", (site_id,))
+        ]
+
+    # ----------------------------------------------------------------- visits
+    def put_visit(self, visit: Visit) -> Visit:
+        self._exec(
+            "INSERT OR REPLACE INTO visits(id, site_id, started_at, status, json) VALUES (?,?,?,?,?)",
+            (visit.id, visit.site_id, _iso(visit.started_at), visit.status.value, visit.model_dump_json()),
+        )
+        return visit
+
+    def get_visit(self, visit_id: str) -> Visit | None:
+        rows = self._rows("SELECT json FROM visits WHERE id=?", (visit_id,))
+        return Visit.model_validate_json(rows[0]["json"]) if rows else None
+
+    def open_visit(self, site_id: str) -> Visit | None:
+        rows = self._rows(
+            "SELECT json FROM visits WHERE site_id=? AND status=? ORDER BY started_at DESC LIMIT 1",
+            (site_id, VisitStatus.OPEN.value),
+        )
+        return Visit.model_validate_json(rows[0]["json"]) if rows else None
+
+    def visits(self, site_id: str, *, since: datetime | None = None, limit: int = 100) -> list[Visit]:
+        sql = "SELECT json FROM visits WHERE site_id=?"
+        params: list[Any] = [site_id]
+        if since is not None:
+            sql += " AND started_at>=?"
+            params.append(_iso(since))
+        sql += " ORDER BY started_at DESC LIMIT ?"
+        params.append(limit)
+        return [Visit.model_validate_json(r["json"]) for r in self._rows(sql, params)]
+
+    # -------------------------------------------------------------- decisions
+    def put_decision(self, d: Decision) -> Decision:
+        self._exec(
+            "INSERT OR REPLACE INTO decisions(id, site_id, event_id, created_at, action, severity, acknowledged_at, json)"
+            " VALUES (?,?,?,?,?,?,?,?)",
+            (
+                d.id,
+                d.site_id,
+                d.event_id,
+                _iso(d.created_at),
+                d.action.value,
+                d.severity.value,
+                _iso(d.acknowledged_at) if d.acknowledged_at else None,
+                d.model_dump_json(),
+            ),
+        )
+        return d
+
+    def get_decision(self, decision_id: str) -> Decision | None:
+        rows = self._rows("SELECT json FROM decisions WHERE id=?", (decision_id,))
+        return Decision.model_validate_json(rows[0]["json"]) if rows else None
+
+    def decisions(
+        self,
+        site_id: str,
+        *,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        unacknowledged_only: bool = False,
+        limit: int = 100,
+    ) -> list[Decision]:
+        sql = "SELECT json FROM decisions WHERE site_id=?"
+        params: list[Any] = [site_id]
+        if since is not None:
+            sql += " AND created_at>=?"
+            params.append(_iso(since))
+        if until is not None:
+            sql += " AND created_at<=?"
+            params.append(_iso(until))
+        if unacknowledged_only:
+            sql += " AND acknowledged_at IS NULL AND action IN ('notify','escalate')"
+        sql += " ORDER BY created_at DESC LIMIT ?"
+        params.append(limit)
+        return [Decision.model_validate_json(r["json"]) for r in self._rows(sql, params)]
+
+    def acknowledge(self, decision_id: str, by: str, at: datetime | None = None) -> Decision | None:
+        d = self.get_decision(decision_id)
+        if d is None:
+            return None
+        d.acknowledged_at = at or datetime.now(tz=UTC)
+        d.acknowledged_by = by
+        return self.put_decision(d)
+
+    def decision_for_rule(
+        self, site_id: str, rule: str, *, since: datetime, until: datetime | None = None, key: str | None = None
+    ) -> Decision | None:
+        """Most recent decision with ``rule`` (and optional metadata ``key``) in [since, until]. Used to avoid repeats.
+
+        Pass ``until`` (normally the event time) so replayed or backdated events never see
+        decisions from their own future.
+        """
+        for d in self.decisions(site_id, since=since, until=until, limit=200):
+            if d.rule == rule and (key is None or d.metadata.get("key") == key):
+                return d
+        return None
+
+    # --------------------------------------------------------------------- kv
+    def set_state(self, site_id: str, key: str, value: Any) -> None:
+        self._exec("INSERT OR REPLACE INTO kv(site_id, key, json) VALUES (?,?,?)", (site_id, key, json.dumps(value)))
+
+    def get_state(self, site_id: str, key: str, default: Any = None) -> Any:
+        rows = self._rows("SELECT json FROM kv WHERE site_id=? AND key=?", (site_id, key))
+        return json.loads(rows[0]["json"]) if rows else default
+
+    def states_with_prefix(self, site_id: str, prefix: str) -> dict[str, Any]:
+        rows = self._rows("SELECT key, json FROM kv WHERE site_id=? AND key LIKE ?", (site_id, prefix + "%"))
+        return {r["key"]: json.loads(r["json"]) for r in rows}