### Install Dependencies and Run Gradio App

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/README.md

Install project dependencies from requirements.txt and prepare for running the Gradio app. Optional vLLM installation is also included.

```bash
pip install -r requirements.txt
# edit .env
# pip install vllm # optional for hosting a local server
```

--------------------------------

### Example Usage of get_prompt

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/ocr_utils.md

Demonstrates how to get a prompt function and generate prompts for both Thai and English figure languages using the v1.5 template.

```python
from typhoon_ocr import get_prompt

# Get the v1.5 prompt function
prompt_fn = get_prompt("v1.5")

# Generate Thai language prompt
thai_prompt = prompt_fn(figure_language="Thai")
print(thai_prompt)

# Generate English language prompt
english_prompt = prompt_fn(figure_language="English")

```

--------------------------------

### Example Usage of check_pdf_utilities Function

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Shows how to call the check_pdf_utilities function and react based on its boolean return value, indicating whether PDF utilities are installed.

```python
from typhoon_ocr.pdf_utils import check_pdf_utilities

if check_pdf_utilities():
    print("All PDF utilities are installed")
else:
    print("PDF utilities missing - installation required")
```

--------------------------------

### Start vLLM Inference Server

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/README.md

Start a local vLLM inference server for the typhoon-ocr-7b model.

```bash
vllm serve scb10x/typhoon-ocr-7b --served-model-name typhoon-ocr --dtype bfloat16 --port 8101
```

--------------------------------

### Example Usage of pdf_utils_available Flag

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Demonstrates how to check the pdf_utils_available flag before attempting PDF processing. It prints a message indicating readiness or the need for installation.

```python
from typhoon_ocr import pdf_utils_available

if not pdf_utils_available:
    print("PDF processing not available - install poppler utilities")
else:
    print("PDF processing ready")
```

--------------------------------

### Install Gradio and python-dotenv for Demo

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Install `gradio` and `python-dotenv` via pip to set up the Gradio demo interface. These are optional dependencies for running the demo.

```bash
pip install gradio python-dotenv
```

--------------------------------

### Start vllm Server for Local Inference

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

Start a vllm server for local inference of the typhoon-ocr model. This is required for local processing.

```bash
# Start vllm server
vllm serve scb10x/typhoon-ocr-7b --served-model-name typhoon-ocr --port 8101
```

--------------------------------

### Install Poppler on Linux (Ubuntu/Debian)

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Install the `poppler-utils` package on Ubuntu/Debian-based Linux systems using apt-get. This is a required system dependency for PDF support.

```bash
sudo apt-get install poppler-utils
```

--------------------------------

### Install Typhoon OCR

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/README.md

Install the typhoon-ocr package using pip.

```bash
pip install typhoon-ocr
```

--------------------------------

### Example OCR Message Preparation

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/types.md

Illustrates how to prepare OCR messages using the `prepare_ocr_messages` function. This example shows how to obtain and access the text and image content within the prepared messages.

```python
messages = prepare_ocr_messages("document.pdf")
# messages[0]["content"][0] contains the text prompt
# messages[0]["content"][1] contains the image URL
```

--------------------------------

### Example Usage of process_pdf

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Demonstrates how to call the `process_pdf` function with sample inputs and shows the expected return values.

```python
image_pil, markdown_out = process_pdf(
    pdf_or_image_file=<uploaded_file>,
    task_type="default",
    page_number=1
)

# image_pil: PIL Image for preview
# markdown_out: Extracted markdown text or error message
```

--------------------------------

### Install Poppler on Linux

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/README.md

Install Poppler utilities on Linux, which are required for PDF processing.

```bash
sudo apt-get update
sudo apt-get install poppler-utils
# The following binaries are required and provided by poppler-utils:
# - pdfinfo
# - pdftoppm
```

--------------------------------

### Example PromptFunction Usage

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/types.md

Demonstrates how to obtain and use a prompt function. Retrieves a default prompt function and applies it to sample text.

```python
from typhoon_ocr import get_prompt

prompt_fn = get_prompt("default")
formatted = prompt_fn("extracted text content")
print(formatted)
```

--------------------------------

### Get Version

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Retrieves the installed version of the typhoon-ocr package.

