VikingDB Python SDK (v2)

This package provides an idiomatic Python interface to the VikingDB v2 data-plane APIs. The SDK mirrors the behaviour and API surface of the official Java and Go clients while embracing Python conventions (dataclasses/pydantic models, requests-based transport, and pytest-driven examples).

Key Features

• Simple client configuration with AK/SK signing (Volcano Engine V4) or API-key authentication.
• Vector Database: Request envelope handling with typed request/response models covering collection, index, and embedding workflows.
• Memory Management: Conversational memory APIs for managing user profiles, events, and session messages with semantic search capabilities.
• Knowledge Base: Document and point CRUD with typed models, hybrid retrieval (search_collection, search_knowledge), rerank, and chat-completion/service-chat orchestration.
• Pluggable retry strategy (exponential backoff with jitter) and per-request overrides (RequestOptions).
• Executable example guides (pytest integration tests and standalone scripts) that demonstrate connectivity, CRUD, search, analytics, embedding, and memory management scenarios against a real VikingDB environment.

Installation

Clone the repository and install the SDK in editable mode:

uv add vikingdb-python-sdk

Dependencies: The SDK relies on requests, pydantic>=2.5, and the Volcano Engine base SDK (volcengine) for request signing.

Quickstart

Vector Database

import os
from vikingdb import IAM
from vikingdb.vector import SearchByRandomRequest, VikingDB

auth = IAM(ak=os.environ["VIKINGDB_AK"], sk=os.environ["VIKINGDB_SK"]) 
client = VikingDB(
    host=os.environ["VIKINGDB_HOST"],
    region=os.environ["VIKINGDB_REGION"],
    auth=auth,
    scheme="https",
    timeout=30,
)
index = client.index(
    collection_name=os.environ["VIKINGDB_COLLECTION"],
    index_name=os.environ["VIKINGDB_INDEX"],
)
resp = index.search_by_random(SearchByRandomRequest(limit=1))
print(f"request_id={resp.request_id} hits={len(resp.result.data or [])}")

Memory Management

from vikingdb import IAM
from vikingdb.memory import VikingMem

auth = IAM(ak="<AK>", sk="<SK>")
client = VikingMem(
    host="api-knowledgebase.mlp.cn-beijing.volces.com",
    region="cn-beijing",
    auth=auth,
    scheme="http",
)

# Get collection
collection = client.get_collection(
    collection_name="demo_collection",
    project_name="default"
)

# Add session messages
collection.add_session(
    session_id="session_001",
    messages=[
        {"role": "user", "content": "Hello, how is the weather today?"},
        {"role": "assistant", "content": "Today is sunny, perfect for going out."}
    ],
    metadata={
        "default_user_id": "user_001",
        "default_assistant_id": "assistant_001",
    }
)

# Search memories
result = collection.search_memory(
    query="weather today",
    filter={"user_id": "user_001", "memory_type": ["event_v1"]},
    limit=10
)
print("search results:", result)

Knowledge Base

import os
from vikingdb import IAM, APIKey
from vikingdb.knowledge import (
    VikingKnowledge,
    KnowledgeCollection,
    SearchKnowledgeRequest,
)

# IAM auth for collection-level operations
client = VikingKnowledge(
    auth=IAM(ak=os.getenv("VOLC_AK"), sk=os.getenv("VOLC_SK")),
    host="api-knowledgebase.mlp.cn-beijing.volces.com",
    region="cn-beijing",
    scheme="http",
)

collection = client.collection(
    resource_id=os.getenv("VIKING_COLLECTION_RID"),
    collection_name=os.getenv("VIKING_COLLECTION_NAME") or "financial_reports",
    project_name=os.getenv("VIKING_PROJECT") or "default",
)

resp = collection.search_knowledge(
    SearchKnowledgeRequest(query="2025 Q1 revenue growth", limit=5, dense_weight=0.5)
)
print(f"request_id={resp.request_id} hits={len(resp.result.result_list or [])}")

# API-key auth for service-level chat
svc_client = VikingKnowledge(auth=APIKey(api_key=os.getenv("VIKING_SERVICE_API_KEY")))

Example Guides

Vector Examples

The integration guides under examples/vector mirror the Go SDK walkthroughs (1–6). Each test connects to a live VikingDB environment and exercises a specific workflow.

1. Set the required environment variables (or create a .env file in the project root):

   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

   The pytest guides themselves lock to the ap-southeast-1 public datasets:

   • host: api-vikingdb.vikingdb.ap-southeast-1.volces.com
   • region: ap-southeast-1
   • text walkthroughs use collection=text, index=text_index
   • vector walkthroughs use collection=vector, index=vector_index

