Translate PDF: Improve response types

- `TranslatePdfTextResponse` gets missing `source_languages` and `output_language` fields.
- Adds `TranslatePdfTextFileResponse`. This inherits from `PdfRestFileBasedResponse` with additional Translate PDF fields.
- Add `FileBasedResponse` TypeVar bound to `PdfRestFileBasedResponse` so classes like `TranslatePdfTextFileResponse` can reuse file fetch logic.

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -69,12 +69,10 @@
     PdfRestFileID,
     PdfRestInfoResponse,
     SummarizePdfTextResponse,
+    TranslatePdfTextFileResponse,
     TranslatePdfTextResponse,
     UpResponse,
 )
-
-__all__ = ("AsyncPdfRestClient", "PdfRestClient")
-
 from .models._internal import (
     BasePdfRestGraphicPayload,
     BmpPdfRestPayload,
@@ -122,6 +120,9 @@
     TranslateOutputFormat,
 )
 
+__all__ = ("AsyncPdfRestClient", "PdfRestClient")
+FileResponseModel = TypeVar("FileResponseModel", bound=PdfRestFileBasedResponse)
+
 DEFAULT_BASE_URL = "https://api.pdfrest.com"
 API_KEY_ENV_VAR = "PDFREST_API_KEY"
 API_KEY_HEADER_NAME = "Api-Key"
@@ -986,11 +987,12 @@ def _post_file_operation(
         endpoint: str,
         payload: dict[str, Any],
         payload_model: type[BaseModel],
+        response_model: type[FileResponseModel] = PdfRestFileBasedResponse,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
-    ) -> PdfRestFileBasedResponse:
+    ) -> FileResponseModel:
         job_options = payload_model.model_validate(payload)
         json_body = job_options.model_dump(
             mode="json", by_alias=True, exclude_none=True, exclude_unset=True
@@ -1018,15 +1020,17 @@ def _post_file_operation(
             for file_id in output_ids
         ]
 
-        return PdfRestFileBasedResponse.model_validate(
-            {
-                "input_id": [str(file_id) for file_id in raw_response.input_id],
-                "output_file": [
-                    file.model_dump(mode="json", by_alias=True) for file in output_files
-                ],
-                "warning": raw_response.warning,
-            }
-        )
+        response_payload: dict[str, Any] = {
+            "input_id": [str(file_id) for file_id in raw_response.input_id],
+            "output_file": [
+                file.model_dump(mode="json", by_alias=True) for file in output_files
+            ],
+            "warning": raw_response.warning,
+        }
+        if raw_response.model_extra:
+            response_payload.update(raw_response.model_extra)
+
+        return response_model.model_validate(response_payload)
 
     def send_request(self, request: _RequestModel) -> Any:
         return self._send_request(request)
@@ -1250,11 +1254,12 @@ async def _post_file_operation(
         endpoint: str,
         payload: dict[str, Any],
         payload_model: type[BaseModel],
+        response_model: type[FileResponseModel] = PdfRestFileBasedResponse,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
-    ) -> PdfRestFileBasedResponse:
+    ) -> FileResponseModel:
         job_options = payload_model.model_validate(payload)
         request = self.prepare_request(
             "POST",
@@ -1290,15 +1295,17 @@ async def throttled_fetch_file_info(file_id: str) -> PdfRestFile:
                 )
             )
 
-        return PdfRestFileBasedResponse.model_validate(
-            {
-                "input_id": [str(file_id) for file_id in raw_response.input_id],
-                "output_file": [
-                    file.model_dump(mode="json", by_alias=True) for file in output_files
-                ],
-                "warning": raw_response.warning,
-            }
-        )
+        response_payload: dict[str, Any] = {
+            "input_id": [str(file_id) for file_id in raw_response.input_id],
+            "output_file": [
+                file.model_dump(mode="json", by_alias=True) for file in output_files
+            ],
+            "warning": raw_response.warning,
+        }
+        if raw_response.model_extra:
+            response_payload.update(raw_response.model_extra)
+
+        return response_model.model_validate(response_payload)
 
     async def send_request(self, request: _RequestModel) -> Any:
         return await self._send_request(request)
@@ -2334,7 +2341,7 @@ def translate_pdf_text_to_file(
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
-    ) -> PdfRestFileBasedResponse:
+    ) -> TranslatePdfTextFileResponse:
         """Translate textual content and receive a file-based response."""
 
         payload: dict[str, Any] = {
@@ -2356,6 +2363,7 @@ def translate_pdf_text_to_file(
             extra_headers=extra_headers,
             extra_body=extra_body,
             timeout=timeout,
+            response_model=TranslatePdfTextFileResponse,
         )
 
     def extract_images(
@@ -3323,7 +3331,7 @@ async def translate_pdf_text_to_file(
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
-    ) -> PdfRestFileBasedResponse:
+    ) -> TranslatePdfTextFileResponse:
         """Translate textual content and receive a file-based response."""
 
         payload: dict[str, Any] = {
@@ -3345,6 +3353,7 @@ async def translate_pdf_text_to_file(
             extra_headers=extra_headers,
             extra_body=extra_body,
             timeout=timeout,
+            response_model=TranslatePdfTextFileResponse,
         )
 
     async def extract_images(

src/pdfrest/models/__init__.py

@@ -8,6 +8,7 @@
     PdfRestFileID,
     PdfRestInfoResponse,
     SummarizePdfTextResponse,
+    TranslatePdfTextFileResponse,
     TranslatePdfTextResponse,
     UpResponse,
 )
@@ -22,6 +23,7 @@
     "PdfRestFileID",
     "PdfRestInfoResponse",
     "SummarizePdfTextResponse",
+    "TranslatePdfTextFileResponse",
     "TranslatePdfTextResponse",
     "UpResponse",
 ]

src/pdfrest/models/public.py

@@ -29,6 +29,7 @@
     "PdfRestFileID",
     "PdfRestInfoResponse",
     "SummarizePdfTextResponse",
+    "TranslatePdfTextFileResponse",
     "TranslatePdfTextResponse",
     "UpResponse",
 )
