sciverse 0.7.2__tar.gz → 0.8.0__tar.gz

{sciverse-0.7.2 → sciverse-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sciverse
-Version: 0.7.2
+Version: 0.8.0
 Summary: Sciverse Agent Tools — OpenAI/Anthropic/LangChain compatible tool schema and async client for Sciverse retrieval APIs
 Project-URL: Homepage, https://github.com/opendatalab/Sciverse-Agent-Tools
 Project-URL: Repository, https://github.com/opendatalab/Sciverse-Agent-Tools.git
@@ -131,6 +131,14 @@ await c.search_papers(
     page_size=10,
 )
 
+# 1b. Entity collections — search authors / journals (set collection)
+await c.search_papers(
+    collection="authors",               # papers (default) / authors / sources
+    filters_advanced=[{"field": "summary_stats.h_index", "operator": "FILTER_OP_GTE", "value": 50}],
+    sort_advanced=[{"field": "cited_by_count", "order": "SORT_ORDER_DESC"}],
+)
+# Call list_catalog(collection="authors") to discover each collection's fields.
+
 # 2. Natural-language semantic search (vector + BM25 hybrid, returns chunks)
 await c.semantic_search(query="How does attention work?", top_k=10, mode="balanced")
 

{sciverse-0.7.2 → sciverse-0.8.0}/README.md

@@ -114,6 +114,14 @@ await c.search_papers(
     page_size=10,
 )
 
+# 1b. Entity collections — search authors / journals (set collection)
+await c.search_papers(
+    collection="authors",               # papers (default) / authors / sources
+    filters_advanced=[{"field": "summary_stats.h_index", "operator": "FILTER_OP_GTE", "value": 50}],
+    sort_advanced=[{"field": "cited_by_count", "order": "SORT_ORDER_DESC"}],
+)
+# Call list_catalog(collection="authors") to discover each collection's fields.
+
 # 2. Natural-language semantic search (vector + BM25 hybrid, returns chunks)
 await c.semantic_search(query="How does attention work?", top_k=10, mode="balanced")
 

{sciverse-0.7.2 → sciverse-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sciverse"
-version = "0.7.2"
+version = "0.8.0"
 description = "Sciverse Agent Tools — OpenAI/Anthropic/LangChain compatible tool schema and async client for Sciverse retrieval APIs"
 readme = "README.md"
 requires-python = ">=3.10"

{sciverse-0.7.2 → sciverse-0.8.0}/src/sciverse/cli.py

@@ -142,6 +142,7 @@ def _cmd_search(args: argparse.Namespace) -> int:
         if args.title_contains: kwargs["title_contains"] = args.title_contains
         if args.abstract_contains: kwargs["abstract_contains"] = args.abstract_contains
         if args.sort_by_year != "none": kwargs["sort_by_year"] = args.sort_by_year
+        if getattr(args, "collection", "papers") != "papers": kwargs["collection"] = args.collection
         if args.freshness_boost != "NONE": kwargs["freshness_boost"] = args.freshness_boost
         kwargs["page"] = args.page
         kwargs["page_size"] = args.page_size
@@ -173,7 +174,10 @@ def _cmd_content(args: argparse.Namespace) -> int:
 
 def _cmd_catalog(args: argparse.Namespace) -> int:
     async def _do(client):
-        r = await client.list_catalog(include_sample_values=args.samples)
+        r = await client.list_catalog(
+            include_sample_values=args.samples,
+            collection=getattr(args, "collection", None),
+        )
         _print_json(r)
 
     return _run_with_client(_do)
@@ -241,6 +245,9 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
     search.add_argument("query", nargs="?", default="", help="全文 BM25 关键词（可选）")
+    search.add_argument("--collection", choices=["papers", "authors", "sources"], default="papers",
+                        help="实体集合（默认 papers）。authors/sources 的高级字段过滤请用 SDK 的 "
+                             "filters_advanced / sort_advanced；CLI 主要支持 query 与 catalog 自省")
     search.add_argument("--author", "--authors", action="append", default=[], dest="authors",
                         help="作者名（可多次传，任一命中即可）")
     search.add_argument("--year-from", type=int, dest="year_from", help="起始年（含）")
@@ -283,6 +290,8 @@ def _build_parser() -> argparse.ArgumentParser:
         "catalog",
         help="字段 introspection（GET /meta-catalog），第一次接入时建议先调",
     )
+    cat.add_argument("--collection", choices=["papers", "authors", "sources"], default="papers",
+                     help="字段目录所属实体集合（默认 papers）")
     cat.add_argument("--samples", action="store_true",
                      help="拉枚举字段的取值样本（首次 OpenSearch terms agg，~几百 ms；之后 24h 缓存）")
     cat.set_defaults(func=_cmd_catalog)

{sciverse-0.7.2 → sciverse-0.8.0}/src/sciverse/client.py

@@ -13,7 +13,7 @@ _PLATFORM = platform.system().lower()  # "linux" | "darwin" | "windows"
 _SOURCE = f"{_PLATFORM}-{_CHANNEL}"
 
 
-_PASSTHROUGH = ("query", "page", "page_size", "fields", "freshness_boost")
+_PASSTHROUGH = ("query", "page", "page_size", "fields", "freshness_boost", "collection")
 _FRESHNESS_BOOST_VALUES = frozenset({"NONE", "MILD", "STRONG"})
 
 
@@ -65,6 +65,11 @@ def _to_backend_payload(kwargs: dict[str, Any]) -> dict[str, Any]:
             "order": "SORT_ORDER_DESC" if sort_by_year == "desc" else "SORT_ORDER_ASC",
         })
 
