Upload 17 files

.env.template

@@ -0,0 +1,3 @@
+TYPHOON_BASE_URL=
+TYPHOON_API_KEY=
+TYPHOON_OCR_MODEL=typhoon-ocr-preview

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/test.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,3 @@
+.env
+*.pyc
+.specstory

README.md

@@ -1,12 +1,79 @@
----
-title: Ocr Typhoon
-emoji: 💻
-colorFrom: pink
-colorTo: yellow
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Typhoon OCR
+
+Typhoon OCR is a model for extracting structured markdown from images or PDFs. It supports document layout analysis and table extraction, returning results in markdown or HTML. This package is a simple Gradio website to demonstrate the performance of Typhoon OCR.
+
+### Features
+
+- Upload a PDF or image (single page)
+- Extracts and reconstructs document content as markdown
+- Supports different prompt modes for layout or structure
+- Language: English, Thai
+- Uses a local or remote OpenAI-compatible API (e.g., vllm, opentyphoon.ai)
+- See blog for more detail https://opentyphoon.ai/blog/en/typhoon-ocr-release
+
+### Requirements
+
+- Linux / Mac with python (window not supported at the moment)
+
+### Install
+
+```bash
+pip install typhoon-ocr
+```
+
+or to run the gradio app.
+
+```bash
+pip install -r requirements.txt
+# edit .env
+# pip install vllm # optional for hosting a local server
+```
+
+### Mac specific
+
+```
+brew install poppler
+# The following binaries are required and provided by poppler:
+# - pdfinfo
+# - pdftoppm
+```
+
+### Linux specific
+
+```
+sudo apt-get update
+sudo apt-get install poppler-utils
+# The following binaries are required and provided by poppler-utils:
+# - pdfinfo
+# - pdftoppm
+```
+
+### Start vllm
+
+```bash
+vllm serve scb10x/typhoon-ocr-7b --served-model-name typhoon-ocr --dtype bfloat16 --port 8101
+```
+
+### Run Gradio demo
+
+```bash
+python app.py
+```
+
+### Dependencies
+
+- openai
+- python-dotenv
+- ftfy
+- pypdf
+- gradio
+- vllm (for hosting an inference server)
+- pillow
+
+### Debug
+
+- If `Error processing document` occur. Make sure you have install `brew install poppler` or `apt-get install poppler-utils`.
+
+### License
+
+This project is licensed under the Apache 2.0 License. See individual datasets and checkpoints for their respective licenses.

app.py

@@ -10,11 +10,7 @@ from PIL import Image
 
 load_dotenv()
 
