vikingdb-python-sdk 0.1.9__tar.gz → 0.1.11__tar.gz

{vikingdb_python_sdk-0.1.9/vikingdb_python_sdk.egg-info → vikingdb_python_sdk-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vikingdb-python-sdk
-Version: 0.1.9
+Version: 0.1.11
 Summary: vikingdb Python SDK
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://github.com/volcengine/volc-vikingdb-python-sdk/README.md
@@ -20,6 +20,7 @@ License-File: LICENSE.txt
 Requires-Dist: httpx>=0.24.1
 Requires-Dist: requests>=2.28.1
 Requires-Dist: pydantic>=2.5.3
+Requires-Dist: typing_extensions>=4.9.0
 Requires-Dist: urllib3>=1.21.1
 Requires-Dist: volcengine>=1.0.0
 Requires-Dist: aiohttp>=3.10.0
@@ -53,10 +54,10 @@ uv add vikingdb-python-sdk
 ```python
 import os
 from vikingdb import IAM
-from vikingdb.vector import SearchByRandomRequest, VikingVector
+from vikingdb.vector import SearchByRandomRequest, VikingDB
 
 auth = IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]) 
-client = VikingVector(
+client = VikingDB(
     host=os.environ["VIKINGDB_HOST"],
     region=os.environ["VIKINGDB_REGION"],
     auth=auth,
@@ -181,7 +182,7 @@ python examples/memory/03_search_memory.py
 ### Architecture Overview
 
 - `vikingdb._client`, `vikingdb.auth`, `vikingdb.request_options`, and `vikingdb.vector.exceptions` form the shared runtime used by all present and future SDK domains (vector, memory, knowledge).
-- Domain-specific features live under dedicated namespaces such as `vikingdb.vector` and `vikingdb.memory`, where the high-level clients (`VikingVector`, `VikingMem`) compose the shared auth stack atop the shared client.
+- Domain-specific features live under dedicated namespaces such as `vikingdb.vector` and `vikingdb.memory`, where the high-level clients (`VikingDB`, `VikingMem`) compose the shared auth stack atop the shared client.
 - Vector request/response models now surface directly from `vikingdb.vector` (backed internally by `vikingdb/vector/models`).
 - Memory APIs return plain dictionaries without object encapsulation, providing a lightweight interface for conversational memory management (session, profile, event operations).
 - Imports from the root package now focus on cross-cutting utilities (auth, config, request options), while application code should pull domain-specific functionality from `vikingdb.vector` or `vikingdb.memory` explicitly.

{vikingdb_python_sdk-0.1.9 → vikingdb_python_sdk-0.1.11}/README.md

@@ -26,10 +26,10 @@ uv add vikingdb-python-sdk
 ```python
 import os
 from vikingdb import IAM
-from vikingdb.vector import SearchByRandomRequest, VikingVector
+from vikingdb.vector import SearchByRandomRequest, VikingDB
 
 auth = IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]) 
