section-anything

Pre-release (0.1). The API may change before 1.0.

Find the sections of a PDF: every heading, its level, the pages it spans and its exact character range in the extracted text. One call, with a dial from free rules to an LLM that reads the whole document, and a hard cost cap on every paid run.

import section_anything

tree = section_anything.section("paper.pdf", mode="quick")
print(tree.to_markdown())
# # A Study of Sectioning
# ## 1 Introduction
# ### 1.1 Scope
# ## 2 Methods
print(tree.sections[1])
# {'number': '1', 'title': 'Introduction', 'level': 1, 'page_start': 1, 'page_end': 1,
#  'start': 22, 'end': 484, 'flags': []}
print(tree.summary())  # mode, model, pages, sections, calls, tokens, cost_usd, seconds

Install

Python 3.11+:

pip install section-anything
pip install "section-anything[langfuse]"  # optional Langfuse tracing
# latest from GitHub:
pip install "git+https://github.com/Omniwot/section-anything#subdirectory=packages/section-anything"
# from a checkout of the repository:
pip install -e ./packages/section-anything

Dependencies: pdfplumber and pdfminer.six (MIT), pypdfium2 (Apache-2.0 / BSD-3-Clause), RapidFuzz (MIT), openai (Apache-2.0), pydantic and pydantic-settings (MIT). No PyMuPDF (AGPL).

Modes

Costs are measured averages at the built-in list prices; your documents may differ.

Command line

section-anything paper.pdf                                   # free, Markdown headings
section-anything paper.pdf --mode quick --format json        # JSON with spans and cost
section-anything paper.pdf --mode standard --max-usd 0.5     # cap this document at $0.50
section-anything paper.pdf --mode local:qwen3:4b --body      # headings plus section text

The result goes to stdout (or -o FILE), a one-line summary with the cost to stderr. Exit codes: 0 done, 2 configuration (for example no API key), 3 refused by the cost cap, 4 the PDF could not be read. API keys are read from the environment only, never from the command line.

Output

tree.sections is a list of dicts in reading order:

• tree.to_markdown(): the document title as #, every other heading as # x (level + 1), capped at six. to_markdown(body=True) adds each section's text, reflowed into paragraphs, with running headers and footers removed.
• tree.to_json() / tree.to_dict(): the sections plus mode, model, pages, calls, tokens, cost and any downgrades.
• tree.extraction holds the lines with their boxes (PDF points), for highlighting.

Configuration

Every setting can be passed in code or set as an environment variable SECTIONANY_<NAME>. Arguments win over the environment. No .env file is read, and nothing is ever written to os.environ.

Or build a Settings object once: section(pdf, "quick", settings=Settings(max_usd_per_doc=1.0)). Async code can await section_anything.asection(...).

Providers

quick and standard call a chat model through the OpenAI Python client (chat.completions.parse with a JSON schema). local calls Ollama.

An endpoint works if it:

• supports structured outputs (response_format with a strict JSON schema);
• accepts max_completion_tokens and reasoning_effort ("low"), which every request sends;
• has a price set for the model. A model with no price is refused, so the cost cap can always be enforced.

export SECTIONANY_BASE_URL="https://openrouter.ai/api/v1"   # the provider's OpenAI-compatible URL
export SECTIONANY_API_KEY="..."                              # the provider's key
export SECTIONANY_QUICK_MODEL="vendor/model-name"            # or SECTIONANY_STANDARD_MODEL
export SECTIONANY_PRICES='{"vendor/model-name": {"input": 0.15, "output": 0.60}}'  # USD per 1M tokens
section-anything paper.pdf --mode quick

tree = section_anything.section(
    "paper.pdf", mode="quick",
    base_url="https://openrouter.ai/api/v1", api_key="...", model="vendor/model-name",
    prices={"vendor/model-name": {"input": 0.15, "output": 0.60}},
)

Benchmark numbers are for the OpenAI models above; other models can score differently. If you run one, results are welcome in an issue.

Costs and caps

