treewide: diagnostics, debug tools, timing, logging cleanup

Author: charludo

README.md

@@ -278,13 +278,21 @@ The result is that usually, your commands will be handled by Hassil/`closest-int
 
 Runs one sentence through the matcher and returns a structured response, including the matched intent, the candidate pattern that won, its score, the captured slots, the canonical sentence that (would have been) forwarded to Hassil.
 Optionally, you can actually forward it to Hassil to see what action this would trigger. (The action is not actually triggered though.)
+On a miss, also surfaces a sample of the `name`/`area`/`floor` slot lists so you can immediately see whether entity exposure is wired up.
+Set `debug_top_candidates: true` to additionally get the top 10 raw-scored candidates regardless of threshold to see why your intended candidate did not win.
 
 Useful when a sentence unexpectedly doesn't match, slot capture is wrong, and so on.
 
 #### `closest_intent.dump_candidates`
 
 Debug-logs and returns the full per-language state. This includes every expanded candidate, every expansion rule and its surface forms, every slot list and its values.
 
+Options:
+
+- `include_builtins: true`: also build and include built-in intent candidates in the dump, even when the integration is configured without them. Best combined with `intent_filter` to keep the output manageable.
+- `intent_filter: <substring>`: case-insensitive substring filter on intent names (e.g. `HassTurnOn`).
+- `include_exposure: true`: adds a per-entity breakdown of which states are exposed to Assist. Useful when an entity isn't showing up in `slot_values['name']`, noisy otherwise.
+
 Useful for "fuck why is this STILL not working".
 
 #### Filing an issue

custom_components/closest_intent/__init__.py

@@ -157,10 +157,23 @@ def _async_register_services(hass: HomeAssistant) -> None:
     if hass.services.has_service(DOMAIN, SERVICE_DUMP_CANDIDATES):
         return
 
+    dump_schema = vol.Schema(
+        {
+            vol.Optional("include_builtins", default=False): cv.boolean,
+            vol.Optional("intent_filter"): cv.string,
+            vol.Optional("include_exposure", default=False): cv.boolean,
+        }
+    )
+
     async def _dump(call: ServiceCall) -> ServiceResponse:
+        data = dump_schema(dict(call.data))
+        include_builtins = data["include_builtins"]
+        intent_filter = data.get("intent_filter")
+        include_exposure = data["include_exposure"]
+
         agents = hass.data.get(DOMAIN, {}).get(KEY_AGENT_INSTANCES, {})
         if not agents:
-            _LOGGER.warning("closest_intent.dump_candidates: no agent instances registered yet")
+            _LOGGER.warning("dump_candidates: no agent instances registered yet")
             return {
                 "version": VERSION,
                 "agents": {},
@@ -169,13 +182,29 @@ async def _dump(call: ServiceCall) -> ServiceResponse:
 
         states: dict[str, dict] = {}
         for entry_id, agent in agents.items():
-            state = agent.dump_state()
+            builtin_overrides: dict | None = None
+            if include_builtins:
+                builtin_overrides = {}
+                for lang, (resolver, _, _) in agent._pools.items():
+                    try:
+                        builtin_overrides[lang] = await agent._async_get_builtin_override(
+                            lang, resolver
+                        )
+                    except Exception:  # pragma: no cover
+                        _LOGGER.exception(
+                            "dump_candidates[%s]: builtin override build failed",
+                            lang,
+                        )
+            state = agent.dump_state(
+                builtin_overrides=builtin_overrides,
+                intent_filter=intent_filter,
+                include_exposure=include_exposure,
+            )
             states[entry_id] = state
             # Pretty-print at DEBUG so users can paste a single block when
             # filing issues. INFO line is a one-liner pointer.
             _LOGGER.info(
-                "closest_intent.dump_candidates[%s]: %d candidate(s) across %d language(s); "
-                "see DEBUG for details",
+                "dump_candidates[%s]: %d candidate(s) across %d language(s) (full state at DEBUG)",
                 entry_id,
                 sum(
                     lang_state["user_candidate_count"] + lang_state["builtin_candidate_count"]
@@ -187,11 +216,7 @@ async def _dump(call: ServiceCall) -> ServiceResponse:
                 pretty = json.dumps(state, indent=2, ensure_ascii=False)
             except Exception:  # pragma: no cover
                 pretty = repr(state)
-            _LOGGER.debug(
-                "closest_intent.dump_candidates[%s] full state:\n%s",
-                entry_id,
-                pretty,
-            )
+            _LOGGER.debug("dump_candidates[%s] full state:\n%s", entry_id, pretty)
 
         return {
             "version": VERSION,
@@ -213,6 +238,7 @@ async def _dump(call: ServiceCall) -> ServiceResponse:
             vol.Optional("entry_id"): cv.string,
             vol.Optional("include_builtins", default=False): cv.boolean,
             vol.Optional("run_official", default=False): cv.boolean,
+            vol.Optional("debug_top_candidates", default=False): cv.boolean,
         }
     )
 
@@ -239,16 +265,18 @@ async def _parse(call: ServiceCall) -> ServiceResponse:
             data["sentence"],
             run_official=data["run_official"],
             include_builtins=data["include_builtins"],
+            debug_top_candidates=data["debug_top_candidates"],
         )
         result["entry_id"] = entry_id
         _LOGGER.info(
-            "closest_intent.parse[%s][%s] %r -> matched=%s intent=%s canonical=%r",
+            "parse[%s][%s] %r -> matched=%s intent=%s canonical=%r [%.1fms]",
             entry_id,
             language,
             data["sentence"],
             result.get("matched"),
             result.get("intent"),
             result.get("canonical"),
+            (result.get("pools") or {}).get("match_ms", 0.0),
         )
         return result