refactor: return a structured TranscriptionResult from transcription

Replace the loosely typed Any return (a dict or a str depending on the
response format) with a TranscriptionResult dataclass exposing two fields:
json (set for json / verbose_json formats) and text (set for text / srt / vtt
formats). This gives the transcription method a single explicit return type and
keeps it uniform with the other otari SDKs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: njbrake

README.md

@@ -263,7 +263,7 @@ result = client.transcription(
     model="openai:whisper-1",
     file=Path("speech.mp3").read_bytes(),
 )
-print(result["text"])
+print(result.json["text"])
 ```
 
 ### Batch operations

src/otari/__init__.py

@@ -51,6 +51,7 @@
     ModerationResponse,
     OtariClientOptions,
     RerankResponse,
+    TranscriptionResult,
 )
 
 try:
@@ -84,6 +85,7 @@
     "OtariError",
     "RateLimitError",
     "RerankResponse",
+    "TranscriptionResult",
     "UnsupportedCapabilityError",
     "UpstreamProviderError",
 ]

src/otari/async_client.py

@@ -69,6 +69,7 @@
         BatchResult,
         CreateBatchParams,
         ListBatchesOptions,
+        TranscriptionResult,
     )
 
 
@@ -367,11 +368,12 @@ async def transcription(
         file: bytes,
         filename: str = "audio",
         **kwargs: Any,
-    ) -> Any:
+    ) -> TranscriptionResult:
         """Transcribe audio to text.
 
         ``file`` is the raw audio bytes uploaded as multipart form data. Returns
-        the parsed JSON (a dict) for JSON response formats, or the raw text for
+        a :class:`~otari.types.TranscriptionResult` whose ``json`` field is set
+        for JSON response formats and whose ``text`` field is set for the
         ``text`` / ``srt`` / ``vtt`` formats.
 
         Args:
@@ -382,12 +384,14 @@ async def transcription(
             **kwargs: Additional parameters (``language``, ``prompt``,
                 ``response_format``, ``temperature``, ``user``).
         """
+        from otari.types import TranscriptionResult  # noqa: PLC0415
+
         data = {"model": model, **{key: str(value) for key, value in kwargs.items()}}
         files = {"file": (filename, file)}
         response = await self._post("/audio/transcriptions", data=data, files=files)
         if "application/json" in response.headers.get("content-type", ""):
-            return response.json()
-        return response.text
+            return TranscriptionResult(json=response.json())
+        return TranscriptionResult(text=response.text)
 
     # -- Models -------------------------------------------------------------
 

src/otari/client.py

@@ -69,6 +69,7 @@
         BatchResult,
         CreateBatchParams,
         ListBatchesOptions,
+        TranscriptionResult,
     )
 
 
@@ -391,11 +392,12 @@ def transcription(
         file: bytes,
         filename: str = "audio",
         **kwargs: Any,
-    ) -> Any:
+    ) -> TranscriptionResult:
         """Transcribe audio to text.
 
         ``file`` is the raw audio bytes uploaded as multipart form data. Returns
-        the parsed JSON (a dict) for JSON response formats, or the raw text for
+        a :class:`~otari.types.TranscriptionResult` whose ``json`` field is set
+        for JSON response formats and whose ``text`` field is set for the
         ``text`` / ``srt`` / ``vtt`` formats.
 
         Args:
@@ -406,12 +408,14 @@ def transcription(
             **kwargs: Additional parameters (``language``, ``prompt``,
                 ``response_format``, ``temperature``, ``user``).
         """
+        from otari.types import TranscriptionResult  # noqa: PLC0415
+
         data = {"model": model, **{key: str(value) for key, value in kwargs.items()}}
         files = {"file": (filename, file)}
         response = self._post("/audio/transcriptions", data=data, files=files)
         if "application/json" in response.headers.get("content-type", ""):
-            return response.json()
-        return response.text
+            return TranscriptionResult(json=response.json())
+        return TranscriptionResult(text=response.text)
 
     # -- Models -------------------------------------------------------------
 

src/otari/types.py

@@ -109,3 +109,24 @@ class BatchResult:
     """Aggregated results of a completed batch job."""
 
     results: list[BatchResultItem] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Audio types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TranscriptionResult:
+    """Result of an audio transcription request.
+
+    Exactly one field is populated, chosen by the gateway response's content
+    type: ``json`` for the default ``json`` / ``verbose_json`` formats, ``text``
+    for the plain ``text`` / ``srt`` / ``vtt`` formats.
+    """
+
+    json: dict[str, Any] | None = None
+    """Parsed JSON response, for ``json`` / ``verbose_json`` formats."""
+
+    text: str | None = None
+    """Raw text response, for ``text`` / ``srt`` / ``vtt`` formats."""

tests/unit/test_async_client.py

@@ -208,7 +208,8 @@ async def test_transcription_returns_json(self) -> None:
         )
         client = AsyncOtariClient(api_base="http://localhost:8000", api_key="vk")
         result = await client.transcription(model="openai:whisper-1", file=b"\x00\x01")
-        assert result == TRANSCRIPTION_RESPONSE
+        assert result.json == TRANSCRIPTION_RESPONSE
+        assert result.text is None
         request = route.calls.last.request
         assert request.headers["content-type"].startswith("multipart/form-data")
         assert b'name="file"' in request.content

tests/unit/test_client.py

@@ -433,7 +433,8 @@ def test_transcription_returns_json(self) -> None:
         )
         client = OtariClient(api_base="http://localhost:8000", api_key="vk")
         result = client.transcription(model="openai:whisper-1", file=b"\x00\x01")
-        assert result == TRANSCRIPTION_RESPONSE
+        assert result.json == TRANSCRIPTION_RESPONSE
+        assert result.text is None
         request = route.calls.last.request
         assert request.headers["content-type"].startswith("multipart/form-data")
         assert b'name="model"' in request.content
@@ -450,7 +451,8 @@ def test_transcription_returns_text(self) -> None:
         result = client.transcription(
             model="m", file=b"\x00", response_format="text"
         )
-        assert result == "hello"
+        assert result.text == "hello"
+        assert result.json is None
 
 
 # ---------------------------------------------------------------------------