feat(fulltext): provider-neutral external resolver hook (opt-in, last resort)#10
Merged
Merged
Conversation
… resort)
Adds an optional extension point to matilde_fetch_fulltext: when
MATILDE_FULLTEXT_RESOLVER_URL (or a resolver_url arg) is set, an external
full-text resolver is consulted — but ONLY after every legal open-access
lookup (OpenAlex/Unpaywall/arXiv) has missed. A legal OA copy always wins,
so a configured resolver is never hit when an open-access copy exists.
The package ships no such service and names no provider. The operator
supplies one out of band against the contract:
GET {resolver_url}/resolve?doi=<doi> -> {"pdf_url": "..."}
Honesty by construction: a resolver hit sets is_oa=false and
source="external-resolver", and the tool message flags it as NOT open
access. The public repo stays open-access-only and provider-neutral; any
specific resolver (and its access/legal posture) lives entirely with the
operator who configures the URL. Unset => behaviour never engages.
Built test-first: 4 engine tests (used-on-miss, skipped-when-unset,
never-consulted-when-OA-exists, miss-falls-through) + 2 handler tests
(env forwarding, honest message). Full suite 93 passed, 6 skipped.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an optional, provider-neutral extension point to
matilde_fetch_fulltext. WhenMATILDE_FULLTEXT_RESOLVER_URL(or aresolver_urlarg) is set, an external full-text resolver is consulted — but only after every legal open-access lookup (OpenAlex/Unpaywall/arXiv) has missed. A legal OA copy always wins, so a configured resolver is never hit when an open-access copy exists.Why it's structured this way
This keeps the public, org-branded package open-access-only and provider-neutral: it ships no resolver service and names no provider. The operator supplies one out of band against a simple contract:
Any specific resolver — an institutional/library proxy, a licensed API, a self-hosted service — and its access/legal posture live entirely with whoever configures the URL, not with this repo.
Honesty by construction
A resolver hit sets
is_oa: falseandsource: "external-resolver", and the tool message flags it as NOT open access — confirm you have the right to access it. The tool never claims a non-OA source is open access. Unset the variable and the behaviour never engages (default off).Tests (TDD)
🤖 Generated with Claude Code