superqode 0.1.5__py3-none-any.whl

superqode/providers/local/discovery.py

@@ -0,0 +1,418 @@
+"""Local provider auto-discovery service.
+
+This module provides automatic discovery of running local LLM servers
+by scanning common ports and detecting provider types.
+"""
+
+import asyncio
+import json
+import socket
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from superqode.providers.local.base import (
+    LocalProviderType,
+    LocalProviderClient,
+    LocalModel,
+    ProviderStatus,
+)
+
+
+# Default ports for each provider type
+DEFAULT_PORTS = {
+    LocalProviderType.OLLAMA: [11434],
+    LocalProviderType.LMSTUDIO: [1234],
+    LocalProviderType.VLLM: [8000],
+    LocalProviderType.SGLANG: [30000],
+    LocalProviderType.TGI: [8080],
+    LocalProviderType.MLX: [8080],
+    LocalProviderType.LLAMACPP: [8080],
+    LocalProviderType.OPENAI_COMPAT: [8000, 8080, 5000],
+}
+
+# All ports to scan for discovery
+ALL_PORTS = [11434, 1234, 8000, 8080, 30000, 5000, 3000]
+
+
+@dataclass
+class DiscoveredProvider:
+    """A discovered local LLM provider.
+
+    Attributes:
+        provider_type: Type of provider detected
+        host: Provider host URL
+        port: Port number
+        version: Provider version (if available)
+        models: List of available models
+        running_models: List of models currently loaded
+        latency_ms: Discovery latency
+    """
+
+    provider_type: LocalProviderType
+    host: str
+    port: int
+    version: str = ""
+    models: List[LocalModel] = field(default_factory=list)
+    running_models: List[LocalModel] = field(default_factory=list)
+    latency_ms: float = 0.0
+
+    @property
+    def url(self) -> str:
+        """Get the full provider URL."""
+        return f"http://localhost:{self.port}"
+
+    @property
+    def model_count(self) -> int:
+        """Get number of available models."""
+        return len(self.models)
+
+    @property
+    def running_count(self) -> int:
+        """Get number of running models."""
+        return len(self.running_models)
+
+
+class LocalProviderDiscovery:
+    """Discovers running local LLM servers.
+
+    Scans common ports and detects provider types:
+    - 11434: Ollama
+    - 1234: LM Studio
+    - 8000: vLLM, OpenAI-compatible
+    - 30000: SGLang
+    - 8080: TGI, MLX, llama.cpp
+    """
+
+    def __init__(self, timeout: float = 2.0):
+        """Initialize the discovery service.
+
+        Args:
+            timeout: Connection timeout for port scanning.
+        """
+        self._timeout = timeout
+        self._discovered: Dict[str, DiscoveredProvider] = {}
+
+    async def scan_all(self) -> Dict[str, DiscoveredProvider]:
+        """Scan all common ports for local providers.
+
+        Returns:
+            Dict mapping host:port to DiscoveredProvider.
+        """
+        # Check all ports in parallel
+        tasks = []
+        for port in ALL_PORTS:
+            tasks.append(self._scan_port(port))
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        discovered = {}
+        for result in results:
+            if isinstance(result, DiscoveredProvider):
+                key = f"localhost:{result.port}"
+                discovered[key] = result
+
+        self._discovered = discovered
+        return discovered
+
+    async def scan_port(self, port: int) -> Optional[DiscoveredProvider]:
+        """Scan a specific port for a provider.
+
+        Args:
+            port: Port number to scan.
+
+        Returns:
+            DiscoveredProvider if found, None otherwise.
+        """
+        return await self._scan_port(port)
+
+    async def _scan_port(self, port: int) -> Optional[DiscoveredProvider]:
+        """Internal port scanning implementation."""
+        # First check if port is open
+        if not await self._is_port_open(port):
+            return None
+
+        start_time = time.time()
+
+        # Try to detect provider type
+        provider_type = await self._detect_provider_type(port)
+
+        if provider_type is None:
+            return None
+
+        latency = (time.time() - start_time) * 1000
+
+        # Get provider details
+        version = await self._get_version(port, provider_type)
+        models = await self._list_models(port, provider_type)
+        running = await self._list_running(port, provider_type)
+
+        return DiscoveredProvider(
+            provider_type=provider_type,
+            host=f"http://localhost:{port}",
+            port=port,
+            version=version,
+            models=models,
+            running_models=running,
+            latency_ms=latency,
+        )
+
+    async def _is_port_open(self, port: int) -> bool:
+        """Check if a port is open."""
+        loop = asyncio.get_event_loop()
+
+        def check():
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(self._timeout)
+            try:
+                result = sock.connect_ex(("localhost", port))
+                return result == 0
+            finally:
+                sock.close()
+
+        return await loop.run_in_executor(None, check)
+
+    async def _detect_provider_type(self, port: int) -> Optional[LocalProviderType]:
+        """Detect the provider type from port responses."""
+        loop = asyncio.get_event_loop()
+
+        def detect():
+            # Try Ollama-specific endpoint
+            if port == 11434:
+                try:
+                    req = Request(f"http://localhost:{port}/api/tags")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        if "models" in data:
+                            return LocalProviderType.OLLAMA
+                except Exception:
+                    pass
+
+            # Try LM Studio-specific detection
+            if port == 1234:
+                try:
+                    req = Request(f"http://localhost:{port}/v1/models")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        if "data" in data:
+                            return LocalProviderType.LMSTUDIO
+                except Exception:
+                    pass
+
+            # Try SGLang-specific detection (has /health endpoint)
+            if port == 30000:
+                try:
+                    req = Request(f"http://localhost:{port}/health")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        return LocalProviderType.SGLANG
+                except Exception:
+                    pass
+
+            # Try TGI-specific detection (has /info endpoint)
+            try:
+                req = Request(f"http://localhost:{port}/info")
+                with urlopen(req, timeout=self._timeout) as resp:
+                    data = json.loads(resp.read())
+                    if "model_id" in data:
+                        return LocalProviderType.TGI
+            except Exception:
+                pass
+
+            # Try vLLM-specific detection
+            if port == 8000:
+                try:
+                    req = Request(f"http://localhost:{port}/health")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        # vLLM health endpoint exists
+                        pass
+                    # Also check for models endpoint
+                    req2 = Request(f"http://localhost:{port}/v1/models")
+                    with urlopen(req2, timeout=self._timeout) as resp:
+                        return LocalProviderType.VLLM
+                except Exception:
+                    pass
+
+            # Generic OpenAI-compatible check
+            try:
+                req = Request(f"http://localhost:{port}/v1/models")
+                with urlopen(req, timeout=self._timeout) as resp:
+                    data = json.loads(resp.read())
+                    if "data" in data:
+                        # Could be MLX, llama.cpp, or generic OpenAI-compatible
+                        if port == 8080:
+                            return LocalProviderType.MLX  # Common MLX port
+                        return LocalProviderType.OPENAI_COMPAT
+            except Exception:
+                pass
+
+            return None
+
+        return await loop.run_in_executor(None, detect)
+
+    async def _get_version(self, port: int, provider_type: LocalProviderType) -> str:
+        """Get provider version string."""
+        loop = asyncio.get_event_loop()
+
+        def get_ver():
+            if provider_type == LocalProviderType.OLLAMA:
+                try:
+                    req = Request(f"http://localhost:{port}/api/version")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        return data.get("version", "")
+                except Exception:
+                    pass
+
+            if provider_type == LocalProviderType.TGI:
+                try:
+                    req = Request(f"http://localhost:{port}/info")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        return data.get("version", "")
+                except Exception:
+                    pass
+
+            return ""
+
+        return await loop.run_in_executor(None, get_ver)
+
+    async def _list_models(self, port: int, provider_type: LocalProviderType) -> List[LocalModel]:
+        """List available models from provider."""
+        loop = asyncio.get_event_loop()
+
+        def list_mod():
+            models = []
+
+            if provider_type == LocalProviderType.OLLAMA:
+                try:
+                    req = Request(f"http://localhost:{port}/api/tags")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        for m in data.get("models", []):
+                            models.append(
+                                LocalModel(
+                                    id=m.get("name", ""),
+                                    name=m.get("name", "").split(":")[0].title(),
+                                    size_bytes=m.get("size", 0),
+                                )
+                            )
+                except Exception:
+                    pass
+
+            elif provider_type in (
+                LocalProviderType.LMSTUDIO,
+                LocalProviderType.VLLM,
+                LocalProviderType.OPENAI_COMPAT,
+                LocalProviderType.MLX,
+            ):
+                try:
+                    req = Request(f"http://localhost:{port}/v1/models")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        for m in data.get("data", []):
+                            models.append(
+                                LocalModel(
+                                    id=m.get("id", ""),
+                                    name=m.get("id", "").split("/")[-1],
+                                )
+                            )
+                except Exception:
+                    pass
+
+            elif provider_type == LocalProviderType.TGI:
+                try:
+                    req = Request(f"http://localhost:{port}/info")
+                    with urlopen(req, timeout=self._timeout) as resp:
+                        data = json.loads(resp.read())
+                        model_id = data.get("model_id", "")
+                        if model_id:
+                            models.append(
+                                LocalModel(
+                                    id=model_id,
+                                    name=model_id.split("/")[-1],
+                                    context_window=data.get("max_input_length", 4096),
+                                )
+                            )
+                except Exception:
+                    pass
+
+            return models
+
+        return await loop.run_in_executor(None, list_mod)
+
+    async def _list_running(self, port: int, provider_type: LocalProviderType) -> List[LocalModel]:
+        """List running models from provider."""
+        loop = asyncio.get_event_loop()
+
+        def list_run():
+            if provider_type != LocalProviderType.OLLAMA:
+                return []  # Only Ollama has running model tracking
+
+            try:
+                req = Request(f"http://localhost:{port}/api/ps")
+                with urlopen(req, timeout=self._timeout) as resp:
+                    data = json.loads(resp.read())
+                    return [
+                        LocalModel(
+                            id=m.get("name", ""),
+                            name=m.get("name", "").split(":")[0].title(),
+                            running=True,
+                            vram_usage=m.get("size_vram", 0),
+                        )
+                        for m in data.get("models", [])
+                    ]
+            except Exception:
+                return []
+
+        return await loop.run_in_executor(None, list_run)
+
+    async def discover_models(self) -> List[LocalModel]:
+        """Discover all available models from all running providers.
+
+        Returns:
+            Combined list of LocalModel from all discovered providers.
+        """
+        if not self._discovered:
+            await self.scan_all()
+
+        all_models = []
+        for provider in self._discovered.values():
+            for model in provider.models:
+                # Add provider info to model
+                model.details["provider_type"] = provider.provider_type.value
+                model.details["provider_host"] = provider.host
+                all_models.append(model)
+
+        return all_models
+
+    def get_discovered(self) -> Dict[str, DiscoveredProvider]:
+        """Get cached discovered providers."""
+        return self._discovered
+
+
+# Singleton instance
+_discovery_instance: Optional[LocalProviderDiscovery] = None
+
+
+def get_discovery_service() -> LocalProviderDiscovery:
+    """Get the global discovery service instance.
+
+    Returns:
+        LocalProviderDiscovery instance.
+    """
+    global _discovery_instance
+    if _discovery_instance is None:
+        _discovery_instance = LocalProviderDiscovery()
+    return _discovery_instance
+
+
+async def quick_scan() -> Dict[str, DiscoveredProvider]:
+    """Perform a quick scan for local providers.
+
+    Returns:
+        Dict of discovered providers.
+    """
+    service = get_discovery_service()
+    return await service.scan_all()

