feat: add DOAJ local mode backed by user-provided CSV snapshot (#1094)

* feat: add DOAJ local mode backed by user-provided CSV snapshot

When DOAJ_MODE=local, DOAJLocalBackend queries a SQLite cache
populated from a DOAJ CSV file placed in .aletheia-probe/doaj/.
Remote mode (default) is unchanged — HTTP API is used as before.

Key changes:
- New DOAJSource(DataSource) reads journalcsv__doaj_*.csv and feeds
  the updater framework; 'aletheia-probe sync doaj' always works
  regardless of DOAJ_MODE
- DOAJLocalBackend(ConfiguredCachedBackend) is always registered so
  sync capability is always present; query() delegates to DOAJBackend
  (HTTP) in remote mode and to the SQLite journal cache in local mode
- Add "doaj": "DOAJ_MODE" to RUNTIME_MODE_ENV_BY_BACKEND so
  'aletheia-probe status' shows mode=local/remote
- docs/local-doaj-backend.md: setup guide + note on matching
  differences vs remote mode

* fix: cast super().query() return to BackendResult to satisfy mypy

---------

Co-authored-by: florath-ai-assistant[bot] <Andreas.Florath@telekom.de>

Author: coding-ai-assistant[bot]

docs/local-doaj-backend.md

@@ -0,0 +1,126 @@
+# Local DOAJ Backend
+
+By default, `aletheia-probe` checks journal legitimacy against the
+[DOAJ (Directory of Open Access Journals)](https://doaj.org/) REST API.
+The **local mode** lets you run entirely offline using a CSV snapshot
+downloaded directly from DOAJ — no network calls, no rate limiting.
+
+---
+
+## Step 1 — Download the DOAJ CSV
+
+1. Go to <https://doaj.org/docs/public-data-dump/>
+2. Click **"Download journals CSV"**.  No login is required.
+3. The downloaded file will be named something like:
+
+   ```
+   journalcsv__doaj_20260314_1626_utf8.csv
+   ```
+
+> **Note:** Use the CSV export (not the JSON bulk-download).
+
+---
+
+## Step 2 — Place the file
+
+Create the directory `.aletheia-probe/doaj/` **inside your working directory**
+(the directory from which you run `aletheia-probe`) and copy the file there:
+
+```bash
+mkdir -p .aletheia-probe/doaj/
+cp ~/Downloads/journalcsv__doaj_*.csv .aletheia-probe/doaj/
+```
+
+If multiple files matching `journalcsv__doaj_*.csv` are present, the most
+recently modified one is used.
+
+---
+
+## Step 3 — Sync the local cache
+
+```bash
+aletheia-probe sync doaj
+```
+
+This reads the CSV and writes the journal records into the local SQLite
+database.  Re-running sync within 30 days of the last update is a no-op
+unless `--force` is passed.
+
+---
+
+## Step 4 — Enable local mode
+
+Set the environment variable `DOAJ_MODE=local` before running any
+`aletheia-probe` command:
+
+```bash
+export DOAJ_MODE=local
+aletheia-probe assess "Nature"
+```
+
+Or inline for a single run:
+
+```bash
+DOAJ_MODE=local aletheia-probe mass-eval --input papers.bib
+```
+
+---
+
+## Verifying the setup
+
+```bash
+DOAJ_MODE=local aletheia-probe status
+```
+
+The DOAJ line should show `mode=local` together with the entry count and
+last-updated date:
+
+```
+✅ doaj (enabled, cached, mode=local) 📊 has data (22,672 entries) (updated: 2026-03-14)
+```
+
+---
+
+## Keeping the data fresh
+
+DOAJ publishes updated snapshots regularly.  To refresh:
+
+1. Download the latest CSV from <https://doaj.org/docs/public-data-dump/>.
+2. Replace the file in `.aletheia-probe/doaj/`.
+3. Run `aletheia-probe sync doaj --force`.
+
+---
+
+## Differences from remote mode
+
+Local mode is **not** a 1:1 replacement for the remote DOAJ API.  There are
+two notable differences:
+
+**Coverage** — The CSV contains only journals that DOAJ has accepted as fully
+open access.  The remote API may return results for journals that are in
+DOAJ's index but not yet reflected in the most recently downloaded CSV
+snapshot.  Conversely, journals removed from DOAJ since the snapshot was
+taken will still appear in the local cache until the next sync.
+
+**Matching strategy** — The remote API performs server-side fuzzy/full-text
+search and may return approximate matches for journal names it cannot find
+exactly (for example, matching "Nature" against "Nature-Nurture Journal of
+Psychology").  The local mode uses exact name and ISSN matching only, so
+it will not return such approximate hits.  This makes local mode
+**more precise** but means it may return `not_found` for queries where the
+remote API would have returned a low-confidence fuzzy match.
+
+In practice, for well-formed journal names or ISSNs the two modes produce
+identical results.  Discrepancies are a sign that the remote API result was
+a false positive, or that the local snapshot is out of date.
+
+---
+
+## Switching back to remote mode
+
+Remove or unset `DOAJ_MODE` (or set it to `remote`) to use the live DOAJ API:
+
+```bash
+unset DOAJ_MODE
+aletheia-probe assess "Nature"
+```

src/aletheia_probe/backends/doaj.py

@@ -1,7 +1,8 @@
 # SPDX-License-Identifier: MIT
 """DOAJ (Directory of Open Access Journals) backend for legitimate journal verification."""
 
-from typing import Any
+import os
+from typing import Any, cast
 from urllib.parse import quote
 
 import aiohttp
@@ -25,8 +26,9 @@
     VenueType,
 )
 from ..retry_utils import async_retry_with_backoff
+from ..updater.sources.doaj import DOAJSource
 from ..utils.dead_code import code_is_used
-from .base import ApiBackendWithCache, get_backend_registry
+from .base import ApiBackendWithCache, ConfiguredCachedBackend, get_backend_registry
 from .fallback_mixin import FallbackStrategyMixin
 
 
@@ -358,9 +360,48 @@ def _build_not_found_result_with_chain(
         )
 
 
+class DOAJLocalBackend(ConfiguredCachedBackend):
+    """DOAJ backend registered in the backend registry.
+
+    Always registered so that ``aletheia-probe sync doaj`` works regardless of
+    ``DOAJ_MODE``.  At query time the mode is checked:
+
+    - ``DOAJ_MODE=local``   → query the local SQLite cache (populated by sync)
+    - ``DOAJ_MODE=remote`` (default) → delegate to :class:`DOAJBackend` (HTTP API)
+
+    The CSV file for local mode must be placed in ``.aletheia-probe/doaj/`` in
+    the current working directory and imported via ``aletheia-probe sync doaj``.
+    """
+
+    def __init__(self, remote_cache_ttl_hours: int = 24) -> None:
+        super().__init__(
+            backend_name="doaj",
+            list_type=AssessmentType.LEGITIMATE,
+            evidence_type=EvidenceType.LEGITIMATE_LIST,
+            cache_ttl_hours=24 * 30,  # Monthly cache for static file
+            data_source_factory=lambda: DOAJSource(),
+        )
+        self._remote_cache_ttl_hours = remote_cache_ttl_hours
+        self._remote_backend: DOAJBackend | None = None
+
+    def _get_remote_backend(self) -> DOAJBackend:
+        if self._remote_backend is None:
+            self._remote_backend = DOAJBackend(
+                cache_ttl_hours=self._remote_cache_ttl_hours
+            )
+        return self._remote_backend
+
+    async def query(self, query_input: QueryInput) -> BackendResult:
+        """Query local cache when DOAJ_MODE=local, otherwise use HTTP API."""
+        mode = os.environ.get("DOAJ_MODE", "remote").strip().lower()
+        if mode == "local":
+            return cast(BackendResult, await super().query(query_input))
+        return await self._get_remote_backend().query(query_input)
+
+
 # Register the backend with factory for configuration support
 get_backend_registry().register_factory(
     "doaj",
-    lambda cache_ttl_hours=24: DOAJBackend(cache_ttl_hours=cache_ttl_hours),
+    lambda cache_ttl_hours=24: DOAJLocalBackend(remote_cache_ttl_hours=cache_ttl_hours),
     default_config={"cache_ttl_hours": 24},
 )

src/aletheia_probe/cli_commands/system_commands.py

@@ -11,6 +11,7 @@
 
 
 RUNTIME_MODE_ENV_BY_BACKEND: dict[str, str] = {
+    "doaj": "DOAJ_MODE",
     "openalex_analyzer": "OPENALEX_MODE",
     "opencitations_analyzer": "OPENCITATIONS_MODE",
 }

src/aletheia_probe/updater/sources/__init__.py

@@ -6,6 +6,7 @@
 from .core import CoreConferenceSource, CoreJournalSource
 from .custom import CustomListSource
 from .dblp import DblpVenueSource
+from .doaj import DOAJSource
 from .kscien_generic import KscienGenericSource
 from .kscien_hijacked_journals import KscienHijackedJournalsSource
 from .kscien_publishers import KscienPublishersSource
@@ -30,6 +31,7 @@
     "CoreConferenceSource",
     "CoreJournalSource",
     "DblpVenueSource",
+    "DOAJSource",
     "KscienGenericSource",
     "KscienHijackedJournalsSource",
     "KscienPublishersSource",