Metadata-Version: 2.5
Name: scipaperlib
Version: 0.1.22
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: pillow<13,>=10
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: pypdf<7,>=5
Requires-Dist: pypdfium2<6,>=4
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

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

## Create, share, and use a library

Install SciPaperlib, create a named library, add papers, and download/index them:

```bash
python -m pip install scipaperlib
spl init --name research
spl add --name research 2409.11939
spl sync --name research
```

Rename it if needed, then prepare a ZIP snapshot:

```bash
spl --name research --rename-lib alice
spl bundle --name alice --out alice.spl.zip
```

Upload the ZIP to a file host of your choice and share its HTTPS download link.
The snapshot includes saved papers, datasets, annotations, and indexes. A compatible,
up-to-date snapshot is searchable immediately after import:

```bash
spl import-library --url https://example.org/alice.spl.zip --name my-alice
spl search --name my-alice --term "energy loss"
```

Omit `--name` to use the archive's name, falling back to the downloaded filename.
If that name or location exists, interactive imports offer **merge**, **separate
copy**, or **cancel**. Scripts must choose explicitly, for example
`--on-conflict separate` creates `alice-2`, `alice-3`, etc. No existing library is
silently overwritten. Local ZIPs use `--file alice.spl.zip`.

On a shared cluster, register the existing directory without copying its data:

```bash
spl --add-library /shared/project/alice --name cluster-alice --read-only
spl search --name cluster-alice --term "energy loss"
spl --list
```

Each user has their own registry. Read-only research caches stay in the user's
cache directory. The owner prepares the shared library and its indexes.

See [library relocation and sharing](docs/sharing.md) for moving a library,
merging multiple libraries, resumable downloads, archive contents, and recovery.
See [all commands and switches](docs/commands.md) or `spl COMMAND --help` for
detailed options, and the [guide](docs/guide.md) for the full research workflow.

Named libraries initially live under `~/.scipaperlib/`; set
`SCIPAPERLIB_DATADIR` to choose another parent for new libraries.
The registry is `~/.scipaperlib/config.json`; `SCIPAPERLIB_CONFIG` overrides it.
Registered locations remain stable when the data directory changes.
Use `--library PATH` instead of `--name` for an explicit directory.

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.

Snapshot import and library merging work offline after obtaining the archive; they never query publication providers.

Development: integrated paper/dataset acquisition, local provider-JSON queries and source-figure evidence are described in the [guide](docs/guide.md#integrated-paper-figure-and-dataset-evidence).

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