```APIDOC
## __version__

### Description
Provides the current version of the typhoon-ocr package.

### Type
string

### Usage Example
```python
import typhoon_ocr

print(typhoon_ocr.__version__)  # "0.4.1"
```
```

--------------------------------

### Example .env File for Gradio Demo

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

A typical .env file configuration for the Gradio demo, including API and local inference settings.

```bash
# API Configuration
TYPHOON_BASE_URL=https://api.opentyphoon.ai/v1
TYPHOON_API_KEY=your-api-key-here

# Alternative: Use local vllm
# TYPHOON_BASE_URL=http://localhost:8101/v1
# TYPHOON_API_KEY=local-inference

# Model to use
TYPHOON_OCR_MODEL=typhoon-ocr
```

--------------------------------

### Check PDF Utilities Installation

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/errors.md

Verify the installation of Poppler utilities by checking their availability in the system's PATH. This is a crucial step before enabling PDF processing.

```bash
which pdfinfo
which pdftoppm
```

--------------------------------

### Connection Error Example

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Example of a connection error when the application fails to establish a network connection. Solutions focus on verifying URLs and server accessibility.

```text
ConnectionError: Failed to establish a new connection
```

--------------------------------

### check_pdf_utilities() - Verify installation

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

A function to explicitly check and verify the installation and accessibility of required PDF processing utilities. It provides detailed feedback if any dependencies are missing or misconfigured.

```APIDOC
## check_pdf_utilities()

### Description
Verifies the installation and proper configuration of PDF processing utilities.

### Method
`check_pdf_utilities()`

### Parameters
None

### Request Example
```python
from typhoon_ocr.api_reference.pdf_utils import check_pdf_utilities

try:
    check_pdf_utilities()
    print("PDF utilities verified successfully.")
except Exception as e:
    print(f"Error verifying PDF utilities: {e}")
```

### Response
#### Success Response
If successful, the function completes without raising an exception. A success message can be printed.

#### Response Example
```json
"PDF utilities verified successfully."
```

#### Error Response
Raises an exception if PDF utilities are not found or are misconfigured.
```

--------------------------------

### Get Typhoon OCR Package Version

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Prints the installed version of the typhoon_ocr package. This is useful for checking compatibility or reporting issues.

```python
import typhoon_ocr

print(typhoon_ocr.__version__)  # "0.4.1"
```

--------------------------------

### Install Poppler on Mac

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/README.md

Install Poppler utilities on macOS, which are required for PDF processing.

```bash
brew install poppler
# The following binaries are required and provided by poppler:
# - pdfinfo
# - pdftoppm
```

--------------------------------

### Install vllm for Local Inference

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Install the `vllm` package using pip to enable local inference capabilities for the OCR system. This is an optional dependency.

```bash
pip install vllm
```

--------------------------------

### Install Poppler for PDF Support

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

Install the Poppler utility for PDF processing on macOS, Linux, or Windows. This is required for PDF support in Typhoon OCR.

```bash
# macOS
brew install poppler

# Linux
sudo apt-get install poppler-utils

# Windows
# Download from https://github.com/oschwartz10612/poppler-windows/releases/
```

--------------------------------

### Get and Use a Prompt Function

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/internal_utilities.md

Demonstrates how to retrieve a prompt function for a specific task type and then use it with extracted text.

```python
from typhoon_ocr.ocr_utils import get_prompt

# Get the function for a task type
prompt_fn = get_prompt("default")

# Call with extracted text
prompt = prompt_fn("Page dimensions: 612x792\n[Text at position...]")
```

--------------------------------

### API Key Authentication Error

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Example of an OpenAI authentication error indicating an invalid API key. Solutions involve verifying the key and environment setup.

```text
openai.error.AuthenticationError: Invalid API key
```

--------------------------------

### check_pdf_utilities

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Checks if required Poppler utilities (pdfinfo and pdftoppm) are installed and available in the system PATH. Emits a warning with installation instructions if utilities are missing.

