Assist Canonicalizer for Home Assistant
Introduction
Assist Canonicalizer enhances Home Assistant Assist by improving intent accuracy. It canonicalizes natural language commands through a multi‑signal lexical ranking engine before they reach the built‑in conversation system. As a native conversation agent, it reduces mismatches and fallback rates while running entirely on your local machine. It is LLM‑free, with no cloud, no telemetry, and no external calls, ensuring privacy, speed, and reliability.
Key Benefits
-
Accurate Commands: Improve voice assistant accuracy for smoother control
-
Instant Feedback: Get fast responses without delays
-
Seamless Setup: Works automatically with Home Assistant, no manual configuration
-
Private and Local: Runs entirely on your device with no cloud or telemetry
-
Multi‑Language Ready: Supports different languages with smart indexing
-
Reliable Fallbacks: Safely handles uncertain inputs with backup options
Installation
Option 1: Using HACS (Recommended)
-
Open HACS in Home Assistant.
-
Search for Assist Canonicalizer.
-
If not found, click the three dots in the top right corner and select Custom repositories.
-
Add
https://github.com/luuquangvu/assist-canonicalizerwith category Integration. -
Search for Assist Canonicalizer and click Download.
-
Restart Home Assistant.
Option 2: Manual Installation
-
Download the latest release and extract the files.
-
Copy the
custom_components/assist_canonicalizerfolder into your Home Assistantconfig/custom_components/directory. -
Restart Home Assistant.
Setup & Configuration
-
Go to Settings > Devices & Services.
-
Click Add Integration and search for Assist Canonicalizer.
-
Select the Fallback Conversation Agent. When the canonicalizer cannot safely match a candidate, your original text is dispatched to this agent as a second chance. Choosing the built-in Home Assistant agent as the fallback is usually ineffective; the accepted canonicalized candidate was already validated against it and failed, so sending the raw text back to the same agent will likely fail again. For best results, select an LLM-based conversation agent that can interpret natural language differently and recover from the mismatch.
-
Set the Minimum Match Confidence. A candidate must score at or above this threshold across all four ranking signals to be accepted. Stick with the default value initially and use the Test Match action to observe real scores before making adjustments.
-
Set the Minimum Confidence Margin. The gap between the top-ranked candidate and the next candidate with a different intent name must be at least this value. This prevents situations where the input is ambiguous and two different intents score similarly. Use the default value at first; only tighten or relax it after analyzing actual score breakdowns with Test Match.
-
Go to Settings > Voice assistants and open your Assist pipeline. Under Conversation agents, select Assist Canonicalizer from the agent list. We recommend enabling Prefer handling commands locally so that the built-in local intent recognizer (Hassil) is tried first. If it can handle the command directly, it does so without involving the canonicalizer; otherwise, Assist Canonicalizer takes over to match the input against its canonical index.
[!IMPORTANT]
Without completing the above steps, Assist Canonicalizer will not process any commands. The integration only activates when it is part of the active Assist pipeline.
Project Details
For integration instructions and source code, please visit the GitHub repository: Assist Canonicalizer. The project is open source and licensed under the terms provided there.
Feedback
Welcome your feedback, bug reports, and feature requests. You can share them here or directly on GitHub.
