Merge 'feat/exceptions' into 'master'

feat: impl common exception in vikingdb

See merge request: !15

Author: ZaynJarvis

examples/memory/04_exception_handling_test.py

@@ -0,0 +1,66 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Example 4: Exceptions
+"""
+
+import os
+import time
+
+from vikingdb import IAM
+from vikingdb.memory import VikingMem
+
+
+# Initialize client
+_auth = IAM(
+    ak=os.getenv("VIKINGDB_AK", "your_ak"),
+    sk=os.getenv("VIKINGDB_SK", "your_sk"),
+)
+client = VikingMem(
+    host="api-knowledgebase.mlp.cn-beijing.volces.com",
+    region="cn-beijing",
+    auth=_auth,
+    scheme="http",
+)
+
+
+def add_session_exception():    
+    collection = client.get_collection(
+        collection_name="sdk_missing",
+        project_name="default"
+    )
+    now_ts = int(time.time() * 1000)
+    # Add session messages
+    result = collection.add_session(
+        session_id="session_001",
+        messages=[
+            {
+                "role": "user",
+                "content": "Hello, how is the weather today?"
+            },
+            {
+                "role": "assistant",
+                "content": "Today is sunny with a temperature of 22 degrees, perfect for going out."
+            }
+        ],
+        metadata = {
+            "default_user_id": "user_3",
+            "default_user_name": "Li",
+            "default_assistant_id": "111",
+            "default_assistant_name": "Smart Assistant",
+            # "group_id": "",
+            "time": now_ts,
+        }
+    )
+    
+    return result
+
+
+
+
+if __name__ == "__main__":
+    print("Viking Memory Add Session Messages Example\n")
+    
+    add_session_exception()
+    

examples/vector/E3_1_index_search_multimodal_test.py

@@ -16,7 +16,6 @@
 
 from .guide_helpers import (
     Clients,
-    assign_chapter_ids_via_search,
     bool_and_filters,
     build_clients,
     build_request_options,

examples/vector/E6_exception_handling_test.py

@@ -0,0 +1,67 @@
+"""Scenario 6 – Exception handling for the vector client."""
+
+from __future__ import annotations
+
+import pytest
+
+from vikingdb import IAM
+from vikingdb.exceptions import NETWORK_ERROR_CODE
+from vikingdb.vector import SearchByRandomRequest, VikingVector
+from vikingdb.vector.exceptions import VikingVectorException
+
+from .guide_helpers import EnvConfig, load_config
+
+
+def _build_vector_client(*, host_override: str | None = None, timeout: int | None = None) -> tuple[EnvConfig, VikingVector]:
+    """
+    Create a VikingVector client using the shared guide configuration.
+
+    ``host_override`` allows tests to force failure scenarios (for example, invalid hosts),
+    while ``timeout`` lets them shorten request durations for network errors.
+    """
+    config = load_config()
+    auth = IAM(ak=config.access_key, sk=config.secret_key)
+    client = VikingVector(
+        host=host_override if host_override is not None else config.host,
+        region=config.region,
+        scheme=config.scheme,
+        auth=auth,
+        timeout=timeout if timeout is not None else 30,
+    )
+    return config, client
+
+
+def test_exception_collection_not_exist() -> None:
+    """Calling a non-existent collection should surface a VikingVectorException with a helpful code."""
+    config, client = _build_vector_client()
+    missing_collection = f"{config.collection}-missing"
+
+    collection_client = client.collection(
+        collection_name=missing_collection,
+        project_name=config.project_name,
+        resource_id=config.resource_id,
+    )
+
+    with pytest.raises(VikingVectorException) as exc_info:
+        collection_client.fetch({"ids": ["non-existent-id"]})
+
+    error_code = str(exc_info.value.code)
+    assert "NotFound" in error_code
+
+
+def test_exception_wrong_host_raises_network() -> None:
+    """Using an invalid host should raise a network exception promoted to VikingVectorException."""
+    config, client = _build_vector_client(host_override="this-host-does-not-exist.invalid", timeout=1)
+
+    index_client = client.index(
+        collection_name=config.collection,
+        index_name=config.index,
+        project_name=config.project_name,
+        resource_id=config.resource_id,
+    )
+
+    with pytest.raises(VikingVectorException) as exc_info:
+        index_client.search_by_random(SearchByRandomRequest(limit=1))
+
+    error_code = str(exc_info.value.code)
+    assert "InternalServerError" in error_code

pyproject.toml

@@ -46,4 +46,5 @@ version = {attr = "vikingdb.version.__version__"}
 [dependency-groups]
 dev = [
     "pytest>=7.4.4",
+    "ruff>=0.14.3",
 ]

uv.lock

@@ -7,6 +7,7 @@
 
 import json
 from abc import ABC, abstractmethod
+from json import JSONDecodeError
 from typing import Any, Mapping, Optional
 
 import aiohttp
@@ -17,6 +18,13 @@
 from volcengine.base.Service import Service
 
 from .auth import Auth
+from .exceptions import (
+    DEFAULT_UNKNOWN_ERROR_CODE,
+    VikingAPIException,
+)
+
+
+_REQUEST_ID_HEADER = "X-Tt-Logid"
 
 
 class Client(Service, ABC):
@@ -113,6 +121,9 @@ def _json(
         self.auth_provider.sign_request(request)
         url = request.build()
 
+        request_id_value = request.headers.get(_REQUEST_ID_HEADER)
+        request_id = str(request_id_value) if request_id_value else "unknown"
+        
         # Use custom timeout if provided, otherwise use default
         if timeout is not None:
             request_timeout = (timeout, timeout)
@@ -122,15 +133,49 @@ def _json(
                 self.service_info.socket_timeout,
             )
 
-        response = self.session.post(
-            url,
-            headers=request.headers,
-            data=request.body,
-            timeout=request_timeout,
-        )
-        if response.status_code == 200:
+        try:
+            response = self.session.post(
+                url,
+                headers=request.headers,
+                data=request.body,
+                timeout=request_timeout,
+            )
+        except Exception as exc:
+            raise VikingAPIException(
+                    DEFAULT_UNKNOWN_ERROR_CODE,
+                    request_id=request_id,
+                    message=f"failed to run session.post {api}: {exc}",
+                ) from exc
+
+        payload_text_attr = getattr(response, "text", "")
+        payload_text = payload_text_attr if isinstance(payload_text_attr, str) else ""
+        payload_text = payload_text or ""
+
+        if response.status_code != 200:
+            error = VikingAPIException.from_response(
+                payload_text,
+                request_id=request_id,
+                status_code=response.status_code,
+            )
+            raise error
+
+        try:
             return response.json()
-        raise Exception(response.text.encode("utf-8"))
+        except (ValueError, JSONDecodeError) as exc:
+            raise VikingAPIException(
+                DEFAULT_UNKNOWN_ERROR_CODE,
+                request_id=request_id,
+                message=f"failed to decode JSON response for {api}: {exc}",
+                status_code=response.status_code,
+            ) from exc
+
+        except Exception as exc:  # pragma: no cover - defensive fallback
+            raise VikingAPIException(
+                DEFAULT_UNKNOWN_ERROR_CODE,
+                request_id=request_id,
+                message=f"unexpected error parsing response for {api}: {exc}",
+                status_code=response.status_code,
+            ) from exc
 
     async def async_json(
         self,
@@ -175,14 +220,36 @@ async def async_json(
             )
 
         url = request.build()
-        async with aiohttp.request(
-            "POST",
-            url,
-            headers=request.headers,
-            data=request.body,
-            timeout=client_timeout,
-        ) as response:
-            payload = await response.text(encoding="utf-8")
-            if response.status == 200:
-                return json.loads(payload)
-            raise Exception(payload)
+        try:
+            async with aiohttp.request(
+                "POST",
+                url,
+                headers=request.headers,
+                data=request.body,
+                timeout=client_timeout,
+            ) as response:
+                request_id_value = response.headers.get(_REQUEST_ID_HEADER)
+                request_id = str(request_id_value) if request_id_value else "unknown"
+                payload = await response.text(encoding="utf-8")
+                if response.status != 200:
+                    error = VikingAPIException.from_response(
+                        payload,
+                        request_id=request_id,
+                        status_code=response.status,
+                    )
+                    raise error
+                try:
+                    return json.loads(payload)
+                except JSONDecodeError as exc:
+                    raise VikingAPIException(
+                        DEFAULT_UNKNOWN_ERROR_CODE,
+                        request_id=request_id,
+                        message=f"failed to decode JSON response for {api}: {exc}",
+                        status_code=response.status,
+                    ) from exc
+        except Exception as exc:
+            raise VikingAPIException(
+                    DEFAULT_UNKNOWN_ERROR_CODE,
+                    request_id=request_id,
+                    message=f"failed to run aiohttp {api}: {exc}",
+                ) from exc