feat: add py.typed, Ray handles for clients, and pre-commit config

- Add py.typed marker for PEP 561 type hint support
- Add ray_utils module for Ray handle detection and caching
- Update all clients (Embeddings, LLM, TTS, STT, Reranker) to use
  Ray handles when running inside Ray cluster for faster internal calls
- Add .pre-commit-config.yaml with ruff and standard hooks
- Add pre-commit and ray[serve] to optional dependencies
- Bump ruff version to 0.4.0

handler_base/clients/stt.py

@@ -1,13 +1,16 @@
 """
 STT service client (Whisper/faster-whisper).
+
+Supports both HTTP (external) and Ray handles (internal) for optimal performance.
 """
 
 import logging
-from typing import Optional
+from typing import Any, Optional
 
 import httpx
 
 from handler_base.config import STTSettings
+from handler_base.ray_utils import get_ray_handle
 from handler_base.telemetry import create_span
 
 logger = logging.getLogger(__name__)
@@ -17,17 +20,33 @@ class STTClient:
     """
     Client for the STT service (Whisper/faster-whisper).
 
+    When running inside Ray, automatically uses Ray handles for faster
+    internal communication. Falls back to HTTP for external calls.
+
     Usage:
         client = STTClient()
         text = await client.transcribe(audio_bytes)
     """
 
+    # Ray Serve deployment configuration
+    RAY_DEPLOYMENT_NAME = "WhisperDeployment"
+    RAY_APP_NAME = "whisper"
+
     def __init__(self, settings: Optional[STTSettings] = None):
         self.settings = settings or STTSettings()
         self._client = httpx.AsyncClient(
             base_url=self.settings.stt_url,
             timeout=180.0,  # Transcription can be slow
         )
+        self._ray_handle: Optional[Any] = None
+        self._ray_checked = False
+
+    def _get_ray_handle(self) -> Optional[Any]:
+        """Get Ray handle, checking only once."""
+        if not self._ray_checked:
+            self._ray_handle = get_ray_handle(self.RAY_DEPLOYMENT_NAME, self.RAY_APP_NAME)
+            self._ray_checked = True
+        return self._ray_handle
 
     async def close(self) -> None:
         """Close the HTTP client."""
@@ -62,6 +81,25 @@ class STTClient:
                 if language:
                     span.set_attribute("stt.language", language)
 
+            # Try Ray handle first (faster internal path)
+            handle = self._get_ray_handle()
+            if handle:
+                try:
+                    if span:
+                        span.set_attribute("stt.transport", "ray")
+                    result = await handle.transcribe.remote(audio, language, task)
+                    if span:
+                        span.set_attribute("stt.result_length", len(result.get("text", "")))
+                        if result.get("language"):
+                            span.set_attribute("stt.detected_language", result["language"])
+                    return result
+                except Exception as e:
+                    logger.warning(f"Ray handle failed, falling back to HTTP: {e}")
+
+            # HTTP fallback
+            if span:
+                span.set_attribute("stt.transport", "http")
+
             files = {"file": ("audio.wav", audio, "audio/wav")}
             data = {
                 "response_format": response_format,