sciverse 0.3.0

package/dist/types.d.ts

@@ -0,0 +1,370 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/meta-search": {
+        /**
+         * 按结构化条件检索学术文献元数据
+         * @description 按结构化条件检索学术文献元数据（标题、作者、期刊、年份、摘要等）。
+         * 适用：「查找 Hinton 在 2020-2023 年发表的论文」「找 Nature 上关于 CRISPR 的近期文献」。
+         * 不适用：自然语言问答检索 → 用 semantic_search；查全文片段 → 用 read_content。
+         * 返回：论文元数据列表，每条含 doc_id、title、author、abstract、publication_venue_name、publication_published_year 等。
+         */
+        post: operations["search_papers"];
+    };
+    "/agentic-search": {
+        /**
+         * 自然语言语义检索（RAG 用）
+         * @description 自然语言语义检索，返回相关文献片段（chunk）用于 RAG 回答。
+         * 适用：「Transformer 注意力机制如何工作？」「最新的蛋白质折叠预测方法有哪些？」
+         * 不适用：精确字段过滤 → search_papers；取完整原文 → read_content。
+         * 返回：相关 chunk 列表，每条含 chunk_id/doc_id/abstract/chunk/score/title/offset。
+         * 典型链路：semantic_search → 选取 chunk → read_content(doc_id, offset)。
+         */
+        post: operations["semantic_search"];
+    };
+    "/meta-catalog": {
+        /**
+         * 列出所有可用字段、能否过滤/排序、枚举值样本
+         * @description 返回 search_papers 所有可用字段的 catalog：字段名、类型、能否过滤/排序、
+         * 是否默认返回、字段说明、FilterOperator 清单等。
+         * 适用：「我该用哪个字段过滤 DOI?」「access_oa_status 有哪些可能值？」
+         * 「`metadata_type` 的合法取值是？」
+         * 不适用：实际查询文献，那是 search_papers / semantic_search 的事。
+         * 典型用法：Agent 第一次接触 SciVerse 或碰到模糊字段需求时先调一次本接口，
+         * 把 schema 装进 working memory，后续精确构造 search_papers 的 filters。
+         * include_sample_values=true 时返回枚举值样本（OpenSearch terms agg，缓存 24h）。
+         */
+        get: operations["list_catalog"];
+    };
+    "/content": {
+        /**
+         * 按字节区间读取文献原文片段
+         * @description 按字节区间读取文献原文片段。通常配合 semantic_search 返回的 doc_id/offset 使用，
+         * 用于扩展上下文（往前/往后读更多字节）。
+         * 返回：UTF-8 文本片段、bytes_returned、next_offset、是否还有后续。
+         */
+        get: operations["read_content"];
+    };
+    "/resource": {
+        /**
+         * 取文献附属图片（论文中的 Figure / Table 等）
+         * @description 按文件名取文献中嵌入的图片字节流（PNG / JPG 等）。
+         * 触发场景：read_content 返回的 Markdown 中含 `![alt](file_name)` 形式的图片占位，
+         * agent 需要把图给用户看时调本接口。
+         * 入参 file_name 来自 markdown 内的 url 段（相对路径，禁止 `\\` 或 `..`）。
+         * 返回：HTTP 二进制流 + image/* Content-Type。
+         * SDK / MCP server 包装层会做 base64 + mime 转换以便 agent 多模态使用。
+         */
+        get: operations["get_resource"];
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        SearchPapersRequest: {
+            /** @description BM25 全文关键词，匹配标题/摘要/期刊名/关键词字段。留空则纯靠结构化过滤。 */
+            query?: string;
+            /** @description 标题中必须包含的词（仅匹配 title 字段）。 */
+            title_contains?: string;
+            /** @description 摘要中必须包含的词（仅匹配 abstract 字段）。 */
+            abstract_contains?: string;
+            /** @description 作者名（任一命中即可）。SDK 内部映射到后端 `author` 字段（FILTER_OP_IN）。 */
+            authors?: string[];
+            /** @description 起始发表年（含）。 */
+            year_from?: number;
+            /** @description 结束发表年（含）。 */
+            year_to?: number;
+            /** @description 期刊名（任一命中即可）。SDK 内部映射到后端 `publication_venue_name` 字段（FILTER_OP_IN）。 */
+            journals?: string[];
+            /** @description 学科分类，如 "computer science"、"biology"。 */
+            subjects?: string[];
+            /** @description 高级过滤逃生舱（仅当上述字段不够用时使用）。 */
+            filters_advanced?: ({
+                field: string;
+                /**
+                 * @default FILTER_OP_EQ
+                 * @enum {string}
+                 */
+                operator?: "FILTER_OP_EQ" | "FILTER_OP_NE" | "FILTER_OP_GT" | "FILTER_OP_GTE" | "FILTER_OP_LT" | "FILTER_OP_LTE" | "FILTER_OP_IN" | "FILTER_OP_NIN" | "FILTER_OP_CONTAINS";
+                value: unknown;
+            })[];
+            /**
+             * @default desc
+             * @enum {string}
+             */
+            sort_by_year?: "desc" | "asc" | "none";
+            /** @default 1 */
+            page?: number;
+            /** @default 10 */
+            page_size?: number;
+        };
+        SearchPapersResponse: {
+            hits: components["schemas"]["PaperMetadata"][];
+            total: number;
+            page: number;
+            page_size: number;
+        };
+        /**
+         * @description 文献元数据。字段名与 metadata-service 后端 `fields.py` 的真实字段一致，
+         * SDK 不做响应转换。`doc_id` 由 metadata-service 注入（OpenSearch `_id`）。
+         */
+        PaperMetadata: {
+            /** @description 文献唯一 ID（OpenSearch _id，通常为内容 sha256）。 */
+            doc_id: string;
+            title: string;
+            /** @description 作者列表（fields.py 中字段名是 author 单数，但类型是 List[string]）。 */
+            author?: string[];
+            abstract?: string;
+            /** @description 期刊/会议名（fields.py 中是 String 类型）。 */
+            publication_venue_name?: string;
+            publication_published_year?: number;
+            subjects?: string[];
+            keywords?: string[];
+            doi?: string;
+        };
+        SemanticSearchRequest: {
+            /** @description 自然语言查询，1-200 字最佳。 */
+            query: string;
+            /** @default 10 */
+            top_k?: number;
+            source_types?: ("web" | "pdf")[];
+            /**
+             * @description fast = 仅关键词召回 (~200ms)；balanced = 混合检索 (~600ms)；quality = LLM 改写 + 混合 (~2-4s)。
+             *
+             * @default balanced
+             * @enum {string}
+             */
+            mode?: "fast" | "balanced" | "quality";
+        };
+        SemanticSearchResponse: {
+            hits: components["schemas"]["SearchChunk"][];
+        };
+        SearchChunk: {
+            chunk_id: string;
+            doc_id: string;
+            title: string;
+            abstract?: string;
+            chunk?: string;
+            /** Format: float */
+            score: number;
+            /**
+             * Format: int64
+             * @description chunk 在原文中的字节偏移，可直接传给 read_content。
+             */
+            offset: number;
+            page_no?: number;
+            source_type?: string;
+        };
+        ReadContentResponse: {
+            text: string;
+            bytes_returned: number;
+            /** Format: int64 */
+            next_offset: number;
+            /** @description 为 true 表示可能还有后续字节，可用 next_offset 继续请求。 */
+            more: boolean;
+        };
+        CatalogResponse: {
+            fields: components["schemas"]["FieldCatalogEntry"][];
+            /** @description search_papers 不传 fields 时默认返回的字段名清单。 */
+            default_fields: string[];
+            /** @description 支持的 FilterOperator 名（不带 FILTER_OP_ 前缀，如 "EQ" / "IN" / "CONTAINS"）。 */
+            filter_operators: string[];
+        };
+        FieldCatalogEntry: {
+            /** @description 字段名（与 search_papers 的 filters[].field 一致）。 */
+            name: string;
+            /** @description 业务类型，如 String / Integer / Boolean / Float / List[string] / List[object] / Object。 */
+            type: string;
+            filterable: boolean;
+            sortable: boolean;
+            /** @description 是否参与 query（BM25 全文搜索）。 */
+            searchable: boolean;
+            /** @description 未指定 fields 时是否默认返回。 */
+            default_returned: boolean;
+            /** @description 人类可读的字段说明（中文）。 */
+            description?: string;
+            /** @description 该字段的取值样本（仅 enum-like 字段；高 cardinality 字段为空）。 */
+            sample_values?: string[];
+            /** @description 适用的 FilterOperator 名（参考性，后端不强校验）。 */
+            operators?: string[];
+        };
+        ApiError: {
+            code: string;
+            message: string;
+            request_id?: string;
+        };
+    };
+    responses: {
+        /** @description 请求参数错误 */
+        BadRequest: {
+            content: {
+                "application/json": components["schemas"]["ApiError"];
+            };
+        };
+        /** @description Bearer Token 缺失或无效 */
+        Unauthorized: {
+            content: {
+                "application/json": components["schemas"]["ApiError"];
+            };
+        };
+        /** @description 上游服务不可用 */
+        BadGateway: {
+            content: {
+                "application/json": components["schemas"]["ApiError"];
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export type external = Record<string, never>;
+export interface operations {
+    /**
+     * 按结构化条件检索学术文献元数据
+     * @description 按结构化条件检索学术文献元数据（标题、作者、期刊、年份、摘要等）。
+     * 适用：「查找 Hinton 在 2020-2023 年发表的论文」「找 Nature 上关于 CRISPR 的近期文献」。
+     * 不适用：自然语言问答检索 → 用 semantic_search；查全文片段 → 用 read_content。
+     * 返回：论文元数据列表，每条含 doc_id、title、author、abstract、publication_venue_name、publication_published_year 等。
+     */
+    search_papers: {
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SearchPapersRequest"];
+            };
+        };
+        responses: {
+            /** @description 检索结果 */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["SearchPapersResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["BadGateway"];
+        };
+    };
+    /**
+     * 自然语言语义检索（RAG 用）
+     * @description 自然语言语义检索，返回相关文献片段（chunk）用于 RAG 回答。
+     * 适用：「Transformer 注意力机制如何工作？」「最新的蛋白质折叠预测方法有哪些？」
+     * 不适用：精确字段过滤 → search_papers；取完整原文 → read_content。
+     * 返回：相关 chunk 列表，每条含 chunk_id/doc_id/abstract/chunk/score/title/offset。
+     * 典型链路：semantic_search → 选取 chunk → read_content(doc_id, offset)。
+     */
+    semantic_search: {
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SemanticSearchRequest"];
+            };
+        };
+        responses: {
+            /** @description 检索结果 */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["SemanticSearchResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["BadGateway"];
+            /** @description 嵌入或检索后端暂不可用 */
+            503: {
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+        };
+    };
+    /**
+     * 列出所有可用字段、能否过滤/排序、枚举值样本
+     * @description 返回 search_papers 所有可用字段的 catalog：字段名、类型、能否过滤/排序、
+     * 是否默认返回、字段说明、FilterOperator 清单等。
+     * 适用：「我该用哪个字段过滤 DOI?」「access_oa_status 有哪些可能值？」
+     * 「`metadata_type` 的合法取值是？」
+     * 不适用：实际查询文献，那是 search_papers / semantic_search 的事。
+     * 典型用法：Agent 第一次接触 SciVerse 或碰到模糊字段需求时先调一次本接口，
+     * 把 schema 装进 working memory，后续精确构造 search_papers 的 filters。
+     * include_sample_values=true 时返回枚举值样本（OpenSearch terms agg，缓存 24h）。
+     */
+    list_catalog: {
+        parameters: {
+            query?: {
+                /** @description 是否拉取 enum-like 字段的取值样本。false 仅返回静态 schema（毫秒级）；true 触发 OpenSearch terms agg（首次几百毫秒，之后 24h 走缓存）。 */
+                include_sample_values?: boolean;
+            };
+        };
+        responses: {
+            /** @description catalog */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["CatalogResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["BadGateway"];
+        };
+    };
+    /**
+     * 按字节区间读取文献原文片段
+     * @description 按字节区间读取文献原文片段。通常配合 semantic_search 返回的 doc_id/offset 使用，
+     * 用于扩展上下文（往前/往后读更多字节）。
+     * 返回：UTF-8 文本片段、bytes_returned、next_offset、是否还有后续。
+     */
+    read_content: {
+        parameters: {
+            query: {
+                /** @description 文献 ID（来自 search_papers / semantic_search）。 */
+                doc_id: string;
+                offset?: number;
+                limit?: number;
+            };
+        };
+        responses: {
+            /** @description 内容片段 */
+            200: {
+                content: {
+                    "application/json": components["schemas"]["ReadContentResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["BadGateway"];
+        };
+    };
+    /**
+     * 取文献附属图片（论文中的 Figure / Table 等）
+     * @description 按文件名取文献中嵌入的图片字节流（PNG / JPG 等）。
+     * 触发场景：read_content 返回的 Markdown 中含 `![alt](file_name)` 形式的图片占位，
+     * agent 需要把图给用户看时调本接口。
+     * 入参 file_name 来自 markdown 内的 url 段（相对路径，禁止 `\\` 或 `..`）。
+     * 返回：HTTP 二进制流 + image/* Content-Type。
+     * SDK / MCP server 包装层会做 base64 + mime 转换以便 agent 多模态使用。
+     */
+    get_resource: {
+        parameters: {
+            query: {
+                /** @description 图片相对路径，来自 read_content Markdown 中的 `![alt](file_name)` 占位。禁止 `\\` 与 `..`，不能以 `/` 开头。 */
+                file_name: string;
+            };
+        };
+        responses: {
+            /** @description 图片二进制流 */
+            200: {
+                content: {
+                    "image/png": string;
+                    "image/jpeg": string;
+                    "image/*": string;
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["BadGateway"];
+        };
+    };
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "sciverse",
+  "version": "0.3.0",
+  "description": "SciVerse Agent Tools — OpenAI/Anthropic/LangChain compatible tool schema and async client for SciVerse retrieval APIs",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/opendatalab/SciVerse-agent-tools/tree/main/packages/typescript",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opendatalab/SciVerse-agent-tools.git",
+    "directory": "packages/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/opendatalab/SciVerse-agent-tools/issues"
+  },
+  "author": "SciVerse Platform Team",
+  "keywords": [
+    "sciverse",
+    "agent",
+    "llm",
+    "tool-calling",
+    "scientific-papers",
+    "rag"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4",
+    "vitest": "^1.4",
+    "openapi-typescript": "^6.7",
+    "msw": "^2.0",
+    "@types/node": "^20"
+  }
+}