BibexPy v2.0.0 "Helium" - local web platform rewrite

- FastAPI + Next.js (static export) shipped as a single pip-installable wheel
- One-click Smart Merge (DOI + Jaro-Winkler record linkage, borderline review)
- ORCID-first author disambiguation, address harmonization
- Multi-source enrichment (CrossRef, OpenAlex, Scopus, DataCite, Unpaywall, ...)
- Reproducible filtering presets, weighted quality dashboard, full provenance
- Structured export: WoS, VOSviewer, BibTeX, RIS, CSV/TSV/XLSX
- Corporate navy/purple palette, Helium logo set, launcher homepage
- CI: tag-triggered wheel build + PyPI Trusted Publishing (OIDC)

Author: bcankara

.env.example

@@ -0,0 +1,13 @@
+# Root .env — docker-compose tarafından okunur.
+
+# --- Bibliometrik API anahtarları (opsiyonel) ---
+SCOPUS_API_KEY=
+SEMANTIC_SCHOLAR_API_KEY=
+UNPAYWALL_EMAIL=
+CROSSREF_EMAIL=
+
+# --- DeepSeek (Deneysel disambiguation) ---
+DEEPSEEK_API_KEY=
+DEEPSEEK_MODEL=deepseek-chat
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DISAMBIGUATION_ENABLED=true

.gitattributes

@@ -0,0 +1,14 @@
+# Satır sonu normalizasyonu — repo LF saklar; shell scriptleri DAİMA LF (CI/Linux güvenli),
+# Windows scriptleri CRLF. Bu, scripts/build_wheel.sh'in CI'da \r yüzünden kırılmasını önler.
+* text=auto eol=lf
+*.sh   text eol=lf
+*.ps1  text eol=crlf
+*.bat  text eol=crlf
+
+# İkili varlıklar
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.ico  binary
+*.whl  binary

.github/assets/bibexpy-home.png

