Skip to content

v1.1.0-preview.3 - Spectra

Pre-release
Pre-release

Choose a tag to compare

View all tags
@seiggy seiggy released this 05 Mar 19:38
· 527 commits to master since this release
v1.1.0-preview.3
6f33a90
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes - 1.1.0

Release Date: March 6, 2026
Code Name: "Spectra"

🔮 Overview

"Spectra" delivers Lucia's largest entity-intelligence upgrade to date and folds in post-cut stabilization work across Home Assistant conversation flow, model-provider support, setup/plugins UX, and CI reliability. This release unifies entity modeling, introduces multi-signal matching, fixes semantic prompt-cache persistence and thresholding, and hardens the platform for day-to-day operation.

🚀 Highlights

  • Unified Entity Model — All Home Assistant entity types now share a common HomeAssistantEntity base with domain-specific subtypes.
  • HybridEntityMatcher — Multi-weighted search combines Levenshtein, Jaro-Winkler, phonetic matching, aliases, and token overlap.
  • Prompt Cache Overhaul — Embeddings now persist correctly, routing/chat thresholds are split, and cache settings hot-reload without restart.
  • Home Assistant Multi-turn Continuity — Follow-up conversation flow restored and HA commit validation tightened.
  • OpenRouter + Discovery — OpenRouter added as a first-class provider with model discovery support.
  • Plugin/Setup/Dashboard Stabilization — Headless setup and HA setup-step UX improvements, plugin installation reliability fixes, and dashboard/tooling cleanup.
  • CI Hardening — HACS validation workflow corrected, deployment docs lint cleanup, and release pipeline reliability improvements.

✨ What's New

🔍 HybridEntityMatcher

  • Multi-signal scoring — Combines normalized Levenshtein, Jaro-Winkler, token overlap, phonetic matching, and exact/prefix bonuses into a weighted composite score.
  • Configurable via HybridMatchOptions — Tune weights, minimum thresholds, and phonetic algorithm (Soundex vs Double Metaphone) per search context.
  • IMatchableEntity interface — Any entity type can participate in hybrid search by implementing this lightweight interface.
  • EntityMatchResult — Rich result type carrying the matched entity, composite score, individual signal scores, and match metadata.

🏠 Unified Entity Architecture

  • HomeAssistantEntity base class — Shared properties (entity ID, friendly name, area, floor, aliases, state, supported features as SupportedFeatures bitflag enum) for all HA entity types.
  • Domain subtypes — LightEntity, ClimateEntity, FanEntity, MusicPlayerEntity extend the base with domain-specific attributes (color modes, HVAC modes, fan speeds, media metadata).
  • EntityLocationService refactor — Centralized entity resolution service replaces per-skill FindLightsByAreaAsync/FindLightAsync methods. Skills now delegate entity lookup to the location service.
  • AreaInfo caching — Areas now pre-build and cache entity collections, floor associations, and phonetic data for fast hierarchical search.
  • FloorInfo model — First-class floor representation with area containment for multi-level home topologies.

👁️ Entity Visibility

  • EntityVisibilityConfig — Per-entity visibility settings stored in MongoDB, letting users hide entities from Lucia without removing them from Home Assistant.
  • EntityVisibilityApi — REST endpoints for bulk visibility management with area/domain filtering.
  • HA Exposed Entity List — Support for pulling the pre-filtered exposed entity list from Home Assistant via WebSocket (homeassistant/expose_entity/list).

🧠 Prompt Cache Overhaul

  • Embedding persistence fixed — Removed [JsonIgnore] from CachedPromptEntry.Embedding and CachedChatResponseData.Embedding that prevented embeddings from ever being serialized to Redis.
  • Split thresholds — SemanticSimilarityThreshold (routing, default 0.95) and ChatCacheSemanticThreshold (chat, default 0.98) are independently configurable.
  • Hot-reload via IOptionsMonitor — Cache thresholds update within seconds of dashboard config changes, no restart required.
  • Hit count tracking fix — Routing cache exact-match hits now correctly persist the incremented HitCount back to Redis.
  • Normalized prompt keys — NormalizePrompt applies Trim().ToLowerInvariant() for stable, case-insensitive cache keys.
  • User-text-only embedding — Chat cache embeddings are computed from the user's request text only.

🏠 Home Assistant Conversation Flow

  • Restored multi-turn continuity behavior for follow-up requests.
  • Enforced stricter HA-side commit validation in automation and tool flows.
  • Addressed follow-up review feedback for the multi-turn flow fix set.

🤖 Model Providers

  • Added OpenRouter as a provider option in model-provider interactions.
  • Expanded model discovery flow and post-review provider hardening.

🔌 Setup, Plugins, and Dashboard

  • Improved headless setup and Home Assistant setup-step UX.
  • Fixed plugin tooling/integration issues that blocked reliable plugin installation.
  • Resolved setup/plugin/dashboard review and lint issues.

🐛 Matcher Debug API

  • /api/matcher/debug — Interactive endpoint for testing HybridEntityMatcher queries against live entity data with per-signal score breakdowns.
  • Dashboard page — MatcherDebugPage.tsx provides a UI for experimenting with matcher queries and score distributions.

