vikingdb-python-sdk 0.1.9__py3-none-any.whl

vikingdb/memory/exceptions.py

@@ -0,0 +1,297 @@
+# coding:utf-8
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Viking Memory SDK Exception Definitions"""
+
+from typing import Optional
+
+from ..exceptions import VikingException
+
+
+class VikingMemException(VikingException):
+    """Viking Memory base exception class"""
+
+    def __init__(
+        self,
+        code: int,
+        request_id: str,
+        message: Optional[str] = None,
+        *,
+        status_code: Optional[int] = None,
+    ):
+        if message is None:
+            message = f"unknown error, request_id: {request_id}"
+        super().__init__(
+            code,
+            request_id,
+            message,
+            status_code=status_code,
+        )
+
+
+class UnauthorizedException(VikingMemException):
+    """
+    User authentication failed exception (Error code: 1000001)
+    
+    Triggered by:
+    - Incorrect AK/SK configuration
+    - Request body not signed
+    - Insufficient sub-account permissions
+    
+    Resolution:
+    - Check if AK/SK input is correct
+    - Check if request body is signed and signature is added to request headers
+    - If sub-account lacks permissions, refer to documentation to request permissions
+    """
+    pass
+
+
+class InvalidRequestException(VikingMemException):
+    """
+    Invalid request parameters exception (Error code: 1000003)
+    
+    Triggered by:
+    - Incorrect request parameter format or incorrect usage
+    
+    Resolution:
+    - Check request parameters based on error message
+    """
+    pass
+
+
+class CollectionExistException(VikingMemException):
+    """
+    Collection already exists exception (Error code: 1000004)
+    
+    Triggered by:
+    - Creating a collection with duplicate name
+    
+    Resolution:
+    - Check if collection exists
+    """
+    pass
+
+
+class CollectionNotExistException(VikingMemException):
+    """
+    Collection does not exist exception (Error code: 1000005)
+    
+    Triggered by:
+    - Collection name is incorrect or does not exist
+    
+    Resolution:
+    - Check if collection exists
+    """
+    pass
+
+
+class IndexExistException(VikingMemException):
+    """
+    Index already exists exception (Error code: 1000007)
+    
+    Triggered by:
+    - Creating an index with duplicate name under the same collection
+    
+    Resolution:
+    - Check if index exists
+    """
+    pass
+
+
+class IndexNotExistException(VikingMemException):
+    """
+    Index does not exist exception (Error code: 1000008)
+    
+    Triggered by:
+    - Index name is incorrect or does not exist
+    
+    Resolution:
+    - Check if index exists
+    """
+    pass
+
+
+class DataNotFoundException(VikingMemException):
+    """
+    Data not found exception (Error code: 1000011)
+    
+    Triggered by:
+    - Attempting to update_data on non-existent data
+    
+    Resolution:
+    - Check if data exists
+    """
+    pass
+
+
+class DelOpFailedException(VikingMemException):
+    """
+    Delete operation failed exception (Error code: 1000013)
+    
+    Triggered by:
+    - Delete operation fails, usually due to server issues
+    
+    Resolution:
+    - Contact customer service promptly
+    """
+    pass
+
+
+class UpsertOpFailedException(VikingMemException):
+    """
+    Upsert operation failed exception (Error code: 1000014)
+    
+    Triggered by:
+    - Upsert operation fails, usually due to server issues
+    
+    Resolution:
+    - Contact customer service promptly
+    """
+    pass
+
+
+class InvalidVectorException(VikingMemException):
+    """
+    Invalid vector exception (Error code: 1000016)
+    
+    Triggered by:
+    - Vector input issues, inconsistent dimensions or incorrect format
+    
+    Resolution:
+    - Check the vector field in the search request
+    """
+    pass
+
+
+class InvalidPrimaryKeyException(VikingMemException):
+    """
+    Invalid primary key exception (Error code: 1000017)
+    
+    Triggered by:
+    - Primary key type mismatch or incorrect format
+    
+    Resolution:
+    - Check the primary key field
+    """
+    pass
+
+
+class InvalidFilterException(VikingMemException):
+    """
+    Invalid scalar filter statement exception (Error code: 1000019)
+    
+    Triggered by:
+    - Incorrect filter format
+    - Field not added to scalar index
+    - Improper use of field filter statement
+    
+    Resolution:
+    - Check filter statement format and field configuration
+    """
+    pass
+
+
+class IndexSearchException(VikingMemException):
+    """
+    Index search exception (Error code: 1000021)
+    
+    Triggered by:
+    - Server encountered unknown error or failure
+    
+    Resolution:
+    - Contact customer service promptly
+    """
+    pass
+
+
+class IndexFetchException(VikingMemException):
+    """
+    Index fetch data exception (Error code: 1000022)
+    
+    Triggered by:
+    - Server encountered unknown error or failure
+    
+    Resolution:
+    - Contact customer service promptly
+    """
+    pass
+
+
+class IndexInitializingException(VikingMemException):
+    """
+    Index initializing exception (Error code: 1000023)
+    
+    Triggered by:
+    - Attempting to search or query data while index is initializing
+    
+    Resolution:
+    - Wait for index to be ready
+    - If not ready after long time (over 1 hour), contact customer service promptly
+    """
+    pass
+
+
+class EmbeddingException(VikingMemException):
+    """
+    Embedding execution exception (Error code: 1000025)
+    
+    Triggered by:
+    - Server error during vectorization of unstructured data
+    
+    Resolution:
+    - If error occurs occasionally, check if input data format is valid
+    - Otherwise, contact customer service promptly
+    """
+    pass
+
+
+class InternalServerException(VikingMemException):
+    """
+    Internal server error exception (Error code: 1000028)
+    
+    Triggered by:
+    - Server encountered unexpected error
+    
+    Resolution:
+    - Contact customer service promptly
+    """
+    pass
+
+
+class QuotaLimiterException(VikingMemException):
+    """
+    Request rate limit exceeded exception (Error code: 1000029)
+    
+    Triggered by:
+    - API request QPS too high
+    
+    Resolution:
+    - If search requests are rate limited, increase CPU Quota
+    - If other APIs are rate limited, check if calling method has issues
+    - Adjust API calling frequency
+    """
+    pass
+
+
+# Error code to exception class mapping
+EXCEPTION_MAP = {
+    1000001: UnauthorizedException,           # User authentication failed
+    1000003: InvalidRequestException,         # Invalid request parameters
+    1000004: CollectionExistException,        # Collection already exists
+    1000005: CollectionNotExistException,     # Collection does not exist
+    1000007: IndexExistException,             # Index already exists
+    1000008: IndexNotExistException,          # Index does not exist
+    1000011: DataNotFoundException,           # Data not found
+    1000013: DelOpFailedException,            # Delete operation failed
+    1000014: UpsertOpFailedException,         # Upsert operation failed
+    1000016: InvalidVectorException,          # Invalid vector
+    1000017: InvalidPrimaryKeyException,      # Invalid primary key
+    1000019: InvalidFilterException,          # Invalid scalar filter statement
+    1000021: IndexSearchException,            # Index search exception
+    1000022: IndexFetchException,             # Index fetch data exception
+    1000023: IndexInitializingException,      # Index initializing
+    1000025: EmbeddingException,              # Embedding execution exception
+    1000028: InternalServerException,         # Internal server error
+    1000029: QuotaLimiterException,           # Request rate limit exceeded
+}

vikingdb/memory/types.py

@@ -0,0 +1,18 @@
+# coding:utf-8
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Viking Memory SDK Type Definitions"""
+
+import json
+from enum import Enum
+from typing import Any
+
+
+class EnumEncoder(json.JSONEncoder):
+    """Enum type JSON encoder"""
+
+    def default(self, obj: Any) -> Any:
+        if isinstance(obj, Enum):
+            return obj.value
+        return super().default(obj)