@@ -0,0 +1,67 @@
+name: Release (PyPI wheel)
+
+# v* tag'i push edilince (örn. v2.0.0) tetiklenir:
+#   git tag v2.0.0 && git push origin v2.0.0
+#
+# Akış: Node ile frontend static export → apps/api + bibex_core kopyala →
+#       tek wheel build → PyPI'a yükle (Trusted Publishing / OIDC).
+#
+# Auth: PyPI Trusted Publishing (OIDC) — secret/token GEREKMEZ. PyPI'da publisher
+#       tanımlı: Repository bcankara/BibexPy · Workflow release.yml.
+#       (Yedek yöntem: twine + PYPI_API_TOKEN secret; bu workflow OIDC kullanır.)
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch: {}   # manuel tetikleme
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # PyPI Trusted Publishing (OIDC) — token gerekmez
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node (frontend build)
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: apps/web/package-lock.json
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install frontend deps
+        working-directory: apps/web
+        run: npm ci
+
+      - name: Build wheel (static export + assemble + build)
+        run: bash scripts/build_wheel.sh
+
+      - name: Verify wheel contents
+        run: |
+          WHL=$(ls python_pkg/dist/*.whl)
+          echo "Wheel: $WHL"
+          python -m zipfile -l "$WHL" | grep -E "_server/main.py|_web/index.html|bibex_core/scp2xlsx.py" \
+            || { echo "HATA: wheel eksik içerik"; exit 1; }
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: bibexpy-dist
+          path: python_pkg/dist/*
+
+      # PyPI Trusted Publishing (OIDC) — PyPI'da publisher tanımlı:
+      #   Repository: bcankara/BibexPy · Workflow: release.yml
+      # Token/secret saklamaya gerek yok; kimlik GitHub OIDC ile doğrulanır.
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: python_pkg/dist

.github/workflows/release.yml

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+.next/
+.turbo/
+out/
+dist/
+*.log
+.pnpm-store/
+
+# Env
+.env
+.env.local
+.env.*.local
+
+# Storage (kullanıcı dosyaları)
+apps/api/storage/
+!apps/api/storage/.gitkeep
+
+# IDE
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Build
+build/
+*.tar.gz
+
+# OS
+Thumbs.db
+desktop.ini
+
+# Temp
+tmp/
+
+# Dev/release scratch — geçici venv'ler, screenshot/seed scriptleri (repoya girmez)
+.shotsenv/
+.pkgtest*/
+home*.js
+shot.js
+seed.py
+
+# Paper assets — manuscript ve figürler kod reposunda tutulmaz
+manuscript_*.docx
+manuscript_assets/
+
+# V1 — kendi git repo'su olan ayri kod tabani; V2 reposunda izlenmez
+/BibexPy/

.gitignore

@@ -0,0 +1,171 @@
+<p align="center">
+  <a href="https://bibexpy.com">
+    <img src="apps/web/public/images/bibexpy-logo-full.png" alt="BibexPy — V2.0.0 Helium — Bibliometrics Experience with Python" width="420">
+  </a>
+</p>
+
+<p align="center">
+  <strong>Self-hosted, reproducible bibliometric data preparation for Web of Science &amp; Scopus.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bibexpy/"><img src="https://img.shields.io/pypi/v/bibexpy?color=0c2847&label=PyPI" alt="PyPI"></a>
+  <a href="https://pypi.org/project/bibexpy/"><img src="https://img.shields.io/pypi/pyversions/bibexpy?color=0c2847" alt="Python"></a>
+  <a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPL--3.0-4f1964.svg" alt="License: GPL-3.0"></a>
+  <a href="https://doi.org/10.1016/j.softx.2025.102098"><img src="https://img.shields.io/badge/DOI-10.1016%2Fj.softx.2025.102098-0f766e" alt="DOI"></a>
+</p>
+
+<p align="center">
+  🌐 <a href="https://bibexpy.com">bibexpy.com</a> ·
+  📚 <a href="https://bibexpy.com/doc">Documentation</a> ·
+  📄 <a href="https://doi.org/10.1016/j.softx.2025.102098">Paper (SoftwareX)</a> ·
+  ▶️ <a href="https://www.youtube.com/@BibexPy">YouTube</a>
+</p>
+
+---
+
+**BibexPy v2.0.0 “Helium”** — the successor to v1.1.0 “Hydrogen” — turns the original
+command-line BibexPy into a **local web platform**, shipped as a single pip-installable
+package. It merges, filters, harmonizes, enriches and exports Web of Science + Scopus
+records with full provenance, and **never sends your licensed exports off your machine**.
+
+<p align="center">
+  <img src=".github/assets/bibexpy-home.png" alt="BibexPy v2 home screen" width="780">
+</p>
+
+## Install
+
+```bash
+pip install bibexpy
+bibexpy            # launches the local web UI (browser opens automatically)
+```
+
+Requires only **Python 3.10+** — no Node.js/npm needed (the Next.js UI ships precompiled
+inside the wheel). Works on Windows, macOS and Linux.
+
+```bash
+bibexpy --port 8080        # custom port
+bibexpy --no-browser       # server only
+bibexpy --storage ./data   # custom storage folder
+bibexpy --version          # → BibexPy 2.0.0 (Helium)
+```
+
+Projects/data live under `~/.bibexpy/storage`; settings and API keys under `~/.bibexpy/.env`
+(managed from the in-app Settings page).
+
+## What's new in v2
+
+- **One-click Smart Merge** — multi-stage probabilistic record linkage: exact DOI/identifier
+  matching + Jaro–Winkler title similarity, confidence scoring, and an optional
+  borderline-review queue. The result includes a copy-ready methodology paragraph.
+- **ORCID-first author disambiguation** — ORCID identifiers as deterministic evidence, with a
+  constrained field-similarity fallback only when coverage is incomplete.
+- **Address harmonization** — organization roll-up to a canonical parent institution +
+  country standardization.
+- **Multi-source enrichment** — fetch-once-fill-all across CrossRef, OpenAlex, Scopus,
+  DataCite, Unpaywall, Europe PMC and Semantic Scholar; reverse-DOI recovery; identity
+  fields (ORCID/ROR). Verifiable sources only — no ML-inferred metadata.
+- **Reproducible filtering** — multi-facet inclusion/exclusion criteria, saved as reusable
+  presets.
+- **Quality dashboard** — a bibliometrically weighted health score + an exportable General
+  Overview table (CSV / XLSX / PNG).
+- **Provenance** — append-only audit log, pre-operation snapshots, isolated analyses, and an
+  auto-generated methodology narrative for your paper's data-preparation section.
+- **Structured export** — WoS plain text, VOSviewer TSV, BibTeX, RIS, CSV, TSV, XLSX
+  (interoperable with VOSviewer & Biblioshiny).
+
+## Workflow
+
+A guided five-step pipeline:
+
+**Data & Merge → Records & Filtering → Harmonization → Export → Report**
+
+Raw Scopus (`.csv`) and Web of Science (`.txt`) exports are uploaded and merged in a single
+click (file preparation runs implicitly), and each merge is stored as an isolated,
+reproducible analysis.
+
+## Repository layout
+
+```
+apps/
+  web/              # Next.js 14 frontend (static-exported into the wheel)
+  api/              # FastAPI backend (documented HTTP API under /api)
+packages/
+  bibex_core/       # core bibliometric library (converters, merge, C1 utils, …)
+python_pkg/         # PyPI packaging — builds the single pip wheel
+scripts/            # build_wheel.sh / build_wheel.ps1
+.github/workflows/  # release.yml — tag → wheel → PyPI (Trusted Publishing)
+```
+
+The published wheel bundles the **prebuilt** frontend (`_web`) + backend (`_server`) +
+vendored core, so end users need no Node.js. Those build-time copies are git-ignored — the
+source of truth is `apps/` and `packages/`, and the wheel is regenerated by CI.
+
+## Development
+
+```bash
+# Backend (port 8001)
+cd apps/api
+pip install -r requirements.txt
+pip install -e ../../packages/bibex_core
+uvicorn main:app --reload --port 8001
+
+# Frontend (port 3000) — separate terminal
+cd apps/web
+npm install
+npm run dev
+```
+
+Then open <http://localhost:3000>. Run tests with `cd apps/api && python -m pytest -q`.
+
+## Build the wheel (maintainers)
+
+```bash
+bash scripts/build_wheel.sh      # macOS / Linux
+pwsh scripts/build_wheel.ps1     # Windows
+```
+
+→ `python_pkg/dist/bibexpy-2.0.0-py3-none-any.whl` — a pure-python `py3-none-any` wheel that
+installs on Windows / macOS / Linux with no compiler.
+
+## Release
+
+Tagging a version triggers GitHub Actions, which builds the wheel (with Node) and publishes
+it to PyPI via **Trusted Publishing (OIDC)** — no API tokens stored:
+
+```bash
+git tag v2.0.0 && git push origin v2.0.0
+```
+
+## Links
+
+[Website](https://bibexpy.com) ·
+[Docs](https://bibexpy.com/doc) ·
+[YouTube](https://www.youtube.com/@BibexPy) ·
+[X / Twitter](https://twitter.com/BibexPy) ·
+[Instagram](https://www.instagram.com/bibexpy/) ·
+[Paper (SoftwareX)](https://doi.org/10.1016/j.softx.2025.102098)
+
+## License
+
+[GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0).
+
+## Citation
+
+If you use BibexPy in your research, please cite:
+
+> Kara, B. C., Şahin, A., & Dirsehan, T. (2025). BibexPy: Harmonizing the bibliometric
+> symphony of Scopus and Web of Science. *SoftwareX*, 30, 102098.
+> <https://doi.org/10.1016/j.softx.2025.102098>
+
+```bibtex
+@article{bibexpy2025,
+  title   = {BibexPy: Harmonizing the bibliometric symphony of {Scopus} and {Web of Science}},
+  author  = {Kara, Burak Can and {\c{S}}ahin, Alperen and Dirsehan, Ta{\c{s}}k{\i}n},
+  journal = {SoftwareX},
+  volume  = {30},
+  pages   = {102098},
+  year    = {2025},
+  doi     = {10.1016/j.softx.2025.102098}
+}
+```

README.md

@@ -0,0 +1,21 @@
+# --- Sunucu ---
+API_HOST=127.0.0.1
+API_PORT=8001
+API_CORS_ORIGINS=http://localhost:3000
+
+# --- Depolama ---
+STORAGE_DIR=./storage
+
+# --- Bibliometrik API anahtarları (opsiyonel — enrichment için) ---
+SCOPUS_API_KEY=
+SEMANTIC_SCHOLAR_API_KEY=
+UNPAYWALL_EMAIL=
+CROSSREF_EMAIL=
+
+# --- DeepSeek (Deneysel disambiguation) ---
+DEEPSEEK_API_KEY=
+DEEPSEEK_MODEL=deepseek-chat
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DISAMBIGUATION_ENABLED=true
+DISAMBIGUATION_BLOCKING_THRESHOLD=0.7
+DISAMBIGUATION_AUTO_APPROVE_THRESHOLD=0.95

apps/api/.env.example

@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# System deps for pandas/scikit
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Önce bibex_core (editable install)
+COPY packages/bibex_core /opt/bibex_core
+RUN pip install --no-cache-dir -e /opt/bibex_core
+
+# API
+COPY apps/api/requirements.txt /tmp/requirements.txt
+# requirements.txt'deki -e ../../packages/... satırı bizim için zaten yapıldı; geri kalanı kur
+RUN grep -v "^-e " /tmp/requirements.txt > /tmp/req.txt && \
+    pip install --no-cache-dir -r /tmp/req.txt
+
+COPY apps/api /app
+
+# NLTK data preheat
+RUN python -c "import nltk; nltk.download('punkt'); nltk.download('stopwords')" || true
+
+EXPOSE 8001
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]