$ pip install "structmd[pdf]"   # uv: uv add "structmd[pdf]"

$ git clone https://github.com/umar052001/structmd.git
$ cd structmd
$ uv sync --extra all --extra dev
$ uv run pytest

$ ollama pull qwen2-vl:2b       # ~1.6 GB, good default
$ ollama pull smolvlm           # small & fast on CPUs

$ ollama signin                # one-time account link
$ ollama pull gemma4:cloud     # registers the remote model locally
$ structmd paper.pdf -o paper.md --model gemma4:cloud

$ structmd report.pdf -o report.md --json report.json

Extracting 12 pages ━━━━━━━━━━━━ 100%
✓ wrote report.md

from pathlib import Path

from structmd import StructMDPipeline
from structmd.config import StructMDConfig

# 1. Configure once — these settings apply to every document.
config = StructMDConfig(
    ollama_model="gemma4:cloud",   # or a local tag, e.g. "qwen2-vl:2b"
    ollama_max_workers=3,          # pages processed concurrently
    save_assets=True,              # crop figures out as PNGs
)

# 2. Collect inputs. rglob walks subfolders; glob is top-level only.
pdfs = sorted(Path("papers").rglob("*.pdf"))
print(f"Found {len(pdfs)} PDFs")

# 3. Run. All pages of all documents share one async worker pool,
#    and finished pages are cached individually.
with StructMDPipeline(config) as pipeline:
    documents = pipeline.process_batch(
        [str(p) for p in pdfs],
        output_dir="markdown",     # anchors figure assets at markdown/figures/
    )

# 4. Write the Markdown files.
for doc in documents:
    stem = Path(doc.metadata["source_path"]).stem
    target = Path("markdown") / f"{stem}.md"
    doc.save(str(target))
    print(f"{target}  ({doc.metadata['page_count']} pages)")

$ structmd batch ./papers/ -o markdown/ --save-assets

from structmd import StructMDPipeline, StructMDConfig

config = StructMDConfig(
    ollama_model="qwen2-vl:2b",          # any Ollama vision tag
    ollama_url="http://localhost:11434",  # default
)

with StructMDPipeline(config) as pipeline:
    result = pipeline.process(
        "report.pdf",
        output_json="report.json",   # optional: keep Stage 1 output
        output_md="report.md",       # optional: write final Markdown
    )
    print(result.title)                      # from the first heading
    print(result.content[:200])              # the Markdown itself
    print(result.metadata["page_count"])     # 12

from structmd import StructMDPipeline

with StructMDPipeline() as pipeline:
    # Stage 1 only: the VLM runs here (slow, cached afterwards)
    doc = pipeline.extract_only("report.pdf", output_json="report.json")

    # ... inspect / hand-edit report.json ...
    # e.g. fix a heading level, correct a table cell, drop a stray footer.

    # Stage 2 only: deterministic rebuild (instant, no VLM)
    md = pipeline.build_from_json("report.json", output_md="report.md")

$ structmd report.pdf --json report.json -o report.md   # full run
$ vim report.json                                       # fix the JSON
$ structmd --from-json report.json -o report.md         # instant rebuild

![Diagram of the Vision Transformer architecture](figures/2010.11929_p03_1.png)

from structmd import attach_assets

written = attach_assets("paper.pdf", extracted_document, "output/report.md", dpi=200)
# -> writes output/figures/*.png, returns the relative paths,
#    and annotates each image element with metadata["asset_path"]

$ structmd big.pdf -o big.md            # slow first run
$ structmd big.pdf -o big.md            # seconds — served from cache
$ structmd big.pdf -o big.md --force    # bypass reads, refresh entries
$ structmd big.pdf -o big.md --no-cache # ignore the cache entirely

$ structmd batch ./contracts/ -o ./markdown/ --workers 4 --pages 1

import asyncio
from pathlib import Path
from structmd import StructMDPipeline

async def main():
    with StructMDPipeline() as pipeline:
        docs = await pipeline.process_batch_async(
            [str(p) for p in Path("papers").glob("*.pdf")]
        )
        for d in docs:
            print(d.metadata["source_path"], d.metadata["page_count"], "pages")

asyncio.run(main())

import asyncio
from structmd import BatchProcessor, OllamaExtractor
from structmd.config import StructMDConfig

config = StructMDConfig(ollama_model="gemma4:cloud")

def on_doc(doc_id, document):
    print(f"done: {document.source_path} ({document.page_count} pages)")

async def main():
    processor = BatchProcessor(
        OllamaExtractor(config),
        max_workers=config.ollama_max_workers,
    )
    documents = await processor.process_batch(
        ["a.pdf", "b.pdf"],
        on_doc_complete=on_doc,   # also: on_page_complete(doc_id, n, page)
    )

asyncio.run(main())

$ structmd scan.png -o scan.md                     # image
$ structmd deck.pptx -o deck.md                    # office (needs LibreOffice)
$ structmd book.pdf -o book.md --pages 1,3,5-10   # page range
$ structmd report.pdf --json r.json -o r.md        # keep the JSON artifact
$ structmd --from-json r.json -o r.md              # deterministic rebuild
$ structmd batch ./papers/ -o ./md/ --workers 6   # whole directory
$ structmd batch ./papers/ -o ./md/ --save-assets  # …with figure PNGs

ollama:
  url: "http://localhost:11434"
  model: "qwen2-vl:2b"
  timeout: 120            # seconds per chat call
  max_workers: 4          # concurrent page extractions

processing:
  dpi: 150
  detect_columns: true            # heuristic multi-column reading order
  merge_continued_paragraphs: true
  normalize_headings: true        # remap [1,3,3] -> [1,2,2]

output:
  include_page_numbers: true
  page_number_format: "\n<!-- Page {page} -->\n"
  table_caption_position: "before"  # or "after"

cache:
  dir: "~/.cache/structmd"

# flat keys work too:
# cache_enabled: true
# save_assets: true
# assets_dirname: "figures"
# assets_dpi: 200

{
  "document_id": "612aefcb65144afb8ad05d6317d945e",
  "source_path": "papers/report.pdf",
  "page_count": 1,
  "pages": [
    {
      "page_number": 1,
      "width": 1275.0,                // rendered pixels at extraction DPI
      "height": 1650.0,
      "elements": [
        {
          "id": "elem_6b35b70785e6",
          "type": "heading",           // see ElementType list above
          "bbox": {"x1": 70.0, "y1": 80.0, "x2": 400.0, "y2": 110.0},
          "text": "Introduction",
          "page_number": 1,
          "confidence": 1.0,
          "metadata": {},
          "heading_level": 1,
          "list_type": null,
          "indent_level": 0,
          "continues_on_next_page": false,
          "table_data": null
        }
      ]
    }
  ],
  "metadata": {"extractor": "ollama", "model": "gemma4:cloud", "dpi": 150}
}