Update PaperSeek to v0.3.0 with recoverable search planning

[MingfengHong]

Summary

• add structured SearchPlan generation, source-specific query contracts, Query Portfolio retrieval, and a candidate provenance ledger
• add bounded native/LangGraph search loops with budgets, checkpoints, Stop/resume, partial recovery, and deterministic guardrails
• improve multi-lane retrieval, citation traversal, post-citation fusion, batched LLM ranking, and metadata/abstract handling
• redesign the Web workflow as a progressive four-stage audit with preserved user disclosure state, compact logs, and complete bilingual UI
• update the community package to v0.3.0, Python 3.10+, refreshed CLI/MCP/Skill/config surfaces, public release notes, and an independent lightweight WoS Starter adapter

Validation

• python -m pytest -q ...: 440 passed, 6 skipped, 253 subtests passed
• Chromium workflow tests: search, progressive disclosure, citation map, language switch, CSV/log export, history, Stop, and checkpoint resume all passed
• live OpenAlex full search passed with citation expansion and abstract enrichment: 814 source records, 64 ranked outputs, 59 abstracts, 72 citation nodes, and 9 edges
• live source smoke passed for OpenAlex, Semantic Scholar, PubMed, Google Scholar/Serper, PaperHub, Crossref, and WoS; arXiv was rate-limited by its public upstream during the latest check
• npm.cmd run docs:build, JavaScript syntax, Python compile, and git diff --check passed
• wheel and sdist passed Twine checks, archive scope checks, and installation in a clean virtual environment

[MingfengHong]

/review

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit 5061dc3)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 5 🔵🔵🔵🔵🔵

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Missing query parameter The new implementation of documents_uid_get and its _with_http_info/_without_preload_content variants no longer passes the detail query parameter to the WoS Starter API. The old auto-generated code included detail when fetching a document by UID. This change silently drops a parameter that callers may rely on (e.g., requesting short vs full data), altering the API response format. def _document_uid_response(self, uid: str, *, db: Optional[str], timeout: Timeout, headers: Optional[dict]): if not str(uid or "").strip(): raise ValueError("uid is required") params = {"db": db} if db else None return self.api_client.request( "GET", f"/documents/{str(uid).strip()}", params=params, headers=headers, timeout=timeout, ) def documents_uid_get( self, uid: str, db: Optional[str] = None, _request_timeout: Timeout = None, _request_auth: Optional[Dict[str, Any]] = None, _content_type: Optional[str] = None, _headers: Optional[Dict[str, Any]] = None, _host_index: int = 0, ) -> Document: del _request_auth, _content_type, _host_index response = self._document_uid_response(uid, db=db, timeout=_request_timeout, headers=_headers) payload = self._decode(response) if isinstance(payload.get("hits"), list): payload = payload["hits"][0] if payload["hits"] else {} return Document.from_dict(payload) Forced default limit The new _limit method now defaults to 10 when limit is None, and this value is always sent in the request parameters. Previously, limit was optional and would be omitted if not provided, allowing the API to return its own default (likely all records). Now every search request is forced to a limit of at most 50, defaulting to 10, which can silently truncate results for users who do not set an explicit limit, potentially causing missing records or unexpected behaviour downstream. @staticmethod def _limit(value: Optional[int]) -> int: limit = 10 if value is None else int(value) if limit < 1: raise ValueError("WoS Starter limit must be positive") return min(limit, 50) @staticmethod def _decode(response) -> dict: try: payload = response.json() except ValueError as exc: raise ApiException( status=response.status_code, reason="WoS Starter returned invalid JSON", body=response.text, ) from exc if not isinstance(payload, dict): raise ApiException( status=response.status_code, reason="WoS Starter returned a non-object JSON payload", body=response.text, ) return payload def _documents_response( self, *, q: str, db: Optional[str], limit: Optional[int], page: Optional[int], sort_field: Optional[str], modified_time_span: Optional[str], tc_modified_time_span: Optional[str], detail: Optional[str], timeout: Timeout, headers: Optional[Dict[str, Any]], ): if not str(q or "").strip(): raise ValueError("q is required") params = { "q": str(q), "db": db,

[MingfengHong]

PR Agent's WoS authentication concern was checked against the transport implementation and is not actionable:

• paperseek_core/client/client.py centralizes authentication in ApiClient.request() and injects X-ApiKey from Configuration.get_api_key_with_prefix(ClarivateApiKeyAuth) for every request.
• tests/test_wos_client_models.py::test_documents_api_sends_auth_and_expected_parameter_names asserts the actual outbound X-ApiKey header.
• A live WoS Starter smoke request also completed successfully with the new adapter.

Keeping authentication in the shared transport avoids duplicating it in each endpoint method.

[MingfengHong]

/review

[github-actions]

Persistent review updated to latest commit 5061dc3