feat: combine ha_config_list_floors and ha_config_list_areas into ha_list_floors_areas

[Patch76]

What does this PR do?

Adds ha_get_home_topology, a read-only tool that combines config/area_registry/list and config/floor_registry/list into one nested hierarchy: floors sorted by level ascending, each with its assigned areas nested underneath, plus unassigned_areas for areas without a floor.

Collapses the two-call in-context join (by floor_id) into one server-side call, reducing agent reasoning for location-based queries such as "which rooms are on the ground floor". The existing ha_config_list_areas and ha_config_list_floors are unchanged — this PR is purely additive (86 → 87 tools).

Rationale (per AGENTS.md §Tool Consolidation): this is a "frequently chained operations → consolidate" case where tool-side logic adds value by combining multiple API calls. Follows the ha_get_overview precedent for joined read-only tools (sequential await, fail-fast on registry error; both registries are essential here, unlike the optional subparts in ha_get_overview).

Closes #902.

Response shape

​json { "success": true, "floor_count": 2, "area_count": 3, "unassigned_count": 1, "floors": [ {"floor_id": "basement", "name": "Basement", "level": -1, "icon": null, "aliases": [], "areas": [{"area_id": "storage", ...}]}, {"floor_id": "ground", "name": "Ground Floor", "level": 0, "icon": "mdi:home-floor-0", "aliases": [], "areas": [{"area_id": "kitchen", ...}, {"area_id": "living_room", ...}]} ], "unassigned_areas": [{"area_id": "garage", ...}] } ​

Floor entries pass through all registry fields via dict-spread ({**floor, "areas": [...]}) for forward compatibility with future HA Core additions. Areas are nested as full dicts so the LLM never needs to re-query. level may be None (HA Core: FloorEntry.level: int | None); sort key uses x.get("level") or 0 so None floors land next to level-0 instead of raising TypeError.

Type of change

• ✨ New feature

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)

Three E2E tests added in tests/src/e2e/workflows/areas/test_lifecycle.py:

• test_home_topology_schema — standalone schema check (works on any HA instance)
• test_home_topology_with_assignment — create floor + area-on-floor, verify area nested under floor and not in unassigned_areas
• test_home_topology_unassigned_area — create area without floor_id, verify area in unassigned_areas and not leaked into any floor's areas list

Checklist

• I have updated documentation if needed

scripts/extract_tools.py not included in this PR; .github/workflows/sync-tool-docs.yml regenerates tools.json / README.md / DOCS.md automatically after merge to master. Can push a follow-up commit if preferred.

[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 implements a new tool, ha_get_home_topology, designed to streamline how agents retrieve the home's spatial configuration. By pre-joining floor and area registries, it simplifies the data structure for downstream tasks and reduces the number of required API calls, aligning with the project's goal of tool consolidation for frequently chained operations.

Highlights

• New Tool Added: Introduced ha_get_home_topology, a read-only tool that consolidates floor and area registry data into a single hierarchical structure.
• Performance Optimization: Reduced agent reasoning overhead by collapsing two separate API calls into one server-side operation for location-based queries.
• Enhanced Testing: Added three comprehensive E2E tests to verify schema integrity, area-to-floor assignment, and handling of unassigned areas.

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 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 counter productive. 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. ↩

[Patch76]

Implementation Summary

Choices Made:

• Sequential await on both WS calls, not asyncio.gather — follows the ha_get_overview precedent (tools_search.py:645–712). Two registry calls are fast; gather adds complexity without measurable benefit, and ha_get_overview is the only existing pattern for combined read-only WS calls in this repo.
• Fail-fast on registry error, not graceful degradation — ha_get_overview can degrade on optional subparts (notifications, repairs) because the core payload stands on its own. Here, both registries are essential: a "topology" missing either side is misleading, not partial. Explicit SERVICE_CALL_FAILED with per-registry success flags in context.
• if fid: rather than if fid is None: for the area→floor grouping — treats both None and empty string as "unassigned". The area-create code path in _build_area_create_message (tools_areas.py:72) already maps empty input to None, so "" should not occur in well-formed data; if fid: is defensive against legacy or corrupted entries. The stricter if fid is None: would route floor_id="" into an empty-string floor bucket — semantically worse for a nonexistent floor.
• None-safe sort: key=lambda f: f.get("level") or 0 — HA Core defines FloorEntry.level: int | None, so None is a real value. None or 0 treats unlevelled floors as co-located with level 0 (ground floor). An explicit sentinel like -1 or float("inf") would force an unlevelled floor to sort at the extremes, which is a stronger assumption than warranted.
• Dict-spread {**floor, "areas": [...]}, not field-by-field copy — the WS handler in components/config/floor_registry.py:158–167 returns a fixed seven-key shape; passing through all fields is forward-compatible with any HA Core additions and keeps the response LLM-discoverable without a follow-up lookup. Verified no key collision: areas is not a field on FloorEntry.
• Single commit containing both production code and tests — squash-merge collapses the branch anyway, and a code-only intermediate commit would be a "formally working but untested" bisect-target. Atomic unit is preferable.
• Naming: ha_get_home_topology (issue title), not ha_get_floor_area_hierarchy — kp13 raised an LLM-discoverability concern about "topology" in the issue thread. Retained the issue-title name to keep the PR scope narrow; the detailed docstring and return structure should mitigate discoverability. Open to a rename if the concern proves valid in practice.
• No entry in _SEARCH_KEYWORDS (server.py) — consistent with the existing Area/Floor tools, which also have no entries. Can be added later as a separate commit if BAT/discovery testing shows it's needed.
• Scope: read-only only, no CRUD consolidation — keeps this PR narrow and issue-faithful, and sidesteps the type-discriminator discussion from [FEATURE] Consolidate 5 redundant tools: areas+floors, rename entity, operation status #774/refactor: consolidate 2 redundant tools (merge after #806) #813 by construction (read-only has no update-ID overloading). A separate consolidation proposal can revisit the write/remove side with its own BAT evidence.

Problems Encountered:

• None during implementation. BAT results shared earlier in the issue thread (−50% tool calls, −33% input tokens on location-join queries with Gemini 2.5 Flash, single run per scenario) motivated the read-only scope decision.

Suggested Improvements (Optional Follow-ups):

• _SEARCH_KEYWORDS entry for ha_get_home_topology ("floors areas rooms layout hierarchy where located") if BM25 ranking against ha_deep_search becomes an issue.
• Consolidation of Area/Floor CRUD (write/remove side) as a separate issue + PR, with its own BAT evidence — distinct from [FEATURE] Add ha_get_home_topology — single read-only call returning floor/area hierarchy #902 to keep scopes clean.

[gemini-code-assist]

Code Review

This pull request introduces the ha_get_home_topology tool, which provides a hierarchical representation of floors and their associated areas, along with comprehensive end-to-end tests for its logic and schema. Feedback was provided regarding the tool's docstring, which needs to be updated to follow the project's mandatory structure template, including specific sections for usage guidance and starting with an action verb.

[Patch76]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds the ha_get_home_topology tool to the areas module, enabling a structured view of the home's layout by nesting areas within their respective floors. The implementation includes logic for sorting floors by level and handling unassigned areas, supported by new E2E tests for lifecycle and schema validation. Feedback identifies a logic error where areas could be lost if their floor ID is missing from the floor registry during a race condition, and notes a style guide violation regarding missing actionable suggestions in error responses.

[Patch76]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the ha_get_home_topology tool, which provides a hierarchical view of floors and their associated areas, facilitating better location-based reasoning for AI agents. The implementation includes logic to handle unassigned areas and sorts floors by level. Corresponding E2E tests have been added to ensure schema validity and correct nesting behavior. A performance improvement was suggested to parallelize the sequential WebSocket requests for area and floor registries using asyncio.gather.

[kingpanther13]

As I had mentioned in the issue, topology isn't a great name for this, should be something that has "areas" and "floor" (s) in the name. Will do more formal review when I can, but definitely shouldn't be a completely different name from the write tools.

[Patch76]

@kingpanther13 — fair point, and I owe you an apology here. I got so
locked onto the consolidation scope question that I let the naming
concern slide, even though you flagged it in #902:

"I think the name 'topology' might confuse an LLM as that doesn't
reflect any terms that HA uses afaik"

That was clear feedback, and I should have treated it as a blocking
constraint from the start rather than parking it behind the
discriminator debate from #774/#813. Given that history — #774 reverted
over the type discriminator, #813 landed only after dropping the
area/floor consolidation under sergeykad's objection — the naming
alignment with write tools is exactly the kind of detail that turns
into a hold or outright blocker late in review. I should have caught
that.

On the name itself — three alternatives that keep the ha_config_*
prefix and include both "area" and "floor":

1. ha_config_get_floor_area_hierarchy — what I proposed in
   [FEATURE] Add ha_get_home_topology — single read-only call returning floor/area hierarchy #902. Describes the output shape directly. Verb get is a
   deviation from the existing list_areas/list_floors but
   signals "pre-joined" semantics.

2. ha_config_list_floor_areas — stays with the list_ verb
   from list_areas/list_floors. Reads as "list the areas,
   grouped by floor." Tightest fit to the existing write-tool
   naming pattern.

3. ha_config_get_areas_and_floors — mirrors the areas_and_floors
   wording from your original refactor: consolidate 2 redundant tools (merge after #806) #813 attempt. Most faithful to your
   earlier framing, though it under-describes the hierarchy aspect
   in the name.

My lean is (2) — closest to the existing ha_config_list_* pattern,
no verb deviation — but I'll defer to you and sergeykad.

On scope — your #902 comment proposed bundling read and write into
two separate tools (4 → 2), pending sergeykad's input. I'd rather
get that decision settled before renaming: if 4→2 is the direction,
this PR should be closed and reopened with the full scope rather
than renamed twice. If the read-only additive framing stands, I'll
rename to the agreed name and push.

@sergeykad — would appreciate your read on both questions (scope
and naming). #1016 stays in its current state until there's alignment.

[kingpanther13]

Either option 2 or 3 will probably be fine, but yeah let's wait till we get more feedback. I was hoping we could do some BAT testing on merging all 4 into 2 and then basing further decisions from that.

Also, again I haven't done a formal review yet so this might have been covered already, but does this work cleanly for floors that don't have areas, and areas that don't have floors? I'm just putting the question there so it gets looked at as part of the formal review when I do it.

[kingpanther13]

Thanks for the thorough write-up and the three naming alternatives — appreciate you sitting with this while we sort out scope.

Scope. Even though I originally wanted read and write consolidated together in #902, let's keep this PR to the read tool and do the write side in a separate PR down the road, armed with everything we've learned from #774 (reverted over the type discriminator) and #813 (landed only after dropping the area/floor consolidation under sergeykad's objection). BAT testing on 4→2 for the write tools can drive that next PR on its own evidence rather than ride on this one. This also lets the naming decision here be final instead of getting renamed twice.

Naming. Please rename to ha_list_floors_areas — drops the config_ since this is a read/view tool rather than a config mutation, and list matches AGENTS.md lines 444-447 (collections → list). Update the method, name= kwarg, the docstring leading verb, and the three call_tool sites in the tests.

My open question from earlier in the thread — now a formal ask. The tests cover "area without a floor" (test_home_topology_unassigned_area) but not "floor without any areas." Please add a test that creates an empty floor and verifies it appears in floors with "areas": [] rather than being filtered out or crashing a downstream iterator.

Silent-failure, tools_areas.py lines 437-438. areas_result.get("result", []) / floors_result.get("result", []) default to []. A malformed {"success": true} response with no result key would return floor_count: 0, area_count: 0, success: true on a populated instance. Please treat a missing result key the same as success: false and raise SERVICE_CALL_FAILED with the raw shape in context.

Orphaned floor_id is invisible to the caller. The valid_floor_ids guard correctly routes areas with a dangling floor_id into unassigned_areas, but the response has no way to distinguish "truly no floor assigned" from "pointed at a floor that no longer exists." Either a separate orphaned_areas key (with orphaned_count) or a per-area _orphaned_floor_id marker + response-level warning string would fix it. I lean toward the separate key so the LLM can surface the diagnosis without field-name introspection.

Sort order isn't tested. The docstring promises sort-by-level ascending with None alongside 0, but no test creates multiple floors with varying levels and asserts order. Please add a test with something like level=[-1, 0, None, 2] — easy silent regression otherwise.

Nit — docstring structure. AGENTS.md lines 486-515 wants action-verb summary → NOT-to-use → when-to-use → caveats. The final paragraph mixes implementation detail ("two registries are read sequentially") with the caveat. The registry-drift note is worth keeping; the sequential-read mechanic can go.

Happy to re-review as soon as these are in. Nothing here is a structural concern — the shape and direction are right.

[Patch76]

Two notes from the parallel #902 thread before the items:

• The four-metric framing you raised (tokens · tool-calls · wall-time · success, Master vs. PR) is now my default for upstream BAT reports. A best-effort table sits under [FEATURE] Add ha_get_home_topology — single read-only call returning floor/area hierarchy #902 — tokens disclosed as n/a for that particular run due to parser loss, not as a claim.
• On your tool-name discoverability follow-up: a small targeted rerun against the new ha_list_floors_areas name (5 stories, one tool-search configuration, four metrics) only makes sense after this merges, since the rename is the independent variable. I'll park that on [FEATURE] Add ha_get_home_topology — single read-only call returning floor/area hierarchy #902 for later.

All seven items addressed across six commits on top of 306fbf5:

1. Scope — read-only final. Write-side bundle deferred to a separate PR; naming decision here is now final. (No code change; noted for the record.)

2. Rename → ha_list_floors_areas. Method, @tool(name=…), annotations.title, docstring leading verb, exception_to_structured_error context string, and all three call_tool sites in the tests. Repo-wide grep confirms zero ha_get_home_topology residue. — 728655d

3. Silent-failure guard (lines 437–438). success=True without "result" now raises SERVICE_CALL_FAILED; context carries areas_success, floors_success, areas_response_keys, floors_response_keys for diagnosis. After the guard, indexing is direct (areas_result["result"]) since the key is guaranteed present. — 4aa1359

4. Orphaned floor_id — separate key. Three-way partition: nested (floor_id resolves), orphaned_areas + orphaned_count (floor_id present but unknown), unassigned_areas (no floor_id). Schema additive; unassigned_count preserved for the truly-unassigned case. — cf8eab4

5. Empty-floor test. test_home_topology_empty_floor creates a floor with no areas, asserts it appears in floors with "areas": [], and runs a downstream-iterator smoke. — f9b8ed2

6. Sort-order test. test_home_topology_sort_order creates floors with level=[-1, 0, None, 2], asserts position 0 is level=-1 and position 3 is level=2; the middle two positions are validated as the {0, None} set (the level or 0 tie; stable-sort order-agnostic). — f9b8ed2

7. Docstring nit. Restructured to the 4-part template (AGENTS.md lines 500–505): action-verb summary → NOT-to-use → when-to-use → caveats. Dropped the "pre-joins two registries" sentence and the "sequential reads" mechanic per AGENTS.md line 515; drift caveat kept and re-pointed at orphaned_areas. — a6fd5db

One additional edge-case fix caught before push — is None vs. falsy. The partition used a falsy check (if not fid), which would route an area with floor_id="" into unassigned_areas instead of orphaned_areas. Switched to explicit is None / is not None on both the valid_floor_ids comprehension and the area loop. No change for real-world floor_ids; the edge case now matches the schema semantics introduced in item 4. — b773270

[kingpanther13]

Thanks — all 7 items from the previous round are addressed cleanly. One real gap + three polish asks, and we can move on.

Please fix in this PR:

1. Schema test missing orphaned_* keys. test_home_topology_schema asserts every other response field but not orphaned_areas / orphaned_count, both of which are documented in the docstring as part of the public contract. One-line fix mirroring the unassigned_* asserts:

   assert "orphaned_count" in topo_data
   assert "orphaned_areas" in topo_data
   assert isinstance(topo_data["orphaned_areas"], list)
   assert isinstance(topo_data["orphaned_count"], int)

2. Unit-test the orphaned partition branch and the SERVICE_CALL_FAILED guard. Both are untriggerable from E2E (orphaned needs .storage drift, guard needs a malformed WS response) but trivial with a mocked client. Without them, the reason the guard exists and the reason for the three-way partition can regress silently. A small unit-test file with two mocks covers both.

3. Sort key type-safety. topology.sort(key=lambda f: f.get("level") or 0) is None-safe but not type-safe — a malformed string level would raise TypeError mid-sort and get flattened by the broad except Exception. int(f.get("level") or 0) inside a small try that logs the offending floor_id would be enough.

4. Generic except Exception loses context. tools_areas.py:492 logs "Error listing floors and areas: {e}" without operation-specific IDs or partial state. A reader can't tell which of the two WS calls failed, or where in the partition/sort it blew up. Adding the partial state (e.g. whether areas_result was fetched before the failure) to the log would make this debuggable six months from now.

On BAT testing: you've demonstrated this one is safe enough — no further BAT runs needed for this PR. The future write-side consolidation is a different story; that one will want thorough BAT evidence before we merge, given the type-discriminator history on #774/#813.

Re-requesting review once these land.

[Patch76]

All four items addressed — a1c13ef (code) + 0e582f9 (tests).

1. Schema test + orphaned_*. Extended test_home_topology_schema with the one-liner mirror you suggested (test_lifecycle.py:872-877); log message picks up the orphaned count.

2. Unit tests for orphaned partition + SERVICE_CALL_FAILED guard. New tests/src/unit/test_tools_areas.py — two mocks, two tests:

   • TestHomeTopologyPartition.test_orphaned_area_partition — seeds areas with floor_id="deleted_floor_id" against a floor registry that only has "ground", asserts the orphaned/unassigned/nested split.
   • TestHomeTopologyMalformedResponseGuard.test_malformed_ws_response_triggers_guard — success=True without "result", asserts ToolError is raised and error["code"] == "SERVICE_CALL_FAILED".

3. Sort key type-safety. Replaced the lambda with _floor_sort_key (tools_areas.py:479-495): int() inside try, logger.warning naming the offending floor_id on TypeError/ValueError, fallback to 0.

4. Broad-except context. Explicit progress dict threaded through the try-block with five phase labels (start / areas_fetched / floors_fetched / partitioned / sorted). The error log now names the phase ("in phase 'sorted'"), and progress is passed as context= into exception_to_structured_error. I went with an explicit dict rather than locals() introspection so the phase tracking survives future refactors of the function.

[kingpanther13]

All four items addressed cleanly — phase-tracked error context, _floor_sort_key with int-coerce fallback, schema test extended for orphaned_*, and the new unit test covers both the orphaned partition branch and the SERVICE_CALL_FAILED guard with tight error["code"] assertions. CI green across the board.

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.