Initial commit: AutoPaperToPPT — paper search → thesis-style PPT toolkit

Single-process Python 3.12+ CLI + MCP server that searches papers,
de-duplicates across sources, optionally enriches via LLM, and exports
to .pptx / .xlsx / .bib / .md / .json.

Search layer:
- 11 pluggable fetcher sources behind a shared HTTPS-only async client
  with per-source token-bucket rate limits: arxiv, semantic_scholar,
  openalex, pubmed, acm (Crossref-scoped), dblp, crossref (generic),
  openaire, springer, ieee, scholar. Top-tier venue whitelist on by
  default; opt-in scraping for ieee/scholar via env vars; springer
  needs a free API key.
- Field-merge dedup so a paper indexed via multiple sources keeps the
  earliest canonical record but inherits any OA pdf_url, doi, venue,
  citation count from later duplicates.
- citation_pdf_url meta-tag fallback when publisher landing pages
  return HTML instead of a PDF, recovering a sizeable fraction of
  paywalled-but-publicly-mirrored papers.

Exporter layer:
- pptx: 16:9 widescreen, page-numbered, three rendering tiers
  (lightweight abstract-only / enriched-flat / thesis-style with
  pain-point quadrants, KPI block, technique-comparison tables,
  per-RQ result tables, contribution summary, core observation,
  limitations & future work, Q&A, references); shape-name contract
  for downstream editing tools; headless overflow check tied to a
  7.05" footer guard.
- i18n template strings across 14 languages (en, zh-tw, zh-cn, ja,
  es, fr, de, ko, pt, ru, it, vi, hi, id), every key present in
  every language enforced by pytest.
- xlsx with Source (real publication venue) vs Indexed-via (fetcher
  that returned the metadata) columns kept distinct so users never
  see "openalex" in a column they read as the venue.

MCP server: 11 tools (list_sources, search, fetch_paper,
fetch_pdf_text, download_pdfs, export, plus five pptx_* editing
tools) so an MCP-aware LLM client can drive the full workflow without
the Anthropic API key.

Local-PDF mode (--pdf): accepts a single file or a directory; a
heuristic metadata extractor pulls title, authors, year, arXiv ID,
DOI and the real abstract straight from each PDF's front matter,
anchored on the Abstract header rather than blind prefix truncation.

Documentation: 14-language README + 14-language Sphinx tree, all
mirroring the canonical CLAUDE.md / AGENTS.md rules — LLM-as-agent
default path, URL/DOI verification, prune-irrelevant-downloads. Six
regression tests in tests/test_agents_md.py and tests/test_i18n.py
pin the cross-document alignment so future commits can't drift the
rules out of sync.

Tooling: ruff + bandit + 392-test pytest suite, all hermetic
(fetcher tests use recorded fixtures, no live HTTP). Definition of
Done in CLAUDE.md enumerates the gates a commit must pass.

Author: JE-Chen

.bandit

@@ -0,0 +1,7 @@
+exclude_dirs:
+  - tests
+  - .venv
+  - build
+skips:
+  # No project-wide skips yet. Add here with a one-line reason when needed,
+  # e.g. "# B101: assert allowed in tests" (already excluded via exclude_dirs).

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -0,0 +1,190 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Generated artifacts — search runs, downloaded PDFs, exported decks.
+# Produced by `py -m autopapertoppt --out ./exports/...` and can be
+# re-generated; committing them would bloat history.
+exports/
+
+# Local agent / IDE settings — user-specific, not part of the project.
+.claude/
+.idea/

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+formats:
+  - htmlzip