Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Turns Home Assistant's four flat registries (floors, areas, devices,
* entities) plus the current state map into the room graph the 3D scene
* renders and the agent reasons over.
*
* Everything here is a pure function of data the bridge already fetched, so the
* scene can rebuild on every state push without another round trip.
*/
/** Domains the 3D scene draws as something you can see or walk up to. */
const RENDERABLE_DOMAINS = new Set([
'light',
'switch',
'cover',
'lock',
'climate',
'media_player',
'fan',
'sensor',
'binary_sensor',
'camera',
'vacuum',
'alarm_control_panel',
]);
export function domainOf(entityId) {
const i = String(entityId || '').indexOf('.');
return i === -1 ? '' : entityId.slice(0, i);
}
/**
* @param {object} input
* @param {Array} input.floors config/floor_registry/list
* @param {Array} input.areas config/area_registry/list
* @param {Array} input.devices config/device_registry/list
* @param {Array} input.entities config/entity_registry/list
* @param {Record<string, object>} input.states entity_id to state object
*/
export function buildHomeGraph({ floors = [], areas = [], devices = [], entities = [], states = {}, temperatureUnit = null } = {}) {
const deviceArea = new Map(devices.map((d) => [d.id, d.area_id || null]));
const rooms = new Map(
areas.map((a) => [
a.area_id,
{
id: a.area_id,
name: a.name,
icon: a.icon || null,
floorId: a.floor_id || null,
aliases: a.aliases || [],
entities: [],
},
]),
);
const unassigned = [];
const seen = new Set();
for (const entry of entities) {
if (entry.disabled_by || entry.hidden_by) continue;
const entityId = entry.entity_id;
seen.add(entityId);
const areaId = entry.area_id || deviceArea.get(entry.device_id) || null;
const item = describeEntity(entityId, entry, states[entityId], areaId);
if (!item) continue;
const room = areaId && rooms.get(areaId);
if (room) {
item.areaName = room.name;
room.entities.push(item);
} else {
unassigned.push(item);
}
}
// Entities created in YAML never reach the entity registry, and the demo and
// template integrations are full of them. Dropping them would silently hide
// half of some houses, so pick them up from the state map directly.
for (const [entityId, state] of Object.entries(states)) {
if (seen.has(entityId)) continue;
const item = describeEntity(entityId, null, state, null);
if (item) unassigned.push(item);
}
const list = [...rooms.values()].map((room) => ({
...room,
entities: room.entities.sort(byName),
lighting: summarizeLighting(room.entities),
climate: summarizeClimate(room.entities, temperatureUnit),
secured: summarizeSecurity(room.entities),
}));
return {
floors: floors.map((f) => ({ id: f.floor_id, name: f.name, level: f.level ?? 0, icon: f.icon || null })).sort((a, b) => a.level - b.level),
rooms: list.sort(byName),
unassigned: unassigned.sort(byName),
// Carried on the graph rather than read at render time: the scene, the 2D
// fallback and the agent's answers all have to say the same unit, and this
// is the one object all three of them already read.
temperatureUnit,
};
}
function describeEntity(entityId, registryEntry, state, areaId) {
const domain = domainOf(entityId);
if (!RENDERABLE_DOMAINS.has(domain)) return null;
const attributes = state?.attributes || {};
return {
entityId,
domain,
areaId: areaId || null,
name: registryEntry?.name || attributes.friendly_name || registryEntry?.original_name || entityId,
deviceClass: attributes.device_class || registryEntry?.device_class || registryEntry?.original_device_class || null,
state: state?.state ?? 'unavailable',
attributes,
};
}
function byName(a, b) {
return String(a.name).localeCompare(String(b.name));
}
/**
* The numbers the 3D scene needs to light a room the way the real room is lit:
* how many lights are on, the mean brightness as 0..1, and the mean colour of
* the lights that report one.
*/
export function summarizeLighting(entities) {
const lights = entities.filter((e) => e.domain === 'light');
const on = lights.filter((e) => e.state === 'on');
let brightness = 0;
const rgb = [0, 0, 0];
let coloured = 0;
for (const light of on) {
brightness += (Number(light.attributes.brightness) || 255) / 255;
const c = light.attributes.rgb_color;
if (Array.isArray(c) && c.length === 3) {
rgb[0] += c[0];
rgb[1] += c[1];
rgb[2] += c[2];
coloured += 1;
}
}
return {
total: lights.length,
on: on.length,
brightness: on.length ? Number((brightness / on.length).toFixed(3)) : 0,
rgb: coloured ? rgb.map((v) => Math.round(v / coloured)) : null,
};
}
const CELSIUS = '\u00b0C';
const FAHRENHEIT = '\u00b0F';
/**
* Convert one reading between the two units Home Assistant measures temperature
* in. An unknown pair is returned untouched rather than mangled: a wrong number
* is worse than an unconverted one, because it looks right.
*/
function convertTemperature(value, from, to) {
if (!Number.isFinite(value) || !from || !to || from === to) return value;
if (from === CELSIUS && to === FAHRENHEIT) return (value * 9) / 5 + 32;
if (from === FAHRENHEIT && to === CELSIUS) return ((value - 32) * 5) / 9;
return value;
}
/**
* The room's temperature, in the unit the house displays.
*
* A house is not all one unit. Switching an instance to US customary does not
* rewrite a sensor that declares its own `unit_of_measurement`, so a real house
* can hold a Celsius sensor and a Fahrenheit thermostat at once, and averaging
* their raw numbers produces a reading that belongs to neither. Every reading
* is converted to `unit` first, using the unit that reading itself declares: a
* sensor states it outright, and a climate entity is already normalised to the
* instance's own unit, which is what `unit` is.
*/
export function summarizeClimate(entities, unit = null) {
const readings = [];
for (const entity of entities) {
const isClimate = entity.domain === 'climate';
if (!isClimate && !(entity.domain === 'sensor' && entity.deviceClass === 'temperature')) continue;
const attributes = entity.attributes || {};
const raw = isClimate ? Number(attributes.current_temperature) : Number(entity.state);
if (!Number.isFinite(raw)) continue;
const own = (isClimate ? attributes.temperature_unit : attributes.unit_of_measurement) || unit;
readings.push(convertTemperature(raw, own, unit || own));
}
if (!readings.length) return null;
const mean = readings.reduce((a, b) => a + b, 0) / readings.length;
return { temperature: Number(mean.toFixed(1)), sources: readings.length, unit: unit || null };
}
/**
* "Is this room buttoned up?" in one object, so the scene can tint a door red
* and the agent can answer "did I lock everything" without a second pass.
*/
export function summarizeSecurity(entities) {
const locks = entities.filter((e) => e.domain === 'lock');
const openings = entities.filter(
(e) => e.domain === 'cover' || (e.domain === 'binary_sensor' && (e.deviceClass === 'door' || e.deviceClass === 'window' || e.deviceClass === 'garage_door')),
);
const unlocked = locks.filter((e) => e.state === 'unlocked').map((e) => e.entityId);
const open = openings.filter((e) => e.state === 'open' || e.state === 'on').map((e) => e.entityId);
if (!locks.length && !openings.length) return null;
return { locks: locks.length, unlocked, openings: openings.length, open, secure: unlocked.length === 0 && open.length === 0 };
}
/** Every renderable entity in the house as one flat list, area id included. */
export function flattenEntities(graph) {
const out = [];
for (const room of graph?.rooms || []) out.push(...room.entities);
out.push(...(graph?.unassigned || []));
return out;
}