@@ -360,6 +361,24 @@ class TranslatePdfTextResponse(BaseModel):
 
     model_config = ConfigDict(extra="allow")
 
+    source_languages: Annotated[
+        list[str] | None,
+        Field(
+            alias="source_languages",
+            validation_alias=AliasChoices("source_languages", "sourceLanguages"),
+            description="Languages detected in the source content.",
+            default=None,
+        ),
+    ] = None
+    output_language: Annotated[
+        str | None,
+        Field(
+            alias="output_language",
+            validation_alias=AliasChoices("output_language", "outputLanguage"),
+            description="Target language used for the translation.",
+            default=None,
+        ),
+    ] = None
     translated_text: Annotated[
         str | None,
         Field(
@@ -396,6 +415,31 @@ class TranslatePdfTextResponse(BaseModel):
     ] = None
 
 
+class TranslatePdfTextFileResponse(PdfRestFileBasedResponse):
+    """File-based response returned by the translated-pdf-text tool."""
+
+    model_config = ConfigDict(extra="allow")
+
+    source_languages: Annotated[
+        list[str] | None,
+        Field(
+            alias="source_languages",
+            validation_alias=AliasChoices("source_languages", "sourceLanguages"),
+            description="Languages detected in the source content.",
+            default=None,
+        ),
+    ] = None
+    output_language: Annotated[
+        str | None,
+        Field(
+            alias="output_language",
+            validation_alias=AliasChoices("output_language", "outputLanguage"),
+            description="Target language used for the translation.",
+            default=None,
+        ),
+    ] = None
+
+
 class ExtractTextResponse(BaseModel):
     """Response returned by the extracted-text tool."""
 

tests/live/test_live_translate_pdf_text.py

@@ -3,7 +3,10 @@
 import pytest
 
 from pdfrest import PdfRestApiError, PdfRestClient
-from pdfrest.models import PdfRestFileBasedResponse, TranslatePdfTextResponse
+from pdfrest.models import (
+    TranslatePdfTextFileResponse,
+    TranslatePdfTextResponse,
+)
 
 from ..resources import get_test_resource_path
 
@@ -26,6 +29,8 @@ def test_live_translate_pdf_text_success(
 
     assert isinstance(response, TranslatePdfTextResponse)
     assert response.translated_text
+    assert response.output_language == "fr"
+    assert response.source_languages
     assert response.input_id == uploaded.id
 
 
@@ -63,6 +68,8 @@ def test_live_translate_pdf_text_file_success(
             output_format="plaintext",
         )
 
-    assert isinstance(response, PdfRestFileBasedResponse)
+    assert isinstance(response, TranslatePdfTextFileResponse)
     assert response.output_files
+    assert response.output_language == "fr"
+    assert response.source_languages
     assert response.input_id == uploaded.id

tests/test_translate_pdf_text.py

@@ -9,8 +9,8 @@
 from pdfrest import AsyncPdfRestClient, PdfRestClient
 from pdfrest.models import (
     PdfRestFile,
-    PdfRestFileBasedResponse,
     PdfRestFileID,
+    TranslatePdfTextFileResponse,
     TranslatePdfTextResponse,
 )
 from pdfrest.models._internal import TranslatePdfTextPayload
@@ -86,6 +86,8 @@ def handler(request: httpx.Request) -> httpx.Response:
                 json={
                     "translated_text": "Bonjour",
                     "inputId": str(input_file.id),
+                    "source_languages": ["en"],
+                    "output_language": "fr",
                 },
             )
         msg = f"Unexpected request {request.method} {request.url}"
@@ -104,6 +106,8 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert seen == {"post": 1}
     assert isinstance(response, TranslatePdfTextResponse)
     assert response.translated_text == "Bonjour"
+    assert response.source_languages == ["en"]
+    assert response.output_language == "fr"
     assert response.input_id == input_file.id
     assert response.output_id is None
     assert response.output_url is None
@@ -140,6 +144,8 @@ def handler(request: httpx.Request) -> httpx.Response:
                     "outputUrl": f"https://api.pdfrest.com/resource/{output_id}?format=file",
                     "outputId": output_id,
                     "inputId": str(input_file.id),
+                    "source_languages": ["en"],
+                    "output_language": "es",
                 },
             )
         if request.method == "GET" and request.url.path == f"/resource/{output_id}":
@@ -166,8 +172,10 @@ def handler(request: httpx.Request) -> httpx.Response:
             timeout=0.3,
         )
 
-    assert isinstance(response, PdfRestFileBasedResponse)
+    assert isinstance(response, TranslatePdfTextFileResponse)
     assert response.output_file.id == output_id
+    assert response.output_language == "es"
+    assert response.source_languages == ["en"]
     timeout_value = captured_timeout["value"]
     assert timeout_value is not None
     if isinstance(timeout_value, dict):
@@ -201,6 +209,8 @@ def handler(request: httpx.Request) -> httpx.Response:
                 json={
                     "translated_text": "Hallo",
                     "inputId": str(input_file.id),
+                    "source_languages": ["en"],
+                    "output_language": "de",
                 },
             )
         msg = f"Unexpected request {request.method} {request.url}"
@@ -216,4 +226,6 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert seen == {"post": 1}
     assert isinstance(response, TranslatePdfTextResponse)
     assert response.translated_text == "Hallo"
+    assert response.source_languages == ["en"]
+    assert response.output_language == "de"
     assert response.input_id == input_file.id