ringglabs 0.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of ringglabs might be problematic. Click here for more details.

@@ -0,0 +1,156 @@
1
+ """Sync WebSocket streaming session implementation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from builtins import TimeoutError as BuiltinTimeoutError
6
+ import json
7
+ from typing import Iterator
8
+
9
+ from websockets.exceptions import ConnectionClosed
10
+
11
+ try:
12
+ from websockets.sync.client import connect as ws_connect
13
+ except ImportError: # pragma: no cover
14
+ ws_connect = None # type: ignore[assignment]
15
+
16
+ from ._serialization import parse_json_message, parse_ws_event
17
+ from .config import ClientConfig
18
+ from .errors import ApiError, ProtocolError, TimeoutError, TransportError
19
+ from .models import ErrorEvent, ReadyEvent, StartConfig, WsEvent
20
+
21
+
22
+ class StreamSession:
23
+ """Sync context-managed WebSocket stream session."""
24
+
25
+ def __init__(
26
+ self,
27
+ client_config: ClientConfig,
28
+ start_config: StartConfig,
29
+ *,
30
+ api_key_override: str | None = None,
31
+ ):
32
+ self._client_config = client_config
33
+ self._start_config = start_config
34
+ self._api_key_override = api_key_override
35
+ self._ws = None
36
+ self.ready_event: ReadyEvent | None = None
37
+
38
+ def __enter__(self) -> "StreamSession":
39
+ self.open()
40
+ return self
41
+
42
+ def __exit__(self, exc_type, exc, tb) -> None:
43
+ self.close()
44
+
45
+ def open(self) -> ReadyEvent:
46
+ if ws_connect is None:
47
+ raise TransportError(
48
+ "websockets sync client is unavailable; install websockets>=12"
49
+ )
50
+ if self._ws is not None:
51
+ return self.ready_event if self.ready_event is not None else self._handshake()
52
+ uri = self._client_config.ws_url
53
+ try:
54
+ self._ws = ws_connect(
55
+ uri,
56
+ open_timeout=self._client_config.timeout.ws_open,
57
+ close_timeout=self._client_config.timeout.ws_close,
58
+ max_size=None,
59
+ )
60
+ except BuiltinTimeoutError as exc:
61
+ raise TimeoutError("WebSocket connection timed out") from exc
62
+ except Exception as exc:
63
+ raise TransportError(f"WebSocket connection failed: {exc}") from exc
64
+ return self._handshake()
65
+
66
+ def _handshake(self) -> ReadyEvent:
67
+ if self._ws is None:
68
+ raise TransportError("WebSocket is not connected")
69
+ resolved_key = self._client_config.resolve_api_key(self._api_key_override)
70
+ payload = self._start_config.to_payload(resolved_api_key=resolved_key)
71
+ self._ws.send(json.dumps(payload, ensure_ascii=False))
72
+ try:
73
+ raw = self._ws.recv(timeout=self._client_config.timeout.ws_recv)
74
+ except BuiltinTimeoutError as exc:
75
+ raise TimeoutError("Timed out waiting for server ready message") from exc
76
+ except Exception as exc:
77
+ raise TransportError(f"Failed during start handshake: {exc}") from exc
78
+
79
+ event = self._parse_raw_event(raw)
80
+ if isinstance(event, ErrorEvent):
81
+ raise ApiError(
82
+ message=event.detail,
83
+ code=event.code,
84
+ status_code=event.status_code,
85
+ payload=event.raw,
86
+ )
87
+ if not isinstance(event, ReadyEvent):
88
+ raise ProtocolError(
89
+ f"Expected first server message to be 'ready', got {event.type!r}"
90
+ )
91
+ self.ready_event = event
92
+ return event
93
+
94
+ def send_audio(self, audio_chunk: bytes) -> None:
95
+ if self._ws is None:
96
+ raise TransportError("WebSocket is not connected")
97
+ if not isinstance(audio_chunk, (bytes, bytearray)):
98
+ raise ProtocolError("audio_chunk must be bytes")
99
+ self._ws.send(bytes(audio_chunk))
100
+
101
+ def send_vad_event(self, state: str) -> None:
102
+ if self._ws is None:
103
+ raise TransportError("WebSocket is not connected")
104
+ self._ws.send(
105
+ json.dumps({"type": "vad_event", "state": str(state)}, ensure_ascii=False)
106
+ )
107
+
108
+ def start_speaking(self) -> None:
109
+ self.send_vad_event("user_start_speaking")
110
+
111
+ def stop_speaking(self) -> None:
112
+ self.send_vad_event("user_stop_speaking")
113
+
114
+ def ping(self) -> None:
115
+ if self._ws is None:
116
+ raise TransportError("WebSocket is not connected")
117
+ self._ws.send(json.dumps({"type": "ping"}, ensure_ascii=False))
118
+
119
+ def end(self, command: str = "end") -> None:
120
+ if self._ws is None:
121
+ raise TransportError("WebSocket is not connected")
122
+ if command not in {"end", "stop", "exit", "close"}:
123
+ raise ProtocolError("command must be one of: end, stop, exit, close")
124
+ self._ws.send(json.dumps({"type": command}, ensure_ascii=False))
125
+
126
+ def recv_event(self) -> WsEvent:
127
+ if self._ws is None:
128
+ raise TransportError("WebSocket is not connected")
129
+ try:
130
+ raw = self._ws.recv(timeout=self._client_config.timeout.ws_recv)
131
+ except BuiltinTimeoutError as exc:
132
+ raise TimeoutError("Timed out waiting for WebSocket message") from exc
133
+ except ConnectionClosed as exc:
134
+ raise TransportError(f"WebSocket connection closed: {exc}") from exc
135
+ return self._parse_raw_event(raw)
136
+
137
+ def events(self) -> Iterator[WsEvent]:
138
+ while True:
139
+ try:
140
+ event = self.recv_event()
141
+ except TimeoutError:
142
+ raise
143
+ except TransportError:
144
+ break
145
+ yield event
146
+
147
+ def _parse_raw_event(self, raw: str | bytes) -> WsEvent:
148
+ if isinstance(raw, bytes):
149
+ raise ProtocolError("Expected text JSON event from server, got binary frame")
150
+ payload = parse_json_message(raw)
151
+ return parse_ws_event(payload)
152
+
153
+ def close(self) -> None:
154
+ if self._ws is not None:
155
+ self._ws.close()
156
+ self._ws = None
@@ -0,0 +1,170 @@
1
+ """Async STT client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import BinaryIO
7
+
8
+ from ._http import AsyncHttpTransport
9
+ from ._io import read_audio_source
10
+ from ._ws_async import AsyncStreamSession
11
+ from .config import ClientConfig, TimeoutConfig
12
+ from .models import (
13
+ FileSource,
14
+ RestTranscriptionResult,
15
+ StreamOptions,
16
+ TranscriptionOptions,
17
+ )
18
+
19
+
20
+ class AsyncClient:
21
+ """Async RinggLabs STT client."""
22
+
23
+ def __init__(
24
+ self,
25
+ *,
26
+ base_url: str | None = None,
27
+ rest_endpoint: str | None = None,
28
+ ws_endpoint: str | None = None,
29
+ api_key: str | None = None,
30
+ timeout: TimeoutConfig | None = None,
31
+ rest_path: str = "/parrot-stt/v1/transcriptions",
32
+ ws_path: str = "/parrot-stt/v1/stream",
33
+ default_headers: dict[str, str] | None = None,
34
+ ):
35
+ self.config = ClientConfig(
36
+ base_url=base_url,
37
+ api_key=api_key,
38
+ timeout=timeout or TimeoutConfig(),
39
+ rest_endpoint=rest_endpoint,
40
+ ws_endpoint=ws_endpoint,
41
+ rest_path=rest_path,
42
+ ws_path=ws_path,
43
+ default_headers=default_headers,
44
+ )
45
+ self._http = AsyncHttpTransport(self.config)
46
+
47
+ async def __aenter__(self) -> "AsyncClient":
48
+ await self._http.open()
49
+ return self
50
+
51
+ async def __aexit__(self, exc_type, exc, tb) -> None:
52
+ await self.close()
53
+
54
+ async def close(self) -> None:
55
+ await self._http.close()
56
+
57
+ async def health(self, *, api_key: str | None = None) -> dict:
58
+ return await self._http.health_check(api_key_override=api_key)
59
+
60
+ async def transcribe(
61
+ self,
62
+ source: FileSource,
63
+ *,
64
+ language: str = "hi",
65
+ enable_cap_punc: bool = True,
66
+ api_key: str | None = None,
67
+ filename: str | None = None,
68
+ content_type: str = "audio/wav",
69
+ ) -> RestTranscriptionResult:
70
+ audio, detected_name = read_audio_source(source, fallback_filename=filename or "audio.wav")
71
+ options = TranscriptionOptions(
72
+ language=language,
73
+ enable_cap_punc=enable_cap_punc,
74
+ api_key=api_key,
75
+ filename=filename or detected_name,
76
+ content_type=content_type,
77
+ )
78
+ return await self._http.transcribe_bytes(audio, options, api_key_override=api_key)
79
+
80
+ async def _transcribe_file(
81
+ self,
82
+ file_path: str | Path,
83
+ *,
84
+ language: str = "hi",
85
+ enable_cap_punc: bool = True,
86
+ api_key: str | None = None,
87
+ content_type: str = "audio/wav",
88
+ ) -> RestTranscriptionResult:
89
+ return await self.transcribe(
90
+ file_path,
91
+ language=language,
92
+ enable_cap_punc=enable_cap_punc,
93
+ api_key=api_key,
94
+ content_type=content_type,
95
+ )
96
+
97
+ async def _transcribe_bytes(
98
+ self,
99
+ audio: bytes | bytearray,
100
+ *,
101
+ language: str = "hi",
102
+ enable_cap_punc: bool = True,
103
+ api_key: str | None = None,
104
+ filename: str = "audio.wav",
105
+ content_type: str = "audio/wav",
106
+ ) -> RestTranscriptionResult:
107
+ return await self.transcribe(
108
+ bytes(audio),
109
+ language=language,
110
+ enable_cap_punc=enable_cap_punc,
111
+ api_key=api_key,
112
+ filename=filename,
113
+ content_type=content_type,
114
+ )
115
+
116
+ async def _transcribe_fileobj(
117
+ self,
118
+ fileobj: BinaryIO,
119
+ *,
120
+ language: str = "hi",
121
+ enable_cap_punc: bool = True,
122
+ api_key: str | None = None,
123
+ filename: str | None = None,
124
+ content_type: str = "audio/wav",
125
+ ) -> RestTranscriptionResult:
126
+ return await self.transcribe(
127
+ fileobj,
128
+ language=language,
129
+ enable_cap_punc=enable_cap_punc,
130
+ api_key=api_key,
131
+ filename=filename,
132
+ content_type=content_type,
133
+ )
134
+
135
+ def _open_stream(self, options: StreamOptions, *, api_key: str | None = None) -> AsyncStreamSession:
136
+ start_config = options.to_start_config()
137
+ return AsyncStreamSession(
138
+ client_config=self.config,
139
+ start_config=start_config,
140
+ api_key_override=api_key,
141
+ )
142
+
143
+ def stream(
144
+ self,
145
+ *,
146
+ sample_rate: int = 16000,
147
+ encoding: str = "int16",
148
+ language: str = "hi",
149
+ mode: str = "stream",
150
+ vad_tail_sil_ms: int = 200,
151
+ vad_confidence: float = 0.55,
152
+ enable_cap_punc: bool = True,
153
+ accept_client_vad_events: bool = False,
154
+ api_key: str | None = None,
155
+ ) -> AsyncStreamSession:
156
+ """Create a stream session with high-level options."""
157
+ return self._open_stream(
158
+ StreamOptions(
159
+ sample_rate=sample_rate,
160
+ encoding=encoding,
161
+ language=language,
162
+ mode=mode,
163
+ vad_tail_sil_ms=vad_tail_sil_ms,
164
+ vad_confidence=vad_confidence,
165
+ enable_cap_punc=enable_cap_punc,
166
+ accept_client_vad_events=accept_client_vad_events,
167
+ api_key=api_key,
168
+ ),
169
+ api_key=api_key,
170
+ )
@@ -0,0 +1,170 @@
1
+ """Sync STT client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import BinaryIO
7
+
8
+ from ._http import SyncHttpTransport
9
+ from ._io import read_audio_source
10
+ from ._ws_sync import StreamSession
11
+ from .config import ClientConfig, TimeoutConfig
12
+ from .models import (
13
+ FileSource,
14
+ RestTranscriptionResult,
15
+ StreamOptions,
16
+ TranscriptionOptions,
17
+ )
18
+
19
+
20
+ class Client:
21
+ """Sync RinggLabs STT client."""
22
+
23
+ def __init__(
24
+ self,
25
+ *,
26
+ base_url: str | None = None,
27
+ rest_endpoint: str | None = None,
28
+ ws_endpoint: str | None = None,
29
+ api_key: str | None = None,
30
+ timeout: TimeoutConfig | None = None,
31
+ rest_path: str = "/parrot-stt/v1/transcriptions",
32
+ ws_path: str = "/parrot-stt/v1/stream",
33
+ default_headers: dict[str, str] | None = None,
34
+ ):
35
+ self.config = ClientConfig(
36
+ base_url=base_url,
37
+ api_key=api_key,
38
+ timeout=timeout or TimeoutConfig(),
39
+ rest_endpoint=rest_endpoint,
40
+ ws_endpoint=ws_endpoint,
41
+ rest_path=rest_path,
42
+ ws_path=ws_path,
43
+ default_headers=default_headers,
44
+ )
45
+ self._http = SyncHttpTransport(self.config)
46
+
47
+ def __enter__(self) -> "Client":
48
+ self._http.open()
49
+ return self
50
+
51
+ def __exit__(self, exc_type, exc, tb) -> None:
52
+ self.close()
53
+
54
+ def close(self) -> None:
55
+ self._http.close()
56
+
57
+ def health(self, *, api_key: str | None = None) -> dict:
58
+ return self._http.health_check(api_key_override=api_key)
59
+
60
+ def transcribe(
61
+ self,
62
+ source: FileSource,
63
+ *,
64
+ language: str = "hi",
65
+ enable_cap_punc: bool = True,
66
+ api_key: str | None = None,
67
+ filename: str | None = None,
68
+ content_type: str = "audio/wav",
69
+ ) -> RestTranscriptionResult:
70
+ audio, detected_name = read_audio_source(source, fallback_filename=filename or "audio.wav")
71
+ options = TranscriptionOptions(
72
+ language=language,
73
+ enable_cap_punc=enable_cap_punc,
74
+ api_key=api_key,
75
+ filename=filename or detected_name,
76
+ content_type=content_type,
77
+ )
78
+ return self._http.transcribe_bytes(audio, options, api_key_override=api_key)
79
+
80
+ def _transcribe_file(
81
+ self,
82
+ file_path: str | Path,
83
+ *,
84
+ language: str = "hi",
85
+ enable_cap_punc: bool = True,
86
+ api_key: str | None = None,
87
+ content_type: str = "audio/wav",
88
+ ) -> RestTranscriptionResult:
89
+ return self.transcribe(
90
+ file_path,
91
+ language=language,
92
+ enable_cap_punc=enable_cap_punc,
93
+ api_key=api_key,
94
+ content_type=content_type,
95
+ )
96
+
97
+ def _transcribe_bytes(
98
+ self,
99
+ audio: bytes | bytearray,
100
+ *,
101
+ language: str = "hi",
102
+ enable_cap_punc: bool = True,
103
+ api_key: str | None = None,
104
+ filename: str = "audio.wav",
105
+ content_type: str = "audio/wav",
106
+ ) -> RestTranscriptionResult:
107
+ return self.transcribe(
108
+ bytes(audio),
109
+ language=language,
110
+ enable_cap_punc=enable_cap_punc,
111
+ api_key=api_key,
112
+ filename=filename,
113
+ content_type=content_type,
114
+ )
115
+
116
+ def _transcribe_fileobj(
117
+ self,
118
+ fileobj: BinaryIO,
119
+ *,
120
+ language: str = "hi",
121
+ enable_cap_punc: bool = True,
122
+ api_key: str | None = None,
123
+ filename: str | None = None,
124
+ content_type: str = "audio/wav",
125
+ ) -> RestTranscriptionResult:
126
+ return self.transcribe(
127
+ fileobj,
128
+ language=language,
129
+ enable_cap_punc=enable_cap_punc,
130
+ api_key=api_key,
131
+ filename=filename,
132
+ content_type=content_type,
133
+ )
134
+
135
+ def _open_stream(self, options: StreamOptions, *, api_key: str | None = None) -> StreamSession:
136
+ start_config = options.to_start_config()
137
+ return StreamSession(
138
+ client_config=self.config,
139
+ start_config=start_config,
140
+ api_key_override=api_key,
141
+ )
142
+
143
+ def stream(
144
+ self,
145
+ *,
146
+ sample_rate: int = 16000,
147
+ encoding: str = "int16",
148
+ language: str = "hi",
149
+ mode: str = "stream",
150
+ vad_tail_sil_ms: int = 200,
151
+ vad_confidence: float = 0.55,
152
+ enable_cap_punc: bool = True,
153
+ accept_client_vad_events: bool = False,
154
+ api_key: str | None = None,
155
+ ) -> StreamSession:
156
+ """Create a stream session with high-level options."""
157
+ return self._open_stream(
158
+ StreamOptions(
159
+ sample_rate=sample_rate,
160
+ encoding=encoding,
161
+ language=language,
162
+ mode=mode,
163
+ vad_tail_sil_ms=vad_tail_sil_ms,
164
+ vad_confidence=vad_confidence,
165
+ enable_cap_punc=enable_cap_punc,
166
+ accept_client_vad_events=accept_client_vad_events,
167
+ api_key=api_key,
168
+ ),
169
+ api_key=api_key,
170
+ )
@@ -0,0 +1,131 @@
1
+ """Configuration objects for SDK clients."""
2
+
3
+ from dataclasses import dataclass, field
4
+ from typing import Mapping
5
+ from urllib.parse import urljoin, urlparse, urlunparse
6
+
7
+ import httpx
8
+
9
+
10
+ def _normalize_base_url(base_url: str) -> str:
11
+ parsed = urlparse(base_url)
12
+ if parsed.scheme not in {"http", "https", "ws", "wss"}:
13
+ raise ValueError(f"Unsupported base_url scheme: {parsed.scheme!r}")
14
+ if not parsed.netloc:
15
+ raise ValueError("base_url must include host, e.g. http://localhost:7860")
16
+ return urlunparse((parsed.scheme, parsed.netloc, "", "", "", ""))
17
+
18
+
19
+ def _to_ws_url(url: str) -> str:
20
+ parsed = urlparse(url)
21
+ if parsed.scheme not in {"http", "https", "ws", "wss"}:
22
+ raise ValueError(f"Unsupported ws URL scheme: {parsed.scheme!r}")
23
+ if parsed.scheme in {"http", "ws"}:
24
+ scheme = "ws"
25
+ else:
26
+ scheme = "wss"
27
+ path = parsed.path or "/"
28
+ return urlunparse((scheme, parsed.netloc, path, parsed.params, parsed.query, parsed.fragment))
29
+
30
+
31
+ def _to_http_url(url: str) -> str:
32
+ parsed = urlparse(url)
33
+ if parsed.scheme not in {"http", "https", "ws", "wss"}:
34
+ raise ValueError(f"Unsupported http URL scheme: {parsed.scheme!r}")
35
+ if parsed.scheme in {"ws", "http"}:
36
+ scheme = "http"
37
+ else:
38
+ scheme = "https"
39
+ path = parsed.path or "/"
40
+ return urlunparse((scheme, parsed.netloc, path, parsed.params, parsed.query, parsed.fragment))
41
+
42
+
43
+ def _to_http_origin(url: str) -> str:
44
+ parsed = urlparse(url)
45
+ if parsed.scheme not in {"http", "https", "ws", "wss"}:
46
+ raise ValueError(f"Unsupported http URL scheme: {parsed.scheme!r}")
47
+ if parsed.scheme in {"ws", "http"}:
48
+ scheme = "http"
49
+ else:
50
+ scheme = "https"
51
+ return urlunparse((scheme, parsed.netloc, "", "", "", ""))
52
+
53
+
54
+ @dataclass(slots=True)
55
+ class TimeoutConfig:
56
+ """Timeouts used by REST and WebSocket operations."""
57
+
58
+ connect: float = 10.0
59
+ read: float = 10.0
60
+ write: float = 10.0
61
+ pool: float = 10.0
62
+ ws_open: float = 10.0
63
+ ws_recv: float = 30.0
64
+ ws_close: float = 10.0
65
+
66
+ def as_httpx_timeout(self) -> httpx.Timeout:
67
+ return httpx.Timeout(
68
+ timeout=None,
69
+ connect=self.connect,
70
+ read=self.read,
71
+ write=self.write,
72
+ pool=self.pool,
73
+ )
74
+
75
+
76
+ @dataclass(slots=True)
77
+ class ClientConfig:
78
+ """Client-level configuration and defaults."""
79
+
80
+ base_url: str | None = None
81
+ api_key: str | None = None
82
+ timeout: TimeoutConfig = field(default_factory=TimeoutConfig)
83
+ rest_endpoint: str | None = None
84
+ ws_endpoint: str | None = None
85
+ rest_path: str = "/parrot-stt/v1/transcriptions"
86
+ ws_path: str = "/parrot-stt/v1/stream"
87
+ default_headers: Mapping[str, str] | None = None
88
+
89
+ def __post_init__(self) -> None:
90
+ if self.base_url is None and self.rest_endpoint is None and self.ws_endpoint is None:
91
+ raise ValueError(
92
+ "Provide at least one of: base_url, rest_endpoint, ws_endpoint"
93
+ )
94
+ if self.base_url is not None:
95
+ self.base_url = _normalize_base_url(self.base_url)
96
+ if self.rest_endpoint is not None:
97
+ self.rest_endpoint = _to_http_url(self.rest_endpoint)
98
+ if self.ws_endpoint is not None:
99
+ self.ws_endpoint = _to_ws_url(self.ws_endpoint)
100
+
101
+ @staticmethod
102
+ def _join(base: str, path: str) -> str:
103
+ root = base if base.endswith("/") else f"{base}/"
104
+ rel = path[1:] if path.startswith("/") else path
105
+ return urljoin(root, rel)
106
+
107
+ @property
108
+ def rest_url(self) -> str:
109
+ if self.rest_endpoint is not None:
110
+ return self.rest_endpoint
111
+ assert self.base_url is not None
112
+ return _to_http_url(self._join(self.base_url, self.rest_path))
113
+
114
+ @property
115
+ def ws_url(self) -> str:
116
+ if self.ws_endpoint is not None:
117
+ return self.ws_endpoint
118
+ assert self.base_url is not None
119
+ return _to_ws_url(self._join(self.base_url, self.ws_path))
120
+
121
+ @property
122
+ def health_url(self) -> str:
123
+ if self.base_url is not None:
124
+ return _to_http_url(self._join(self.base_url, "/health"))
125
+ if self.rest_endpoint is not None:
126
+ return _to_http_url(self._join(_to_http_origin(self.rest_endpoint), "/health"))
127
+ assert self.ws_endpoint is not None
128
+ return _to_http_url(self._join(_to_http_origin(self.ws_endpoint), "/health"))
129
+
130
+ def resolve_api_key(self, override: str | None = None) -> str | None:
131
+ return override if override is not None else self.api_key
ringglabs/stt/enums.py ADDED
@@ -0,0 +1,25 @@
1
+ """Enum types for RinggLabs STT SDK."""
2
+
3
+ from enum import Enum
4
+
5
+
6
+ class Language(str, Enum):
7
+ HI = "hi"
8
+ EN = "en"
9
+
10
+
11
+ class Mode(str, Enum):
12
+ STREAM = "stream"
13
+ ON_FINAL = "on_final"
14
+
15
+
16
+ class Encoding(str, Enum):
17
+ INT16 = "int16"
18
+ LINEAR16 = "linear16"
19
+ FLOAT32 = "float32"
20
+ INT32 = "int32"
21
+
22
+
23
+ class VadState(str, Enum):
24
+ USER_START_SPEAKING = "user_start_speaking"
25
+ USER_STOP_SPEAKING = "user_stop_speaking"
@@ -0,0 +1,46 @@
1
+ """Error taxonomy for RinggLabs STT SDK."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+
6
+
7
+ class RinggLabsError(Exception):
8
+ """Base exception for all SDK errors."""
9
+
10
+
11
+ class ValidationError(RinggLabsError):
12
+ """Raised for invalid SDK input values or types."""
13
+
14
+
15
+ @dataclass(slots=True)
16
+ class ApiError(RinggLabsError):
17
+ """Raised when server returns an error payload or non-2xx HTTP response."""
18
+
19
+ message: str
20
+ status_code: int | None = None
21
+ code: str | None = None
22
+ payload: dict[str, Any] | None = None
23
+
24
+ def __str__(self) -> str:
25
+ details = [self.message]
26
+ if self.code:
27
+ details.append(f"code={self.code}")
28
+ if self.status_code is not None:
29
+ details.append(f"status={self.status_code}")
30
+ return " | ".join(details)
31
+
32
+
33
+ class TransportError(RinggLabsError):
34
+ """Raised on network failures."""
35
+
36
+
37
+ class TimeoutError(TransportError):
38
+ """Raised when a request or receive operation times out."""
39
+
40
+
41
+ class ProtocolError(RinggLabsError):
42
+ """Raised for incompatible or malformed server messages."""
43
+
44
+
45
+ class AuthenticationError(ApiError):
46
+ """Raised for authentication-related server responses."""