llm-markdownify 0.1.0__tar.gz

llm_markdownify-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Envs
+.venv/
+.uv/
+.env
+.env.*
+
+# Build
+build/
+dist/
+*.egg-info/
+
+# IDE
+.vscode/
+.idea/
+
+# Tests
+.coverage
+htmlcov/
+.pytest_cache/
+
+test_files/

llm_markdownify-0.1.0/LICENSE

@@ -0,0 +1,73 @@
+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
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

llm_markdownify-0.1.0/NOTICE

@@ -0,0 +1,6 @@
+llm-markdownify - Convert documents to Markdown using Vision LLMs
+
+Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+
+This product includes software developed by Sethu Pavan Venkata Reddy Pastula.
+Project: https://github.com/sethupavan12/Markdownify

llm_markdownify-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: llm-markdownify
+Version: 0.1.0
+Summary: Convert documents (PDF, DOCX) to high-quality Markdown using Vision LLMs via LiteLLM
+Project-URL: Homepage, https://github.com/sethupavan12/Markdownify
+Project-URL: Repository, https://github.com/sethupavan12/Markdownify
+Project-URL: Issues, https://github.com/sethupavan12/Markdownify/issues
+Author: Sethu Pavan Venkata Reddy Pastula
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: docx,litellm,llm,markdown,ocr,pdf,vision
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: litellm[proxy]>=1.43.0
+Requires-Dist: pillow>=10.3.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pypdfium2>=4.30.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: typer>=0.12.3
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.6; extra == 'dev'
+Provides-Extra: docx
+Requires-Dist: docx2pdf>=0.1.8; extra == 'docx'
+Description-Content-Type: text/markdown
+
+## Markdownify
+
+Mardownify is a super easy-to-use PDF to high-quality Markdown converter using Vision LLMs. It supports text, images, signatures, tables, charts, flowcharts and preserves document structure (Headings, numbered lists etc).
+
+Tables become Markdown tables, charts become Mermaid diagrams, and images get concise summaries. Use as a CLI or Python library. Works with 100+ LLMs. Recommended to use with `gpt-5-mini` or `gpt-4.1-mini` or even better models for better performance. 
+
+### Features
+- High-quality complex markdown generation powered by LLMs. 
+- Supports Text, Images, Tables, Charts.
+- Built-in prompts tuned for clean Markdown, Mermaid, and structured headings along with ability to customise.
+- Supports multi-page tables, charts and images.
+- High-fidelity page rendering from PDF.
+- Optional DOCX→PDF conversion using MS word installation.
+- Works seamlessly with 100+ LLMs with LiteLLM Intergration.
+
+### Install
+```bash
+uv pip install llm-markdownify
+# or
+pip install llm-markdownify
+```
+
+### Quickstart (CLI)
+```bash
+markdownify run input.pdf -o output.md --model gpt-5-mini
+```
+
+### Python API (one-liner)
+```python
+from llm_markdownify import convert
+
+convert(
+    "input.pdf",
+    "output.md",
+    model="gpt-5-mini",   # optional; can rely on env/provider defaults
+    dpi=72,
+    profile="contracts",    # or path to JSON profile
+)
+```
+
+Optional DOCX support (macOS/Windows via Word):
+```bash
+pip install llm-markdownify[docx]
+```
+
+### Configure your provider (via LiteLLM)
+Pick one of the following. See the full providers list and details in the LiteLLM docs: [Supported Providers](https://docs.litellm.ai/docs/providers).
+
+- **OpenAI**
+  - Set your API key:
+    ```bash
+    export OPENAI_API_KEY="sk-..."
+    ```
+  - Example usage:
+    ```bash
+    markdownify run input.pdf -o output.md --model gpt-5-mini
+    ```
+
+- **Google Gemini**
+  - Set your API key (Google AI Studio key):
+    ```bash
+    export GOOGLE_API_KEY="..."
+    ```
+  - Example usage (pick a Gemini vision-capable model):
+    ```bash
+    markdownify run input.pdf -o output.md --model gemini/gemini-2.5-flash
+    ```
+
+- **Azure OpenAI**
+  - Set these environment variables (values from your Azure OpenAI resource):
+    ```bash
+    export AZURE_API_KEY="..."
+    export AZURE_API_BASE="https://<your-resource>.openai.azure.com"
+    export AZURE_API_VERSION=""
+    ```
+  - Use your deployment name via the `azure/<deployment_name>` model syntax:
+    ```bash
+    markdownify run input.pdf -o output.md --model azure/<deployment_name>
+    ```
+  - See: [LiteLLM Azure OpenAI](https://docs.litellm.ai/docs/providers/azure_openai)
+
+- **OpenAI-compatible APIs**
+  - Many providers expose an OpenAI-compatible REST API. Set your API key and base URL:
+    ```bash
+    export OPENAI_API_KEY="..."
+    export OPENAI_API_BASE="https://your-openai-compatible-endpoint.com/v1"
+    ```
+  - Use the model name supported by that endpoint:
+    ```bash
+    markdownify run input.pdf -o output.md --model <model-name>
+    ```
+  - Reference: [LiteLLM Providers](https://docs.litellm.ai/docs/providers)
+
+For additional providers and advanced configuration (fallbacks, cost tracking, streaming), see the LiteLLM docs: [Getting Started](https://docs.litellm.ai/).
+
+### Configuration flags
+- `--model`: LiteLLM model (e.g., `gpt-5-mini`, `azure/<deployment>`, `gemini/gemini-2.5-flash`)
+- `--dpi`: Render DPI (default 72)
+- `--max-group-pages`: Max pages to merge for continued content (default 3)
+- `--no-grouping`: Disable LLM-based grouping
+- `--temperature`, `--max-tokens`: LLM generation params
+
+### Dev tooling
+- Install pre-commit and enable the license header hook:
+  ```bash
+  pip install pre-commit
+  pre-commit install
+  # run on all files once
+  pre-commit run --all-files
+  ```
+  This inserts the header:
+  ```
+  # Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+  # Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+  # SPDX-License-Identifier: Apache-2.0
+  ```
+
+### Attribution & License
+This project uses the Apache 2.0 License, which includes an attribution/NOTICE requirement. If you distribute or use this project, please keep the `LICENSE` and `NOTICE` files intact, crediting the original author, Sethu Pavan Venkata Reddy Pastula.
+
+- Project repository: https://github.com/sethupavan12/Markdownify
+
+### Development
+- Requires Python 3.10+
+- Use `uv` for fast installs: `uv sync`
+- Run tests: `pytest`
+- Lint: `ruff check src tests`
+
+### Releasing
+GitHub Actions are configured to:
+- Run tests on PRs/pushes
+- Build & publish to PyPI on tagged releases (requires `PYPI_API_TOKEN` secret)

llm_markdownify-0.1.0/README.md

@@ -0,0 +1,132 @@
+## Markdownify
+
+Mardownify is a super easy-to-use PDF to high-quality Markdown converter using Vision LLMs. It supports text, images, signatures, tables, charts, flowcharts and preserves document structure (Headings, numbered lists etc).
+
+Tables become Markdown tables, charts become Mermaid diagrams, and images get concise summaries. Use as a CLI or Python library. Works with 100+ LLMs. Recommended to use with `gpt-5-mini` or `gpt-4.1-mini` or even better models for better performance. 
+
+### Features
+- High-quality complex markdown generation powered by LLMs. 
+- Supports Text, Images, Tables, Charts.
+- Built-in prompts tuned for clean Markdown, Mermaid, and structured headings along with ability to customise.
+- Supports multi-page tables, charts and images.
+- High-fidelity page rendering from PDF.
+- Optional DOCX→PDF conversion using MS word installation.
+- Works seamlessly with 100+ LLMs with LiteLLM Intergration.
+
+### Install
+```bash
+uv pip install llm-markdownify
+# or
+pip install llm-markdownify
+```
+
+### Quickstart (CLI)
+```bash
+markdownify run input.pdf -o output.md --model gpt-5-mini
+```
+
+### Python API (one-liner)
+```python
+from llm_markdownify import convert
+
+convert(
+    "input.pdf",
+    "output.md",
+    model="gpt-5-mini",   # optional; can rely on env/provider defaults
+    dpi=72,
+    profile="contracts",    # or path to JSON profile
+)
+```
+
+Optional DOCX support (macOS/Windows via Word):
+```bash
+pip install llm-markdownify[docx]
+```
+
+### Configure your provider (via LiteLLM)
+Pick one of the following. See the full providers list and details in the LiteLLM docs: [Supported Providers](https://docs.litellm.ai/docs/providers).
+
+- **OpenAI**
+  - Set your API key:
+    ```bash
+    export OPENAI_API_KEY="sk-..."
+    ```
+  - Example usage:
+    ```bash
+    markdownify run input.pdf -o output.md --model gpt-5-mini
+    ```
+
+- **Google Gemini**
+  - Set your API key (Google AI Studio key):
+    ```bash
+    export GOOGLE_API_KEY="..."
+    ```
+  - Example usage (pick a Gemini vision-capable model):
+    ```bash
+    markdownify run input.pdf -o output.md --model gemini/gemini-2.5-flash
+    ```
+
+- **Azure OpenAI**
+  - Set these environment variables (values from your Azure OpenAI resource):
+    ```bash
+    export AZURE_API_KEY="..."
+    export AZURE_API_BASE="https://<your-resource>.openai.azure.com"
+    export AZURE_API_VERSION=""
+    ```
+  - Use your deployment name via the `azure/<deployment_name>` model syntax:
+    ```bash
+    markdownify run input.pdf -o output.md --model azure/<deployment_name>
+    ```
+  - See: [LiteLLM Azure OpenAI](https://docs.litellm.ai/docs/providers/azure_openai)
+
+- **OpenAI-compatible APIs**
+  - Many providers expose an OpenAI-compatible REST API. Set your API key and base URL:
+    ```bash
+    export OPENAI_API_KEY="..."
+    export OPENAI_API_BASE="https://your-openai-compatible-endpoint.com/v1"
+    ```
+  - Use the model name supported by that endpoint:
+    ```bash
+    markdownify run input.pdf -o output.md --model <model-name>
+    ```
+  - Reference: [LiteLLM Providers](https://docs.litellm.ai/docs/providers)
+
+For additional providers and advanced configuration (fallbacks, cost tracking, streaming), see the LiteLLM docs: [Getting Started](https://docs.litellm.ai/).
+
+### Configuration flags
+- `--model`: LiteLLM model (e.g., `gpt-5-mini`, `azure/<deployment>`, `gemini/gemini-2.5-flash`)
+- `--dpi`: Render DPI (default 72)
+- `--max-group-pages`: Max pages to merge for continued content (default 3)
+- `--no-grouping`: Disable LLM-based grouping
+- `--temperature`, `--max-tokens`: LLM generation params
+
+### Dev tooling
+- Install pre-commit and enable the license header hook:
+  ```bash
+  pip install pre-commit
+  pre-commit install
+  # run on all files once
+  pre-commit run --all-files
+  ```
+  This inserts the header:
+  ```
+  # Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+  # Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+  # SPDX-License-Identifier: Apache-2.0
+  ```
+
+### Attribution & License
+This project uses the Apache 2.0 License, which includes an attribution/NOTICE requirement. If you distribute or use this project, please keep the `LICENSE` and `NOTICE` files intact, crediting the original author, Sethu Pavan Venkata Reddy Pastula.
+
+- Project repository: https://github.com/sethupavan12/Markdownify
+
+### Development
+- Requires Python 3.10+
+- Use `uv` for fast installs: `uv sync`
+- Run tests: `pytest`
+- Lint: `ruff check src tests`
+
+### Releasing
+GitHub Actions are configured to:
+- Run tests on PRs/pushes
+- Build & publish to PyPI on tagged releases (requires `PYPI_API_TOKEN` secret)

llm_markdownify-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llm-markdownify"
+version = "0.1.0"
+description = "Convert documents (PDF, DOCX) to high-quality Markdown using Vision LLMs via LiteLLM"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [
+  { name = "Sethu Pavan Venkata Reddy Pastula" }
+]
+keywords = ["markdown", "pdf", "docx", "llm", "vision", "ocr", "litellm"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Topic :: Text Processing :: Markup",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "litellm[proxy]>=1.43.0",
+  "pypdfium2>=4.30.0",
+  "Pillow>=10.3.0",
+  "typer>=0.12.3",
+  "pydantic>=2.7.0",
+  "tqdm>=4.66.0",
+]
+
+[project.optional-dependencies]
+docx = [
+  "docx2pdf>=0.1.8",
+]
+dev = [
+  "pytest>=8.2.0",
+  "pytest-cov>=5.0.0",
+  "ruff>=0.5.6",
+  "pre-commit>=3.6.0",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.2.0",
+  "pytest-cov>=5.0.0",
+  "ruff>=0.5.6",
+  "pre-commit>=3.6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sethupavan12/Markdownify"
+Repository = "https://github.com/sethupavan12/Markdownify"
+Issues = "https://github.com/sethupavan12/Markdownify/issues"
+
+[project.scripts]
+markdownify = "llm_markdownify.cli:app"
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llm_markdownify"]
+
+[tool.hatch.build]
+include = [
+  "src/llm_markdownify/**",
+  "README.md",
+  "LICENSE",
+  "NOTICE",
+]

llm_markdownify-0.1.0/src/llm_markdownify/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+__all__ = [
+    "MarkdownifyConfig",
+    "Markdownifier",
+    "convert",
+]
+
+__version__ = "0.1.0"
+
+from .config import MarkdownifyConfig  # noqa: E402
+from .markdownifier import Markdownifier  # noqa: E402
+from .api import convert  # noqa: E402

llm_markdownify-0.1.0/src/llm_markdownify/api.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .config import MarkdownifyConfig
+from .markdownifier import Markdownifier
+
+
+def convert(
+    input_path: str | Path,
+    output_path: str | Path,
+    *,
+    model: Optional[str] = None,
+    dpi: int = 200,
+    max_group_pages: int = 3,
+    enable_grouping: bool = True,
+    temperature: float = 0.2,
+    max_tokens: Optional[int] = None,
+    concurrency: int = 4,
+    profile: Optional[str] = None,
+    allow_docx: bool = False,
+) -> Path:
+    """Convert a document to Markdown using the configured LLM via LiteLLM.
+
+    Parameters
+    - input_path: PDF path (preferred) or DOCX if `allow_docx=True`
+    - output_path: Markdown file destination
+    - model: LiteLLM model name (e.g., 'gpt-4.1-mini', 'azure/<deployment>', 'gemini/gemini-2.5-flash')
+    - dpi: Render DPI for PDF pages (higher = slower, clearer)
+    - max_group_pages: Max pages to merge when a table/chart spans pages
+    - enable_grouping: Whether to use LLM to detect cross-page continuations
+    - temperature: LLM temperature
+    - max_tokens: LLM max tokens; if None, uses config default
+    - concurrency: Max parallel LLM calls across page groups
+    - profile: Prompt profile name ('contracts', 'generic') or path to a JSON profile
+    - allow_docx: Enable DOCX via Word/COM conversion (not recommended; prefer PDFs)
+
+    Returns
+    - Path to the written Markdown file
+    """
+    cfg_kwargs = dict(
+        input_path=Path(input_path),
+        output_path=Path(output_path),
+        dpi=dpi,
+        max_group_pages=max_group_pages,
+        enable_grouping=enable_grouping,
+        temperature=temperature,
+        concurrency=concurrency,
+        allow_docx=allow_docx,
+    )
+    if model is not None:
+        cfg_kwargs["model"] = model
+    if max_tokens is not None:
+        cfg_kwargs["max_tokens"] = max_tokens
+
+    cfg = MarkdownifyConfig(**cfg_kwargs)
+    return Markdownifier(cfg, profile=profile).run()

llm_markdownify-0.1.0/src/llm_markdownify/cli.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from .config import MarkdownifyConfig
+from .markdownifier import Markdownifier
+
+app = typer.Typer(help="Convert documents (PDF) to Markdown using Vision LLMs via LiteLLM.")
+
+
+@app.command()
+def run(
+    input_path: str = typer.Argument(
+        ..., help="Path to input .pdf (preferred) or .docx (discouraged)"
+    ),
+    output: str = typer.Option(..., "-o", "--output", help="Output .md path"),
+    model: Optional[str] = typer.Option(
+        None, help="LiteLLM model, e.g. gpt-4.1-mini, azure/<deployment>, gemini/gemini-2.5-flash"
+    ),
+    dpi: int = typer.Option(
+        72,
+        help="DPI for rendering PDF pages. Higher DPI may improve OCR accuracy if document is blurry.",
+    ),
+    max_group_pages: int = typer.Option(3, help="Max pages to merge for continued content"),
+    grouping: bool = typer.Option(
+        True,
+        "--grouping/--no-grouping",
+        help="Enable LLM-based grouping of continued content",
+    ),
+    temperature: float = typer.Option(
+        0.2, help="LLM temperature. Lower makes OCR results more reliable."
+    ),
+    max_tokens: Optional[int] = typer.Option(
+        None, help="LLM max tokens (defaults to config default). Change based on model limitations"
+    ),
+    concurrency: int = typer.Option(
+        4,
+        help="Max concurrent LLM requests for page groups. Higher concurrency means faster processing at the risk of hitting rate limits.",
+    ),
+    profile: Optional[str] = typer.Option(
+        None, help="Prompt profile name (e.g., 'contracts', 'generic') or path to JSON profile"
+    ),
+    allow_docx: bool = typer.Option(
+        False, help="Allow DOCX via Word/COM conversion (not recommended). Prefer PDFs."
+    ),
+):
+    cfg_kwargs = dict(
+        input_path=Path(input_path),
+        output_path=Path(output),
+        dpi=dpi,
+        max_group_pages=max_group_pages,
+        enable_grouping=grouping,
+        temperature=temperature,
+        concurrency=concurrency,
+        allow_docx=allow_docx,
+    )
+    if model:
+        cfg_kwargs["model"] = model
+    if max_tokens is not None:
+        cfg_kwargs["max_tokens"] = max_tokens
+
+    cfg = MarkdownifyConfig(**cfg_kwargs)
+    Markdownifier(cfg, profile=profile).run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

llm_markdownify-0.1.0/src/llm_markdownify/config.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class MarkdownifyConfig(BaseModel):
+    """Configuration for the markdownification process."""
+
+    input_path: Path = Field(..., description="Path to input PDF/DOCX file")
+    output_path: Path = Field(..., description="Path to output Markdown file")
+
+    dpi: int = Field(72, ge=72, le=600, description="DPI used to render PDF pages")
+    max_group_pages: int = Field(3, ge=1, le=10, description="Max pages to group together")
+    enable_grouping: bool = Field(True, description="Enable LLM-based grouping")
+
+    # Prefer PDFs; DOCX allowed only with explicit opt-in
+    allow_docx: bool = Field(
+        False,
+        description="Allow DOCX via Word/COM conversion (not recommended). Prefer PDFs.",
+    )
+
+    model: str = Field(
+        default_factory=lambda: os.getenv("LLM_MARKDOWNIFY_MODEL", "gpt-4.1-mini"),
+        description="LiteLLM model name (e.g., gpt-4.1-mini, azure/<deployment>, gemini/gemini-2.5-flash)",
+    )
+    temperature: float = Field(0.1, ge=0.0, le=1)
+    max_tokens: int = Field(16000, ge=256, le=128000)
+
+    concurrency: int = Field(
+        4,
+        ge=1,
+        le=1000,
+        description="Max concurrent LLM requests when processing page groups",
+    )
+
+    # Optional path where page images are cached for debugging
+    cache_dir: Optional[Path] = Field(None)
+
+    @field_validator("input_path")
+    @classmethod
+    def _validate_input(cls, path: Path) -> Path:
+        if not path.exists():
+            raise ValueError(f"Input file not found: {path}")
+        if path.suffix.lower() not in {".pdf", ".docx"}:
+            raise ValueError("input_path must be a .pdf or .docx file")
+        return path
+
+    @field_validator("output_path")
+    @classmethod
+    def _validate_output(cls, path: Path) -> Path:
+        parent = path.parent
+        if not parent.exists():
+            parent.mkdir(parents=True, exist_ok=True)
+        if path.suffix.lower() not in {".md", ".markdown"}:
+            raise ValueError("output_path must be a .md or .markdown file")
+        return path
+
+    @model_validator(mode="after")
+    def _enforce_pdf_preference(self) -> "MarkdownifyConfig":
+        if self.input_path.suffix.lower() == ".docx" and not self.allow_docx:
+            raise ValueError(
+                "DOCX input is not enabled. Prefer exporting to PDF, or rerun with --allow-docx (requires Word/COM)."
+            )
+        return self

llm_markdownify-0.1.0/src/llm_markdownify/grouping.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import List
+
+from .llm import assess_continuation
+from .pager import PageImage
+from .logging import get_logger
+from .prompt_profiles import PromptProfile
+
+logger = get_logger("llm_markdownify.grouping")
+
+
+def group_pages(
+    pages: List[PageImage],
+    model: str,
+    max_group_pages: int,
+    enable_grouping: bool,
+    profile: PromptProfile,
+) -> List[List[PageImage]]:
+    if not pages:
+        return []
+
+    if not enable_grouping:
+        return [[p] for p in pages]
+
+    groups: List[List[PageImage]] = []
+    current_group: List[PageImage] = [pages[0]]
+
+    for i in range(len(pages)):
+        if i == len(pages) - 1:
+            groups.append(current_group)
+            break
+        a = pages[i]
+        b = pages[i + 1]
+
+        label = assess_continuation(
+            model=model, first_data_url=a.data_url, second_data_url=b.data_url, profile=profile
+        )
+        logger.info("Continuation assessment for pages %d->%d: %s", a.index + 1, b.index + 1, label)
+
+        continues = label == "CONTINUE_NEXT"
+        if continues and len(current_group) < max_group_pages:
+            current_group.append(b)
+        else:
+            groups.append(current_group)
+            current_group = [b]
+
+    return groups

llm_markdownify-0.1.0/src/llm_markdownify/llm.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import List
+
+import litellm  # type: ignore
+from litellm import completion  # type: ignore
+
+from .prompt_profiles import PromptProfile
+
+# Drop unsupported params for strict models (e.g., gpt-5-mini)
+litellm.drop_params = True  # type: ignore[attr-defined]
+
+
+def _message_with_images(text: str, image_data_urls: List[str]) -> dict:
+    content = [{"type": "text", "text": text}]
+    for url in image_data_urls:
+        content.append({"type": "image_url", "image_url": {"url": url}})
+    return {"role": "user", "content": content}
+
+
+def assess_continuation(
+    model: str,
+    first_data_url: str,
+    second_data_url: str | None,
+    profile: PromptProfile,
+) -> str:
+    images = [first_data_url] + ([second_data_url] if second_data_url else [])
+    messages = [
+        {"role": "system", "content": profile.continuation_system},
+        _message_with_images(profile.continuation_user, images),
+    ]
+    resp = completion(model=model, messages=messages, temperature=0.0, max_tokens=4)
+    return str(resp["choices"][0]["message"]["content"]).strip().upper()
+
+
+def generate_markdown(
+    model: str,
+    image_data_urls: List[str],
+    profile: PromptProfile,
+    temperature: float = 0.2,
+    max_tokens: int = 2000,
+) -> str:
+    messages = [
+        {"role": "system", "content": profile.markdown_system},
+        _message_with_images(profile.markdown_user, image_data_urls),
+    ]
+    resp = completion(
+        model=model, messages=messages, temperature=temperature, max_tokens=max_tokens
+    )
+    return str(resp["choices"][0]["message"]["content"]).strip()

llm_markdownify-0.1.0/src/llm_markdownify/logging.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+import sys
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter(
+        fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.propagate = False
+    return logger

llm_markdownify-0.1.0/src/llm_markdownify/markdownifier.py

@@ -0,0 +1,78 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import List, Tuple
+
+from tqdm import tqdm
+
+from .config import MarkdownifyConfig
+from .grouping import group_pages
+from .llm import generate_markdown
+from .logging import get_logger
+from .pager import PageImage, load_document_pages
+from .prompt_profiles import load_prompt_profile, PromptProfile
+
+logger = get_logger("llm_markdownify.core")
+
+
+class Markdownifier:
+    """Orchestrates the conversion of a document into Markdown using a Vision LLM."""
+
+    def __init__(self, config: MarkdownifyConfig, profile: str | None = None) -> None:
+        self.config = config
+        self.profile: PromptProfile = load_prompt_profile(profile or "contracts")
+
+    def _render_pages(self) -> List[PageImage]:
+        return load_document_pages(
+            self.config.input_path, dpi=self.config.dpi, allow_docx=self.config.allow_docx
+        )
+
+    def _group_pages(self, pages: List[PageImage]) -> List[List[PageImage]]:
+        return group_pages(
+            pages=pages,
+            model=self.config.model,
+            max_group_pages=self.config.max_group_pages,
+            enable_grouping=self.config.enable_grouping,
+            profile=self.profile,
+        )
+
+    def _markdown_for_group(self, group: List[PageImage]) -> str:
+        image_urls = [p.data_url for p in group]
+        return generate_markdown(
+            model=self.config.model,
+            image_data_urls=image_urls,
+            profile=self.profile,
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens,
+        )
+
+    def run(self) -> Path:
+        pages = self._render_pages()
+        groups = self._group_pages(pages)
+
+        logger.info(
+            "Processing %d groups with concurrency=%d", len(groups), self.config.concurrency
+        )
+
+        # Submit LLM work in parallel, but preserve order by collecting (idx, result)
+        results: List[Tuple[int, str]] = []
+        with ThreadPoolExecutor(max_workers=self.config.concurrency) as executor:
+            future_to_idx = {
+                executor.submit(self._markdown_for_group, group): idx
+                for idx, group in enumerate(groups)
+            }
+            for future in tqdm(as_completed(future_to_idx), total=len(groups), desc="LLM groups"):
+                idx = future_to_idx[future]
+                md = future.result()
+                results.append((idx, md))
+
+        ordered = [text for _, text in sorted(results, key=lambda t: t[0])]
+        output = "\n\n".join(ordered).strip() + "\n"
+        self.config.output_path.write_text(output, encoding="utf-8")
+        logger.info("Wrote Markdown to %s", self.config.output_path)
+        return self.config.output_path

llm_markdownify-0.1.0/src/llm_markdownify/pager.py

@@ -0,0 +1,78 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+from typing import Iterable, List
+
+import pypdfium2 as pdfium
+
+from .logging import get_logger
+
+try:
+    from docx2pdf import convert as docx2pdf_convert  # type: ignore
+except Exception:  # pragma: no cover - optional
+    docx2pdf_convert = None  # type: ignore
+
+logger = get_logger("llm_markdownify.pager")
+
+
+@dataclass
+class PageImage:
+    index: int
+    width: int
+    height: int
+    content: bytes  # PNG bytes
+
+    @property
+    def data_url(self) -> str:
+        b64 = base64.b64encode(self.content).decode("ascii")
+        return f"data:image/png;base64,{b64}"
+
+
+def _docx_to_pdf(input_path: Path) -> Path:
+    if docx2pdf_convert is None:
+        raise RuntimeError(
+            "DOCX support requires 'docx2pdf' and platform support for Word/COM. Prefer PDFs."
+        )
+    temp_pdf = input_path.with_suffix(".converted.pdf")
+    logger.info("Converting DOCX to PDF: %s -> %s", input_path, temp_pdf)
+    docx2pdf_convert(str(input_path), str(temp_pdf))
+    return temp_pdf
+
+
+def iter_pdf_pages_as_images(pdf_path: Path, dpi: int) -> Iterable[PageImage]:
+    logger.info("Rendering PDF pages to images at %s DPI", dpi)
+    pdf = pdfium.PdfDocument(str(pdf_path))
+    num_pages = len(pdf)
+    scale = dpi / 72.0
+    for i in range(num_pages):
+        page = pdf[i]
+        bitmap = page.render(scale=scale)
+        pil_image = bitmap.to_pil()
+        with BytesIO() as buf:
+            pil_image.save(buf, format="PNG")
+            data = buf.getvalue()
+        yield PageImage(index=i, width=pil_image.width, height=pil_image.height, content=data)
+
+
+def load_document_pages(input_path: Path, dpi: int, allow_docx: bool = False) -> List[PageImage]:
+    """Load a PDF (preferred) or DOCX (if allowed) as a list of rendered page images."""
+    suffix = input_path.suffix.lower()
+    if suffix == ".docx":
+        if not allow_docx:
+            raise ValueError(
+                "DOCX not allowed. Prefer exporting DOCX to PDF, or enable --allow-docx (requires Word/COM)."
+            )
+        pdf_path = _docx_to_pdf(input_path)
+    else:
+        pdf_path = input_path
+
+    pages = list(iter_pdf_pages_as_images(pdf_path, dpi=dpi))
+    logger.info("Loaded %d pages", len(pages))
+    return pages

llm_markdownify-0.1.0/src/llm_markdownify/prompt_profiles.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict
+
+from . import prompts as default_prompts
+
+
+@dataclass(frozen=True)
+class PromptProfile:
+    name: str
+    continuation_system: str
+    continuation_user: str
+    markdown_system: str
+    markdown_user: str
+
+
+_BUILTIN_PROFILES: Dict[str, PromptProfile] = {
+    "contracts": PromptProfile(
+        name="contracts",
+        continuation_system=default_prompts.CONTINUATION_SYSTEM_PROMPT,
+        continuation_user=default_prompts.CONTINUATION_USER_PROMPT,
+        markdown_system=default_prompts.MARKDOWN_SYSTEM_PROMPT,
+        markdown_user=default_prompts.MARKDOWN_USER_PROMPT,
+    ),
+    "generic": PromptProfile(
+        name="generic",
+        continuation_system=(
+            "You analyze page images to decide if content visually continues (tables/charts split). "
+            "Respond only CONTINUE_NEXT or NONE."
+        ),
+        continuation_user=(
+            "Look for split tables/charts at the end of page A and start of page B. If found, CONTINUE_NEXT; else NONE."
+        ),
+        markdown_system=(
+            "Convert page images into clean Markdown. Use clear headings, lists, and tables; cover all pages; avoid page numbers."
+        ),
+        markdown_user=("Produce a single coherent Markdown output from the provided page images."),
+    ),
+}
+
+
+def load_prompt_profile(name_or_path: str) -> PromptProfile:
+    candidate = Path(name_or_path)
+    if candidate.exists() and candidate.is_file():
+        with candidate.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        required = {
+            "name",
+            "continuation_system",
+            "continuation_user",
+            "markdown_system",
+            "markdown_user",
+        }
+        missing = required - set(data.keys())
+        if missing:
+            raise ValueError(
+                f"Prompt profile missing required fields {sorted(missing)} in {candidate}"
+            )
+        return PromptProfile(
+            name=str(data["name"]),
+            continuation_system=str(data["continuation_system"]),
+            continuation_user=str(data["continuation_user"]),
+            markdown_system=str(data["markdown_system"]),
+            markdown_user=str(data["markdown_user"]),
+        )
+
+    key = name_or_path.strip().lower()
+    if key in _BUILTIN_PROFILES:
+        return _BUILTIN_PROFILES[key]
+
+    raise ValueError(
+        f"Unknown prompt profile '{name_or_path}'. Provide a built-in name ({', '.join(sorted(_BUILTIN_PROFILES))}) "
+        f"or a path to a JSON file with the fields: name, continuation_system, continuation_user, markdown_system, markdown_user."
+    )

llm_markdownify-0.1.0/src/llm_markdownify/prompts.py

@@ -0,0 +1,78 @@
+# Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
+# Licensed under the Apache License, Version 2.0. See LICENSE file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+CONTINUATION_SYSTEM_PROMPT = (
+    "You are a document structure analyst. Given one or two consecutive page images, "
+    "decide if the FIRST page should be MERGED with the NEXT page. \n"
+    "MERGE ONLY IF there is a clear visual continuation across the page boundary of: \n"
+    "- a table (gridlines/cell borders/columns cut at the bottom of page A and resuming at the top of page B), or\n"
+    "- a boxed layout/panel, or\n"
+    "- a chart/figure/diagram clearly split across pages.\n"
+    "Plain text paragraphs DO NOT qualify. Headings and body text continuity alone is NOT a reason to merge.\n"
+    "If uncertain, respond NONE. Respond with ONLY one token: CONTINUE_NEXT or NONE."
+)
+
+CONTINUATION_USER_PROMPT = (
+    "Check for split visual structures at the bottom of page A and the top of page B: \n"
+    "- table gridlines or cell borders continuing,\n"
+    "- boxed panels continuing,\n"
+    "- charts/figures cut between pages.\n"
+    "If you see such a split visual structure, answer CONTINUE_NEXT. Otherwise answer NONE."
+)
+
+MARKDOWN_SYSTEM_PROMPT = (
+    "You are a meticulous technical writer converting page images into clean Markdown. Follow this CHECKLIST strictly.\n"
+    "\n"
+    "1) Table of Contents (TOC) detection:\n"
+    "   - If the page shows a TOC (label like 'CONTENTS' or dense sequential entries like '1 …', '2 …' with dot leaders/page numbers), render it as a simple list.\n"
+    "   - DO NOT promote TOC entries to headings. Schedules in TOC are listed plainly.\n"
+    "\n"
+    "2) Top-level sections ('# '):\n"
+    "   - A top-level section must be a concise, title-like line (typically ≤ 2 lines and a short phrase), not a long sentence.\n"
+    "   - Use '# ' when the line begins with a single integer section number, optionally followed by a dot (e.g., '1', '1.', '12', '12.'), AND the remainder looks like a section name (short phrase, not a long sentence).\n"
+    "   - Examples that SHOULD be headings: '# 2. SCOPE OF ENGAGEMENT', '# 18 ESCROW AGREEMENT'.\n"
+    "   - Output as '# <full original line>' (preserve numeric prefix and casing).\n"
+    "   - Even if an overall title exists (e.g., '# TERMS AND CONDITIONS'), subsequent integer sections still become '# 1 …', '# 2 …', etc.\n"
+    "   - If the content after the number reads like a sentence (e.g., contains verbs such as 'shall', 'agree', 'will', 'must' early on, or clearly reads as a full clause), DO NOT make it a heading; keep it as a numbered line.\n"
+    "\n"
+    "3) Decimal-numbered items (NEVER headings):\n"
+    "   - Items like '1.2', '12.1', '12.1.1' are NOT headings. Keep them as numbered lines under their parent section.\n"
+    "   - If a page/group BEGINS with a decimal-numbered item (e.g., '4.3', '4.2.3'), treat it as CONTINUATION from a previous section; DO NOT fabricate '# 4'.\n"
+    "   - Uppercase/bold/visual prominence does NOT change this rule. Decimal-numbered items must never become headings.\n"
+    "\n"
+    "4) Subheadings ('## '):\n"
+    "   - Use '## ' ONLY for true subheadings that are NOT decimal-numbered list points (e.g., '## Warranty' under '# 3. Charges').\n"
+    "   - Do not convert ordinary numbered paragraphs/lists into headings.\n"
+    "\n"
+    "5) Tables, charts, and images:\n"
+    "   - Tables: render as valid GitHub-Flavored Markdown tables with proper alignment.\n"
+    "   - Charts/diagrams: use Mermaid when feasible.\n"
+    "   - Images/figures: include concise alt-text/captions. Dont try to provide a link to the image. You are just going to tell what the image is about in excruciating detail.\n"
+    "\n"
+    "6) Structure & hygiene:\n"
+    "   - Cover ALL provided page images in order; do not omit later pages.\n"
+    "   - Keep content readable; do not include page numbers or scanning artifacts.\n"
+    "\n"
+    "7) Output constraints (critical):\n"
+    "   - Output ONLY the document content. DO NOT add any meta commentary, assurances, disclaimers, or notes (e.g., 'Note: Decimal-numbered items …', 'According to the images …', 'Summary of changes …').\n"
+    "   - Do NOT include this checklist, instructions, or any explanation of your process.\n"
+    "   - Do NOT add content that is not visibly present in the document.\n"
+    "\n"
+    "Examples (Do/Don't):\n"
+    "- Do: '# TERMS AND CONDITIONS' then '# 1. DEFINITIONS AND INTERPRETATION' then lines '1.1 …', '1.2 …'.\n"
+    "- Do: '# 2. SCOPE OF ENGAGEMENT' and '# 12 ESCROW AGREEMENT' (short, title-like).\n"
+    "- Do: At page start with '4.3 …', keep it as a numbered line (continuation), DO NOT add '# 4'.\n"
+    "- Do: TOC as a list of entries (no '#').\n"
+    "- Don't: '# 1.2 …' or '## 12.1 …' or '# 12.4 …'.\n"
+    "- Don't: '# 5 The Parties shall co-operate …' (this is a long, sentence-like numbered paragraph; keep as a numbered line).\n"
+    "- Don't: Any 'Note:'/'Disclaimer:' or statements about your output or method.\n"
+)
+
+MARKDOWN_USER_PROMPT = (
+    "Convert the provided page images into a single coherent Markdown segment. \n"
+    "Apply the checklist strictly: '# ' only for concise, title-like integer-numbered sections ('1'/'1.', '12'/'12.'); decimal-numbered items never become headings (even if bold/uppercase/first line); if the text after an integer number reads as a long sentence, keep it as a numbered line; TOC entries are lists; '## ' reserved only for true non-numbered subheadings. \n"
+    "Return ONLY the document content in Markdown with no notes, disclaimers, or extra commentary."
+)