markdrop
Professional AI skill and usage instructions for the Markdrop package, a Python tool for converting PDFs to Markdown/HTML with AI-powered image/table descriptions.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/shoryasethia--markdrop)HTML
<a href="/listings/shoryasethia--markdrop"><img src="/api/listings/shoryasethia--markdrop/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Core install (PDF conversion + Gemini/OpenAI):**
pip install markdrop
**With Anthropic Claude:**
pip install "markdrop[anthropic]"
**With Groq:**
pip install "markdrop[groq]"
**With LiteLLM (routes to 100+ providers):**
pip install "markdrop[litellm]"
**Everything (including local HuggingFace models):**
pip install "markdrop[all]"
**Faster CPU / lightweight Markdown (`--fast` mode):**
pip install "markdrop[lite]" markdrop convert report.pdf --output_dir out --fast
See [docs/cpu-guide.md](docs/cpu-guide.md) for CPU-only and Colab guidance.
> **OpenRouter** is accessed through the `openai` package (already included in core), so no extra install is needed.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 136 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: markdrop
- description: Professional AI skill and usage instructions for the Markdrop package, a Python tool for converting PDFs to Markdown/HTML with AI-powered image/table descriptions.
- ---
- # Markdrop Skill
- Welcome to the `markdrop` skill. `markdrop` is a powerful Python package and CLI tool used to convert PDF documents into structured Markdown and interactive HTML, while natively leveraging AI vision models to interpret and describe extracted images and tables.
- If you are an AI agent or a user aiming to process PDFs and augment them with text or image descriptions, this document serves as your complete guide on utilizing `markdrop` efficiently and accurately.
- ## 1. Capabilities
- - **PDF to Markdown/HTML**: Retains formatting, extracts images, and detects tables via Microsoft Table Transformer and Docling. Supports processing both local file paths and direct PDF URLs.
- - **AI Vision Descriptions**: Query GEMINI, OPENAI, ANTHROPIC, GROQ, OPENROUTER, or LITELLM to generate rich descriptions of images and tables.
- - **Batch Processing**: Describe entire directories of images in single commands using multiple LLM backends simultaneously.
- - **Extensible Configuration**: Precise override control over which structural text-models vs vision-models are used, as well as prompts, resolution scales, and output features.
- ## 2. API Keys Setup
- Before using AI features, API keys must be available in the root `.env` file or environment variables.
- If deploying programmatically, you can run the built-in CLI command, or inject them into `os.environ`:
- ```bash
- markdrop setup gemini # -> GEMINI_API_KEY
- markdrop setup openai # -> OPENAI_API_KEY
- markdrop setup anthropic # -> ANTHROPIC_API_KEY
- markdrop setup groq # -> GROQ_API_KEY
- markdrop setup openrouter # -> OPENROUTER_API_KEY
- markdrop setup litellm # -> LITELLM_API_KEY
- ```
- ## 3. Python API Integration
- The Python API is the recommended way to embed `markdrop` into applications.
- ### 3.1 PDF Conversion to Interactive HTML
- Use `markdrop` function combined with `add_downloadable_tables`:
- ```python
- from markdrop import markdrop, MarkDropConfig, add_downloadable_tables
- from pathlib import Path
- import logging
- # Configuration block
- config = MarkDropConfig(
- image_resolution_scale=2.0,
- download_button_color="#444444",
- log_level=logging.INFO,
- log_dir="logs",
- excel_dir="markdrop-excel-tables",
- )
- # 1. Convert PDF to base HTML (and markdown locally). URL supported here too: "https://url.to/pdf"
- html_path = markdrop("path/to/document.pdf", "output_directory", config)
- # 2. Enrich HTML to allow downloading tables as Excel sheets
- enhanced_html_path = add_downloadable_tables(html_path, config)
- ```
- ### 3.2 Injecting AI Descriptions into Markdown
- If you have a Markdown file containing image/table links, `process_markdown` automatically routes vision requests to the chosen provider and inserts contextual descriptions.
- ```python
- from markdrop import process_markdown, ProcessorConfig, AIProvider
- config = ProcessorConfig(
- input_path="output_directory/document.md",
- output_dir="output_directory",
- ai_provider=AIProvider.GEMINI, # Available: GEMINI, OPENAI, ANTHROPIC, GROQ, OPENROUTER, LITELLM
- # Target configurations
- remove_images=False,
- remove_tables=False,
- table_descriptions=True,
- image_descriptions=True,
- # Provider-Specific overrides (Optional)
- # Allows granular decoupling of vision parsing vs table text-parsing
- model_name_override="gemini-2.0-flash", # Primary vision analysis model
- text_model_name_override="gemini-2.0-flash", # Lean text-only model for generic parsing
- )
- # Executes AI processing and saves the enriched document
- output_path = process_markdown(config)
- ```
- ### 3.3 Batch Image Description
- For standalone image directories or files:
- ```python
- from markdrop import generate_descriptions
- generate_descriptions(
- input_path="images_folder/",
- output_dir="descriptions_output/",
- prompt="Analyze this image and describe all textual and structural elements.",
- llm_client=["gemini", "openai"],
- )
- ```
- ## 4. CLI Execution Best Practices
- As an agent, you can also trigger `markdrop` workflows via Bash.
- 1. **Convert PDF to MD/HTML (including tables)**:
- ```bash
- markdrop convert <input_path_or_url> --output_dir <dir> --add_tables
- ```
- 2. **Run AI Provider over the Markdown Output with exact models**:
- ```bash
- markdrop describe <markdown_file> \
- --ai_provider anthropic \
- --model claude-opus-4-6 \
- --text-model claude-sonnet-4-5 \
- --remove_images
- ```
- 3. **Only Analyze / Extract Images**:
- ```bash
- # Also accepts URLs directly
- markdrop analyze https://domain.com/report.pdf --output_dir pdf_analysis --save_images
- ```
- 4. **Batch Image Description**:
- ```bash
- markdrop generate images/ --output_dir descriptions/ \
- --prompt "Describe in detail." \
- --llm_client gemini openai
- ```
- ## 5. Typical Model Fallbacks & Suggestions
- - **Default / Cost-Effective**: `gemini` (Gemini 2.0 Flash) is frequently the fastest and cheapest for large scale document evaluation.
- - **High Complexity / Intricate Tables**: `anthropic` with the latest Claude models (`claude-opus-4-6` or `claude-sonnet-4-5`) excel in reasoning and formatting.
- - **Maximum Speed**: `groq` using LLaMA models.
- Whenever instantiating `ProcessorConfig`, be exact about paths—use absolute paths if the current working directory is dynamically changing.
README.md · README · 361 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="left">
- <img src="https://raw.githubusercontent.com/shoryasethia/markdrop/main/markdrop/src/markdrop-logo.png" alt="Markdrop Logo" width="200" height="200"/>
- <h1 style="display: inline; font-size: 2em; vertical-align: middle; padding-left: 10px; margin: 0;">Markdrop</h1>
- </p>
- [](https://pepy.tech/projects/markdrop)
- [](https://pypi.org/project/markdrop/)
- [](https://github.com/shoryasethia/markdrop/blob/main/LICENSE)
- [](https://github.com/shoryasethia/markdrop/stargazers)
- [](https://github.com/shoryasethia/markdrop/issues)
- [](https://github.com/shoryasethia/markdrop/network/members)
- A Python package for converting PDFs to structured Markdown and interactive HTML, with AI-powered image and table descriptions across **six major LLM providers**. Available on PyPI.
- ---
- ## Features
- - [x] PDF → Markdown conversion with formatting preservation (via Docling)
- - [x] Automatic image extraction using XRef IDs
- - [x] Table detection using Microsoft's Table Transformer
- - [x] PDF URL support
- - [x] AI-powered image and table descriptions — **6 providers**: Gemini, OpenAI, Anthropic Claude, Groq, OpenRouter, LiteLLM
- - [x] Interactive HTML output with downloadable Excel tables
- - [x] Customisable image resolution and UI elements
- - [x] Structured logging (never pollutes your app's root logger)
- ---
- ## Installation
- **Core install (PDF conversion + Gemini/OpenAI):**
- ```bash
- pip install markdrop
- ```
- **With Anthropic Claude:**
- ```bash
- pip install "markdrop[anthropic]"
- ```
- **With Groq:**
- ```bash
- pip install "markdrop[groq]"
- ```
- **With LiteLLM (routes to 100+ providers):**
- ```bash
- pip install "markdrop[litellm]"
- ```
- **Everything (including local HuggingFace models):**
- ```bash
- pip install "markdrop[all]"
- ```
- **Faster CPU / lightweight Markdown (`--fast` mode):**
- ```bash
- pip install "markdrop[lite]"
- markdrop convert report.pdf --output_dir out --fast
- ```
- See [docs/cpu-guide.md](docs/cpu-guide.md) for CPU-only and Colab guidance.
- > **OpenRouter** is accessed through the `openai` package (already included in core), so no extra install is needed.
- ---
- ## Supported AI Providers
- | Provider | `--ai_provider` | Default vision model | Default text model (tables) | Vision |
- |---|---|---|---|---|
- | Google Gemini | `gemini` | `gemini-3.1-flash-lite` | `gemini-3.1-flash-lite` | ✅ |
- | OpenAI | `openai` | `gpt-5.6-terra` | `gpt-5.6-luna` | ✅ |
- | Anthropic Claude | `anthropic` | `claude-opus-5` | `claude-sonnet-5` | ✅ |
- | Groq | `groq` | `meta-llama/llama-4-maverick-17b-128e-instruct` | `meta-llama/llama-4-scout-17b-16e-instruct` | ✅ |
- | OpenRouter | `openrouter` | `google/gemini-3.1-flash-lite` | `anthropic/claude-sonnet-5` | ✅ |
- | LiteLLM | `litellm` | `openai/gpt-5.6-terra` | `openai/gpt-5.6-luna` | ✅ |
- > All models are configurable — use `--model` to override for any provider, or set `model_name_override` in `ProcessorConfig`.
- ---
- ## Quick Start
- See [examples/quickstart.md](examples/quickstart.md) for copy-paste commands.
- [](https://colab.research.google.com/drive/1oApTrP_kjNn0s1tpE0SIWRyGzYfflQsi?usp=sharing)
- [](https://youtu.be/2xg7W0-oiw0)
- ---
- ## CLI Usage
- Check the installed version:
- ```bash
- markdrop --version
- ```
- ### 1. Convert PDF → Markdown + HTML
- ```bash
- markdrop convert <input_path> --output_dir <dir> [--add_tables] [--fast]
- ```
- ```bash
- # Example
- markdrop convert report.pdf --output_dir out --add_tables
- # Outputs: out/report-markdroped.md and out/report-markdroped.html
- # Also works with URLs (SSRF-protected download):
- markdrop convert https://arxiv.org/pdf/1706.03762 --output_dir out
- ```
- ### 2. Generate AI Descriptions for Images & Tables
- ```bash
- markdrop describe <markdown_file> --ai_provider <provider> [--output_dir <dir>] [--remove_images] [--remove_tables]
- ```
- | Provider | `--ai_provider` |
- |---|---|
- | Google Gemini | `gemini` |
- | OpenAI | `openai` |
- | Anthropic Claude | `anthropic` |
- | Groq | `groq` |
- | OpenRouter | `openrouter` |
- | LiteLLM | `litellm` |
- ```bash
- # Gemini (default)
- markdrop describe doc.md --ai_provider gemini
- # Anthropic Claude
- markdrop describe doc.md --ai_provider anthropic --remove_images
- # Groq (fastest inference)
- markdrop describe doc.md --ai_provider groq
- # OpenRouter (any model)
- markdrop describe doc.md --ai_provider openrouter
- # LiteLLM (unified gateway)
- markdrop describe doc.md --ai_provider litellm
- ```
- ### 3. Set Up API Keys
- ```bash
- markdrop setup <provider>
- ```
- Keys are stored in your user config directory (via `platformdirs`, with a fallback to `~/.config/markdrop/`):
- - **Linux/macOS:** `~/.config/markdrop/.env` (or `$XDG_CONFIG_HOME/markdrop/.env`)
- - **Windows:** `%LOCALAPPDATA%\markdrop\.env`
- On POSIX systems, the `.env` file is written with `0o600` permissions.
- ```bash
- markdrop setup gemini # → GEMINI_API_KEY (GOOGLE_API_KEY also accepted)
- markdrop setup openai # → OPENAI_API_KEY
- markdrop setup anthropic # → ANTHROPIC_API_KEY
- markdrop setup groq # → GROQ_API_KEY
- markdrop setup openrouter # → OPENROUTER_API_KEY
- markdrop setup litellm # → LITELLM_API_KEY
- ```
- ### 4. Analyze Images in a PDF
- ```bash
- markdrop analyze report.pdf --output_dir pdf_analysis --save_images
- ```
- ### 5. Batch Image Description Generation
- ```bash
- markdrop generate images/ --output_dir descriptions/ --prompt "Describe in detail." \
- --llm_client gemini openai
- ```
- Available `--llm_client` values: `qwen`, `gemini`, `openai`, `llama-vision`, `molmo`, `pixtral`
- ---
- ## Python API
- ### PDF Conversion
- ```python
- from markdrop import markdrop, MarkDropConfig, add_downloadable_tables
- from pathlib import Path
- import logging
- config = MarkDropConfig(
- image_resolution_scale=2.0,
- download_button_color="#444444",
- log_level=logging.INFO,
- log_dir="logs",
- excel_dir="markdrop-excel-tables",
- )
- html_path = markdrop("path/to/input.pdf", "output", config)
- downloadable_html = add_downloadable_tables(html_path, config)
- ```
- ### AI Descriptions
- ```python
- import asyncio
- from markdrop import process_markdown, ProcessorConfig, AIProvider, setup_keys
- # One-time key setup (writes to user config ~/.config/markdrop/.env)
- setup_keys("anthropic")
- config = ProcessorConfig(
- input_path="out/report-markdroped.md",
- output_dir="output",
- ai_provider=AIProvider.ANTHROPIC, # GEMINI | OPENAI | ANTHROPIC | GROQ | OPENROUTER | LITELLM
- remove_images=False,
- remove_tables=False,
- table_descriptions=True,
- image_descriptions=True,
- max_retries=3,
- retry_delay=2,
- # Override default models (all providers have matching config fields):
- anthropic_model_name="claude-opus-5",
- anthropic_text_model_name="claude-sonnet-5",
- )
- output_path = asyncio.run(process_markdown(config))
- ```
- #### Using OpenRouter to access any model
- ```python
- config = ProcessorConfig(
- input_path="doc.md",
- output_dir="output",
- ai_provider=AIProvider.OPENROUTER,
- openrouter_model_name="meta-llama/llama-4-scout", # any model on openrouter.ai/models
- openrouter_text_model_name="anthropic/claude-sonnet-5",
- openrouter_site_url="https://yoursite.com",
- openrouter_site_name="My App",
- )
- ```
- #### Using LiteLLM for any 100+ provider
- ```python
- import os
- os.environ["ANTHROPIC_API_KEY"] = "..." # set any provider's key
- config = ProcessorConfig(
- input_path="doc.md",
- output_dir="output",
- ai_provider=AIProvider.LITELLM,
- litellm_model_name="anthropic/claude-opus-5",
- litellm_text_model_name="openai/gpt-5.6-luna",
- )
- ```
- ### Batch Image Description Generation
- ```python
- from markdrop import generate_descriptions
- generate_descriptions(
- input_path="images/",
- output_dir="output/",
- prompt="Give a highly detailed description of this image.",
- llm_client=["gemini", "llama-vision"],
- )
- ```
- ---
- ## API Reference
- ### `ProcessorConfig` – AI Provider Fields
- | Field | Default | Notes |
- |---|---|---|
- | `gemini_model_name` | `gemini-3.1-flash-lite` | Vision model |
- | `gemini_text_model_name` | `gemini-3.1-flash-lite` | Text model |
- | `openai_model_name` | `gpt-5.6-terra` | Vision |
- | `openai_text_model_name` | `gpt-5.6-luna` | Tables / text |
- | `anthropic_model_name` | `claude-opus-5` | Vision |
- | `anthropic_text_model_name` | `claude-sonnet-5` | Text (cheaper) |
- | `groq_model_name` | `meta-llama/llama-4-maverick-17b-128e-instruct` | Vision |
- | `groq_text_model_name` | `meta-llama/llama-4-scout-17b-16e-instruct` | Text |
- | `openrouter_model_name` | `google/gemini-3.1-flash-lite` | Any model string from openrouter.ai/models |
- | `openrouter_text_model_name` | `anthropic/claude-sonnet-5` | |
- | `litellm_model_name` | `openai/gpt-5.6-terra` | `provider/model` format |
- | `litellm_text_model_name` | `openai/gpt-5.6-luna` | |
- ### `MarkDropConfig`
- | Field | Default | Notes |
- |---|---|---|
- | `image_resolution_scale` | `2.0` | Scale factor for extracted images |
- | `download_button_color` | `'#444444'` | HTML button colour |
- | `log_level` | `logging.INFO` | |
- | `log_dir` | `'logs'` | |
- | `excel_dir` | `'markdrop_excel_tables'` | |
- ---
- ## Contributing
- We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md). Please read our [Code of Conduct](CODE_OF_CONDUCT.md).
- ```bash
- git clone https://github.com/shoryasethia/markdrop.git
- cd markdrop
- python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate
- pip install -e .
- ```
- ---
- ## Project Structure
- ```
- markdrop/
- ├── setup.py
- ├── requirements.txt
- ├── README.md
- └── markdrop/
- ├── __init__.py
- ├── main.py ← CLI entry-point
- ├── process.py ← PDF conversion
- ├── parse.py ← AI description engine (all 6 providers)
- ├── helper.py ← PDF image analysis
- ├── utils.py ← PDF download helpers
- ├── setup_keys.py ← Interactive API key manager
- ├── ignore_warnings.py
- ├── src/
- │ └── markdrop-logo.png
- └── models/
- ├── img_descriptions.py
- ├── model_loader.py ← Local HF model loader
- ├── responder.py
- └── logger.py
- ```
- ---
- ## License
- GPL-3.0 — see [LICENSE](LICENSE).
- ## Changelog
- See [CHANGELOG.md](CHANGELOG.md).
- ## Support
- - [Open an issue](https://github.com/shoryasethia/markdrop/issues)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.