```APIDOC
## check_pdf_utilities

### Description
Checks if required Poppler utilities are installed and available. Uses `shutil.which()` to locate `pdfinfo` and `pdftoppm` in the system PATH.

### Returns
`bool`: True if both `pdfinfo` and `pdftoppm` commands are available, False otherwise.

### Side Effects
Emits a warning message via Python's warnings module with installation instructions for macOS, Ubuntu/Debian, and Windows if utilities are missing.

### Example
```python
from typhoon_ocr.pdf_utils import check_pdf_utilities

if check_pdf_utilities():
    print("All PDF utilities are installed")
else:
    print("PDF utilities missing - installation required")
```

### Installation Instructions (if False)

#### macOS
```bash
brew install poppler
```

#### Linux (Ubuntu/Debian)
```bash
sudo apt-get update
sudo apt-get install poppler-utils
```

#### Windows
1. Download from: https://github.com/oschwartz10612/poppler-windows/releases/
2. Extract to a directory
3. Add directory to system PATH environment variable
```

--------------------------------

### Valid Model and Task Type Combination

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Example showing a valid configuration using the 'typhoon-ocr-preview' model with the 'default' task type.

```python
from typhoon_ocr import ocr_document

# ✓ Valid - typhoon-ocr-preview with default task
ocr_document("file.pdf", model="typhoon-ocr-preview", task_type="default")
```

--------------------------------

### Check Poppler Availability

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Verify if Poppler, a PDF rendering library, is available in the environment. If not, installation is required.

```python
from typhoon_ocr import pdf_utils_available
if not pdf_utils_available:
    # Install Poppler
```

--------------------------------

### Docker Deployment Configuration

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Defines a Dockerfile for building a containerized Gradio application. Installs dependencies and exposes the application port.

```dockerfile
FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY app.py .
EXPOSE 7860
CMD ["python", "app.py"]
```

--------------------------------

### API Key Resolution Order Example

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Demonstrates the priority of API key resolution for the ocr_document function. It shows how an explicit parameter takes precedence over environment variables, with TYPHOON_OCR_API_KEY being preferred over TYPHOON_API_KEY.

```python
from typhoon_ocr import ocr_document
import os

# Setup environment
os.environ["TYPHOON_API_KEY"] = "env-key"

# This uses "explicit-key" (highest priority)
result1 = ocr_document("file.pdf", api_key="explicit-key")

# This uses "env-key" from TYPHOON_API_KEY
result2 = ocr_document("file.pdf")
```

--------------------------------

### Get Prompt

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Retrieves a prompt template, potentially for use in custom OCR workflows.

```APIDOC
## get_prompt()

### Description
Retrieves a prompt template, identified by a version string.

### Method
Direct function call.

### Parameters
- **version** (string) - Required - The version identifier for the prompt (e.g., 'v1.5').

### Request Example
```python
from typhoon_ocr import get_prompt

prompt_fn = get_prompt("v1.5")
```

### Response
#### Success Response
- **prompt_template** (string/object) - The requested prompt template.

#### Response Example
```json
{
  "example": "Prompt template string or object..."
}
```
```

--------------------------------

### Check Availability of PDF Utilities

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Check if essential Poppler utilities (pdfinfo and pdftoppm) are installed and available for PDF processing. This is a boolean flag indicating readiness.

```python
from typhoon_ocr import pdf_utils_available

if pdf_utils_available:
    print("PDF processing available")
else:
    print("PDF processing not available - install Poppler")
```

--------------------------------

### API Timeout Error Example

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Example of an OpenAI timeout error, indicating the request took too long to complete. Solutions involve reducing image dimensions or using different task types.

```text
openai.error.Timeout: Request timed out
```

--------------------------------

### Function to Check PDF Utilities

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Checks if both pdfinfo and pdftoppm commands are available in the system PATH. Emits a warning with installation instructions if utilities are missing.

```python
def check_pdf_utilities() -> bool:
    # ... implementation details ...
    pass
```

--------------------------------

### Integration with OCR Processing

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Demonstrates how the prepare_ocr_messages function automatically checks for PDF utility availability and raises an ImportError if Poppler is not installed.

```python
from typhoon_ocr import prepare_ocr_messages

# This automatically checks pdf_utils_available
# and raises ImportError if Poppler is not installed
messages = prepare_ocr_messages("document.pdf")
```

--------------------------------

