Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Provider-neutral text-language types.
Same shape as :mod:`nodes.speech._protocol`, minus everything that existed
there to keep audio bytes out of the engine. Text results are small, so there
is no ``FileRef`` equivalent and none of ``services.media`` is involved.
**Three capabilities, three registries.** Translation, transliteration and
language identification are related but not interchangeable: DeepL translates
and does nothing else, ICU transliterates without translating, and a
general-purpose LLM does all three. One registry with capability flags would
put a provider in a dropdown it cannot serve and fail at runtime; membership
per capability makes that unrepresentable. This is the same argument that gave
speech two registries rather than one.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Dict, List, Mapping, Optional, Protocol, runtime_checkable
# ---------------------------------------------------------------------------
# Requests
# ---------------------------------------------------------------------------
@dataclass
class TranslateRequest:
"""One translation call.
``text`` is a list because the batch shape is the honest one: DeepL takes
an array natively, and a provider that only handles one string at a time
can loop. Modelling it as a single string would make batching impossible
to add later without breaking every caller.
"""
text: List[str]
target_language: str
source_language: str = ""
model: str = ""
formality: str = ""
context: str = ""
preserve_formatting: bool = False
provider_options: Dict[str, Any] = field(default_factory=dict)
@dataclass
class TransliterateRequest:
"""Script conversion — same language, different writing system."""
text: List[str]
target_script: str = ""
source_language: str = ""
target_language: str = ""
model: str = ""
# Numerals and spoken-form handling differ enough between vendors that
# they stay in provider_options rather than being half-normalised.
provider_options: Dict[str, Any] = field(default_factory=dict)
@dataclass
class DetectRequest:
"""Language identification."""
text: List[str]
model: str = ""
provider_options: Dict[str, Any] = field(default_factory=dict)
# ---------------------------------------------------------------------------
# Results
# ---------------------------------------------------------------------------
@dataclass
class TranslatedText:
text: str = ""
detected_source_language: Optional[str] = None
@dataclass
class TranslateResult:
translations: List[TranslatedText] = field(default_factory=list)
model: str = ""
request_id: Optional[str] = None
# Reported by the provider when it tells us (DeepL returns
# `billed_characters` per translation, which beats counting input
# ourselves); otherwise the node falls back to input length.
billed_units: Optional[float] = None
billed_unit: str = "characters"
@property
def text(self) -> str:
"""First translation, for the single-input common case."""
return self.translations[0].text if self.translations else ""
@dataclass
class TransliterateResult:
results: List[str] = field(default_factory=list)
model: str = ""
request_id: Optional[str] = None
billed_units: Optional[float] = None
billed_unit: str = "characters"
@property
def text(self) -> str:
return self.results[0] if self.results else ""
@dataclass
class DetectedLanguage:
language: str = ""
script: Optional[str] = None
confidence: Optional[float] = None
@dataclass
class DetectResult:
detections: List[DetectedLanguage] = field(default_factory=list)
model: str = ""
request_id: Optional[str] = None
billed_units: Optional[float] = None
billed_unit: str = "characters"
@property
def language(self) -> str:
return self.detections[0].language if self.detections else ""
@dataclass
class LanguageOption:
"""One selectable language, for the dropdown loaders."""
code: str
name: str = ""
def as_option(self) -> Dict[str, str]:
return {"value": self.code, "label": self.name or self.code}
# ---------------------------------------------------------------------------
# Errors
# ---------------------------------------------------------------------------
class TranslateErrorCategory(str, Enum):
AUTHENTICATION = "authentication"
PERMISSION = "permission"
QUOTA = "quota"
RATE_LIMIT = "rate_limit"
INVALID_REQUEST = "invalid_request"
UNSUPPORTED_LANGUAGE = "unsupported_language"
NOT_FOUND = "not_found"
TEXT_TOO_LONG = "text_too_long"
TIMEOUT = "timeout"
CONNECTION = "connection"
SERVER = "server"
UNKNOWN = "unknown"
_RETRYABLE = {
TranslateErrorCategory.RATE_LIMIT,
TranslateErrorCategory.TIMEOUT,
TranslateErrorCategory.CONNECTION,
TranslateErrorCategory.SERVER,
}
_PROVIDER_NAMES = {
"deepl": "DeepL",
"sarvam": "Sarvam AI",
"openai": "OpenAI",
}
@dataclass
class TranslateError(Exception):
"""Provider-independent structured failure."""
message: str
provider: str
category: TranslateErrorCategory = TranslateErrorCategory.UNKNOWN
retryable: bool = False
status_code: Optional[int] = None
provider_code: Optional[str] = None
request_id: Optional[str] = None
def __post_init__(self) -> None:
Exception.__init__(self, self.message)
@property
def user_message(self) -> str:
"""Sanitized message — the only field allowed across a boundary.
``message`` keeps the raw provider text for operator diagnostics, and
provider bodies routinely echo request fragments.
"""
key = str(self.provider or "").strip().lower()
known = key in _PROVIDER_NAMES
provider = _PROVIDER_NAMES.get(key, "The translation provider")
obj = provider if known else "the translation provider"
category = (
self.category.value
if isinstance(self.category, TranslateErrorCategory)
else str(self.category or TranslateErrorCategory.UNKNOWN.value)
)
messages = {
TranslateErrorCategory.AUTHENTICATION.value: (
f"{provider} authentication failed. Check the configured API key."
),
TranslateErrorCategory.PERMISSION.value: (
f"{provider} denied this request. Check the account and plan."
),
TranslateErrorCategory.QUOTA.value: (
f"The {obj} character quota is exhausted for this billing period."
),
TranslateErrorCategory.RATE_LIMIT.value: (
f"{provider} is rate-limiting requests. Retry after a short delay."
),
TranslateErrorCategory.INVALID_REQUEST.value: (
f"{provider} rejected the request configuration."
),
TranslateErrorCategory.UNSUPPORTED_LANGUAGE.value: (
f"{provider} does not support that language pair."
),
TranslateErrorCategory.NOT_FOUND.value: (
f"The configured {obj} model or endpoint was not found."
),
TranslateErrorCategory.TEXT_TOO_LONG.value: (
f"The text exceeds what {obj} accepts in one request. Split it."
),
TranslateErrorCategory.TIMEOUT.value: f"The request to {obj} timed out.",
TranslateErrorCategory.CONNECTION.value: f"Could not connect to {obj}.",
TranslateErrorCategory.SERVER.value: (
f"{provider} is temporarily unavailable."
),
TranslateErrorCategory.UNKNOWN.value: f"{provider} request failed.",
}
return messages.get(category, messages[TranslateErrorCategory.UNKNOWN.value])
@classmethod
def from_exception(cls, provider: str, exc: BaseException) -> "TranslateError":
response = getattr(exc, "response", None)
status = _optional_int(
getattr(exc, "status_code", None)
or getattr(response, "status_code", None)
)
body = _response_text(response)
category = classify(exc, status, body)
return cls(
message=_detail(exc, body),
provider=provider,
category=category,
retryable=category in _RETRYABLE,
status_code=status,
provider_code=_provider_code(response),
request_id=_header(response, "x-request-id"),
)
def classify(
exc: BaseException, status: Optional[int], body_text: str = ""
) -> TranslateErrorCategory:
"""Map an exception plus HTTP status onto a category.
456 is DeepL-specific and worth handling by number: it means the character
quota is exhausted, which is a billing problem the operator must act on,
not a transient failure to retry.
"""
name = type(exc).__name__.lower()
haystack = f"{exc} {body_text}".lower()
if status in (401, 403) or "authentication" in name or "api key" in haystack:
return TranslateErrorCategory.AUTHENTICATION
if status == 456 or "quota" in haystack:
return TranslateErrorCategory.QUOTA
if status == 429 or "ratelimit" in name or "rate limit" in haystack:
return TranslateErrorCategory.RATE_LIMIT
if status == 404 or "notfound" in name:
return TranslateErrorCategory.NOT_FOUND
if status == 413 or "too long" in haystack or "too large" in haystack:
return TranslateErrorCategory.TEXT_TOO_LONG
if "language" in haystack and ("support" in haystack or "invalid" in haystack):
return TranslateErrorCategory.UNSUPPORTED_LANGUAGE
if status in {400, 409, 422} or "badrequest" in name:
return TranslateErrorCategory.INVALID_REQUEST
if status == 408 or "timeout" in name:
return TranslateErrorCategory.TIMEOUT
if "connect" in name:
return TranslateErrorCategory.CONNECTION
if status is not None and status >= 500:
return TranslateErrorCategory.SERVER
return TranslateErrorCategory.UNKNOWN
def _optional_int(value: Any) -> Optional[int]:
try:
return int(value) if value is not None else None
except (TypeError, ValueError, OverflowError):
return None
def _header(response: Any, name: str) -> Optional[str]:
headers = getattr(response, "headers", None)
if headers is None:
return None
try:
return headers.get(name)
except (AttributeError, TypeError):
return None
def _response_text(response: Any) -> str:
if response is None:
return ""
try:
return str(getattr(response, "text", "") or "")[:600]
except Exception:
return ""
def _provider_code(response: Any) -> Optional[str]:
if response is None:
return None
try:
payload = response.json()
except Exception:
return None
if not isinstance(payload, Mapping):
return None
error = payload.get("error")
if isinstance(error, Mapping):
code = error.get("code") or error.get("type")
return str(code) if code is not None else None
code = payload.get("code")
return str(code) if code is not None else None
def _detail(exc: BaseException, body_text: str) -> str:
base = str(exc)
return f"{base} :: {body_text}" if body_text and body_text not in base else base
# ---------------------------------------------------------------------------
# Provider protocols
# ---------------------------------------------------------------------------
#
# One per capability. A provider implements only what it serves and registers
# only into those registries, so an unsupported capability is unreachable
# rather than a method that raises.
@runtime_checkable
class TranslateProvider(Protocol):
provider_name: str
async def translate(self, req: TranslateRequest) -> TranslateResult: ...
async def languages(self, *, target: bool = True) -> List[LanguageOption]: ...
@runtime_checkable
class TransliterateProvider(Protocol):
provider_name: str
async def transliterate(
self, req: TransliterateRequest
) -> TransliterateResult: ...
@runtime_checkable
class DetectProvider(Protocol):
provider_name: str
async def detect(self, req: DetectRequest) -> DetectResult: ...
__all__ = [
"DetectProvider",
"DetectRequest",
"DetectResult",
"DetectedLanguage",
"LanguageOption",
"TranslateError",
"TranslateErrorCategory",
"TranslateProvider",
"TranslateRequest",
"TranslateResult",
"TranslatedText",
"TransliterateProvider",
"TransliterateRequest",
"TransliterateResult",
"classify",
]