AI Assistant

The AI Assistant is an admin-side conversational helper that wires GEM's data model into natural-language requests. It opens as a drawer from the admin top bar and stays scoped to the integrator/admin context — it does not control end-user devices on its own (homeowner-facing voice control is a separate, more constrained surface).

You talk to it in plain English. It picks the right tool, asks for confirmation on anything that changes state, and shows you a one-line description of what it's about to do before it runs.

Where to find it

• Click the AI icon in the admin top bar to open the drawer.
• The same assistant is also available on the Admin → Help page.
• The assistant runs against Anthropic's Claude API. The first time you open the drawer it shows AI Assistant — Setup: paste your Claude API key (it starts with sk-) into the inline field and click Save & Enable. The key is stored encrypted and the assistant turns itself on — you don't have to add it manually under System → Attributes. If a key is already on file but the assistant is switched off, the drawer instead offers Enable with Existing Key (or paste a different key to replace it). Get a key at console.anthropic.com.

Providers and per-chat model selection

The assistant can talk to more than one AI provider. Anthropic (Claude) is the default. You can also add Google Gemini (native generateContent API) and any OpenAI-compatible provider — OpenAI itself, OpenRouter, or a local/self-hosted model server. (Gemini is also available through its OpenAI-compatible endpoint as a separate preset if you prefer that path.)

