metaso-sdk 0.1.0__py3-none-any.whl

metaso_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""metaso-sdk package.
+
+The official Python SDK for https://metaso.cn
+"""
+
+from __future__ import annotations
+
+from .model import File, Query, Status, Topic
+from .search import search
+from .subject import create_topic, delete_file, delete_topic, update_progress, upload_directory, upload_file
+
+__all__: list[str] = [
+    Status,
+    Query,
+    Topic,
+    File,
+    search,
+    create_topic,
+    delete_topic,
+    upload_file,
+    update_progress,
+    delete_file,
+    upload_directory,
+]

metaso_sdk/__main__.py

@@ -0,0 +1,14 @@
+"""Entry-point module, in case you use `python -m metaso_sdk`.
+
+Why does this file exist, and why `__main__`? For more info, read:
+
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+import sys
+
+from metaso_sdk.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

metaso_sdk/cli.py

@@ -0,0 +1,58 @@
+"""Module that contains the command line application."""
+
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m metaso_sdk` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `metaso_sdk.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `metaso_sdk.__main__` in `sys.modules`.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from metaso_sdk import debug
+
+
+class _DebugInfo(argparse.Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        debug.print_debug_info()
+        sys.exit(0)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the CLI argument parser.
+
+    Returns:
+        An argparse parser.
+    """
+    parser = argparse.ArgumentParser(prog="metaso")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug.get_version()}")
+    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
+    return parser
+
+
+def main(args: list[str] | None = None) -> int:
+    """Run the main program.
+
+    This function is executed when you type `metaso` or `python -m metaso_sdk`.
+
+    Parameters:
+        args: Arguments passed from the command line.
+
+    Returns:
+        An exit code.
+    """
+    parser = get_parser()
+    opts = parser.parse_args(args=args)
+    print(opts)
+    return 0

metaso_sdk/client.py

@@ -0,0 +1,11 @@
+import os
+
+import httpx
+
+api_key = os.getenv("METASO_API_KEY", "")
+
+client = httpx.Client(
+    base_url="https://metaso.cn/api/open",
+    headers={"Authorization": f"Bearer {api_key}"},
+    timeout=60,
+)

metaso_sdk/debug.py

@@ -0,0 +1,109 @@
+"""Debugging utilities."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+
+
+@dataclass
+class Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class Package:
+    """Dataclass describing a Python package."""
+
+    name: str
+    """Package name."""
+    version: str
+    """Package version."""
+
+
+@dataclass
+class Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[Package]
+    """Installed packages."""
+    variables: list[Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def get_version(dist: str = "metaso-sdk") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def get_debug_info() -> Environment:
+    """Get debug/environment information.
+
+    Returns:
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages = ["metaso-sdk"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("METASO_SDK")]]
+    return Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[Package(pkg, get_version(pkg)) for pkg in packages],
+    )
+
+
+def print_debug_info() -> None:
+    """Print debug/environment information."""
+    info = get_debug_info()
+    print(f"- __System__: {info.platform}")
+    print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
+    print("- __Environment variables__:")
+    for var in info.variables:
+        print(f"  - `{var.name}`: `{var.value}`")
+    print("- __Installed packages__:")
+    for pkg in info.packages:
+        print(f"  - `{pkg.name}` v{pkg.version}")
+
+
+if __name__ == "__main__":
+    print_debug_info()

metaso_sdk/model.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class Status(BaseModel):
+    errCode: int
+    errMsg: str
+
+
+class Query(BaseModel):
+    question: str
+    lang: str = "zh"
+    sessionId: Optional[str] = None
+    stream: bool = False
+    topicId: Optional[str] = None
+    searchTopicId: Optional[str] = None
+
+
+class Topic(BaseModel):
+    id: Optional[str] = None
+    name: str
+    dirRootId: Optional[str] = None
+    description: Optional[str] = None
+
+
+class File(BaseModel):
+    id: Optional[str]
+    fileName: str
+    parentId: str
+    contentType: str
+    size: int
+    previewUrl: Optional[str] = None
+    originalUrl: Optional[str] = None
+    progress: int

metaso_sdk/search.py

@@ -0,0 +1,35 @@
+import json
+
+from httpx_sse import EventSource, connect_sse
+
+from .client import client
+from .model import Query, Topic
+
+EventSource._check_content_type = lambda self: True
+
+
+def search(query: Query, *, stream: bool = False, topic: Topic = None):
+    """搜索功能的函数注释。
+
+    :param query: 查询对象，用于指定搜索内容。
+    :param stream: 布尔值，表示是否以流的形式返回结果，默认为False。
+    :param topic: 专题对象，用于指定搜索的专题，默认为None。
+    :return: 根据查询条件返回搜索结果。
+    """
+    if topic is not None:
+        query.searchTopicId = topic.id
+
+    if stream:
+        query.stream = True
+
+    def _gen():
+        with connect_sse(client, "POST", "/search/v2", json=query.model_dump()) as event_source:
+            for sse in event_source.iter_sse():
+                if (data := sse.data) != "[DONE]":
+                    yield json.loads(data)
+
+    if query.stream:
+        return _gen()
+
+    resp = client.post("/search/v2", json=query.model_dump())
+    return resp.json()["data"]

metaso_sdk/subject.py

@@ -0,0 +1,98 @@
+from pathlib import Path
+from typing import List, Optional
+
+from streamable import Stream
+
+from .client import client
+from .model import File, Status, Topic
+
+
+def create_topic(topic: Topic) -> Optional[Topic]:
+    """创建一个新专题。
+
+    :param topic (Topic): 要创建的专题对象。
+    :return: 专题对象。
+    """
+    resp = client.put("/topic", json=topic.model_dump())
+    json = resp.json()
+    status = Status.model_validate(json)
+    if status.errCode == 0:
+        topic = Topic.model_validate(json["data"])
+        return topic
+
+
+def delete_topic(topic: Topic) -> bool:
+    """删除指定的专题。
+
+    :param topic (Topic): 要删除的Topic对象。
+    :return: 如果成功删除Topic返回True，否则返回False。
+    """
+    resp = client.post("/topic/trash", json={"ids": [topic.id]})
+    status = Status.model_validate(resp.json())
+    return status.errCode == 0
+
+
+def upload_file(topic: Topic, file) -> Optional[File]:
+    """上传文件到指定专题。
+
+    :param topic (Topic): 文件所属的专题。
+    :param file: 待上传的文件对象。
+    :return: 如果文件上传成功，返回文件对象；否则返回None。
+    """
+    resp = client.put(f"/file/{topic.dirRootId}", files={"file": file})
+    json = resp.json()
+    status = Status.model_validate(json)
+    if status.errCode == 0:
+        file = File.model_validate(json["data"][0])
+        return file
+
+
+def update_progress(file: File) -> File:
+    """更新文件处理进度。
+
+    :param file: 需要更新进度的文件对象。
+    :return: 更新后的文件对象。
+    """
+    resp = client.get(f"/file/{file.id}/progress")
+    file.progress = resp.json()["data"]
+    return file
+
+
+def delete_file(file: File) -> bool:
+    """删除指定的文件。
+
+    :param file: 要删除的File对象。
+    :return: 如果成功删除File返回True，否则返回False。
+    """
+    resp = client.post("/file/trash", json={"ids": [file.id]})
+    status = Status.model_validate(resp.json())
+    return status.errCode == 0
+
+
+def upload_directory(topic: Topic, path: Path, pattern="**/*", *, concurrency=10) -> List[File]:
+    """递归上传指定目录下的文件到指定专题。
+
+    参数:
+    - topic: 目标专题。
+    - path: 需要上传的本地目录路径。
+    - pattern: 文件匹配模式，默认为"**/*"，表示匹配所有文件。
+    - concurrency: 并发上传的数量，默认为10。
+
+    返回:
+    - List[File]: 成功上传的文件列表。
+    """
+
+    def _upload_file(file) -> File:
+        with file.open("rb") as f:
+            return upload_file(topic, f)
+
+    files = list(
+        Stream(Path(path).glob(pattern))
+        .filter(Path.is_file)
+        .map(_upload_file, concurrency=concurrency)
+        .filter(lambda file: file is not None)
+        .observe("files")
+        .catch(),
+    )
+
+    return files

metaso_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: metaso-sdk
+Version: 0.1.0
+Summary: The official Python SDK for https://metaso.cn
+Author-Email: Zhao Xiaohong <zhaoxiaohong@metasota.ai>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://meta-sota.github.io/metaso-sdk
+Project-URL: Documentation, https://meta-sota.github.io/metaso-sdk
+Project-URL: Changelog, https://meta-sota.github.io/metaso-sdk/changelog
+Project-URL: Repository, https://github.com/meta-sota/metaso-sdk
+Project-URL: Issues, https://github.com/meta-sota/metaso-sdk/issues
+Project-URL: Discussions, https://github.com/meta-sota/metaso-sdk/discussions
+Project-URL: Gitter, https://gitter.im/metaso-sdk/community
+Project-URL: Funding, https://github.com/sponsors/meta-sota
+Requires-Python: >=3.8
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: streamable>=1.3.5
+Description-Content-Type: text/markdown
+
+# metaso-sdk
+
+[![ci](https://github.com/meta-sota/metaso-sdk/workflows/ci/badge.svg)](https://github.com/meta-sota/metaso-sdk/actions?query=workflow%3Aci)
+[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://meta-sota.github.io/metaso-sdk/)
+[![pypi version](https://img.shields.io/pypi/v/metaso-sdk.svg)](https://pypi.org/project/metaso-sdk/)
+[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#metaso-sdk:gitter.im)
+
+The official Python SDK for https://metaso.cn
+
+## 安装
+
+```bash
+pip install metaso-sdk
+```
+
+## 配置 METASO_API_KEY
+
+metaso-sdk 从环境变量 `METASO_API_KEY` 读取用于认证的 API 密钥，可以在 shell 里进行设置：
+
+```bash
+export METASO_API_KEY="mk-EE2..."
+```
+
+或者在 Python 代码里进行设置：
+
+```python
+import os
+os.environ["METASO_API_KEY"] = "mk-EE2..."
+```
+
+## 搜索
+
+### 搜索问题
+```python
+from metaso_sdk import search, Query
+search(Query(question="abc"))
+```
+
+### 追问
+
+```python
+search(Query(question="广播公司", sessionId='8550018047390023680'))
+```
+
+### 流式返回
+
+```python
+for chunk in search(Query(question="abc"), stream=True):
+    print(chunk)
+
+...
+{'type': 'heartbeat'}
+{'text': '因此，“abc”可以指代字母表的前三个字母、美籍华裔、美国广播公司、一种音乐记谱法以及一种编程语言。具体含义需要根据上下文来确定。', 'type': 'append-text'}
+```
+
+## 专题
+
+### 递归上传文件夹
+
+```
+from metaso_sdk import create_topic, upload_directory, Topic
+
+topic = create_topic(Topic(name="functional programing"))
+files = upload_directory(topic, "dir")
+```
+
+### 搜索特定专题
+
+```python
+from metaso_sdk import search, Query
+
+query = Query(question="functional")
+search(query, topic=topic)
+```

metaso_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+metaso_sdk-0.1.0.dist-info/METADATA,sha256=p6elhZYx8vXqoMtjv16dinGrmC1NmE96kfVLH_SIBAE,3420
+metaso_sdk-0.1.0.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+metaso_sdk-0.1.0.dist-info/entry_points.txt,sha256=VqvzYeWOYZKCpogIumetYL8h5UZsI93oLI15kJjbwj4,63
+metaso_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=7nWd1jm_pniRaOJtzgZnzECn_eeGLoPMvPTjCyRpj1A,1065
+metaso_sdk/__init__.py,sha256=ojrRidgqOO2LWNh0q7lv897364hE61yck2Kh7OW8mZ8,488
+metaso_sdk/__main__.py,sha256=WCRS7Ehbf26-NWDSnt-Zmy0eP63paf67q9eYV4V_Q3g,345
+metaso_sdk/cli.py,sha256=Z7I54ojBpWxQ_Pce7-XM7gucneDIpC21yAqRGkYrm9I,1734
+metaso_sdk/client.py,sha256=j2hC1NBbxsRFHC4hOSD06YrfV5JLffgrA-H5iGNBPq4,204
+metaso_sdk/debug.py,sha256=K3ypLgs78a8bhiAHE_5fZZAL-U622fuKPyEdL7M1UW8,2831
+metaso_sdk/model.py,sha256=oXLuFZMkZczRxOyWu2enRtM5eDKrNsMgDg0O2KWkX64,674
+metaso_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+metaso_sdk/search.py,sha256=3iA9lIncpAcbPHPby0XnTYaYvhM2983bEOBa40Nu_kY,1082
+metaso_sdk/subject.py,sha256=0CsDo1PRZlagR4GKLDbJXvK2Q6qFAd4_3VV8NTNYPeE,2877
+metaso_sdk-0.1.0.dist-info/RECORD,,

metaso_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.3)
+Root-Is-Purelib: true
+Tag: py3-none-any

metaso_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+metaso = metaso_sdk.cli:main
+
+[gui_scripts]
+

metaso_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MetaSota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.