sarvamai 0.1.23a6__py3-none-any.whl → 0.1.23a8__py3-none-any.whl

sarvamai/doc_digitization_job/client.py

@@ -0,0 +1,776 @@
+# This file was auto-generated by Fern from our API Definition.
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.request_options import RequestOptions
+from ..requests.doc_digitization_job_parameters import (
+    DocDigitizationJobParametersParams,
+)
+from ..requests.doc_digitization_webhook_callback import (
+    DocDigitizationWebhookCallbackParams,
+)
+from ..types.doc_digitization_create_job_response import (
+    DocDigitizationCreateJobResponse,
+)
+from ..types.doc_digitization_download_files_response import (
+    DocDigitizationDownloadFilesResponse,
+)
+from ..types.doc_digitization_job_status_response import (
+    DocDigitizationJobStatusResponse,
+)
+from ..types.doc_digitization_upload_files_response import (
+    DocDigitizationUploadFilesResponse,
+)
+from ..types.doc_digitization_supported_language import DocDigitizationSupportedLanguage
+from ..types.doc_digitization_output_format import DocDigitizationOutputFormat
+from .raw_client import AsyncRawDocDigitizationJobClient, RawDocDigitizationJobClient
+from .job import DocDigitizationJob, AsyncDocDigitizationJob
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class DocDigitizationJobClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._raw_client = RawDocDigitizationJobClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> RawDocDigitizationJobClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        RawDocDigitizationJobClient
+        """
+        return self._raw_client
+
+    def initialise(
+        self,
+        *,
+        job_parameters: typing.Optional[DocDigitizationJobParametersParams] = OMIT,
+        callback: typing.Optional[DocDigitizationWebhookCallbackParams] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DocDigitizationCreateJobResponse:
+        """
+        Creates a new document digitization job.
+
+        **Supported Languages:**
+        - `hi`: Hindi
+        - `en`: English
+        - `bn`: Bengali
+        - `gu`: Gujarati
+        - `kn`: Kannada
+        - `ml`: Malayalam
+        - `mr`: Marathi
+        - `or`: Odia
+        - `pa`: Punjabi
+        - `ta`: Tamil
+        - `te`: Telugu
+        - `ur`: Urdu
+        - `as`: Assamese
+        - `bodo`: Bodo
+        - `doi`: Dogri
+        - `ks`: Kashmiri
+        - `kok`: Konkani
+        - `mai`: Maithili
+        - `mni`: Manipuri
+        - `ne`: Nepali
+        - `sa`: Sanskrit
+        - `sat`: Santali
+        - `sd`: Sindhi
+
+        **Output Formats:**
+        - `html`: Structured HTML with layout preservation (default)
+        - `md`: Markdown format
+
+        **Webhook Callback:**
+        Optionally provide a callback URL to receive notification when processing completes.
+
+        Parameters
+        ----------
+        job_parameters : typing.Optional[DocDigitizationJobParametersParams]
+            Job configuration parameters. Omit the request body to use defaults.
+
+        callback : typing.Optional[DocDigitizationWebhookCallbackParams]
+            Optional webhook for completion notification
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationCreateJobResponse
+            Successful Response
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+        client.doc_digitization_job.initialise()
+        """
+        _response = self._raw_client.initialise(
+            job_parameters=job_parameters,
+            callback=callback,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def get_upload_links(
+        self,
+        *,
+        job_id: str,
+        files: typing.Sequence[str],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DocDigitizationUploadFilesResponse:
+        """
+        Returns presigned URLs for uploading input files.
+
+        **File Constraints:**
+        - Exactly one file required (PDF or ZIP)
+        - PDF files: `.pdf` extension
+        - ZIP files: `.zip` extension
+
+        Parameters
+        ----------
+        job_id : str
+            Job identifier returned from Create Job
+
+        files : typing.Sequence[str]
+            List of filenames to upload (exactly 1 file: PDF or ZIP)
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationUploadFilesResponse
+            Successful Response
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+        client.doc_digitization_job.get_upload_links(
+            job_id="job_id",
+            files=["files"],
+        )
+        """
+        _response = self._raw_client.get_upload_links(
+            job_id=job_id, files=files, request_options=request_options
+        )
+        return _response.data
+
+    def start(
+        self, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DocDigitizationJobStatusResponse:
+        """
+        Validates the uploaded file and starts processing.
+
+        **Validation Checks:**
+        - File must be uploaded before starting
+        - File size must not exceed 200 MB
+        - PDF must be parseable by the PDF parser
+        - ZIP must contain only JPEG/PNG images
+        - ZIP must be flat (no nested folders beyond one level)
+        - ZIP must contain at least one valid image
+        - Page/image count must not exceed 500
+        - User must have sufficient credits
+
+        **Processing:**
+        Job runs asynchronously. Poll the status endpoint or use webhook callback for completion notification.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationJobStatusResponse
+            Successful Response
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+        client.doc_digitization_job.start(
+            job_id="job_id",
+        )
+        """
+        _response = self._raw_client.start(job_id, request_options=request_options)
+        return _response.data
+
+    def get_status(
+        self, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DocDigitizationJobStatusResponse:
+        """
+        Returns the current status of a job with page-level metrics.
+
+        **Job States:**
+        - `Accepted`: Job created, awaiting file upload
+        - `Pending`: File uploaded, waiting to start
+        - `Running`: Processing in progress
+        - `Completed`: All pages processed successfully
+        - `PartiallyCompleted`: Some pages succeeded, some failed
+        - `Failed`: All pages failed or job-level error
+
+        **Page Metrics:**
+        Response includes detailed progress: total pages, pages processed, succeeded, failed, and per-page errors.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationJobStatusResponse
+            Successful Response
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+        client.doc_digitization_job.get_status(
+            job_id="job_id",
+        )
+        """
+        _response = self._raw_client.get_status(job_id, request_options=request_options)
+        return _response.data
+
+    def get_download_links(
+        self, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DocDigitizationDownloadFilesResponse:
+        """
+        Returns presigned URLs for downloading output files.
+
+        **Prerequisites:**
+        - Job must be in `Completed` or `PartiallyCompleted` state
+        - Failed jobs have no output available
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationDownloadFilesResponse
+            Successful Response
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+        client.doc_digitization_job.get_download_links(
+            job_id="job_id",
+        )
+        """
+        _response = self._raw_client.get_download_links(
+            job_id, request_options=request_options
+        )
+        return _response.data
+
+    def create_job(
+        self,
+        language: DocDigitizationSupportedLanguage = "hi",
+        output_format: DocDigitizationOutputFormat = "html",
+        callback: typing.Optional[DocDigitizationWebhookCallbackParams] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DocDigitizationJob:
+        """
+        Create a new Document Digitization job.
+
+        Parameters
+        ----------
+        language : DocDigitizationSupportedLanguage, default="hi"
+            ISO language code for the document.
+
+        output_format : DocDigitizationOutputFormat, default="html"
+            Output format: "html" for structured HTML or "md" for Markdown.
+
+        callback : typing.Optional[DocDigitizationWebhookCallbackParams], default=OMIT
+            Optional webhook configuration for job completion notification.
+
+        request_options : typing.Optional[RequestOptions], default=None
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationJob
+            A handle to the newly created Document Digitization job.
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(api_subscription_key="YOUR_API_SUBSCRIPTION_KEY")
+
+        # Create job and get handle
+        job = client.doc_digitization_job.create_job(language="hi", output_format="md")
+
+        # Upload PDF, start, wait, download
+        job.upload_file("/path/to/document.pdf")
+        job.start()
+        job.wait_until_complete()
+        job.download_output("./output.md")
+        """
+        response = self.initialise(
+            job_parameters=DocDigitizationJobParametersParams(
+                language=language,
+                output_format=output_format,
+            ),
+            callback=callback,
+            request_options=request_options,
+        )
+        return DocDigitizationJob(job_id=response.job_id, client=self)
+
+    def get_job(self, job_id: str) -> DocDigitizationJob:
+        """
+        Get an existing Document Digitization job handle by job ID.
+
+        Parameters
+        ----------
+        job_id : str
+            The job ID of a previously created Document Digitization job.
+
+        Returns
+        -------
+        DocDigitizationJob
+            A job handle which can be used to check status, upload files, or download results.
+
+        Examples
+        --------
+        from sarvamai import SarvamAI
+
+        client = SarvamAI(api_subscription_key="YOUR_API_SUBSCRIPTION_KEY")
+
+        # Get existing job
+        job = client.doc_digitization_job.get_job(job_id="your-job-uuid")
+        status = job.get_status()
+        """
+        return DocDigitizationJob(job_id=job_id, client=self)
+
+
+class AsyncDocDigitizationJobClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._raw_client = AsyncRawDocDigitizationJobClient(
+            client_wrapper=client_wrapper
+        )
+
+    @property
+    def with_raw_response(self) -> AsyncRawDocDigitizationJobClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        AsyncRawDocDigitizationJobClient
+        """
+        return self._raw_client
+
+    async def initialise(
+        self,
+        *,
+        job_parameters: typing.Optional[DocDigitizationJobParametersParams] = OMIT,
+        callback: typing.Optional[DocDigitizationWebhookCallbackParams] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DocDigitizationCreateJobResponse:
+        """
+        Creates a new document digitization job.
+
+        **Supported Languages:**
+        - `hi`: Hindi
+        - `en`: English
+        - `bn`: Bengali
+        - `gu`: Gujarati
+        - `kn`: Kannada
+        - `ml`: Malayalam
+        - `mr`: Marathi
+        - `or`: Odia
+        - `pa`: Punjabi
+        - `ta`: Tamil
+        - `te`: Telugu
+        - `ur`: Urdu
+        - `as`: Assamese
+        - `bodo`: Bodo
+        - `doi`: Dogri
+        - `ks`: Kashmiri
+        - `kok`: Konkani
+        - `mai`: Maithili
+        - `mni`: Manipuri
+        - `ne`: Nepali
+        - `sa`: Sanskrit
+        - `sat`: Santali
+        - `sd`: Sindhi
+
+        **Output Formats:**
+        - `html`: Structured HTML with layout preservation (default)
+        - `md`: Markdown format
+
+        **Webhook Callback:**
+        Optionally provide a callback URL to receive notification when processing completes.
+
+        Parameters
+        ----------
+        job_parameters : typing.Optional[DocDigitizationJobParametersParams]
+            Job configuration parameters. Omit the request body to use defaults.
+
+        callback : typing.Optional[DocDigitizationWebhookCallbackParams]
+            Optional webhook for completion notification
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationCreateJobResponse
+            Successful Response
+
+        Examples
+        --------
+        import asyncio
+
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.doc_digitization_job.initialise()
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.initialise(
+            job_parameters=job_parameters,
+            callback=callback,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def get_upload_links(
+        self,
+        *,
+        job_id: str,
+        files: typing.Sequence[str],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> DocDigitizationUploadFilesResponse:
+        """
+        Returns presigned URLs for uploading input files.
+
+        **File Constraints:**
+        - Exactly one file required (PDF or ZIP)
+        - PDF files: `.pdf` extension
+        - ZIP files: `.zip` extension
+
+        Parameters
+        ----------
+        job_id : str
+            Job identifier returned from Create Job
+
+        files : typing.Sequence[str]
+            List of filenames to upload (exactly 1 file: PDF or ZIP)
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationUploadFilesResponse
+            Successful Response
+
+        Examples
+        --------
+        import asyncio
+
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.doc_digitization_job.get_upload_links(
+                job_id="job_id",
+                files=["files"],
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_upload_links(
+            job_id=job_id, files=files, request_options=request_options
+        )
+        return _response.data
+
+    async def start(
+        self, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DocDigitizationJobStatusResponse:
+        """
+        Validates the uploaded file and starts processing.
+
+        **Validation Checks:**
+        - File must be uploaded before starting
+        - File size must not exceed 200 MB
+        - PDF must be parseable by the PDF parser
+        - ZIP must contain only JPEG/PNG images
+        - ZIP must be flat (no nested folders beyond one level)
+        - ZIP must contain at least one valid image
+        - Page/image count must not exceed 500
+        - User must have sufficient credits
+
+        **Processing:**
+        Job runs asynchronously. Poll the status endpoint or use webhook callback for completion notification.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationJobStatusResponse
+            Successful Response
+
+        Examples
+        --------
+        import asyncio
+
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.doc_digitization_job.start(
+                job_id="job_id",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.start(
+            job_id, request_options=request_options
+        )
+        return _response.data
+
+    async def get_status(
+        self, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DocDigitizationJobStatusResponse:
+        """
+        Returns the current status of a job with page-level metrics.
+
+        **Job States:**
+        - `Accepted`: Job created, awaiting file upload
+        - `Pending`: File uploaded, waiting to start
+        - `Running`: Processing in progress
+        - `Completed`: All pages processed successfully
+        - `PartiallyCompleted`: Some pages succeeded, some failed
+        - `Failed`: All pages failed or job-level error
+
+        **Page Metrics:**
+        Response includes detailed progress: total pages, pages processed, succeeded, failed, and per-page errors.
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationJobStatusResponse
+            Successful Response
+
+        Examples
+        --------
+        import asyncio
+
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.doc_digitization_job.get_status(
+                job_id="job_id",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_status(
+            job_id, request_options=request_options
+        )
+        return _response.data
+
+    async def get_download_links(
+        self, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> DocDigitizationDownloadFilesResponse:
+        """
+        Returns presigned URLs for downloading output files.
+
+        **Prerequisites:**
+        - Job must be in `Completed` or `PartiallyCompleted` state
+        - Failed jobs have no output available
+
+        Parameters
+        ----------
+        job_id : str
+            The unique identifier of the job
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        DocDigitizationDownloadFilesResponse
+            Successful Response
+
+        Examples
+        --------
+        import asyncio
+
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(
+            api_subscription_key="YOUR_API_SUBSCRIPTION_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.doc_digitization_job.get_download_links(
+                job_id="job_id",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_download_links(
+            job_id, request_options=request_options
+        )
+        return _response.data
+
+    async def create_job(
+        self,
+        language: DocDigitizationSupportedLanguage = "hi",
+        output_format: DocDigitizationOutputFormat = "html",
+        callback: typing.Optional[DocDigitizationWebhookCallbackParams] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncDocDigitizationJob:
+        """
+        Create a new Document Digitization job.
+
+        Parameters
+        ----------
+        language : DocDigitizationSupportedLanguage, default="hi"
+            ISO language code for the document.
+
+        output_format : DocDigitizationOutputFormat, default="html"
+            Output format: "html" for structured HTML or "md" for Markdown.
+
+        callback : typing.Optional[DocDigitizationWebhookCallbackParams], default=OMIT
+            Optional webhook configuration for job completion notification.
+
+        request_options : typing.Optional[RequestOptions], default=None
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncDocDigitizationJob
+            A handle to the newly created Document Digitization job.
+
+        Examples
+        --------
+        import asyncio
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(api_subscription_key="YOUR_API_SUBSCRIPTION_KEY")
+
+        async def main():
+            job = await client.doc_digitization_job.create_job(language="hi", output_format="md")
+            await job.upload_file("/path/to/document.pdf")
+            await job.start()
+            await job.wait_until_complete()
+            await job.download_output("./output.md")
+
+        asyncio.run(main())
+        """
+        response = await self.initialise(
+            job_parameters=DocDigitizationJobParametersParams(
+                language=language,
+                output_format=output_format,
+            ),
+            callback=callback,
+            request_options=request_options,
+        )
+        return AsyncDocDigitizationJob(job_id=response.job_id, client=self)
+
+    def get_job(self, job_id: str) -> AsyncDocDigitizationJob:
+        """
+        Get an existing Document Digitization job handle by job ID.
+
+        Parameters
+        ----------
+        job_id : str
+            The job ID of a previously created Document Digitization job.
+
+        Returns
+        -------
+        AsyncDocDigitizationJob
+            A job handle which can be used to check status, upload files, or download results.
+
+        Examples
+        --------
+        import asyncio
+        from sarvamai import AsyncSarvamAI
+
+        client = AsyncSarvamAI(api_subscription_key="YOUR_API_SUBSCRIPTION_KEY")
+
+        async def main():
+            job = client.doc_digitization_job.get_job(job_id="your-job-uuid")
+            status = await job.get_status()
+
+        asyncio.run(main())
+        """
+        return AsyncDocDigitizationJob(job_id=job_id, client=self)