search-paper 0.1.1__tar.gz

search_paper-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Soroush
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

search_paper-0.1.1/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: search-paper
+Version: 0.1.1
+Summary: CLI for academic paper search across 9 APIs (OpenAlex, Semantic Scholar, PubMed, arXiv, medRxiv, CrossRef, Google Scholar, ORCID, Unpaywall)
+License-Expression: MIT
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: requests>=2.34.2
+Requires-Dist: scholarly>=1.7.11
+Dynamic: license-file
+
+# search-paper
+
+Single-command CLI for academic paper search across 9 APIs. 25 tools, no API keys.
+
+Based on [`alisoroushmd/academic-research-mcp`](https://github.com/alisoroushmd/academic-research-mcp) (MIT).
+
+## Install
+
+```bash
+uv tool install search-paper
+```
+
+## Usage
+
+```shell
+search-paper -t smart_search -a '{"query":"deep learning","num_results":5}'
+search-paper -t find_paper -a '{"identifier":"10.1038/nature14539"}'
+search-paper -t search_papers -a '{"query":"cancer","source":"pubmed","num_results":3}'
+search-paper -L  # list all 25 tools
+```
+
+## License
+
+MIT
+
+## Credits
+
+All API client modules, orchestrator, cache, and review manager are from [`alisoroushmd/academic-research-mcp`](https://github.com/alisoroushmd/academic-research-mcp) (MIT), repackaged as a standalone CLI.

search_paper-0.1.1/README.md

@@ -0,0 +1,28 @@
+# search-paper
+
+Single-command CLI for academic paper search across 9 APIs. 25 tools, no API keys.
+
+Based on [`alisoroushmd/academic-research-mcp`](https://github.com/alisoroushmd/academic-research-mcp) (MIT).
+
+## Install
+
+```bash
+uv tool install search-paper
+```
+
+## Usage
+
+```shell
+search-paper -t smart_search -a '{"query":"deep learning","num_results":5}'
+search-paper -t find_paper -a '{"identifier":"10.1038/nature14539"}'
+search-paper -t search_papers -a '{"query":"cancer","source":"pubmed","num_results":3}'
+search-paper -L  # list all 25 tools
+```
+
+## License
+
+MIT
+
+## Credits
+
+All API client modules, orchestrator, cache, and review manager are from [`alisoroushmd/academic-research-mcp`](https://github.com/alisoroushmd/academic-research-mcp) (MIT), repackaged as a standalone CLI.

search_paper-0.1.1/arxiv_client.py

@@ -0,0 +1,267 @@
+"""
+arXiv API client.
+
+Uses the arXiv API (https://info.arxiv.org/help/api/index.html).
+Free, no authentication required. Returns structured metadata including
+abstracts, authors, categories, PDF links, and version history.
+
+Rate limit: 1 request per 3 seconds (enforced by the client).
+"""
+
+import re
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+import defusedxml.ElementTree as ET
+
+import cache
+import http_client
+
+ARXIV_API_BASE = "https://export.arxiv.org/api/query"
+ATOM_NS = "{http://www.w3.org/2005/Atom}"
+OPENSEARCH_NS = "{http://a9.com/-/spec/opensearch/1.1/}"
+ARXIV_NS = "{http://arxiv.org/schemas/atom}"
+
+# Throttle to respect arXiv rate limits (thread-safe)
+_last_request_time = 0
+_throttle_lock = threading.Lock()
+
+
+def _throttle():
+    global _last_request_time
+    with _throttle_lock:
+        now = time.time()
+        elapsed = now - _last_request_time
+        if elapsed < 3.0:
+            time.sleep(3.0 - elapsed)
+        _last_request_time = time.time()
+
+
+@cache.cached(category="search", ttl=cache.SEARCH_TTL)
+def search_arxiv(
+    query: str,
+    num_results: int = 10,
+    sort_by: str = "relevance",
+    category: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Search arXiv for papers.
+
+    Parameters:
+        query (str): Search query. Supports arXiv search syntax:
+            - Simple keywords: "computational pathology"
+            - Author: "au:Campanella"
+            - Title: "ti:foundation model endoscopy"
+            - Abstract: "abs:gastric intestinal metaplasia"
+            - Category: "cat:cs.CV"
+            - Combine with AND, OR, ANDNOT
+        num_results (int): Max results (default: 10, max: 100).
+        sort_by (str): "relevance", "lastUpdatedDate", or "submittedDate".
+        category (str): Filter by arXiv category (e.g., "cs.CV", "cs.AI",
+            "eess.IV", "q-bio.QM"). If provided, combined with query via AND.
+
+    Returns:
+        List of paper dicts.
+    """
+    search_query = query
+    if category:
+        search_query = f"({query}) AND cat:{category}"
+
+    sort_map = {
+        "relevance": "relevance",
+        "lastUpdatedDate": "lastUpdatedDate",
+        "submittedDate": "submittedDate",
+    }
+
+    params = {
+        "search_query": f"all:{search_query}" if " " in query and not any(
+            prefix in query for prefix in ["au:", "ti:", "abs:", "cat:", "AND", "OR"]
+        ) else search_query,
+        "start": 0,
+        "max_results": min(num_results, 100),
+        "sortBy": sort_map.get(sort_by, "relevance"),
+        "sortOrder": "descending",
+    }
+
+    _throttle()
+    resp = http_client.get(ARXIV_API_BASE, params=params, timeout=30)
+    resp.raise_for_status()
+
+    return _parse_feed(resp.text)
+
+
+@cache.cached(category="paper", ttl=cache.PAPER_TTL)
+def get_arxiv_paper(arxiv_id: str) -> Dict[str, Any]:
+    """
+    Get details for a specific arXiv paper by ID.
+
+    Parameters:
+        arxiv_id (str): arXiv ID (e.g., "2312.00567" or "2312.00567v2").
+            Also accepts full URLs like "https://arxiv.org/abs/2312.00567".
+
+    Returns:
+        Paper dict with full metadata.
+    """
+    # Extract ID from URL if needed
+    arxiv_id = _clean_arxiv_id(arxiv_id)
+
+    params = {
+        "id_list": arxiv_id,
+        "max_results": 1,
+    }
+
+    _throttle()
+    resp = http_client.get(ARXIV_API_BASE, params=params, timeout=30)
+    resp.raise_for_status()
+
+    papers = _parse_feed(resp.text)
+    if papers:
+        return papers[0]
+    return {"error": f"Paper not found: {arxiv_id}"}
+
+
+@cache.cached(category="search", ttl=cache.SEARCH_TTL)
+def get_arxiv_by_author(
+    author_name: str, num_results: int = 10, category: Optional[str] = None
+) -> List[Dict[str, Any]]:
+    """
+    Get papers by a specific author.
+
+    Parameters:
+        author_name (str): Author name (e.g., "Campanella, Gabriele").
+        num_results (int): Max results.
+        category (str): Optional category filter.
+
+    Returns:
+        List of paper dicts sorted by submission date (newest first).
+    """
+    query = f'au:"{author_name}"'
+    if category:
+        query = f'{query} AND cat:{category}'
+
+    params = {
+        "search_query": query,
+        "start": 0,
+        "max_results": min(num_results, 100),
+        "sortBy": "submittedDate",
+        "sortOrder": "descending",
+    }
+
+    _throttle()
+    resp = http_client.get(ARXIV_API_BASE, params=params, timeout=30)
+    resp.raise_for_status()
+
+    return _parse_feed(resp.text)
+
+
+# --- Parsing helpers ---
+
+def _parse_feed(xml_text: str) -> List[Dict[str, Any]]:
+    """Parse an arXiv Atom feed into a list of paper dicts."""
+    root = ET.fromstring(xml_text)
+    papers = []
+
+    for entry in root.findall(f"{ATOM_NS}entry"):
+        paper = _parse_entry(entry)
+        if paper.get("title"):
+            papers.append(paper)
+
+    return papers
+
+
+def _parse_entry(entry) -> Dict[str, Any]:
+    """Parse a single Atom entry into a paper dict."""
+    # Title (clean whitespace)
+    title_el = entry.find(f"{ATOM_NS}title")
+    title = _clean_text(title_el.text) if title_el is not None and title_el.text else ""
+
+    # Abstract
+    summary_el = entry.find(f"{ATOM_NS}summary")
+    abstract = _clean_text(summary_el.text) if summary_el is not None and summary_el.text else ""
+
+    # Authors
+    authors = []
+    for author_el in entry.findall(f"{ATOM_NS}author"):
+        name_el = author_el.find(f"{ATOM_NS}name")
+        if name_el is not None and name_el.text:
+            authors.append(name_el.text.strip())
+
+    # arXiv ID and URLs
+    id_el = entry.find(f"{ATOM_NS}id")
+    arxiv_url = id_el.text.strip() if id_el is not None and id_el.text else ""
+    arxiv_id = _clean_arxiv_id(arxiv_url)
+
+    # PDF link
+    pdf_url = ""
+    for link_el in entry.findall(f"{ATOM_NS}link"):
+        if link_el.get("title") == "pdf":
+            pdf_url = link_el.get("href", "")
+
+    # Dates
+    published_el = entry.find(f"{ATOM_NS}published")
+    published = published_el.text.strip()[:10] if published_el is not None and published_el.text else ""
+
+    updated_el = entry.find(f"{ATOM_NS}updated")
+    updated = updated_el.text.strip()[:10] if updated_el is not None and updated_el.text else ""
+
+    # Categories
+    categories = []
+    primary_category_el = entry.find(f"{ARXIV_NS}primary_category")
+    primary_category = ""
+    if primary_category_el is not None:
+        primary_category = primary_category_el.get("term", "")
+
+    for cat_el in entry.findall(f"{ATOM_NS}category"):
+        term = cat_el.get("term", "")
+        if term:
+            categories.append(term)
+
+    # DOI (if available)
+    doi_el = entry.find(f"{ARXIV_NS}doi")
+    doi = doi_el.text.strip() if doi_el is not None and doi_el.text else ""
+
+    # Journal reference
+    journal_ref_el = entry.find(f"{ARXIV_NS}journal_ref")
+    journal_ref = journal_ref_el.text.strip() if journal_ref_el is not None and journal_ref_el.text else ""
+
+    # Comment (often contains page count, conference info)
+    comment_el = entry.find(f"{ARXIV_NS}comment")
+    comment = comment_el.text.strip() if comment_el is not None and comment_el.text else ""
+
+    return {
+        "arxiv_id": arxiv_id,
+        "title": title,
+        "authors": authors,
+        "abstract": abstract,
+        "published": published,
+        "updated": updated,
+        "primary_category": primary_category,
+        "categories": categories,
+        "doi": doi,
+        "journal_ref": journal_ref,
+        "comment": comment,
+        "arxiv_url": f"https://arxiv.org/abs/{arxiv_id}",
+        "pdf_url": pdf_url or f"https://arxiv.org/pdf/{arxiv_id}",
+    }
+
+
+def _clean_arxiv_id(text: str) -> str:
+    """Extract a clean arXiv ID from a URL or ID string."""
+    text = text.strip()
+    # Match patterns like 2312.00567 or 2312.00567v2
+    match = re.search(r'(\d{4}\.\d{4,5}(?:v\d+)?)', text)
+    if match:
+        return match.group(1)
+    # Older format like cs/0601001
+    match = re.search(r'([a-z-]+/\d{7}(?:v\d+)?)', text)
+    if match:
+        return match.group(1)
+    return text
+
+
+def _clean_text(text: str) -> str:
+    """Clean whitespace from arXiv text fields."""
+    if not text:
+        return ""
+    return " ".join(text.split())

search_paper-0.1.1/cache.py

@@ -0,0 +1,268 @@
+"""
+Local SQLite cache for academic research API responses.
+
+Caches paper metadata, search results, and author profiles to avoid
+redundant API calls. Papers that appear across multiple searches
+(landmark studies, your own work, frequently cited references) are
+fetched once and served from cache thereafter.
+
+Cache is stored at ~/.cache/academic-research-mcp/cache.db by default.
+Set ACADEMIC_CACHE_DIR to override.
+"""
+
+import functools
+import hashlib
+import json
+import logging
+import os
+import time
+from typing import Any, Dict, Optional
+
+import db as _db
+
+logger = logging.getLogger(__name__)
+
+# Re-export the shared lock so any legacy references still work.
+_lock = _db._lock
+
+# Default TTL: 24 hours for search results, 7 days for paper details
+SEARCH_TTL = 24 * 60 * 60  # 24 hours
+PAPER_TTL = 7 * 24 * 60 * 60  # 7 days
+AUTHOR_TTL = 3 * 24 * 60 * 60  # 3 days
+
+# Guard so the table DDL only runs once per process.
+_tables_created = False
+
+
+def _ensure_cache_table() -> None:
+    """Create the cache table and index if they don't yet exist."""
+    global _tables_created
+    if _tables_created:
+        return
+    conn = _db.get_db()
+    with _lock:
+        if _tables_created:
+            return
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS cache (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL,
+                category TEXT NOT NULL,
+                created_at REAL NOT NULL,
+                ttl REAL NOT NULL
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_cache_category
+            ON cache(category)
+        """)
+        conn.commit()
+        _tables_created = True
+
+
+def make_key(prefix: str, *args, **kwargs) -> str:
+    """Generate a deterministic cache key from function arguments."""
+    raw = json.dumps({"prefix": prefix, "args": args, "kwargs": kwargs}, sort_keys=True)
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def get(key: str) -> Optional[Any]:
+    """
+    Get a value from cache if it exists and hasn't expired.
+
+    Parameters:
+        key: Cache key.
+
+    Returns:
+        Cached value or None if not found/expired.
+    """
+    try:
+        _ensure_cache_table()
+        conn = _db.get_db()
+        with _lock:
+            cursor = conn.execute(
+                "SELECT value, created_at, ttl FROM cache WHERE key = ?",
+                (key,),
+            )
+            row = cursor.fetchone()
+
+        if row is None:
+            return None
+
+        value, created_at, ttl = row
+        if time.time() - created_at > ttl:
+            _delete(key)
+            return None
+
+        return json.loads(value)
+    except Exception:
+        logger.debug("Cache get failed for key %s", key[:16], exc_info=True)
+        return None
+
+
+def put(
+    key: str, value: Any, category: str = "general", ttl: float = SEARCH_TTL
+) -> None:
+    """
+    Store a value in cache.
+
+    Parameters:
+        key: Cache key.
+        value: Value to cache (must be JSON-serializable).
+        category: Category for grouping (e.g., "search", "paper", "author").
+        ttl: Time-to-live in seconds.
+    """
+    try:
+        _ensure_cache_table()
+        conn = _db.get_db()
+        with _lock:
+            conn.execute(
+                """INSERT OR REPLACE INTO cache (key, value, category, created_at, ttl)
+                   VALUES (?, ?, ?, ?, ?)""",
+                (key, json.dumps(value), category, time.time(), ttl),
+            )
+            conn.commit()
+    except Exception:
+        logger.debug("Cache put failed for key %s", key[:16], exc_info=True)
+
+
+def _delete(key: str) -> None:
+    """Delete a cache entry."""
+    try:
+        _ensure_cache_table()
+        conn = _db.get_db()
+        with _lock:
+            conn.execute("DELETE FROM cache WHERE key = ?", (key,))
+            conn.commit()
+    except Exception:
+        logger.debug("Cache delete failed for key %s", key[:16], exc_info=True)
+
+
+def clear(category: Optional[str] = None) -> int:
+    """
+    Clear cache entries.
+
+    Parameters:
+        category: If provided, only clear entries in this category.
+                  Otherwise clear everything.
+
+    Returns:
+        Number of entries cleared.
+    """
+    try:
+        _ensure_cache_table()
+        conn = _db.get_db()
+        with _lock:
+            if category:
+                cursor = conn.execute(
+                    "DELETE FROM cache WHERE category = ?", (category,)
+                )
+            else:
+                cursor = conn.execute("DELETE FROM cache")
+            count = cursor.rowcount
+            conn.commit()
+        return count
+    except Exception:
+        logger.debug("Cache clear failed", exc_info=True)
+        return 0
+
+
+def stats() -> Dict[str, Any]:
+    """
+    Get cache statistics.
+
+    Returns:
+        Dict with total entries, entries by category, and cache size.
+    """
+    try:
+        _ensure_cache_table()
+        conn = _db.get_db()
+        with _lock:
+            total = conn.execute("SELECT COUNT(*) FROM cache").fetchone()[0]
+
+            categories = {}
+            for row in conn.execute(
+                "SELECT category, COUNT(*) FROM cache GROUP BY category"
+            ):
+                categories[row[0]] = row[1]
+
+            expired = conn.execute(
+                "SELECT COUNT(*) FROM cache WHERE (? - created_at) > ttl",
+                (time.time(),),
+            ).fetchone()[0]
+
+        db_path = _db.get_db_path()
+        size_bytes = os.path.getsize(db_path) if os.path.exists(db_path) else 0
+
+        return {
+            "total_entries": total,
+            "expired_entries": expired,
+            "active_entries": total - expired,
+            "by_category": categories,
+            "cache_size_mb": round(size_bytes / (1024 * 1024), 2),
+            "cache_path": db_path,
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def cleanup() -> int:
+    """
+    Remove expired cache entries.
+
+    Returns:
+        Number of entries removed.
+    """
+    try:
+        _ensure_cache_table()
+        conn = _db.get_db()
+        with _lock:
+            cursor = conn.execute(
+                "DELETE FROM cache WHERE (? - created_at) > ttl",
+                (time.time(),),
+            )
+            count = cursor.rowcount
+            conn.commit()
+        return count
+    except Exception:
+        logger.debug("Cache cleanup failed", exc_info=True)
+        return 0
+
+
+# --- Decorator for easy caching ---
+
+
+def cached(category: str = "general", ttl: float = SEARCH_TTL):
+    """
+    Decorator that caches function results.
+
+    Usage:
+        @cached(category="search", ttl=SEARCH_TTL)
+        def search_papers(query, num_results=10):
+            ...
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            key = make_key(func.__name__, *args, **kwargs)
+            result = get(key)
+            if result is not None:
+                return result
+            result = func(*args, **kwargs)
+            # Don't cache error responses
+            if isinstance(result, dict) and "error" in result:
+                return result
+            if (
+                isinstance(result, list)
+                and result
+                and isinstance(result[0], dict)
+                and "error" in result[0]
+            ):
+                return result
+            put(key, result, category=category, ttl=ttl)
+            return result
+
+        return wrapper
+
+    return decorator