node-red-contrib-knx-ultimate 7.1.0-beta.2 → 7.1.2

package/nodes/utils/knxAiCamera.js

@@ -0,0 +1,302 @@
+const KNX_AI_CAMERA_REGISTRY_KEY = Symbol.for('node-red.knx-ai.camera-adapters.v1')
+const KNX_AI_CAMERA_IMAGE_MAX_BYTES = 6 * 1024 * 1024
+const KNX_AI_CAMERA_MAX_ACTIONS = 8
+
+const clampText = (value, maxChars = 240) => String(value === undefined || value === null ? '' : value)
+  .trim()
+  .slice(0, Math.max(0, Number(maxChars) || 0))
+
+const normalizeSearchText = value => clampText(value, 300)
+  .normalize('NFKD')
+  .replace(/[\u0300-\u036f]/g, '')
+  .toLocaleLowerCase()
+  .replace(/[^a-z0-9]+/g, ' ')
+  .trim()
+
+const uniqueTexts = values => Array.from(new Set((Array.isArray(values) ? values : [])
+  .map(value => clampText(value, 240))
+  .filter(Boolean)))
+
+// Runtime contract for optional camera suites. A package registers one adapter
+// manifest and one provider per configured controller. Providers expose:
+//   listCameras({ force }) -> camera[]
+//   takeSnapshot({ cameraId, cameraName, highQuality }) -> { data, mediaType, camera }
+//   subscribe(listener) -> unsubscribe(), with normalized camera event objects.
+// The global Symbol lets separately installed Node-RED packages share the same
+// in-process registry without either package importing the other one.
+const getKnxAiCameraAdapterRegistry = () => {
+  const existing = globalThis[KNX_AI_CAMERA_REGISTRY_KEY]
+  if (existing && existing.version === 1 && existing.adapters instanceof Map && existing.providers instanceof Map) return existing
+  const registry = {
+    version: 1,
+    adapters: new Map(),
+    providers: new Map(),
+    listeners: new Set(),
+    registerAdapter (adapter) {
+      if (!adapter || !adapter.id) return
+      this.adapters.set(String(adapter.id), Object.freeze(Object.assign({}, adapter)))
+      this.listeners.forEach(listener => {
+        try { listener({ type: 'adapter_registered', adapter: this.adapters.get(String(adapter.id)) }) } catch (error) { /* ignore */ }
+      })
+    },
+    registerProvider (provider) {
+      if (!provider || !provider.id) return
+      this.providers.set(String(provider.id), provider)
+      this.listeners.forEach(listener => {
+        try { listener({ type: 'provider_registered', provider }) } catch (error) { /* ignore */ }
+      })
+    },
+    unregisterProvider (providerId) {
+      const id = String(providerId || '')
+      const provider = this.providers.get(id)
+      if (!provider) return
+      this.providers.delete(id)
+      this.listeners.forEach(listener => {
+        try { listener({ type: 'provider_unregistered', provider }) } catch (error) { /* ignore */ }
+      })
+    },
+    subscribe (listener) {
+      if (typeof listener !== 'function') return () => {}
+      this.listeners.add(listener)
+      return () => this.listeners.delete(listener)
+    }
+  }
+  globalThis[KNX_AI_CAMERA_REGISTRY_KEY] = registry
+  return registry
+}
+
+const normalizeKnxAiCameraRegistration = (value = {}) => {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+  const id = clampText(source.cameraId || source.id, 160)
+  const name = clampText(source.cameraName || source.name || id, 240)
+  const state = clampText(source.state, 80).toUpperCase()
+  const online = typeof source.online === 'boolean'
+    ? source.online
+    : state
+      ? ['CONNECTED', 'ONLINE'].includes(state)
+      : null
+  if (!id && !name) return null
+  return {
+    id,
+    name,
+    aliases: uniqueTexts([name, id].concat(Array.isArray(source.aliases) ? source.aliases : [])),
+    source: clampText(source.source || 'camera-adapter', 80),
+    adapterId: clampText(source.adapterId, 120),
+    adapterTitle: clampText(source.adapterTitle, 240),
+    providerId: clampText(source.providerId, 200),
+    controllerId: clampText(source.controllerId, 160),
+    controllerName: clampText(source.controllerName, 240),
+    nativeCameraId: clampText(source.nativeCameraId, 160),
+    state,
+    online,
+    objectTypes: uniqueTexts(source.objectTypes).map(normalizeCameraObjectType).filter(Boolean).slice(0, 24),
+    lines: (Array.isArray(source.lines) ? source.lines : []).slice(0, 80),
+    zones: (Array.isArray(source.zones) ? source.zones : []).slice(0, 80),
+    lastSeenAt: clampText(source.lastSeenAt || new Date().toISOString(), 64)
+  }
+}
+
+const resolveKnxAiCamera = ({ target, cameras } = {}) => {
+  const requested = normalizeSearchText(target)
+  const list = (Array.isArray(cameras) ? cameras : [])
+    .map(normalizeKnxAiCameraRegistration)
+    .filter(Boolean)
+  if (!requested) return { camera: null, ambiguous: false }
+
+  const exact = list.filter(camera => [camera.id, camera.name].concat(camera.aliases)
+    .some(alias => normalizeSearchText(alias) === requested))
+  if (exact.length === 1) return { camera: exact[0], ambiguous: false }
+  if (exact.length > 1) return { camera: null, ambiguous: true }
+
+  const partial = list.filter(camera => [camera.id, camera.name].concat(camera.aliases)
+    .some(alias => {
+      const normalizedAlias = normalizeSearchText(alias)
+      return normalizedAlias && (normalizedAlias.includes(requested) || requested.includes(normalizedAlias))
+    }))
+  if (partial.length === 1) return { camera: partial[0], ambiguous: false }
+  return { camera: null, ambiguous: partial.length > 1 }
+}
+
+const normalizeCameraEventType = value => {
+  const raw = normalizeSearchText(value).replace(/\s+/g, '')
+  if (['smartdetect', 'objectdetect', 'objectdetection', 'smartdetection'].includes(raw)) return 'smartDetect'
+  if (['smartdetectline', 'line', 'linecrossing', 'crossline'].includes(raw)) return 'smartDetectLine'
+  if (['smartdetectzone', 'zone', 'intrusionzone', 'intrusion'].includes(raw)) return 'smartDetectZone'
+  if (['smartdetectloiterzone', 'loiter', 'loiterzone'].includes(raw)) return 'smartDetectLoiterZone'
+  if (['motion', 'movement'].includes(raw)) return 'motion'
+  if (['ring', 'doorbell'].includes(raw)) return 'ring'
+  if (['smartaudiodetect', 'audio'].includes(raw)) return 'smartAudioDetect'
+  return clampText(value, 80)
+}
+
+const normalizeCameraObjectType = value => {
+  const raw = normalizeSearchText(value).replace(/\s+/g, '')
+  if (['person', 'people', 'persona', 'persone', 'human', 'someone', 'qualcuno'].includes(raw)) return 'person'
+  if (['animal', 'animale', 'animali', 'pet', 'pets', 'dog', 'cat', 'cane', 'gatto'].includes(raw)) return 'animal'
+  if (['vehicle', 'vehicles', 'veicolo', 'veicoli', 'car', 'auto', 'automobile'].includes(raw)) return 'vehicle'
+  if (['face', 'volto', 'faccia'].includes(raw)) return 'face'
+  if (['licenseplate', 'numberplate', 'targa'].includes(raw)) return 'licenseplate'
+  if (['package', 'parcel', 'pacco'].includes(raw)) return 'package'
+  return normalizeSearchText(value).replace(/\s+/g, '')
+}
+
+const normalizeCameraActionType = value => {
+  const raw = normalizeSearchText(value).replace(/\s+/g, '_')
+  if (['snapshot', 'get_snapshot', 'send_snapshot', 'camera_snapshot'].includes(raw)) return 'snapshot'
+  if (['analyze', 'analyse', 'analyze_snapshot', 'describe_snapshot', 'vision'].includes(raw)) return 'analyze'
+  if (['watch', 'subscribe', 'notify', 'create_watch'].includes(raw)) return 'watch'
+  if (['unwatch', 'unsubscribe', 'stop', 'remove_watch', 'delete_watch'].includes(raw)) return 'unwatch'
+  if (['list', 'list_watches', 'show_watches'].includes(raw)) return 'list_watches'
+  return ''
+}
+
+const normalizeKnxAiCameraAction = (value, cameras = []) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const type = normalizeCameraActionType(value.type || value.action || value.operation)
+  if (!type) return null
+  const target = clampText(value.cameraId || value.cameraName || value.camera || value.target, 240)
+  const resolved = resolveKnxAiCamera({ target, cameras })
+  const camera = resolved.camera
+  let eventType = normalizeCameraEventType(value.eventType || value.event)
+  const requestedScope = clampText(value.scopeId || value.scopeName || value.zoneId || value.lineId || value.zone || value.line, 240)
+  const availableScopes = camera
+    ? eventType === 'smartDetectLine'
+      ? camera.lines
+      : ['smartDetectZone', 'smartDetectLoiterZone'].includes(eventType)
+          ? camera.zones
+          : []
+    : []
+  const normalizedScopeTarget = normalizeSearchText(requestedScope)
+  const matchingScopes = normalizedScopeTarget
+    ? (Array.isArray(availableScopes) ? availableScopes : []).filter(scope => [scope && scope.id, scope && scope.name]
+        .some(candidate => normalizeSearchText(candidate) === normalizedScopeTarget))
+    : []
+  const resolvedScope = matchingScopes.length === 1 ? matchingScopes[0] : null
+  const objectTypes = uniqueTexts(Array.isArray(value.objectTypes)
+    ? value.objectTypes
+    : [value.objectType || value.smartDetectType]).map(normalizeCameraObjectType).filter(Boolean).slice(0, 12)
+  // A plain motion event has no classified object metadata. Convert requests
+  // such as "motion caused by a person/animal" to the generic smart-detection
+  // family so they can match Protect zone, line, or loiter detections.
+  if (type === 'watch' && eventType === 'motion' && objectTypes.length > 0) eventType = 'smartDetect'
+  return {
+    type,
+    cameraId: camera ? camera.id : clampText(value.cameraId, 160),
+    cameraName: camera ? camera.name : clampText(value.cameraName || value.camera || value.target, 240),
+    unresolvedTarget: camera ? '' : target,
+    unresolved: Boolean(target && !camera),
+    ambiguous: resolved.ambiguous,
+    eventType,
+    scopeId: resolvedScope ? clampText(resolvedScope.id, 160) : clampText(value.scopeId || value.zoneId || value.lineId, 160),
+    scopeName: resolvedScope ? clampText(resolvedScope.name || resolvedScope.id, 240) : clampText(value.scopeName || value.zone || value.line, 240),
+    unresolvedScope: Boolean(requestedScope && camera && !resolvedScope),
+    ambiguousScope: matchingScopes.length > 1,
+    objectTypes,
+    cooldownSeconds: Math.max(10, Math.min(86400, Number(value.cooldownSeconds) || 60)),
+    sendSnapshot: value.sendSnapshot !== false,
+    reason: clampText(value.reason, 500)
+  }
+}
+
+const normalizeKnxAiCameraActions = ({ actions, cameras } = {}) => (Array.isArray(actions) ? actions : [])
+  .slice(0, KNX_AI_CAMERA_MAX_ACTIONS)
+  .map(action => normalizeKnxAiCameraAction(action, cameras))
+  .filter(Boolean)
+
+const normalizeKnxAiCameraEvent = value => {
+  const meta = value && typeof value === 'object' && !Array.isArray(value) && value.eventType
+    ? value
+    : null
+  if (!meta) return null
+  return {
+    cameraId: clampText(meta.cameraId, 160),
+    cameraName: clampText(meta.cameraName, 240),
+    eventType: normalizeCameraEventType(meta.eventType),
+    scopeId: clampText(meta.scopeId, 160),
+    scopeName: clampText(meta.scopeName, 240),
+    objectTypes: uniqueTexts(Array.isArray(meta.objectTypes) ? meta.objectTypes : []).map(normalizeSearchText).filter(Boolean),
+    eventId: clampText(meta.eventId, 160),
+    active: meta.active !== false,
+    at: clampText(meta.at || new Date().toISOString(), 64),
+    raw: meta.raw
+  }
+}
+
+const cameraWatchMatchesEvent = (watch, event) => {
+  if (!watch || !event) return false
+  const watchCameraId = clampText(watch.cameraId, 160)
+  const eventCameraId = clampText(event.cameraId, 160)
+  if (watchCameraId && eventCameraId && watchCameraId !== eventCameraId) return false
+  if ((!watchCameraId || !eventCameraId) && normalizeSearchText(watch.cameraName) !== normalizeSearchText(event.cameraName)) return false
+  const wantedObjects = (Array.isArray(watch.objectTypes) ? watch.objectTypes : []).map(normalizeCameraObjectType).filter(Boolean)
+  const watchEventType = normalizeCameraEventType(watch.eventType)
+  const eventType = normalizeCameraEventType(event.eventType)
+  const genericSmartDetection = watchEventType === 'smartDetect' ||
+    (watchEventType === 'motion' && wantedObjects.length > 0)
+  if (genericSmartDetection) {
+    if (!['smartDetectZone', 'smartDetectLine', 'smartDetectLoiterZone'].includes(eventType)) return false
+  } else if (watchEventType && watchEventType !== eventType) return false
+  const watchScope = normalizeSearchText(watch.scopeId || watch.scopeName)
+  const eventScopeCandidates = [event.scopeId, event.scopeName].map(normalizeSearchText).filter(Boolean)
+  if (watchScope && !eventScopeCandidates.some(candidate => candidate === watchScope || candidate.includes(watchScope) || watchScope.includes(candidate))) return false
+  if (wantedObjects.length) {
+    const detectedObjects = (Array.isArray(event.objectTypes) ? event.objectTypes : []).map(normalizeCameraObjectType).filter(Boolean)
+    if (!detectedObjects.some(type => wantedObjects.includes(type))) return false
+  }
+  return true
+}
+
+const normalizeKnxAiCameraImage = ({ data, mediaType } = {}) => {
+  if (!Buffer.isBuffer(data)) throw new Error('The camera snapshot is not binary image data')
+  if (data.length === 0) throw new Error('The camera snapshot is empty')
+  if (data.length > KNX_AI_CAMERA_IMAGE_MAX_BYTES) throw new Error(`The camera snapshot exceeds ${KNX_AI_CAMERA_IMAGE_MAX_BYTES} bytes`)
+  const type = clampText(mediaType || 'image/jpeg', 80).toLocaleLowerCase().split(';')[0]
+  if (!['image/jpeg', 'image/png', 'image/webp', 'image/gif'].includes(type)) throw new Error(`Unsupported camera image type: ${type}`)
+  return { data, mediaType: type, bytes: data.length }
+}
+
+const buildKnxAiCameraNotificationText = ({ language, event } = {}) => {
+  const lang = clampText(language || 'en', 8).toLocaleLowerCase()
+  const camera = clampText(event && event.cameraName, 240) || clampText(event && event.cameraId, 160) || 'camera'
+  const eventType = normalizeCameraEventType(event && event.eventType)
+  const scope = clampText(event && (event.scopeName || event.scopeId), 240)
+  const objectTypes = uniqueTexts(event && event.objectTypes).join(', ')
+  const details = [scope, objectTypes].filter(Boolean).join(' — ')
+  const suffix = details ? ` (${details})` : ''
+  const labels = {
+    it: { smartDetectLine: 'un attraversamento di linea', smartDetectZone: 'un ingresso in zona', smartDetectLoiterZone: 'una permanenza in zona', motion: 'un movimento', ring: 'un suono del campanello', smartAudioDetect: 'un evento audio intelligente' },
+    de: { smartDetectLine: 'eine Linienüberquerung', smartDetectZone: 'einen Zoneneintritt', smartDetectLoiterZone: 'einen längeren Zonenaufenthalt', motion: 'eine Bewegung', ring: 'ein Klingeln', smartAudioDetect: 'ein intelligentes Audioereignis' },
+    fr: { smartDetectLine: 'un franchissement de ligne', smartDetectZone: 'une entrée dans une zone', smartDetectLoiterZone: 'une présence prolongée dans une zone', motion: 'un mouvement', ring: 'une sonnerie', smartAudioDetect: 'un événement audio intelligent' },
+    es: { smartDetectLine: 'un cruce de línea', smartDetectZone: 'una entrada en zona', smartDetectLoiterZone: 'una permanencia en zona', motion: 'un movimiento', ring: 'una llamada al timbre', smartAudioDetect: 'un evento de audio inteligente' },
+    zh: { smartDetectLine: '越线事件', smartDetectZone: '进入区域事件', smartDetectLoiterZone: '区域徘徊事件', motion: '移动事件', ring: '门铃事件', smartAudioDetect: '智能音频事件' },
+    en: { smartDetectLine: 'a line crossing', smartDetectZone: 'a zone entry', smartDetectLoiterZone: 'loitering in a zone', motion: 'motion', ring: 'a doorbell ring', smartAudioDetect: 'a smart audio event' }
+  }
+  const label = (labels[lang] || labels.en)[eventType] || (lang === 'zh' ? '摄像机事件' : lang === 'it' ? 'un evento' : lang === 'de' ? 'ein Ereignis' : lang === 'fr' ? 'un événement' : lang === 'es' ? 'un evento' : 'an event')
+  const copy = {
+    it: `La telecamera ${camera} ha rilevato ${label}${suffix}.`,
+    de: `Die Kamera ${camera} hat ${label} erkannt${suffix}.`,
+    fr: `La caméra ${camera} a détecté ${label}${suffix}.`,
+    es: `La cámara ${camera} ha detectado ${label}${suffix}.`,
+    zh: `摄像机 ${camera} 检测到${label}${suffix}。`,
+    en: `Camera ${camera} detected ${label}${suffix}.`
+  }
+  return copy[lang] || copy.en
+}
+
+module.exports = {
+  KNX_AI_CAMERA_IMAGE_MAX_BYTES,
+  KNX_AI_CAMERA_MAX_ACTIONS,
+  KNX_AI_CAMERA_REGISTRY_KEY,
+  buildKnxAiCameraNotificationText,
+  cameraWatchMatchesEvent,
+  getKnxAiCameraAdapterRegistry,
+  normalizeCameraEventType,
+  normalizeCameraObjectType,
+  normalizeKnxAiCameraAction,
+  normalizeKnxAiCameraActions,
+  normalizeKnxAiCameraEvent,
+  normalizeKnxAiCameraImage,
+  normalizeKnxAiCameraRegistration,
+  normalizeSearchText,
+  resolveKnxAiCamera
+}