vikingdb/request_options.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import MutableMapping, Optional
+
+
+@dataclass
+class RequestOptions:
+    """
+    Per-request overrides for headers, query parameters, and retry behaviour.
+
+    Attributes:
+        headers: Additional HTTP headers to apply for a single request.
+        query: Additional query parameters appended to the request URL.
+        request_id: Optional request identifier propagated via X-Tt-Logid.
+        max_attempts: Override for retry attempts (defaults to client configuration).
+        timeout: Override for the response read timeout (seconds).
+    """
+
+    headers: MutableMapping[str, str] = field(default_factory=dict)
+    query: MutableMapping[str, str] = field(default_factory=dict)
+    request_id: Optional[str] = None
+    max_attempts: Optional[int] = None
+    timeout: Optional[int] = None
+
+
+def ensure_request_options(
+    options: Optional[RequestOptions],
+) -> RequestOptions:
+    return options if options is not None else RequestOptions()

vikingdb/vector/__init__.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from .client import VikingVector
+from .collection import CollectionClient
+from .embedding import EmbeddingClient
+from .rerank import RerankClient
+from .index import IndexClient
+from .models import CollectionMeta, IndexMeta, __all__ as _models_all  # noqa: F401
+from .models import *  # noqa: F401,F403
+from .exceptions import VikingVectorException
+__all__ = [
+    "VikingVector",
+    "CollectionClient",
+    "IndexClient",
+    "EmbeddingClient",
+    "RerankClient",
+    "VikingVectorException",
+] + list(_models_all)
+
+del _models_all

vikingdb/vector/base.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping, Optional, Type, Union
+
+from pydantic import BaseModel
+
+from ..request_options import RequestOptions
+
+if TYPE_CHECKING:
+    from .client import VikingVector
+
+
+class VectorClientBase:
+    """Shared helper for all Vector clients."""
+
+    def __init__(self, service: "VikingVector") -> None:
+        self._service = service
+
+    def _post(
+        self,
+        api: str,
+        payload: Mapping[str, Any],
+        response_model: Type[BaseModel],
+        *,
+        request_options: Optional[RequestOptions] = None,
+    ) -> BaseModel:
+        response_payload = self._service.request(api, payload, options=request_options)
+        return response_model.model_validate(response_payload)
+
+    @staticmethod
+    def _merge_payload(
+        base: Mapping[str, Any],
+        request: Union[BaseModel, Mapping[str, Any], None],
+    ) -> Mapping[str, Any]:
+        if isinstance(request, BaseModel):
+            body = request.model_dump(by_alias=True, exclude_none=True)
+        elif request is None:
+            body = {}
+        elif isinstance(request, Mapping):
+            body = {key: value for key, value in request.items() if value is not None}
+        else:
+            raise Exception(
+                f"unsupported request type: {type(request)!r}"
+            )
+
+        merged = dict(base)
+        merged.update(body)
+        return merged