flonat-research 0.1.0

package/.mcp-server-biblio/sources/base.py

@@ -0,0 +1,73 @@
+"""Abstract base class for scholarly data sources."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from sources.models import Paper
+
+
+class ScholarlySource(ABC):
+    """Abstract interface for bibliometric data providers.
+
+    Implement this for each data source (OpenAlex, Scopus, Web of Science).
+    All methods are async to support concurrent API calls.
+    """
+
+    @property
+    @abstractmethod
+    def source_name(self) -> str:
+        """Human-readable name of this data source."""
+        ...
+
+    @property
+    @abstractmethod
+    def source_key(self) -> str:
+        """Machine-readable slug for this source (e.g. 'openalex', 'scopus', 'wos')."""
+        ...
+
+    @abstractmethod
+    async def search_works(
+        self,
+        query: str,
+        *,
+        year_from: int | None = None,
+        year_to: int | None = None,
+        sort_by: str = "relevance",
+        limit: int = 50,
+    ) -> list[Paper]:
+        """Search for works matching a text query."""
+        ...
+
+    @abstractmethod
+    async def verify_doi(self, doi: str) -> Paper | None:
+        """Look up a single DOI and return metadata, or None if not found."""
+        ...
+
+    @abstractmethod
+    async def batch_verify_dois(self, dois: list[str]) -> dict[str, Paper | None]:
+        """Verify multiple DOIs at once. Returns {doi: Paper or None}."""
+        ...
+
+    @abstractmethod
+    async def find_similar_works(
+        self,
+        text: str,
+        *,
+        limit: int = 20,
+    ) -> list[Paper]:
+        """Find works most similar to a given text (title or abstract)."""
+        ...
+
+    async def close(self) -> None:
+        """Release any network/session resources held by the source."""
+        return None
+
+    def reset_diagnostics(self) -> None:
+        """Reset per-request diagnostics collected by the source."""
+        return None
+
+    def consume_diagnostics(self) -> dict[str, Any] | None:
+        """Return and clear diagnostics for the current request context."""
+        return None

package/.mcp-server-biblio/sources/formatters.py

@@ -0,0 +1,83 @@
+"""Markdown formatters for multi-source scholarly results."""
+
+from __future__ import annotations
+
+from sources.models import Paper
+
+
+def format_papers_table(papers: list[Paper], title: str = "Results") -> str:
+    """Format a list of Papers as a markdown table."""
+    if not papers:
+        return f"## {title}\n\nNo results found."
+
+    lines = [f"## {title}\n"]
+    lines.append("| # | Title | Authors | Year | Cited | Source | DOI |")
+    lines.append("|---|-------|---------|------|-------|--------|-----|")
+
+    for i, p in enumerate(papers, 1):
+        authors = ", ".join(p.authors[:3])
+        if len(p.authors) > 3:
+            authors += " et al."
+        title_short = p.title[:80] + "..." if len(p.title) > 80 else p.title
+        doi_link = f"[link]({p.doi})" if p.doi else "—"
+        source = p.source_name or "—"
+        if len(source) > 30:
+            source = source[:27] + "..."
+
+        lines.append(
+            f"| {i} | {title_short} | {authors} | {p.publication_year} | "
+            f"{p.cited_by_count:,} | {source} | {doi_link} |"
+        )
+
+    return "\n".join(lines)
+
+
+def format_verification_table(results: dict[str, Paper | None]) -> str:
+    """Format DOI verification results as a markdown table."""
+    lines = ["## DOI Verification Results\n"]
+    lines.append("| # | DOI | Title | Year | Cited By | Verified By | Status |")
+    lines.append("|---|-----|-------|------|----------|-------------|--------|")
+
+    verified_count = 0
+    single_count = 0
+    not_found_count = 0
+
+    for i, (doi, paper) in enumerate(results.items(), 1):
+        if paper is None:
+            status = "NOT FOUND"
+            not_found_count += 1
+            lines.append(f"| {i} | `{doi}` | — | — | — | — | ❌ {status} |")
+        else:
+            sources = ", ".join(paper.verified_by)
+            if len(paper.verified_by) >= 2:
+                status = "VERIFIED"
+                verified_count += 1
+            else:
+                status = "SINGLE SOURCE"
+                single_count += 1
+            title_short = paper.title[:60] + "..." if len(paper.title) > 60 else paper.title
+            lines.append(
+                f"| {i} | `{doi}` | {title_short} | {paper.publication_year} | "
+                f"{paper.cited_by_count:,} | {sources} | "
+                f"{'✅' if status == 'VERIFIED' else '⚠️'} {status} |"
+            )
+
+    lines.append("")
+    lines.append(f"**Summary:** {verified_count} verified (2+ sources), "
+                 f"{single_count} single-source, {not_found_count} not found")
+
+    return "\n".join(lines)
+
+
+def format_source_status(sources: list[dict]) -> str:
+    """Format source status as a markdown table."""
+    lines = ["## Scholarly Source Status\n"]
+    lines.append("| Source | Status | Key |")
+    lines.append("|--------|--------|-----|")
+
+    for s in sources:
+        status = "✅ Active" if s["active"] else "❌ Not configured"
+        key = s.get("key", "—")
+        lines.append(f"| {s['name']} | {status} | `{key}` |")
+
+    return "\n".join(lines)

package/.mcp-server-biblio/sources/models.py

@@ -0,0 +1,22 @@
+"""Paper dataclass for multi-source scholarly search."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Paper:
+    """Unified paper representation across all sources."""
+
+    source_id: str
+    title: str
+    authors: list[str]
+    publication_year: int
+    cited_by_count: int
+    doi: str | None
+    abstract: str | None = None
+    source_name: str | None = None  # journal / venue
+    keywords: list[str] = field(default_factory=list)
+    url: str | None = None
+    verified_by: list[str] = field(default_factory=list)  # which sources confirmed this DOI