package/nodes/utils/knxAiCatalogRetrieval.js

@@ -0,0 +1,349 @@
+const KNX_AI_CATALOG_MAX_RESEARCH_ROUNDS = 1
+const KNX_AI_CATALOG_MAX_ACTIONS_PER_ROUND = 4
+const KNX_AI_CATALOG_MAX_RESULTS_PER_ACTION = 12
+const KNX_AI_CATALOG_MAX_ACCUMULATED_OBJECTS = 24
+
+const normalizeText = (value) => String(value || '')
+  .normalize('NFKD')
+  .replace(/[\u0300-\u036f]/g, '')
+  .toLowerCase()
+  .replace(/[^\p{L}\p{N}/]+/gu, ' ')
+  .replace(/\s+/g, ' ')
+  .trim()
+
+const normalizeGa = (value) => String(value || '').trim()
+
+const clampLimit = (value) => Math.max(1, Math.min(
+  KNX_AI_CATALOG_MAX_RESULTS_PER_ACTION,
+  Math.round(Number(value) || 8)
+))
+
+const normalizeStringList = (value, maxItems = 12) => Array.from(new Set(
+  (Array.isArray(value) ? value : [])
+    .map(item => String(item || '').trim())
+    .filter(Boolean)
+)).slice(0, maxItems)
+
+const normalizeKnxAiCatalogActions = (value, { maxActions = KNX_AI_CATALOG_MAX_ACTIONS_PER_ROUND } = {}) => {
+  const accepted = []
+  const allowedOperations = new Set(['search', 'get', 'list_areas', 'browse_area', 'related'])
+  const allowedAccess = new Set(['any', 'read-only', 'read-write'])
+  const allowedPurposes = new Set(['any', 'read', 'write', 'inspect'])
+  ;(Array.isArray(value) ? value : []).slice(0, Math.max(1, Number(maxActions) || 1)).forEach(candidate => {
+    const source = candidate && typeof candidate === 'object' && !Array.isArray(candidate) ? candidate : {}
+    const operation = String(source.operation || '').trim().toLowerCase()
+    if (!allowedOperations.has(operation)) return
+    const query = String(source.query || '').trim().slice(0, 300)
+    const destinations = normalizeStringList(source.destinations, 20)
+    const area = String(source.area || '').trim().slice(0, 300)
+    if (operation === 'search' && !query) return
+    if ((operation === 'get' || operation === 'related') && !destinations.length) return
+    if (operation === 'browse_area' && !area) return
+    const semanticKinds = normalizeStringList(source.semanticKinds, 12)
+      .map(kind => normalizeText(kind))
+      .filter(Boolean)
+    const requestedAccess = String(source.access || '').trim().toLowerCase()
+    const requestedPurpose = String(source.purpose || '').trim().toLowerCase()
+    accepted.push({
+      operation,
+      query,
+      destinations,
+      area,
+      semanticKinds,
+      access: allowedAccess.has(requestedAccess) ? requestedAccess : 'any',
+      purpose: allowedPurposes.has(requestedPurpose) ? requestedPurpose : 'any',
+      offset: Math.max(0, Math.min(100000, Math.round(Number(source.offset) || 0))),
+      limit: clampLimit(source.limit),
+      reason: String(source.reason || '').trim().slice(0, 1000)
+    })
+  })
+  return accepted
+}
+
+const editDistanceAtMostTwo = (left, right) => {
+  if (left === right) return 0
+  if (!left || !right || Math.abs(left.length - right.length) > 2) return 3
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index)
+  for (let i = 1; i <= left.length; i += 1) {
+    const current = [i]
+    let rowMinimum = current[0]
+    for (let j = 1; j <= right.length; j += 1) {
+      const substitution = previous[j - 1] + (left[i - 1] === right[j - 1] ? 0 : 1)
+      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, substitution)
+      rowMinimum = Math.min(rowMinimum, current[j])
+    }
+    if (rowMinimum > 2) return 3
+    previous = current
+  }
+  return previous[right.length]
+}
+
+const tokenQuality = (queryToken, candidateToken) => {
+  if (queryToken === candidateToken) return 1
+  const substringMinimum = /[^\u0000-\u007f]/.test(queryToken) ? 2 : 3
+  if (queryToken.length >= substringMinimum && (candidateToken.includes(queryToken) || queryToken.includes(candidateToken))) return 0.82
+  if (queryToken.length < 4) return 0
+  const distance = editDistanceAtMostTwo(queryToken, candidateToken)
+  if (distance === 1) return 0.68
+  if (distance === 2 && queryToken.length >= 7) return 0.5
+  return 0
+}
+
+const buildSearchDocument = (item) => {
+  const semantic = item && item.semantic && typeof item.semantic === 'object' ? item.semantic : {}
+  const aliases = Array.isArray(item && item.aliases) ? item.aliases : []
+  const options = Array.isArray(item && item.valueOptions) ? item.valueOptions : []
+  const fields = {
+    ga: normalizeText(item && item.ga),
+    label: normalizeText(item && item.label),
+    etsName: normalizeText(item && item.etsName),
+    hierarchy: normalizeText(item && item.hierarchyPath),
+    aliases: normalizeText(aliases.join(' ')),
+    semantic: normalizeText([semantic.kind, semantic.area, item && item.mainGroup, item && item.middleGroup, ...(Array.isArray(item && item.tags) ? item.tags : [])].join(' ')),
+    values: normalizeText(options.map(option => `${option && option.value} ${option && option.label}`).join(' ')),
+    dpt: normalizeText(item && item.dpt)
+  }
+  const combined = Object.values(fields).join(' ').trim()
+  return { fields, combined, tokens: Array.from(new Set(combined.split(' ').filter(Boolean))) }
+}
+
+const itemPassesFilters = (item, action) => {
+  if (action.access === 'read-only' && item && item.readOnly !== true) return false
+  if (action.access === 'read-write' && item && item.readOnly === true) return false
+  if (action.purpose === 'write' && item && item.readOnly === true) return false
+  const semantic = item && item.semantic && typeof item.semantic === 'object' ? item.semantic : {}
+  if (action.semanticKinds.length && !action.semanticKinds.includes(normalizeText(semantic.kind))) return false
+  return true
+}
+
+const purposeScore = (item, purpose) => {
+  const readOnly = item && item.readOnly === true
+  if (purpose === 'write') return readOnly ? -1000 : 130
+  if (purpose === 'read') return readOnly ? 90 : 50
+  if (purpose === 'inspect') return readOnly ? 70 : 55
+  return 0
+}
+
+const scoreSearchMatch = (item, action) => {
+  if (!itemPassesFilters(item, action)) return 0
+  const query = normalizeText(action.query)
+  if (!query) return 0
+  const document = buildSearchDocument(item)
+  const exactGa = normalizeGa(item && item.ga) === normalizeGa(action.query)
+  if (exactGa) return 2000 + purposeScore(item, action.purpose)
+  let score = 0
+  if (document.fields.label === query) score += 900
+  if (document.fields.etsName === query) score += 850
+  if (document.fields.aliases.split(' ').includes(query)) score += 800
+  if (document.fields.hierarchy === query) score += 750
+  if (document.combined.includes(query)) score += 360
+  const queryTokens = query.split(' ').filter(Boolean)
+  let qualityTotal = 0
+  let matchedTokens = 0
+  let strongMatches = 0
+  for (const queryToken of queryTokens) {
+    let best = 0
+    for (const candidateToken of document.tokens) {
+      best = Math.max(best, tokenQuality(queryToken, candidateToken))
+      if (best === 1) break
+    }
+    if (best >= 0.5) {
+      matchedTokens += 1
+      qualityTotal += best
+      if (best >= 0.68) strongMatches += 1
+    }
+  }
+  if (strongMatches === 0) return 0
+  const missingTokens = Math.max(0, queryTokens.length - matchedTokens)
+  const coverage = queryTokens.length > 0 ? matchedTokens / queryTokens.length : 0
+  score += qualityTotal * 120
+  score += coverage * 200
+  score += Math.max(0, matchedTokens - 1) * 50
+  score -= missingTokens * 18
+  score += purposeScore(item, action.purpose)
+  if (action.area) {
+    const area = normalizeText(action.area)
+    const itemArea = normalizeText([
+      item && item.hierarchyPath,
+      item && item.mainGroup,
+      item && item.middleGroup,
+      item && item.semantic && item.semantic.area
+    ].join(' '))
+    if (!itemArea.includes(area)) return 0
+    score += 120
+  }
+  return score
+}
+
+const sortScoredItems = (scored) => scored
+  .sort((left, right) => right.score - left.score || String(left.item && left.item.hierarchyPath || left.item && left.item.label || left.item && left.item.ga || '').localeCompare(String(right.item && right.item.hierarchyPath || right.item && right.item.label || right.item && right.item.ga || '')))
+  .map(entry => entry.item)
+
+const findSearchItems = (catalog, action) => sortScoredItems(
+  catalog.map(item => ({ item, score: scoreSearchMatch(item, action) })).filter(entry => entry.score > 0)
+)
+
+const buildAreaRows = (catalog) => {
+  const areas = new Map()
+  catalog.forEach(item => {
+    const semantic = item && item.semantic && typeof item.semantic === 'object' ? item.semantic : {}
+    const candidates = [semantic.area, item && item.hierarchyPath, item && item.middleGroup, item && item.mainGroup]
+      .map(value => String(value || '').trim())
+      .filter(Boolean)
+    const area = candidates[0] || 'Unclassified'
+    const key = normalizeText(area)
+    if (!key) return
+    if (!areas.has(key)) areas.set(key, { area, count: 0, sampleLabels: [] })
+    const row = areas.get(key)
+    row.count += 1
+    const label = String(item && item.label || item && item.ga || '').trim()
+    if (label && row.sampleLabels.length < 3 && !row.sampleLabels.includes(label)) row.sampleLabels.push(label)
+  })
+  return Array.from(areas.values()).sort((left, right) => right.count - left.count || left.area.localeCompare(right.area))
+}
+
+const findAreaItems = (catalog, action) => {
+  const requestedArea = normalizeText(action.area)
+  return sortScoredItems(catalog
+    .filter(item => itemPassesFilters(item, action))
+    .map(item => {
+      const semantic = item && item.semantic && typeof item.semantic === 'object' ? item.semantic : {}
+      const areaText = normalizeText([semantic.area, item && item.hierarchyPath, item && item.middleGroup, item && item.mainGroup].join(' '))
+      if (!areaText.includes(requestedArea)) return { item, score: 0 }
+      return { item, score: 400 + purposeScore(item, action.purpose) }
+    })
+    .filter(entry => entry.score > 0))
+}
+
+const findRelatedItems = (catalog, action) => {
+  const requested = new Set(action.destinations.map(normalizeGa))
+  const seeds = catalog.filter(item => requested.has(normalizeGa(item && item.ga)))
+  if (!seeds.length) return []
+  const seedDocuments = seeds.map(seed => ({ seed, tokens: new Set(buildSearchDocument(seed).tokens) }))
+  const scored = catalog.map(item => {
+    if (!itemPassesFilters(item, action)) return { item, score: 0 }
+    let best = requested.has(normalizeGa(item && item.ga)) ? 1000 : 0
+    const itemTokens = buildSearchDocument(item).tokens
+    seedDocuments.forEach(({ seed, tokens: seedTokens }) => {
+      if (seed === item) return
+      const seedSemantic = seed && seed.semantic && typeof seed.semantic === 'object' ? seed.semantic : {}
+      const itemSemantic = item && item.semantic && typeof item.semantic === 'object' ? item.semantic : {}
+      let relationScore = 0
+      if (normalizeText(seed.hierarchyPath) && normalizeText(seed.hierarchyPath) === normalizeText(item.hierarchyPath)) relationScore += 260
+      if (normalizeText(seedSemantic.area) && normalizeText(seedSemantic.area) === normalizeText(itemSemantic.area)) relationScore += 180
+      if (normalizeText(seed.middleGroup) && normalizeText(seed.middleGroup) === normalizeText(item.middleGroup)) relationScore += 100
+      if (normalizeText(seed.mainGroup) && normalizeText(seed.mainGroup) === normalizeText(item.mainGroup)) relationScore += 45
+      if (normalizeText(seedSemantic.kind) && normalizeText(seedSemantic.kind) === normalizeText(itemSemantic.kind)) relationScore += 65
+      const overlap = itemTokens.filter(token => token.length >= 4 && seedTokens.has(token)).length
+      relationScore += Math.min(100, overlap * 20)
+      if (relationScore <= 0) return
+      const score = relationScore + purposeScore(item, action.purpose)
+      best = Math.max(best, score)
+    })
+    return { item, score: best }
+  }).filter(entry => entry.score > 0)
+  return sortScoredItems(scored)
+}
+
+const actionFingerprint = (action) => JSON.stringify({
+  operation: action.operation,
+  query: normalizeText(action.query),
+  destinations: action.destinations.map(normalizeGa).sort(),
+  area: normalizeText(action.area),
+  semanticKinds: action.semanticKinds.slice().sort(),
+  access: action.access,
+  purpose: action.purpose,
+  offset: action.offset,
+  limit: action.limit
+})
+
+const executeKnxAiCatalogActions = ({ actions, catalog, priorResults = [] } = {}) => {
+  const safeCatalog = Array.isArray(catalog) ? catalog : []
+  const normalized = normalizeKnxAiCatalogActions(actions)
+  const seen = new Set((Array.isArray(priorResults) ? priorResults : []).map(result => String(result && result.fingerprint || '')).filter(Boolean))
+  const results = []
+  normalized.forEach(action => {
+    const fingerprint = actionFingerprint(action)
+    if (seen.has(fingerprint)) return
+    seen.add(fingerprint)
+    if (action.operation === 'list_areas') {
+      const allAreas = buildAreaRows(safeCatalog.filter(item => itemPassesFilters(item, action)))
+      results.push({
+        action,
+        fingerprint,
+        ok: true,
+        totalMatches: allAreas.length,
+        truncated: allAreas.length > action.offset + action.limit,
+        areas: allAreas.slice(action.offset, action.offset + action.limit),
+        items: []
+      })
+      return
+    }
+    let matched = []
+    if (action.operation === 'get') {
+      const requested = new Set(action.destinations.map(normalizeGa))
+      matched = safeCatalog.filter(item => requested.has(normalizeGa(item && item.ga)) && itemPassesFilters(item, action))
+    } else if (action.operation === 'search') {
+      matched = findSearchItems(safeCatalog, action)
+    } else if (action.operation === 'browse_area') {
+      matched = findAreaItems(safeCatalog, action)
+    } else if (action.operation === 'related') {
+      matched = findRelatedItems(safeCatalog, action)
+    }
+    results.push({
+      action,
+      fingerprint,
+      ok: true,
+      totalMatches: matched.length,
+      truncated: matched.length > action.offset + action.limit,
+      items: matched.slice(action.offset, action.offset + action.limit),
+      areas: []
+    })
+  })
+  return results
+}
+
+const collectKnxAiCatalogObjects = (results, maxItems = KNX_AI_CATALOG_MAX_ACCUMULATED_OBJECTS) => {
+  const byGa = new Map()
+  ;(Array.isArray(results) ? results.slice().reverse() : []).forEach(result => {
+    ;(Array.isArray(result && result.items) ? result.items : []).forEach(item => {
+      const ga = normalizeGa(item && item.ga)
+      if (!ga || byGa.has(ga) || byGa.size >= maxItems) return
+      byGa.set(ga, item)
+    })
+  })
+  return Array.from(byGa.values())
+}
+
+const buildKnxAiCatalogResearchContext = (results) => {
+  const source = Array.isArray(results) ? results : []
+  if (!source.length) return ''
+  const lines = ['LOCAL ETS CATALOG RETRIEVAL RESULTS:']
+  source.forEach((result, index) => {
+    const action = result && result.action ? result.action : {}
+    const target = action.operation === 'search'
+      ? ` query=${JSON.stringify(action.query)}`
+      : action.operation === 'browse_area'
+        ? ` area=${JSON.stringify(action.area)}`
+        : (action.operation === 'get' || action.operation === 'related')
+            ? ` destinations=${JSON.stringify(action.destinations)}`
+            : ''
+    lines.push(`[C${index + 1}] ${action.operation || 'unknown'}${target}: ${Number(result && result.totalMatches) || 0} match(es); page offset=${Math.max(0, Number(action.offset) || 0)}, limit=${Math.max(1, Number(action.limit) || 1)}${result && result.truncated ? '; more matches are available with a larger offset' : ''}.`)
+    ;(Array.isArray(result && result.areas) ? result.areas : []).forEach(area => {
+      lines.push(`- area ${JSON.stringify(area.area)} | ${area.count} objects | examples ${area.sampleLabels.join(', ') || '?'}`)
+    })
+  })
+  lines.push('END LOCAL ETS CATALOG RETRIEVAL RESULTS')
+  return lines.join('\n')
+}
+
+module.exports = {
+  KNX_AI_CATALOG_MAX_ACCUMULATED_OBJECTS,
+  KNX_AI_CATALOG_MAX_ACTIONS_PER_ROUND,
+  KNX_AI_CATALOG_MAX_RESEARCH_ROUNDS,
+  KNX_AI_CATALOG_MAX_RESULTS_PER_ACTION,
+  buildKnxAiCatalogResearchContext,
+  collectKnxAiCatalogObjects,
+  executeKnxAiCatalogActions,
+  normalizeKnxAiCatalogActions
+}