Metadata-Version: 2.4
Name: publication-lens
Version: 1.0.0
Summary: Track researchers' publications across sources and rank their venues, with per-person folders, notes and reports
Author: Benjamin Piwowarski
Author-email: Benjamin Piwowarski <benjamin@piwowarski.fr>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: alembic>=1.20.0
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: lark>=1.3.1
Requires-Dist: latex2mathml>=3.81.1
Requires-Dist: lxml>=6.1.3
Requires-Dist: nicegui>=3.17.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: sqlalchemy>=2.1.1
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# PublicationLens

A local web app (NiceGUI + SQLite) to follow and evaluate researchers: it tracks their
publications across sources, ranks their venues, and keeps per-person folders with tags,
notes, stored PDFs and reports. Venues are ranked with Scimago, CORE (every edition since
2008) and a predatory list.

## Features

- **People** with profiles on DBLP (SPARQL endpoint), HAL, ORCID, Semantic Scholar, Google
  Scholar, theses.fr and OpenAlex (needs a free API key). Profiles are found automatically
  and must be **validated** by hand; each source shows its update status (never synced,
  updating, up to date, out of date, error). Syncing is on demand only.
- **Merging** across sources (DOI, titles, years), preprints folded into the published
  version, PDF links, manual split / merge / hide.
- **Publications panel**: distribution, publications by year,
  co-authors, author position, "with PhD student", cross-filtering, named **periods** with
  **stars**, **flags** (short, demo…) that stick to papers, **tags** (global or within a
  period) and Markdown **notes**, with a Markdown listing of the noted / tagged papers;
  **tag from a pasted list** (e.g. a report's numbered list: matched by HAL id / DOI / title,
  missing papers searched on HAL and added, the list's numbers kept for reporting).
  Notes accept LaTeX (`$…$`, `$$…$$`), edited with a Markdown editor (toolbar, preview).
- **Reports** within a period / folder: Markdown citing the papers (Pandoc's `[@key]`,
  `@key`, `[@key]{.notes}`, `[@key]{.tags}`), checking each paper to discuss (by tags) is
  cited, substituted (numbers like **#6**, titles, notes, tags) when copied.
- **PDFs**: downloaded from the papers' open-access links (sources, else Unpaywall), one by
  one or for all the papers shown, or uploaded; stored in the data directory and read in
  the browser with PDF.js (highlight, text, drawing, images), the annotations saved back,
  the paper's tags and notes alongside; clean-up of the files of deleted papers.
- **Venues** (Conferences / Journals pages): variants after cleaning, two-level
  classification (kind → rank), default levels per kind, manual decisions per paper or per
  venue that are never overridden.
- Author highlighting: the person (with aliases) and their PhD students (from theses.fr),
  with potential matches to confirm.
- **Settings**: ranking sources, confidence threshold, rewrite and cleaning rules, venue
  kinds, flags, datasets, JCR import, API keys, and **import / export** (replace, or merge
  with per-conflict choices) to share them.

## Usage

```sh
uv tool run publication-lens   # http://127.0.0.1:8081
```

or install it with `uv tool install publication-lens` and run `publication-lens`. Options:
`--port`, `--host`, `--data-dir`, `--no-browser`. Press Ctrl-C, or the power button in the
header, to quit.

Data lives in `~/.local/share/publication-lens` (override with `PUBLICATION_LENS_DATA`). Your email is
required before anything is fetched (it identifies you to the sources); it and the API keys can
be given with `PUBLICATION_LENS_EMAIL`, `OPENALEX_API_KEY` / `S2_API_KEY` or in Settings → API keys.

## Data sources

Venue ranks come from third-party data, credited here and in the app (Settings → Data):

- **[SCImago Journal & Country Rank](https://www.scimagojr.com)** (journals), shipped with
  the app. *SCImago, (n.d.). SJR — SCImago Journal & Country Rank [Portal].* SCImago allows
  the use of its data as long as the source is cited; the journal metadata comes from
  Scopus (Elsevier).
- **[ICORE conference rankings](https://portal.core.edu.au/conf-ranks/)** (conferences,
  every CORE edition since 2008), shipped with the app.
- **Predatory list**: Beall's list as maintained by
  [stop-predatory-journals](https://github.com/stop-predatory-journals/stop-predatory-journals.github.io)
  (MIT licence), downloaded by the app and refreshed weekly. Being listed is an indication,
  not a verdict.
- **JCR** impact factors are Clarivate's and are not distributed: import your own export.

See [`src/publication_lens/data/README.md`](src/publication_lens/data/README.md) for the
files and their terms.

## Licence

The code is released under the [MIT licence](LICENSE). The ranking datasets keep their
sources' terms (see above).

## Development

```sh
uv sync
uv run pre-commit install
uv run pytest              # unit + simulated-UI tests
uv run pytest -m live -o addopts=""   # smoke tests against the real APIs
uv run publication-lens --live-reload  # offers a restart when the code changes
```

- `src/publication_lens/ranking/` — venue normalization, fuzzy matching and resolution
  (checked against reference fixtures by `tests/test_matcher_parity.py`).
- `sources/` — one adapter per source; `merge.py` — clustering; `sync.py` — syncing and
  auto-matching; `venues.py` — venues; `pubview.py` — panel view model; `ui/` — pages.
- Schema changes go through Alembic migrations (`db/migrations/versions`), applied at
  startup; never edit a released migration.
