quelle 0.1.0__tar.gz

quelle-0.1.0/.env.example

@@ -0,0 +1,29 @@
+# quelle configuration.
+# Copy to `.env` and fill in. All values are optional — defaults are tight
+# enough that `uv run quelle fetch 10.xxx/yyy` works without any config.
+#
+# Filesystem layout (config / data / cache) is resolved automatically via
+# platformdirs. Override any of the three with QUELLE_CONFIG_DIR,
+# QUELLE_DATA_DIR, QUELLE_CACHE_DIR — useful for tests or custom deployments.
+
+# Your email. Goes into the User-Agent and drops into the polite pool
+# for both Crossref and OpenAlex — recommended for any production use.
+QUELLE_CONTACT_EMAIL=alice@example.com
+
+# Free OpenAlex key (openalex.org/settings/api). Unauthenticated calls work
+# but have a lower daily quota. Get one if you plan to do bulk ingest.
+#OPENALEX_API_KEY=
+
+# Free Semantic Scholar key (api.semanticscholar.org/getting-started).
+# Unauthenticated calls also work; the key only raises the rate limit.
+#SEMANTIC_SCHOLAR_API_KEY=
+
+# Unpaywall requires an email as an API parameter. Defaults to
+# QUELLE_CONTACT_EMAIL when unset.
+#UNPAYWALL_EMAIL=alice@example.com
+
+# HTTP timeout per request, in seconds.
+#QUELLE_HTTP_TIMEOUT=30
+
+# Maximum PDF size to download, in megabytes. Downloads are aborted above this.
+#QUELLE_MAX_PDF_MB=100

quelle-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+      contents: read    # required so actions/checkout@v4 can read the repo
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quelle-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Secrets and local config
+.env
+.env.local
+
+# Local dev state (dev-mode cache DB + downloaded PDFs under the repo root).
+# Installed users' data lives in platformdirs dirs, not here.
+.dev-state/
+.publications-state/
+
+# Python build artefacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Test / coverage artefacts
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/

