[claude] Add vllm-mlx as high-performance local inference backend (#1069) (#1089)

Co-authored-by: Claude (Opus 4.6) <claude@hermes.local>
Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>

tests/infrastructure/test_router_cascade.py

@@ -489,6 +489,197 @@ class TestProviderAvailabilityCheck:
 
         assert router._check_provider_available(provider) is False
 
+    def test_check_vllm_mlx_without_requests(self):
+        """Test vllm-mlx returns True when requests not available (fallback)."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+            base_url="http://localhost:8000/v1",
+        )
+
+        import infrastructure.router.cascade as cascade_module
+
+        old_requests = cascade_module.requests
+        cascade_module.requests = None
+        try:
+            assert router._check_provider_available(provider) is True
+        finally:
+            cascade_module.requests = old_requests
+
+    def test_check_vllm_mlx_server_healthy(self):
+        """Test vllm-mlx when health check succeeds."""
+        from unittest.mock import MagicMock, patch
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+            base_url="http://localhost:8000/v1",
+        )
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+
+        with patch("infrastructure.router.cascade.requests") as mock_requests:
+            mock_requests.get.return_value = mock_response
+            result = router._check_provider_available(provider)
+
+        assert result is True
+        mock_requests.get.assert_called_once_with("http://localhost:8000/health", timeout=5)
+
+    def test_check_vllm_mlx_server_down(self):
+        """Test vllm-mlx when server is not running."""
+        from unittest.mock import patch
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+            base_url="http://localhost:8000/v1",
+        )
+
+        with patch("infrastructure.router.cascade.requests") as mock_requests:
+            mock_requests.get.side_effect = ConnectionRefusedError("Connection refused")
+            result = router._check_provider_available(provider)
+
+        assert result is False
+
+    def test_check_vllm_mlx_default_url(self):
+        """Test vllm-mlx uses default localhost:8000 when no URL configured."""
+        from unittest.mock import MagicMock, patch
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+        )
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+
+        with patch("infrastructure.router.cascade.requests") as mock_requests:
+            mock_requests.get.return_value = mock_response
+            router._check_provider_available(provider)
+
+        mock_requests.get.assert_called_once_with("http://localhost:8000/health", timeout=5)
+
+
+@pytest.mark.asyncio
+class TestVllmMlxProvider:
+    """Test vllm-mlx provider integration."""
+
+    async def test_complete_with_vllm_mlx(self):
+        """Test successful completion via vllm-mlx."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+            base_url="http://localhost:8000/v1",
+            models=[{"name": "Qwen/Qwen2.5-14B-Instruct-MLX", "default": True}],
+        )
+        router.providers = [provider]
+
+        with patch.object(router, "_call_vllm_mlx") as mock_call:
+            mock_call.return_value = {
+                "content": "MLX response",
+                "model": "Qwen/Qwen2.5-14B-Instruct-MLX",
+            }
+
+            result = await router.complete(
+                messages=[{"role": "user", "content": "Hi"}],
+            )
+
+        assert result["content"] == "MLX response"
+        assert result["provider"] == "vllm-mlx-local"
+        assert result["model"] == "Qwen/Qwen2.5-14B-Instruct-MLX"
+
+    async def test_vllm_mlx_base_url_normalization(self):
+        """Test _call_vllm_mlx appends /v1 when missing."""
+        from unittest.mock import AsyncMock, MagicMock, patch
+
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+            base_url="http://localhost:8000",  # No /v1
+            models=[{"name": "qwen-mlx", "default": True}],
+        )
+
+        mock_choice = MagicMock()
+        mock_choice.message.content = "hello"
+        mock_response = MagicMock()
+        mock_response.choices = [mock_choice]
+        mock_response.model = "qwen-mlx"
+
+        async def fake_create(**kwargs):
+            return mock_response
+
+        with patch("openai.AsyncOpenAI") as mock_openai_cls:
+            mock_client = MagicMock()
+            mock_client.chat.completions.create = AsyncMock(side_effect=fake_create)
+            mock_openai_cls.return_value = mock_client
+
+            await router._call_vllm_mlx(
+                provider=provider,
+                messages=[{"role": "user", "content": "hi"}],
+                model="qwen-mlx",
+                temperature=0.7,
+                max_tokens=None,
+            )
+
+            call_kwargs = mock_openai_cls.call_args
+            base_url_used = call_kwargs.kwargs.get("base_url") or call_kwargs[1].get("base_url")
+            assert base_url_used.endswith("/v1")
+
+    async def test_vllm_mlx_is_local_not_cloud(self):
+        """Confirm vllm_mlx is not subject to metabolic protocol cloud skip."""
+        router = CascadeRouter(config_path=Path("/nonexistent"))
+
+        provider = Provider(
+            name="vllm-mlx-local",
+            type="vllm_mlx",
+            enabled=True,
+            priority=2,
+            base_url="http://localhost:8000/v1",
+            models=[{"name": "qwen-mlx", "default": True}],
+        )
+        router.providers = [provider]
+
+        # Quota monitor returns False (block cloud) — vllm_mlx should still be tried
+        with patch("infrastructure.router.cascade._quota_monitor") as mock_qm:
+            mock_qm.check.return_value = object()
+            mock_qm.should_use_cloud.return_value = False
+
+            with patch.object(router, "_call_vllm_mlx") as mock_call:
+                mock_call.return_value = {
+                    "content": "Local MLX response",
+                    "model": "qwen-mlx",
+                }
+                result = await router.complete(
+                    messages=[{"role": "user", "content": "hi"}],
+                )
+
+        assert result["content"] == "Local MLX response"
+
 
 class TestCascadeRouterReload:
     """Test hot-reload of providers.yaml."""