Preparing for AI: Data Dictionary

It occurred to me that to make AI work on top of the eisy ecosystem, there really needs to be a data dictionary that is fully legible to the LLM. It needs to be able to determine what each device does, what sensor readings mean, etc. While most of us have friendly folder and device naming structures, that will not be enough for semantic systems to shine.

I spent some time with AI interrogating a full backup, and the AI could certainly parse that to create a low level dictionary. But it can't tell how the parts all relate. It needs more.

The last thing we want is to be forced to create a separate semantic overlay to provide this information, but there is a gap currently. In other words, there is no way I know of to add the needed semantic context within the existing UDI interfaces.

I asked the AI whether the low level parsing was enough, and here's what it said:

"You've hit on the most critical challenge in home automation AI integration: the Semantic Gap.

Raw backup files give the LLM syntax and structure, but not semantic meaning or intent.

While iGarDoorState hints at its purpose, the LLM won't reliably know:

1. Value Mapping (Enums): Is 0 = Closed, 1 = Open, 2 = Opening, or 3 = Fault?

2. Physical Context: Which bay of the garage does this track? Is it a tilt sensor, contact sensor, or smart door opener?

3. Behavioral Intent: Why does iKitchenStairsOffReset exist? (e.g., "Latches to prevent stair motion sensors from turning off lights while someone is cooking").

4. Cryptic Names: What do abbreviations like 1.KitchCookingKPL.H.All Off or G.GarZWkRmMotion.Tamper Alarm mean?

How to Bridge the Semantic Gap

To make your eisy system fully legible to an LLM, you need a Two-Tier Data Dictionary:

[ Tier 1: Auto-Extracted Telemetry ]         [ Tier 2: Human Semantic Overlay ]

- Variable & Node IDs - Value Enums (0=Closed, 1=Open)

- Current & Initial Values - Physical Location & Area

- Program Cross-References (If/Then) - Plain-English Purpose & Intent

\ /

v v

[ LLM-Optimized Data Dictionary (JSON/YAML) ]

_____________

It goes on to suggest the creation of a YAML/JSON overlay containing richer descriptions. And suggests a python tool that would build the file and pre-populate it for easy editing. Here is an example of the json for a couple of variables.

variables:
  integer:
    iGarDoorState:
      id: 7
      current_val: 0
      type: "integer"
      description: "Tracks the physical open/closed state of the main garage overhead door."
      values:
        0: "Closed"
        1: "Open"
        2: "Opening / In Motion"
      used_by_programs:
        - "Garage Door Opening Alert"
        - "Auto Close Garage At Night"
      associated_nodes:
        - "G.GarageMainSensorZSE70"

  state:
    sDark:
      id: 1
      current_val: 1
      type: "state"
      description: "Global environmental state flag indicating ambient darkness (between sunset and sunrise or heavy cloud cover)."
      values:
        0: "Daylight"
        1: "Dark / Night"
      triggers_automation: true 

In my view, it makes a lot more sense for UDI to build this semantic capability into the native tool.

Thoughts anyone?