### Get Prompt Template

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Retrieves a prompt template for a specific task type using the `get_prompt` function. This is useful for customizing the LLM's instructions.

```python
prompt_fn = get_prompt("v1.5")
```

--------------------------------

### Check PDF Utility Availability

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/errors.md

Check if PDF utilities (Poppler) are available before attempting PDF processing. Provides user-friendly installation instructions if unavailable.

```python
from typhoon_ocr import prepare_ocr_messages, pdf_utils_available

if not pdf_utils_available:
    print("Poppler not installed - PDF processing unavailable")
    print("Install with: brew install poppler (macOS) or apt-get install poppler-utils (Linux)")
else:
    # Safe to process PDFs
    messages = prepare_ocr_messages("document.pdf")
```

--------------------------------

### Memory Issue Debugging with tracemalloc

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Python code snippet demonstrating how to use the `tracemalloc` module to start memory tracing for debugging memory issues during PDF processing.

```python
# In process_pdf, add try-catch for memory
import tracemalloc
tracemalloc.start()
# ... processing ...
# For debugging: print memory usage
```

--------------------------------

### Check PDF Utilities Availability

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Checks if the necessary PDF processing utilities (like Poppler) are installed. This is useful for conditional processing or providing warnings to the user.

```python
from typhoon_ocr import pdf_utils_available

if not pdf_utils_available:
    print("Warning: Poppler not installed")
    # Fall back to image-only processing
```

--------------------------------

### Reinstall Package to Fix ImportError

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Provides the command to upgrade and reinstall the typhoon-ocr package using pip. This is the solution for `AttributeError: module 'typhoon_ocr' has no attribute 'prepare_ocr_messages'`, often caused by an improperly installed package.

```bash
pip install --upgrade typhoon-ocr
```

--------------------------------

### Verify PDF Utility Dependencies via Command Line

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Shows how to check for the presence of required system binaries (pdfinfo, pdftoppm) using command-line tools. Also includes a Python one-liner to check the availability flag.

```bash
# Check for pdfinfo
which pdfinfo

# Check for pdftoppm  
which pdftoppm

# Or with our utility
python -c "from typhoon_ocr import pdf_utils_available; print(pdf_utils_available)"
```

--------------------------------

### Get PDF MediaBox Dimensions

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/internal_utilities.md

Extracts the MediaBox dimensions (width and height) of a PDF page using the pdfinfo command. Requires Poppler utilities to be installed.

```python
from typhoon_ocr.ocr_utils import get_pdf_media_box_width_height

width, height = get_pdf_media_box_width_height("document.pdf", page_num=1)
print(f"Page 1 dimensions: {width} x {height} points")

# Convert to pixels at 72 DPI (standard PDF resolution)
width_px = width
height_px = height
print(f"At standard DPI: {width_px} x {height_px} pixels")
```

--------------------------------

### Initialize OpenAI Client

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Loads environment variables for API credentials and initializes the OpenAI client. Ensure TYPHOON_BASE_URL and TYPHOON_API_KEY are set in your .env file.

```python
import os
from dotenv import load_dotenv
from openai import OpenAI

# Load environment variables from .env file
load_dotenv()

# Initialize OpenAI client with credentials
openai = OpenAI(
    base_url=os.getenv("TYPHOON_BASE_URL"),
    api_key=os.getenv("TYPHOON_API_KEY")
)
```

--------------------------------

### Run Gradio Demo

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/README.md

Execute the Gradio demo application to interact with the Typhoon OCR model.

```bash
python app.py
```

--------------------------------

### Check PDF Utility Availability at Runtime

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Demonstrates how to safely use PDF features by checking for the availability of PDF utilities at runtime. Imports are conditional based on the availability.

```python
from typhoon_ocr import pdf_utils_available

if pdf_utils_available:
    # Safe to use PDF features
    from typhoon_ocr import prepare_ocr_messages
    messages = prepare_ocr_messages("file.pdf")
else:
    # PDF features not available
    # Images only
    from typhoon_ocr import prepare_ocr_messages
    messages = prepare_ocr_messages("file.jpg")
```

--------------------------------

