release: version 0.1.1

1. support vector Exceptions, code should be string
2. add retry and ping in vector
3. update examples for easy usage

Author: ZaynJarvis

.gitignore

@@ -10,4 +10,6 @@ venv
 AGENTS.md
 .env
 
-dist/
+dist/
+.pytest_cache/
+.ruff_cache/

README.md

@@ -14,7 +14,7 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 Clone the repository and install the SDK in editable mode:
 
 ```bash
-pip install -e .
+uv add vikingdb-python-sdk
 ```
 
 > **Dependencies:** The SDK relies on `requests`, `pydantic>=2.5`, and the Volcano Engine base SDK (`volcengine`) for request signing.
@@ -24,34 +24,24 @@ pip install -e .
 #### Vector Database
 
 ```python
+import os
 from vikingdb import IAM
-from vikingdb.vector import UpsertDataRequest, VikingVector
+from vikingdb.vector import SearchByRandomRequest, VikingVector
 
-auth = IAM(ak="<AK>", sk="<SK>")
+auth = IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]) 
 client = VikingVector(
-    host="api.vector.bytedance.com",
-    region="cn-beijing",
+    host=os.environ["VIKINGDB_HOST"],
+    region=os.environ["VIKINGDB_REGION"],
     auth=auth,
     scheme="https",
     timeout=30,
 )
-
-collection = client.collection(collection_name="demo_collection")
-index = client.index(collection_name="demo_collection", index_name="demo_index")
-embedding = client.embedding()
-
-# Upsert documents into a collection
-upsert_request = UpsertDataRequest(
-    data=[
-        {"title": "Demo Chapter", "paragraph": 1, "score": 42.0, "text": "hello vikingdb"},
-    ]
+index = client.index(
+    collection_name=os.environ["VIKINGDB_COLLECTION"],
+    index_name=os.environ["VIKINGDB_INDEX"],
 )
-response = collection.upsert(upsert_request)
-print("request_id:", response.request_id, "result:", response.result)
-
-# Run a quick search
-search_response = index.search_by_random({"limit": 1})
-print("search hits:", len(search_response.result.data) if search_response.result else 0)
+resp = index.search_by_random(SearchByRandomRequest(limit=1))
+print(f"request_id={resp.request_id} hits={len(resp.result.data or [])}")
 ```
 
 #### Memory Management