package/.mcp-server-biblio/sources/multi_source.py

@@ -0,0 +1,243 @@
+"""Multi-source composite adapter with DOI-based deduplication.
+
+Queries all enabled sources concurrently and merges results.
+Ported from ZZ Topic Finder with improvements.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from contextvars import ContextVar
+from typing import Any
+
+from sources.base import ScholarlySource
+from sources.models import Paper
+
+logger = logging.getLogger(__name__)
+
+
+class MultiSource(ScholarlySource):
+    """Composite data source that queries multiple APIs and deduplicates results.
+
+    All methods query sources concurrently. Failed sources are skipped gracefully.
+    Papers are deduplicated by normalized DOI; papers without DOIs are kept as-is.
+    """
+
+    def __init__(self, sources: list[ScholarlySource]) -> None:
+        if not sources:
+            raise ValueError("MultiSource requires at least one source")
+        self._sources = sources
+        self._diagnostics_ctx: ContextVar[dict[str, Any] | None] = ContextVar(
+            f"multi_source_diagnostics_{id(self)}", default=None
+        )
+
+    @property
+    def source_name(self) -> str:
+        names = [s.source_name for s in self._sources]
+        return " + ".join(names)
+
+    @property
+    def source_key(self) -> str:
+        return "multi"
+
+    def reset_diagnostics(self) -> None:
+        self._diagnostics_ctx.set(
+            {
+                "attempted": [s.source_name for s in self._sources],
+                "failed": set(),
+                "warnings": [],
+            }
+        )
+
+    def consume_diagnostics(self) -> dict[str, Any] | None:
+        diag = self._diagnostics_ctx.get()
+        if diag is None:
+            return None
+
+        attempted = list(diag["attempted"])
+        failed = sorted(diag["failed"])
+        succeeded = [name for name in attempted if name not in failed]
+        warnings = list(diag["warnings"])
+        self._diagnostics_ctx.set(None)
+        return {
+            "attempted": attempted,
+            "succeeded": succeeded,
+            "failed": failed,
+            "warnings": warnings,
+        }
+
+    async def search_works(
+        self,
+        query: str,
+        *,
+        year_from: int | None = None,
+        year_to: int | None = None,
+        sort_by: str = "relevance",
+        limit: int = 50,
+    ) -> list[Paper]:
+        coros = [
+            s.search_works(query, year_from=year_from, year_to=year_to, sort_by=sort_by, limit=limit)
+            for s in self._sources
+        ]
+        all_papers = await self._gather_flat(coros)
+        deduped = deduplicate_papers(all_papers)
+
+        if sort_by == "cited_by_count":
+            deduped.sort(key=lambda p: p.cited_by_count, reverse=True)
+        elif sort_by == "publication_year":
+            deduped.sort(key=lambda p: p.publication_year, reverse=True)
+
+        return deduped[:limit]
+
+    async def verify_doi(self, doi: str) -> Paper | None:
+        coros = [s.verify_doi(doi) for s in self._sources]
+        results = await asyncio.gather(*coros, return_exceptions=True)
+
+        papers = []
+        verified_by: list[str] = []
+        for i, result in enumerate(results):
+            if isinstance(result, BaseException):
+                logger.debug("Source %s failed DOI verify: %s", self._sources[i].source_name, result)
+                continue
+            if result is not None:
+                papers.append(result)
+                verified_by.append(self._sources[i].source_key)
+
+        if not papers:
+            return None
+
+        # Merge all found papers into one
+        merged = papers[0]
+        for p in papers[1:]:
+            merged = _merge_papers(merged, p)
+        merged.verified_by = verified_by
+        return merged
+
+    async def batch_verify_dois(self, dois: list[str]) -> dict[str, Paper | None]:
+        coros = [s.batch_verify_dois(dois) for s in self._sources]
+        results = await asyncio.gather(*coros, return_exceptions=True)
+
+        # Merge results from all sources
+        merged: dict[str, Paper | None] = {d: None for d in dois}
+
+        for i, result in enumerate(results):
+            if isinstance(result, BaseException):
+                logger.warning("Source %s failed batch verify: %s", self._sources[i].source_name, result)
+                continue
+
+            for doi, paper in result.items():
+                if paper is None:
+                    continue
+                if merged[doi] is None:
+                    merged[doi] = paper
+                    merged[doi].verified_by = [self._sources[i].source_key]
+                else:
+                    merged[doi] = _merge_papers(merged[doi], paper)
+                    if self._sources[i].source_key not in merged[doi].verified_by:
+                        merged[doi].verified_by.append(self._sources[i].source_key)
+
+        return merged
+
+    async def find_similar_works(
+        self,
+        text: str,
+        *,
+        limit: int = 20,
+    ) -> list[Paper]:
+        coros = [s.find_similar_works(text, limit=limit) for s in self._sources]
+        all_papers = await self._gather_flat(coros)
+        return deduplicate_papers(all_papers)[:limit]
+
+    async def close(self) -> None:
+        for s in self._sources:
+            try:
+                await s.close()
+            except Exception:
+                pass
+
+    async def _gather_flat(self, coros: list) -> list:
+        """Run coroutines concurrently, flatten results, skip failures."""
+        diag = self._diagnostics_ctx.get()
+        results = await asyncio.gather(*coros, return_exceptions=True)
+        flat: list = []
+        for i, result in enumerate(results):
+            if isinstance(result, BaseException):
+                source_name = self._sources[i].source_name
+                logger.warning("Source %s failed: %s", source_name, result)
+                if diag is not None:
+                    diag["failed"].add(source_name)
+                    diag["warnings"].append(f"{source_name} failed: {result}")
+                continue
+            flat.extend(result)
+        return flat
+
+
+# ---------------------------------------------------------------------------
+# Deduplication
+# ---------------------------------------------------------------------------
+
+_DOI_PATTERN = re.compile(r"10\.\d{4,}/[^\s]+", re.IGNORECASE)
+
+
+def _normalize_doi(doi: str | None) -> str | None:
+    """Extract and normalize a DOI string for comparison."""
+    if not doi:
+        return None
+    match = _DOI_PATTERN.search(doi)
+    if not match:
+        return None
+    return match.group(0).lower().rstrip(".")
+
+
+def deduplicate_papers(papers: list[Paper]) -> list[Paper]:
+    """Deduplicate papers by normalized DOI.
+
+    For duplicates: keep the longest abstract, max citation count, union keywords.
+    Papers without DOIs are kept as-is.
+    """
+    by_doi: dict[str, Paper] = {}
+    no_doi: list[Paper] = []
+
+    for p in papers:
+        ndoi = _normalize_doi(p.doi)
+        if ndoi is None:
+            no_doi.append(p)
+            continue
+
+        if ndoi not in by_doi:
+            by_doi[ndoi] = p
+        else:
+            existing = by_doi[ndoi]
+            by_doi[ndoi] = _merge_papers(existing, p)
+
+    return list(by_doi.values()) + no_doi
+
+
+def _merge_papers(a: Paper, b: Paper) -> Paper:
+    """Merge two Paper records representing the same work."""
+    # Pick the longer abstract
+    abstract = a.abstract
+    if b.abstract and (not abstract or len(b.abstract) > len(abstract)):
+        abstract = b.abstract
+
+    # Union keywords, preserving order
+    keywords = list(dict.fromkeys(a.keywords + b.keywords))
+
+    # Union verified_by
+    verified_by = list(dict.fromkeys(a.verified_by + b.verified_by))
+
+    return Paper(
+        source_id=a.source_id,
+        title=a.title or b.title,
+        abstract=abstract,
+        authors=a.authors or b.authors,
+        publication_year=a.publication_year or b.publication_year,
+        cited_by_count=max(a.cited_by_count, b.cited_by_count),
+        source_name=a.source_name or b.source_name,
+        doi=a.doi or b.doi,
+        keywords=keywords,
+        url=a.url or b.url,
+        verified_by=verified_by,
+    )

package/.mcp-server-biblio/sources/openalex_source.py

@@ -0,0 +1,183 @@
+"""OpenAlex adapter wrapping the shared client from .scripts/openalex/."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+from sources.base import ScholarlySource
+from sources.models import Paper
+
+logger = logging.getLogger(__name__)
+
+# Import the shared OpenAlex client
+SCRIPTS_DIR = str(Path(__file__).parent.parent.parent / ".scripts" / "openalex")
+if SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, SCRIPTS_DIR)
+
+from openalex_client import OpenAlexClient  # noqa: E402
+
+
+class OpenAlexSource(ScholarlySource):
+    """OpenAlex implementation using the shared client.
+
+    Always available (no API key needed). Uses polite pool with email.
+    """
+
+    def __init__(self, client: OpenAlexClient) -> None:
+        self._client = client
+
+    @property
+    def source_name(self) -> str:
+        return "OpenAlex"
+
+    @property
+    def source_key(self) -> str:
+        return "openalex"
+
+    async def search_works(
+        self,
+        query: str,
+        *,
+        year_from: int | None = None,
+        year_to: int | None = None,
+        sort_by: str = "relevance",
+        limit: int = 50,
+    ) -> list[Paper]:
+        filter_params: dict[str, str] = {}
+        if year_from and year_to:
+            filter_params["publication_year"] = f"{year_from}-{year_to}"
+        elif year_from:
+            filter_params["publication_year"] = f">{year_from - 1}"
+        elif year_to:
+            filter_params["publication_year"] = f"<{year_to + 1}"
+
+        sort_param = "cited_by_count:desc"
+        if sort_by == "relevance":
+            sort_param = "relevance_score:desc"
+        elif sort_by == "publication_year":
+            sort_param = "publication_date:desc"
+
+        def _search() -> dict[str, Any]:
+            return self._client.search_works(
+                search=query,
+                filter_params=filter_params if filter_params else None,
+                per_page=min(limit, 200),
+                sort=sort_param,
+            )
+
+        response = await asyncio.to_thread(_search)
+        works = response.get("results", [])
+        return [self._to_paper(w) for w in works[:limit]]
+
+    async def verify_doi(self, doi: str) -> Paper | None:
+        if not doi.startswith("https://doi.org/"):
+            doi = f"https://doi.org/{doi}"
+
+        try:
+            work = await asyncio.to_thread(self._client.get_entity, "works", doi)
+            if work and work.get("id"):
+                return self._to_paper(work)
+        except Exception:
+            logger.debug("OpenAlex DOI lookup failed for: %s", doi)
+        return None
+
+    async def batch_verify_dois(self, dois: list[str]) -> dict[str, Paper | None]:
+        # Normalize DOIs
+        normalized = []
+        for d in dois:
+            if not d.startswith("https://doi.org/"):
+                d = f"https://doi.org/{d}"
+            normalized.append(d)
+
+        results: dict[str, Paper | None] = {d: None for d in dois}
+
+        try:
+            works = await asyncio.to_thread(
+                self._client.batch_lookup, "works", normalized, "doi"
+            )
+            for w in works:
+                doi_val = w.get("doi", "")
+                if doi_val:
+                    # Match back to original DOI
+                    for orig in dois:
+                        norm_orig = orig if orig.startswith("https://doi.org/") else f"https://doi.org/{orig}"
+                        if doi_val.lower() == norm_orig.lower():
+                            results[orig] = self._to_paper(w)
+                            break
+        except Exception:
+            logger.warning("OpenAlex batch DOI lookup failed")
+
+        return results
+
+    async def find_similar_works(
+        self,
+        text: str,
+        *,
+        limit: int = 20,
+    ) -> list[Paper]:
+        return await self.search_works(text, sort_by="relevance", limit=limit)
+
+    @staticmethod
+    def _to_paper(work: dict[str, Any]) -> Paper:
+        """Convert OpenAlex work dict to Paper."""
+        # Authors
+        authors = []
+        for authorship in work.get("authorships", []):
+            author = authorship.get("author", {})
+            name = author.get("display_name", "")
+            if name:
+                authors.append(name)
+
+        # Keywords
+        keywords = []
+        for kw in work.get("keywords", []):
+            if isinstance(kw, dict):
+                keywords.append(kw.get("keyword", ""))
+            elif isinstance(kw, str):
+                keywords.append(kw)
+
+        # Abstract
+        abstract = None
+        inv_abstract = work.get("abstract_inverted_index")
+        if inv_abstract:
+            try:
+                word_positions = []
+                for word, positions in inv_abstract.items():
+                    for pos in positions:
+                        word_positions.append((pos, word))
+                word_positions.sort()
+                abstract = " ".join(w for _, w in word_positions)
+            except Exception:
+                pass
+
+        # DOI
+        doi = work.get("doi")
+        if doi and not doi.startswith("http"):
+            doi = f"https://doi.org/{doi}"
+
+        # Publication year
+        pub_year = work.get("publication_year", 0) or 0
+
+        # Source / journal
+        source_name = None
+        primary_location = work.get("primary_location") or {}
+        source_info = primary_location.get("source") or {}
+        source_name = source_info.get("display_name")
+
+        return Paper(
+            source_id=f"openalex:{work.get('id', '')}",
+            title=work.get("title", "") or "",
+            abstract=abstract,
+            authors=authors,
+            publication_year=pub_year,
+            cited_by_count=work.get("cited_by_count", 0) or 0,
+            source_name=source_name,
+            doi=doi,
+            keywords=keywords,
+            url=doi or work.get("id", ""),
+            verified_by=["openalex"],
+        )