• Unknown prices are refused. A cloud model with no price (built-in, SECTIONANY_PRICES or prices=) is refused before the PDF is read, so the cap can always be enforced. Local models are free.
• Estimate first. Before a paid mode runs, its cost is estimated from the document. Over max_usd, the run is downgraded (standard -> quick -> free) and the downgrade is reported in tree.downgraded, or refused with CostCapExceeded when over_budget="fail".
• Hard cap while running. The cap is re-checked before every model call, and each call's output tokens are limited to what the remaining budget can pay for. A downgrade continues the same budget. The SDK's own retries are off; one retry on an unusable answer is counted.
• The built-in prices are list prices from October 2026. Check your provider's prices and override them with SECTIONANY_PRICES.

Handling untrusted PDFs

• File size and page count are checked first, from the PDF's page tree, without parsing any page content.
• Text extraction runs in a separate Python process: the text size is counted (PDFium) before layout analysis starts, the process is killed at the time limit, has a memory limit on Linux, runs in an empty temporary directory, and inherits no API keys. It returns JSON, not pickles.
• Document text is treated as untrusted in every prompt; model output is validated against a schema and clipped (strings to 300 characters, lists to 2,000 items). In quick, a heading title the model rewrote is replaced by the printed line; in standard, titles the model wrote for headingless text are flagged generated_title.
• Log messages and errors name the error type, HTTP status and error code, never prompt or response text.

Benchmarks (summary)

Heading-tree similarity (TEDS, 0-100, higher is better) with READoc's own scoring code, October 2026. The full tables, methods and per-document results are in the repository: site/data/results.js (rendered by the project site in site/) and corpus/results/.

free and quick are release 0.1.2. 0.1.1 found the abstract's heading (journals often set it small, bold or run into the first line): +2.4 to free and +3.7 to quick in a pre-registered held-out test (0.1.0: 54.8 and 63.9). 0.1.2 keeps a section number that the PDF extractor split off its title ("1" | "Introduction"): +0.7 to free (95% CI 0.5 to 1.0) and +0.5 to quick (95% CI 0.4 to 0.8; +1.7 on the 291 papers it changes) in a second pre-registered test (0.1.1: 57.2 and 67.4). standard uses neither. See the changelog.

On the same 905 papers with MinerU's cloud service: our standard 70.0, our quick 68.0, MinerU

• its LLM title levels (gpt-6.1-sol) 64.8 (standard +5.1, 95% CI 4.0 to 6.2, or +2.8 without the 154 papers where its LLM step gave up and kept its raw levels; quick +3.1, 95% CI 2.1 to 4.1, but level without those papers: +1.0, 95% CI −0.03 to 2.0), MinerU cloud alone 53.9, Docling 49.4.

On 1,112 bookmarked READoc GitHub READMEs not used in development, free scores 81.9 against Docling's 75.5. On 27 UK government reports never used in development (answer keys from each report's HTML version), the outline check improved free by +5.7 (95% CI +0.4 to +12.2; 43.1 → 48.8; measured on 0.1.0).

Where others win: our quick and standard only tie with Docling on READMEs (about 75); Nougat, an OCR model trained on arXiv, scores far higher on arXiv papers (88.5, published).

Limitations

• Reads the PDF's text layer. Scanned PDFs need OCR first.
• Tables, figures and equations are not structured; their text is part of the section text.
• free relies on bookmarks or a printed table of contents for its best results; without them it is weaker than quick on papers. When the bookmarks look complete it drops headings they do not list, so bookmarks that stop at the top levels lose real deeper headings (about 6% of READMEs lose more than 5 points); set SECTIONANY_DEMOTE_UNLISTED_HEADINGS='[]' to turn this off.
• quick and standard send text to the provider you configure; results vary slightly between runs.
• local uses Ollama's OpenAI-compatible endpoint, whose default context is small (4k tokens on most laptops) and truncates silently. Candidate batches are kept small, but give the model a larger context (for example a Modelfile with num_ctx 8192) for long documents. Quality with local models has not been measured.
• Python 3.11 or newer.

Licence

Apache-2.0. See LICENSE and NOTICE.