fix: triage all 10 ha_search_entities behaviors from #1170

[kingpanther13]

What does this PR do?

Triage and fix every one of the 10 behaviors in ha_search_entities documented in #1170. Each finding is addressed with a targeted change plus regression tests; the alias work also closes #1166.

The 10 findings

#	Finding	Resolution
1	domain_filter is case-sensitive (silent zero on Light)	normalize to .strip().lower() at both the tool and service-layer boundaries (and BEFORE the at-least-one-set validation, so a whitespace-only filter fails validation instead of falling through); the response echoes the canonical value
2	bedlight ties light.bed_light against five unrelated *_lights at score 76	per-entity, the entity_id tail and friendly_name now contribute their separator-stripped concat as a high-IDF BM25 token
3	area_only results miss score + match_type; essential_attributes only on fuzzy_search	add score=100, match_type="area_match" so the shape matches the other four search-type branches; drop essential_attributes from fuzzy_search for full shape parity
4	area_filtered_query echoes area_filter per-result (asymmetric)	drop the redundant per-result echo (top-level area_filter still present)
5	Threshold lets xyz_irrelevant_garbage → cover.garage_door at score 92; lit surfaces 186 *_lite* entities at 85	multi-token coverage gate (≥50% of distinct tokens must fuzzy-match a doc token) + single-token min-length gate (≥4 chars) in typo_fallback. Legitimate typos like ligth (5 chars) unaffected
6	_partial_results_search returned a useless score-0 entity dump	deleted; exceptions propagate so callers see the real cause instead of partial: true noise
7	area_only returns the first matched area only (and from a set, so non-deterministic)	aggregate all matched areas in deterministic order; new area_names: list[str] joins legacy area_name. Exact id/name/alias matches short-circuit fuzzy aggregation so a literal area_id no longer leaks sibling areas' entities
8	Entity / area aliases not searchable	fold entity_registry.aliases into the BM25 corpus via a single batched get_entries call; consult area_registry.aliases in the area resolver. Closes #1166.
9	Hidden entities (hidden_by) outrank visible peers under identical match conditions	option (c) from the issue: hidden entities still surface, but receive a 20-point score penalty so visible matches sort above them. New include_hidden: bool = True parameter is the explicit opt-out for filtering them entirely
10	E2E coverage gap on populated areas	new TestSearchEntitiesSeededAreasIssue1170 test class against the tests/initial_test_state seed

Implementation notes

