refactor: The project was comprehensively refactored, with litellm introduced as the LLM client library, and input/output parameters were optimized.

Author: jorben

.env.sample

@@ -1,4 +1,55 @@
-OPENAI_API_KEY="sk-xxxxxx"
-OPENAI_API_BASE="https://api.openai.com/v1/"
-OPENAI_DEFAULT_MODEL="gpt-4o"
-OPENAI_REASONING_EFFORT="" # 'high' | 'medium' | 'low' | 'minimal' 
+# MarkPDFDown Configuration Template
+# Copy this file to .env and configure your settings
+
+# =============================================================================
+# Model Configuration
+# =============================================================================
+
+# Model name - LiteLLM will automatically route to the correct provider
+# Examples:
+#   OpenAI models: gpt-4o, gpt-4o-mini, gpt-4-vision-preview
+#   OpenRouter models: openrouter/anthropic/claude-3.5-sonnet, openrouter/google/gemini-pro-vision
+#   OpenAI-Compatible models: openai/hunyuan-turbo-vision, openai/doubao-1-5-vision-pro-32k-250115
+MODEL_NAME=gpt-4o
+
+# =============================================================================
+# API Keys (LiteLLM automatically detects these environment variables)
+# =============================================================================
+
+# OpenAI API Key (for OpenAI models)
+# OPENAI_API_KEY=your-openai-api-key-here
+# OPENAI_API_BASE=https://api.openai.com/v1  # [OPTIONAL]
+
+# OpenRouter API Key (for OpenRouter models)
+# OPENROUTER_API_KEY=your-openrouter-api-key-here
+# OPENROUTER_API_BASE=https://openrouter.ai/api/v1/  # [OPTIONAL]
+
+# =============================================================================
+# Generation Parameters (Optional)
+# =============================================================================
+
+# Temperature for text generation (0.0 to 2.0)
+TEMPERATURE=0.3
+
+# Maximum number of tokens for generated text
+MAX_TOKENS=8192
+
+# Number of retries for failed API calls
+RETRY_TIMES=3
+
+# =============================================================================
+# Usage Examples
+# =============================================================================
+
+# For OpenAI GPT-4o:
+# MODEL_NAME=gpt-4o
+# OPENAI_API_KEY=sk-...
+
+# For OpenRouter Claude 4 Sonnet:
+# MODEL_NAME=openrouter/anthropic/claude-sonnet-4
+# OPENROUTER_API_KEY=sk-or-v1-...
+
+# For Doubao 1.5 Vision Pro:
+# MODEL_NAME=openai/doubao-1-5-vision-pro-32k-250115
+# OPENAI_API_KEY=sk-...
+# OPENAI_API_BASE=https://ark.cn-beijing.volces.com/api/v3/

Dockerfile

@@ -1,5 +1,29 @@
-from python:3.9-slim
+FROM python:3.9-slim
+
+# Set working directory
 WORKDIR /app
-COPY . /app
-RUN pip install -e .
-CMD ["python", "main.py"]
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for faster package management
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.cargo/bin:$PATH"
+
+# Copy project files
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+COPY .env.sample ./
+
+# Install dependencies and the package
+RUN uv sync --frozen
+RUN uv pip install -e .
+
+# Set environment variables
+ENV PYTHONPATH=/app/src
+ENV PYTHONUNBUFFERED=1
+
+# Use markpdfdown as the entry point
+ENTRYPOINT ["markpdfdown"]

README.md

@@ -15,15 +15,17 @@
 
 ## Overview
 
-MarkPDFDown is designed to simplify the process of converting PDF documents into clean, editable Markdown text. By utilizing advanced multimodal AI models, it can accurately extract text, preserve formatting, and handle complex document structures including tables, formulas, and diagrams.
+MarkPDFDown is designed to simplify the process of converting PDF documents into clean, editable Markdown text. By utilizing advanced multimodal AI models through LiteLLM, it can accurately extract text, preserve formatting, and handle complex document structures including tables, formulas, and diagrams.
 
 ## Features
 
 - **PDF to Markdown Conversion**: Transform any PDF document into well-formatted Markdown
 - **Image to Markdown Conversion**: Transform image into well-formatted Markdown
-- **Multimodal Understanding**: Leverages AI to comprehend document structure and content
+- **Multi-Provider Support**: Supports OpenAI and OpenRouter through LiteLLM
+- **Flexible CLI**: Both file-based and pipe-based usage modes
 - **Format Preservation**: Maintains headings, lists, tables, and other formatting elements