@@ -107,6 +97,8 @@ The integration guides under `examples/vector` mirror the Go SDK walkthroughs (`
    ```
    VIKINGDB_AK=your-access-key
    VIKINGDB_SK=your-secret-key
+   VIKINGDB_COLLECTION=demo_collection
+   VIKINGDB_INDEX=demo_index
    # Optional:
    # VIKINGDB_PROJECT=project-name
    # VIKINGDB_RESOURCE_ID=resource-id

examples/memory/04_exception_handling_test.py

@@ -0,0 +1,65 @@
+# 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/1_connectivity.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import os
+import json
+
+from vikingdb import IAM
+from vikingdb.vector import SearchByRandomRequest, VikingVector
+
+
+def main() -> None:
+    """Connectivity quickstart mirroring the snippet test."""
+    auth = IAM(
+        ak=os.environ["VIKINGDB_AK"],
+        sk=os.environ["VIKINGDB_SK"],
+    )
+    client = VikingVector(
+        host=os.environ["VIKINGDB_HOST"],
+        region=os.environ["VIKINGDB_REGION"],
+        auth=auth,
+        scheme="https",
+        timeout=30,
+    )
+    index_client = client.index(
+        collection_name=os.environ["VIKINGDB_COLLECTION"],
+        index_name=os.environ["VIKINGDB_INDEX"],
+    )
+
+    response = index_client.search_by_random(SearchByRandomRequest(limit=1))
+    data = []
+    if response.result and response.result.data:
+        data = response.result.data
+    hits = len(data)
+    print(f"SearchByRandom request_id={response.request_id} hits={hits}")
+    # Pretty print full JSON response if available
+    if hasattr(response, "model_dump"):
+        try:
+            print(response.model_dump_json(indent=2, by_alias=True) if hasattr(response, "model_dump_json") else json.dumps(response.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()

examples/vector/E2_collection_lifecycle_test.py renamed to examples/vector/2_collection_lifecycle.py

@@ -1,17 +1,11 @@
 # Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
 # SPDX-License-Identifier: Apache-2.0
 
-"""
-Scenario 2 – Collection Lifecycle
-
-Follows the Go reference by showing both an inline lifecycle walkthrough and a helper-based scenario.
-"""
 from __future__ import annotations
 
 import os
 import time
-
-import pytest
+import json
 
 from vikingdb import IAM
 from vikingdb.vector import (
@@ -23,28 +17,9 @@
     VikingVector,
 )
 
-from .guide_helpers import (
-    Clients,
-    assign_chapter_ids_via_search,
-    build_clients,
-    build_request_options,
-    build_story_chapters,
-    chapters_to_upsert,
-    cleanup_chapters,
-    load_config,
-    new_session_tag,
-)
-
 
-def test_snippet_collection_lifecycle() -> None:
-    """
-    Inline lifecycle flow mirroring the Go snippet:
-      1. Upsert a chapter.
-      2. Search to hydrate the chapter ID.
-      3. Update scalar fields.
-      4. Fetch to verify.
-      5. Delete the record.
-    """
+def main() -> None:
+    """Inline lifecycle flow: upsert → search → update → fetch → delete."""
     auth = IAM(
         ak=os.environ["VIKINGDB_AK"],
         sk=os.environ["VIKINGDB_SK"],
@@ -71,6 +46,7 @@ def test_snippet_collection_lifecycle() -> None:
     }
     upsert_resp = collection_client.upsert(UpsertDataRequest(data=[chapter]))
     print(f"Upsert request_id={upsert_resp.request_id}")
+    print(upsert_resp.model_dump_json(indent=2, by_alias=True) if hasattr(upsert_resp, "model_dump_json") else json.dumps(upsert_resp.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
 
     time.sleep(2)
 
@@ -81,6 +57,7 @@ def test_snippet_collection_lifecycle() -> None:
         output_fields=["title", "score"],
     )
     search_resp = index_client.search_by_multi_modal(search_req)
+    print(search_resp.model_dump_json(indent=2, by_alias=True) if hasattr(search_resp, "model_dump_json") else json.dumps(search_resp.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
     if not search_resp.result or not search_resp.result.data:
         print("SearchByMultiModal returned no hits")
         return
@@ -94,59 +71,19 @@ def test_snippet_collection_lifecycle() -> None:
         UpdateDataRequest(data=[{"__AUTO_ID__": chapter_id, "score": new_score}])
     )
     print(f"Update request_id={update_resp.request_id}")
+    print(update_resp.model_dump_json(indent=2, by_alias=True) if hasattr(update_resp, "model_dump_json") else json.dumps(update_resp.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
 
     fetch_resp = collection_client.fetch(FetchDataInCollectionRequest(ids=[chapter_id]))
+    print(fetch_resp.model_dump_json(indent=2, by_alias=True) if hasattr(fetch_resp, "model_dump_json") else json.dumps(fetch_resp.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
     if fetch_resp.result and fetch_resp.result.items:
         fetched = fetch_resp.result.items[0].fields.get("score")
         fetched_score = float(fetched) if fetched is not None else None
         print(f"Fetch request_id={fetch_resp.request_id} score={fetched_score}")
 
     delete_resp = collection_client.delete(DeleteDataRequest(ids=[chapter_id]))
     print(f"Delete request_id={delete_resp.request_id}")
+    print(delete_resp.model_dump_json(indent=2, by_alias=True) if hasattr(delete_resp, "model_dump_json") else json.dumps(delete_resp.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
 
 
-@pytest.fixture(scope="module")
-def collection_clients() -> Clients:
-    return build_clients(load_config())
-
-
-def test_scenario_collection_lifecycle(collection_clients: Clients) -> None:
-    session_tag = new_session_tag("collection-lifecycle")
-    request_options = build_request_options(session_tag)
-    base_paragraph = int(time.time()) % 1_000_000
-    chapters = build_story_chapters(session_tag, base_paragraph)
-
-    try:
-        for payload in chapters_to_upsert(chapters):
-            response = collection_clients.collection.upsert(
-                UpsertDataRequest(data=[payload]),
-                request_options=request_options,
-            )
-            assert response.request_id
-
-        assign_chapter_ids_via_search(
-            collection_clients.index,
-            chapters,
-            output_fields=["title", "paragraph", "score"],
-            request_options=request_options,
-        )
-
-        target = next(ch for ch in chapters if ch.key == "retrieval-lab")
-        assert target.chapter_id is not None
-
-        new_score = target.score + 4.25
-        update_resp = collection_clients.collection.update(
-            UpdateDataRequest(data=[{"__AUTO_ID__": target.chapter_id, "score": new_score}]),
-            request_options=request_options,
-        )
-        assert update_resp.request_id
-
-        fetch_resp = collection_clients.collection.fetch(
-            FetchDataInCollectionRequest(ids=[target.chapter_id]),
-            request_options=request_options,
-        )
-        assert fetch_resp.result and fetch_resp.result.items
-        fetched_score = fetch_resp.result.items[0].fields.get("score")
-        assert fetched_score == pytest.approx(new_score)
-    finally:
-        cleanup_chapters(collection_clients.collection, chapters, request_options=request_options)
+if __name__ == "__main__":
+    main()

examples/vector/3_1_index_search_multimodal.py

@@ -0,0 +1,69 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import os
+import time
+import json
+
+from vikingdb import IAM
+from vikingdb.vector import SearchByMultiModalRequest, UpsertDataRequest, VikingVector
+
+
+def main() -> None:
+    """Inline multi-modal search showing filters and output fields."""
+    auth = IAM(
+        ak=os.environ["VIKINGDB_AK"],
+        sk=os.environ["VIKINGDB_SK"],
+    )
+    client = VikingVector(
+        host=os.environ["VIKINGDB_HOST"],
+        region=os.environ["VIKINGDB_REGION"],
+        auth=auth,
+        scheme="https",
+        timeout=30,
+    )
+    collection_client = client.collection(collection_name=os.environ["VIKINGDB_COLLECTION"])
+    index_client = client.index(
+        collection_name=os.environ["VIKINGDB_COLLECTION"],
+        index_name=os.environ["VIKINGDB_INDEX"],
+    )
+
+    base_paragraph = int(time.time() * 1e6) % 1_000_000
+    chapters = [
+        {
+            "title": "Session kickoff",
+            "paragraph": base_paragraph,
+            "score": 73.0,
+            "text": "This kickoff chapter keeps the reference search grounded.",
+        },
+        {
+            "title": "Session filters",
+            "paragraph": base_paragraph + 1,
+            "score": 91.0,
+            "text": "Filter walkthrough for multi-modal search.",
+        },
+    ]
+
+    for payload in chapters:
+        collection_client.upsert(UpsertDataRequest(data=[payload]))
+
+    time.sleep(2)
+
+    filter_map = {"op": "range", "field": "paragraph", "gte": base_paragraph, "lte": base_paragraph + 1}
+    search_req = SearchByMultiModalRequest(
+        text="Which chapter explains the session filters?",
+        need_instruction=False,
+        limit=2,
+        output_fields=["title", "score", "paragraph"],
+        filter=filter_map,
+    )
+    response = index_client.search_by_multi_modal(search_req)
+    hits = response.result.data if response.result and response.result.data else []
+    print(f"SearchByMultiModal request_id={response.request_id} hits={len(hits)}")
+    print(response.model_dump_json(indent=2, by_alias=True) if hasattr(response, "model_dump_json") else json.dumps(response.model_dump(by_alias=True, mode="json"), ensure_ascii=False, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()