• Concat-token elision (fix: documentation formatting and accuracy improvements #2): the new _strip_separators helper exposes elided forms (bed_light → bedlight) as BM25 tokens. Single-token queries that omit separators now hit a unique high-IDF token directly instead of falling through to typo_fallback's tie-cluster.
• Coverage gate + single-token gate (docs: fix typos and formatting in README #5): in _typo_fallback, multi-token queries must have ≥50% of their distinct tokens fuzzy-match some doc token. Garbage queries with one accidental hit (garbage~garage) are rejected. Single-token queries shorter than 4 chars also skip the fallback ("lit" no longer surfaces every *_lite* entity at score 85); legitimate typos like "ligth" are unaffected.
• Aliases plumbing (feat: add detail_level parameter to ha_get_overview with 4 levels #8): the slim config/entity_registry/list deliberately omits aliases — we now batch-fetch via config/entity_registry/get_entries after the hidden filter, so the extra round-trip stays bounded by the post-filter survivor set. Same approach in get_entities_by_area for area-resolved entities. Alias-driven matches surface as match_type="alias_match".
• Aggregate areas + exact-id short-circuit (feat: update repository references to homeassistant-ai/ha-mcp #7): the area_only branch was using next(iter(area_result["areas"].values())) against a set upstream — non-deterministic AND lossy. Now sorts by area_id and iterates all. area_names: list[str] is the new field; area_name (singular) is retained as the first match for one minor version of soft-compat. Exact id/name/alias matches now short-circuit fuzzy aggregation: area_filter="bedroom_kids" no longer fuzzy-matches its parent "bedroom" (partial_ratio=100) and aggregates sibling areas' entities.
• Hidden-score penalty (feat: add backup creation and restore tools #9): new apply_hidden_penalty(score, hidden_by) helper in fuzzy_search.py subtracts a 20-point penalty whenever hidden_by is non-None. Wired through every branch that emits a score field — BM25, typo_fallback, exact_match, area_only, area_filtered_query, domain_listing — so the contract is uniform: a hidden exact-id match (raw 100 → 80) still ranks above a fuzzy threshold-floor visible match (60-70), but loses to any visible entity scoring 80+. The threshold gate runs on the raw score so a borderline hidden match doesn't silently disappear. include_hidden=False retains the explicit opt-out for callers that need visible-only results.
• Error propagation (refactor: split ha_manage_* into ha_config_{get,set,remove}_* tools #6): the fuzzy fallback wrapper now has an except ToolError: raise guard, so structured failures from smart_entity_search propagate instead of being retried via the substring fallback. Alias-enrichment warnings carry a structured alias_enrichment_failed prefix and the survivor count for log bucketing.
• CancelledError propagation: asyncio.gather(return_exceptions=True) captures asyncio.CancelledError like any other exception. Three call sites (smart_entity_search, _exact_match_search, the empty-query+domain branch) now explicitly re-raise it so the canceller doesn't wait forever.
• Sort tie-breaker: all four score-only sort sites (fuzzy_search main path, _exact_match_search, area_only, domain_listing) now tie-break on entity_id for stable pagination — the hidden-penalty banding (visible@100, hidden@80) made the within-tier reordering particularly likely without the secondary key.
• Validation-order fix: domain_filter / area_filter strip+lowercase now happens BEFORE the at-least-one-set validation. Previously a whitespace-only filter (" ") passed validation truthy then collapsed to "" and fell through to a silent zero-result fuzzy search.
• Validation error suggestions: ValueError from coerce_bool_param / coerce_int_param is now caught separately and surfaced via create_validation_error with the helper's own message and no boilerplate operational suggestions (previously limit=0 returned "Check Home Assistant connection" next to "limit must be at least 1, got 0").
• Internal-field strip helpers: strip_internal_fields (recursive, mutating, cycle-guarded) and public_fields (shallow, non-mutating) in tools/util_helpers.py centralise the leading-underscore convention so _hidden_by / _aliases enrichments don't leak through public tool returns. server.py:get_entities_by_area bridge now strips its delegate's output.
• Zero-overlap message (area+domain): when area_filter resolves to populated areas but domain_filter wipes out every entity, the response now carries "No <domain> entities found in area: <area>" — previously the empty-area branch had a message but the populated-but-domain-filtered-empty branch was silent.

Public API impact

• Adds: include_hidden parameter (default True); area_names: list[str] on area_only; match_type="alias_match" result value.
• Shape changes (compatible upgrades for the 4 affected branches):
  • area_only results now include score + match_type (fix: resolve GitHub Action semantic-release configuration issues #3).
  • area_filtered_query no longer emits area_filter per-result (top-level still present) (Potential fix for code scanning alert no. 1: Workflow does not contain permissions #4).
  • search_type="partial_listing" no longer returned (refactor: split ha_manage_* into ha_config_{get,set,remove}_* tools #6) — failures now surface as ToolError instead of a zero-scored entity dump.
  • fuzzy_search no longer emits essential_attributes (matches the other four branches' shape).
  • domain_filter is .strip().lower() normalized before matching, and echoed in normalized form (ci(deps): bump python-semantic-release/python-semantic-release from 9.10.0 to 10.4.1 in the actions group #1).
• Score change (feat: add backup creation and restore tools #9): hidden entities (hidden_by != null) now sort below comparable visible matches due to a 20-point score penalty. Default-True include_hidden keeps them in results — set include_hidden=False for the visible-only behavior. No callers have a smaller result set than before unless they explicitly opt out.

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Test additions:

• TestFuzzySearcherIssue1170 in tests/src/unit/test_bm25_search.py: concat-token elision, multi-token coverage gate, alias-match labeling, single-token typo recall, alias-vs-name precedence, short single-token min-length gate ("lit" returns empty; "ligth" still recalls).
• TestSmartEntitySearchPropagation — locks down the finding-6 contract that get_states failures surface as ToolError.
• TestHiddenScorePenalty — locks down the option-(c) ranking contract: helper math, visible-vs-hidden ordering on shared queries, zero-clamp boundary, threshold-on-raw-score edge case (raw-100 hidden surfaces at score 80 even when threshold=100), typo_fallback penalty, CancelledError propagation, sort tie-breaker ordering.
• TestStripInternalFields and TestPublicFields in tests/src/unit/test_util_helpers_internal_strip.py — full coverage of the leak-guard helpers (recursion, cycles, non-string keys, mutation semantics, shallow-copy contract).
• TestExactMatchSearchCancelledPropagation in test_search_fallback.py — _exact_match_search re-raises CancelledError from the registry task.
• tests/src/unit/test_server_bridge_strip.py — server.py:get_entities_by_area bridge actually invokes strip_internal_fields.
• E2E regression tests in tests/src/e2e/tools/test_search_entities.py: one per runtime-observable finding, plus area-alias resolution, concat-token elision through the full pipeline, area_filtered_query + hidden penalty, domain_listing + hidden penalty, determinism of area_names ordering, exact area_id short-circuits fuzzy aggregation, shape consistency across all 5 search_types, validation error has no generic suggestions, area+domain zero-overlap message, parametrised whitespace test for domain_filter (5 variants), whitespace-only filter rejected at validation, hidden-with-penalty / include_hidden=False pair across substring + fuzzy + area_only branches.
• TestSearchEntitiesSeededAreasIssue1170 class with 3 test methods exercising area_filter branches at realistic seeded-area populations (feat: Docker deployment and Home Assistant add-on support #10).
• Existing unit tests in test_search_fallback.py rewritten for option (c) — assert hidden entities are present with reduced score, and assert include_hidden=False filters them out.
• seeded_bedroom fixture wrapped in try/finally so a fixture-body failure (or pytest.skip) doesn't leak the seed area assignments.

Test updates:

• valid_search_types in the response-structure regression test no longer accepts the deleted partial_listing.
• test_search_fallback.py and test_search_pagination.py updated to drop references to the deleted _partial_results_search.

Future improvements

None tracked — every triage item from #1170, plus all findings surfaced during live stress testing on a real HA instance, is addressed in this PR.

Checklist

• I have updated documentation if needed (tool docstrings refreshed inline; no public docs needed updating)

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses 10 specific behavioral findings in the ha_search_entities tool, significantly improving search accuracy, API consistency, and the handling of hidden entities. It introduces robust filtering, better alias support, and cleaner fallback mechanisms, while also expanding E2E test coverage to ensure future stability.

Highlights

• Search Accuracy & Robustness: Implemented concat-token elision and a multi-token coverage gate in typo_fallback to reduce false positives and improve search relevance.
• Hidden Entity Filtering: Added an include_hidden parameter to search tools to filter out entities marked as hidden in the registry by default.
• Alias Support: Integrated entity and area registry aliases into the search corpus, enabling more flexible entity discovery.
• API Cleanup: Standardized result shapes across search branches and removed the deprecated _partial_results_search fallback.
• Area Search Improvements: Fixed non-deterministic area aggregation and added support for multi-area matching in area_only searches.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request enhances the entity search system by introducing support for hidden entities and aliases, normalizing domain filters, and improving area-based matching. Key updates include parallelizing registry fetches, implementing a multi-token coverage gate in fuzzy matching to reduce noise, and removing the legacy partial results fallback. Review feedback focuses on ensuring that docstrings for both public tools and internal helpers start with approved action verbs to maintain consistency with project documentation standards.

[kingpanther13]

/Gemini review

[gemini-code-assist]

Code Review

This pull request significantly enhances the search capabilities of the MCP server by implementing alias support for entities and areas, and introducing a score-penalty system for hidden entities. It also fixes a bug where area searches only returned results from a single matched area and improves the typo-fallback logic to reduce noise. Feedback from the review focuses on improving the robustness of exception handling for Home Assistant API calls, ensuring docstrings adhere to the project's style guide, and adding secondary sort keys to guarantee deterministic result ordering.

[kingpanther13]

Claude discovere the following things. Claude is being particularly stupid lately, so these might be nonsense, so confirm they are actually legitimate because there's a good chance that they aren't, but if they are then we should probably fix them.

---

1. Exact area_id is treated as fuzzy in area_filter

area_filter="bedroom_kids" (a literal area_id from ha_config_list_areas) still partial-matches the parent bedroom because calculate_partial_ratio("bedroom_kids", "bedroom") == 100, which clears the 80 threshold. Result aggregates both areas' entities.

Repro: assign light.bed_light + switch.ac to bedroom, cover.kitchen_window to bedroom_kids, then area_filter=bedroom_kids → returns all 3 entities, area_names: ["Bedroom", "Bedroom Kids"].

If real: short-circuit when area_query_lower in area_registry (skip fuzzy step on exact id hit) in smart_search.py::get_entities_by_area.

---

2. Single-token sub-word noise in _typo_fallback

The coverage-gate fix from finding 5 is multi-token-only by construction. Single-token queries still surface unrelated entities via SequenceMatcher partial overlap. Original example from the issue: query="lit" → returns todo.shopping_list at score 85.

Repro: ha_search_entities(query="lit", exact_match=False, limit=3) → todo.shopping_list@85, light.bed_light@75, light.ceiling_lights@75.

If real: either raise the typo_fallback threshold for single-token queries (~85), or require min query length ≥ 4 for the fallback to fire, in fuzzy_search.py::_typo_fallback.

---

3. essential_attributes shape asymmetry across branches

Result-shape consistency was the target of finding 3, which closed the score/match_type gap on area_only. But the fuzzy_search branch alone emits an extra essential_attributes dict that the other four branches don't. Either prune from fuzzy or add to the other four.

Repro: compare result_keys of query="bed_light" (exact=true vs false), domain_filter="light", area_filter="bedroom", area_filter="bedroom" + query="light" — only fuzzy has essential_attributes.

If real: decide which way to go, then either drop the field in smart_search.py::smart_entity_search or add it to the other four sites in tools_search.py.

---

4. Misleading suggestion on VALIDATION_FAILED errors

A limit=0 (or any other validation failure) returns code: VALIDATION_FAILED with suggestion: "Check Home Assistant connection" next to a 3-element suggestions array of the same generic text. None of the suggestions relate to the actual validation problem.

Repro: ha_search_entities(query="light", limit=0).

If real: pass an appropriate suggestions list when constructing the validation error, or drop the suggestion field for validation errors entirely. The error originates from exception_to_structured_error defaults in tools_search.py::ha_search_entities.

---

5. area_filter + domain_filter no-overlap returns no message

When area_filter matches areas with entities, but domain_filter filters them all out within those areas, the response is total: 0, count: 0 with no message. The empty-area branch emits "No entities found in area: <area>" for shape parity.

Repro: ha_search_entities(area_filter="bedroom", domain_filter="sensor") when bedroom has only lights/switches/covers assigned → returns total: 0 silently.

If real: emit a parallel "No <domain> entities found in area: <area>" message in the populated-but-domain-filtered path in tools_search.py.

[kingpanther13]

Implementation Summary

Choices Made:

• Option (c) over (b) for finding 9 (hidden entities): the issue's investigation listed three approaches; chose the score-penalty (option c) per user direction. Hidden entities still surface but receive a 20-point penalty so visible matches sort above them. include_hidden=False remains as an explicit opt-out for visible-only callers.
• Action verbs over noun phrases for tool docstrings (Gemini Code Assist flagged "Find or list" → "Search"). Aligned with AGENTS.md approved-verb list.
• Threshold-on-raw-score in BM25 + typo_fallback: the penalty applies AFTER the threshold gate so a borderline hidden match doesn't get silently dropped (would violate the option-c contract).
• Exact area_id short-circuits fuzzy aggregation: when an area_filter value is a literal id/name/alias, sibling areas no longer leak in via partial_ratio. Fuzzy aggregation only runs when no exact match exists.
• Single-token typo_fallback min-length=4: the multi-token coverage gate from finding 5 doesn't help short single-token queries ("lit" matched 186 entities). Added a length gate; typical real typos ("ligth", 5 chars) are unaffected.
• essential_attributes pruned from fuzzy_search rather than added to the other four branches (shape consistency, less payload; callers fetch full state via ha_get_state if needed).
• ValueError from coerce_*_param caught separately so VALIDATION_FAILED errors carry only the helper's message, not boilerplate operational suggestions.
• strip_internal_fields (mutating, recursive, cycle-guarded) + public_fields (shallow, non-mutating) as twin helpers in util_helpers.py. Server.py bridge uses the mutating form; tools_search.py inline comprehensions use the shallow form.

Problems Encountered:

• Stress test against a real HA instance caught domain_filter=" LIGHT " returning silent 0 — the lowercase normalization didn't strip whitespace first. Fixed with .strip().lower() at both the tool entry and the service layer, then moved BEFORE the at-least-one-set validation so a whitespace-only filter fails validation instead of falling through.
• Initial E2E test for area_filtered_query + hidden penalty timed out in CI (entity_id fallback missing + name format meant the prefix-only query couldn't fuzzy-match). Rewrote with a distinctive token in a space-separated name so BM25 hits at score 100.
• server.HomeAssistantSmartMCPServer.smart_tools is a lazy-init property with no setter — bridge test had to set the _smart_tools backing field directly.
• A second-pass review surfaced 5 additional findings (exact area_id treated as fuzzy, single-token typo_fallback noise, essential_attributes shape asymmetry, misleading VALIDATION_FAILED suggestions, silent empty result on area+domain no-overlap). All five verified as legitimate against live HA and fixed.

[Patch76]

Triage-comprehensive coverage of #1170 — all 10 findings closed, plus the alias work folding in #1166.

Verified G4/G6 dismissals: client.send_websocket_message (rest_client.py:1101-1129) catches except Exception broadly and returns a {success, error} dict, so HomeAssistantConnectionError / HomeAssistantAPIError / TimeoutError / OSError don't propagate to either alias-enrichment site. The narrow (KeyError, TypeError, AttributeError) catch correctly scopes to malformed-but-success payloads; transport failures hit the explicit non-success else branch that logs alias_enrichment_failed: with the survivor count. Reasoning checks out.

Backwards-compat on Finding 7: tools_search.py:494-503 emits both area_names: list[str] (new) and area_name: str (legacy, first match by sorted area_id), with the soft-deprecation flagged in-line. Not breaking per the styleguide's return-restructuring rule.

Test envelope: +1839 net test lines — one E2E file (test_search_entities.py), two new unit files (test_server_bridge_strip.py, test_util_helpers_internal_strip.py), a BM25 expansion (test_bm25_search.py, +462 net), plus rewrites of test_search_fallback and test_search_pagination. Both new helpers (strip_internal_fields + public_fields) ship with dedicated unit coverage.

[Patch76]

LGTM

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.