vikingdb-python-sdk 0.1.11__tar.gz → 0.1.13__tar.gz

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/PKG-INFO

@@ -1,8 +1,8 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: vikingdb-python-sdk
-Version: 0.1.11
+Version: 0.1.13
 Summary: vikingdb Python SDK
-License-Expression: Apache-2.0
+License: Apache-2.0
 Project-URL: Documentation, https://github.com/volcengine/volc-vikingdb-python-sdk/README.md
 Project-URL: Source, https://github.com/volcengine/volc-vikingdb-python-sdk
 Keywords: vikingdb,vector,bytedance,volcengine,sdk
@@ -24,7 +24,6 @@ Requires-Dist: typing_extensions>=4.9.0
 Requires-Dist: urllib3>=1.21.1
 Requires-Dist: volcengine>=1.0.0
 Requires-Dist: aiohttp>=3.10.0
-Dynamic: license-file
 
 ## VikingDB Python SDK (v2)
 
@@ -34,6 +33,7 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 - 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.
 
@@ -114,6 +114,40 @@ result = collection.search_memory(
 print("search results:", result)
 ```
 
+#### Knowledge Base
+
+```python
+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
@@ -179,6 +213,40 @@ 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:
+
+```bash
+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).
@@ -186,6 +254,7 @@ python examples/memory/03_search_memory.py
 - 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
 
@@ -211,6 +280,12 @@ vikingdb/
 │   ├── 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)
@@ -222,6 +297,11 @@ 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

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/README.md

@@ -6,6 +6,7 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 - 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.
 
@@ -86,6 +87,40 @@ result = collection.search_memory(
 print("search results:", result)
 ```
 
+#### Knowledge Base
+
+```python
+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
@@ -151,6 +186,40 @@ 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:
+
+```bash
+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).
@@ -158,6 +227,7 @@ python examples/memory/03_search_memory.py
 - 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
 
@@ -183,6 +253,12 @@ vikingdb/
 │   ├── 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)
@@ -194,6 +270,11 @@ 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

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "vikingdb Python SDK"
 readme = "README.md"
 requires-python = ">=3.8"
-license = "Apache-2.0"
+license = {text = "Apache-2.0"}
 keywords = ["vikingdb", "vector", "bytedance", "volcengine", "sdk"]
 classifiers = [
     "Development Status :: 4 - Beta",

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/vikingdb/__init__.py

@@ -19,6 +19,11 @@ from .memory import (
     VikingMem,
     Collection,
 )
+from .knowledge import (
+    VikingKnowledge,
+    KnowledgeCollection,
+)
+
 from .version import __version__
 __all__ = [
     "IAM",
@@ -34,5 +39,7 @@ __all__ = [
     "memory",
     "VikingMem",
     "Collection",
+    "VikingKnowledge",
+    "KnowledgeCollection",
     "__version__",
 ]

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/vikingdb/_client.py

@@ -260,3 +260,56 @@ class Client(Service, ABC):
                     request_id=request_id,
                     message=f"failed to run aiohttp {api}: {exc}",
                 ) from exc
+
+
+    def _stream_json(self, api, params, body, headers=None, timeout=None):
+        if api not in self.api_info:
+            raise Exception("no such api")
+        api_info = self.api_info[api]
+        request = self.prepare_request(api_info, params)
+        if headers:
+            for key, value in headers.items():
+                request.headers[key] = value
+        request.headers["Content-Type"] = "application/json"
+        request.headers["Accept"] = "text/event-stream"
+        request.body = body
+        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"
+        if timeout is not None:
+            request_timeout = (timeout, timeout)
+        else:
+            request_timeout = (
+                self.service_info.connection_timeout,
+                self.service_info.socket_timeout,
+            )
+        response = self.session.post(
+            url,
+            headers=request.headers,
+            data=request.body,
+            stream=True,
+            timeout=request_timeout,
+        )
+        if response.status_code != 200:
+            payload_text_attr = getattr(response, "text", "")
+            payload_text = payload_text_attr if isinstance(payload_text_attr, str) else ""
+            payload_text = payload_text or ""
+            raise VikingAPIException.from_response(
+                payload_text,
+                request_id=request_id,
+                status_code=response.status_code,
+            )
+        for line in response.iter_lines():
+            s = line.decode("utf-8")
+            if not s:
+                continue
+            if s.startswith("data:"):
+                data_str = s.split("data:", 1)[1]
+                data = json.loads(data_str)
+                yield data
+                try:
+                    if "end" in data.get("data", {}):
+                        break
+                except Exception:
+                    pass

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/vikingdb/knowledge/client.py

@@ -5,14 +5,14 @@
 from __future__ import annotations
 
 import json
-from typing import Mapping, Optional, Union, Sequence, cast
+from typing import Mapping, Optional, Union, Sequence, Iterable
 
 from volcengine.ApiInfo import ApiInfo
 
 from .. import APIKey
 from .._client import Client, _REQUEST_ID_HEADER
 from ..auth import Auth
-from ..exceptions import VikingException, promote_exception
+from ..exceptions import VikingException, promote_exception, VikingAPIException
 from .exceptions import EXCEPTION_MAP, VikingKnowledgeException
 from ..version import __version__
 from .models.base import CollectionMeta, Model
@@ -90,6 +90,16 @@ class VikingKnowledge(Client):
             raise VikingKnowledgeException(1000028, "missed", "empty response due to unknown error", status_code=None)
         return res
 
+    def stream_json_exception(self, api, params, body, headers=None, timeout=None):
+        try:
+            for item in self._stream_json(api, params, body, headers=headers, timeout=timeout):
+                yield item
+        except VikingException as exc:
+            raise promote_exception(exc, exception_map=EXCEPTION_MAP, default_cls=VikingKnowledgeException) from None
+        except Exception as exc:
+            raise exc
+        return
+
     async def async_json_exception(self, api, params, body, headers=None, timeout=None):
         try:
             res = await self.async_json(api, params, body, headers=headers, timeout=timeout)
@@ -146,15 +156,20 @@ class VikingKnowledge(Client):
         *,
         headers: Optional[Mapping[str, str]] = None,
         timeout: Optional[int] = None,
-    ) -> ChatCompletionResponse:
+    ) -> Union[ChatCompletionResponse, Iterable[ChatCompletionResponse]]:
         payload = (
             request.model_dump(by_alias=True, exclude_none=True)  # type: ignore[attr-defined]
             if isinstance(request, ChatCompletionRequest)
             else dict(request)
         )