### Launch Gradio App (Public Share)

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Launches the Gradio application and generates a temporary public URL for sharing. This URL is valid for 72 hours.

```python
demo.launch(share=True)  # Generates 72-hour public URL
```

--------------------------------

### pdftoppm Command Syntax

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Shows the command-line syntax for pdftoppm to render PDF pages into PNG images, specifying page range, resolution (DPI), and output format.

```bash
pdftoppm -png -f <page> -l <page> -r <dpi> <pdf_file>
```

--------------------------------

### Get OCR Prompt

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Retrieve a specific OCR prompt version. The 'typhoon_ocr' library provides this utility.

```python
from typhoon_ocr import get_prompt
fn = get_prompt("v1.5")
```

--------------------------------

### OCR Document with Default Task Type

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Example of calling ocr_document with the 'default' task type for simple documents.

```python
ocr_document("file.pdf", task_type="default")
```

--------------------------------

### Load API Key from .env File

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/errors.md

Load the API key from a .env file using `dotenv` and then pass it to the `ocr_document` function. This helps manage credentials securely.

```python
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("TYPHOON_API_KEY")

result = ocr_document("file.pdf", api_key=api_key)
```

--------------------------------

### Perform Simple OCR Extraction

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Use this function to extract text from a PDF document. Ensure the 'typhoon_ocr' library is installed.

```python
from typhoon_ocr import ocr_document
result = ocr_document("file.pdf")
```

--------------------------------

### Production Deployment with Gunicorn

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Deploys the Gradio application in production using Gunicorn. Configured for multiple workers and a longer timeout for processing.

```bash
gunicorn -w 1 -b 0.0.0.0:7860 --timeout 120 \
    "app:demo.launch(share=False, server_name='0.0.0.0', server_port=7860)"
```

--------------------------------

### OCR Document with Lower Image Resolution

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Example of calling ocr_document with a reduced target_image_dim for faster processing at the cost of quality.

```python
# Faster, lower quality
ocr_document("file.pdf", target_image_dim=1024)
```

--------------------------------

### Import Core Functions

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/packages/typhoon_ocr/README.md

Import the main functions `ocr_document` and `prepare_ocr_messages` from the typhoon_ocr package.

```python
from typhoon_ocr import ocr_document, prepare_ocr_messages
```

--------------------------------

### Launch Gradio App (Local)

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Launches the Gradio application for local access only, without generating a public shareable link.

```python
demo.launch(share=False)
```

--------------------------------

### OCR Document with Structure Task Type

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Example of calling ocr_document with the 'structure' task type for complex documents with forms and images.

```python
ocr_document("file.pdf", task_type="structure")
```

--------------------------------

### Required Environment Variables

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Lists essential environment variables for configuring the API connection and OCR model. Ensure these are set in your environment or .env file.

```bash
TYPHOON_BASE_URL=https://api.opentyphoon.ai/v1
TYPHOON_API_KEY=<your-api-key>
TYPHOON_OCR_MODEL=typhoon-ocr
```

--------------------------------

### Optional Environment Variables

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Lists optional environment variables for customizing application behavior, such as logging level and Gradio sharing.

```bash
LOG_LEVEL=INFO
GRADIO_SHARE=False
```

--------------------------------

### Invalid Model and Task Type Combination

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Example demonstrating an invalid configuration that will raise an AssertionError, using 'typhoon-ocr-preview' with the 'v1.5' task type.

```python
# ✗ Invalid - will raise AssertionError
ocr_document("file.pdf", model="typhoon-ocr-preview", task_type="v1.5")
```

--------------------------------

### OCR Processing with Environment File

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Load environment variables, including API key and base URL, from a .env file for OCR processing. This simplifies configuration management.

```python
from dotenv import load_dotenv
from typhoon_ocr import ocr_document

load_dotenv()
result = ocr_document("document.pdf")
```

--------------------------------

### Set Environment Variables for Local Inference

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Exporting environment variables to direct Typhoon OCR to a local vllm server.

```bash
export TYPHOON_BASE_URL="http://localhost:8101/v1"
export TYPHOON_API_KEY="any-value"
```

--------------------------------

### OCR Document Function with TYPHOON_OCR_API_KEY

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Illustrates calling the ocr_document function when TYPHOON_OCR_API_KEY is set, demonstrating its preferred status in the API key resolution order.

