truthound-dashboard 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

truthound_dashboard/translate/providers/base.py

@@ -0,0 +1,225 @@
+"""Base classes and protocols for AI providers.
+
+This module defines the abstract interface that all AI providers must implement,
+ensuring consistent behavior across different translation backends.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ProviderConfig:
+    """Configuration for an AI provider.
+
+    Attributes:
+        api_key: API key for authentication (None for local providers like Ollama)
+        model: Model name to use for translation
+        base_url: Optional base URL override for API endpoint
+        timeout: Request timeout in seconds
+        max_retries: Maximum number of retry attempts on failure
+        extra: Additional provider-specific configuration
+    """
+
+    api_key: str | None = None
+    model: str | None = None
+    base_url: str | None = None
+    timeout: float = 60.0
+    max_retries: int = 3
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_env(
+        cls,
+        env_var: str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> "ProviderConfig":
+        """Create config from environment variable.
+
+        Args:
+            env_var: Environment variable name for API key
+            model: Model name to use
+            **kwargs: Additional configuration options
+
+        Returns:
+            ProviderConfig instance
+        """
+        api_key = os.getenv(env_var) if env_var else None
+        return cls(api_key=api_key, model=model, **kwargs)
+
+
+@dataclass
+class TranslationRequest:
+    """Request for translation.
+
+    Attributes:
+        text: Text to translate
+        source_lang: Source language code (e.g., 'en', 'ko')
+        target_lang: Target language code (e.g., 'ja', 'zh')
+        context: Optional context to improve translation quality
+    """
+
+    text: str
+    source_lang: str
+    target_lang: str
+    context: str | None = None
+
+
+@dataclass
+class TranslationResponse:
+    """Response from translation.
+
+    Attributes:
+        translated_text: The translated text
+        source_lang: Source language code
+        target_lang: Target language code
+        model: Model used for translation
+        provider: Provider name
+        usage: Token usage information (if available)
+    """
+
+    translated_text: str
+    source_lang: str
+    target_lang: str
+    model: str
+    provider: str
+    usage: dict[str, int] | None = None
+
+
+class AIProvider(ABC):
+    """Abstract base class for AI translation providers.
+
+    All AI providers must inherit from this class and implement
+    the required abstract methods.
+
+    Example:
+        class MyProvider(AIProvider):
+            name = "my_provider"
+            env_var = "MY_API_KEY"
+            default_model = "my-model-v1"
+
+            async def translate(self, request: TranslationRequest) -> TranslationResponse:
+                # Implementation here
+                pass
+    """
+
+    # Class attributes to be overridden by subclasses
+    name: str = ""
+    display_name: str = ""
+    env_var: str | None = None
+    default_model: str = ""
+    supported_models: list[str] = []
+
+    def __init__(self, config: ProviderConfig | None = None) -> None:
+        """Initialize the provider.
+
+        Args:
+            config: Provider configuration. If None, will attempt to
+                   create from environment variables.
+        """
+        if config is None:
+            config = ProviderConfig.from_env(
+                env_var=self.env_var,
+                model=self.default_model,
+            )
+        self.config = config
+        self._validate_config()
+
+    def _validate_config(self) -> None:
+        """Validate provider configuration.
+
+        Override this method in subclasses for provider-specific validation.
+
+        Raises:
+            APIKeyNotFoundError: If required API key is missing
+        """
+        from truthound_dashboard.translate.exceptions import APIKeyNotFoundError
+
+        if self.requires_api_key and not self.config.api_key:
+            raise APIKeyNotFoundError(self.name, self.env_var or "API_KEY")
+
+    @property
+    def requires_api_key(self) -> bool:
+        """Whether this provider requires an API key.
+
+        Override this in subclasses that don't require API keys (e.g., Ollama).
+        """
+        return True
+
+    @property
+    def model(self) -> str:
+        """Get the model to use for translation."""
+        return self.config.model or self.default_model
+
+    @abstractmethod
+    async def translate(self, request: TranslationRequest) -> TranslationResponse:
+        """Translate text using this provider.
+
+        Args:
+            request: Translation request containing text and language info
+
+        Returns:
+            TranslationResponse with translated text
+
+        Raises:
+            TranslationAPIError: If API call fails
+        """
+        pass
+
+    async def translate_batch(
+        self,
+        requests: list[TranslationRequest],
+    ) -> list[TranslationResponse]:
+        """Translate multiple texts.
+
+        Default implementation calls translate() for each request.
+        Override this in subclasses for more efficient batch processing.
+
+        Args:
+            requests: List of translation requests
+
+        Returns:
+            List of translation responses
+        """
+        import asyncio
+
+        return await asyncio.gather(*[self.translate(req) for req in requests])
+
+    @abstractmethod
+    async def is_available(self) -> bool:
+        """Check if the provider is available and configured.
+
+        Returns:
+            True if the provider can be used, False otherwise
+        """
+        pass
+
+    def get_translation_prompt(self, request: TranslationRequest) -> str:
+        """Generate the translation prompt.
+
+        Override this method to customize the prompt for specific providers.
+
+        Args:
+            request: Translation request
+
+        Returns:
+            Formatted prompt string
+        """
+        context_part = ""
+        if request.context:
+            context_part = f"\n\nContext: {request.context}"
+
+        return f"""Translate the following text from {request.source_lang} to {request.target_lang}.
+Only output the translated text, nothing else.
+Do not add any explanations, notes, or additional formatting.{context_part}
+
+Text to translate:
+{request.text}"""
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(model={self.model!r})"

truthound_dashboard/translate/providers/mistral.py

@@ -0,0 +1,138 @@
+"""Mistral provider for translation.
+
+This module implements the Mistral AI translation provider.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from truthound_dashboard.translate.exceptions import TranslationAPIError
+from truthound_dashboard.translate.providers.base import (
+    AIProvider,
+    ProviderConfig,
+    TranslationRequest,
+    TranslationResponse,
+)
+
+
+class MistralProvider(AIProvider):
+    """Mistral AI translation provider.
+
+    Uses Mistral AI's models for translation.
+
+    Environment:
+        MISTRAL_API_KEY: API key for authentication
+
+    Example:
+        provider = MistralProvider()
+        response = await provider.translate(
+            TranslationRequest(text="Hello", source_lang="en", target_lang="ja")
+        )
+    """
+
+    name = "mistral"
+    display_name = "Mistral AI"
+    env_var = "MISTRAL_API_KEY"
+    default_model = "mistral-small-latest"
+    supported_models = [
+        "mistral-large-latest",
+        "mistral-medium-latest",
+        "mistral-small-latest",
+        "open-mistral-7b",
+        "open-mixtral-8x7b",
+        "open-mixtral-8x22b",
+    ]
+
+    DEFAULT_BASE_URL = "https://api.mistral.ai/v1"
+
+    def __init__(self, config: ProviderConfig | None = None) -> None:
+        super().__init__(config)
+        self.base_url = self.config.base_url or self.DEFAULT_BASE_URL
+
+    async def translate(self, request: TranslationRequest) -> TranslationResponse:
+        """Translate text using Mistral API.
+
+        Args:
+            request: Translation request
+
+        Returns:
+            Translation response with translated text
+
+        Raises:
+            TranslationAPIError: If API call fails
+        """
+        prompt = self.get_translation_prompt(request)
+
+        async with httpx.AsyncClient(timeout=self.config.timeout) as client:
+            try:
+                response = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    headers={
+                        "Authorization": f"Bearer {self.config.api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json={
+                        "model": self.model,
+                        "messages": [
+                            {
+                                "role": "system",
+                                "content": (
+                                    "You are a professional translator. "
+                                    "Translate the given text accurately and naturally. "
+                                    "Only output the translated text, nothing else."
+                                ),
+                            },
+                            {"role": "user", "content": prompt},
+                        ],
+                        "temperature": 0.3,
+                        "max_tokens": 4096,
+                    },
+                )
+
+                if response.status_code != 200:
+                    raise TranslationAPIError(
+                        provider_name=self.name,
+                        message=f"API request failed: {response.text}",
+                        status_code=response.status_code,
+                        response_body=response.text,
+                    )
+
+                data = response.json()
+                translated_text = data["choices"][0]["message"]["content"].strip()
+
+                usage = None
+                if "usage" in data:
+                    usage = {
+                        "prompt_tokens": data["usage"].get("prompt_tokens", 0),
+                        "completion_tokens": data["usage"].get("completion_tokens", 0),
+                        "total_tokens": data["usage"].get("total_tokens", 0),
+                    }
+
+                return TranslationResponse(
+                    translated_text=translated_text,
+                    source_lang=request.source_lang,
+                    target_lang=request.target_lang,
+                    model=self.model,
+                    provider=self.name,
+                    usage=usage,
+                )
+
+            except httpx.TimeoutException as e:
+                raise TranslationAPIError(
+                    provider_name=self.name,
+                    message=f"Request timed out after {self.config.timeout}s",
+                ) from e
+            except httpx.RequestError as e:
+                raise TranslationAPIError(
+                    provider_name=self.name,
+                    message=f"Request failed: {e}",
+                ) from e
+
+    async def is_available(self) -> bool:
+        """Check if Mistral API is available.
+
+        Returns:
+            True if API key is set
+        """
+        return bool(self.config.api_key)