-        res = self.json_exception("ChatCompletion", {}, json.dumps(payload), headers=headers, timeout=timeout)
-        response = ChatCompletionResponse.parse_with(res)
-        return response
+        if bool(payload.get("stream")):
+            def _gen():
+                for res in self.stream_json_exception("ChatCompletion", {}, json.dumps(payload), headers=headers, timeout=timeout):
+                    yield ChatCompletionResponse.parse_with(res)
+            return _gen()
+        else:
+            res = self.json_exception("ChatCompletion", {}, json.dumps(payload), headers=headers, timeout=timeout)
+            return ChatCompletionResponse.parse_with(res)
 
     def service_chat(
         self,
@@ -162,13 +177,17 @@ class VikingKnowledge(Client):
         *,
         headers: Optional[Mapping[str, str]] = None,
         timeout: Optional[int] = None,
-    ) -> ServiceChatResponse:
+    ) -> Union[ServiceChatResponse, Iterable[ServiceChatResponse]]:
         payload = (
             request.model_dump(by_alias=True, exclude_none=True)  # type: ignore[attr-defined]
             if isinstance(request, ServiceChatRequest)
             else dict(request)
         )
-        req_headers = dict(headers or {})
-        res = self.json_exception("ServiceChat", {}, json.dumps(payload), headers=req_headers, timeout=timeout)
-        response = ServiceChatResponse.parse_with(res)
-        return response
+        if bool(payload.get("stream")):
+            def _gen():
+                for res in self.stream_json_exception("ServiceChat", {}, json.dumps(payload), headers=headers, timeout=timeout):
+                    yield ServiceChatResponse.parse_with(res)
+            return _gen()
+        else:
+            res = self.json_exception("ServiceChat", {}, json.dumps(payload), headers=headers, timeout=timeout)
+            return ServiceChatResponse.parse_with(res)

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/vikingdb/vector/models/index.py

@@ -95,9 +95,13 @@ class SearchByScalarRequest(SearchBase):
 
 
 class SearchByKeywordsRequest(SearchBase):
+    mode: Optional[str] = Field(default=None, alias="mode")
     keywords: Optional[Sequence[str]] = Field(default=None, alias="keywords")
     query: Optional[str] = Field(default=None, alias="query")
     case_sensitive: Optional[bool] = Field(default=None, alias="case_sensitive")
+    fields: Optional[Sequence[str]] = Field(default=None, alias="fields")
+    bm25_k1: Optional[float] = Field(default=None, alias="bm25_k1")
+    bm25_b: Optional[float] = Field(default=None, alias="bm25_b")
 
 
 class SearchByRandomRequest(SearchBase):

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/vikingdb/version.py

@@ -1,4 +1,4 @@
 # Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = '0.1.11'
+__version__ = '0.1.13'

{vikingdb_python_sdk-0.1.11 → vikingdb_python_sdk-0.1.13}/vikingdb_python_sdk.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: vikingdb-python-sdk
-Version: 0.1.11
+Version: 0.1.13
 Summary: vikingdb Python SDK
-License-Expression: Apache-2.0
+License: Apache-2.0
 Project-URL: Documentation, https://github.com/volcengine/volc-vikingdb-python-sdk/README.md
 Project-URL: Source, https://github.com/volcengine/volc-vikingdb-python-sdk
 Keywords: vikingdb,vector,bytedance,volcengine,sdk
@@ -24,7 +24,6 @@ Requires-Dist: typing_extensions>=4.9.0
 Requires-Dist: urllib3>=1.21.1
 Requires-Dist: volcengine>=1.0.0
 Requires-Dist: aiohttp>=3.10.0
-Dynamic: license-file
 
 ## VikingDB Python SDK (v2)
 
@@ -34,6 +33,7 @@ This package provides an idiomatic Python interface to the VikingDB v2 data-plan
 - 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.
 
@@ -114,6 +114,40 @@ result = collection.search_memory(
 print("search results:", result)
 ```
 
+#### Knowledge Base
+
+```python
+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
@@ -179,6 +213,40 @@ 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:
+
+```bash
+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).
@@ -186,6 +254,7 @@ python examples/memory/03_search_memory.py
 - 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
 
@@ -211,6 +280,12 @@ vikingdb/
 │   ├── 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)
@@ -222,6 +297,11 @@ 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