+    if (sa := kwargs.get("sort_advanced")) is not None:
+        for item in sa:
+            if item and item.get("field"):
+                sort.append({"field": item["field"], "order": item.get("order", "SORT_ORDER_DESC")})
+
     if filters:
         out["filters"] = filters
     if sort:
@@ -151,14 +156,25 @@ class AgentToolsClient:
         resp.raise_for_status()
         return resp.json()
 
-    async def list_catalog(self, *, include_sample_values: bool = False) -> dict[str, Any]:
+    async def list_catalog(
+        self,
+        *,
+        include_sample_values: bool = False,
+        include_field_stats: bool = False,
+        collection: str | None = None,
+    ) -> dict[str, Any]:
         """对应 GET /meta-catalog。
 
         返回字段 catalog：每个字段的名称 / 类型 / filterable / sortable / default_returned /
         描述 / 适用 FilterOperator，外加 enum-like 字段的样本值（include_sample_values=True 时）。
+        collection 指定实体集合（papers 默认 / authors / sources），各 collection 字段集不同。
         Agent 第一次接触 Sciverse 或碰到字段不确定时建议先调一次再构造 search_papers。
         """
-        params = {"include_sample_values": str(include_sample_values).lower()}
+        params: dict[str, str] = {"include_sample_values": str(include_sample_values).lower()}
+        if include_field_stats:
+            params["include_field_stats"] = "true"
+        if collection:
+            params["collection"] = collection
         resp = await self._client.get("/meta-catalog", params=params)
         resp.raise_for_status()
         return resp.json()

{sciverse-0.7.2 → sciverse-0.8.0}/src/sciverse/tools.py

@@ -1,7 +1,7 @@
 """Auto-generated. Do not edit. Run scripts/build.sh."""
 import json
 
