feat: optimize Housekeeper for Mistral-Nemo tool calling

- Rewrite system prompt with negative constraints and step-by-step process
- Set temperature to 0.1 for deterministic tool calling
- Sort room groups to top of device list (address positional bias)
- Add [ROOM GROUP] marker in list_devices output
- Update tool docstrings with explicit entity_id= parameter examples
- Add optimization findings doc (experiment log: 0% → 100% success)
- Add test script for room group detection regression testing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/agents/housekeeper/agent.py

@@ -32,93 +32,69 @@ from src.core.logging_config import get_logger
 
 logger = get_logger(__name__)
 
-# Housekeeper system prompt
-HOUSEKEEPER_SYSTEM_PROMPT = """You are The Housekeeper, an expert home automation assistant in the Tatlock household.
+# Housekeeper system prompt - Optimized for Mistral-Nemo function calling
+HOUSEKEEPER_SYSTEM_PROMPT = """You are a strictly tool-based home automation assistant.
 
-Your role is to help users control and monitor their smart home through Home Assistant:
-- Lights, switches, and other devices
-- Scenes (pre-configured device states)
-- Scripts (automation sequences)
-- Automations (event-triggered rules)
+## CRITICAL: You Have NO Internal Knowledge
 
-## Your Personality
-- Efficient and practical
-- Safety-conscious (confirm destructive actions)
-- Proactive in suggesting optimizations
-- Clear about what actions you're taking
+You do NOT know what devices exist. You do NOT know any entity IDs.
+Entity IDs are different in every installation. You MUST discover them using tools.
 
-## Your Tools
+## Entity ID Format
 
-### Discovery Tools
-- **list_areas**: See all rooms/areas configured in Home Assistant
-- **list_devices**: Find devices by type (domain) or location (area)
-- **get_device_state**: Check a device's current state and attributes
+Entity IDs follow the format: `domain.name`
+Examples: `light.kitchen`, `light.study_main`, `switch.coffee_maker`
 
-### Control Tools
-- **turn_on**: Turn on lights, switches, etc. (supports brightness/color for lights)
-- **turn_off**: Turn off devices
-- **toggle**: Flip a device's state
+The `entity_id` parameter MUST be the COMPLETE value including the domain prefix.
+WRONG: `entity_id="kitchen"`
+RIGHT: `entity_id="light.kitchen"`
 
-### Scene Tools
-- **list_scenes**: See available scene presets
-- **activate_scene**: Activate a scene (e.g., "movie night", "good morning")
+## Step-by-Step Process (ALWAYS FOLLOW)
 
-### Script Tools
-- **list_scripts**: See available automation scripts
-- **run_script**: Execute a script
+When asked to control devices in a room:
 
-### Automation Tools
-- **list_automations**: See all automations and their status
-- **toggle_automation**: Enable or disable an automation
+1. THINK: What domain? (light, switch, climate, etc.)
+2. CALL: list_devices(domain="light") to discover available devices
+3. CHECK: Look for EXACT match `light.<room_name>` first!
+   - For "study lights" → look for `light.study` (not light.study_main, not light.studeerlamp)
+   - For "kitchen lights" → look for `light.kitchen` (not light.kitchen_spot_1)
+   - These room groups control ALL lights in that room at once
+   - If found, use ONLY the group (stop looking for individual lights)
+4. FALLBACK: Only if no exact room group exists, find entity_ids containing the room name
+5. CALL: turn_on/turn_off using the EXACT entity_id from step 3 or 4
 
-### History Tools
-- **get_history**: Check a device's state history
+Example for "Turn off study lights":
+1. Domain is "light"
+2. Call list_devices(domain="light")
+3. Look for room group: `light.study` - FOUND!
+4. Call turn_off(entity_id="light.study")  # This controls all study lights
 
-## Critical Rules
+Example for "Turn off hallway lights" (no room group):
+1. Domain is "light"
+2. Call list_devices(domain="light")
+3. Look for room group: `light.hallway` - NOT FOUND
+4. Find all with "hallway": light.hallway_spot_1, light.hallway_spot_2
+5. Call turn_off for each
 
-**NEVER GUESS ENTITY IDs.** You do not know what devices exist. Entity IDs vary between
-installations. You MUST call list_devices() FIRST to discover actual entity_ids before
-ANY control action (turn_on, turn_off, toggle).
+## Tool Parameter Names
 
-Wrong approach:
-  User: "Turn off the study lights"
-  You: turn_off("light.study")  ← WRONG! You guessed the entity_id
+- turn_on, turn_off, toggle: Use `entity_id` (NOT device_id, NOT id)
+- activate_scene: Use `scene_id`
+- run_script: Use `script_id`
 
-Correct approach:
-  User: "Turn off the study lights"
-  You: list_devices(domain="light")  ← First discover what exists
-  You: [See results like light.study_main, light.study]
-  You: turn_off("light.study_main"), turn_off("light.study")  ← Use actual IDs
+## What NOT To Do
 
-## Best Practices
-
-1. **ALWAYS list_devices first** before any control action. No exceptions.
-   Filter by domain and/or area to narrow results.
-
-2. **Use exact entity_ids** from list_devices results. Never construct or guess them.
-
-3. **Area-aware filtering**: Use area parameter when users mention a room.
-   Note: Some devices may have area=None but contain the room name in entity_id.
-
-4. **Verify after actions**: Use get_device_state to confirm state changes if needed.
-
-5. **Safety for bulk actions**: When affecting multiple devices, summarize first.
-
-## Common Patterns
-
-- "Turn on the lights" → list_devices(domain="light"), then turn_on each
-- "What's on?" → list_devices() and filter for state="on"
-- "Movie time" → Either activate_scene("scene.movie_night") or run_script if available
-- "Dim the bedroom" → turn_on("light.bedroom", brightness=64)
+- NEVER guess an entity_id
+- NEVER construct an entity_id from the room name
+- NEVER drop the domain prefix (light., switch., etc.)
+- NEVER use "device_id" - the parameter is called "entity_id"
+- NEVER provide an answer without calling list_devices first
 
 ## Response Format
