SciPaperlib

Version 0.1.16 adds read-only BibTeX retrieval through MCP and richer publication fields with explicit missing-metadata reports; see the guide for installation and usage.

A local research library for collecting publications and retrieving inspectable, revision-bound evidence. No LLM, embedding service, or API key is required.

The distribution and Python import name are scipaperlib. Commands scipaperlib and spl are equivalent; spl-tui launches spl --tui.

python -m pip install scipaperlib
scipaperlib demo ./demo-library
scipaperlib search --library ./demo-library --term mass --term "energy loss"
scipaperlib tui --library ./demo-library

Libraries are selected by name: spl-tui --name "heavy ion papers" uses a registered location, or creates ~/.scipaperlib/heavy_ion_papers_scipaperlib after confirmation. With no name, the library is default, stored initially at ~/.scipaperlib/default_scipaperlib. Set SCIPAPERLIB_DATADIR to change the parent directory for new libraries.

spl --list shows known libraries. Register an existing directory with spl --add-library /path/to/library --name "heavy ion papers". The registry lives at ~/.scipaperlib/config.json; SCIPAPERLIB_CONFIG overrides that file path. Registered locations remain stable when the data directory changes. Use --library PATH for an explicit location instead of --name. Scripts can pass --init-library to create a missing library without prompting.

A fixed TUI activity panel shows progress and outcomes; CLI progress goes to stderr. The TUI prevents overlapping write operations and supports stopping imports after the current request.

Add papers from the TUI's paste area and remove a selected paper with confirmation. The CLI equivalent is spl remove PAPER_ID; removal archives files by default, while --delete-files permanently deletes them.

Textual, PDF extraction, and MCP are installed by default. Legacy pdf, mcp, and tui extras remain accepted for compatibility. See the guide for imports, provenance, recovery, and agent access.

Show the installed version with spl --version (or -v). Check for application updates with spl --check-upgrade; install an update with spl --upgrade, then restart SciPaperlib. Both accept --json and work through spl-tui without launching the TUI. Upgrades target the Python environment running the command; editable development installs are protected. This is separate from spl update, which updates papers.

Follow an INSPIRE author once through Add & Process → Followed authors → Resolve → Confirm & follow. Use Scan selected/Scan all authors or spl authors scan --all to add new publications without confirming again. Followed identities and scan history stay inside each library; unfollowing retains their papers.

For evidence-based Codex research across named libraries, use the read-only spl research-mcp endpoint and the bundled scipaperlib-research skill. See research setup and evaluation.

After installing scipaperlib, run spl setup-codex to configure the research MCP connection and install its bundled skill. Use --dry-run to preview; restart Codex after setup.

Undo managed Codex integration with spl setup-codex-remove (or --dry-run to preview). It preserves later user edits and retains backups; it never removes libraries.

CLI reports are human-readable by default. Use --json for scripts and agent CLI calls; MCP results remain structured. Browse annotations without a text query using spl papers --topic jets --tag review.

Share libraries: spl bundle --name research --out research.spl.zip creates a portable library; spl import-library --file research.spl.zip or --url HTTPS_URL merges it without publication-provider requests. See the guide.

Development: integrated paper/dataset acquisition, local provider-JSON queries and source-figure evidence are described in the guide.

Release automation

After bumping the package version and committing it, push a matching vX.Y.Z tag. The Release version tag workflow publishes a GitHub Release and explicitly dispatches Publish to PyPI for that tag. Publication follows the existing test, package-validation, and clean-install checks. No additional access token is needed.

For an existing tag, run Release version tag manually with its tag input. Publishing a GitHub Release manually also continues to trigger PyPI publication.