Skip to content

1.1.0-preview.4 - Spectra

Pre-release
Pre-release

Choose a tag to compare

View all tags
@seiggy seiggy released this 06 Mar 02:24
· 519 commits to master since this release
v1.1.0-preview.4
c87b613
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.
  • Embedding Resiliency + Live Progress — Entity-location embeddings now generate in throttled background batches, expose SSE progress, and support per-item evict/regenerate controls.
  • 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.
  • Brave Search API Plugin — New privacy-respecting web search plugin using the Brave Search API, with full plugin config GUI for managing API keys from the dashboard.
  • 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).

📡 Entity Embedding Resiliency + Live Progress

  • Name fallback for embedding safety — When an entity/floor/area has no name or alias, matchable names now fall back to IDs (entity IDs strip domain and replace _ with spaces) to avoid invalid empty embedding inputs.
  • Non-blocking embedding generation — EntityLocationService now loads/cache location data first, then generates embeddings asynchronously in throttled batches with retry/backoff.
  • Batch embedding pipeline — Uses provider batch generation (GenerateAsync(IEnumerable<string>)) to reduce request pressure and better handle provider-side limits.
  • Progress API + SSE stream — Added /api/entity-location/embedding-progress and /api/entity-location/embedding-progress/live for real-time generation status.
  • Per-item cache controls — Added embedding eviction/regeneration endpoints for floors, areas, and entities.
  • Dashboard live status — Entity Location page now shows a live generation progress bar, missing-embedding count, and updates without manual refresh.

🧠 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.

🌐 Brave Search API Plugin

  • New web search provider — plugins/brave-search/plugin.cs implements IWebSearchSkill using the Brave Search API as an alternative to SearXNG.
  • API key authentication — Configurable via BraveSearch:ApiKey, BRAVE_SEARCH_API_KEY env var, or the new plugin config GUI.
  • Full telemetry — OpenTelemetry ActivitySource and Meter instrumentation for request counts, failure counts, and search duration.
  • Provider-agnostic agent — General Agent skill description no longer references SearXNG; works with whichever search plugin is active.

⚙️ Plugin Configuration GUI

  • Schema-driven config — Plugins can now declare configurable properties via ConfigSection, ConfigDescription, and ConfigProperties on the ILuciaPlugin interface (default interface members — non-breaking).
  • PluginConfigProperty record — Defines name, type, description, default value, and sensitivity for each config field.
  • GET /api/plugins/config/schemas — New endpoint aggregates config schemas from all loaded plugins.
  • Dashboard Configuration tab — New tab on the Plugins page renders dynamic forms from plugin schemas, with sensitive-field masking, save/discard, and toast notifications.
  • SearXNG retrofitted — SearXNG plugin now declares its BaseUrl in the config schema so it can also be configured from the UI.

🐛 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.
  • Startup embedding failures from blank input — Prevented invalid embedding calls caused by empty match names.
  • Embedding request bursts during cache reloads — Moved generation to throttled background batching to reduce provider rate-limit pressure.
  • Presence sensor refresh duplicate-key crashes — Fixed MongoDB duplicate key failures on re-scan by deduplicating auto-detected sensor IDs and skipping IDs already reserved by user overrides (issue #41).

🧪 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.
  • Name fallback tests — EntityMatchNameFormatterTests validates alias sanitization and ID-based fallback behavior used by embedding inputs.
  • Brave Search contract tests — BraveSearchWebSearchSkillTests validates HTTP request format, auth headers, JSON deserialization, empty results, and error handling.
  • Plugin config schema tests — PluginConfigSchemaTests validates default interface members, schema declaration, property equality, and filtering logic.

📋 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.Agents/Models/HomeAssistant/EntityLocationEmbeddingProgress.cs Embedding coverage/progress snapshot model
lucia.Agents/Services/EntityMatchNameFormatter.cs Safe name/alias formatter with ID fallback
lucia-dashboard/src/pages/MatcherDebugPage.tsx Matcher debug dashboard page
lucia-dashboard/src/pages/EntityLocationPage.tsx Live embedding progress UI + embedding actions
lucia.PlaywrightTests/Agents/PromptCacheRoutingTests.cs Cache embedding e2e test
plugins/brave-search/plugin.cs Brave Search API web search plugin
lucia.Agents/Abstractions/PluginConfigProperty.cs Plugin config property record type
lucia.AgentHost/PluginFramework/Models/PluginConfigSchemaDto.cs Plugin config schema API DTO
lucia.AgentHost/PluginFramework/Models/PluginConfigPropertyDto.cs Plugin config property API DTO
lucia-dashboard/src/components/PluginConfigTab.tsx Plugin configuration tab component
lucia.Tests/BraveSearchWebSearchSkillTests.cs Brave Search HTTP contract tests
lucia.Tests/PluginConfigSchemaTests.cs Plugin config schema infrastructure tests

🗑️ 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