-- **Customizable Model**: Configure the model to suit your needs
+- **Page Range Selection**: Convert specific page ranges from PDF documents
+- **Modular Architecture**: Clean, maintainable codebase with separation of concerns
 
 ## Demo
 ![](https://raw.githubusercontent.com/markpdfdown/markpdfdown/refs/heads/master/tests/demo_02.png)
@@ -43,6 +45,8 @@ cd markpdfdown
 # Install dependencies and create virtual environment
 uv sync
 
+# Install the package in development mode
+uv pip install -e .
 ```
 
 ### Using conda
@@ -58,29 +62,106 @@ cd markpdfdown
 # Install dependencies
 pip install -e .
 ```
+
+## Configuration
+
+MarkPDFDown uses environment variables for configuration. Create a `.env` file in your project directory:
+
+```bash
+# Copy the sample configuration
+cp .env.sample .env
+```
+
+Edit the `.env` file with your settings:
+
+```bash
+# Model Configuration
+MODEL_NAME=gpt-4o
+
+# API Keys (LiteLLM automatically detects these)
+OPENAI_API_KEY=your-openai-api-key
+# or for OpenRouter
+OPENROUTER_API_KEY=your-openrouter-api-key
+
+# Optional Parameters
+TEMPERATURE=0.3
+MAX_TOKENS=8192
+RETRY_TIMES=3
+```
+
+### Supported Models
+
+#### OpenAI Models
+```bash
+MODEL_NAME=gpt-4o
+MODEL_NAME=gpt-4o-mini
+MODEL_NAME=gpt-4-vision-preview
+```
+
+#### OpenRouter Models
+```bash
+MODEL_NAME=openrouter/anthropic/claude-3.5-sonnet
+MODEL_NAME=openrouter/google/gemini-pro-vision
+MODEL_NAME=openrouter/meta-llama/llama-3.2-90b-vision
+```
+
 ## Usage
+
+### File Mode (Recommended)
+
 ```bash
-# Set up your OpenAI API key
-export OPENAI_API_KEY="your-api-key"
-# Optionally, set up your OpenAI API base
-export OPENAI_API_BASE="your-api-base"
-# Optionally, set up your OpenAI API model
-export OPENAI_DEFAULT_MODEL="your-model"
-
-# pdf to markdown
-python main.py < tests/input.pdf > output.md
-
-# image to markdown
-python main.py < input_image.png > output.md
+# Basic conversion
+markpdfdown --input document.pdf --output output.md
+
+# Convert specific page range
+markpdfdown --input document.pdf --output output.md --start 1 --end 10
+
+# Convert image to markdown
+markpdfdown --input image.png --output output.md
+
+# Using python module
+python -m markpdfdown --input document.pdf --output output.md
+```
+
+### Pipe Mode (Docker-friendly)
+
+```bash
+# PDF to markdown via pipe
+markpdfdown < document.pdf > output.md
+
+# Using python module
+python -m markpdfdown < document.pdf > output.md
 ```
-## Advanced Usage
+
+### Advanced Usage
+
 ```bash
-python main.py page_start page_end < tests/input.pdf > output.md
+# Convert pages 5-15 of a PDF
+markpdfdown --input large_document.pdf --output chapter.md --start 5 --end 15
+
+# Process multiple files
+for file in *.pdf; do
+    markpdfdown --input "$file" --output "${file%.pdf}.md"
+done
 ```
 
 ## Docker Usage
+
 ```bash
-docker run -i -e OPENAI_API_KEY=your-api-key -e OPENAI_API_BASE=your-api-base -e OPENAI_DEFAULT_MODEL=your-model jorbenzhu/markpdfdown < input.pdf > output.md
+# Build the image (if needed)
+docker build -t markpdfdown .
+
+# Run with environment variables
+docker run -i \
+  -e MODEL_NAME=gpt-4o \
+  -e OPENAI_API_KEY=your-api-key \
+  markpdfdown < input.pdf > output.md
+
+# Using OpenRouter
+docker run -i \
+  -e MODEL_NAME=openrouter/anthropic/claude-3.5-sonnet \
+  -e OPENROUTER_API_KEY=your-openrouter-key \
+  markpdfdown < input.pdf > output.md
 ```
 
 ## Development Setup
@@ -126,7 +207,24 @@ ruff check --fix
 - Python 3.9+
 - [uv](https://astral.sh/uv/) (recommended for package management) or conda/pip
 - Dependencies specified in `pyproject.toml`
-- Access to the specified multimodal AI model
+- Access to supported LLM providers (OpenAI or OpenRouter)
+
+## Architecture
+
+The project follows a modular architecture:
+
+```
+src/markpdfdown/
+├── __init__.py          # Package initialization
+├── __main__.py          # Entry point for python -m
+├── cli.py               # Command line interface
+├── main.py              # Core conversion logic
+├── config.py            # Configuration management
+└── core/                # Core modules
+    ├── llm_client.py    # LiteLLM integration
+    ├── file_worker.py   # File processing
+    └── utils.py         # Utility functions
+```
 
 ## Contributing
 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -150,10 +248,26 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 Please ensure your code follows the project's coding standards by running the linting and formatting tools before submitting.
 
+## Changelog
+
+### v0.2.0 (Latest)
+- **Breaking Changes**: Complete architecture refactor
+- **New**: LiteLLM integration for multi-provider support
+- **New**: Unified CLI with `--input`/`--output` parameters
+- **New**: Support for `python -m markpdfdown` execution
+- **New**: Environment-based configuration with `.env` support
+- **New**: OpenRouter support alongside OpenAI
+- **Improved**: Modular codebase with better separation of concerns
+- **Improved**: Enhanced error handling and logging
+
+### v0.1.0
+- Initial release with basic PDF to Markdown conversion
+
 ## License
 This project is licensed under the Apache License 2.0. See the LICENSE file for details.
 
 ## Acknowledgments
+- Thanks to the developers of LiteLLM for providing unified LLM access
 - Thanks to the developers of the multimodal AI models that power this tool
 - Inspired by the need for better PDF to Markdown conversion tools
 
@@ -164,4 +278,4 @@ This project is licensed under the Apache License 2.0. See the LICENSE file for
 [Size]: https://img.shields.io/docker/image-size/jorbenzhu/markpdfdown/latest?color=066da5&label=size
 [Pulls]: https://img.shields.io/docker/pulls/jorbenzhu/markpdfdown.svg?style=flat&label=pulls&logo=docker
 [Tag]: https://img.shields.io/github/release/markpdfdown/markpdfdown.svg
-[License]: https://img.shields.io/github/license/markpdfdown/markpdfdown
+[License]: https://img.shields.io/github/license/markpdfdown/markpdfdown