replication-radar 0.4.2__tar.gz → 0.4.3__tar.gz

{replication_radar-0.4.2 → replication_radar-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: replication-radar
-Version: 0.4.2
+Version: 0.4.3
 Summary: MCP server that turns the OpenAIRE Graph into a ranked replication queue — impact-ranked targets and the Science Live verification overlay (retraction/supersession-aware).
 Project-URL: Homepage, https://github.com/ScienceLiveHub/replication-radar
 Project-URL: Repository, https://github.com/ScienceLiveHub/replication-radar
@@ -54,7 +54,7 @@ The Radar joins three sources to add a **replication layer** on top:
 | Tool | What it answers |
 |---|---|
 | `radar(topic)` | Impact-ranked replication targets in a field — each **OPEN** (opportunity) or **VERIFIED** (done, with verdict) + independent tooling + funder context |
-| `find_independent_software(doi, topic)` | Reusable engines **not authored by the original team** (author-disjoint = *replication*, not *reproduction*), ranked by reuse signal not citations |
+| `find_independent_software(doi, topic)` | Reusable engines **not authored by the original team** (author-disjoint = *replication*, not *reproduction*), ranked by reuse signal — repo · Software Heritage · downloads · **GitHub stars** — not citations (returns `stars` + `rank_score`) |
 | `replication_status(doi)` | Has this DOI been replicated, did it hold? Verdict(s) — **live from the nanopub network, any signer** — with status, CiTO relation, repo, and signed Outcome/CiTO nanopub links; `open` if not |
 | `verified_claims()` | The whole **verified-knowledge corpus** — every claim the network holds a verdict for (author-agnostic) |
 

{replication_radar-0.4.2 → replication_radar-0.4.3}/README.md

@@ -31,7 +31,7 @@ The Radar joins three sources to add a **replication layer** on top:
 | Tool | What it answers |
 |---|---|
 | `radar(topic)` | Impact-ranked replication targets in a field — each **OPEN** (opportunity) or **VERIFIED** (done, with verdict) + independent tooling + funder context |
-| `find_independent_software(doi, topic)` | Reusable engines **not authored by the original team** (author-disjoint = *replication*, not *reproduction*), ranked by reuse signal not citations |
+| `find_independent_software(doi, topic)` | Reusable engines **not authored by the original team** (author-disjoint = *replication*, not *reproduction*), ranked by reuse signal — repo · Software Heritage · downloads · **GitHub stars** — not citations (returns `stars` + `rank_score`) |
 | `replication_status(doi)` | Has this DOI been replicated, did it hold? Verdict(s) — **live from the nanopub network, any signer** — with status, CiTO relation, repo, and signed Outcome/CiTO nanopub links; `open` if not |
 | `verified_claims()` | The whole **verified-knowledge corpus** — every claim the network holds a verdict for (author-agnostic) |
 

{replication_radar-0.4.2 → replication_radar-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "replication-radar"
-version = "0.4.2"
+version = "0.4.3"
 description = "MCP server that turns the OpenAIRE Graph into a ranked replication queue — impact-ranked targets and the Science Live verification overlay (retraction/supersession-aware)."
 readme = "README.md"
 requires-python = ">=3.10"

{replication_radar-0.4.2 → replication_radar-0.4.3}/site/methodology.json

@@ -1,15 +1,15 @@
 {
   "title": "Replication Radar — methodology & data provenance",
   "summary": "Replication Radar joins three public, grounded sources into one view of a research field: the OpenAIRE Graph (what exists and how cited it is), the Science Live nanopublication network (whether a claim has been independently replicated and with what verdict), and FAIR-software signals (whether the replication's code is reusable). This document states, for every label and score in the interface, exactly where it comes from and how it is computed. It is served as JSON (this file) and rendered as a page at /methodology.html.",
-  "version": "0.3.2",
-  "updated": "2026-06-16",
+  "version": "0.4.3",
+  "updated": "2026-08-13",
   "license": "CC-BY-4.0",
   "sources": [
     { "id": "openaire", "name": "OpenAIRE Graph", "url": "https://graph.openaire.eu/", "api": "https://api.openaire.eu/graph/v1", "role": "Research products (papers, software, datasets), citation-impact indicators, open-access status, subject classification (FOS, SDG), and code/data links. Queried live from the browser; no key required." },
     { "id": "bip", "name": "BIP! citation indicators (via OpenAIRE)", "url": "https://bip.imsi.athenarc.gr/", "role": "The C1–C5 impact and impulse classes are BIP! indicators carried in the OpenAIRE record." },
     { "id": "sciencelive", "name": "Science Live nanopublication network", "url": "https://sciencelive4all.org", "api": "https://query.knowledgepixels.com/repo/full", "role": "FORRT replication chains as signed nanopublications: the Outcome (verdict), the Study (method), the Claim (what was tested) and CiTO citations to the original paper. Queried live via SPARQL; author-agnostic (any signer)." },
     { "id": "fairsoftware", "name": "fair-software.eu recommendations", "url": "https://fair-software.eu/", "role": "The five FAIR-for-research-software recommendations we score a replication's code against." },
-    { "id": "github", "name": "GitHub REST API", "url": "https://docs.github.com/rest", "role": "Repository existence, licence, citation file, release/quality signals, stars and forks for the FAIR-software check (unauthenticated, 60 requests/hour)." },
+    { "id": "github", "name": "GitHub REST API", "url": "https://docs.github.com/rest", "role": "Repository existence, licence, citation file, release/quality signals, and stars/forks — used both for the FAIR-software check and as the GitHub-star reuse signal in the reusable-software ranking (unauthenticated, 60 requests/hour; set GITHUB_TOKEN to raise the limit)." },
     { "id": "swh", "name": "Software Heritage API", "url": "https://archive.softwareheritage.org/api/", "role": "Whether the replication's code is archived in Software Heritage (long-term preservation), for the FAIR-software check." },
     { "id": "zenodo", "name": "Zenodo API", "url": "https://developers.zenodo.org/", "role": "Resolving a Zenodo deposit to its source GitHub repository and DOI when OpenAIRE lacks a direct code link." },
     { "id": "turingway", "name": "The Turing Way", "url": "https://the-turing-way.netlify.app/", "role": "A community handbook for reproducible, ethical and collaborative research — the language-agnostic reference behind the 'RSE practices' explanations (documentation, testing, continuous integration)." },
@@ -41,6 +41,8 @@
       "means": "Whether independent replications agree. Many-agree differs from disagree.", "computed": "From the verdict counts across all of a paper's outcomes — see the 'agreement' score below.", "limits": "Depends on how many replications exist; one confirmation is weaker evidence than several." },
     { "id": "fair", "name": "FAIR-software score (N/5)", "shownAs": "FAIR software N/5 + per-recommendation checks", "source": "fairsoftware",
       "means": "How reusable the replication's code is, on the five fair-software.eu recommendations: public repository, open licence, in a registry, citable (CITATION.cff / DOI), and quality artefacts.", "computed": "Computed live from the GitHub API (repository, licence, citation file, quality), Software Heritage (archival/registry) and Zenodo (DOI). One point per met recommendation. Only ever run on a replication we have a real repository URL for.", "limits": "GitHub unauthenticated rate limit is 60/hour; a check can be skipped if the limit is hit." },
+    { "id": "reusablesoftware", "name": "Reusable software for a field", "shownAs": "the reusable-software list (and the MCP find_independent_software tool)", "source": "openaire",
+      "means": "Software an RSE could pick up to replicate work in this field, restricted to engines NOT authored by the paper's own team (author-disjoint = replication, not reproduction).", "computed": "OpenAIRE type=software matching the field, filtered to author-disjoint records, ranked by the reusable-software score below (resolvable repository · Software Heritage · downloads · citations · GitHub stars), with the repository resolved via Zenodo when OpenAIRE omits it.", "limits": "Keyword recall is OpenAIRE's — a tool whose record doesn't contain the search terms won't appear (e.g. a narrow topic can miss an established tool); the field's software may be thin or dominated by one-off study deposits." },
     { "id": "gap", "name": "The replication-gap map", "shownAs": "the composition bar at the top", "source": "sciencelive",
       "means": "How much of the matched high-impact work has actually been independently checked — the rest is the replication gap.", "computed": "A composition of the ranked list by status (reproducible / validated / contested / needs check / dormant).", "limits": "Reflects the current search and the current network coverage." }
   ],
@@ -53,7 +55,10 @@
       "explanation": "Each outcome is one signed nanopublication; records without a signed outcome are not counted." },
     { "id": "fair", "name": "FAIR-software score",
       "formula": "1 point for each met recommendation, out of 5: public repository · open licence · in a registry · citable (CITATION.cff or DOI) · quality artefacts.",
-      "explanation": "fair-software.eu's five recommendations, evaluated from live GitHub / Software Heritage / Zenodo signals." }
+      "explanation": "fair-software.eu's five recommendations, evaluated from live GitHub / Software Heritage / Zenodo signals." },
+    { "id": "softwarereuse", "name": "Reusable-software ranking",
+      "formula": "In the web app: a quality composite a one-off deposit can't fake — the FAIR-software score (0–5) + the count of RSE good-practice signals (0–5) + a GitHub-star bonus = min(3, log10(stars+1)·1.6) − 1.5 if the software needs a proprietary/paid runtime, plus 0.4×the OpenAIRE reuse signal and +0.5 if Software Heritage archived. In the MCP find_independent_software tool (no per-repo FAIR assessment): a resolvable code repository (+2) + Software Heritage (+2) + has downloads (+1) + has citations (+1) + the same GitHub-star bonus. Both rank author-disjoint software only.",
+      "explanation": "Citation class is useless for research software (nearly everything is C5 / 0-citation), so software is ranked by grounded REUSE signals instead. GitHub stars are the signal that separates an established, widely-used tool from a one-off study deposit — read from the repo, falling back to the Zenodo→GitHub link when OpenAIRE omits the repo URL, and capped on a log scale so a handful of very-starred repos can't dominate. A star lookup that is rate-limited or unreachable falls back to the other signals, never a guess. GitHub's unauthenticated rate limit is 60/hour; set GITHUB_TOKEN to raise it." }
   ],
   "practices": [
     { "id": "documented", "name": "Documented",

{replication_radar-0.4.2 → replication_radar-0.4.3}/src/replication_radar/__init__.py

@@ -7,4 +7,4 @@ OpenAIRE impact + Software Heritage reuse signals + Science Live nanopub verdict
 from .radar import radar, find_independent_software, replication_status, verified_claims
 
 __all__ = ["radar", "find_independent_software", "replication_status", "verified_claims"]
-__version__ = "0.4.2"
+__version__ = "0.4.3"

replication_radar-0.4.3/src/replication_radar/github.py

@@ -0,0 +1,98 @@
+"""GitHub + Zenodo helpers so reusable-software ranking reflects real reuse (stars),
+not just OpenAIRE metadata.
+
+Why: OpenAIRE's software records are uniformly low-citation and often omit the code
+repository URL, so a one-off study repo can look as "reusable" as an established tool.
+GitHub stars are the missing signal — the web app already ranks its software lens with
+them; this brings the MCP in line.
+
+Resolution mirrors the web app: prefer OpenAIRE's codeRepositoryUrl, else the Zenodo
+record's related_identifiers (many Zenodo-published tools omit the repo URL in OpenAIRE —
+e.g. XMHW). Stars come from the GitHub REST API (unauth 60/hr; set GITHUB_TOKEN to lift to
+5000/hr). Every lookup is cached and BEST-EFFORT — a failed/rate-limited call returns None
+and the caller falls back to the OpenAIRE-only signal, so results stay grounded and never
+crash. Stdlib only.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import urllib.request
+
+_TIMEOUT = float(os.environ.get("RADAR_HTTP_TIMEOUT", "30"))
+_TOKEN = os.environ.get("GITHUB_TOKEN") or os.environ.get("RADAR_GITHUB_TOKEN")
+_stars_cache: dict[str, int | None] = {}
+_zenodo_repo_cache: dict[str, str | None] = {}
+
+
+def _parse(url: str | None) -> tuple[str, str] | None:
+    m = re.search(r"github\.com/([^/]+)/([^/#?]+)", url or "", re.I)
+    return (m.group(1), m.group(2).replace(".git", "")) if m else None
+
+
+def _get_json(url: str, headers: dict) -> dict | None:
+    try:
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=_TIMEOUT) as r:
+            return json.load(r)
+    except Exception:
+        return None
+
+
+def _github_from_zenodo(doi: str | None) -> str | None:
+    m = re.search(r"zenodo\.(\d+)", doi or "", re.I)
+    if not m:
+        return None
+    key = m.group(1)
+    if key in _zenodo_repo_cache:
+        return _zenodo_repo_cache[key]
+    found = None
+    d = _get_json(
+        f"https://zenodo.org/api/records/{key}",
+        {"Accept": "application/json", "User-Agent": "replication-radar"},
+    )
+    for rel in ((d or {}).get("metadata") or {}).get("related_identifiers") or []:
+        ident = rel.get("identifier") or ""
+        if "github.com" in ident:
+            found = ident
+            break
+    _zenodo_repo_cache[key] = found
+    return found
+
+
+def resolve_repo(code_repo: str | None, doi: str | None = None) -> str | None:
+    """Normalised ``https://github.com/owner/repo`` for this software, or None.
+
+    Prefers OpenAIRE's ``codeRepositoryUrl``; falls back to the Zenodo record's
+    ``related_identifiers`` (many Zenodo-published tools omit the repo URL in OpenAIRE)."""
+    g = _parse(code_repo) or _parse(_github_from_zenodo(doi))
+    return f"https://github.com/{g[0]}/{g[1]}" if g else None
+
+
+def stars(repo_url: str | None) -> int | None:
+    """GitHub stargazers for a repo URL (cached); None if unknown/unreachable/rate-limited.
+
+    Set ``GITHUB_TOKEN`` (or ``RADAR_GITHUB_TOKEN``) to lift the 60/hr unauth limit to 5000/hr."""
+    g = _parse(repo_url)
+    if not g:
+        return None
+    key = f"{g[0]}/{g[1]}".lower()
+    if key in _stars_cache:
+        return _stars_cache[key]
+    headers = {"Accept": "application/vnd.github+json", "User-Agent": "replication-radar"}
+    if _TOKEN:
+        headers["Authorization"] = f"Bearer {_TOKEN}"
+    d = _get_json(f"https://api.github.com/repos/{g[0]}/{g[1]}", headers)
+    val = int(d["stargazers_count"]) if d and "stargazers_count" in d else None
+    _stars_cache[key] = val
+    return val
+
+
+def star_bonus(n: int | None) -> float:
+    """Bounded log-scale star contribution to a reuse score, mirroring the web app
+    (``min(3, log10(stars+1) * 1.6)``): 0 stars → 0; ~10 → 1.7; ~30 → 2.4; ≥250 → 3.0."""
+    if not n or n <= 0:
+        return 0.0
+    return min(3.0, math.log10(n + 1) * 1.6)

{replication_radar-0.4.2 → replication_radar-0.4.3}/src/replication_radar/radar.py

@@ -11,7 +11,7 @@ Three capabilities (exposed as MCP tools in server.py):
 """
 from __future__ import annotations
 
-from . import openaire, verdicts
+from . import github, openaire, verdicts
 
 # impact class -> 0..1 (C1 best). Used in the readiness score.
 _CLASS_SCORE = {"C1": 1.0, "C2": 0.8, "C3": 0.6, "C4": 0.4, "C5": 0.2, None: 0.2}
@@ -89,6 +89,21 @@ def verified_claims() -> dict:
     return {"count": len(claims), "claims": claims}
 
 
+_SW_POOL = 100        # software candidates to fetch (established tools are often relevance-buried)
+_RESOLVE_CAP = 40     # max GitHub/Zenodo lookups per call (cached; set GITHUB_TOKEN for headroom)
+
+
+def _sw_rank_score(p, repo: str | None, stars: int | None) -> float:
+    """Reuse score used to RANK software: the OpenAIRE signal plus a bounded GitHub-star bonus.
+    Uses the resolved `repo` (so a Zenodo-linked tool OpenAIRE omitted still gets repo credit)."""
+    s = 0.0
+    if repo:                 s += 2   # a real, resolvable code repository
+    if p.swh_archived:       s += 2   # Software Heritage archived
+    if p.downloads > 0:      s += 1
+    if p.citation_count > 0: s += 1
+    return s + github.star_bonus(stars)   # stars separate established tools from one-off study repos
+
+
 def find_independent_software(
     doi: str | None = None,
     topic: str | None = None,
@@ -109,7 +124,9 @@ def find_independent_software(
         # derive a short topic from the title's leading words
         topic = " ".join((paper.title if paper else "").split()[:3]) or "software"
 
-    pool = openaire.search_products(topic, "software", size=25)
+    # Wide pool: established tools are often relevance-buried in OpenAIRE's software index
+    # (e.g. XMHW ranks ~60th for "marine heatwave"), so a small pool never sees them.
+    pool = openaire.search_products(topic, "software", size=_SW_POOL)
     rows = []
     for p in pool:
         rows.append(
@@ -118,14 +135,32 @@ def find_independent_software(
                 "doi": p.doi,
                 "authors": p.authors,
                 "independent": _independence(original_authors, p.authors),
-                "reuse_score": p.reuse_score,
+                "reuse_score": p.reuse_score,      # OpenAIRE-only signal (kept for transparency)
                 "code_repo": p.code_repo,
                 "swh_archived": p.swh_archived,
                 "downloads": p.downloads,
+                "stars": None,
+                "_p": p,
             }
         )
-    # independent first, then most-reusable
-    rows.sort(key=lambda r: (not r["independent"], -r["reuse_score"]))
+    # Resolve GitHub stars for the independent candidates (bounded + cached, best-effort).
+    # Stars are the missing reuse signal: without them a 0-star one-off study repo ranks like
+    # an established, widely-used tool. Resolve highest OpenAIRE-signal first so the budget is
+    # spent well; the Zenodo fallback recovers repos OpenAIRE omits (that is how XMHW resolves).
+    resolvable = [
+        r for r in rows
+        if r["independent"] and (r["code_repo"] or "zenodo" in (r["doi"] or "").lower())
+    ]
+    resolvable.sort(key=lambda r: (-r["reuse_score"], -r["downloads"]))
+    for r in resolvable[:_RESOLVE_CAP]:
+        repo = github.resolve_repo(r["code_repo"], r["doi"])
+        if repo:
+            r["code_repo"] = repo
+            r["stars"] = github.stars(repo)
+    for r in rows:
+        r["rank_score"] = round(_sw_rank_score(r.pop("_p"), r["code_repo"], r["stars"]), 2)
+    # independent first, then real (stars-augmented) reuse, then downloads
+    rows.sort(key=lambda r: (not r["independent"], -r["rank_score"], -r["downloads"]))
     return {
         "query_topic": topic,
         "original_authors": original_authors,

{replication_radar-0.4.2 → replication_radar-0.4.3}/src/replication_radar/server.py

@@ -40,9 +40,12 @@ def radar(topic: str, limit: int = 8) -> dict:
 @mcp.tool()
 def find_independent_software(doi: str = "", topic: str = "", limit: int = 8) -> dict:
     """Reusable method software for *replicating* a claim — engines NOT authored by
-    the original paper's team (author-disjoint), ranked by reuse signal (code repo +
-    Software Heritage archival + usage), not citations. Pass the original paper's DOI
-    (authors are looked up) and a short topic."""
+    the original paper's team (author-disjoint), ranked by reuse signal — a resolvable
+    code repository + Software Heritage archival + downloads + GitHub stars (the signal
+    that separates an established tool from a one-off study repo) — not citations. Each
+    result carries its `stars` and `rank_score`. Pass the original paper's DOI (authors
+    are looked up) and a short topic; keep the topic broad (a narrow one can miss an
+    established tool whose OpenAIRE record doesn't contain the extra words)."""
     return _find_software(doi=doi or None, topic=topic or None, limit=limit)