truthound_dashboard/translate/providers/ollama.py

@@ -0,0 +1,226 @@
+"""Ollama provider for translation.
+
+This module implements the Ollama translation provider for local LLM
+translation without requiring API keys.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from truthound_dashboard.translate.exceptions import (
+    OllamaNotRunningError,
+    TranslationAPIError,
+)
+from truthound_dashboard.translate.providers.base import (
+    AIProvider,
+    ProviderConfig,
+    TranslationRequest,
+    TranslationResponse,
+)
+
+
+class OllamaProvider(AIProvider):
+    """Ollama translation provider for local LLM.
+
+    Uses locally running Ollama models for translation.
+    No API key required.
+
+    Requirements:
+        - Ollama installed and running (ollama serve)
+        - A model pulled (e.g., ollama pull llama2)
+
+    Example:
+        provider = OllamaProvider()
+        response = await provider.translate(
+            TranslationRequest(text="Hello", source_lang="en", target_lang="ja")
+        )
+    """
+
+    name = "ollama"
+    display_name = "Ollama (Local)"
+    env_var = None  # No API key needed
+    default_model = "llama3.2"
+    supported_models = [
+        "llama3.2",
+        "llama3.1",
+        "llama2",
+        "mistral",
+        "mixtral",
+        "qwen2.5",
+        "gemma2",
+        "phi3",
+    ]
+
+    DEFAULT_BASE_URL = "http://localhost:11434"
+
+    def __init__(self, config: ProviderConfig | None = None) -> None:
+        if config is None:
+            config = ProviderConfig(model=self.default_model)
+        super().__init__(config)
+        self.base_url = self.config.base_url or self.DEFAULT_BASE_URL
+
+    @property
+    def requires_api_key(self) -> bool:
+        """Ollama doesn't require an API key."""
+        return False
+
+    async def translate(self, request: TranslationRequest) -> TranslationResponse:
+        """Translate text using Ollama API.
+
+        Args:
+            request: Translation request
+
+        Returns:
+            Translation response with translated text
+
+        Raises:
+            OllamaNotRunningError: If Ollama is not running
+            TranslationAPIError: If API call fails
+        """
+        # First check if Ollama is running
+        if not await self.is_available():
+            raise OllamaNotRunningError()
+
+        prompt = self.get_translation_prompt(request)
+
+        async with httpx.AsyncClient(timeout=self.config.timeout) as client:
+            try:
+                response = await client.post(
+                    f"{self.base_url}/api/generate",
+                    json={
+                        "model": self.model,
+                        "prompt": prompt,
+                        "stream": False,
+                        "options": {
+                            "temperature": 0.3,
+                            "num_predict": 4096,
+                        },
+                    },
+                )
+
+                if response.status_code == 404:
+                    raise TranslationAPIError(
+                        provider_name=self.name,
+                        message=(
+                            f"Model '{self.model}' not found. "
+                            f"Please pull it first: ollama pull {self.model}"
+                        ),
+                        status_code=404,
+                    )
+
+                if response.status_code != 200:
+                    raise TranslationAPIError(
+                        provider_name=self.name,
+                        message=f"API request failed: {response.text}",
+                        status_code=response.status_code,
+                        response_body=response.text,
+                    )
+
+                data = response.json()
+                translated_text = data.get("response", "").strip()
+
+                # Clean up common artifacts from local models
+                translated_text = self._clean_response(translated_text)
+
+                return TranslationResponse(
+                    translated_text=translated_text,
+                    source_lang=request.source_lang,
+                    target_lang=request.target_lang,
+                    model=self.model,
+                    provider=self.name,
+                    usage=None,  # Ollama doesn't provide token usage
+                )
+
+            except httpx.ConnectError as e:
+                raise OllamaNotRunningError() from e
+            except httpx.TimeoutException as e:
+                raise TranslationAPIError(
+                    provider_name=self.name,
+                    message=f"Request timed out after {self.config.timeout}s",
+                ) from e
+            except httpx.RequestError as e:
+                raise TranslationAPIError(
+                    provider_name=self.name,
+                    message=f"Request failed: {e}",
+                ) from e
+
+    def _clean_response(self, text: str) -> str:
+        """Clean up common artifacts from local model responses.
+
+        Args:
+            text: Raw response text
+
+        Returns:
+            Cleaned text
+        """
+        # Remove common prefixes that models might add
+        prefixes_to_remove = [
+            "Here is the translation:",
+            "Translation:",
+            "Translated text:",
+            "Here's the translation:",
+        ]
+        for prefix in prefixes_to_remove:
+            if text.lower().startswith(prefix.lower()):
+                text = text[len(prefix):].strip()
+
+        # Remove quotes if the entire response is quoted
+        if text.startswith('"') and text.endswith('"'):
+            text = text[1:-1]
+        if text.startswith("'") and text.endswith("'"):
+            text = text[1:-1]
+
+        return text.strip()
+
+    async def is_available(self) -> bool:
+        """Check if Ollama is running locally.
+
+        Returns:
+            True if Ollama server is responding
+        """
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(f"{self.base_url}/api/tags")
+                return response.status_code == 200
+        except Exception:
+            return False
+
+    async def list_models(self) -> list[str]:
+        """List available models in Ollama.
+
+        Returns:
+            List of model names
+        """
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.get(f"{self.base_url}/api/tags")
+                if response.status_code == 200:
+                    data = response.json()
+                    return [model["name"] for model in data.get("models", [])]
+        except Exception:
+            pass
+        return []
+
+    def get_translation_prompt(self, request: TranslationRequest) -> str:
+        """Generate a prompt optimized for local models.
+
+        Local models sometimes need more explicit instructions.
+
+        Args:
+            request: Translation request
+
+        Returns:
+            Formatted prompt string
+        """
+        context_part = ""
+        if request.context:
+            context_part = f"\nContext: {request.context}"
+
+        return f"""You are a professional translator. Translate the following text from {request.source_lang} to {request.target_lang}.
+
+IMPORTANT: Only output the translated text. Do not include any explanations, notes, or the original text.{context_part}
+
+Text: {request.text}
+
+Translation:"""