feat(sources): OpenAlex, SemanticScholar, arXiv API clients

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

codex/sources/openalex.py

@@ -0,0 +1,136 @@
+"""OpenAlex API client.
+
+Provides:
+- fetch_paper: resolve an arXiv ID or DOI to a Paper dataclass.
+- fetch_citations: retrieve reference list as Citation dataclasses.
+
+All requests use the OpenAlex Polite Pool (mailto query parameter) and
+are retried on 429/5xx with exponential back-off via tenacity.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential
+
+from codex.config import get_settings
+from codex.models import Citation, Paper
+
+logger = logging.getLogger(__name__)
+
+_BASE = "https://api.openalex.org"
+
+
+def _is_retryable(exc: BaseException) -> bool:
+    """Return True for HTTP 429 / 5xx responses wrapped in httpx.HTTPStatusError."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        return exc.response.status_code == 429 or exc.response.status_code >= 500
+    return False
+
+
+def _polite_params() -> dict[str, str]:
+    mailto = get_settings().openalex_mailto
+    if mailto:
+        return {"mailto": mailto}
+    return {}
+
+
+@retry(
+    retry=retry_if_exception(_is_retryable),
+    stop=stop_after_attempt(5),
+    wait=wait_exponential(min=1, max=30),
+    before_sleep=lambda rs: logger.warning(
+        "OpenAlex retry %d after %s",
+        rs.attempt_number,
+        rs.outcome.exception(),  # type: ignore[union-attr]
+    ),
+)
+def _get(url: str, params: dict[str, str] | None = None) -> httpx.Response:
+    merged: dict[str, str] = {**_polite_params(), **(params or {})}
+    response = httpx.get(url, params=merged, timeout=30)
+    response.raise_for_status()
+    return response
+
+
+def _reconstruct_abstract(inverted_index: dict[str, list[int]] | None) -> str | None:
+    """Convert OpenAlex abstract_inverted_index back to plain text."""
+    if not inverted_index:
+        return None
+    word_positions: list[tuple[int, str]] = []
+    for word, positions in inverted_index.items():
+        for pos in positions:
+            word_positions.append((pos, word))
+    word_positions.sort(key=lambda t: t[0])
+    return " ".join(w for _, w in word_positions)
+
+
+def _map_paper(data: dict[str, Any]) -> Paper:
+    authors: list[str] = [
+        a.get("author", {}).get("display_name") or "" for a in data.get("authorships", [])
+    ]
+    abstract = _reconstruct_abstract(data.get("abstract_inverted_index"))
+    return Paper(
+        id=data.get("doi") or data.get("id") or "",
+        title=data.get("title") or "",
+        openalex_id=data.get("id"),
+        authors=authors,
+        year=data.get("publication_year"),
+        abstract=abstract,
+    )
+
+
+def fetch_paper(id: str) -> Paper | None:
+    """Fetch a single paper by arXiv ID or DOI.
+
+    Parameters
+    ----------
+    id:
+        An arXiv ID (``"2301.07041"``) or a DOI (``"10.1145/…"``).
+
+    Returns
+    -------
+    Paper | None
+        A populated Paper instance, or None on 404.
+    """
+    url = f"{_BASE}/works/{id}"
+    try:
+        response = _get(url)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            logger.debug("OpenAlex 404 for id=%s", id)
+            return None
+        raise
+    return _map_paper(response.json())
+
+
+def fetch_citations(openalex_id: str) -> list[Citation]:
+    """Fetch the reference list for a paper as Citation objects.
+
+    Parameters
+    ----------
+    openalex_id:
+        The OpenAlex work ID (``"https://openalex.org/W…"`` or short ``"W…"``).
+
+    Returns
+    -------
+    list[Citation]
+        One Citation per referenced work.
+    """
+    url = f"{_BASE}/works/{openalex_id}/references"
+    try:
+        response = _get(url)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            return []
+        raise
+
+    results: list[dict[str, Any]] = response.json().get("results", [])
+    citations: list[Citation] = []
+    for ref in results:
+        cited_id: str = ref.get("doi") or ref.get("id") or ""
+        if cited_id:
+            citations.append(Citation(citing_id=openalex_id, cited_id=cited_id))
+    return citations