researchdown 0.1.0

A lean MarkItDown-style converter built for research papers, equations, citations, and researcher-specific Markdown workflows.

ResearchDown

ResearchDown is a tiny, from-scratch document-to-Markdown tool for mathematical researchers and research-heavy reading workflows.

It is inspired by the broad idea of Microsoft MarkItDown, but intentionally keeps a smaller surface area:

• Convert papers and notes into Markdown from plain text, Markdown, HTML, PDF, and DOCX.
• Preserve research structure: title, abstract, numbered sections, equations, citations, references, theorem-like blocks, figures, and tables.
• Add a researcher-facing digest with extracted claims, methods, limitations, open questions, math objects, and citation signals.
• Run with built-in or custom personalities so output can match how a specific researcher reads.
• Avoid heavyweight services by default. Optional format support is installed only when needed.

Quickstart With uv

From this repo:

uv run researchdown examples/sample-paper.txt

Write Markdown to a file:

uv run researchdown examples/sample-paper.txt -o output.md

Or use the positional output form:

uv run researchdown examples/sample-paper.txt output.md

Use a built-in researcher profile:

uv run researchdown examples/sample-paper.txt --profile theorem-mapper

Use a custom personality plus one-off requests:

uv run researchdown examples/sample-paper.txt \
  --persona examples/persona.toml \
  --request "Prefer theorem/proof maps"

Install optional extractors into the uv environment when you need richer formats:

uv sync --extra pdf --extra html --extra docx
uv run researchdown paper.pdf -o paper.md

Run tests:

uv run --group dev pytest

pip Install

uv run is the easiest path, but regular pip still works:

python3 -m pip install -e .

PyPI Install

Once published to PyPI:

Install into the current project environment:

uv pip install researchdown

Or install it as a reusable command-line tool:

uv tool install researchdown

Then run it:

researchdown paper_1.pdf paper1summary.md
researchdown paper_2.pdf -o paper2summary.md --profile peer-reviewer
researchdown paper_3.pdf paper3summary.md --request "Focus on assumptions and limitations"

For PDF, DOCX, and HTML support:

uv pip install "researchdown[all]"

If you prefer an isolated one-off run without installing:

uvx researchdown paper_1.pdf paper1summary.md

Publishing

Build the release artifacts:

uv build

Publish to TestPyPI first:

uv publish --publish-url https://test.pypi.org/legacy/

Publish to PyPI:

uv publish

CLI

researchdown paper.pdf paper.md
researchdown paper.pdf -o paper.md
researchdown paper.html --profile theorem-mapper
researchdown notes.txt --request "Focus on assumptions and possible counterexamples"
researchdown paper.pdf --persona examples/persona.toml --include-prompt

Python API

from researchdown import ResearchDown

rd = ResearchDown(
    profile="literature-scout",
    special_requests=["Track datasets and evaluation metrics"],
)
result = rd.convert("paper.pdf")
print(result.markdown)

Custom Personalities

Use JSON or TOML:

name = "skeptical applied mathematician"
tone = "precise, terse, assumption-hunting"
focus = ["definitions", "proof obligations", "failure cases"]
questions = [
  "Which claims depend on smoothness or compactness?",
  "Where would the method break under noisy data?"
]

Then run:

researchdown paper.pdf --persona persona.toml --request "Prefer theorem/proof maps"

Design

ResearchDown has only four moving parts:

• extractors: read source text from a small set of formats.
• analyzer: detects research-paper structure and signals.
• persona: merges built-in profiles, custom personality files, and one-off requests.
• renderer: writes clean Markdown plus optional prompt instructions for downstream LLMs.

No plugin registry, no cloud dependency, no large framework.

Security

ResearchDown reads files with the privileges of the current process. Do not pass untrusted paths or untrusted remote content to a hosted service without your own validation and sandboxing.