-# Load API (OpenAI-compatible)
-openai = OpenAI(
-    base_url=os.getenv("TYPHOON_BASE_URL"),
-    api_key=os.getenv("TYPHOON_API_KEY")
-)
+openai = OpenAI(base_url=os.getenv("TYPHOON_BASE_URL"), api_key=os.getenv("TYPHOON_API_KEY"))
 
 theme = gr.themes.Soft(
     primary_hue=gr.themes.Color(
@@ -37,11 +33,11 @@ theme = gr.themes.Soft(
 def process_pdf(pdf_or_image_file, task_type, page_number):
     if pdf_or_image_file is None:
         return None, "No file uploaded"
-
+    
     orig_filename = pdf_or_image_file.name
-
+    
     try:
-        # Prepare OCR messages using Typhoon’s helper
+        # Use the new simplified function to prepare OCR messages with page number
         messages = prepare_ocr_messages(
             pdf_or_image_path=orig_filename,
             task_type=task_type,
@@ -49,13 +45,13 @@ def process_pdf(pdf_or_image_file, task_type, page_number):
             target_text_length=8000,
             page_num=page_number if page_number else 1
         )
-
-        # Extract image for preview
+        
+        # Extract the image from the message content for display
         image_url = messages[0]["content"][1]["image_url"]["url"]
         image_base64 = image_url.replace("data:image/png;base64,", "")
         image_pil = Image.open(BytesIO(base64.b64decode(image_base64)))
-
-        # Send the request to Typhoon API
+        
+        # Send messages to OpenAI compatible API
         response = openai.chat.completions.create(
             model=os.getenv("TYPHOON_OCR_MODEL"),
             messages=messages,
@@ -66,58 +62,82 @@ def process_pdf(pdf_or_image_file, task_type, page_number):
                 "top_p": 0.6,
             },
         )
-
         text_output = response.choices[0].message.content
-
-        # Try to extract `natural_text`
+        
+        # Try to parse the output assuming it is a Python dictionary containing 'natural_text'
         try:
             json_data = json.loads(text_output)
-            markdown_out = json_data.get("natural_text", "").replace("<figure>", "").replace("</figure>", "")
-        except:
-            markdown_out = text_output
-
+            markdown_out = json_data.get('natural_text', "").replace("<figure>", "").replace("</figure>", "")
+        except Exception as e:
+            markdown_out = f"⚠️ Could not extract `natural_text` from output.\nError: {str(e)}"
+        
         return image_pil, markdown_out
-
+    
     except Exception as e:
-        return None, f"Error: {str(e)}"
+        return None, f"Error processing file: {str(e)}"
 
 
+# Build the Gradio UI.
 with gr.Blocks(theme=theme) as demo:
     title = gr.HTML("""
-    <h1>Typhoon OCR (API version)</h1>
-    <p>This Space uses the Typhoon OCR API, NOT the huge local model. Works on CPU!</p>
-    """)
-
+    <h1>Typhoon OCR</h1>
+    <ul>
+        <li>🤗 <b>Model weights</b>: <a href="https://huggingface.co/scb10x/typhoon-ocr-7b" target="_blank">https://huggingface.co/scb10x/typhoon-ocr-7b</a></li>
+    </ul>
+    <br />
+    <details>
+        <summary><strong>Disclaimer</strong></summary>
+        The responses generated by this Artificial Intelligence (AI) system are autonomously constructed and do not necessarily reflect the views or positions of the developing organizations, their affiliates, or any of their employees. These AI-generated responses do not represent those of the organizations. The organizations do not endorse, support, sanction, encourage, verify, or agree with the comments, opinions, or statements generated by this AI. The information produced by this AI is not intended to malign any religion, ethnic group, club, organization, company, individual, anyone, or anything. It is not the intent of the organizations to malign any group or individual. The AI operates based on its programming and training data and its responses should not be interpreted as the explicit intent or opinion of the organizations.
+    </details>
+    <br />
+    <details>
+        <summary><strong>Terms of use</strong></summary>
+        By using this service, users are required to agree to the following terms: The service is a research preview intended for non-commercial use only. It only provides limited safety measures and may generate offensive content. It must not be used for any illegal, harmful, violent, racist, or sexual purposes. Vision language models are prone to hallucinations to a greater extent compared to text-only LLMs.
+    </details>
+    <br />
+    <details>
+        <summary><strong>License</strong></summary>
+        This project utilizes certain datasets and checkpoints that are subject to their respective original licenses. Users must comply with all terms and conditions of these original licenses. The content of this project itself is licensed under the Apache license 2.0.
+    </details>
+""")
     with gr.Row():
         with gr.Column(scale=1):
-            pdf_input = gr.File(
-                label="📄 Upload Image or PDF",
-                file_types=[".pdf", ".png", ".jpg", ".jpeg"]
-            )
-
-            task_dropdown = gr.Radio(
-                ["default", "structure"],
-                label="🎯 OCR Task",
-                value="default"
-            )
-
-            page_number = gr.Number(
-                label="📄 Page Number (PDFs only)",
-                value=1,
-                minimum=1,
-                step=1
-            )
-
-            run_button = gr.Button("🚀 Run OCR")
+            # Update file_types to accept PDF as well as common image formats.
+            pdf_input = gr.File(label="📄 Upload Image file or PDF file", file_types=[".pdf", ".png", ".jpg", ".jpeg"])
+            
+            with gr.Group(elem_classes=["task-background"]):
+                task_dropdown = gr.Radio(["default", "structure"], label="🎯 Select Task", value="default")
+                gr.HTML("""
+                <p><b>default</b>: This mode works for most cases and is recommended for files without a clear template such as infographics.</p>
+                <p><b>structure</b>: This mode offers improved performance for complex layout documents such as those containing images, tables and forms.</p>
+                <p>We recommend trying both and see which one works better for your use case.</p>
+                """, elem_classes=["task-dropdown-info"])
+                demo.css = """
+                .task-background {
+                    background: var(--block-background-fill) !important;
+                    
+                }
+                .task-background > * {
+                    background: var(--block-background-fill) !important;
+                }
+                .task-dropdown-info {
+                    padding: 0 16px;
+                    font-size: 12px;
+                }
+                """
+            page_number = gr.Number(label="📄 Page Number (for PDFs only)", value=1, minimum=1, step=1)
+            run_button = gr.Button("🚀 Run")
             image_output = gr.Image(label="📸 Preview Image", type="pil")
-
         with gr.Column(scale=2):
-            markdown_output = gr.Markdown(label="OCR Result", show_label=True)
+            markdown_output = gr.Markdown(label='Markdown Result', show_label=True)
 
+    
+    # Connect the UI inputs to the processing function.
     run_button.click(
         fn=process_pdf,
         inputs=[pdf_input, task_dropdown, page_number],
         outputs=[image_output, markdown_output]
     )
 
-demo.launch()
+# Launch the Gradio demo (temporary public share for 72 hours)
+demo.launch(share=False)

examples/simple_ocr.py

@@ -0,0 +1,10 @@
+from typhoon_ocr import ocr_document
+import os
+
+# please set env TYPHOON_API_KEY or OPENAI_API_KEY to use this function
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+image_path = os.path.join(script_dir, "test.png")
+
+markdown = ocr_document(image_path)
+print(markdown)

packages/typhoon_ocr/.gitignore

@@ -0,0 +1,52 @@
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+venv/
+env/
+ENV/
+.env
+.venv
+env.bak/
+venv.bak/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Sphinx documentation
+docs/_build/
+docs/api/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Project specific
+*.bak
+*.tmp
+temp/ 

packages/typhoon_ocr/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS 

packages/typhoon_ocr/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include pyproject.toml 

packages/typhoon_ocr/README.md

@@ -0,0 +1,134 @@
+# Typhoon OCR
+
+Typhoon OCR is a model for extracting structured markdown from images or PDFs. It supports document layout analysis and table extraction, returning results in markdown or HTML. This package provides utilities to convert images and PDFs to the format supported by the Typhoon OCR model.
+
+## Languages Supported
+
+The Typhoon OCR model supports:
+- English
+- Thai
+
+## Features
+
+- Convert images to PDFs for unified processing
+- Extract text and layout information from PDFs and images
+- Generate OCR-ready messages for API processing with Typhoon OCR model
+- Built-in prompt templates for different document processing tasks
+- Process specific pages from multi-page PDF documents
+
+## Installation
+
+```bash
+pip install typhoon-ocr
+```
+
+### System Requirements
+
+The package requires the Poppler utilities to be installed on your system:
+
+#### For macOS:
+```bash
+brew install poppler
+```
+
+#### For Linux:
+```bash
+sudo apt-get update
+sudo apt-get install poppler-utils
+```
+
+The following binaries are required:
+- `pdfinfo`
+- `pdftoppm`
+
+## Usage
+
+### Core functionality
+
+The package provides 2 main functions:
+
+```python
+from typhoon_ocr import ocr_document, prepare_ocr_messages
+```
+* `ocr_document`: Full OCR pipeline for Typhoon OCR model via opentyphoon.ai or OpenAI compatible api (such as vllm)
+* `prepare_ocr_messages`: Generate complete OCR-ready messages for the Typhoon OCR model
+
+
+### Complete OCR workflow
+
+Use the simplified API to ocr the document or prepare messages for OpenAI compatible api at opentyphoon.ai:
+
+```python
+from typhoon_ocr import ocr_document
+
+markdown = ocr_document(
+    pdf_or_image_path="document.pdf",  # Works with PDFs or images
+    task_type="default",    # Choose between "default" or "structure"
+    page_num=2              # Process page 2 of a PDF (default is 1, always 1 for images)
+)
+
+# Or with image
+markdown = ocr_document(
+    pdf_or_image_path="scan.jpg",  # Works with PDFs or images
+    task_type="default",    # Choose between "default" or "structure"
+)
+```
+
+Prepare the messages manually.
+
+```python
+from typhoon_ocr import prepare_ocr_messages
+from openai import OpenAI
+
+# Prepare messages for OCR processing
+messages = prepare_ocr_messages(
+    pdf_or_image_path="document.pdf",  # Works with PDFs or images
+    task_type="default",    # Choose between "default" or "structure"
+    page_num=2              # Process page 2 of a PDF (default is 1, always 1 for images)
+)
+
+# Use with https://opentyphoon.ai/ api or self-host model via vllm
+# See model list at https://huggingface.co/collections/scb10x/typhoon-ocr-682713483cb934ab0cf069bd
+client = OpenAI(base_url='https://api.opentyphoon.ai/v1')
+response = client.chat.completions.create(
+    model="typhoon-ocr-preview",
+    messages=messages,
+    max_tokens=16000,
+    extra_body={
+        "repetition_penalty": 1.2,
+        "temperature": 0.1,
+        "top_p": 0.6,
+    },
+
+)
+
+# Parse the JSON response
+text_output = response.choices[0].message.content
+markdown = json.loads(text_output)['natural_text']
+print(markdown)
+```
+
+### Available task types
+
+The package comes with built-in prompt templates for different OCR tasks:
+
+- `default`: Extracts markdown representation of the document with tables in markdown format
+- `structure`: Provides more structured output with HTML tables and image analysis placeholders
+
+## Document Extraction Capabilities
+
+The Typhoon OCR model, when used with this package, can extract:
+
+- Structured text with proper layout preservation
+- Tables (in markdown or HTML format)
+- Document hierarchy (headings, paragraphs, lists)
+- Text with positional information
+- Basic image analysis and placement
+
+## License
+
+This project code is licensed under the Apache 2.0 License.
+
+## Acknowledgments
+
+The code is based on work from [OlmoCR](https://github.com/allenai/olmocr) under the Apache 2.0 license.

packages/typhoon_ocr/build_and_upload.sh

@@ -0,0 +1 @@
+python -m build && python -m twine upload dist/* --verbose

packages/typhoon_ocr/pyproject.toml

@@ -0,0 +1,12 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 88
+target-version = ["py37"]
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 88 

packages/typhoon_ocr/setup.py

@@ -0,0 +1,39 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="typhoon-ocr",
+    version="0.3.8",
+    author="Typhoon OCR Contributors",
+    author_email="contact@opentyphoon.ai",
+    description="A package for extracting structured content from PDFs and images using Typhoon OCR models",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/scb-10x/typhoon-ocr",
+    packages=find_packages(),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.7",
+    install_requires=[
+        "ftfy",
+        "pypdf",
+        "pillow",
+        "openai",
+    ],
+    extras_require={
+        "dev": [
+            "pytest",
+            "black",
+            "flake8",
+        ],
+        "app": [
+            "gradio",
+            "python-dotenv",
+        ],
+    },
+) 

packages/typhoon_ocr/typhoon_ocr/__init__.py

@@ -0,0 +1,39 @@
+"""
+Typhoon OCR is a model for extracting structured markdown from images or PDFs.
+
+This package provides utilities for document analysis, layout extraction, and OCR processing.
+It focuses on structured text extraction with proper formatting and layout preservation.
+
+Main Functions:
+    - prepare_ocr_messages: Generate OCR-ready messages from PDFs or images
+    - get_prompt: Access built-in prompt templates for different OCR tasks
+    - image_to_pdf: Convert image files to PDF format
+
+Requirements:
+    - Poppler utilities (pdfinfo, pdftoppm) must be installed on the system
+    - Appropriate dependencies (ftfy, pypdf, pillow) for text processing
+
+Example Usage:
+    >>> from typhoon_ocr import prepare_ocr_messages
+    >>> messages = prepare_ocr_messages("document.pdf", task_type="default", page_num=1)
+    >>> # Use messages with LLM API for OCR processing
+"""
+from .pdf_utils import pdf_utils_available
+from .ocr_utils import (
+    prepare_ocr_messages,
+    get_prompt,
+    get_anchor_text,
+    image_to_pdf,
+    ocr_document,
+)
+
+__version__ = "0.3.8"
+
+__all__ = [
+    "pdf_utils_available",
+    "prepare_ocr_messages",
+    "get_prompt",
+    "get_anchor_text", 
+    "image_to_pdf",
+    "ocr_document",
+] 

packages/typhoon_ocr/typhoon_ocr/ocr_utils.py

@@ -0,0 +1,623 @@
+"""
+Utility functions for Typhoon OCR.
+
+This code is adapted from https://github.com/allenai/olmocr
+Under the Apache 2.0 license.
+Edited by Typhoon OCR Contributors.
+"""
+from dataclasses import dataclass
+import json
+from openai import OpenAI
+import os
+import re
+import io
+import tempfile
+from PIL import Image
+import subprocess
+import base64
+from typing import Any, Callable, Dict, List, Literal
+import random
+import ftfy
+from pypdf.generic import RectangleObject
+from pypdf import PdfReader
+
+
+@dataclass(frozen=True)
+class Element:
+    pass
+
+
+@dataclass(frozen=True)
+class BoundingBox:
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+
+    @staticmethod
+    def from_rectangle(rect: RectangleObject) -> "BoundingBox":
+        return BoundingBox(rect[0], rect[1], rect[2], rect[3])
+
+
+@dataclass(frozen=True)
+class TextElement(Element):
+    text: str
+    x: float
+    y: float
+
+
+@dataclass(frozen=True)
+class ImageElement(Element):
+    name: str
+    bbox: BoundingBox
+
+
+@dataclass(frozen=True)
+class PageReport:
+    mediabox: BoundingBox
+    text_elements: List[TextElement]
+    image_elements: List[ImageElement]
+    
+def image_to_pdf(image_path):
+    try:
+        # Open the image file.
+        img = Image.open(image_path)
+        # Create a temporary file to store the PDF.
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp:
+            filename = tmp.name
+            temp_pdf_created = True
+        # Convert image to RGB if necessary and save as PDF.
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+        img.save(filename, "PDF")
+        return filename
+    except Exception as conv_err:
+        return None
+
+def get_pdf_media_box_width_height(local_pdf_path: str, page_num: int) -> tuple[float, float]:
+    """
+    Get the MediaBox dimensions for a specific page in a PDF file using the pdfinfo command.
+
+    :param pdf_file: Path to the PDF file
+    :param page_num: The page number for which to extract MediaBox dimensions
+    :return: A dictionary containing MediaBox dimensions or None if not found
+    """
+        
+    # Construct the pdfinfo command to extract info for the specific page
+    command = ["pdfinfo", "-f", str(page_num), "-l", str(page_num), "-box", "-enc", "UTF-8", local_pdf_path]
+    # Run the command using subprocess
+    result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+
+    # Check if there is any error in executing the command
+    if result.returncode != 0:
+        raise ValueError(f"Error running pdfinfo: {result.stderr}")
+
+    # Parse the output to find MediaBox
+    output = result.stdout
+
+    for line in output.splitlines():
+        if "MediaBox" in line:
+            media_box_str: List[str] = line.split(":")[1].strip().split()
+            media_box: List[float] = [float(x) for x in media_box_str]
+            return abs(media_box[0] - media_box[2]), abs(media_box[3] - media_box[1])
+
+    raise ValueError("MediaBox not found in the PDF info.")
+    
+def render_pdf_to_base64png(local_pdf_path: str, page_num: int, target_longest_image_dim: int = 2048) -> str:
+        
+    longest_dim = max(get_pdf_media_box_width_height(local_pdf_path, page_num))
+
+    # Convert PDF page to PNG using pdftoppm
+    pdftoppm_result = subprocess.run(
+        [
+            "pdftoppm",
+            "-png",
+            "-f",
+            str(page_num),
+            "-l",
+            str(page_num),
+            "-r",
+            str(target_longest_image_dim * 72 / longest_dim),  # 72 pixels per point is the conversion factor
+            local_pdf_path,
+        ],
+        timeout=120,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    assert pdftoppm_result.returncode == 0, pdftoppm_result.stderr
+    return base64.b64encode(pdftoppm_result.stdout).decode("utf-8")
+
+
+def _linearize_pdf_report(report: PageReport, max_length: int = 4000) -> str:
+    result = ""
+    result += f"Page dimensions: {report.mediabox.x1:.1f}x{report.mediabox.y1:.1f}\n"
+
+    if max_length < 20:
+        return result
+
+    images = _merge_image_elements(report.image_elements)
+
+    # Process image elements
+    image_strings = []
+    for element in images:
+        image_str = f"[Image {element.bbox.x0:.0f}x{element.bbox.y0:.0f} to {element.bbox.x1:.0f}x{element.bbox.y1:.0f}]\n"
+        # Use element's unique identifier (e.g., id or position) for comparison
+        image_strings.append((element, image_str))
+
+    # Process text elements
+    text_strings = []
+    for element in report.text_elements:  # type: ignore
+        if len(element.text.strip()) == 0:  # type: ignore
+            continue
+
+        element_text = _cleanup_element_text(element.text)  # type: ignore
+        text_str = f"[{element.x:.0f}x{element.y:.0f}]{element_text}\n"  # type: ignore
+        text_strings.append((element, text_str))
+
+    # Combine all elements with their positions for sorting
+    all_elements: list[tuple[str, ImageElement, str, tuple[float, float]]] = []
+    for elem, s in image_strings:
+        position = (elem.bbox.x0, elem.bbox.y0)
+        all_elements.append(("image", elem, s, position))
+    for elem, s in text_strings:
+        position = (elem.x, elem.y)  # type: ignore
+        all_elements.append(("text", elem, s, position))
+
+    # Calculate total length
+    total_length = len(result) + sum(len(s) for _, _, s, _ in all_elements)
+
+    if total_length <= max_length:
+        # Include all elements
+        for _, _, s, _ in all_elements:
+            result += s
+        return result
+
+    # Identify elements with min/max coordinates
+    edge_elements = set()
+
+    if images:
+        min_x0_image = min(images, key=lambda e: e.bbox.x0)
+        max_x1_image = max(images, key=lambda e: e.bbox.x1)
+        min_y0_image = min(images, key=lambda e: e.bbox.y0)
+        max_y1_image = max(images, key=lambda e: e.bbox.y1)
+        edge_elements.update([min_x0_image, max_x1_image, min_y0_image, max_y1_image])
+
+    if report.text_elements:
+        text_elements = [e for e in report.text_elements if len(e.text.strip()) > 0]
+        if text_elements:
+            min_x_text = min(text_elements, key=lambda e: e.x)
+            max_x_text = max(text_elements, key=lambda e: e.x)
+            min_y_text = min(text_elements, key=lambda e: e.y)
+            max_y_text = max(text_elements, key=lambda e: e.y)
+            edge_elements.update([min_x_text, max_x_text, min_y_text, max_y_text])  # type: ignore
+
+    # Keep track of element IDs to prevent duplication
+    selected_element_ids = set()
+    selected_elements = []
+
+    # Include edge elements first
+    for elem_type, elem, s, position in all_elements:
+        if elem in edge_elements and id(elem) not in selected_element_ids:
+            selected_elements.append((elem_type, elem, s, position))
+            selected_element_ids.add(id(elem))
+
+    # Calculate remaining length
+    current_length = len(result) + sum(len(s) for _, _, s, _ in selected_elements)
+    _remaining_length = max_length - current_length
+
+    # Exclude edge elements from the pool
+    remaining_elements = [(elem_type, elem, s, position) for elem_type, elem, s, position in all_elements if id(elem) not in selected_element_ids]
+
+    # Sort remaining elements by their positions (e.g., x-coordinate and then y-coordinate)
+    # remaining_elements.sort(key=lambda x: (x[3][0], x[3][1]))
+
+    # Shuffle remaining elements randomly
+    random.shuffle(remaining_elements)
+
+    # Add elements until reaching max_length
+    for elem_type, elem, s, position in remaining_elements:
+        if current_length + len(s) > max_length:
+            break
+        selected_elements.append((elem_type, elem, s, position))
+        selected_element_ids.add(id(elem))
+        current_length += len(s)
+
+    # Sort selected elements by their positions to maintain logical order
+    selected_elements.sort(key=lambda x: (x[3][0], x[3][1]))
+
+    # Build the final result
+    for _, _, s, _ in selected_elements:
+        result += s
+
+    return result
+
+
+def _cap_split_string(text: str, max_length: int) -> str:
+    if len(text) <= max_length:
+        return text
+
+    head_length = max_length // 2 - 3
+    tail_length = head_length
+
+    head = text[:head_length].rsplit(" ", 1)[0] or text[:head_length]
+    tail = text[-tail_length:].split(" ", 1)[-1] or text[-tail_length:]
+
+    return f"{head} ... {tail}"
+
+
+def _cleanup_element_text(element_text: str) -> str:
+    MAX_TEXT_ELEMENT_LENGTH = 250
+    TEXT_REPLACEMENTS = {"[": "\\[", "]": "\\]", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+    text_replacement_pattern = re.compile("|".join(re.escape(key) for key in TEXT_REPLACEMENTS.keys()))
+
+    element_text = ftfy.fix_text(element_text).strip()
+
+    # Replace square brackets with escaped brackets and other escaped chars
+    element_text = text_replacement_pattern.sub(lambda match: TEXT_REPLACEMENTS[match.group(0)], element_text)
+
+    return _cap_split_string(element_text, MAX_TEXT_ELEMENT_LENGTH)
+
+def _merge_image_elements(images: List[ImageElement], tolerance: float = 0.5) -> List[ImageElement]:
+    n = len(images)
+    parent = list(range(n))  # Initialize Union-Find parent pointers
+
+    def find(i):
+        # Find with path compression
+        root = i
+        while parent[root] != root:
+            root = parent[root]
+        while parent[i] != i:
+            parent_i = parent[i]
+            parent[i] = root
+            i = parent_i
+        return root
+
+    def union(i, j):
+        # Union by attaching root of one tree to another
+        root_i = find(i)
+        root_j = find(j)
+        if root_i != root_j:
+            parent[root_i] = root_j
+
+    def bboxes_overlap(b1: BoundingBox, b2: BoundingBox, tolerance: float) -> bool:
+        # Compute horizontal and vertical distances between boxes
+        h_dist = max(0, max(b1.x0, b2.x0) - min(b1.x1, b2.x1))
+        v_dist = max(0, max(b1.y0, b2.y0) - min(b1.y1, b2.y1))
+        # Check if distances are within tolerance
+        return h_dist <= tolerance and v_dist <= tolerance
+
+    # Union overlapping images
+    for i in range(n):
+        for j in range(i + 1, n):
+            if bboxes_overlap(images[i].bbox, images[j].bbox, tolerance):
+                union(i, j)
+
+    # Group images by their root parent
+    groups: dict[int, list[int]] = {}
+    for i in range(n):
+        root = find(i)
+        groups.setdefault(root, []).append(i)
+
+    # Merge images in the same group
+    merged_images = []
+    for indices in groups.values():
+        # Initialize merged bounding box
+        merged_bbox = images[indices[0]].bbox
+        merged_name = images[indices[0]].name
+
+        for idx in indices[1:]:
+            bbox = images[idx].bbox
+            # Expand merged_bbox to include the current bbox
+            merged_bbox = BoundingBox(
+                x0=min(merged_bbox.x0, bbox.x0),
+                y0=min(merged_bbox.y0, bbox.y0),
+                x1=max(merged_bbox.x1, bbox.x1),
+                y1=max(merged_bbox.y1, bbox.y1),
+            )
+            # Optionally, update the name
+            merged_name += f"+{images[idx].name}"
+
+        merged_images.append(ImageElement(name=merged_name, bbox=merged_bbox))
+
+    # Return the merged images along with other elements
+    return merged_images
+
+def _transform_point(x, y, m):
+    x_new = m[0] * x + m[2] * y + m[4]
+    y_new = m[1] * x + m[3] * y + m[5]
+    return x_new, y_new
+
+def _mult(m: List[float], n: List[float]) -> List[float]:
+    return [
+        m[0] * n[0] + m[1] * n[2],
+        m[0] * n[1] + m[1] * n[3],
+        m[2] * n[0] + m[3] * n[2],
+        m[2] * n[1] + m[3] * n[3],
+        m[4] * n[0] + m[5] * n[2] + n[4],
+        m[4] * n[1] + m[5] * n[3] + n[5],
+    ]
+    
+def _pdf_report(local_pdf_path: str, page_num: int) -> PageReport:
+    reader = PdfReader(local_pdf_path)
+    page = reader.pages[page_num - 1]
+    resources = page.get("/Resources", {})
+    xobjects = resources.get("/XObject", {})
+    text_elements, image_elements = [], []
+
+    def visitor_body(text, cm, tm, font_dict, font_size):
+        txt2user = _mult(tm, cm)
+        text_elements.append(TextElement(text, txt2user[4], txt2user[5]))
+
+    def visitor_op(op, args, cm, tm):
+        if op == b"Do":
+            xobject_name = args[0]
+            xobject = xobjects.get(xobject_name)
+            if xobject and xobject["/Subtype"] == "/Image":
+                # Compute image bbox
+                # The image is placed according to the CTM
+                _width = xobject.get("/Width")
+                _height = xobject.get("/Height")
+                x0, y0 = _transform_point(0, 0, cm)
+                x1, y1 = _transform_point(1, 1, cm)
+                image_elements.append(ImageElement(xobject_name, BoundingBox(min(x0, x1), min(y0, y1), max(x0, x1), max(y0, y1))))
+
+    page.extract_text(visitor_text=visitor_body, visitor_operand_before=visitor_op)
+
+    return PageReport(
+        mediabox=BoundingBox.from_rectangle(page.mediabox),
+        text_elements=text_elements,
+        image_elements=image_elements,
+    )
+    
+def get_anchor_text(
+    local_pdf_path: str, page: int, pdf_engine: Literal["pdftotext", "pdfium", "pypdf", "topcoherency", "pdfreport"], target_length: int = 4000
+) -> str:
+    assert page > 0, "Pages are 1-indexed in pdf-land"
+
+    
+    if pdf_engine == "pdfreport":
+        return _linearize_pdf_report(_pdf_report(local_pdf_path, page), max_length=target_length)
+    else:
+        raise NotImplementedError("Unknown engine")
+
+PROMPTS_SYS = {
+    "default": lambda base_text: (f"Below is an image of a document page along with its dimensions. "
+        f"Simply return the markdown representation of this document, presenting tables in markdown format as they naturally appear.\n"
+        f"If the document contains images, use a placeholder like dummy.png for each image.\n"
+        f"Your final output must be in JSON format with a single key `natural_text` containing the response.\n"
+        f"RAW_TEXT_START\n{base_text}\nRAW_TEXT_END"),
+    "structure": lambda base_text: (
+        f"Below is an image of a document page, along with its dimensions and possibly some raw textual content previously extracted from it. "
+        f"Note that the text extraction may be incomplete or partially missing. Carefully consider both the layout and any available text to reconstruct the document accurately.\n"
+        f"Your task is to return the markdown representation of this document, presenting tables in HTML format as they naturally appear.\n"
+        f"If the document contains images or figures, analyze them and include the tag <figure>IMAGE_ANALYSIS</figure> in the appropriate location.\n"
+        f"Your final output must be in JSON format with a single key `natural_text` containing the response.\n"
+        f"RAW_TEXT_START\n{base_text}\nRAW_TEXT_END"
+    ),
+}
+
+def get_prompt(prompt_name: str) -> Callable[[str], str]:
+    """
+    Get a prompt template function for the specified prompt type.
+    
+    This function returns a callable that generates a prompt template based on the provided prompt name.
+    The returned function takes extracted text as input and returns a formatted prompt string
+    that can be used with OCR/vision models.
+    
+    Available prompt types:
+    - "default": Creates a prompt for extracting text with tables in markdown format.
+    - "structure": Creates a prompt for extracting text with tables in HTML format and image analysis.
+    
+    Args:
+        prompt_name (str): The identifier for the desired prompt template ("default" or "structure").
+        
+    Returns:
+        Callable[[str], str]: A function that takes extracted text and returns a formatted prompt.
+        
+    Examples:
+        >>> prompt_fn = get_prompt("default")
+        >>> formatted_prompt = prompt_fn("Sample extracted text")
+        >>> print(formatted_prompt[:50])  # Print first 50 chars
+        Below is an image of a document page along with its
+    """
+    return PROMPTS_SYS.get(prompt_name, lambda x: "Invalid PROMPT_NAME provided.")
+
+def image_to_base64png(img: Image.Image):
+    buffered = io.BytesIO()
+    img = img.convert("RGB")
+    img.save(buffered, format="JPEG")
+    return base64.b64encode(buffered.getvalue()).decode("utf-8")
+
+def get_anchor_text_from_image(img: Image.Image):
+    width = float(img.width)
+    height = float(img.height)
+    text = f"""Page dimensions: {width:.1f}x{height:.1f}\n[Image 0x0 to {width:.0f}x{height:.0f}]\n"""
+    return text
+
+def prepare_ocr_messages(
+    pdf_or_image_path: str, 
+    task_type: str = "default", 
+    target_image_dim: int = 1800,
+    target_text_length: int = 8000,
+    page_num: int = 1,
+) -> List[Dict[str, Any]]:
+    """
+    Prepare messages for OCR processing from a PDF or image file.
+    
+    This function provides an end-to-end workflow that combines multiple processing steps
+    into a single call, creating messages ready for OCR processing with language models.
+    It handles both image and PDF inputs, with appropriate page selection for PDFs.
+    
+    Processing Steps:
+    1. Convert image to PDF if necessary (images are always treated as single pages)
+    2. Render the selected PDF page to base64 PNG
+    3. Extract anchor text from the page with position information
+    4. Apply appropriate prompt template based on task type
+    5. Create a messages structure ready for LLM API submission
+    
+    Args:
+        pdf_or_image_path (str): Path to a PDF or image file to process
+        task_type (str): Type of OCR task - "default" for standard markdown extraction,
+                         "structure" for enhanced layout analysis with HTML tables
+        target_image_dim (int): Target longest dimension for the rendered image in pixels
+        target_text_length (int): Maximum length of extracted text to include
+        page_num (int): Page number to process (default=1, for images always 1)
+        
+    Returns:
+        List[Dict[str, Any]]: Messages structure ready for OCR processing with an LLM API,
+                             containing both text prompt and image data
+    
+    Raises:
+        ValueError: If image conversion fails, page number is out of range, or other processing errors occur
+        
+    Examples:
+        >>> # Process the first page of a PDF
+        >>> messages = prepare_ocr_messages("document.pdf")
+        >>> 
+        >>> # Process page 5 of a PDF with structure analysis
+        >>> messages = prepare_ocr_messages(
+        ...     pdf_or_image_path="multipage.pdf",
+        ...     task_type="structure",
+        ...     page_num=5
+        ... )
+        >>> 
+        >>> # Process an image file (always page 1)
+        >>> messages = prepare_ocr_messages("scan.jpg")
+    """
+    # Check for required PDF utilities
+    ext = os.path.splitext(pdf_or_image_path)[1].lower()
+    is_image = ext not in [".pdf"]
+    
+    # Determine if the file is a PDF or image
+    filename = pdf_or_image_path
+    
+    try:
+        if is_image:
+            page_num = 1
+            img = Image.open(pdf_or_image_path)
+            # Render the image to base64 PNG
+            image_base64 = image_to_base64png(img)
+            # Get anchor text from the image
+            anchor_text = get_anchor_text_from_image(img)
+        else:
+            if page_num < 1:
+                page_num = 1
+            else:
+                page_num = int(page_num)  # cast to int
+            # Render the selected page to base64 PNG
+            image_base64 = render_pdf_to_base64png(
+                filename, page_num, target_longest_image_dim=target_image_dim
+            )
+            # Extract anchor text from the selected PDF page
+            anchor_text = get_anchor_text(
+                filename,
+                page_num,
+                pdf_engine="pdfreport",
+                target_length=target_text_length,
+            )
+        
+        
+        # Get the prompt template function for the specified task type
+        prompt_fn = get_prompt(task_type)
+        
+        # Apply the prompt template to the extracted anchor text
+        prompt_text = prompt_fn(anchor_text)
+        
+        # Create messages structure
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt_text},
+                    {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_base64}"}},
+                ],
+            }
+        ]
+        
+        return messages
+    except IndexError:
+        raise ValueError(f"Page number {page_num} is out of range for the document {pdf_or_image_path}")
+    except Exception as e:
+        raise ValueError(f"Error processing document: {str(e)}")
+
+def is_base64_string(input_string: str) -> bool:
+    try:
+        # Try to decode and re-encode to check validity
+        return base64.b64encode(base64.b64decode(input_string))[:10] == input_string.encode()[:10]
+    except Exception:
+        return False
+
+def ensure_image_in_path(input_string: str) -> str:
+    """
+    Detect whether the input is a base64-encoded image or a file path.
+
+    - If it's base64, decode and save it as a temporary image file.
+    - If it's a valid image format (e.g. JPEG, PNG), preserve the format.
+    - If it's not base64, return the input as-is (assumed to be a path).
+
+    Returns:
+        str: A file path (either the original or a temp file path if base64).
+    """
+    if input_string.endswith(".png") or input_string.endswith(".jpg") or input_string.endswith(".jpeg") or input_string.endswith(".pdf"):
+        return input_string
+    elif is_base64_string(input_string):
+        try:
+            image_data = base64.b64decode(input_string)
+            image = Image.open(io.BytesIO(image_data))
+            image_format = image.format.lower()  # e.g. 'jpeg', 'png'
+            # Save image to a temporary file with correct extension
+            temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=f".{image_format}")
+            image.save(temp_file.name, format=image_format)
+            return temp_file.name
+        except Exception:
+            return input_string
+    return input_string
+
+def ocr_document(pdf_or_image_path: str, task_type: str = "default", target_image_dim: int = 1800, target_text_length: int = 8000, page_num: int = 1, base_url: str = os.getenv("TYPHOON_BASE_URL", 'https://api.opentyphoon.ai/v1'), api_key: str = None, model: str = "typhoon-ocr-preview") -> str:
+    """
+    OCR a PDF or image file.
+    
+    This function provides an end-to-end workflow that combines multiple processing steps
+    into a single call, creating messages ready for OCR processing with language models.
+    It handles both image and PDF inputs, with appropriate page selection for PDFs.
+    
+    Args:
+        pdf_or_image_path (str): Path to a PDF or image file to process
+        task_type (str): Type of OCR task - "default" for standard markdown extraction,
+                         "structure" for enhanced layout analysis with HTML tables
+        target_image_dim (int): Target longest dimension for the rendered image in pixels
+        target_text_length (int): Maximum length of extracted text to include
+        page_num (int): Page number to process (default=1, for images always 1)
+        base_url (str): API base URL
+        api_key (str): API key for authentication (will also check environment variables if None)
+        model (str): Model identifier to use for OCR
+        
+    Returns:
+        str: Extracted text content in the specified format
+        
+    Raises:
+        ValueError: If image conversion fails, page number is out of range, or other processing errors occur
+    """
+    pdf_or_image_path = ensure_image_in_path(pdf_or_image_path)
+    
+    openai = OpenAI(base_url=base_url, api_key=api_key or os.getenv("TYPHOON_OCR_API_KEY") or os.getenv('TYPHOON_API_KEY') or os.getenv("OPENAI_API_KEY"))
+    messages = prepare_ocr_messages(
+        pdf_or_image_path=pdf_or_image_path,
+        task_type=task_type,
+        target_image_dim=target_image_dim,
+        target_text_length=target_text_length,
+        page_num=page_num if page_num else 1
+    )
+    response = openai.chat.completions.create(
+        model=model,
+        messages=messages,
+        max_tokens=16384,
+        extra_body={
+            "repetition_penalty": 1.2,
+            "temperature": 0.1,
+            "top_p": 0.6,
+        },
+    )
+    text_output = response.choices[0].message.content
+    text = json.loads(text_output)['natural_text']
+    return text

packages/typhoon_ocr/typhoon_ocr/pdf_utils.py

@@ -0,0 +1,46 @@
+import shutil
+import warnings
+
+def check_pdf_utilities():
+    """
+    Check if the required Poppler utilities (pdfinfo and pdftoppm) are installed.
+    
+    This function verifies if the necessary PDF utilities are available on the system
+    and provides helpful instructions if they are missing.
+    
+    Returns:
+        bool: True if all required utilities are available, False otherwise.
+    """
+    missing_utils = []
+    
+    # Check for pdfinfo
+    if shutil.which("pdfinfo") is None:
+        missing_utils.append("pdfinfo")
+    
+    # Check for pdftoppm
+    if shutil.which("pdftoppm") is None:
+        missing_utils.append("pdftoppm")
+    
+    if missing_utils:
+        warning_message = (
+            f"WARNING: The following required Poppler utilities are missing: {', '.join(missing_utils)}.\n"
+            "These utilities are required for PDF processing in Typhoon OCR.\n\n"
+            "Installation instructions:\n"
+            "- macOS: Run 'brew install poppler'\n"
+            "- Ubuntu/Debian: Run 'apt-get install poppler-utils'\n"
+            "- Windows: Install from https://github.com/oschwartz10612/poppler-windows/releases/ and add to PATH\n"
+        )
+        warnings.warn(warning_message, ImportWarning)
+        return False
+    
+    return True
+
+pdf_utils_available = check_pdf_utilities()
+if not pdf_utils_available:
+    message = ('PDF utilities are not available.'
+            "Installation instructions for Poppler utilities:\n"
+            "- macOS: Run 'brew install poppler'\n"
+            "- Ubuntu/Debian: Run 'apt-get install poppler-utils'\n"
+            "- Windows: Install from https://github.com/oschwartz10612/poppler-windows/releases/ and add to PATH"
+        )
+    raise ImportError(message)

requirements.txt

@@ -1,5 +1,7 @@
 openai
 python-dotenv
+ftfy
+pypdf
 gradio
-Pillow
-typhoon-ocr
+pillow
+typhoon-ocr