quelle-0.1.0/CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md — quelle
+
+Local CLI that fetches academic publication metadata and PDFs from open sources (OpenAlex, Crossref, Semantic Scholar, arXiv, Unpaywall) and returns them as normalised JSON. Designed as a composable building block — the tool has no hardcoded opinion about where results end up; downstream consumers (skills, scripts, reference managers) decide that.
+
+The name is German for *source*: in academic citations, "Quelle:" prefixes a bibliographic reference, and fetching from open sources is what this tool does. The package distributes on PyPI under `quelle`; the command-line binary is also `quelle`.
+
+## Project type
+
+- **Not deployed.** Per-laptop tool, distributed via PyPI (`pip install quelle`) or `uv tool install quelle`.
+- **No daemon / server.** Every invocation is a short-lived CLI process.
+- **Multiple upstreams, no single source of truth.** This tool queries 5+ different open APIs and normalises their responses. Cache is a convenience, not a mirror.
+
+## Stack
+
+- Python 3.12+, `uv`-managed
+- Typer (CLI) + httpx (sync HTTP) + stdlib `sqlite3` (cache) + rich + environs + platformdirs + pytest + pytest-httpx
+- No GUI. No ORM. No async.
+
+## Architecture
+
+Strict layers — imports only go downward.
+
+```
+quelle/
+  models/        <- Publication, Author (pure dataclasses, no I/O)
+  repositories/  <- http_client, errors, sources/{openalex, crossref, ...}
+  services/      <- resolver (orchestrates which source to hit first)
+  cli/           <- Typer app + config sub-app + rich/JSON output helpers
+  paths.py       <- platformdirs resolution (config / data / cache)
+  migrate.py     <- One-shot migration from the legacy PublicationManager layout
+  settings.py    <- environs config (uses paths.resolve internally)
+```
+
+Layer rules:
+
+- **Models** import nothing from this project.
+- **Repositories** import from models. Each source (`sources/openalex.py` etc.) is a self-contained module that returns a `Publication`.
+- **Services** import from models + repositories. The `resolver` decides which source to call based on the shape of the query (DOI vs arXiv id vs free text).
+- **CLI** is the wiring layer: Typer command → load Settings → build httpx client → call resolver → render via `quelle/cli/output.py`.
+
+## Paths
+
+`quelle/paths.py` resolves three locations via [`platformdirs`](https://platformdirs.readthedocs.io/), following each OS's conventions:
+
+| Role | Linux (XDG) | macOS | Windows |
+|---|---|---|---|
+| Config (`.env`) | `~/.config/quelle/` | `~/Library/Application Support/quelle/` | `%APPDATA%\quelle\` |
+| Data (`pdfs/`) | `~/.local/share/quelle/` | `~/Library/Application Support/quelle/` | `%LOCALAPPDATA%\quelle\` |
+| Cache (`cache.sqlite`) | `~/.cache/quelle/` | `~/Library/Caches/quelle/` | `%LOCALAPPDATA%\quelle\Cache\` |
+
+Override any of the three at runtime via `QUELLE_CONFIG_DIR`, `QUELLE_DATA_DIR`, `QUELLE_CACHE_DIR`. Env-var overrides always win over both dev-mode detection and platformdirs defaults — this is how tests isolate filesystem state via `tmp_path`.
+
+### Dev mode vs installed mode
+
+`paths.resolve()` walks up from `__file__` looking for `pyproject.toml`:
+
+- **Dev** (running from a source checkout, e.g. `uv run quelle …`): config dir = repo root (so `.env` at the repo root is still loaded automatically), data dir = `.dev-state/`, cache dir = `.dev-state/cache/`. `.dev-state/` is gitignored.
+- **Installed** (`__file__` inside `site-packages/` or a `uv tools/` venv): config / data / cache come from `platformdirs`.
+
+The detection is a heuristic (`_looks_like_installed_location` in `paths.py`) — site-packages and uv tools venvs are recognised and force installed mode regardless of any nearby `pyproject.toml`.
+
+## Sources
+
+Implemented in priority order (see `quelle/repositories/sources/`). Each module exports:
+
+- `search_by_title(client, settings, title) -> Publication`
+- `fetch_by_doi(client, settings, doi) -> Publication` (where applicable)
+- `_to_publication(raw) -> Publication` — private mapper, unit-tested without network
+
+Sources never decide the resolution order themselves — the `services/resolver.py` orchestrator does.
+
+## Rate-limit discipline
+
+- **Crossref polite pool**: every request must carry `mailto=…` (either as a query param or a `User-Agent: …(mailto:…)` suffix). `build_client` in `quelle/repositories/http_client.py` bakes the User-Agent.
+- **arXiv**: max 1 request / 3 seconds for metadata queries. Static PDF fetches from `arxiv.org/pdf/...` are unbounded.
+- **Unpaywall**: 100 ms delay between requests, 100k / day quota.
+- **OpenAlex**: $1/day quota when authenticated, lower unauth. Don't batch fetch without caching.
+
+## Commands
+
+```bash
+make dev-install   # install all deps incl. dev
+make test          # pytest
+make lint          # ruff check + format --check
+make format        # ruff check --fix + format
+make tool-install  # install `quelle` globally via `uv tool install`
+```
+
+## Workflow
+
+1. After any code change: `make format` — enforced by ruff.
+2. Before committing: `make lint && make test`.
+3. When adding a new CLI command: add a smoke test in `tests/test_cli_smoke.py` (or `test_cli_config.py` for `config`-subapp commands).
+4. When adding a new source: add a mapper unit test that feeds a recorded fixture JSON into `_to_publication` — no network required.
+5. When touching the path-resolution layer or the migration: tests in `tests/test_paths.py` and `tests/test_migrate.py` must stay green. Both use `monkeypatch` to isolate filesystem state; never hit the real user's home dir.

quelle-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Alice Voland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE DEALINGS IN THE SOFTWARE.

quelle-0.1.0/Makefile

@@ -0,0 +1,29 @@
+PYTHONPATH := $(shell pwd)
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "%-16s %s\n", $$1, $$2}'
+
+install: ## Install dependencies into a uv-managed venv
+	uv sync
+
+dev-install: ## Install dev dependencies too
+	uv sync --all-groups
+
+run: ## Run the quelle CLI (pass args after --, e.g. make run -- config)
+	uv run quelle
+
+test: ## Run pytest
+	uv run pytest; RET=$$?; if [ $$RET -eq 5 ]; then exit 0; else exit $$RET; fi
+
+coverage: ## Run pytest with line-coverage report
+	uv run pytest --cov=quelle --cov-report=term-missing --cov-report=html
+
+lint: ## Ruff lint + format check
+	uv run ruff check .
+	uv run ruff format --check .
+
+format: ## Ruff auto-fix + format
+	uv run ruff check --fix .
+	uv run ruff format .
+
+.PHONY: help install dev-install run test coverage lint format

quelle-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: quelle
+Version: 0.1.0
+Summary: Fetch academic publication metadata and PDFs from open sources (OpenAlex, Crossref, Semantic Scholar, arXiv, Unpaywall) and return normalised JSON
+Project-URL: Homepage, https://github.com/vcoeur/quelle
+Project-URL: Repository, https://github.com/vcoeur/quelle
+Project-URL: Issues, https://github.com/vcoeur/quelle/issues
+Author: Alice Voland
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.12
+Requires-Dist: environs>=14.6.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: platformdirs>=4
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.16
+Description-Content-Type: text/markdown
+
+# quelle
+
+`quelle` is a local CLI that fetches academic publication metadata and PDFs from open academic sources (OpenAlex, Crossref, Semantic Scholar, arXiv, Unpaywall) and returns them as normalised JSON. Designed as a composable building block — feed the output into any note-taking system, reference manager, or research workflow.
+
+The name is German for *source* — in academic German, "Quelle:" is the word that introduces a bibliographic reference, and fetching from open sources is exactly what the tool does.
+
+## What it does
+
+Given a publication identifier or a free-text title, `quelle fetch` returns a normalised JSON blob with title, authors, year, venue, DOI, abstract, citation count and (optionally) a downloaded local PDF. It walks a fallback chain of free open sources:
+
+| Source | Role | Rate limit |
+|---|---|---|
+| [OpenAlex](https://docs.openalex.org/) | Primary metadata + OA PDF URL | $1/day on free key |
+| [Crossref](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) | DOI-authoritative fallback (abstract, journal block) | polite pool (no hard cap) |
+| [Semantic Scholar](https://api.semanticscholar.org/) | Citation graph + metadata fallback | 5000 / 5 min unauth |
+| [arXiv](https://info.arxiv.org/help/api/) | Preprint metadata + direct PDFs | 1 req / 3s (enforced) |
+| [Unpaywall](https://unpaywall.org/products/api) | DOI → OA PDF lookup | 100k / day |
+
+Google Scholar URLs are **not supported**: Scholar has no public API and its Terms of Service prohibit automated access. If you only have a Scholar link, open the page, copy the paper title, and feed that to `quelle fetch` as a free-text query — OpenAlex and Crossref cover almost every paper with a DOI.
+
+## Stack
+
+Python 3.12+, `uv`-managed. Typer (CLI) + httpx (sync HTTP) + stdlib `sqlite3` (cache) + rich + environs + platformdirs + pytest + pytest-httpx. No GUI, no ORM, no async.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install quelle
+```
+
+Run the one-time bootstrap to create the config, data, and cache directories and seed a default `.env`:
+
+```bash
+quelle init
+quelle config edit        # opens the .env in your $EDITOR
+```
+
+### Development from a source checkout
+
+```bash
+git clone https://github.com/vcoeur/quelle.git
+cd quelle
+make dev-install          # uv sync --all-groups
+make test                 # pytest
+make lint                 # ruff check + format --check
+make format               # ruff --fix + format
+uv run quelle --help      # run the CLI straight from the repo
+```
+
+When run from the repo, `quelle` picks up the `.env` at the repo root and stores dev cache / PDFs under a repo-local `.dev-state/` instead of polluting your installed user data.
+
+## Configuration
+
+`quelle` follows each OS's standard "config dir + data dir + cache dir" layout via [`platformdirs`](https://platformdirs.readthedocs.io/):
+
+| Role | Linux (XDG) | macOS | Windows |
+|---|---|---|---|
+| Config (`.env`) | `~/.config/quelle/` | `~/Library/Application Support/quelle/` | `%APPDATA%\quelle\` |
+| Data (downloaded PDFs) | `~/.local/share/quelle/` | `~/Library/Application Support/quelle/` | `%LOCALAPPDATA%\quelle\` |
+| Cache (sqlite index) | `~/.cache/quelle/` | `~/Library/Caches/quelle/` | `%LOCALAPPDATA%\quelle\Cache\` |
+
+Any of the three can be overridden via env vars — useful for tests, Docker, or custom deployments:
+
+```bash
+export QUELLE_CONFIG_DIR=/etc/quelle
+export QUELLE_DATA_DIR=/srv/quelle/data
+export QUELLE_CACHE_DIR=/var/cache/quelle
+```
+
+Inspect the resolved paths at any time:
+
+```bash
+quelle config path        # plain output, one path per line
+quelle config path --json # JSON, scriptable
+quelle config show        # all values including API keys (redacted)
+```
+
+The only variable worth setting by default is `QUELLE_CONTACT_EMAIL` — it goes into the `User-Agent` header and enrolls you in the Crossref / OpenAlex polite pool. See [`.env.example`](.env.example) for the full list.
+
+**Dev mode**: when you run `quelle` from a source checkout (`uv run quelle …` inside the repo), the `.env` at the repo root is still picked up — the same ergonomics as before — but downloaded PDFs and the cache go into a repo-local `.dev-state/` directory so your installed user data stays clean.
+
+**Migration from PublicationManager**: if you upgraded from the old `publication-manager` package, the first run of `quelle` automatically moves your `~/.config/publications/.env` and `~/.publications/.publications-state/` into the new locations. No data loss, no manual steps.
+
+## Usage
+
+```bash
+# Resolve by DOI (uses OpenAlex + Crossref enrichment by default).
+quelle fetch 10.1109/83.902291
+
+# Resolve by arXiv id, with PDF download into the data dir.
+quelle fetch 1706.03762 --download-pdf
+
+# Resolve by free-text title.
+quelle fetch "The Perceptron: A Probabilistic Model" --json
+
+# Bypass the local cache and force network.
+quelle fetch 10.xxxx/yyyy --no-cache
+
+# Inspect the cache.
+quelle cache stats
+quelle cache list --limit 20
+quelle cache show 10.1109/83.902291
+quelle cache clear --yes
+```
+
+## Claude Code skill
+
+A minimal example [`SKILL.md`](skills/quelle/SKILL.md) ships in `skills/quelle/` — drop it into `~/.claude/skills/quelle/` (or `<project>/.claude/skills/quelle/`) to use the CLI from a Claude Code session. It's deliberately thin: resolve the paper, print the metadata, stop. Adapt the last step for your own downstream workflow (Zettelkasten import, BibTeX append, etc.).
+
+## Layout
+
+```
+quelle/
+  models/        <- Publication, Author (pure dataclasses)
+  repositories/
+    cache.py           <- SQLite cache keyed by DOI / arXiv / title
+    errors.py          <- Error hierarchy -> exit codes 1/2/3/4
+    http_client.py     <- httpx + polite User-Agent
+    pdf_downloader.py  <- Streaming PDF download with content-type + size checks
+    sources/           <- One module per source: openalex, crossref, semantic_scholar, arxiv, unpaywall
+  services/
+    resolver.py         <- Source orchestration + enrichment chain + cache lookup
+    pdf_resolver.py     <- Lazy PDF fallback chain
+  cli/
+    main.py             <- Typer app (fetch, cache, version, init)
+    config.py           <- `config show` / `path` / `edit` + bootstrap
+    output.py           <- JSON vs rich TTY rendering
+  paths.py              <- platformdirs resolution (config / data / cache)
+  migrate.py            <- One-shot migration from the legacy PublicationManager layout
+  settings.py           <- environs-layered config
+tests/
+```
+
+Layer rules: imports only go downward. Models import nothing from this project. Repositories import models. Services import models + repositories. CLI is the wiring layer.
+
+## Status
+
+v0.1 — all five open-API sources wired up with a merge-logic enrichment chain, a SQLite cache keyed by DOI / arXiv id / OpenAlex id / title (second query for the same paper is offline), and a PDF download chain with OpenAlex → arXiv → Unpaywall fallback plus content-type and size validation.
+
+## Usage and terms
+
+This tool is intended for **personal and academic research use**. It queries free, public APIs on your behalf. **You are responsible for complying with each upstream's terms of service** — the MIT licence on this repo covers the *code* of this tool, not the data you fetch through it.
+
+**Not supported use cases**:
+
+- **Bulk scraping** / batch ingestion of many records. Most upstreams publish free database snapshots; use those instead of hammering the live API.
+- **Rehosting downloaded PDFs** on a public server. The `--download-pdf` flag writes to a local cache on your machine — that is fine. Re-serving arXiv PDFs, publisher PDFs, or full text from your own infrastructure is not (see arXiv and Semantic Scholar rows below).
+- **Commercial repackaging** of the JSON output as a paid product. Individual commercial use of the metadata is generally allowed by the underlying licences, but Semantic Scholar in particular requires attribution and some S2 records are `CC BY-NC`.
+
+**Per-source summary**:
+
+| Source | Data licence | Rate limit | Attribution | Notes |
+|---|---|---|---|---|
+| [OpenAlex](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication) | CC0 — *"OpenAlex data is and will remain available at no cost"* | ~100k / day on the polite pool; single-entity lookups unlimited | not required | Provide an email via `QUELLE_CONTACT_EMAIL` for the polite pool, or set `OPENALEX_API_KEY` for the new key-based tier (OpenAlex announced in January 2026 that key authentication is replacing the mailto polite pool; the tool supports both). |
+| [Crossref REST](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) | CC0 for metadata — *"almost none of the metadata is subject to copyright, and you may use it for any purpose"*. Some abstracts may remain copyrighted. | No hard cap; the polite pool is requested via your `mailto=` / User-Agent | not required, but recommended | Commercial users who need SLAs should subscribe to Metadata Plus directly with Crossref. |
+| [arXiv API](https://info.arxiv.org/help/api/tou.html) | Metadata CC0. PDFs retain their authors' / arXiv's licence. | **1 request / 3 seconds** (the tool enforces this globally via a module-level lock) | Do not claim arXiv endorses your project. | **You may not store and re-serve arXiv e-prints (PDFs, source files, other content) from your own servers unless you have the copyright holder's permission.** Downloading for local personal reading is explicitly allowed. |
+| [Semantic Scholar](https://www.semanticscholar.org/product/api/license) | S2 data may be `CC BY-NC` or `ODC-BY` depending on the record. The API itself is provided *"AS IS, WITH ALL FAULTS, AND AS AVAILABLE"* with no warranty. | Public endpoints need no auth; higher throughput requires a free key from Ai2. | **Required** — *"Licensee will include an attribution to 'Semantic Scholar'"*, and publications must cite *The Semantic Scholar Open Data Platform*. | You may not *"repackage, sell, rent, lease, lend, distribute, or sublicense the API"*. This tool is a personal client, not a proxy. |
+| [Unpaywall](https://unpaywall.org/products/api) | CC0 data | 100k requests / day | not required | The email parameter is **mandatory** — Unpaywall uses it to contact you if something goes wrong. Don't fake it. For bulk workloads, download the free data snapshot instead of hammering the API. |
+
+**Google Scholar is not supported.** Google Scholar has no official API, and Google's Terms of Service prohibit automated access. Passing a Scholar URL to `quelle fetch` returns a `UserError` asking you to copy the paper title manually and retry — OpenAlex and Crossref together cover almost every paper with a DOI, so the workaround is usually one extra copy-paste.
+
+**No warranty**: see the MIT [`LICENSE`](LICENSE) — this tool is provided as-is, with no guarantee that its JSON output is correct, complete, or current. Verify critical metadata against the canonical upstream before relying on it.
+
+## Licence
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Questions or feedback
+
+This is a personal tool — I'm happy to hear from you, but there is no formal support. The best way to reach me is the contact form on [vcoeur.com](https://vcoeur.com).

quelle-0.1.0/README.md

@@ -0,0 +1,172 @@
+# quelle
+
+`quelle` is a local CLI that fetches academic publication metadata and PDFs from open academic sources (OpenAlex, Crossref, Semantic Scholar, arXiv, Unpaywall) and returns them as normalised JSON. Designed as a composable building block — feed the output into any note-taking system, reference manager, or research workflow.
+
+The name is German for *source* — in academic German, "Quelle:" is the word that introduces a bibliographic reference, and fetching from open sources is exactly what the tool does.
+
+## What it does
+
+Given a publication identifier or a free-text title, `quelle fetch` returns a normalised JSON blob with title, authors, year, venue, DOI, abstract, citation count and (optionally) a downloaded local PDF. It walks a fallback chain of free open sources:
+
+| Source | Role | Rate limit |
+|---|---|---|
+| [OpenAlex](https://docs.openalex.org/) | Primary metadata + OA PDF URL | $1/day on free key |
+| [Crossref](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) | DOI-authoritative fallback (abstract, journal block) | polite pool (no hard cap) |
+| [Semantic Scholar](https://api.semanticscholar.org/) | Citation graph + metadata fallback | 5000 / 5 min unauth |
+| [arXiv](https://info.arxiv.org/help/api/) | Preprint metadata + direct PDFs | 1 req / 3s (enforced) |
+| [Unpaywall](https://unpaywall.org/products/api) | DOI → OA PDF lookup | 100k / day |
+
+Google Scholar URLs are **not supported**: Scholar has no public API and its Terms of Service prohibit automated access. If you only have a Scholar link, open the page, copy the paper title, and feed that to `quelle fetch` as a free-text query — OpenAlex and Crossref cover almost every paper with a DOI.
+
+## Stack
+
+Python 3.12+, `uv`-managed. Typer (CLI) + httpx (sync HTTP) + stdlib `sqlite3` (cache) + rich + environs + platformdirs + pytest + pytest-httpx. No GUI, no ORM, no async.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install quelle
+```
+
+Run the one-time bootstrap to create the config, data, and cache directories and seed a default `.env`:
+
+```bash
+quelle init
+quelle config edit        # opens the .env in your $EDITOR
+```
+
+### Development from a source checkout
+
+```bash
+git clone https://github.com/vcoeur/quelle.git
+cd quelle
+make dev-install          # uv sync --all-groups
+make test                 # pytest
+make lint                 # ruff check + format --check
+make format               # ruff --fix + format
+uv run quelle --help      # run the CLI straight from the repo
+```
+
+When run from the repo, `quelle` picks up the `.env` at the repo root and stores dev cache / PDFs under a repo-local `.dev-state/` instead of polluting your installed user data.
+
+## Configuration
+
+`quelle` follows each OS's standard "config dir + data dir + cache dir" layout via [`platformdirs`](https://platformdirs.readthedocs.io/):
+
+| Role | Linux (XDG) | macOS | Windows |
+|---|---|---|---|
+| Config (`.env`) | `~/.config/quelle/` | `~/Library/Application Support/quelle/` | `%APPDATA%\quelle\` |
+| Data (downloaded PDFs) | `~/.local/share/quelle/` | `~/Library/Application Support/quelle/` | `%LOCALAPPDATA%\quelle\` |
+| Cache (sqlite index) | `~/.cache/quelle/` | `~/Library/Caches/quelle/` | `%LOCALAPPDATA%\quelle\Cache\` |
+
+Any of the three can be overridden via env vars — useful for tests, Docker, or custom deployments:
+
+```bash
+export QUELLE_CONFIG_DIR=/etc/quelle
+export QUELLE_DATA_DIR=/srv/quelle/data
+export QUELLE_CACHE_DIR=/var/cache/quelle
+```
+
+Inspect the resolved paths at any time:
+
+```bash
+quelle config path        # plain output, one path per line
+quelle config path --json # JSON, scriptable
+quelle config show        # all values including API keys (redacted)
+```
+
+The only variable worth setting by default is `QUELLE_CONTACT_EMAIL` — it goes into the `User-Agent` header and enrolls you in the Crossref / OpenAlex polite pool. See [`.env.example`](.env.example) for the full list.
+
+**Dev mode**: when you run `quelle` from a source checkout (`uv run quelle …` inside the repo), the `.env` at the repo root is still picked up — the same ergonomics as before — but downloaded PDFs and the cache go into a repo-local `.dev-state/` directory so your installed user data stays clean.
+
+**Migration from PublicationManager**: if you upgraded from the old `publication-manager` package, the first run of `quelle` automatically moves your `~/.config/publications/.env` and `~/.publications/.publications-state/` into the new locations. No data loss, no manual steps.
+
+## Usage
+
+```bash
+# Resolve by DOI (uses OpenAlex + Crossref enrichment by default).
+quelle fetch 10.1109/83.902291
+
+# Resolve by arXiv id, with PDF download into the data dir.
+quelle fetch 1706.03762 --download-pdf
+
+# Resolve by free-text title.
+quelle fetch "The Perceptron: A Probabilistic Model" --json
+
+# Bypass the local cache and force network.
+quelle fetch 10.xxxx/yyyy --no-cache
+
+# Inspect the cache.
+quelle cache stats
+quelle cache list --limit 20
+quelle cache show 10.1109/83.902291
+quelle cache clear --yes
+```
+
+## Claude Code skill
+
+A minimal example [`SKILL.md`](skills/quelle/SKILL.md) ships in `skills/quelle/` — drop it into `~/.claude/skills/quelle/` (or `<project>/.claude/skills/quelle/`) to use the CLI from a Claude Code session. It's deliberately thin: resolve the paper, print the metadata, stop. Adapt the last step for your own downstream workflow (Zettelkasten import, BibTeX append, etc.).
+
+## Layout
+
+```
+quelle/
+  models/        <- Publication, Author (pure dataclasses)
+  repositories/
+    cache.py           <- SQLite cache keyed by DOI / arXiv / title
+    errors.py          <- Error hierarchy -> exit codes 1/2/3/4
+    http_client.py     <- httpx + polite User-Agent
+    pdf_downloader.py  <- Streaming PDF download with content-type + size checks
+    sources/           <- One module per source: openalex, crossref, semantic_scholar, arxiv, unpaywall
+  services/
+    resolver.py         <- Source orchestration + enrichment chain + cache lookup
+    pdf_resolver.py     <- Lazy PDF fallback chain
+  cli/
+    main.py             <- Typer app (fetch, cache, version, init)
+    config.py           <- `config show` / `path` / `edit` + bootstrap
+    output.py           <- JSON vs rich TTY rendering
+  paths.py              <- platformdirs resolution (config / data / cache)
+  migrate.py            <- One-shot migration from the legacy PublicationManager layout
+  settings.py           <- environs-layered config
+tests/
+```
+
+Layer rules: imports only go downward. Models import nothing from this project. Repositories import models. Services import models + repositories. CLI is the wiring layer.
+
+## Status
+
+v0.1 — all five open-API sources wired up with a merge-logic enrichment chain, a SQLite cache keyed by DOI / arXiv id / OpenAlex id / title (second query for the same paper is offline), and a PDF download chain with OpenAlex → arXiv → Unpaywall fallback plus content-type and size validation.
+
+## Usage and terms
+
+This tool is intended for **personal and academic research use**. It queries free, public APIs on your behalf. **You are responsible for complying with each upstream's terms of service** — the MIT licence on this repo covers the *code* of this tool, not the data you fetch through it.
+
+**Not supported use cases**:
+
+- **Bulk scraping** / batch ingestion of many records. Most upstreams publish free database snapshots; use those instead of hammering the live API.
+- **Rehosting downloaded PDFs** on a public server. The `--download-pdf` flag writes to a local cache on your machine — that is fine. Re-serving arXiv PDFs, publisher PDFs, or full text from your own infrastructure is not (see arXiv and Semantic Scholar rows below).
+- **Commercial repackaging** of the JSON output as a paid product. Individual commercial use of the metadata is generally allowed by the underlying licences, but Semantic Scholar in particular requires attribution and some S2 records are `CC BY-NC`.
+
+**Per-source summary**:
+
+| Source | Data licence | Rate limit | Attribution | Notes |
+|---|---|---|---|---|
+| [OpenAlex](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication) | CC0 — *"OpenAlex data is and will remain available at no cost"* | ~100k / day on the polite pool; single-entity lookups unlimited | not required | Provide an email via `QUELLE_CONTACT_EMAIL` for the polite pool, or set `OPENALEX_API_KEY` for the new key-based tier (OpenAlex announced in January 2026 that key authentication is replacing the mailto polite pool; the tool supports both). |
+| [Crossref REST](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) | CC0 for metadata — *"almost none of the metadata is subject to copyright, and you may use it for any purpose"*. Some abstracts may remain copyrighted. | No hard cap; the polite pool is requested via your `mailto=` / User-Agent | not required, but recommended | Commercial users who need SLAs should subscribe to Metadata Plus directly with Crossref. |
+| [arXiv API](https://info.arxiv.org/help/api/tou.html) | Metadata CC0. PDFs retain their authors' / arXiv's licence. | **1 request / 3 seconds** (the tool enforces this globally via a module-level lock) | Do not claim arXiv endorses your project. | **You may not store and re-serve arXiv e-prints (PDFs, source files, other content) from your own servers unless you have the copyright holder's permission.** Downloading for local personal reading is explicitly allowed. |
+| [Semantic Scholar](https://www.semanticscholar.org/product/api/license) | S2 data may be `CC BY-NC` or `ODC-BY` depending on the record. The API itself is provided *"AS IS, WITH ALL FAULTS, AND AS AVAILABLE"* with no warranty. | Public endpoints need no auth; higher throughput requires a free key from Ai2. | **Required** — *"Licensee will include an attribution to 'Semantic Scholar'"*, and publications must cite *The Semantic Scholar Open Data Platform*. | You may not *"repackage, sell, rent, lease, lend, distribute, or sublicense the API"*. This tool is a personal client, not a proxy. |
+| [Unpaywall](https://unpaywall.org/products/api) | CC0 data | 100k requests / day | not required | The email parameter is **mandatory** — Unpaywall uses it to contact you if something goes wrong. Don't fake it. For bulk workloads, download the free data snapshot instead of hammering the API. |
+
+**Google Scholar is not supported.** Google Scholar has no official API, and Google's Terms of Service prohibit automated access. Passing a Scholar URL to `quelle fetch` returns a `UserError` asking you to copy the paper title manually and retry — OpenAlex and Crossref together cover almost every paper with a DOI, so the workaround is usually one extra copy-paste.
+
+**No warranty**: see the MIT [`LICENSE`](LICENSE) — this tool is provided as-is, with no guarantee that its JSON output is correct, complete, or current. Verify critical metadata against the canonical upstream before relying on it.
+
+## Licence
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Questions or feedback
+
+This is a personal tool — I'm happy to hear from you, but there is no formal support. The best way to reach me is the contact form on [vcoeur.com](https://vcoeur.com).