## 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.
- 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:
```bash
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
```python
import os
from vikingdb import IAM
from vikingdb.vector import SearchByRandomRequest, VikingVector
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.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
```python
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)
```
### 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):
```bash
uv add --dev pytest
```
3. Execute the guides:
```bash
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:
```bash
# 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
```
### 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 (`VikingVector`, `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.
### 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
│ ├── 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
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
```
### Contributing
Contributions and feedback are welcome. Please ensure any new APIs match the OpenAPI specification and include accompanying example coverage.
Raw data
{
"_id": null,
"home_page": null,
"name": "vikingdb-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "vikingdb, vector, bytedance, volcengine, sdk",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a1/c6/e6346ef89a6bcf20051ad20600f3598cdc1d85be4c315a9592fc8384e61e/vikingdb_python_sdk-0.1.2.tar.gz",
"platform": null,
"description": "## VikingDB Python SDK (v2)\n\nThis 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).\n\n### Key Features\n- Simple client configuration with AK/SK signing (Volcano Engine V4) or API-key authentication.\n- **Vector Database**: Request envelope handling with typed request/response models covering collection, index, and embedding workflows.\n- **Memory Management**: Conversational memory APIs for managing user profiles, events, and session messages with semantic search capabilities.\n- Pluggable retry strategy (exponential backoff with jitter) and per-request overrides (`RequestOptions`).\n- 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.\n\n### Installation\n\nClone the repository and install the SDK in editable mode:\n\n```bash\nuv add vikingdb-python-sdk\n```\n\n> **Dependencies:** The SDK relies on `requests`, `pydantic>=2.5`, and the Volcano Engine base SDK (`volcengine`) for request signing.\n\n### Quickstart\n\n#### Vector Database\n\n```python\nimport os\nfrom vikingdb import IAM\nfrom vikingdb.vector import SearchByRandomRequest, VikingVector\n\nauth = IAM(ak=os.environ[\"VIKINGDB_AK\"], sk=os.environ[\"VIKINGDB_SK\"]) \nclient = VikingVector(\n host=os.environ[\"VIKINGDB_HOST\"],\n region=os.environ[\"VIKINGDB_REGION\"],\n auth=auth,\n scheme=\"https\",\n timeout=30,\n)\nindex = client.index(\n collection_name=os.environ[\"VIKINGDB_COLLECTION\"],\n index_name=os.environ[\"VIKINGDB_INDEX\"],\n)\nresp = index.search_by_random(SearchByRandomRequest(limit=1))\nprint(f\"request_id={resp.request_id} hits={len(resp.result.data or [])}\")\n```\n\n#### Memory Management\n\n```python\nfrom vikingdb import IAM\nfrom vikingdb.memory import VikingMem\n\nauth = IAM(ak=\"<AK>\", sk=\"<SK>\")\nclient = VikingMem(\n host=\"api-knowledgebase.mlp.cn-beijing.volces.com\",\n region=\"cn-beijing\",\n auth=auth,\n scheme=\"http\",\n)\n\n# Get collection\ncollection = client.get_collection(\n collection_name=\"demo_collection\",\n project_name=\"default\"\n)\n\n# Add session messages\ncollection.add_session(\n session_id=\"session_001\",\n messages=[\n {\"role\": \"user\", \"content\": \"Hello, how is the weather today?\"},\n {\"role\": \"assistant\", \"content\": \"Today is sunny, perfect for going out.\"}\n ],\n metadata={\n \"default_user_id\": \"user_001\",\n \"default_assistant_id\": \"assistant_001\",\n }\n)\n\n# Search memories\nresult = collection.search_memory(\n query=\"weather today\",\n filter={\"user_id\": \"user_001\", \"memory_type\": [\"event_v1\"]},\n limit=10\n)\nprint(\"search results:\", result)\n```\n\n### Example Guides\n\n#### Vector Examples\n\nThe integration guides under `examples/vector` mirror the Go SDK walkthroughs (`1`\u2013`6`). Each test connects to a live VikingDB environment and exercises a specific workflow.\n\n1. Set the required environment variables (or create a `.env` file in the project root):\n\n ```\n VIKINGDB_AK=your-access-key\n VIKINGDB_SK=your-secret-key\n VIKINGDB_COLLECTION=demo_collection\n VIKINGDB_INDEX=demo_index\n # Optional:\n # VIKINGDB_PROJECT=project-name\n # VIKINGDB_RESOURCE_ID=resource-id\n ```\n\n The pytest guides themselves lock to the ap-southeast-1 public datasets:\n\n - host: `api-vikingdb.vikingdb.ap-southeast-1.volces.com`\n - region: `ap-southeast-1`\n - text walkthroughs use `collection=text`, `index=text_index`\n - vector walkthroughs use `collection=vector`, `index=vector_index`\n\n2. Install pytest (if not already available):\n\n ```bash\n uv add --dev pytest\n ```\n\n3. Execute the guides:\n\n ```bash\n uv run pytest examples/vector -k scenario\n ```\n\nEach scenario writes temporary documents using unique session tags and cleans them up afterwards.\n\n#### Memory Examples\n\nThe memory examples under `examples/memory` demonstrate the core workflows for managing conversational memories:\n\n1. **01_init_client_and_collection.py**: Initialize the VikingMem client and get collection instances using either collection name + project name or resource ID.\n\n2. **02_add_session.py**: Add session messages (user-assistant conversations) to the memory collection with metadata such as user ID, assistant ID, and timestamps.\n\n3. **03_search_memory.py**: Search memories with various filters including:\n - User profile search\n - Event search by semantic query\n - Time range filtering for recent events\n\nTo run the memory examples:\n\n```bash\n# Set environment variables\nexport VIKINGDB_AK=your-access-key\nexport VIKINGDB_SK=your-secret-key\n\n# Run individual examples\npython examples/memory/01_init_client_and_collection.py\npython examples/memory/02_add_session.py\npython examples/memory/03_search_memory.py\n```\n\n### Architecture Overview\n\n- `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).\n- Domain-specific features live under dedicated namespaces such as `vikingdb.vector` and `vikingdb.memory`, where the high-level clients (`VikingVector`, `VikingMem`) compose the shared auth stack atop the shared client.\n- Vector request/response models now surface directly from `vikingdb.vector` (backed internally by `vikingdb/vector/models`).\n- Memory APIs return plain dictionaries without object encapsulation, providing a lightweight interface for conversational memory management (session, profile, event operations).\n- 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.\n\n### Project Structure\n\n```\nvikingdb/\n\u251c\u2500\u2500 _client.py # Shared base client built on volcengine Service\n\u251c\u2500\u2500 auth.py # Shared auth providers (IAM, API key)\n\u251c\u2500\u2500 request_options.py # Per-request overrides shared by all services\n\u251c\u2500\u2500 version.py # Package metadata\n\u251c\u2500\u2500 vector/ # Vector-specific clients and models\n\u2502 \u251c\u2500\u2500 __init__.py # High-level vector client and namespace exports\n\u2502 \u251c\u2500\u2500 base.py # Shared helpers for vector clients\n\u2502 \u251c\u2500\u2500 collection.py # Collection operations\n\u2502 \u251c\u2500\u2500 embedding.py # Embedding operations\n\u2502 \u251c\u2500\u2500 index.py # Index/search operations\n\u2502 \u251c\u2500\u2500 client.py # Vector service wrapper and high-level client\n\u2502 \u251c\u2500\u2500 exceptions.py # Vector-specific exceptions\n\u2502 \u2514\u2500\u2500 models/ # Vector request/response models (pydantic)\n\u251c\u2500\u2500 memory/ # Memory-specific clients and models\n\u2502 \u251c\u2500\u2500 __init__.py # High-level memory client and namespace exports\n\u2502 \u251c\u2500\u2500 client.py # VikingMem service client\n\u2502 \u251c\u2500\u2500 collection.py # Memory collection operations\n\u2502 \u251c\u2500\u2500 types.py # Type definitions for memory operations\n\u2502 \u2514\u2500\u2500 exceptions.py # Memory-specific exceptions\n\nexamples/\n\u251c\u2500\u2500 vector/ # Vector integration guides (pytest)\n\u2502 \u251c\u2500\u2500 1_connectivity_test.py\n\u2502 \u251c\u2500\u2500 2_collection_lifecycle_test.py\n\u2502 \u251c\u2500\u2500 3_*_test.py # Search and indexing examples\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 memory/ # Memory usage examples\n \u251c\u2500\u2500 01_init_client_and_collection.py\n \u251c\u2500\u2500 02_add_session.py\n \u2514\u2500\u2500 03_search_memory.py\n```\n\n### Contributing\n\nContributions and feedback are welcome. Please ensure any new APIs match the OpenAPI specification and include accompanying example coverage.\n",
"bugtrack_url": null,
"license": null,
"summary": "vikingdb Python SDK",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/volcengine/volc-vikingdb-python-sdk/README.md",
"Source": "https://github.com/volcengine/volc-vikingdb-python-sdk"
},
"split_keywords": [
"vikingdb",
" vector",
" bytedance",
" volcengine",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "40fe256503700edcc9b6823dbeaf33557f62b520595ae126214daf7a63c9952d",
"md5": "c9810daee732da4fe47146a09614345a",
"sha256": "66744d69b1f215839af705efdc2986ab4c6c1250720b0e3897f13dde31ac5f1e"
},
"downloads": -1,
"filename": "vikingdb_python_sdk-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9810daee732da4fe47146a09614345a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 34247,
"upload_time": "2025-11-06T04:09:57",
"upload_time_iso_8601": "2025-11-06T04:09:57.658445Z",
"url": "https://files.pythonhosted.org/packages/40/fe/256503700edcc9b6823dbeaf33557f62b520595ae126214daf7a63c9952d/vikingdb_python_sdk-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a1c6e6346ef89a6bcf20051ad20600f3598cdc1d85be4c315a9592fc8384e61e",
"md5": "70fa53bd0009037c1e695ec802d15798",
"sha256": "e2efd64b27110fc43b1e84409bce058995bd03488f2196af75adbdf084f51fe1"
},
"downloads": -1,
"filename": "vikingdb_python_sdk-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "70fa53bd0009037c1e695ec802d15798",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28072,
"upload_time": "2025-11-06T04:09:59",
"upload_time_iso_8601": "2025-11-06T04:09:59.192680Z",
"url": "https://files.pythonhosted.org/packages/a1/c6/e6346ef89a6bcf20051ad20600f3598cdc1d85be4c315a9592fc8384e61e/vikingdb_python_sdk-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-06 04:09:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "volcengine",
"github_project": "volc-vikingdb-python-sdk",
"github_not_found": true,
"lcname": "vikingdb-python-sdk"
}
JSON
