docent-cli 1.0.0__py3-none-any.whl

docent/bundled_plugins/reading/mendeley_cache.py

@@ -0,0 +1,183 @@
+"""File-backed read-through cache for Mendeley collection metadata.
+
+Step 11.7. Wraps `mendeley_list_documents(folder_id)` only — `get_document`
+isn't wrapped yet because no reader needs the fields it adds (abstract,
+attachments) and the bulk list call already covers title/authors/year/doi.
+
+Cache file: `<cache_dir>/paper/mendeley_collection.json`.
+
+  {
+    "<folder_id>": {
+      "fetched_at": <unix_ts>,
+      "docs": {"<mendeley_id>": <doc>, ...}
+    },
+    ...
+  }
+
+Across-CLI persistence is the whole point: each `docent paper next` is a
+fresh Python process, and a 5-minute TTL only delivers the promised
+"feels instant" UX if it survives process exits. `sync-from-mendeley`
+calls `invalidate()` after writing the queue so the next reader pulls
+fresh data.
+
+On MCP transport / auth error the cache returns `None` — callers fall
+back to the snapshot fields persisted in queue.json by sync-from-mendeley.
+A failed fetch is never written to disk.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from .mendeley_client import list_documents as default_list_documents
+from .mendeley_client import list_folders as default_list_folders
+
+DEFAULT_TTL_SECONDS = 300
+# Folder IDs are effectively immutable in Mendeley — the only realistic
+# invalidator is the user renaming/recreating the collection, which already
+# surfaces a verbose actionable hint via sync-from-mendeley.
+FOLDER_TTL_SECONDS = 86400
+# Reserved key for the collection_name -> folder_id map. Mendeley folder
+# IDs are UUID-shaped, so this can't collide with a real top-level entry.
+_FOLDERS_KEY = "__folders__"
+
+
+class MendeleyCache:
+    def __init__(
+        self,
+        cache_path: Path,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+        list_documents: Callable[..., dict[str, Any]] | None = None,
+        list_folders: Callable[..., dict[str, Any]] | None = None,
+        folder_ttl_seconds: int = FOLDER_TTL_SECONDS,
+    ) -> None:
+        self._path = cache_path
+        self._ttl = ttl_seconds
+        self._list_documents = list_documents or default_list_documents
+        self._list_folders = list_folders or default_list_folders
+        self._folder_ttl = folder_ttl_seconds
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def get_collection(
+        self,
+        folder_id: str,
+        launch_command: list[str] | None = None,
+    ) -> dict[str, dict[str, Any]] | None:
+        """Return `{mendeley_id: doc}` for the given folder, or None on
+        transport/auth error. Reads from disk if fresh, otherwise calls
+        `list_documents` and rewrites the cache file.
+        """
+        store = self._load()
+        entry = store.get(folder_id)
+        now = time.time()
+        if entry and (now - entry.get("fetched_at", 0.0)) < self._ttl:
+            docs = entry.get("docs")
+            if isinstance(docs, dict):
+                return docs
+
+        resp = self._list_documents(folder_id=folder_id, launch_command=launch_command)
+        if resp.get("error"):
+            return None
+        items = resp.get("items") or []
+        docs = {mid: doc for doc in items if (mid := _doc_id(doc))}
+        store[folder_id] = {"fetched_at": now, "docs": docs}
+        self._save(store)
+        return docs
+
+    def get_folder_id(
+        self,
+        collection_name: str,
+        launch_command: list[str] | None = None,
+    ) -> str | None:
+        """Return the Mendeley folder ID for `collection_name`, or None on
+        transport error / missing / ambiguous. Cached in the same file under
+        a reserved `__folders__` key with a long TTL — folder IDs are
+        effectively static, and this saves the ~5s `list_folders` MCP
+        round-trip on every reader call.
+        """
+        store = self._load()
+        entry = store.get(_FOLDERS_KEY)
+        now = time.time()
+        if entry and (now - entry.get("fetched_at", 0.0)) < self._folder_ttl:
+            by_name = entry.get("by_name")
+            if isinstance(by_name, dict) and collection_name in by_name:
+                fid = by_name[collection_name]
+                return fid if isinstance(fid, str) and fid else None
+
+        resp = self._list_folders(launch_command=launch_command)
+        if resp.get("error"):
+            return None
+        folders = resp.get("items") or []
+        # Count names first so duplicates get dropped entirely (not toggled).
+        counts: dict[str, int] = {}
+        for f in folders:
+            if isinstance(f, dict):
+                n = f.get("name")
+                if isinstance(n, str) and n:
+                    counts[n] = counts.get(n, 0) + 1
+        by_name: dict[str, str] = {}
+        for f in folders:
+            if not isinstance(f, dict):
+                continue
+            name = f.get("name")
+            fid = f.get("id")
+            if (
+                isinstance(name, str) and name
+                and isinstance(fid, str) and fid
+                and counts.get(name, 0) == 1
+            ):
+                by_name[name] = fid
+        store[_FOLDERS_KEY] = {"fetched_at": now, "by_name": by_name}
+        self._save(store)
+        return by_name.get(collection_name)
+
+    def invalidate(self, folder_id: str | None = None) -> None:
+        """Drop one folder's entry, or the whole file if `folder_id` is None.
+        Called by `sync-from-mendeley` after a successful write so the next
+        reader pulls fresh data."""
+        if folder_id is None:
+            try:
+                self._path.unlink()
+            except FileNotFoundError:
+                pass
+            return
+        store = self._load()
+        if folder_id in store:
+            del store[folder_id]
+            self._save(store)
+
+    def _load(self) -> dict[str, dict[str, Any]]:
+        if not self._path.exists():
+            return {}
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            # Corrupt cache file: behave as if empty. Next write rewrites it.
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _save(self, store: dict[str, dict[str, Any]]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
+        tmp.write_text(json.dumps(store, indent=2, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, self._path)
+
+
+def _doc_id(doc: Any) -> str | None:
+    """Mendeley docs may carry the id under `id` (library docs) or
+    `catalog_id` (catalog hits via mendeley_get_by_doi). list_documents
+    returns library docs, so `id` covers it; we accept `catalog_id` too
+    in case a future caller mixes payloads."""
+    if not isinstance(doc, dict):
+        return None
+    for key in ("id", "catalog_id"):
+        v = doc.get(key)
+        if isinstance(v, str) and v:
+            return v
+    return None

docent/bundled_plugins/reading/mendeley_client.py

@@ -0,0 +1,132 @@
+"""Mendeley MCP client wrapper - sync facade over the async `mcp` SDK.
+
+Step 11.4. Spawn-per-call: each call launches the Mendeley MCP server as a
+subprocess via stdio, runs one `call_tool`, and tears down. Step 11.9 retired
+`lookup_doi` / `search_library` (sync-mendeley subsumed by sync-from-mendeley);
+only `list_folders` and `list_documents` remain — both feeding the Mendeley
+read-through cache used by paper readers.
+
+Return shape is `{"items": list, "error": str | None}`:
+
+- success      -> {"items": [...], "error": None} (items may be empty = not found)
+- auth failure -> {"items": [], "error": "auth: ..."}
+- transport    -> {"items": [], "error": "transport: ..."}
+- tool error   -> {"items": [], "error": "tool: ..."}
+
+Callers bucket on `error` prefix. Lazy-imports `mcp` so importing this
+module is cheap; the SDK is only loaded when a function actually runs.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+DEFAULT_LAUNCH_COMMAND: list[str] = ["uvx", "mendeley-mcp"]
+
+
+def _parse_text_payload(result: Any) -> Any:
+    """MCP CallToolResult.content is a list of content blocks; the Mendeley
+    server returns a single text block carrying JSON. Returns the parsed
+    JSON value (may be dict, list, or scalar) or None if the shape is off.
+    """
+    try:
+        block = result.content[0]
+    except (AttributeError, IndexError):
+        return None
+    text = getattr(block, "text", None)
+    if text is None:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return None
+
+
+def _classify_error(message: str) -> str:
+    low = message.lower()
+    if any(s in low for s in ("auth", "token", "credential", "401", "403", "unauthor")):
+        return "auth"
+    return "tool"
+
+
+async def _call_tool(launch_command: list[str], tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    # Lazy import: keeps `paper.py` import path free of the mcp SDK.
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+
+    if not launch_command:
+        return {"items": [], "error": "transport: empty launch command"}
+
+    params = StdioServerParameters(
+        command=launch_command[0],
+        args=list(launch_command[1:]),
+        env=None,
+    )
+
+    try:
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(tool_name, arguments)
+    except FileNotFoundError as e:
+        return {"items": [], "error": f"transport: launch command not found ({e})"}
+    except Exception as e:  # noqa: BLE001 — surfaces stdio_client / session errors uniformly.
+        return {"items": [], "error": f"transport: {type(e).__name__}: {e}"}
+
+    parsed = _parse_text_payload(result)
+
+    if getattr(result, "isError", False):
+        if isinstance(parsed, dict) and parsed.get("error"):
+            msg = str(parsed["error"])
+        else:
+            msg = "tool returned error"
+        return {"items": [], "error": f"{_classify_error(msg)}: {msg}"}
+
+    if parsed is None:
+        return {"items": [], "error": "tool: unparseable response"}
+
+    # Some tool error paths return a JSON dict with an `error` key but no isError flag.
+    if isinstance(parsed, dict) and "error" in parsed and len(parsed) == 1:
+        msg = str(parsed["error"])
+        return {"items": [], "error": f"{_classify_error(msg)}: {msg}"}
+
+    if isinstance(parsed, list):
+        items = parsed
+    elif isinstance(parsed, dict):
+        # Single-document response (mendeley_get_by_doi) or wrapped list.
+        items = parsed.get("documents") or parsed.get("results") or parsed.get("items") or [parsed]
+    else:
+        items = [parsed]
+
+    return {"items": items, "error": None}
+
+
+def _run(coro: Any) -> dict[str, Any]:
+    return asyncio.run(coro)
+
+
+def list_folders(launch_command: list[str] | None = None) -> dict[str, Any]:
+    """Call Mendeley's `mendeley_list_folders`. Returns flat list of
+    `{id, name, parent_id}`; nesting is encoded via `parent_id`. Used by
+    `sync-from-mendeley` to resolve a configured collection name to its id."""
+    cmd = launch_command or DEFAULT_LAUNCH_COMMAND
+    return _run(_call_tool(cmd, "mendeley_list_folders", {}))
+
+
+def list_documents(
+    folder_id: str | None = None,
+    launch_command: list[str] | None = None,
+    limit: int = 200,
+    sort_by: str = "last_modified",
+) -> dict[str, Any]:
+    """Call Mendeley's `mendeley_list_documents`. With `folder_id`, scopes
+    to that collection; without, returns the whole library. Default limit
+    bumped from 50 (MCP default) to 200 — a reading queue can plausibly hold
+    that many. Documents above the limit are silently truncated; revisit if
+    real-data queues grow past it."""
+    cmd = launch_command or DEFAULT_LAUNCH_COMMAND
+    args: dict[str, Any] = {"limit": limit, "sort_by": sort_by}
+    if folder_id is not None:
+        args["folder_id"] = folder_id
+    return _run(_call_tool(cmd, "mendeley_list_documents", args))

docent/bundled_plugins/reading/reading_notify.py

@@ -0,0 +1,78 @@
+"""Startup deadline notifications for the reading queue.
+
+Called once per day on first `docent` invocation. Prints a warning for any
+entry whose deadline is within 3 days or already past. Deduplicates within a
+calendar day so the same alert doesn't repeat across multiple commands.
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any
+
+
+def check_deadlines(store_root: Path) -> list[str]:
+    """Return alert lines for entries with deadlines within 3 days or past due.
+
+    Only fires once per calendar day — seen entries are tracked in
+    `<store_root>/deadline-seen.json`. Returns an empty list when there is
+    nothing to report or when the daily gate has already fired.
+    """
+    queue_path = store_root / "queue.json"
+    seen_path = store_root / "deadline-seen.json"
+
+    if not queue_path.exists():
+        return []
+
+    today_str = date.today().isoformat()
+    seen: dict[str, str] = {}  # entry_id -> last-seen date
+    if seen_path.exists():
+        try:
+            seen = json.loads(seen_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            seen = {}
+
+    try:
+        queue: list[dict[str, Any]] = json.loads(queue_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+
+    today = date.today()
+    warn_horizon = today + timedelta(days=3)
+    alerts: list[str] = []
+    updated_seen = dict(seen)
+
+    for entry in queue:
+        if entry.get("status") in ("done", "removed"):
+            continue
+        deadline_str = entry.get("deadline")
+        if not deadline_str:
+            continue
+        eid = entry.get("id", "")
+        if seen.get(eid) == today_str:
+            continue  # already alerted today
+        try:
+            deadline = date.fromisoformat(deadline_str)
+        except ValueError:
+            continue
+
+        if deadline <= warn_horizon:
+            days_left = (deadline - today).days
+            title = entry.get("title") or eid
+            if days_left < 0:
+                alerts.append(f"[OVERDUE {abs(days_left)}d] {title!r} — deadline was {deadline_str}")
+            elif days_left == 0:
+                alerts.append(f"[DUE TODAY] {title!r} — deadline {deadline_str}")
+            else:
+                alerts.append(f"[DUE IN {days_left}d] {title!r} — deadline {deadline_str}")
+            updated_seen[eid] = today_str
+
+    if updated_seen != seen:
+        store_root.mkdir(parents=True, exist_ok=True)
+        tmp = seen_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(updated_seen, indent=2, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, seen_path)
+
+    return alerts

docent/bundled_plugins/reading/reading_store.py

@@ -0,0 +1,105 @@
+"""Persistence + state recompute for the reading queue.
+
+Owns three files inside `<root>/`:
+- queue.json        — source-of-truth list of QueueEntry dicts
+- queue-index.json  — id -> {title, status, order} for fast lookups
+- state.json        — banner counts + last_updated timestamp
+
+Reads return safe defaults if a file is missing. Writes self-initialize the
+directory and use atomic rename so a crash mid-write can't leave a partial
+JSON file in place.
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class BannerCounts(BaseModel):
+    queued: int = 0
+    reading: int = 0
+    done: int = 0
+
+
+class ReadingQueueStore:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    @property
+    def queue_path(self) -> Path:
+        return self.root / "queue.json"
+
+    @property
+    def index_path(self) -> Path:
+        return self.root / "queue-index.json"
+
+    @property
+    def state_path(self) -> Path:
+        return self.root / "state.json"
+
+    def load_queue(self) -> list[dict[str, Any]]:
+        if not self.queue_path.exists():
+            return []
+        return json.loads(self.queue_path.read_text(encoding="utf-8"))
+
+    def load_index(self) -> dict[str, dict[str, Any]]:
+        if not self.index_path.exists():
+            return {}
+        return json.loads(self.index_path.read_text(encoding="utf-8"))
+
+    def save_queue(self, queue: list[dict[str, Any]]) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._atomic_write_json(self.queue_path, queue)
+        self._atomic_write_json(self.index_path, self._recompute_index(queue))
+        self._write_state(queue)
+
+    def banner_counts(self) -> BannerCounts:
+        if not self.state_path.exists():
+            return BannerCounts()
+        data = json.loads(self.state_path.read_text(encoding="utf-8"))
+        return BannerCounts(
+            queued=data.get("queued", 0),
+            reading=data.get("reading", 0),
+            done=data.get("done", 0),
+        )
+
+    @staticmethod
+    def list_database_pdfs(database_dir: Path) -> list[Path]:
+        """Return all PDFs found recursively in `database_dir`.
+        Missing directory yields an empty list, not an error.
+        """
+        if not database_dir.is_dir():
+            return []
+        return sorted(database_dir.rglob("*.pdf"))
+
+    @staticmethod
+    def _recompute_index(queue: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+        return {
+            e["id"]: {
+                "title": e.get("title", ""),
+                "status": e["status"],
+                "order": e.get("order", 0),
+            }
+            for e in queue
+        }
+
+    def _write_state(self, queue: list[dict[str, Any]]) -> None:
+        state = {
+            "queued": sum(1 for e in queue if e["status"] == "queued"),
+            "reading": sum(1 for e in queue if e["status"] == "reading"),
+            "done": sum(1 for e in queue if e["status"] == "done"),
+            "last_updated": datetime.now().isoformat(),
+        }
+        self._atomic_write_json(self.state_path, state)
+
+    @staticmethod
+    def _atomic_write_json(path: Path, data: Any) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, path)