2. Install pytest (if not already available):

   uv add --dev pytest

3. Execute the guides:

   uv run pytest examples/vector -k scenario

Each scenario writes temporary documents using unique session tags and cleans them up afterwards.

Memory Examples

The memory examples under examples/memory demonstrate the core workflows for managing conversational memories:

1. 01_init_client_and_collection.py: Initialize the VikingMem client and get collection instances using either collection name + project name or resource ID.

2. 02_add_session.py: Add session messages (user-assistant conversations) to the memory collection with metadata such as user ID, assistant ID, and timestamps.

3. 03_search_memory.py: Search memories with various filters including:

   • User profile search
   • Event search by semantic query
   • Time range filtering for recent events

To run the memory examples:

# Set environment variables
export VIKINGDB_AK=your-access-key
export VIKINGDB_SK=your-secret-key

# Run individual examples
python examples/memory/01_init_client_and_collection.py
python examples/memory/02_add_session.py
python examples/memory/03_search_memory.py

Knowledge Examples

The examples under examples/knowledge cover core knowledge base workflows:

1. 01_init_client.py: Initialize VikingKnowledge and obtain collections by resource ID or by name + project.
2. 02_doc_crud.py: Add documents via URL or TOS path (add_doc_v2), get/update metadata, list documents.
3. 03_point_crud.py: Add/update/delete points (chunks) within a document; list and fetch detailed point info.
4. 04_search.py: Perform collection search and knowledge search, invoke rerank, and orchestrate chat-completion or service-chat (including streaming).

Environment variables:

VOLC_AK=your-access-key
VOLC_SK=your-secret-key
VIKING_PROJECT=project-name
VIKING_COLLECTION_RID=collection-resource-id
VIKING_COLLECTION_NAME=collection-name
# For chat/service features:
VIKING_CHAT_API_KEY=chat-api-key
VIKING_SERVICE_API_KEY=service-api-key
VIKING_SERVICE_RID=service-resource-id
# Optional for rerank:
VIKING_RERANK_INSTRUCTION=custom-instruction

Run individual examples:

python examples/knowledge/01_init_client.py
python examples/knowledge/02_doc_crud.py
python examples/knowledge/03_point_crud.py
python examples/knowledge/04_search.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 (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.
• Knowledge base APIs surface typed pydantic models under vikingdb.knowledge for documents, points, search, rerank, and chat/service chat, with IAM and API-key authentication modes.

Project Structure

vikingdb/
├── _client.py          # Shared base client built on volcengine Service
├── auth.py              # Shared auth providers (IAM, API key)
├── request_options.py   # Per-request overrides shared by all services
├── version.py           # Package metadata
├── vector/              # Vector-specific clients and models
│   ├── __init__.py      # High-level vector client and namespace exports
│   ├── base.py          # Shared helpers for vector clients
│   ├── collection.py    # Collection operations
│   ├── embedding.py     # Embedding operations
│   ├── rerank.py        # rerank operations
│   ├── index.py         # Index/search operations
│   ├── client.py        # Vector service wrapper and high-level client
│   ├── exceptions.py    # Vector-specific exceptions
│   └── models/          # Vector request/response models (pydantic)
├── memory/              # Memory-specific clients and models
│   ├── __init__.py      # High-level memory client and namespace exports
│   ├── client.py        # VikingMem service client
│   ├── collection.py    # Memory collection operations
│   ├── types.py         # Type definitions for memory operations
│   └── exceptions.py    # Memory-specific exceptions
├── knowledge/           # Knowledge base clients and models
│   ├── __init__.py      # High-level knowledge client and exports
│   ├── client.py        # VikingKnowledge service client
│   ├── collection.py    # Document/point/search operations
│   ├── exceptions.py    # Knowledge-specific exceptions
│   └── models/          # Typed pydantic models (doc, point, search, chat, rerank)

examples/
├── vector/              # Vector integration guides (pytest)
│   ├── 1_connectivity_test.py
│   ├── 2_collection_lifecycle_test.py
│   ├── 3_*_test.py     # Search and indexing examples
│   └── ...
└── memory/              # Memory usage examples
    ├── 01_init_client_and_collection.py
    ├── 02_add_session.py
    └── 03_search_memory.py
└── knowledge/           # Knowledge base usage examples
    ├── 01_init_client.py
    ├── 02_doc_crud.py
    ├── 03_point_crud.py
    └── 04_search.py

Contributing

Contributions and feedback are welcome. Please ensure any new APIs match the OpenAPI specification and include accompanying example coverage.