sciverse 0.3.0__py3-none-any.whl

sciverse/__init__.py

@@ -0,0 +1,25 @@
+"""SciVerse Agent Tools - Python SDK."""
+from sciverse.client import AgentToolsClient
+from sciverse.credentials import (
+    credentials_path,
+    delete_credentials,
+    load_credentials,
+    resolve_endpoint,
+    resolve_token,
+    save_credentials,
+)
+from sciverse.tools import OPENAI_TOOLS, ANTHROPIC_TOOLS, TOOLS_VERSION
+
+__version__ = "0.3.0"
+__all__ = [
+    "AgentToolsClient",
+    "OPENAI_TOOLS",
+    "ANTHROPIC_TOOLS",
+    "TOOLS_VERSION",
+    "credentials_path",
+    "delete_credentials",
+    "load_credentials",
+    "resolve_endpoint",
+    "resolve_token",
+    "save_credentials",
+]

sciverse/cli.py

@@ -0,0 +1,142 @@
+"""`sciverse` CLI —— 主要为用户提供本地凭据管理。
+
+设计选择：当前不实现完整 OAuth device-code flow（需要后端 + 控制台前端配套）。
+走"token paste"模式 —— 体验类似 `aws configure` / `gh auth login (--with-token)`，
+用户从控制台复制 token 粘贴，CLI 保存到 ~/.sciverse/credentials.json (0600)。
+后续后端就绪后可无痛升级到 device-code（保留同样命令接口）。
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+from typing import Sequence
+
+from .credentials import (
+    DEFAULT_ENDPOINT,
+    credentials_path,
+    delete_credentials,
+    load_credentials,
+    save_credentials,
+)
+
+CONSOLE_TOKEN_URL = "https://sciverse.space/tokens"
+
+
+def _cmd_login(args: argparse.Namespace) -> int:
+    print("SciVerse 登录")
+    print("-" * 40)
+    print(f"1. 浏览器将打开控制台 token 页：{CONSOLE_TOKEN_URL}")
+    print("2. 登录后创建 / 复制一个 API Token（形如 sv-xxx）")
+    print("3. 把 token 粘贴回这里")
+    print()
+
+    if not args.no_browser:
+        try:
+            webbrowser.open(CONSOLE_TOKEN_URL)
+        except Exception:
+            print(f"[warn] 无法自动打开浏览器，请手动访问 {CONSOLE_TOKEN_URL}")
+
+    # 用 getpass 避免 token 在 shell history 留痕
+    if args.token:
+        token = args.token.strip()
+    else:
+        try:
+            from getpass import getpass
+            token = getpass("Token: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n已取消", file=sys.stderr)
+            return 1
+
+    if not token:
+        print("错误：token 为空", file=sys.stderr)
+        return 1
+    if not token.startswith("sv-"):
+        print(
+            "[warn] token 看起来不像 SciVerse 格式（应以 sv- 开头），"
+            "但仍按用户输入保存。",
+            file=sys.stderr,
+        )
+
+    endpoint = args.endpoint or DEFAULT_ENDPOINT
+    path = save_credentials(token, endpoint)
+    print(f"✓ 凭据已保存到 {path}（权限 0600）")
+    print(f"  endpoint: {endpoint}")
+    print()
+    print("现在 Python / TS SDK / MCP server 不需要再传 token —— 会自动读取本文件。")
+    print("更换 token：再跑一次 `sciverse auth login`。")
+    print("删除：`sciverse auth logout`。")
+    return 0
+
+
+def _cmd_logout(_: argparse.Namespace) -> int:
+    if delete_credentials():
+        print(f"✓ 已删除 {credentials_path()}")
+        return 0
+    print(f"凭据文件不存在：{credentials_path()}", file=sys.stderr)
+    return 1
+
+
+def _cmd_status(_: argparse.Namespace) -> int:
+    path = credentials_path()
+    creds = load_credentials()
+    if creds is None:
+        print(f"未登录。运行 `sciverse auth login` 完成登录。")
+        print(f"凭据文件路径（未创建）：{path}")
+        return 1
+    token = creds.get("token", "")
+    masked = (token[:6] + "…" + token[-4:]) if len(token) > 12 else "***"
+    print(f"已登录")
+    print(f"  凭据文件: {path}")
+    print(f"  token:    {masked}")
+    print(f"  endpoint: {creds.get('endpoint', DEFAULT_ENDPOINT)}")
+    print(f"  保存时间: {creds.get('saved_at', '?')}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sciverse",
+        description="SciVerse 开发者工具 CLI。",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    auth = sub.add_parser("auth", help="本地凭据管理")
+    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
+
+    login = auth_sub.add_parser(
+        "login",
+        help="保存 API Token 到 ~/.sciverse/credentials.json",
+    )
+    login.add_argument(
+        "--token",
+        help="直接传入 token（跳过交互式粘贴；适合脚本场景）",
+    )
+    login.add_argument(
+        "--endpoint",
+        help=f"API endpoint，默认 {DEFAULT_ENDPOINT}",
+    )
+    login.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="不自动打开浏览器（远程 / 无桌面环境）",
+    )
+    login.set_defaults(func=_cmd_login)
+
+    logout = auth_sub.add_parser("logout", help="删除本地凭据文件")
+    logout.set_defaults(func=_cmd_logout)
+
+    status = auth_sub.add_parser("status", help="查看当前凭据状态")
+    status.set_defaults(func=_cmd_status)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sciverse/client.py

@@ -0,0 +1,177 @@
+"""SciVerse Agent Tools 异步 HTTP client。"""
+from __future__ import annotations
+
+import platform
+import uuid
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+_SKILL_NAME = "sciverse"
+_CHANNEL = "python-sdk"
+_PLATFORM = platform.system().lower()  # "linux" | "darwin" | "windows"
+
+
+_PASSTHROUGH = ("query", "page", "page_size", "fields")
+
+
+def _to_backend_payload(kwargs: dict[str, Any]) -> dict[str, Any]:
+    """把 search_papers 高级参数映射为 platform-console MetaSearchBody 接受的
+    canonical 格式（query/filters/sort/fields/page/page_size）。"""
+    out: dict[str, Any] = {}
+    filters: list[dict[str, Any]] = []
+    sort: list[dict[str, str]] = []
+
+    for k in _PASSTHROUGH:
+        if k in kwargs and kwargs[k] is not None:
+            out[k] = kwargs[k]
+
+    def _filter(field: str, op: str, value: Any) -> None:
+        filters.append({"field": field, "operator": op, "value": value})
+
+    if (v := kwargs.get("title_contains")) is not None:
+        _filter("title", "FILTER_OP_CONTAINS", v)
+    if (v := kwargs.get("abstract_contains")) is not None:
+        _filter("abstract", "FILTER_OP_CONTAINS", v)
+    if (v := kwargs.get("authors")) is not None and len(v) > 0:
+        _filter("author", "FILTER_OP_IN", list(v))
+    if (v := kwargs.get("year_from")) is not None:
+        _filter("publication_published_year", "FILTER_OP_GTE", v)
+    if (v := kwargs.get("year_to")) is not None:
+        _filter("publication_published_year", "FILTER_OP_LTE", v)
+    if (v := kwargs.get("journals")) is not None and len(v) > 0:
+        _filter("publication_venue_name", "FILTER_OP_IN", list(v))
+    if (v := kwargs.get("subjects")) is not None and len(v) > 0:
+        _filter("subjects", "FILTER_OP_IN", list(v))
+    if (v := kwargs.get("filters_advanced")) is not None:
+        for item in v:
+            entry = dict(item)
+            entry.setdefault("operator", "FILTER_OP_EQ")
+            filters.append(entry)
+
+    sort_by_year = kwargs.get("sort_by_year")
+    if sort_by_year and sort_by_year != "none":
+        sort.append({
+            "field": "publication_published_year",
+            "order": "SORT_ORDER_DESC" if sort_by_year == "desc" else "SORT_ORDER_ASC",
+        })
+
+    if filters:
+        out["filters"] = filters
+    if sort:
+        out["sort"] = sort
+    return out
+
+
+class AgentToolsClient:
+    """封装 SciVerse 三个对外检索接口的 Bearer-authenticated 异步 client。
+
+    用法：
+        async with AgentToolsClient(base_url=..., token=...) as c:
+            r = await c.semantic_search(query="...")
+
+    token / base_url 都可省略 —— 省略时按以下顺序 fallback：
+        1. 显式参数
+        2. 环境变量 SCIVERSE_API_TOKEN / SCIVERSE_BASE_URL
+        3. ~/.sciverse/credentials.json（由 `sciverse auth login` 写入）
+        4. base_url 默认值 https://api.sciverse.space；token 找不到则抛 ValueError
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        from sciverse.credentials import resolve_endpoint, resolve_token
+        resolved_token = resolve_token(token)
+        if not resolved_token:
+            raise ValueError(
+                "未找到 SciVerse API Token。请显式传 token、或设 SCIVERSE_API_TOKEN 环境变量、"
+                "或运行 `sciverse auth login` 保存凭据到 ~/.sciverse/credentials.json。"
+            )
+        self._base_url = resolve_endpoint(base_url).rstrip("/")
+        self._token = resolved_token
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {resolved_token}"},
+            event_hooks={"request": [self._inject_request_id]},
+        )
+
+    @staticmethod
+    async def _inject_request_id(request: httpx.Request) -> None:
+        request.headers["X-Request-Id"] = f"{_SKILL_NAME}-{_PLATFORM}-{_CHANNEL}-{uuid.uuid4()}"
+
+    async def __aenter__(self) -> "AgentToolsClient":
+        return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def search_papers(self, **kwargs: Any) -> dict[str, Any]:
+        """对应 POST /meta-search。
+
+        参数会被转换为后端 canonical 格式。Agent 友好参数：
+        - query, page, page_size, fields  （透传）
+        - title_contains, abstract_contains  → filter CONTAINS
+        - authors  → filter author IN
+        - year_from, year_to  → filter publication_published_year GTE/LTE
+        - journals  → filter publication_venue_name IN
+        - subjects  → filter subjects IN
+        - filters_advanced  → 直接拼到 filters 列表
+        - sort_by_year  → sort publication_published_year DESC/ASC
+        """
+        body = _to_backend_payload(kwargs)
+        resp = await self._client.post("/meta-search", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def semantic_search(self, *, query: str, **kwargs: Any) -> dict[str, Any]:
+        """对应 POST /agentic-search。"""
+        body = {"query": query, **{k: v for k, v in kwargs.items() if v is not None}}
+        resp = await self._client.post("/agentic-search", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_catalog(self, *, include_sample_values: bool = False) -> dict[str, Any]:
+        """对应 GET /meta-catalog。
+
+        返回字段 catalog：每个字段的名称 / 类型 / filterable / sortable / default_returned /
+        描述 / 适用 FilterOperator，外加 enum-like 字段的样本值（include_sample_values=True 时）。
+        Agent 第一次接触 SciVerse 或碰到字段不确定时建议先调一次再构造 search_papers。
+        """
+        params = {"include_sample_values": str(include_sample_values).lower()}
+        resp = await self._client.get("/meta-catalog", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def read_content(self, *, doc_id: str, offset: int = 0, limit: int = 4096) -> dict[str, Any]:
+        """对应 GET /content。"""
+        params = {"doc_id": doc_id, "offset": offset, "limit": limit}
+        resp = await self._client.get("/content", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_resource(self, *, file_name: str) -> tuple[bytes, str]:
+        """对应 GET /resource。
+
+        取文献附属图片字节流。触发场景：read_content 返回的 Markdown 中含
+        `![alt](file_name)` 图片占位时，调本接口拿图片 binary。
+
+        返回 (bytes, mime_type)。mime_type 来自响应头 content-type，如
+        "image/png" / "image/jpeg" / "application/octet-stream"。
+        """
+        resp = await self._client.get(
+            "/resource",
+            params={"file_name": file_name},
+            headers={"accept": "image/*"},
+        )
+        resp.raise_for_status()
+        mime = (resp.headers.get("content-type") or "application/octet-stream").split(";")[0].strip()
+        return resp.content, mime

sciverse/credentials.py

@@ -0,0 +1,107 @@
+"""共享凭据文件读写。
+
+约定（与 MCP server / TS SDK 一致）：
+- 路径：`~/.sciverse/credentials.json`
+- 文件权限：0600（仅当前用户可读写）
+- 内容：
+  {
+    "token": "sv-xxx",
+    "endpoint": "https://api.sciverse.space",
+    "saved_at": "2026-05-14T15:30:00Z"
+  }
+
+读取顺序（client.py / cli.py 共用）：
+  1. 显式构造 client 传 token
+  2. 环境变量 SCIVERSE_API_TOKEN
+  3. 凭据文件
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TypedDict
+
+
+class Credentials(TypedDict, total=False):
+    token: str
+    endpoint: str
+    saved_at: str
+
+
+DEFAULT_ENDPOINT = "https://api.sciverse.space"
+
+
+def credentials_path() -> Path:
+    return Path.home() / ".sciverse" / "credentials.json"
+
+
+def load_credentials() -> Credentials | None:
+    """读凭据文件。文件不存在 / 解析失败 / 不是 dict 时返回 None（不抛错）。"""
+    path = credentials_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data  # type: ignore[return-value]
+
+
+def save_credentials(token: str, endpoint: str = DEFAULT_ENDPOINT) -> Path:
+    """保存凭据到 ~/.sciverse/credentials.json，文件权限设为 0600。返回 path。"""
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload: Credentials = {
+        "token": token,
+        "endpoint": endpoint,
+        "saved_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+    }
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    # 0600
+    try:
+        path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        # Windows / 某些 FS 不支持 chmod；保留文件，不抛错
+        pass
+    return path
+
+
+def delete_credentials() -> bool:
+    """删凭据文件。文件不存在时返回 False，删除成功返回 True。"""
+    path = credentials_path()
+    if not path.exists():
+        return False
+    path.unlink()
+    return True
+
+
+def resolve_token(explicit: str | None = None) -> str | None:
+    """按 [显式参数 → SCIVERSE_API_TOKEN → 凭据文件] 顺序返回 token，
+    都没有时返回 None（不抛错；让调用方决定怎么提示用户）。"""
+    if explicit:
+        return explicit
+    env_token = os.environ.get("SCIVERSE_API_TOKEN")
+    if env_token:
+        return env_token
+    creds = load_credentials()
+    if creds and creds.get("token"):
+        return creds["token"]
+    return None
+
+
+def resolve_endpoint(explicit: str | None = None) -> str:
+    """按 [显式参数 → SCIVERSE_BASE_URL → 凭据文件 → 默认值] 顺序返回 endpoint。"""
+    if explicit:
+        return explicit
+    env_url = os.environ.get("SCIVERSE_BASE_URL")
+    if env_url:
+        return env_url
+    creds = load_credentials()
+    if creds and creds.get("endpoint"):
+        return creds["endpoint"]
+    return DEFAULT_ENDPOINT