node-red-contrib-knx-ultimate 7.1.4 → 8.0.2

package/nodes/utils/knxAiCamera.js

@@ -1,302 +0,0 @@
-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

@@ -1,349 +0,0 @@
-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
-}