• Manage providers — click the gear on the provider bar at the top of the assistant drawer. Each provider has a display name, a base URL (pre-filled for the common presets), a default model, an optional set of models to show in the chat picker, and its own API key. Keys are stored encrypted, one secure attribute per provider; leaving the key field blank when editing keeps the existing key.
• Model selection — model fields are dropdowns, not typed ids: once a provider has a key, the editor fetches the live model catalog from the provider's own models API (Anthropic, Gemini, OpenAI, OpenRouter, and local OpenAI-compatible servers all support this). Pick the default model from the list and check which models should appear in the per-chat picker. Pasting a new key loads the catalog immediately, before the first save; Reload models re-fetches. If a catalog can't be loaded (no key yet, or a local server that's offline), the fields fall back to free-text ids so nothing is blocked.
• Pick one per chat — when more than one provider is configured, the provider bar shows a provider dropdown and a model dropdown. The selection applies to the current admin chat session; each request is sent to the chosen provider and model. Start a New Chat to reset context when switching. The same picker appears in the script editor's AI sidebar — the widget code editor, the Script Console, and the driver / web-service / macro-script editors — with its own remembered selection shared across those editors.
• Scope — provider selection is available in the admin assistant chat and the script editor AI sidebar. Voice commands run on their own voice provider + voice model, set in the Voice commands section of the providers editor (typically a small, fast model) — the voice model is likewise picked from the voice provider's fetched catalog; this is independent of the per-chat picker. Blueprint analysis and other vision features run on Anthropic.
• Streaming — responses stream token-by-token on every provider (Claude, Gemini, and OpenAI-compatible alike). The tool-use loop, confirmation gate, and undo work identically across providers.

How it decides what to do

Every skill carries a plain-English description, a defined set of inputs, and — for anything that changes state — a confirmation requirement. When you ask the assistant to do something, it:

1. Picks the skill whose description matches your request.
2. Resolves IDs (zones, devices, macros, etc.) against the system's live current state, so the values it acts on are always up to date.
3. For mutations: shows a one-line preview and waits for your confirmation before writing.
4. For atomic bulk operations: pre-validates every entry, writes them, and rolls back the entire batch if any one fails.

If you're not sure what the assistant can do, just ask it: "what can you do?" — it will call its list_skills tool and return the live catalog.

Skill categories

Skills are grouped by intent. The same categories are returned by list_skills.

create — commission new entities

Skill	One-line summary
bulk_create_devices	Atomic batch device commissioning with command_set / device_type auto-resolve.
bulk_create_zones	Atomic batch zone commissioning with subsystem name/id resolve + device/site_space validation.
bulk_create_site_spaces	Atomic batch room/floor/area creation with in-batch parent_name resolution.
bulk_create_site_modes	Atomic batch site mode creation (Home / Away / Vacation / Party / Sleep / …) — each with enter/exit actions (macro references or inline subsystem commands), at most one default across the batch, auto-assigned sort order, and rollback.
bulk_create_triggers	Atomic batch attribute_trigger creation with template + targets fan-out.
bulk_create_schedules	Atomic batch macro_schedule creation with natural-language at/days → cron.
bulk_create_channels	Atomic batch channel-lineup commissioning under one provider.
bulk_create_av_sources	Atomic batch add of av_sources to an existing av_zone.
bulk_create_av_zones	Atomic batch creation of many distinct av_zones, each with its own backing zone + per-zone sources.
bulk_create_commands	Atomic batch add of outbound command rows (name + template + args + arg_options) to an existing command_set, with skip/replace-on-collision and rollback.
bulk_create_widgets	Atomic batch add of ui_page_widget rows to a ui_page.
bulk_create_ui_pages	Atomic batch ui_page creation with optional pre-seeded widgets and multi-UI linking.
create_camera_wall	One-call camera dashboard — resolves camera zones (explicit ids, name substrings, or a pattern like "every zone containing camera"), creates or reuses a ui_page, places a single camera-grid widget covering all of them, and optionally links the page to one or more UIs. Atomic with rollback; capped at 40 cameras per wall.
bulk_create_ui_zone_groups	Atomic batch creation of per-subsystem UI zone-group cards — each grouping several zones into one collapsible card, optionally linked to multiple UIs and reassigning existing ui_zone rows into the group. Resolves subsystems / UIs / member zones by name or id, rejects cross-subsystem members, reloads each affected UI, and rolls back every group + link + reassignment on any failure. (Groups already-visible zones — run bulk_assign_zones_to_ui first if a zone isn't on the UI yet.)
bulk_create_macros	Atomic batch macro creation (each with optional steps) for scene-per-room rollouts.
bulk_create_monitors	Atomic batch ping/HTTP/TCP monitor commissioning with device-ip auto-resolve and in-batch depends_on chains.
bulk_create_monitor_tags	Atomic batch creation of many monitor tag rollup groups — each with a health rule (anchor / all / threshold), member monitors, and upstream dependency edges — with a shared defaults block, in-batch dependency resolution + topological ordering, cycle rejection, and rollback. Wired through the live monitor cache so rollups arm immediately (no reload).
bulk_create_variables	Atomic batch automation-variable commissioning (weather / sun_moon / usgs / google_calendar / date_and_time), with driver validation, per-driver prefix-collision checks, and interval resolution — starts each variable's timer on success.
bulk_create_users	Atomic batch auth_user creation — each entry with its own roles + profile + sites + credentials, a shared defaults block, in-batch PIN/username collision checks, and full rollback.
create_av_zone_with_sources	Atomic AV zone + sources + placeholder macros.
create_scene	Author a multi-zone scene macro from per-zone intent (off / on / level / color_temp), auto-emitting the right command steps.
snapshot_scene	Capture the current live state of a set of zones into a new scene macro — "save the room the way it is right now". Scoped by zone ids/names, a subsystem (e.g. all lights), or a room keyword; reads each zone's live level / color temp / shade position / lock / arm state and hands the result to create_scene (same validation + rollback). Off/closed zones are captured by default so recall reproduces the exact look (skip_off captures only what's on); climate setpoints and AV are not captured and are reported as skipped.
bulk_create_scenes	Atomic batch counterpart to create_scene — many scene macros in one call (e.g. the standard Movie / Dinner / Goodnight suite, or bright/dim/off per room), each fanning command steps to its zones, with shared defaults, full pre-validation, and rollback.
create_climate_schedule	One-call thermostat setback schedule ("70 at 7am, 62 when we leave, 70 at 5pm, 64 at 10pm") — for each time-of-day period it builds a setpoint macro (one setpoint step per thermostat, single or heat/cool dual setpoints) plus the macro_schedule that fires it, all cross-linked, pre-validated (setpoint safe range, time/day parsing, name collisions), and rolled back as a whole batch on any failure.
create_macro_with_steps	Atomic macro + steps with metadata-validated drivers.
create_macro	Create one empty macro.
create_trigger	Create one attribute_trigger.
create_schedule	Create one macro_schedule.
create_access_rule	Create a physical access_control rule (reader + users + action).
bulk_create_access_rules	Atomic batch access_control rule creation with a shared defaults block, natural-language day/hour parsing, and full rollback.
bulk_create_holiday_calendars	Atomic batch holiday_calendar creation — each with its own dates (single YYYY-MM-DD days and from/to ranges), full date validation, name-collision checks, and rollback.
bulk_create_schedule_exceptions	Atomic batch schedule exception creation — each window (dates, optional times, yearly recurrence) wired to its affected macro_schedules with a per-link action (skip / substitute / only_during), a shared defaults.schedules list for "same skip list on every holiday" sets, full date/link validation, and rollback of both exceptions and links. The scheduler picks new exceptions up on the next fire — no reload.
bulk_create_alarms	Atomic batch alarm definition creation — condition + severity + deadband/delays + notify/escalation steps, with a shared defaults block, full pre-validation, rollback, and a single engine reload so new alarms arm immediately.
create_notification_profile	Create notification_profile + bulk-assign auth_users.
bulk_create_notification_profiles	Atomic batch creation of many different notification_profiles — each with its own delivery methods / day-hour mask / user assignments, a shared defaults block, in-batch and against-DB name-collision checks, and full rollback.
create_user_with_roles	Atomic auth_user + roles + profile + sites + credentials.
create_ui_room	Create a UI for a room with auto-discovered controls.
configure_device	Configure an existing device's network/auth attributes.
add_device_from_discovery	Add a single device discovered via network scan.
discover_network	Scan the local network for new devices.

wire — link existing entities together

Skill	One-line summary
bulk_assign_zones_to_ui	Wire many zones to a manual UI (ui_zone rows).
bulk_assign_macros_to_ui	Wire many macros as scene-buttons on a manual UI (ui_macro rows).
bulk_assign_pages_to_ui	Link many existing ui_pages to a UI (ui_page_ui rows).
link_zones_to_site_spaces	Auto-suggest or apply zone → site_space linkage based on name/label matching.
remap_av_zone_devices	Rebind av_source.device_id across one or many av_zones.

clone — deep-copy existing entities

Skill	One-line summary
clone_ui	Deep-copy a UI with all its zones, controls, macros, and page links.
clone_ui_page	Deep-copy a single ui_page (and its widgets) with optional re-linking.
clone_widget	Deep-copy a single dashboard widget (its config intact) to one or many new names, with per-clone config overrides and optional copying of its page placements.
clone_macro	Clone a macro to one or many new names.
clone_trigger	Clone a trigger to one name OR fan out across many targets.
clone_schedule	Clone a schedule to one or many new names.
clone_av_zone	Deep-copy an av_zone with all sources (and optionally their macros).
clone_channel_provider	Deep-copy a channel provider with every child channel row (number + name + call sign + logo + enabled/favorite flags + sort order) to one or many new providers — fast-path for fanning a hand-built lineup across identical hardware (two Rokus with the same apps, three cable boxes with the same channels). The external listings ID is not copied by default, so clones start as manual lineups.
clone_command_set	Deep-copy a command_set with every child command row (name + template + args + arg_options + description + system flag) to one or many new sets — fast-path for commissioning a vendor whose protocol resembles an existing one.
clone_zone	Deep-copy a plain zone with every attribute row (and optionally its ui_zone links) to one or many new zones, with per-clone device/address overrides.
clone_device	Deep-copy a device with every attribute row (and optionally its child zones) to one or many new devices, with per-clone ip/port/credential overrides — secure attributes are skipped by default so credentials aren't silently fanned across clones.
clone_alarm	Deep-copy an alarm definition — conditions, notify/escalation ladder, actions, deadband/delays/latching/repeat/cooldown — to one or many new names, or "stamp" it across many similar targets with the condition's target rewritten per clone.
clone_user	Clone an auth_user (roles + sites + notification profile + flags) to one or many new accounts — credentials are never copied.
clone_role	Clone an auth_role (its full rules array + the is_elevated / allow_remote / enabled flags) to one or many new roles, with optional per-clone rule patches (append / remove rules) or wholesale rule replacement.
clone_notification_profile	Clone a notification_profile (delivery methods + day/hour masks) to one or many, optionally copying user assignments.
clone_monitor	Deep-copy a network monitor — header, check interval, dependency chain, and full config JSON (notification lists, retries, timeouts, type settings) — to one or many new names, or "stamp" it across many IP targets with the ip rewritten per clone. Clones start probing immediately.
clone_access_rule	Clone an access_control rule (reader + users + days/hours + action) to one or many — name-only, or "stamp" the same rule across many readers and/or many users in one atomic call.
clone_site_mode	Deep-copy a site mode — label, description, and both enter/exit action lists — to one or many new modes, with per-clone overrides that replace or append actions. The default flag is never copied, so the existing default mode stays intact.
clone_site_space	Deep-copy a site space subtree — a floor/wing plus every room nested under it — to one or many new spaces ("duplicate floor 2 as floor 3"). Each descendant gets a derived unique name (labels copy verbatim, so the tree still reads Floor 3 → Bedroom 1), and each node's attributes and blueprint floor-plan art come along. Zones are never copied — they're physical hardware; reassign them afterward with link_zones_to_site_spaces. Refuses to clone the root space, and rolls back every row + attribute on any failure.
clone_ui_zone_group	Clone a UI zone-group card (with its UI links) to one or many new groups — the fan-out counterpart to bulk_create_ui_zone_groups. Member zones either move to the clone (single-clone default, source ends up empty), stay on the source with clones starting empty (copy, multi-clone default), or a chosen subset moves. Per-clone label / sort / UI-link overrides; cross-subsystem clones refuse to move members; reloads each affected UI and rolls back every group + link + reassignment on any failure.

edit — modify existing rows

Skill	One-line summary
update_model	Update fields on one row in any table.
update_macro_steps	Atomic add / update / remove / renumber for steps in an existing macro.
add_macro_step	Add a single step to an existing macro.
insert_model	Insert one row into any table.
batch_insert	Insert multiple rows into one table in a single transaction.
set_attribute	Set one attribute value.
build_widget	Create or update a ui_widget definition (with code).
compose_widget	Create or update a designer (composed) widget from a validated element tree — no code; the result stays visually editable on the UI Widgets page.

bulk_edit — same change to many rows

Skill	One-line summary
bulk_set_attribute	Set the same attribute on many targets (with dry_run + rollback).
bulk_toggle_enabled	Flip the enabled flag on many rows (with dry_run + rollback).
bulk_rename	Find/replace the name and/or label columns across many rows (with dry_run + rollback).

run — execute or undo

Skill	One-line summary
run_macro	Run a macro on demand.
send_command	Dispatch a single command to a device or zone.
undo_last_action	Revert the last update_model or set_attribute change.
reload	Reload a single entity from the database into memory.

discover — read-only lookups

Skill	One-line summary
list_skills	Return this catalog grouped by category.
query_database	Generic read-only lookup against any table (filters plus % wildcards).
describe_attributes	List attributes on an entity, enriched with registry metadata.
describe_macro_step	Get the data-payload schema for a macro step driver.
get_attributes	Get current attribute values for an entity.
get_zone_states	Read live state attributes for one or many zones.
get_alarms	Read the alarm center's open events and recent history — severity, acknowledge/shelve state, and the per-recipient notification delivery log.
alarm_context	Deep-dive on ONE alarm event for a causal brief — the rule that fired and its tripping value, the source entity's live state, the attribute timeline around activation, 30-day recurrence, and correlated alarms / automation runs / user actions in the same window. Behind the Explain with AI button on each alarm row.
diagnose	Full configuration audit — the same 28-check battery as the Diagnostics page (orphans, duplicates, empty/unused, config smells, naming, connectivity, security, integrity, performance), filterable by category/severity.
navigate	Open an admin page or entity in the UI.
search_docs	Search the GEM documentation.
recall_memory_notes	Search persistent per-site memory notes captured in prior sessions.

notes — capture knowledge

Skill	One-line summary
record_attribute_note	Attach a note to a specific attribute.
update_registry_description	Update the canonical description in the attribute registry.
record_memory_note	Save site-specific knowledge that future sessions should know.

automate — multi-artifact one-shots

Skill	One-line summary
create_motion_automation	Wire one motion sensor to N target zones with on/off macros and triggers in one call.

create_scene (build one scene macro that fans out command steps to many zones at known levels / colors) is a closely related one-shot, but list_skills files it under create — you'll find it in that table above.

Workflow patterns

A few recurring shapes the assistant uses well:

Commission then wire. Use bulk_create_zones (or device commissioning) to bring rows into existence, then link_zones_to_site_spaces to bin them into rooms, then bulk_assign_zones_to_ui (manual UIs) — or skip the last step entirely if the install uses space-driven UIs (the 90/10 default).

Suggest then apply. Several skills support a discover/commit split: link_zones_to_site_spaces returns ranked suggestions when called with no mapping, then is called again with the user-confirmed mapping to write. bulk_set_attribute and bulk_toggle_enabled accept dry_run: true for the same purpose. Prefer this two-call shape whenever scope might be broader than expected.

Atomic with rollback. Every bulk_* and clone_* skill validates the whole batch first and rolls back every partial write if any one step fails. This means it's safe to rerun after a failure once you've fixed the offending entry — the state is exactly as it was before the failed call.

Stored data is a public API. The assistant never silently migrates DB rows on a write path. If a stored macro / trigger / attribute predates a feature, the new code paths default to the old behavior; the new shape is opt-in.

Confirmation gate

Skills that write to the system trigger a one-line confirmation prompt in the drawer before they execute — anything in create, wire, clone, edit, bulk_edit, notes, or automate, plus run_macro. The prompt shows the resolved description (e.g. "Wire 12 zones to UI 'security_panel'") — not the raw call — so you can sanity-check intent at a glance. Read-only lookups (the discover group) run without prompting.

Click Allow to run the action or Deny to cancel it. Deny means stop — the assistant cancels that action and ends the turn rather than retrying a different way, so it won't re-prompt you in a loop. Just type your next instruction to continue.

A few skills run without a prompt even though they appear in a write-oriented group, so keep an eye on them:

• In create: discover_network (a read-only network scan that changes nothing) and add_device_from_discovery (which commits the chosen device immediately).
• In run: only run_macro prompts — send_command (dispatch a command to a device/zone), reload, and undo_last_action execute right away.

Keeping this page current

This page is a written snapshot. The assistant builds its real catalog at runtime from the skills actually installed on your system, and the list_skills skill enumerates that live set and sorts it into the same categories shown here. So the assistant's own answer to "what can you do?" is always accurate for your version — even when this page lags a release or two behind. When in doubt, ask the assistant directly.