🔧 Skill Optimizer Migration

  • GetCachedEntitiesAsync removed from IOptimizableSkill — Entity resolution now flows through EntityLocationService.
  • Legacy skill methods retired — LightControlSkill.FindLightsByAreaAsync, FindLightAsync, GetLightStateAsync, and SetLightStateAsync now throw NotSupportedException.
  • Device cache dependencies removed — LightAgent no longer depends directly on embedding provider or device cache.

🐳 CI/CD and Delivery

  • Added support for pre-release Docker tags without moving latest.
  • Fixed CI workflow ordering to check out repository contents before HACS validation.
  • Fixed deployment markdownlint issues and removed defunct documentation.

🐛 Bug Fixes

  • Prompt cache embeddings never persisted — Fixed serialization of embedding fields.
  • Chat cache replayed incorrect actions — Prevented cross-action semantic collisions by splitting routing/chat thresholds.
  • Routing cache hit count not persisted — Exact-hit HitCount now writes back to Redis.
  • Cache config changes required restart — Migrated to IOptionsMonitor<T> for hot-reload.
  • Embedding provider concurrency issue — Replaced unsafe dictionary usage with concurrency-safe coordination.
  • Tracing duration always reported 0ms — Routing completion timing now measures elapsed request duration correctly.
  • Unsupported tool-chain config caused provider errors — Removed invalid configuration path.
  • Dashboard dependency vulnerabilities — Patched minimatch (CVE-2026-27903) and rollup (CVE-2026-27606).
  • Home Assistant follow-up flow regression — Fixed continuity and follow-up behavior for multi-turn requests.
  • Plugin install regressions — Fixed install path/tooling issues affecting plugin usability.
  • HACS validation workflow failure — Corrected CI step order to ensure repository content is present.

🧪 Testing

  • Playwright e2e test — PromptCacheRoutingTests validates prompt-cache embedding round-trip and semantic route matching behavior.
  • Embedding diagnostics — EmbeddingMatchingTests measure similarity behavior across synonym/opposite/cross-domain prompt variants.
  • Plugin/install regression coverage — Added and updated tests around plugin installability and related dashboard/setup flows.

📋 New Files

Path Purpose
lucia.Agents/Abstractions/IEntityLocationService.cs Centralized entity resolution interface
lucia.Agents/Abstractions/IHybridEntityMatcher.cs Multi-signal entity search interface
lucia.Agents/Abstractions/IMatchableEntity.cs Entity search participation contract
lucia.Agents/Models/HomeAssistant/HomeAssistantEntity.cs Unified HA entity base class
lucia.Agents/Models/HomeAssistant/SupportedColorModes.cs Light color mode bitflag enum
lucia.Agents/Models/HomeAssistant/FloorInfo.cs Floor model with area containment
lucia.Agents/Models/HomeAssistant/OccupiedArea.cs Area occupancy tracking
lucia.Agents/Models/HomeAssistant/EntityVisibilityConfig.cs Per-entity visibility settings
lucia.Agents/Models/HybridEntityMatcher.cs Multi-weighted entity matching engine
lucia.Agents/Models/HybridMatchOptions.cs Matcher configuration (weights, thresholds)
lucia.Agents/Models/MatchableEntityInfo.cs Searchable entity wrapper
lucia.Agents/Models/EntityMatchResult.cs Scored match result with signal breakdown
lucia.Agents/Models/HierarchicalSearchResult.cs Floor→Area→Entity search result
lucia.Agents/Models/ResolutionStrategy.cs Entity resolution strategy enum
lucia.Agents/Integration/SearchTermCache.cs Cached search term normalization
lucia.Agents/Integration/SearchTermNormalizer.cs Query normalization pipeline
lucia.HomeAssistant/Models/ExposedEntityListResponse.cs HA WebSocket exposed entity response
lucia.AgentHost/Apis/EntityVisibilityApi.cs Entity visibility REST endpoints
lucia.AgentHost/Apis/MatcherDebugApi.cs Matcher debug/testing REST endpoints
lucia-dashboard/src/pages/MatcherDebugPage.tsx Matcher debug dashboard page
lucia.PlaywrightTests/Agents/PromptCacheRoutingTests.cs Cache embedding e2e test

🗑️ Removed / Deprecated

Path Reason
lucia.Agents/Services/IEntityLocationService.cs Moved to Abstractions/ namespace
lucia.Agents/Models/FloorInfo.cs Moved to Models/HomeAssistant/
lucia.Agents/Models/OccupiedArea.cs Moved to Models/HomeAssistant/
lucia.Agents/Agents/DiagnosticChatClientWrapper.cs Replaced by TracingChatClientFactory
lucia.Agents/Configuration/AgentConfiguration.cs Replaced by AgentDefinition
LightControlSkill.FindLightsByAreaAsync Throws NotSupportedException — use entity tools
LightControlSkill.FindLightAsync Throws NotSupportedException — use entity tools
IOptimizableSkill.GetCachedEntitiesAsync Removed — optimizer uses location service

⬆️ Upgrade Notes

  1. Cache eviction recommended — Evict routing and chat caches via dashboard (or DELETE /api/prompt-cache and DELETE /api/chat-cache) to clear stale entries.
  2. New cache config properties — RouterExecutor:SemanticSimilarityThreshold (0.95) and RouterExecutor:ChatCacheSemanticThreshold (0.98) can be tuned in dashboard settings.
  3. Skill API breaking changes — Skills calling FindLightsByAreaAsync, FindLightAsync, or GetCachedEntitiesAsync must migrate to unified entity tools via EntityLocationService.
Assets 2
Loading