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.

Security and privacy

This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md.