Metadata-Version: 2.5
Name: scipaperlib
Version: 0.1.13
Summary: Local publication acquisition and evidence-preserving source search
Project-URL: Repository, https://github.com/matplo/scipaperlib
Project-URL: Issues, https://github.com/matplo/scipaperlib/issues
Author: matplo
Maintainer: matplo
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: httpcore<1.1,>=1.0.9
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: mcp<2,>=1.20
Requires-Dist: packaging<27,>=24
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: pypdf<7,>=5
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=13
Requires-Dist: textual<9,>=8.2
Requires-Dist: tomlkit<1,>=0.13
Requires-Dist: typer<1,>=0.16
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
Requires-Dist: twine<8,>=6; extra == 'dev'
Provides-Extra: mcp
Provides-Extra: pdf
Provides-Extra: tui
Description-Content-Type: text/markdown

# SciPaperlib

Version 0.1.13 adds five concurrent download workers, batched revision lookups, and aggregate download progress; see the [guide](docs/guide.md) 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](docs/guide.md) 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](docs/research.md).

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](docs/guide.md#share-and-import-libraries).
