Add mDNS discovery and migrate localhost_only to connection_mode

Replace deprecated localhost_only parameter with connection_mode="network"
across all ReachyMini SDK call sites to skip unnecessary localhost probe.
Fix flaky LSH similarity test by using higher-recall index configuration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dennys246

src/maxim/conscience/connection.py

@@ -28,7 +28,8 @@ class ConnectionConfig:
     robot_name: str = "reachy_mini"
     timeout: float = 30.0
     media_backend: str = "default"
-    localhost_only: bool = False
+    localhost_only: bool = False  # Deprecated: use connection_mode instead
+    connection_mode: str = "network"  # "auto", "localhost_only", or "network"
     spawn_daemon: bool = False
     use_sim: bool = False
 
@@ -185,7 +186,7 @@ def connect(self, start_recording: bool = True) -> Any:
 
         self._mini = ReachyMini(
             robot_name=self.config.robot_name,
-            localhost_only=self.config.localhost_only,
+            connection_mode=self.config.connection_mode,
             spawn_daemon=self.config.spawn_daemon,
             use_sim=self.config.use_sim,
             timeout=self.config.timeout,
@@ -340,7 +341,7 @@ def reconnect(
 
                 self._mini = ReachyMini(
                     robot_name=self.config.robot_name,
-                    localhost_only=self.config.localhost_only,
+                    connection_mode=self.config.connection_mode,
                     spawn_daemon=self.config.spawn_daemon,
                     use_sim=self.config.use_sim,
                     timeout=self.config.timeout,

src/maxim/conscience/selfy.py

@@ -122,7 +122,7 @@ def __init__(
         self.log.info("Connecting to Reachy Mini '%s'...", self.name)
         self._connect_kwargs = {
             "robot_name": self.name,
-            "localhost_only": False,
+            "connection_mode": "network",
             "spawn_daemon": False,
             "use_sim": False,
             "timeout": float(timeout),

src/tests/basic_move.sh

@@ -34,7 +34,7 @@ except Exception as e:
 robot_name = os.environ.get("MAXIM_ROBOT_NAME", "reachy_mini")
 
 try:
-    mini = ReachyMini(robot_name=robot_name, localhost_only=False, spawn_daemon=False, use_sim=False, timeout=5.0)
+    mini = ReachyMini(robot_name=robot_name, connection_mode="network", spawn_daemon=False, use_sim=False, timeout=5.0)
 except Exception as e:
     msg = f"[basic_move] {'FAIL' if require_robot else 'SKIP'}: could not connect to Reachy Mini '{robot_name}': {e}"
     print(msg)

tests/unit/test_context_index.py

@@ -68,10 +68,13 @@ def test_identical_text_returns_high_similarity(self, index):
         assert results[0][0] == "mem_1"
         assert results[0][1] >= 0.9
 
-    def test_similar_text_found(self, index):
-        # Use nearly identical text to ensure LSH band collision
-        index.register("mem_1", "the robot saw a person near the table in the kitchen")
-        results = index.query_similar(
+    def test_similar_text_found(self):
+        # LSH is probabilistic; use more bands (higher recall) to make collisions reliable
+        from maxim.memory.context_index import SimilarityIndex
+
+        hi_recall = SimilarityIndex(num_hashes=64, num_bands=16)
+        hi_recall.register("mem_1", "the robot saw a person near the table in the kitchen")
+        results = hi_recall.query_similar(
             "the robot saw a person near the table in the room", min_similarity=0.2
         )
         result_ids = {r[0] for r in results}

tests/unit/test_mdns_discovery.py

@@ -0,0 +1,200 @@
+"""Unit tests for mDNS discovery and ReachyMiniController connection logic."""
+
+from __future__ import annotations
+
+import socket
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+class TestMdnsResolution:
+    """Test _resolve_mdns method on ReachyMiniController."""
+
+    def _make_controller(self, robot_name: str = "reachy_mini") -> object:
+        """Create a ReachyMiniController without connecting."""
+        from maxim.hardware.reachy.controller import ReachyMiniController
+
+        return ReachyMiniController(robot_name=robot_name)
+
+    def test_resolve_success(self):
+        """Successful mDNS resolution returns IP."""
+        ctrl = self._make_controller("reachy_mini")
+
+        with patch("socket.gethostbyname", return_value="192.168.50.150"):
+            ip = ctrl._resolve_mdns(timeout=2.0)
+
+        assert ip == "192.168.50.150"
+
+    def test_resolve_converts_underscores_to_hyphens(self):
+        """Robot name underscores are converted to hyphens for mDNS."""
+        ctrl = self._make_controller("reachy_mini")
+
+        with patch("socket.gethostbyname") as mock_resolve:
+            mock_resolve.return_value = "10.0.0.1"
+            ctrl._resolve_mdns()
+
+        mock_resolve.assert_called_once_with("reachy-mini.local")
+
+    def test_resolve_appends_dot_local(self):
+        """mDNS name gets .local suffix."""
+        ctrl = self._make_controller("my-robot")
+
+        with patch("socket.gethostbyname") as mock_resolve:
+            mock_resolve.return_value = "10.0.0.2"
+            ctrl._resolve_mdns()
+
+        mock_resolve.assert_called_once_with("my-robot.local")
+
+    def test_resolve_failure_returns_none(self):
+        """Failed resolution returns None."""
+        ctrl = self._make_controller("reachy_mini")
+
+        with patch("socket.gethostbyname", side_effect=socket.gaierror("not found")):
+            ip = ctrl._resolve_mdns(timeout=1.0)
+
+        assert ip is None
+
+    def test_resolve_restores_default_timeout(self):
+        """Socket default timeout is restored after resolution."""
+        ctrl = self._make_controller("reachy_mini")
+        original_timeout = socket.getdefaulttimeout()
+
+        with patch("socket.gethostbyname", return_value="10.0.0.1"):
+            ctrl._resolve_mdns(timeout=3.0)
+
+        assert socket.getdefaulttimeout() == original_timeout
+
+    def test_resolve_restores_timeout_on_failure(self):
+        """Socket default timeout is restored even on failure."""
+        ctrl = self._make_controller("reachy_mini")
+        original_timeout = socket.getdefaulttimeout()
+
+        with patch("socket.gethostbyname", side_effect=socket.gaierror("fail")):
+            ctrl._resolve_mdns(timeout=3.0)
+
+        assert socket.getdefaulttimeout() == original_timeout
+
+    def test_resolve_no_underscores_in_name(self):
+        """Robot name without underscores works correctly."""
+        ctrl = self._make_controller("reachymini")
+
+        with patch("socket.gethostbyname") as mock_resolve:
+            mock_resolve.return_value = "10.0.0.3"
+            ctrl._resolve_mdns()
+
+        mock_resolve.assert_called_once_with("reachymini.local")
+
+
+class TestControllerConnect:
+    """Test ReachyMiniController.connect() integration with mDNS."""
+
+    def _make_controller(self, robot_name: str = "reachy_mini") -> object:
+        from maxim.hardware.reachy.controller import ReachyMiniController
+
+        return ReachyMiniController(robot_name=robot_name)
+
+    @patch("maxim.hardware.reachy.controller.ReachyMiniController._resolve_mdns")
+    def test_connect_calls_mdns_resolve(self, mock_mdns):
+        """connect() pre-resolves mDNS before SDK init."""
+        mock_mdns.return_value = "192.168.50.150"
+        ctrl = self._make_controller()
+
+        with patch.dict("sys.modules", {"reachy_mini": MagicMock()}):
+            import sys
+
+            mock_sdk_module = sys.modules["reachy_mini"]
+            mock_mini = MagicMock()
+            mock_sdk_module.ReachyMini.return_value = mock_mini
+
+            ctrl.connect(timeout=5.0)
+
+        mock_mdns.assert_called_once_with(timeout=5.0)
+
+    @patch("maxim.hardware.reachy.controller.ReachyMiniController._resolve_mdns")
+    def test_connect_caps_mdns_timeout_at_5s(self, mock_mdns):
+        """mDNS timeout is capped at 5 seconds even with larger connect timeout."""
+        mock_mdns.return_value = "192.168.50.150"
+        ctrl = self._make_controller()
+
+        with patch.dict("sys.modules", {"reachy_mini": MagicMock()}):
+            import sys
+
+            mock_sdk_module = sys.modules["reachy_mini"]
+            mock_mini = MagicMock()
+            mock_sdk_module.ReachyMini.return_value = mock_mini
+
+            ctrl.connect(timeout=30.0)
+
+        mock_mdns.assert_called_once_with(timeout=5.0)
+
+    @patch("maxim.hardware.reachy.controller.ReachyMiniController._resolve_mdns")
+    def test_connect_uses_network_mode(self, mock_mdns):
+        """connect() passes connection_mode='network' to SDK."""
+        mock_mdns.return_value = "192.168.50.150"
+        ctrl = self._make_controller()
+
+        with patch.dict("sys.modules", {"reachy_mini": MagicMock()}):
+            import sys
+
+            mock_sdk_module = sys.modules["reachy_mini"]
+            mock_mini = MagicMock()
+            mock_sdk_module.ReachyMini.return_value = mock_mini
+
+            ctrl.connect(timeout=5.0)
+
+            mock_sdk_module.ReachyMini.assert_called_once()
+            call_kwargs = mock_sdk_module.ReachyMini.call_args[1]
+            assert call_kwargs["connection_mode"] == "network"
+
+    @patch("maxim.hardware.reachy.controller.ReachyMiniController._resolve_mdns")
+    def test_connect_proceeds_when_mdns_fails(self, mock_mdns):
+        """connect() still attempts SDK connection when mDNS fails."""
+        mock_mdns.return_value = None
+        ctrl = self._make_controller()
+
+        with patch.dict("sys.modules", {"reachy_mini": MagicMock()}):
+            import sys
+
+            mock_sdk_module = sys.modules["reachy_mini"]
+            mock_mini = MagicMock()
+            mock_sdk_module.ReachyMini.return_value = mock_mini
+
+            result = ctrl.connect(timeout=5.0)
+
+        assert result is True
+
+    def test_connect_returns_false_on_import_error(self):
+        """connect() returns False when reachy-mini SDK is not installed."""
+        ctrl = self._make_controller()
+
+        # Ensure reachy_mini is not importable
+        with patch.dict("sys.modules", {"reachy_mini": None}):
+            result = ctrl.connect(timeout=1.0)
+
+        assert result is False
+
+
+class TestConnectionConfigMigration:
+    """Test that ConnectionConfig uses connection_mode correctly."""
+
+    def test_default_connection_mode_is_network(self):
+        """Default connection_mode is 'network'."""
+        from maxim.conscience.connection import ConnectionConfig
+
+        config = ConnectionConfig()
+        assert config.connection_mode == "network"
+
+    def test_custom_connection_mode(self):
+        """Can set custom connection_mode."""
+        from maxim.conscience.connection import ConnectionConfig
+
+        config = ConnectionConfig(connection_mode="auto")
+        assert config.connection_mode == "auto"
+
+    def test_localhost_only_still_exists_for_compat(self):
+        """localhost_only field still exists for backward compatibility."""
+        from maxim.conscience.connection import ConnectionConfig
+
+        config = ConnectionConfig()
+        assert hasattr(config, "localhost_only")