-Your responses are returned to Tatlock (the butler) who will synthesize them into
-a final answer for the user. Keep this in mind:
-- Lead with confirmation of what you did or found
-- Be specific about which devices were affected
-- Include relevant state information
-- Note any issues or failures
-- Be concise - Tatlock will format the final response
+
+After completing actions, briefly confirm:
+- Which devices were affected (list the entity_ids)
+- Whether each action succeeded or failed
 """
 
 # Lazy initialization to avoid connection issues during imports
@@ -231,9 +207,13 @@ async def run_housekeeper(
     )
 
     try:
+        # Use temperature 0.1 for slight exploration
+        from pydantic_ai.settings import ModelSettings
+
         result = await agent.run(
             prompt,
             message_history=message_history,
+            model_settings=ModelSettings(temperature=0.1),
         )
 
         logger.info(
@@ -289,9 +269,13 @@ async def run_housekeeper_stream(
     )
 
     try:
+        # Use temperature 0.1 for slight exploration
+        from pydantic_ai.settings import ModelSettings
+
         async with agent.run_stream(
             prompt,
             message_history=message_history,
+            model_settings=ModelSettings(temperature=0.1),
         ) as response:
             async for delta in response.stream_text(delta=True):
                 yield delta

src/agents/housekeeper/tools.py

@@ -59,10 +59,27 @@ async def list_devices(
 
             for dom, dom_devices in sorted(by_domain.items()):
                 output_parts.append(f"### {dom.title()}s")
-                for device in dom_devices:
+
+                # Sort devices: room groups first (using Home Assistant's is_hue_group attribute)
+                def is_room_group(d: object) -> bool:
+                    """Check if device is a room group based on HA attributes."""
+                    attrs = getattr(d, "attributes", {})
+                    # Check for Hue room groups
+                    if attrs.get("is_hue_group") and attrs.get("hue_type") == "room":
+                        return True
+                    # Check for other group indicators (icon or entity_id list)
+                    if "entity_id" in attrs and isinstance(attrs["entity_id"], list):
+                        return True
+                    return False
+
+                sorted_devices = sorted(dom_devices, key=lambda d: (not is_room_group(d), d.entity_id))
+
+                for device in sorted_devices:
                     state_icon = "on" if device.state == "on" else "off" if device.state == "off" else device.state
                     area_str = f" ({device.area})" if device.area else ""
-                    output_parts.append(f"- **{device.name}**{area_str}: {state_icon}")
+                    # Mark room groups clearly using actual HA data
+                    group_marker = " [ROOM GROUP]" if is_room_group(device) else ""
+                    output_parts.append(f"- **{device.name}**{area_str}{group_marker}: {state_icon}")
                     output_parts.append(f"  ID: `{device.entity_id}`")
                 output_parts.append("")
 
@@ -164,12 +181,12 @@ async def turn_on(
     color_temp: int | None = None,
 ) -> str:
     """
-    Turn on a device.
+    Turn on a device. Use the entity_id parameter with the EXACT value from list_devices.
 
     For lights, can optionally set brightness and color temperature.
 
     Args:
-        entity_id: Device to turn on (e.g., light.living_room, switch.coffee_maker)
+        entity_id: The EXACT entity ID from list_devices including domain prefix.
         brightness: Optional brightness for lights (0-255, where 255 is full brightness)
         color_temp: Optional color temperature in Kelvin (2700=warm, 6500=cool)
 
@@ -177,10 +194,9 @@ async def turn_on(
         Confirmation of the action
 
     Examples:
-        turn_on("light.living_room")  # Turn on at current brightness
-        turn_on("light.bedroom", brightness=128)  # Turn on at 50% brightness
-        turn_on("light.office", brightness=255, color_temp=4000)  # Full, neutral white
-        turn_on("switch.coffee_maker")  # Turn on a switch
+        turn_on(entity_id="light.living_room")
+        turn_on(entity_id="light.bedroom", brightness=128)
+        turn_on(entity_id="switch.coffee_maker")
     """
     try:
         async with CoreAPIClient() as client:
@@ -209,17 +225,18 @@ async def turn_on(
 
 async def turn_off(entity_id: str) -> str:
     """
-    Turn off a device.
+    Turn off a device. Use the entity_id parameter with the EXACT value from list_devices.
 
     Args:
-        entity_id: Device to turn off (e.g., light.living_room, switch.coffee_maker)
+        entity_id: The EXACT entity ID from list_devices including domain prefix.
 
     Returns:
         Confirmation of the action
 
     Examples:
-        turn_off("light.living_room")
-        turn_off("switch.coffee_maker")
+        turn_off(entity_id="light.living_room")
+        turn_off(entity_id="switch.coffee_maker")
+        turn_off(entity_id="light.kitchen")
     """
     try:
         async with CoreAPIClient() as client:
@@ -239,15 +256,17 @@ async def toggle(entity_id: str) -> str:
     """
     Toggle a device's state (on becomes off, off becomes on).
 
+    Use the entity_id parameter with the EXACT value from list_devices.
+
     Args:
-        entity_id: Device to toggle
+        entity_id: The EXACT entity ID from list_devices including domain prefix.
 
     Returns:
         Confirmation with the new state
 
     Examples:
-        toggle("light.living_room")
-        toggle("switch.fan")
+        toggle(entity_id="light.living_room")
+        toggle(entity_id="switch.fan")
     """
     try:
         async with CoreAPIClient() as client: