Metadata-Version: 2.5
Name: scipaperlib
Version: 0.3.1
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
Provides-Extra: visualization
Requires-Dist: ipywidgets<9,>=8; extra == 'visualization'
Requires-Dist: matplotlib<4,>=3.8; extra == 'visualization'
Requires-Dist: nbformat<6,>=5.10; extra == 'visualization'
Requires-Dist: numpy<3,>=1.26; extra == 'visualization'
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.

**New user?** Follow the [quick start](QUICK-START.md) to turn a paper list or a
shared library ZIP into a curated HTML table browser and Jupyter notebook.

## 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 --codex-setup` (or `spl setup-codex`) to configure the research MCP connection and install its research, data-curation and data-visualization skills. All three skills ship inside the SciPaperlib package; no separate skill download or explorer package is required. Use `spl --codex-setup --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).

## Curate scientific data and generate a browser

Portable curation records describe exact quantities, units, conditions and
source evidence. They are reusable across libraries containing the same paper
and table revisions. Curation and browser commands read existing libraries
without modifying them; interpretations live in a separate durable store.

```bash
python -m pip install 'scipaperlib[visualization]'
spl browse --name default --output ./browser --format both
```

This produces the existing three-panel offline HTML style plus a Jupyter notebook.
Repeat `--name` to combine libraries. The figure starts blank; unreviewed and
problematic records stay visible. Rebuilding uses saved reviews without calling
an LLM. Numerical data are preserved, with explicit display conversions.

To have Codex resume curation and generate both outputs, simply ask:

> Curate library research.

Or explicitly select the skill: `Use $scipaperlib-data-curation on research`.
The skill handles source checks, saved progress, review reuse and visible issues;
outputs default to `./research-browser`. Say "no browser" for curation only, or
"Rebuild the research browser" to render saved reviews without another review.

Curation follows each paper across libraries. `spl bundle` includes it in the
same archive automatically. To adopt only curation for papers you already have:

```bash
spl import-library --file alice.spl.zip --name default --curation-only
```

This preserves paper files and memberships, reuses matching evidence, and reports
skipped records and conflicts. No separate curation file is needed for sharing.

The [curation and visualization guide](docs/data-curation.md) documents the full
paper-by-paper workflow, checkpoints, source identities, grouped decisions,
transfer between libraries, conflict resolution, review scope, direct MCP/Python
analysis, and the distinction between standalone HTML and notebook/plot exports.
It also explains the transition from existing explorer workspaces.

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