Metadata-Version: 2.4
Name: researchdown
Version: 0.1.0
Summary: A lean MarkItDown-style converter built for research papers, equations, citations, and researcher-specific Markdown workflows.
Author: ResearchDown Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/sanjukta7/researchdown
Project-URL: Repository, https://github.com/sanjukta7/researchdown
Project-URL: Issues, https://github.com/sanjukta7/researchdown/issues
Keywords: markdown,research,papers,pdf,latex,citations
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0.0; extra == "pdf"
Provides-Extra: html
Requires-Dist: beautifulsoup4>=4.12.0; extra == "html"
Provides-Extra: docx
Requires-Dist: python-docx>=1.1.0; extra == "docx"
Provides-Extra: all
Requires-Dist: pypdf>=4.0.0; extra == "all"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "all"
Requires-Dist: python-docx>=1.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# 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:

```bash
uv run researchdown examples/sample-paper.txt
```

Write Markdown to a file:

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

Or use the positional output form:

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

Use a built-in researcher profile:

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

Use a custom personality plus one-off requests:

```bash
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:

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

Run tests:

```bash
uv run --group dev pytest
```

## pip Install

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

```bash
python3 -m pip install -e .
```

## PyPI Install

Once published to PyPI:

Install into the current project environment:

```bash
uv pip install researchdown
```

Or install it as a reusable command-line tool:

```bash
uv tool install researchdown
```

Then run it:

```bash
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:

```bash
uv pip install "researchdown[all]"
```

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

```bash
uvx researchdown paper_1.pdf paper1summary.md
```

## Publishing

Build the release artifacts:

```bash
uv build
```

Publish to TestPyPI first:

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

Publish to PyPI:

```bash
uv publish
```

## CLI

```bash
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

```python
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:

```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:

```bash
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.