```bash
export TYPHOON_OCR_API_KEY="key1"
```

--------------------------------

### Project File Navigation Structure

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Illustrates the directory structure and navigation of the Typhoon OCR project. This helps users understand where to find different components and documentation.

```tree
README.md (this file)
├── index.md (Start here for overview)
├── api-reference/
│   ├── package_exports.md (All exported symbols)
│   ├── ocr_utils.md (Core functions)
│   ├── pdf_utils.md (PDF utilities)
│   ├── internal_utilities.md (Advanced internal APIs)
│   └── gradio_app.md (Web UI documentation)
├── types.md (Type definitions)
├── configuration.md (Environment setup)
└── errors.md (Error handling)
```

--------------------------------

### OCR Document with v1.5 Task Type and Thai Figures

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Example of calling ocr_document with the recommended 'v1.5' task type and specifying Thai for figure language.

```python
ocr_document("file.pdf", task_type="v1.5", figure_language="Thai")
```

--------------------------------

### Run All Tests

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/tests/README.md

Execute all tests in the typhoon-ocr package by navigating to the project directory and running pytest.

```bash
cd /Users/kunato/typhoon-applications/typhoon-ocr
python -m pytest tests/ -v
```

--------------------------------

### Simple OCR with Defaults

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/ocr_utils.md

Extracts text from an image file using default OCR settings. Ensure API credentials are set via environment variables.

```python
from typhoon_ocr import ocr_document
import os

# Set API credentials via environment
os.environ["TYPHOON_API_KEY"] = "your-api-key"

# Extract text from image
result = ocr_document("document.jpg")
print(result)  # Extracted markdown text
```

--------------------------------

### Retrieve Prompt Template Function

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Get a prompt template function for a specific OCR task by its name. The returned function can format prompts based on provided arguments.

```python
from typhoon_ocr import get_prompt

prompt_fn = get_prompt("v1.5")
formatted_prompt = prompt_fn(figure_language="Thai")
```

--------------------------------

### Handle AssertionError for Task Type

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/errors.md

Catch and handle AssertionError when an unsupported task type is used with a preview model. This example provides specific feedback for task type issues.

```python
from typhoon_ocr import ocr_document

try:
    # This will fail - v1.5 not supported for preview model
    result = ocr_document(
        "file.pdf",
        model="typhoon-ocr-preview",
        task_type="v1.5"
    )
except AssertionError as e:
    if "task_type" in str(e):
        print("Use default or structure task_type with preview models")
    else:
        print(f"Internal assertion failed: {e}")
```

--------------------------------

### Define PageReport with Example Usage

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/types.md

A comprehensive report for a PDF page, containing its mediabox and lists of text and image elements. Demonstrates accessing page dimensions and iterating through elements.

```python
from dataclasses import dataclass
from typing import List

# Assuming BoundingBox, TextElement, and ImageElement are defined

@dataclass(frozen=True)
class PageReport:
    mediabox: BoundingBox
    text_elements: List[TextElement]
    image_elements: List[ImageElement]

# Example Usage (assuming _pdf_report is available):
# from typhoon_ocr.ocr_utils import _pdf_report
# report = _pdf_report("document.pdf", page_num=1)
# width = report.mediabox.x1 - report.mediabox.x0
# height = report.mediabox.y1 - report.mediabox.y0
# for text_elem in report.text_elements:
#     print(f"Text: {text_elem.text} at ({text_elem.x}, {text_elem.y})")
# for img_elem in report.image_elements:
#     print(f"Image {img_elem.name} in region: {img_elem.bbox}")
```

--------------------------------

### Configure Local Inference with vllm

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Configures `ocr_document` to use a local inference server (like vllm) by specifying the base URL, model name, and a dummy API key. This is for running OCR models locally.

```python
from typhoon_ocr import ocr_document

# Configure for local vllm
result = ocr_document(
    "file.pdf",
    base_url="http://localhost:8101/v1",
    model="typhoon-ocr",
    api_key="dummy"
)
```

--------------------------------

### Apply Affine Transformation to a 2D Point

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/internal_utilities.md

Applies a 6-element affine transformation matrix to a 2D point (x, y). This is used to calculate transformed coordinates, for example, for image bounding boxes.

```python
from typhoon_ocr.ocr_utils import _transform_point

# Translation matrix (move by 100, 50)
matrix = [1, 0, 0, 1, 100, 50]

# Transform point (10, 20)
x_new, y_new = _transform_point(10, 20, matrix)
print(x_new, y_new)  # Output: 110, 70

# Scale and translate
scale_translate = [2, 0, 0, 2, 10, 20]
x2, y2 = _transform_point(5, 5, scale_translate)
print(x2, y2)  # Output: 20, 30  (5*2+10, 5*2+20)
```

--------------------------------

### Task Selection Radio Buttons

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Sets up a Gradio Radio component for task selection with 'default' and 'structure' options. Includes HTML to explain the differences between modes.

```python
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"])

```

--------------------------------

### Retrieve v1.5 Prompt Function

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/ocr_utils.md

Retrieves the prompt function for OCR v1.5, which supports clean markdown output. For v1.5, pass the figure language instead of text to get language-specific instructions.

```python
prompt_fn = get_prompt("v1.5")
# For v1.5, pass figure_language instead of text
formatted_prompt = prompt_fn(figure_language="Thai")
# Returns prompt with language-specific instructions
```

--------------------------------

### Check PDF Utilities Function

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Imports and calls the `check_pdf_utilities` function from the `pdf_utils` submodule. This function returns a boolean indicating if PDF utilities are ready.

```python
from typhoon_ocr.pdf_utils import check_pdf_utilities

if check_pdf_utilities():
    print("Poppler OK")
```

--------------------------------

### Set Optional Environment Variables

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Sets optional environment variables for the Typhoon API, such as the base URL and OCR model. Defaults are provided if these are not set.

```bash
export TYPHOON_BASE_URL="https://api.opentyphoon.ai/v1"
export TYPHOON_OCR_MODEL="typhoon-ocr"
```

--------------------------------

### Verify Page Number for PDF OCR

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

Ensure the page number used for OCR processing is within the valid range of the PDF document. This example shows how to check and use a valid page number.

```python
# Verify page_num <= total_pages
ocr_document("file.pdf", page_num=1)  # Valid: page 1
```

--------------------------------

### Set Typhoon OCR Base URL

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Configure the base URL for the Typhoon OCR API endpoint. This is used when making requests to LLM services. Examples show setting the official API, a local inference server, or an OpenAI compatible server.

```bash
# Use official Typhoon API
export TYPHOON_BASE_URL="https://api.opentyphoon.ai/v1"

# Use local inference server
export TYPHOON_BASE_URL="http://localhost:8101/v1"

# Use OpenAI compatible server
export TYPHOON_BASE_URL="http://192.168.1.100:8000/v1"
```

--------------------------------

### Import Internal Type BoundingBox for Custom Use

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Shows how to import the `BoundingBox` type from `typhoon_ocr.ocr_utils` when needed for custom implementations. This is contrasted with standard usage where such imports are not necessary.

```python
# For custom implementations
from typhoon_ocr.ocr_utils import BoundingBox

# For standard usage, not needed
from typhoon_ocr import prepare_ocr_messages
```

--------------------------------

### Use Typhoon OCR with Local vllm Server

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/configuration.md

Python code to configure ocr_document to use a locally running vllm server.

```python
from typhoon_ocr import ocr_document

result = ocr_document(
    pdf_or_image_path="document.pdf",
    base_url="http://localhost:8101/v1",
    model="typhoon-ocr",
    api_key="dummy-key"  # vllm doesn't require real keys
)
```

--------------------------------

### Correct Import for ocr_document

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Illustrates the correct way to import the `ocr_document` function directly from the `typhoon_ocr` package, contrasting it with an incorrect import path.

```python
# ✗ Wrong
from typhoon_ocr.ocr_utils import ocr_document

# ✓ Correct
from typhoon_ocr import ocr_document
```

--------------------------------

### OCR Document with Local Inference

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

Process a PDF document using a locally running vllm server. Specify the base URL and a dummy API key.

