Aletheia Nexus

A local-first path from a verifiable research paper to durable scientific knowledge.

中文 README · User manual (Chinese) · Contributing · Security

Why this name? Aletheia is Greek for truth; Nexus means connection. We want evidence scattered across papers, data, tools, and research practice to form trustworthy connections—so conclusions can be traced to their sources and each investigation can add to a researcher's long-term knowledge.

Why this project exists

Research has increasingly capable models, but still lacks a dependable entry point for facts. A DOI can lead to the main article, supporting information, a login screen, a paywall, a citation, or a dead link. Finding a plausible PDF is not the same as acquiring the correct main article with an explainable provenance. Errors at this boundary propagate into parsers, search indexes, knowledge systems, and agents.

Aletheia Nexus (AN) begins with a deliberately testable question: Is this locally saved file the intended paper's main text, and how did it get here? It treats a failed acquisition as an informative result rather than quietly importing the wrong document. The larger ambition is a researcher-controlled, auditable scientific knowledge foundation that can eventually connect evidence, methods, workflows, and decisions. The current repository implements the acquisition layer, not that entire future system.

What works today

The first public code release was v0.6.0. v0.6.1 adds publisher adapters, an installed CLI, Windows CI, and PyPI packaging without changing the frozen v0.6.0 tag. See the release history for exact test and real-DOI evidence. First-time testing by independent users remains open; the three-minute onboarding target has not yet been independently established.

How it works

DOI → metadata and candidate sources → bounded acquisition
    → PDF structure and identity checks → main-text role check
    → VERIFIED file + provenance + hash, or an explicit non-success status

Every access route converges on the same document validation. The browser engine handles navigation, response/download capture, challenge observation, and handoff. Narrow publisher adapters handle known article URL patterns and visible page differences; they cannot declare an article verified. A browser that displays a PDF has not by itself completed acquisition.

Get started

Python 3.11 or newer is required. With the v0.6.1 PyPI release:

python -m pip install aletheia-nexus
aletheia-nexus doctor
aletheia-nexus acquire 10.1371/journal.pone.0310216 --public-only --output-dir downloads

The --public-only example does not require a browser and may legitimately report EXHAUSTED if no verified main article is publicly reachable. A quick local CLI smoke test is aletheia-nexus --help; a live DOI attempt depends on network services and access rights.

For the experimental authenticated browser path:

python -m pip install "aletheia-nexus[browser]"
python -m playwright install chromium
aletheia-nexus acquire papers.json --output-dir downloads/papers --fail-on-unverified

papers.json may contain DOI strings or objects with doi and optional title. TXT and CSV input are also supported. The installed aletheia-nexus acquire command replaces the old scripts/batch_v06_download.py invocation; that script remains as a compatibility wrapper. For all options, run aletheia-nexus acquire --help and consult the detailed manual.

Check the PyPI project for published versions; a GitHub source checkout or release alone does not prove that a PyPI upload succeeded. To try an unmerged development branch instead, clone the repository and run python -m pip install -e . from its root.

Result semantics

• VERIFIED: a validated main-article PDF exists locally with traceable acquisition evidence.
• INTERACTION_REQUIRED: the site needs human action; the program can wait and resume when the page becomes usable.
• ENTITLEMENT_REQUIRED: the current legitimate session has no full-text access, or the site asks for purchase.
• EXHAUSTED: configured routes and budgets were used without a verified main article. This does not mean the paper is nonexistent.

The output includes per-paper status, a batch report and checkpoint, and a .acquisition.json sidecar for verified PDFs. Only a file that still exists and matches its SHA-256 can be reused as verified on a later run. The tool does not provide publisher subscriptions, answer CAPTCHAs, or bypass paywalls.

Roadmap and participation

The next near-term priorities are to stabilize the acquisition architecture, make installation and first use straightforward across Windows/Linux, and obtain feedback from researchers who did not build the project. Later work will parse verified papers into source-linked objects, connect those objects to experimental context and research decisions, and expose auditable workflows to agents. These are directions, not current features.

If you are trying AN for the first time, please join the v0.6.1 first-time setup trial. A small report is especially valuable: which DOI, which legal access route, what status AN returned, and what you observed instead. Remove cookies, tokens, account details, institutional login screenshots, signed URLs, and copyrighted PDF bytes before opening an issue. See CONTRIBUTING.md and the issue templates.

The code is licensed under Apache-2.0. Third-party papers retain their own copyright and access terms; the project license does not authorize their redistribution.