-TOOLS_VERSION = "0.7.2"
+TOOLS_VERSION = "0.8.0"
 
 OPENAI_TOOLS = json.loads(r"""
 [
@@ -13,6 +13,17 @@ OPENAI_TOOLS = json.loads(r"""
       "parameters": {
         "type": "object",
         "properties": {
+          "collection": {
+            "type": "string",
+            "enum": [
+              "papers",
+              "authors",
+              "sources"
+            ],
+            "default": "papers",
+            "description": "检索的实体集合。papers（默认，论文）/ authors（作者）/ sources（来源期刊）。 各 collection 字段集不同，用 list_catalog（collection=<name>）学习对应 schema。 注意：本工具的便捷字段（authors/journals/year_from/subjects 等）只对 papers 有意义； 查 authors/sources 时改用 filters_advanced + 该 collection 的字段名（如 authors 的 summary_stats.h_index / orcid，sources 的 issn / is_oa）。authors 用 orcid、 sources 用 issn 与论文检索结果关联。",
+            "x-en-description": "Entity collection to search. papers (default) / authors / sources. Each collection has its own field schema — call list_catalog(collection=<name>). The convenience fields (authors/journals/year_from/subjects) apply to papers only; for authors/sources use filters_advanced with that collection's field names."
+          },
           "query": {
             "type": "string",
             "description": "BM25 全文关键词，匹配标题/摘要/期刊名/关键词字段。留空则纯靠结构化过滤。"
@@ -69,6 +80,7 @@ OPENAI_TOOLS = json.loads(r"""
                 },
                 "operator": {
                   "type": "string",
+                  "description": "过滤操作符。MATCH（分词模糊）适用于 author、keywords（输入 \"Hinton\" 命中 \"Geoffrey Hinton\"）； MATCH_PHRASE（短语模糊）适用于 publication_venue_name_unified，整词连续匹配（\"Nature\" 命中 \"Nature Communications\"；非前缀匹配，\"Nature Comm\" 不会命中）； doi 用 EQ，服务端归一化（去 doi.org 前缀+转小写）后精确匹配。MATCH/MATCH_PHRASE 仅对配了 text 子字段的字段有效。",
                   "enum": [
                     "FILTER_OP_EQ",
                     "FILTER_OP_NE",
@@ -78,7 +90,9 @@ OPENAI_TOOLS = json.loads(r"""
                     "FILTER_OP_LTE",
                     "FILTER_OP_IN",
                     "FILTER_OP_NIN",
-                    "FILTER_OP_CONTAINS"
+                    "FILTER_OP_CONTAINS",
+                    "FILTER_OP_MATCH",
+                    "FILTER_OP_MATCH_PHRASE"
                   ],
                   "default": "FILTER_OP_EQ"
                 },
@@ -86,6 +100,30 @@ OPENAI_TOOLS = json.loads(r"""
               }
             }
           },
+          "sort_advanced": {
+            "type": "array",
+            "description": "高级排序逃生舱（按任意可排序字段）。papers 用 sort_by_year 即可； authors/sources 想按 h-index / 被引 / works_count 排序时用本字段。 与 query 互斥（query 走相关性排序）。",
+            "items": {
+              "type": "object",
+              "required": [
+                "field",
+                "order"
+              ],
+              "properties": {
+                "field": {
+                  "type": "string"
+                },
+                "order": {
+                  "type": "string",
+                  "enum": [
+                    "SORT_ORDER_DESC",
+                    "SORT_ORDER_ASC"
+                  ],
+                  "default": "SORT_ORDER_DESC"
+                }
+              }
+            }
+          },
           "sort_by_year": {
             "type": "string",
             "enum": [
@@ -175,16 +213,71 @@ OPENAI_TOOLS = json.loads(r"""
       "parameters": {
         "type": "object",
         "properties": {
+          "collection": {
+            "type": "string",
+            "enum": [
+              "papers",
+              "authors",
+              "sources"
+            ],
+            "default": "papers",
+            "description": "字段 catalog 所属实体集合。papers（默认）/ authors / sources，各 collection 字段不同。"
+          },
           "include_sample_values": {
             "type": "boolean",
             "default": false,
             "description": "是否拉取 enum-like 字段的取值样本。false 仅返回静态 schema（毫秒级）；true 触发 OpenSearch terms agg（首次几百毫秒，之后 24h 走缓存）。"
+          },
+          "include_field_stats": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否返回字段统计（keyword 字段基数 + 数值字段 min/max/avg/p50/p95）。触发 OpenSearch 聚合，缓存 24h。"
           }
         },
         "required": []
       }
     }
   },
+  {
+    "type": "function",
+    "function": {
+      "name": "list_paper_relations",
+      "description": "分页返回某篇论文的引用关系完整列表。citations/references/related_works 是无界数组\n（高被引文献可达数千条），search_papers 只内联截断少量，要翻完整列表用本接口。\n适用：「论文 X 引用了哪些文献」（relation=REFERENCES）、「哪些文献引用了论文 X」\n（relation=CITATIONS）、「与论文 X 相关的工作」（relation=RELATED_WORKS）。\n注意：CITATIONS（被引：谁引用了我）与 REFERENCES（参考文献：我引用了谁）方向相反。\n典型链路：先 search_papers / semantic_search 拿到 unique_id，再用本接口按 relation 分页。",
+      "parameters": {
+        "type": "object",
+        "required": [
+          "unique_id",
+          "relation"
+        ],
+        "properties": {
+          "unique_id": {
+            "type": "string",
+            "description": "目标论文 unique_id（如 paper:10.1038/xxx），来自 search_papers / semantic_search；勿传 doc_id。"
+          },
+          "relation": {
+            "type": "string",
+            "enum": [
+              "CITATIONS",
+              "REFERENCES",
+              "RELATED_WORKS"
+            ],
+            "description": "关系类型。CITATIONS=被引（谁引用了我）；REFERENCES=参考文献（我引用了谁）；RELATED_WORKS=相关工作。"
+          },
+          "page": {
+            "type": "integer",
+            "default": 1,
+            "minimum": 1
+          },
+          "page_size": {
+            "type": "integer",
+            "default": 25,
+            "minimum": 1,
+            "maximum": 200
+          }
+        }
+      }
+    }
+  },
   {
     "type": "function",
     "function": {
@@ -245,6 +338,17 @@ ANTHROPIC_TOOLS = json.loads(r"""
     "input_schema": {
       "type": "object",
       "properties": {
+        "collection": {
+          "type": "string",
+          "enum": [
+            "papers",
+            "authors",
+            "sources"
+          ],
+          "default": "papers",
+          "description": "检索的实体集合。papers（默认，论文）/ authors（作者）/ sources（来源期刊）。 各 collection 字段集不同，用 list_catalog（collection=<name>）学习对应 schema。 注意：本工具的便捷字段（authors/journals/year_from/subjects 等）只对 papers 有意义； 查 authors/sources 时改用 filters_advanced + 该 collection 的字段名（如 authors 的 summary_stats.h_index / orcid，sources 的 issn / is_oa）。authors 用 orcid、 sources 用 issn 与论文检索结果关联。",
+          "x-en-description": "Entity collection to search. papers (default) / authors / sources. Each collection has its own field schema — call list_catalog(collection=<name>). The convenience fields (authors/journals/year_from/subjects) apply to papers only; for authors/sources use filters_advanced with that collection's field names."
+        },
         "query": {
           "type": "string",
           "description": "BM25 全文关键词，匹配标题/摘要/期刊名/关键词字段。留空则纯靠结构化过滤。"
@@ -301,6 +405,7 @@ ANTHROPIC_TOOLS = json.loads(r"""
               },
               "operator": {
                 "type": "string",
+                "description": "过滤操作符。MATCH（分词模糊）适用于 author、keywords（输入 \"Hinton\" 命中 \"Geoffrey Hinton\"）； MATCH_PHRASE（短语模糊）适用于 publication_venue_name_unified，整词连续匹配（\"Nature\" 命中 \"Nature Communications\"；非前缀匹配，\"Nature Comm\" 不会命中）； doi 用 EQ，服务端归一化（去 doi.org 前缀+转小写）后精确匹配。MATCH/MATCH_PHRASE 仅对配了 text 子字段的字段有效。",
                 "enum": [
                   "FILTER_OP_EQ",
                   "FILTER_OP_NE",
@@ -310,7 +415,9 @@ ANTHROPIC_TOOLS = json.loads(r"""
                   "FILTER_OP_LTE",
                   "FILTER_OP_IN",
                   "FILTER_OP_NIN",
-                  "FILTER_OP_CONTAINS"
+                  "FILTER_OP_CONTAINS",
+                  "FILTER_OP_MATCH",
+                  "FILTER_OP_MATCH_PHRASE"
                 ],
                 "default": "FILTER_OP_EQ"
               },
@@ -318,6 +425,30 @@ ANTHROPIC_TOOLS = json.loads(r"""
             }
           }
         },
+        "sort_advanced": {
+          "type": "array",
+          "description": "高级排序逃生舱（按任意可排序字段）。papers 用 sort_by_year 即可； authors/sources 想按 h-index / 被引 / works_count 排序时用本字段。 与 query 互斥（query 走相关性排序）。",
+          "items": {
+            "type": "object",
+            "required": [
+              "field",
+              "order"
+            ],
+            "properties": {
+              "field": {
+                "type": "string"
+              },
+              "order": {
+                "type": "string",
+                "enum": [
+                  "SORT_ORDER_DESC",
+                  "SORT_ORDER_ASC"
+                ],
+                "default": "SORT_ORDER_DESC"
+              }
+            }
+          }
+        },
         "sort_by_year": {
           "type": "string",
           "enum": [
@@ -401,15 +532,67 @@ ANTHROPIC_TOOLS = json.loads(r"""
     "input_schema": {
       "type": "object",
       "properties": {
+        "collection": {
+          "type": "string",
+          "enum": [
+            "papers",
+            "authors",
+            "sources"
+          ],
+          "default": "papers",
+          "description": "字段 catalog 所属实体集合。papers（默认）/ authors / sources，各 collection 字段不同。"
+        },
         "include_sample_values": {
           "type": "boolean",
           "default": false,
           "description": "是否拉取 enum-like 字段的取值样本。false 仅返回静态 schema（毫秒级）；true 触发 OpenSearch terms agg（首次几百毫秒，之后 24h 走缓存）。"
+        },
+        "include_field_stats": {
+          "type": "boolean",
+          "default": false,
+          "description": "是否返回字段统计（keyword 字段基数 + 数值字段 min/max/avg/p50/p95）。触发 OpenSearch 聚合，缓存 24h。"
         }
       },
       "required": []
     }
   },
+  {
+    "name": "list_paper_relations",
+    "description": "分页返回某篇论文的引用关系完整列表。citations/references/related_works 是无界数组\n（高被引文献可达数千条），search_papers 只内联截断少量，要翻完整列表用本接口。\n适用：「论文 X 引用了哪些文献」（relation=REFERENCES）、「哪些文献引用了论文 X」\n（relation=CITATIONS）、「与论文 X 相关的工作」（relation=RELATED_WORKS）。\n注意：CITATIONS（被引：谁引用了我）与 REFERENCES（参考文献：我引用了谁）方向相反。\n典型链路：先 search_papers / semantic_search 拿到 unique_id，再用本接口按 relation 分页。",
+    "input_schema": {
+      "type": "object",
+      "required": [
+        "unique_id",
+        "relation"
+      ],
+      "properties": {
+        "unique_id": {
+          "type": "string",
+          "description": "目标论文 unique_id（如 paper:10.1038/xxx），来自 search_papers / semantic_search；勿传 doc_id。"
+        },
+        "relation": {
+          "type": "string",
+          "enum": [
+            "CITATIONS",
+            "REFERENCES",
+            "RELATED_WORKS"
+          ],
+          "description": "关系类型。CITATIONS=被引（谁引用了我）；REFERENCES=参考文献（我引用了谁）；RELATED_WORKS=相关工作。"
+        },
+        "page": {
+          "type": "integer",
+          "default": 1,
+          "minimum": 1
+        },
+        "page_size": {
+          "type": "integer",
+          "default": 25,
+          "minimum": 1,
+          "maximum": 200
+        }
+      }
+    }
+  },
   {
     "name": "read_content",
     "description": "按字节区间读取文献原文片段。通常配合 semantic_search 返回的 doc_id/offset 使用，\n用于扩展上下文（往前/往后读更多字节）。\n返回：UTF-8 文本片段、bytes_returned、next_offset、是否还有后续。",

{sciverse-0.7.2 → sciverse-0.8.0}/src/sciverse/types.py

@@ -9,7 +9,21 @@ from typing import Any
 from pydantic import BaseModel, Field
 
 
+class Collection(Enum):
+    """
+    检索的实体集合。papers（默认，论文）/ authors（作者）/ sources（来源期刊）。 各 collection 字段集不同，用 list_catalog（collection=<name>）学习对应 schema。 注意：本工具的便捷字段（authors/journals/year_from/subjects 等）只对 papers 有意义； 查 authors/sources 时改用 filters_advanced + 该 collection 的字段名（如 authors 的 summary_stats.h_index / orcid，sources 的 issn / is_oa）。authors 用 orcid、 sources 用 issn 与论文检索结果关联。
+    """
+
+    papers = "papers"
+    authors = "authors"
+    sources = "sources"
+
+
 class Operator(Enum):
+    """
+    过滤操作符。MATCH（分词模糊）适用于 author、keywords（输入 "Hinton" 命中 "Geoffrey Hinton"）； MATCH_PHRASE（短语模糊）适用于 publication_venue_name_unified，整词连续匹配（"Nature" 命中 "Nature Communications"；非前缀匹配，"Nature Comm" 不会命中）； doi 用 EQ，服务端归一化（去 doi.org 前缀+转小写）后精确匹配。MATCH/MATCH_PHRASE 仅对配了 text 子字段的字段有效。
+    """
+
     FILTER_OP_EQ = "FILTER_OP_EQ"
     FILTER_OP_NE = "FILTER_OP_NE"
     FILTER_OP_GT = "FILTER_OP_GT"
@@ -19,14 +33,29 @@ class Operator(Enum):
     FILTER_OP_IN = "FILTER_OP_IN"
     FILTER_OP_NIN = "FILTER_OP_NIN"
     FILTER_OP_CONTAINS = "FILTER_OP_CONTAINS"
+    FILTER_OP_MATCH = "FILTER_OP_MATCH"
+    FILTER_OP_MATCH_PHRASE = "FILTER_OP_MATCH_PHRASE"
 
 
 class FiltersAdvancedItem(BaseModel):
     field: str
-    operator: Operator | None = "FILTER_OP_EQ"
+    operator: Operator | None = Field(
+        "FILTER_OP_EQ",
+        description='过滤操作符。MATCH（分词模糊）适用于 author、keywords（输入 "Hinton" 命中 "Geoffrey Hinton"）； MATCH_PHRASE（短语模糊）适用于 publication_venue_name_unified，整词连续匹配（"Nature" 命中 "Nature Communications"；非前缀匹配，"Nature Comm" 不会命中）； doi 用 EQ，服务端归一化（去 doi.org 前缀+转小写）后精确匹配。MATCH/MATCH_PHRASE 仅对配了 text 子字段的字段有效。',
+    )
     value: Any
 
 
+class Order(Enum):
+    SORT_ORDER_DESC = "SORT_ORDER_DESC"
+    SORT_ORDER_ASC = "SORT_ORDER_ASC"
+
+
+class SortAdvancedItem(BaseModel):
+    field: str
+    order: Order
+
+
 class SortByYear(Enum):
     desc = "desc"
     asc = "asc"
@@ -48,6 +77,10 @@ class FreshnessBoost(Enum):
 
 
 class SearchPapersRequest(BaseModel):
+    collection: Collection | None = Field(
+        "papers",
+        description="检索的实体集合。papers（默认，论文）/ authors（作者）/ sources（来源期刊）。 各 collection 字段集不同，用 list_catalog（collection=<name>）学习对应 schema。 注意：本工具的便捷字段（authors/journals/year_from/subjects 等）只对 papers 有意义； 查 authors/sources 时改用 filters_advanced + 该 collection 的字段名（如 authors 的 summary_stats.h_index / orcid，sources 的 issn / is_oa）。authors 用 orcid、 sources 用 issn 与论文检索结果关联。",
+    )
     query: str | None = Field(
         None,
         description="BM25 全文关键词，匹配标题/摘要/期刊名/关键词字段。留空则纯靠结构化过滤。",
@@ -74,6 +107,10 @@ class SearchPapersRequest(BaseModel):
     filters_advanced: list[FiltersAdvancedItem] | None = Field(
         None, description="高级过滤逃生舱（仅当上述字段不够用时使用）。"
     )
+    sort_advanced: list[SortAdvancedItem] | None = Field(
+        None,
+        description="高级排序逃生舱（按任意可排序字段）。papers 用 sort_by_year 即可； authors/sources 想按 h-index / 被引 / works_count 排序时用本字段。 与 query 互斥（query 走相关性排序）。",
+    )
     sort_by_year: SortByYear | None = "desc"
     freshness_boost: FreshnessBoost | None = Field(
         "NONE",
@@ -83,6 +120,11 @@ class SearchPapersRequest(BaseModel):
     page_size: int | None = Field(10, ge=1, le=50)
 
 
+class AuthorItem(BaseModel):
+    name: str | None = None
+    orcid: str | None = None
+
+
 class PaperMetadata(BaseModel):
     """
     文献元数据。字段名与 metadata-service 后端 `fields.py` 的真实字段一致，
@@ -106,9 +148,9 @@ class PaperMetadata(BaseModel):
         description="全文 artifact 的内容哈希（sha256）。仅当文档存在全文时返回；元数据-only 记录无此字段，且无法用 doc_id 过滤命中。",
     )
     title: str
-    author: list[str] | None = Field(
+    author: list[AuthorItem] | None = Field(
         None,
-        description="作者列表（fields.py 中字段名是 author 单数，但类型是 List[string]）。",
+        description='作者列表（OS object 数组，子字段 name/orcid）。按作者名检索：精确走 author.name.keyword、模糊 MATCH 走 author.name；对外过滤仍传 field "author"。',
     )
     abstract: str | None = None
     publication_venue_name_unified: str | None = Field(
@@ -201,10 +243,25 @@ class ApiError(BaseModel):
 
 
 class SearchPapersResponse(BaseModel):
-    hits: list[PaperMetadata]
-    total: int
+    results: list[PaperMetadata] = Field(
+        ..., description="命中论文列表（后端字段名为 results，非 hits）。"
+    )
+    total_count: int = Field(
+        ...,
+        description="命中总数；超过 10000 会被截断为 10000，需精确值时改用深翻页/计数。",
+    )
     page: int
     page_size: int
+    total_pages: int | None = Field(None, description="总页数。")
+    next_cursor: str | None = Field(
+        None,
+        description="深翻页游标，为空表示无更多。page*page_size>10000 时必须改用 cursor（把此值回填到请求的 cursor）。",
+    )
+    search_time_ms: float | None = Field(None, description="检索耗时（毫秒）。")
+    request_tokens: int | None = Field(None, description="输入 query 的 token 数。")
+    response_tokens: int | None = Field(
+        None, description="输出结果文本字段的 token 数。"
+    )
 
 
 class SemanticSearchResponse(BaseModel):

{sciverse-0.7.2 → sciverse-0.8.0}/uv.lock

@@ -323,7 +323,7 @@ wheels = [
 
 [[package]]
 name = "sciverse"
-version = "0.7.1"
+version = "0.7.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },