paperstack-cli 0.4.0__tar.gz → 0.4.1__tar.gz

{paperstack_cli-0.4.0 → paperstack_cli-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paperstack-cli
-Version: 0.4.0
+Version: 0.4.1
 Summary: Review, inspect, and retrieve research sources from one CLI
 Project-URL: Repository, https://github.com/MilkClouds/paperstack
 Project-URL: Issues, https://github.com/MilkClouds/paperstack/issues
@@ -134,6 +134,7 @@ These commands use external source records and do not select a citation or make
 
 ```bash
 paperstack paper search "Attention Is All You Need" --source dblp
+paperstack paper search "Exact Paper Title" --source openreview --exact-title --openreview-status accepted
 paperstack paper search "robot learning" --source semantic-scholar --year 2024-2026
 paperstack paper search 'ti:"robot learning"' --source arxiv --category cs.RO --sort date
 paperstack paper metadata arxiv:2106.09685
@@ -151,6 +152,10 @@ reference. `authors`, `citations`, and `references` use Semantic Scholar and als
 `--offline` flags. Paperstack reports source records but does not synthesize a citation entry or choose which version
 of a work should be cited.
 
+OpenReview exact-title search uses its title-only exact mode and verifies a normalized title match locally. Status
+filtering is conservative because venues encode decisions and withdrawals differently; Paperstack infers it from
+public invitation, venue, decision, and status fields rather than treating it as a universal field.
+
 ## Build a viewer
 
 ```bash

{paperstack_cli-0.4.0 → paperstack_cli-0.4.1}/README.md

@@ -112,6 +112,7 @@ These commands use external source records and do not select a citation or make
 
 ```bash
 paperstack paper search "Attention Is All You Need" --source dblp
+paperstack paper search "Exact Paper Title" --source openreview --exact-title --openreview-status accepted
 paperstack paper search "robot learning" --source semantic-scholar --year 2024-2026
 paperstack paper search 'ti:"robot learning"' --source arxiv --category cs.RO --sort date
 paperstack paper metadata arxiv:2106.09685
@@ -129,6 +130,10 @@ reference. `authors`, `citations`, and `references` use Semantic Scholar and als
 `--offline` flags. Paperstack reports source records but does not synthesize a citation entry or choose which version
 of a work should be cited.
 
+OpenReview exact-title search uses its title-only exact mode and verifies a normalized title match locally. Status
+filtering is conservative because venues encode decisions and withdrawals differently; Paperstack infers it from
+public invitation, venue, decision, and status fields rather than treating it as a universal field.
+
 ## Build a viewer
 
 ```bash

{paperstack_cli-0.4.0 → paperstack_cli-0.4.1}/src/paperstack/cli.py

@@ -925,12 +925,42 @@ def _run_paper(a: argparse.Namespace) -> int:
         metadata.print_results(results, json_output=a.json)
         return 0 if any(item["status"] == "ok" for item in results) else 1
     if a.paper_cmd == "search":
+        semantic_filters = [
+            flag
+            for flag, selected in (
+                ("--offset", a.offset),
+                ("--year", a.year),
+                ("--field-of-study", a.fields_of_study),
+                ("--open-access", a.open_access),
+            )
+            if selected
+        ]
+        arxiv_filters = [
+            flag
+            for flag, selected in (
+                ("--category", a.categories),
+                ("--date-from", a.date_from),
+                ("--date-to", a.date_to),
+                ("--sort", a.sort != "relevance"),
+            )
+            if selected
+        ]
+        openreview_filters = [
+            flag
+            for flag, selected in (
+                ("--exact-title", a.exact_title),
+                ("--openreview-status", a.openreview_status),
+            )
+            if selected
+        ]
         try:
+            if a.source != "openreview" and openreview_filters:
+                die(f"--source openreview is required for {', '.join(openreview_filters)}")
             if a.source == "arxiv":
                 from . import arxiv
 
-                if a.year or a.fields_of_study or a.open_access or a.offset:
-                    die("--year, --field-of-study, --open-access, and --offset require --source semantic-scholar")
+                if semantic_filters:
+                    die(f"--source semantic-scholar is required for {', '.join(semantic_filters)}")
                 result = arxiv.search(
                     a.query,
                     categories=a.categories,
@@ -942,8 +972,8 @@ def _run_paper(a: argparse.Namespace) -> int:
             elif a.source == "semantic-scholar":
                 from . import semantic_scholar
 
-                if a.categories or a.date_from or a.date_to or a.sort != "relevance":
-                    die("--category, --date-from, --date-to, and --sort require --source arxiv")
+                if arxiv_filters:
+                    die(f"--source arxiv is required for {', '.join(arxiv_filters)}")
                 result = semantic_scholar.search(
                     a.query,
                     limit=a.limit,
@@ -953,19 +983,21 @@ def _run_paper(a: argparse.Namespace) -> int:
                     open_access=a.open_access,
                 )
             else:
-                if (
-                    a.categories
-                    or a.date_from
-                    or a.date_to
-                    or a.limit != 10
-                    or a.offset
-                    or a.sort != "relevance"
-                    or a.year
-                    or a.fields_of_study
-                    or a.open_access
-                ):
-                    die("search filters require --source arxiv or --source semantic-scholar")
-                result = metadata.search(a.source, a.query, local_only=offline)
+                requirements = []
+                if semantic_filters:
+                    requirements.append(f"--source semantic-scholar is required for {', '.join(semantic_filters)}")
+                if arxiv_filters:
+                    requirements.append(f"--source arxiv is required for {', '.join(arxiv_filters)}")
+                if requirements:
+                    die("; ".join(requirements))
+                result = metadata.search(
+                    a.source,
+                    a.query,
+                    limit=a.limit,
+                    local_only=offline,
+                    exact_title=a.exact_title,
+                    openreview_status=a.openreview_status,
+                )
         except credentials.CredentialsError as exc:
             die(f"configuration failed: {exc}")
         except RuntimeError as exc:
@@ -1178,6 +1210,12 @@ Use `paperstack review ...` to find or read an authored critical judgment.""",
     s.add_argument("--date-from", help="earliest arXiv submission date")
     s.add_argument("--date-to", help="latest arXiv submission date")
     s.add_argument("--sort", choices=("relevance", "date"), default="relevance")
+    s.add_argument("--exact-title", action="store_true", help="require a normalized exact OpenReview title")
+    s.add_argument(
+        "--openreview-status",
+        choices=("submission", "accepted", "withdrawn"),
+        help="filter OpenReview forum records by inferred status",
+    )
     _output(s)
     _offline(s)
     for command in ("authors", "citations", "references"):

{paperstack_cli-0.4.0 → paperstack_cli-0.4.1}/src/paperstack/metadata.py

@@ -6,11 +6,18 @@ import json
 import os
 import re
 import time
+import unicodedata
 import urllib.error
 import urllib.parse
 import urllib.request
 import xml.etree.ElementTree as ET
+from contextlib import contextmanager
 from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+
+from filelock import FileLock
 
 from . import credentials
 
@@ -45,6 +52,59 @@ class PaperRef:
 
 
 _last_request: dict[str, float] = {}
+_OPENREVIEW_HOSTS = {"api.openreview.net", "api2.openreview.net"}
+
+
+@contextmanager
+def _request_slot(key: str):
+    if key != "openreview":
+        yield None
+        return
+    base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    root = base / "paperstack" / "http"
+    try:
+        root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        lock = FileLock(root / "openreview.lock", timeout=120)
+        lock.acquire()
+    except OSError:
+        yield None
+        return
+    try:
+        yield root / "openreview.timestamp"
+    finally:
+        lock.release()
+
+
+def _shared_elapsed(path: Path | None) -> float:
+    if path is None:
+        return float("inf")
+    try:
+        return max(0.0, time.time() - path.stat().st_mtime)
+    except OSError:
+        return float("inf")
+
+
+def _mark_request(path: Path | None) -> None:
+    if path is not None:
+        try:
+            path.touch()
+        except OSError:
+            pass
+
+
+def _retry_delay(exc: urllib.error.HTTPError, attempt: int) -> float:
+    value = exc.headers.get("Retry-After") if exc.headers else None
+    if value:
+        try:
+            delay = float(value)
+        except ValueError:
+            try:
+                delay = (parsedate_to_datetime(value) - datetime.now(UTC)).total_seconds()
+            except (TypeError, ValueError, OverflowError):
+                delay = -1
+        if delay >= 0:
+            return min(delay, 120)
+    return min(2**attempt, 30)
 
 
 def request(
@@ -56,34 +116,41 @@ def request(
     if params:
         url += "?" + urllib.parse.urlencode(params)
     host = urllib.parse.urlparse(url).netloc
+    request_key = "openreview" if host in _OPENREVIEW_HOSTS else host
     interval = 3.0 if "arxiv.org" in host else 1.1 if "dblp.org" in host else 0.5
     request_headers = {
         "User-Agent": "paperstack (+https://github.com/MilkClouds/paperstack)",
         **(headers or {}),
     }
     req = urllib.request.Request(url, headers=request_headers, data=data)
-    for attempt in range(3):
-        elapsed = time.monotonic() - _last_request.get(host, 0.0)
-        if elapsed < interval:
-            time.sleep(interval - elapsed)
-        try:
-            with urllib.request.urlopen(req, timeout=30) as response:
-                _last_request[host] = time.monotonic()
-                return response.read()
-        except urllib.error.HTTPError as exc:
-            _last_request[host] = time.monotonic()
-            if exc.code != 429:
-                raise
-            if attempt == 2:
-                has_api_key = any(name.lower() == "x-api-key" for name in request_headers)
-                if host == "api.semanticscholar.org" and not has_api_key:
-                    message = (
-                        f"{exc.reason}; configure semantic-scholar.api-key with "
-                        "`paperstack config set semantic-scholar.api-key` for more reliable access"
-                    )
-                    raise urllib.error.HTTPError(exc.url, exc.code, message, exc.headers, exc.fp) from exc
-                raise
-            time.sleep(5 * (attempt + 1))
+    with _request_slot(request_key) as shared_timestamp:
+        for attempt in range(3):
+            elapsed = min(
+                time.monotonic() - _last_request.get(request_key, 0.0),
+                _shared_elapsed(shared_timestamp),
+            )
+            if elapsed < interval:
+                time.sleep(interval - elapsed)
+            try:
+                with urllib.request.urlopen(req, timeout=30) as response:
+                    _last_request[request_key] = time.monotonic()
+                    _mark_request(shared_timestamp)
+                    return response.read()
+            except urllib.error.HTTPError as exc:
+                _last_request[request_key] = time.monotonic()
+                _mark_request(shared_timestamp)
+                if exc.code != 429:
+                    raise
+                if attempt == 2:
+                    has_api_key = any(name.lower() == "x-api-key" for name in request_headers)
+                    if host == "api.semanticscholar.org" and not has_api_key:
+                        message = (
+                            f"{exc.reason}; configure semantic-scholar.api-key with "
+                            "`paperstack config set semantic-scholar.api-key` for more reliable access"
+                        )
+                        raise urllib.error.HTTPError(exc.url, exc.code, message, exc.headers, exc.fp) from exc
+                    raise
+                time.sleep(_retry_delay(exc, attempt))
     raise RuntimeError("unreachable request retry state")
 
 
@@ -305,11 +372,50 @@ def fetch_all(
     return results
 
 
-def search(source: str, query: str, *, local_only: bool = False) -> dict:
+def _content_value(note: dict, name: str):
+    value = (note.get("content") or {}).get(name)
+    return value.get("value") if isinstance(value, dict) and "value" in value else value
+
+
+def _normalized_title(value: object) -> str:
+    return re.sub(r"\W+", "", unicodedata.normalize("NFKC", str(value or "")).casefold())
+
+
+def _openreview_status(note: dict) -> str:
+    venue = _content_value(note, "venue") or _content_value(note, "venueid") or _content_value(note, "venue_id")
+    fields = [*note.get("invitations", []), venue, _content_value(note, "decision"), _content_value(note, "status")]
+    text = " ".join(str(value) for value in fields if value).casefold()
+    if "withdraw" in text:
+        return "withdrawn"
+    if "reject" in text:
+        return "rejected"
+    if "accept" in text or venue and not any(word in str(venue).casefold() for word in ("submission", "submitted")):
+        return "accepted"
+    return "submission"
+
+
+def search(
+    source: str,
+    query: str,
+    *,
+    limit: int = 10,
+    local_only: bool = False,
+    exact_title: bool = False,
+    openreview_status: str | None = None,
+) -> dict:
+    query = query.strip()
+    if not query:
+        raise ValueError("paper search query is required")
+    if not 1 <= limit <= 100:
+        raise ValueError("limit must be between 1 and 100")
+    if (exact_title or openreview_status) and source != "openreview":
+        raise ValueError("exact title and OpenReview status filters require the openreview source")
+    if openreview_status not in (None, "submission", "accepted", "withdrawn"):
+        raise ValueError("OpenReview status must be submission, accepted, or withdrawn")
     if source == "dblp":
         from . import dblp_index
 
-        if hits := dblp_index.search(query):
+        if hits := dblp_index.search(query, limit=limit):
             return _result("dblp", str(dblp_index.index_path()), {"query": query, "matches": hits})
         if local_only:
             return {
@@ -319,19 +425,25 @@ def search(source: str, query: str, *, local_only: bool = False) -> dict:
                 "reason": "not found in local index",
             }
         url = "https://dblp.org/search/publ/api"
+        has_field_token = re.search(r"(?:^|\s)(?:author|title|venue|year|type|stream|toc):[^:]+:", query)
+        remote_query = query if has_field_token else re.sub(r":\s+", " ", query)
         return _safe(
-            lambda: _result("dblp", url, _get_json(url, {"q": query, "format": "json", "h": 10})), "dblp", url
+            lambda: _result("dblp", url, _get_json(url, {"q": remote_query, "format": "json", "h": limit})),
+            "dblp",
+            url,
         )
     if source == "crossref":
         url = "https://api.crossref.org/works"
         return _safe(
-            lambda: _result("crossref", url, _get_json(url, {"query.title": query, "rows": 10})), "crossref", url
+            lambda: _result("crossref", url, _get_json(url, {"query.title": query, "rows": limit})),
+            "crossref",
+            url,
         )
     if source == "arxiv":
         url = "https://export.arxiv.org/api/query"
 
         def arxiv_search() -> dict:
-            root = ET.fromstring(_get_text(url, {"search_query": f'ti:"{query}"', "max_results": 10}))
+            root = ET.fromstring(_get_text(url, {"search_query": f'ti:"{query}"', "max_results": limit}))
             matches = [
                 {
                     "id": entry.findtext("atom:id", "", ARXIV_NS),
@@ -347,40 +459,75 @@ def search(source: str, query: str, *, local_only: bool = False) -> dict:
         token = os.environ.get("OPENREVIEW_ACCESS_TOKEN")
         headers = {"Cookie": f"openreview.accessToken={token}"} if token else {}
         endpoints = (
-            "https://api2.openreview.net/notes/search",
-            "https://api.openreview.net/notes/search",
+            ("https://api2.openreview.net/notes/search", True),
+            ("https://api.openreview.net/notes/search", False),
         )
         matches = []
         errors = []
-        for endpoint in endpoints:
-            result = _safe(
-                lambda endpoint=endpoint: _result(
+        for endpoint, is_v2 in endpoints:
+            endpoint_matches = []
+            local_filter = bool(openreview_status or (exact_title and not is_v2))
+            page_size = min(max(limit * 2, 20), 100) if local_filter else limit
+            params = {"limit": page_size, "source": "forum", "cache": "true"}
+            if exact_title and is_v2:
+                params.update({"term": query, "type": "exact", "content": "title"})
+            else:
+                params["query"] = query
+            for offset in range(0, 1000, page_size):
+                page_params = {**params, "offset": offset} if offset else params
+                result = _safe(
+                    lambda endpoint=endpoint, page_params=page_params: _result(
+                        "openreview",
+                        endpoint,
+                        _get_json(endpoint, page_params, headers),
+                    ),
                     "openreview",
                     endpoint,
-                    _get_json(endpoint, {"query": query, "limit": 10, "source": "forum"}, headers),
-                ),
-                "openreview",
-                endpoint,
-            )
-            if result["status"] == "ok":
-                matches.extend(result.get("response", {}).get("notes", []))
-            else:
-                errors.append(result.get("error", endpoint))
+                )
+                if result["status"] != "ok":
+                    errors.append(result.get("error", endpoint))
+                    break
+                notes = result.get("response", {}).get("notes", [])
+                matches.extend(notes)
+                endpoint_matches.extend(notes)
+                if not local_filter or len(notes) < page_size:
+                    break
+                eligible = endpoint_matches
+                if exact_title:
+                    wanted = _normalized_title(query)
+                    eligible = [
+                        note for note in eligible if _normalized_title(_content_value(note, "title")) == wanted
+                    ]
+                if openreview_status:
+                    eligible = [note for note in eligible if _openreview_status(note) == openreview_status]
+                eligible_ids = {note.get("forum") or note.get("id") for note in eligible}
+                if len(eligible_ids) >= limit:
+                    break
         if not matches and errors:
-            return _result("openreview", endpoints[0], error="; ".join(errors))
+            return _result("openreview", endpoints[0][0], error="; ".join(errors))
         unique = {}
         for note in matches:
             unique[note.get("forum") or note.get("id") or json.dumps(note, sort_keys=True)] = note
+        selected = list(unique.values())
+        if exact_title:
+            wanted = _normalized_title(query)
+            selected = [note for note in selected if _normalized_title(_content_value(note, "title")) == wanted]
+        if openreview_status:
+            selected = [note for note in selected if _openreview_status(note) == openreview_status]
         return _result(
             "openreview",
-            endpoints[0],
-            {"query": query, "matches": list(unique.values()), "api_endpoints": list(endpoints)},
+            endpoints[0][0],
+            {
+                "query": query,
+                "matches": selected[:limit],
+                "api_endpoints": [endpoint for endpoint, _ in endpoints],
+            },
         )
     if source == "s2":
         url = "https://api.semanticscholar.org/graph/v1/paper/search"
         api_key = credentials.get(credentials.SEMANTIC_SCHOLAR_API_KEY)
         headers = {"x-api-key": api_key} if api_key else {}
-        params = {"query": query, "limit": 10, "fields": S2_FIELDS}
+        params = {"query": query, "limit": limit, "fields": S2_FIELDS}
         return _safe(
             lambda: _result("semantic_scholar", url, _get_json(url, params, headers)), "semantic_scholar", url
         )

{paperstack_cli-0.4.0 → paperstack_cli-0.4.1}/src/paperstack/viewer.py

@@ -94,11 +94,12 @@ def build(root: Path, output: Path) -> int:
     ):
         raise ValueError("viewer output would replace a broad path, the corpus, or authored entries")
     backup = destination.parent / f".{destination.name}.backup"
-    if backup.exists() and not destination.exists():
+    if backup.exists():
         marker = backup / ".paperstack-viewer"
         if not backup.is_dir() or not marker.is_file() or marker.read_text(encoding="utf-8") != "1\n":
             raise ValueError(f"viewer backup is not owned by Paperstack: {backup}")
-        os.replace(backup, destination)
+        if not destination.exists():
+            os.replace(backup, destination)
     if destination.exists() and not destination.is_dir():
         raise ValueError(f"viewer output is not a directory: {destination}")
     if destination.exists() and any(destination.iterdir()):