Split Summarize PDF method by response file type

- Add additional method to summarize to output file
- Use PdfRestFileBasedResponse for summarize to file

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -60,9 +60,9 @@
     translate_httpx_error,
 )
 from .models import (
-    PdfRestDeletionResponse,
     ConvertToMarkdownResponse,
     ExtractTextResponse,
+    PdfRestDeletionResponse,
     PdfRestErrorResponse,
     PdfRestFile,
     PdfRestFileBasedResponse,
@@ -78,14 +78,14 @@
 from .models._internal import (
     BasePdfRestGraphicPayload,
     BmpPdfRestPayload,
-    DeletePayload,
     ConvertToMarkdownPayload,
+    DeletePayload,
     ExtractImagesPayload,
     ExtractTextPayload,
     GifPdfRestPayload,
     JpegPdfRestPayload,
-    PdfCompressPayload,
     OcrPdfPayload,
+    PdfCompressPayload,
     PdfFlattenAnnotationsPayload,
     PdfFlattenFormsPayload,
     PdfFlattenTransparenciesPayload,
@@ -2134,21 +2134,24 @@ def summarize_pdf_text(
         summary_format: SummaryFormat = "overview",
         pages: PdfPageSelection | None = None,
         output_format: SummaryOutputFormat = "markdown",
-        output_type: SummaryOutputType = "json",
         output: str | None = None,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> SummarizePdfTextResponse:
-        """Summarize the textual content of a PDF, Markdown, or text document."""
+        """Summarize the textual content of a PDF, Markdown, or text document.
+
+        Always requests JSON output and returns the inline summary response defined in
+        the pdfRest API reference.
+        """
 
         payload: dict[str, Any] = {
             "files": file,
             "target_word_count": target_word_count,
             "summary_format": summary_format,
             "output_format": output_format,
-            "output_type": output_type,
+            "output_type": "json",
         }
         if pages is not None:
             payload["pages"] = pages
@@ -2170,6 +2173,44 @@ def summarize_pdf_text(
         raw_payload = self._send_request(request)
         return SummarizePdfTextResponse.model_validate(raw_payload)
 
+    def summarize_pdf_text_to_file(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        target_word_count: int | None = 400,
+        summary_format: SummaryFormat = "overview",
+        pages: PdfPageSelection | None = None,
+        output_format: SummaryOutputFormat = "markdown",
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Summarize a document and return the result as a downloadable file."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "target_word_count": target_word_count,
+            "summary_format": summary_format,
+            "output_format": output_format,
+            "output_type": "file",
+        }
+        if pages is not None:
+            payload["pages"] = pages
+        if output is not None:
+            payload["output"] = output
+
+        return self._post_file_operation(
+            endpoint="/summarized-pdf-text",
+            payload=payload,
+            payload_model=SummarizePdfTextPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def convert_to_markdown(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -2668,7 +2709,6 @@ def compress_pdf(
             extra_body=extra_body,
             timeout=timeout,
         )
-        
 
     def flatten_transparencies(
         self,
@@ -3083,21 +3123,24 @@ async def summarize_pdf_text(
         summary_format: SummaryFormat = "overview",
         pages: PdfPageSelection | None = None,
         output_format: SummaryOutputFormat = "markdown",
-        output_type: SummaryOutputType = "json",
         output: str | None = None,
         extra_query: Query | None = None,
         extra_headers: AnyMapping | None = None,
         extra_body: Body | None = None,
         timeout: TimeoutTypes | None = None,
     ) -> SummarizePdfTextResponse:
-        """Summarize the textual content of a PDF, Markdown, or text document."""
+        """Summarize the textual content of a PDF, Markdown, or text document.
+
+        Always requests JSON output and returns the inline summary response defined in
+        the pdfRest API reference.
+        """
 
         payload: dict[str, Any] = {
             "files": file,
             "target_word_count": target_word_count,
             "summary_format": summary_format,
             "output_format": output_format,
-            "output_type": output_type,
+            "output_type": "json",
         }
         if pages is not None:
             payload["pages"] = pages
@@ -3119,6 +3162,44 @@ async def summarize_pdf_text(
         raw_payload = await self._send_request(request)
         return SummarizePdfTextResponse.model_validate(raw_payload)
 
+    async def summarize_pdf_text_to_file(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        target_word_count: int | None = 400,
+        summary_format: SummaryFormat = "overview",
+        pages: PdfPageSelection | None = None,
+        output_format: SummaryOutputFormat = "markdown",
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Summarize a document and return the result as a downloadable file."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "target_word_count": target_word_count,
+            "summary_format": summary_format,
+            "output_format": output_format,
+            "output_type": "file",
+        }
+        if pages is not None:
+            payload["pages"] = pages
+        if output is not None:
+            payload["output"] = output
+
+        return await self._post_file_operation(
+            endpoint="/summarized-pdf-text",
+            payload=payload,
+            payload_model=SummarizePdfTextPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def convert_to_markdown(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3659,7 +3740,6 @@ async def compress_pdf(
             extra_body=extra_body,
             timeout=timeout,
         )
-        
 
     async def flatten_transparencies(
         self,
@@ -3687,7 +3767,7 @@ async def flatten_transparencies(
             extra_body=extra_body,
             timeout=timeout,
         )
-        
+
     async def linearize_pdf(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],

src/pdfrest/models/__init__.py

@@ -1,7 +1,7 @@
 from .public import (
-    PdfRestDeletionResponse,
     ConvertToMarkdownResponse,
     ExtractTextResponse,
+    PdfRestDeletionResponse,
     PdfRestErrorResponse,
     PdfRestFile,
     PdfRestFileBasedResponse,
@@ -13,9 +13,9 @@
 )
 
 __all__ = [
-    "PdfRestDeletionResponse",
     "ConvertToMarkdownResponse",
     "ExtractTextResponse",
+    "PdfRestDeletionResponse",
     "PdfRestErrorResponse",
     "PdfRestFile",
     "PdfRestFileBasedResponse",

src/pdfrest/models/public.py

@@ -20,9 +20,9 @@
 from typing_extensions import override
 
 __all__ = (
-    "PdfRestDeletionResponse",
     "ConvertToMarkdownResponse",
     "ExtractTextResponse",
+    "PdfRestDeletionResponse",
     "PdfRestErrorResponse",
     "PdfRestFile",
     "PdfRestFileBasedResponse",
@@ -314,6 +314,8 @@ class PdfRestDeletionResponse(BaseModel):
             min_length=1,
         ),
     ]
+
+
 class SummarizePdfTextResponse(BaseModel):
     """Response returned by the summarize-pdf-text tool."""
 

tests/live/test_live_summarize_pdf_text.py

@@ -3,7 +3,7 @@
 import pytest
 
 from pdfrest import PdfRestApiError, PdfRestClient
-from pdfrest.models import SummarizePdfTextResponse
+from pdfrest.models import PdfRestFileBasedResponse, SummarizePdfTextResponse
 
 from ..resources import get_test_resource_path
 
@@ -21,7 +21,6 @@ def test_live_summarize_pdf_text_success(
         response = client.summarize_pdf_text(
             uploaded,
             target_word_count=40,
-            output_type="json",
             summary_format="overview",
         )
 
@@ -30,6 +29,28 @@ def test_live_summarize_pdf_text_success(
     assert response.input_id == uploaded.id
 
 
+def test_live_summarize_pdf_text_to_file_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    resource = get_test_resource_path("report.pdf")
+    with PdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        uploaded = client.files.create_from_paths([resource])[0]
+        response = client.summarize_pdf_text_to_file(
+            uploaded,
+            target_word_count=40,
+            summary_format="overview",
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_files
+    assert response.output_file.id
+    assert response.input_id == uploaded.id
+
+
 def test_live_summarize_pdf_text_invalid_format(
     pdfrest_api_key: str,
     pdfrest_live_base_url: str,