```python
from typhoon_ocr import ocr_document

result = ocr_document(
    "document.pdf",
    base_url="http://localhost:8101/v1",
    api_key="dummy-key"
)
```

--------------------------------

### Simple OCR with PNG File

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

Perform OCR on a PNG image file using the ocr_document function and print the resulting Markdown output. Ensure the TYPHOON_API_KEY is set.

```python
# examples/simple_ocr.py
from typhoon_ocr import ocr_document
import os

os.environ["TYPHOON_API_KEY"] = "your-key"

markdown = ocr_document("test.png")
print(markdown)
```

--------------------------------

### pdfinfo Command Syntax

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/pdf_utils.md

Illustrates the command-line syntax for using pdfinfo to extract PDF metadata, including page range and box information.

```bash
pdfinfo -f <page> -l <page> -box -enc UTF-8 <pdf_file>
```

--------------------------------

### Customizing Gradio Theme Colors

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Python code showing how to customize the theme of a Gradio application using the `gr.themes.Soft` class and defining primary hue colors.

```python
theme = gr.themes.Soft(
    primary_hue=gr.themes.Color(
        c50="#your-color",
        # ... other color levels
    ),
)
```

--------------------------------

### Import Internal Types from ocr_utils

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Demonstrates how to import internal types like BoundingBox, TextElement, and PageReport from the ocr_utils submodule if needed for custom implementations. This is generally not recommended for standard usage.

```python
# Available but not recommended for standard use
from typhoon_ocr.ocr_utils import (
    _pdf_report,
    BoundingBox,
    TextElement,
    ImageElement,
    PageReport,
)
```

--------------------------------

### All Exports from Typhoon OCR Package

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/package_exports.md

Lists all public symbols available for import from the root of the typhoon_ocr package.

```python
__all__ = [
    "pdf_utils_available",
    "prepare_ocr_messages",
    "get_prompt",
    "get_anchor_text", 
    "image_to_pdf",
    "ocr_document",
]
```

--------------------------------

### Event Connection for Run Button

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/api-reference/gradio_app.md

Connects the 'Run' button's click event to the `process_pdf` function, specifying input and output components.

```python
run_button.click(
    fn=process_pdf,
    inputs=[pdf_input, task_dropdown, page_number],
    outputs=[image_output, markdown_output]
)
```

--------------------------------

### Use with Custom API Endpoint and Model

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

Process a document using a custom API endpoint and specify a custom model name. This allows for flexibility in deployment.

```python
from typhoon_ocr import ocr_document

result = ocr_document(
    "document.pdf",
    base_url="http://custom-server:8000/v1",
    api_key="custom-key",
    model="custom-model"
)
```

--------------------------------

### get_prompt() - Access prompt templates

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/README.md

Retrieves the available prompt templates used by the OCR system. This function allows users to inspect or customize the prompts sent to the LLM.

```APIDOC
## get_prompt()

### Description
Retrieves and returns the default prompt templates used for OCR tasks.

### Method
`get_prompt(template_name: str = None)`

### Parameters
#### Path Parameters
- **template_name** (str, optional) - The name of a specific prompt template to retrieve. If None, returns all available templates.

### Request Example
```python
from typhoon_ocr.api_reference.ocr_utils import get_prompt

# Get a specific prompt template
llm_prompt = get_prompt("document_analysis")
print(llm_prompt)

# Get all available prompt templates
all_prompts = get_prompt()
print(all_prompts)
```

### Response
#### Success Response
- **prompt_template** (str or dict) - The requested prompt template string or a dictionary of all available templates.

#### Response Example
```json
"You are an AI assistant that extracts text from documents..."
```
```

--------------------------------

### Configure OpenAI-Compatible API Endpoint

Source: https://github.com/scb-10x/typhoon-ocr/blob/master/_autodocs/index.md

This snippet shows how to use the `ocr_document` function with a custom OpenAI-compatible API endpoint. Ensure you provide the correct `base_url`, `model`, and `api_key` for your service.

```python
from typhoon_ocr import ocr_document

# Any OpenAI-compatible API server
result = ocr_document(
    "file.pdf",
    base_url="http://your-server:port/v1",
    model="your-model-name",
    api_key="your-key"
)
```