-client = VikingVector(
+client = VikingDB(
     host=os.environ["VIKINGDB_HOST"],
     region=os.environ["VIKINGDB_REGION"],
     auth=auth,
@@ -154,7 +154,7 @@ python examples/memory/03_search_memory.py
 ### Architecture Overview
 
 - `vikingdb._client`, `vikingdb.auth`, `vikingdb.request_options`, and `vikingdb.vector.exceptions` form the shared runtime used by all present and future SDK domains (vector, memory, knowledge).
-- Domain-specific features live under dedicated namespaces such as `vikingdb.vector` and `vikingdb.memory`, where the high-level clients (`VikingVector`, `VikingMem`) compose the shared auth stack atop the shared client.
+- Domain-specific features live under dedicated namespaces such as `vikingdb.vector` and `vikingdb.memory`, where the high-level clients (`VikingDB`, `VikingMem`) compose the shared auth stack atop the shared client.
 - Vector request/response models now surface directly from `vikingdb.vector` (backed internally by `vikingdb/vector/models`).
 - Memory APIs return plain dictionaries without object encapsulation, providing a lightweight interface for conversational memory management (session, profile, event operations).
 - Imports from the root package now focus on cross-cutting utilities (auth, config, request options), while application code should pull domain-specific functionality from `vikingdb.vector` or `vikingdb.memory` explicitly.

{vikingdb_python_sdk-0.1.9 → vikingdb_python_sdk-0.1.11}/pyproject.toml

@@ -24,6 +24,7 @@ dependencies = [
     "httpx>=0.24.1",
     "requests>=2.28.1",
     "pydantic>=2.5.3",
+    "typing_extensions>=4.9.0",
     "urllib3>=1.21.1",
     "volcengine>=1.0.0",
     "aiohttp>=3.10.0",

{vikingdb_python_sdk-0.1.9 → vikingdb_python_sdk-0.1.11}/vikingdb/__init__.py

@@ -12,6 +12,7 @@ from .vector import (
     EmbeddingClient,
     IndexClient,
     RerankClient,
+    VikingDB,
     VikingVector,
 )
 from .memory import (
@@ -27,6 +28,7 @@ __all__ = [
     "RerankClient",
     "IndexClient",
     "RequestOptions",
+    "VikingDB",
     "VikingVector",
     "vector",
     "memory",

{vikingdb_python_sdk-0.1.9 → vikingdb_python_sdk-0.1.11}/vikingdb/_client.py

@@ -18,7 +18,7 @@ from volcengine.base.Request import Request
 from volcengine.base.Service import Service
 import requests
 
-from .auth import Auth, IAM, APIKey
+from .auth import Auth, IAM, APIKey, HeaderAuth
 from .exceptions import (
     DEFAULT_UNKNOWN_ERROR_CODE,
     VikingAPIException,
@@ -56,10 +56,10 @@ class Client(Service, ABC):
         # 判断auth是不是IAM 还是 APIKey类型
         if isinstance(auth, IAM):
             super().__init__(self.service_info, self.api_info)
-        elif isinstance(auth, APIKey):
+        elif isinstance(auth, (APIKey, HeaderAuth)):
             self.session = requests.session()
         else:
-            raise ValueError("auth must be IAM or APIKey type")
+            raise ValueError("auth must be IAM, APIKey or HeaderAuth type")
 
         if sts_token:
             self.set_session_token(session_token=sts_token)

{vikingdb_python_sdk-0.1.9 → vikingdb_python_sdk-0.1.11}/vikingdb/auth.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from typing import Mapping
 from volcengine.Credentials import Credentials
 from volcengine.auth.SignerV4 import SignerV4
 
@@ -66,3 +67,18 @@ class APIKey(Auth):
 
     def sign_request(self, request) -> None:
         request.headers["Authorization"] = f"Bearer {self.api_key}"
+
+
+class HeaderAuth(Auth):
+    """Header-based authentication provider."""
+
+    def __init__(self, headers: Mapping[str, str]):
+        self.headers = headers
+
+    def initialize(self, *, service: str, region: str):
+        return None
+
+    def sign_request(self, request) -> None:
+        if self.headers:
+            for key, value in self.headers.items():
+                request.headers[key] = value

vikingdb_python_sdk-0.1.11/vikingdb/knowledge/__init__.py

@@ -0,0 +1,126 @@
+# coding:utf-8
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from .client import VikingKnowledge
+from .collection import KnowledgeCollection
+from .exceptions import (
+    VikingKnowledgeException,
+    UnauthorizedException,
+    NoPermissionException,
+    InvalidRequestException,
+    CollectionExistException,
+    CollectionNotExistException,
+    OperationNotAllowedException,
+    IndexExistException,
+    IndexNotExistException,
+    QueryOpFailedException,
+    DataNotFoundException,
+    DelOpFailedException,
+    UpsertOpFailedException,
+    TokenMismatchException,
+    InvalidQueryVecException,
+    InvalidPrimaryKeyException,
+    InvalidPartitionException,
+    InvalidScalarCondException,
+    InvalidProxyServiceException,
+    IndexRecallException,
+    IndexFetchDataException,
+    IndexNotReadyException,
+    APINotImplementedException,
+    CalcEmbeddingFailedException,
+    ListEmbeddingModelsException,
+    InternalServerException,
+    QuotaLimiterException,
+    RerankException,
+    DocNotExistException,
+    DocIsFullException,
+    PointNotExistException,
+)
+from .models.base import CollectionMeta
+from .models.doc import DocInfo, DocInfo, ListDocsResponse, AddDocRequest, AddDocV2Request, ListDocsRequest, DedupOptions, MetaItem, AddDocResponse, AddDocResponseData
+from .models.point import (
+    PointInfo,
+    ListPointsResponse,
+    AddPointRequest,
+    UpdatePointRequest,
+    ListPointsRequest,
+    DeletePointRequest,
+)
+from .models.search import (
+    SearchCollectionRequest,
+    SearchResponse,
+    SearchKnowledgeResponse,
+    SearchKnowledgeRequest,
+)
+from .models.rerank import RerankDataItem, RerankResponse
+from .models.service_chat import ServiceChatRequest, ServiceChatResponse
+from .models.chat import (
+    ChatMessage,
+    ChatCompletionRequest,
+    ChatCompletionResponse,
+)
+
+__all__ = [
+    "VikingKnowledge",
+    "KnowledgeCollection",
+    "VikingKnowledgeException",
+    "UnauthorizedException",
+    "NoPermissionException",
+    "InvalidRequestException",
+    "CollectionExistException",
+    "CollectionNotExistException",
+    "OperationNotAllowedException",
+    "IndexExistException",
+    "IndexNotExistException",
+    "QueryOpFailedException",
+    "DataNotFoundException",
+    "DelOpFailedException",
+    "UpsertOpFailedException",
+    "TokenMismatchException",
+    "InvalidQueryVecException",
+    "InvalidPrimaryKeyException",
+    "InvalidPartitionException",
+    "InvalidScalarCondException",
+    "InvalidProxyServiceException",
+    "IndexRecallException",
+    "IndexFetchDataException",
+    "IndexNotReadyException",
+    "APINotImplementedException",
+    "CalcEmbeddingFailedException",
+    "ListEmbeddingModelsException",
+    "InternalServerException",
+    "QuotaLimiterException",
+    "RerankException",
+    "DocNotExistException",
+    "DocIsFullException",
+    "PointNotExistException",
+    "CollectionMeta",
+    "DocInfo",
+    "DocInfo",
+    "ListDocsResponse",
+    "AddDocRequest",
+    "AddDocV2Request",
+    "AddDocResponse",
+    "AddDocResponseData",
+    "ListDocsRequest",
+    "PointInfo",
+    "DedupOptions",
+    "MetaItem",
+    "ListPointsResponse",
+    "AddPointRequest",
+    "UpdatePointRequest",
+    "ListPointsRequest",
+    "DeletePointRequest",
+    "SearchCollectionRequest",
+    "SearchResponse",
+    "SearchKnowledgeResponse",
+    "SearchKnowledgeRequest",
+    "RerankDataItem",
+    "RerankResponse",
+    "ServiceChatRequest",
+    "ServiceChatResponse",
+    "ChatMessage",
+    "ChatCompletionRequest",
+    "ChatCompletionResponse",
+]

vikingdb_python_sdk-0.1.11/vikingdb/knowledge/client.py

@@ -0,0 +1,174 @@
+# coding:utf-8
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from typing import Mapping, Optional, Union, Sequence, cast
+
+from volcengine.ApiInfo import ApiInfo
+
+from .. import APIKey
+from .._client import Client, _REQUEST_ID_HEADER
+from ..auth import Auth
+from ..exceptions import VikingException, promote_exception
+from .exceptions import EXCEPTION_MAP, VikingKnowledgeException
+from ..version import __version__
+from .models.base import CollectionMeta, Model
+from .models.rerank import RerankDataItem, RerankResponse
+from .models.chat import ChatCompletionRequest, ChatCompletionResponse
+from .models.service_chat import ServiceChatRequest, ServiceChatResponse
+
+
+_DEFAULT_USER_AGENT = f"vikingdb-python-sdk/{__version__}"
+
+
+def _get_common_viking_request_header():
+    header = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": _DEFAULT_USER_AGENT,
+    }
+    return header
+
+
+class VikingKnowledge(Client):
+    def __init__(
+        self,
+        *,
+        host: str = "api-knowledgebase.mlp.cn-beijing.volces.com",
+        region: str = "cn-beijing",
+        auth: Auth,
+        sts_token: str = "",
+        scheme: str = "http",
+        timeout: int = 30,
+    ):
+        super().__init__(
+            host=host,
+            region=region,
+            service="air",
+            auth=auth,
+            sts_token=sts_token,
+            scheme=scheme,
+            timeout=timeout,
+        )
+
+    def _build_api_info(self):
+        header = _get_common_viking_request_header()
+        return {
+            "SearchCollection": ApiInfo("POST", "/api/knowledge/collection/search", {}, {}, header),
+            "SearchKnowledge": ApiInfo("POST", "/api/knowledge/collection/search_knowledge", {}, {}, header),
+            "ServiceChat": ApiInfo("POST", "/api/knowledge/service/chat", {}, {}, header),
+            # Doc
+            "AddDoc": ApiInfo("POST", "/api/knowledge/doc/add", {}, {}, header),
+            "AddDocV2": ApiInfo("POST", "/api/knowledge/doc/v2/add", {}, {}, header),
+            "DeleteDoc": ApiInfo("POST", "/api/knowledge/doc/delete", {}, {}, header),
+            "GetDocInfo": ApiInfo("POST", "/api/knowledge/doc/info", {}, {}, header),
+            "ListDocs": ApiInfo("POST", "/api/knowledge/doc/list", {}, {}, header),
+            "UpdateDocMeta": ApiInfo("POST", "/api/knowledge/doc/update_meta", {}, {}, header),
+            "UpdateDoc": ApiInfo("POST", "/api/knowledge/doc/update", {}, {}, header),
+            # Point
+            "GetPointInfo": ApiInfo("POST", "/api/knowledge/point/info", {}, {}, header),
+            "ListPoints": ApiInfo("POST", "/api/knowledge/point/list", {}, {}, header),
+            "AddPoint": ApiInfo("POST", "/api/knowledge/point/add", {}, {}, header),
+            "UpdatePoint": ApiInfo("POST", "/api/knowledge/point/update", {}, {}, header),
+            "DeletePoint": ApiInfo("POST", "/api/knowledge/point/delete", {}, {}, header),
+            # Service
+            "Ping": ApiInfo("GET", "/ping", {}, {}, header),
+            "Rerank": ApiInfo("POST", "/api/knowledge/service/rerank", {}, {}, header),
+            # Chat
+            "ChatCompletion": ApiInfo("POST", "/api/knowledge/chat/completions", {}, {}, header),
+        }
+
+    def json_exception(self, api, params, body, headers=None, timeout=None):
+        try:
+            res = self._json(api, params, body, headers=headers, timeout=timeout)
+        except VikingException as exc:
+            raise promote_exception(exc, exception_map=EXCEPTION_MAP, default_cls=VikingKnowledgeException) from None
+        if res is None:
+            raise VikingKnowledgeException(1000028, "missed", "empty response due to unknown error", status_code=None)
+        return res
+
+    async def async_json_exception(self, api, params, body, headers=None, timeout=None):
+        try:
+            res = await self.async_json(api, params, body, headers=headers, timeout=timeout)
+        except VikingException as exc:
+            raise promote_exception(exc, exception_map=EXCEPTION_MAP, default_cls=VikingKnowledgeException) from None
+        if res is None:
+            raise VikingKnowledgeException(1000028, "missed", "empty response due to unknown error", status_code=None)
+        return res
+
+    def collection(
+        self,
+        *,
+        resource_id: Optional[str] = None,
+        collection_name: Optional[str] = None,
+        project_name: Optional[str] = None,
+    ):
+        from .collection import KnowledgeCollection
+
+        meta = CollectionMeta(
+            resource_id=resource_id,
+            collection_name=collection_name,
+            project_name=project_name,
+        )
+        return KnowledgeCollection(self, meta)
+
+    def rerank(
+        self,
+        datas: Sequence[Union[RerankDataItem,Mapping[str, object]]],
+        *,
+        rerank_model: str = "Doubao-pro-4k-rerank",
+        rerank_instruction: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> RerankResponse:
+        items = [
+            (d.model_dump(by_alias=True, exclude_none=True) if isinstance(d, RerankDataItem) else dict(d))
+            for d in datas
+        ]
+        if len(items) > 50:
+            raise VikingKnowledgeException(1000028, "missed", "datas list too large", status_code=None)
+        payload: dict = {"datas": items, "rerank_model": rerank_model}
+        if rerank_instruction is not None:
+            payload["rerank_instruction"] = rerank_instruction
+        if endpoint_id is not None:
+            payload["endpoint_id"] = endpoint_id
+        res = self.json_exception("Rerank", {}, json.dumps(payload), headers=headers, timeout=timeout)
+        response = RerankResponse.parse_with(res)
+        return response
+
+    def chat_completion(
+        self,
+        request: Union[ChatCompletionRequest, Mapping[str, object]],
+        *,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> ChatCompletionResponse:
+        payload = (
+            request.model_dump(by_alias=True, exclude_none=True)  # type: ignore[attr-defined]
+            if isinstance(request, ChatCompletionRequest)
+            else dict(request)
+        )
+        res = self.json_exception("ChatCompletion", {}, json.dumps(payload), headers=headers, timeout=timeout)
+        response = ChatCompletionResponse.parse_with(res)
+        return response
+
+    def service_chat(
+        self,
+        request: Union[ServiceChatRequest, Mapping[str, object]],
+        *,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> ServiceChatResponse:
+        payload = (
+            request.model_dump(by_alias=True, exclude_none=True)  # type: ignore[attr-defined]
+            if isinstance(request, ServiceChatRequest)
+            else dict(request)
+        )
+        req_headers = dict(headers or {})
+        res = self.json_exception("ServiceChat", {}, json.dumps(payload), headers=req_headers, timeout=timeout)
+        response = ServiceChatResponse.parse_with(res)
+        return response