superqode/providers/local/lmstudio.py

@@ -0,0 +1,256 @@
+"""LM Studio client for local model inference.
+
+LM Studio is a desktop application for running LLMs locally with
+a user-friendly interface and OpenAI-compatible API server.
+"""
+
+import asyncio
+import json
+import os
+import time
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from superqode.providers.local.base import (
+    LocalProviderClient,
+    LocalProviderType,
+    LocalModel,
+    ProviderStatus,
+    ToolTestResult,
+    detect_model_family,
+    detect_quantization,
+    likely_supports_tools,
+)
+
+
+class LMStudioClient(LocalProviderClient):
+    """LM Studio local server client.
+
+    LM Studio provides:
+    - User-friendly GUI for model management
+    - OpenAI-compatible local server
+    - GGUF model support
+    - GPU and CPU inference
+
+    API Endpoints (OpenAI-compatible):
+    - GET /v1/models - List loaded models
+    - POST /v1/chat/completions - Chat completion
+    - POST /v1/completions - Text completion
+    - POST /v1/embeddings - Embeddings
+
+    Environment:
+        LMSTUDIO_HOST: Override default host (default: http://localhost:1234)
+    """
+
+    provider_type = LocalProviderType.LMSTUDIO
+    default_port = 1234
+
+    def __init__(self, host: Optional[str] = None):
+        """Initialize LM Studio client.
+
+        Args:
+            host: LM Studio host URL. Falls back to LMSTUDIO_HOST env var.
+        """
+        if host is None:
+            host = os.environ.get("LMSTUDIO_HOST")
+        super().__init__(host)
+
+    def _request(
+        self, method: str, endpoint: str, data: Optional[Dict] = None, timeout: float = 30.0
+    ) -> Any:
+        """Make a request to the LM Studio API."""
+        url = f"{self.host}{endpoint}"
+        headers = {"Content-Type": "application/json"}
+
+        body = None
+        if data is not None:
+            body = json.dumps(data).encode("utf-8")
+
+        request = Request(url, data=body, headers=headers, method=method)
+
+        with urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    async def _async_request(
+        self, method: str, endpoint: str, data: Optional[Dict] = None, timeout: float = 30.0
+    ) -> Any:
+        """Async wrapper for _request."""
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None, lambda: self._request(method, endpoint, data, timeout)
+        )
+
+    async def is_available(self) -> bool:
+        """Check if LM Studio server is running."""
+        try:
+            await self._async_request("GET", "/v1/models", timeout=5.0)
+            return True
+        except Exception:
+            return False
+
+    async def get_status(self) -> ProviderStatus:
+        """Get detailed LM Studio status."""
+        start_time = time.time()
+
+        try:
+            models_response = await self._async_request("GET", "/v1/models", timeout=5.0)
+            latency = (time.time() - start_time) * 1000
+
+            models = models_response.get("data", [])
+
+            return ProviderStatus(
+                available=True,
+                provider_type=self.provider_type,
+                host=self.host,
+                version="LM Studio",
+                models_count=len(models),
+                running_models=len(models),
+                gpu_available=True,
+                latency_ms=latency,
+                last_checked=datetime.now(),
+            )
+
+        except Exception as e:
+            return ProviderStatus(
+                available=False,
+                provider_type=self.provider_type,
+                host=self.host,
+                error=str(e),
+                last_checked=datetime.now(),
+            )
+
+    async def list_models(self) -> List[LocalModel]:
+        """List available models."""
+        try:
+            response = await self._async_request("GET", "/v1/models")
+            models = response.get("data", [])
+
+            result = []
+            for model_data in models:
+                model_id = model_data.get("id", "")
+
+                # Parse model info from ID (LM Studio often uses paths)
+                name = model_id.split("/")[-1]
+                family = detect_model_family(model_id)
+                quant = detect_quantization(model_id)
+
+                result.append(
+                    LocalModel(
+                        id=model_id,
+                        name=name,
+                        quantization=quant,
+                        family=family,
+                        supports_tools=likely_supports_tools(model_id),
+                        running=True,
+                    )
+                )
+
+            return result
+
+        except Exception:
+            return []
+
+    async def list_running(self) -> List[LocalModel]:
+        """List running models."""
+        return await self.list_models()
+
+    async def get_model_info(self, model_id: str) -> Optional[LocalModel]:
+        """Get model information."""
+        models = await self.list_models()
+        for m in models:
+            if m.id == model_id or model_id in m.id:
+                return m
+        return None
+
+    async def test_tool_calling(self, model_id: str) -> ToolTestResult:
+        """Test tool calling capability."""
+        start_time = time.time()
+
+        if not likely_supports_tools(model_id):
+            return ToolTestResult(
+                model_id=model_id,
+                supports_tools=False,
+                notes="Model family not known to support tools",
+            )
+
+        test_tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_weather",
+                    "description": "Get weather for a city",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"city": {"type": "string"}},
+                        "required": ["city"],
+                    },
+                },
+            }
+        ]
+
+        try:
+            response = await self._async_request(
+                "POST",
+                "/v1/chat/completions",
+                data={
+                    "model": model_id,
+                    "messages": [{"role": "user", "content": "What's the weather in Paris?"}],
+                    "tools": test_tools,
+                },
+                timeout=60.0,
+            )
+
+            latency = (time.time() - start_time) * 1000
+
+            choices = response.get("choices", [])
+            if choices:
+                message = choices[0].get("message", {})
+                tool_calls = message.get("tool_calls", [])
+
+                if tool_calls:
+                    return ToolTestResult(
+                        model_id=model_id,
+                        supports_tools=True,
+                        parallel_tools=len(tool_calls) > 1,
+                        tool_choice=["auto"],
+                        latency_ms=latency,
+                        notes="Tool calling verified via LM Studio",
+                    )
+
+            return ToolTestResult(
+                model_id=model_id,
+                supports_tools=False,
+                latency_ms=latency,
+                notes="Model did not use tools in test",
+            )
+
+        except Exception as e:
+            return ToolTestResult(
+                model_id=model_id,
+                supports_tools=False,
+                error=str(e),
+            )
+
+    def get_litellm_model_name(self, model_id: str) -> str:
+        """Get LiteLLM-compatible model name."""
+        # LM Studio uses lm_studio/ prefix in LiteLLM
+        if model_id.startswith("lm_studio/"):
+            return model_id
+        return f"lm_studio/{model_id}"
+
+
+async def get_lmstudio_client(host: Optional[str] = None) -> Optional[LMStudioClient]:
+    """Get an LM Studio client if available.
+
+    Args:
+        host: Optional host override.
+
+    Returns:
+        LMStudioClient if LM Studio server is running, None otherwise.
+    """
+    client = LMStudioClient(host)
+    if await client.is_available():
+        return client
+    return None