description
Scheduled full-frame Vision-Language-Model check — the catch-all rule for requirements that need scene UNDERSTANDING rather than object detection. On a Mon-Fri schedule (one-shot at fixed times + periodic every N seconds within a time window, in the camera's timezone) it emits a full-frame snapshot event; the downstream VLM service answers a configured natural-language question about the scene (e.g. "is the room tidy?", "are curtains closed during nap time?", "is the gate locked?"). No detector, no tracker, no model from the zoo — pure schedule. The cl01/cl02/cl03 codes are the same module with different questions/schedules per deployment. This is usually the fastest way to cover a new requirement BEFORE investing in a dedicated rule or model: write a question + schedule instead of code.
use cases
- periodic housekeeping / tidiness / setup checks (room state, equipment presence)
- open-ended compliance questions a detector cannot answer (signage, door/gate state, lighting)
- fast prototyping of a new requirement as a VLM question before building a dedicated rule
- end-of-day / start-of-day site condition snapshots
limitations
- schedule-driven, not event-driven — it cannot react to a live incident between ticks
- answer quality depends on the VLM and question phrasing; needs the celia-vlm-serving service
- no per-object localization or tracking — scene-level verdicts only
config parameters
general
| Parameter | Type | Default | Notes |
|---|---|---|---|
| timezone | string | "utc-5" | utc | utc-5 | utc+7 |
| schedule * | array of any | — |
advanced
| Parameter | Type | Default | Notes |
|---|---|---|---|
| camera_fps | integer | 10 | |
| cam_resolution | array of integer | — | (min items 2, max items 2) |
golden replay cases
| Case | Frames | Expected events |
|---|---|---|
| schedule | 6 | 3 |
readme
vlm_periodic
Fire a full-frame VLM-check event on a Mon–Fri schedule (one-shot times + periodic windows), per the camera's timezone. No object detection or tracking.
A self-describing rule module built on celia-rule-sdk. It implements the FrameRule contract
(kind: frame): the rule worker computes a deterministic video clock and calls check_frame(...)
directly — no detections, no tracker. When a timestamp is due it emits one full-frame candidate
(class_name="vlm_check_frame", whole frame as the bbox); the actual VLM verification happens
downstream in the evidence service. One module class serves four rule codes
(vlm_periodic, cl01, cl02, cl03), differentiated only by config. Replaces the karterschool
CL01–03 controllers.
How it plugs in
Registered as four celia.rules entry points (one per rule code) pointing at one VlmPeriodicModule;
the entry-point name becomes the rule code. A rule worker drives it like any other rule, but because
it's a FrameRule the SDK skips detections/tracking and feeds it the frame's video timestamp, against
which the SDK Scheduler fires deterministically.
Configuration
module.yaml: rule_codes: [vlm_periodic, cl01, cl02, cl03], kind: frame, domain: karterschool,
requires.models: [], tracking: none.
Config (config.schema.json):
schedule(required) — a list of entries, each either{type: one_shot, time: "HH:MM", end_time?: "HH:MM"}or{type: periodic, start_time: "HH:MM", end_time: "HH:MM", interval_seconds: N}.timezone—utc|utc-5|utc+7(defaultutc-5).camera_fps(default 10, drives the video clock) andcam_resolution— advanced.
Schedule is Mon–Fri only and resets daily; firing is deterministic on the video clock.
Testing
pytest modules/rules/vlm_periodic # 5 offline tests (scheduler units + frame-dispatch + alias rule code)