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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vikingdb-python-sdk
-Version: 0.1.12
+Version: 0.1.13
 Summary: vikingdb Python SDK
 License: Apache-2.0
 Project-URL: Documentation, https://github.com/volcengine/volc-vikingdb-python-sdk/README.md
@@ -33,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.
 
@@ -113,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
@@ -178,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).
@@ -185,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
 
@@ -210,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)
@@ -221,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.12 → 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.12 → 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.12 → 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.12 → 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.12 → vikingdb_python_sdk-0.1.13}/vikingdb/knowledge/collection.py

@@ -63,12 +63,6 @@ class KnowledgeCollection:
             if isinstance(request, Model)
             else dict(request)
         )
-        if request.file_path:
-
-
-
-            pass
-
         payload = {**self._meta_payload, **req_payload}
         res = self.client.json_exception("AddDocV2", {}, json.dumps(payload), headers=headers, timeout=timeout)
         response = AddDocResponse.parse_with(res)
@@ -267,36 +261,3 @@ class KnowledgeCollection:
         res = self.client.json_exception("SearchKnowledge", {}, json.dumps(payload), headers=headers, timeout=timeout)
         response = SearchKnowledgeResponse.parse_with(res)
         return response
-
-    def _upload_file(self, file_path: str) -> str:
-        with open(file_path, "rb") as f:
-            res = self.client.json_exception("UploadFile", {}, f.read())
-
-        # https://console.volcengine.com/api/top/vikingdb/cn-beijing/2025-04-01/GetKnowledgeBasePreSignedUrl?KnowledgeBaseId=kb-1e04481ba6a823c2&ProjectName=default
-        # {"TosPaths": ["2026_02_05_21_40_30rvbjCrtJycnAGsOFvXrphLN7F7VRsP2e/核心流程.md"]}
-        """
-        {
-            "Result": {
-                "PreSignedUrls": [
-                    "https://knowledgebase-fileupload.tos-cn-beijing.volces.com/ADD_DOC/2100655893/2026_02_05_21_40_30rvbjCrtJycnAGsOFvXrphLN7F7VRsP2e/%E6%A0%B8%E5%BF%83%E6%B5%81%E7%A8%8B.md?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Content-Sha256=UNSIGNED-PAYLOAD&X-Tos-Credential=AKLTOTg3ODc0NTAyYzU1NDIxNmJmODg1MWUyYTkwZDY3ZGM%2F20260205%2Ftos-cn-beijing.volces.com%2Ftos%2Frequest&X-Tos-Date=20260205T134045Z&X-Tos-Expires=300&X-Tos-SignedHeaders=host&X-Tos-Signature=712e8572edc6d251bf234cdb580246714c1ac9414e824ac1fe110772a6372fbc"
-                ],
-                "BucketName": "knowledgebase-fileupload"
-            },
-            "ResponseMetadata": {
-                "RequestId": "202602052140452A8D3265DCDE1911D17B",
-                "Action": "GetKnowledgeBasePreSignedUrl",
-                "Version": "2025-04-01",
-                "Service": "vikingdb",
-                "Region": "cn-beijing"
-            }
-        }
-        """
-
-        """
-        https://knowledgebase-fileupload.tos-cn-beijing.volces.com/ADD_DOC/2100655893/2026_02_05_21_40_30rvbjCrtJycnAGsOFvXrphLN7F7VRsP2e/%E6%A0%B8%E5%BF%83%E6%B5%81%E7%A8%8B.md?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Content-Sha256=UNSIGNED-PAYLOAD&X-Tos-Credential=AKLTOTg3ODc0NTAyYzU1NDIxNmJmODg1MWUyYTkwZDY3ZGM%2F20260205%2Ftos-cn-beijing.volces.com%2Ftos%2Frequest&X-Tos-Date=20260205T134045Z&X-Tos-Expires=300&X-Tos-SignedHeaders=host&X-Tos-Signature=712e8572edc6d251bf234cdb580246714c1ac9414e824ac1fe110772a6372fbc        
-        """
-
-
-
-        return res["data"]["uri"]
-

{vikingdb_python_sdk-0.1.12 → vikingdb_python_sdk-0.1.13}/vikingdb/knowledge/models/doc.py

@@ -41,7 +41,6 @@ class AddDocRequest(Model):
     doc_type: Optional[str] = Field(default=None, alias="doc_type")
     description: Optional[str] = Field(default=None, alias="description")
     tos_path: Optional[str] = Field(default=None, alias="tos_path")
-    file_path: Optional[str] = Field(default=None, alias="file_path")
     url: Optional[str] = Field(default=None, alias="url")
     lark_file: Optional[str] = Field(default=None, alias="lark_file")
     meta: Optional[List["MetaItem"]] = Field(default=None, alias="meta")
@@ -64,7 +63,6 @@ class AddDocV2Request(Model):
     description: Optional[str] = Field(default=None, alias="description")
     tag_list: Optional[List[MetaItem]] = Field(default=None, alias="tag_list")
     uri: Optional[str] = Field(default=None, alias="uri")
-    file_path: Optional[str] = Field(default=None, alias="file_path")
 
 class DedupInfo(Model):
     skip: Optional[bool] = Field(default=None, alias="skip")

{vikingdb_python_sdk-0.1.12 → 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.12'
+__version__ = '0.1.13'

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vikingdb-python-sdk
-Version: 0.1.12
+Version: 0.1.13
 Summary: vikingdb Python SDK
 License: Apache-2.0
 Project-URL: Documentation, https://github.com/volcengine/volc-vikingdb-python-sdk/README.md
@@ -33,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.
 
@@ -113,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
@@ -178,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).
@@ -185,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
 
@@ -210,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)
@@ -221,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