Use OpenViking storage

The openviking backend delegates resource parsing, indexing, and retrieval to OpenViking, so VeADK does not need a local embedding model. Each index maps to viking://user/<openviking_user_id>/resources/<index>/ by default, where openviking_user_id is the owner/context the resources belong to; it defaults to default. This backend is available in VeADK 1.0.3 and later.

openviking_user_id identifies the OpenViking owner/context used to isolate resources and memory for different applications or tenants within the same OpenViking service. It is distinct from Runner.user_id, which identifies the end user.

Dependencies

The OpenViking SDK is part of VeADK’s base dependencies:

pip install veadk-python

Prepare a reachable OpenViking service and a service-owner API key. In production, inject credentials through environment variables or a secret manager:

export DATABASE_OPENVIKING_URL="https://openviking.example.com"
export DATABASE_OPENVIKING_API_KEY="your-openviking-api-key"

Imported documents are sent to the configured OpenViking service. Before processing personal, business, or other sensitive data, verify that the service location, access controls, and retention policy meet your requirements.

Example

import os

from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(
    backend="openviking",
    index="product_docs",
    backend_config={
        "index": "product_docs",
        "url": "https://openviking.example.com",
        "api_key": os.environ["DATABASE_OPENVIKING_API_KEY"],
        # Optional; defaults to default when omitted
        "openviking_user_id": "product_app",
    },
)
kb.add_from_text("Annual leave is 15 days per year")
for entry in kb.search("annual leave"):
    print(entry.content)

agent = Agent(knowledgebase=kb)

When backend_config is omitted, url, api_key, and openviking_user_id are read from the DATABASE_OPENVIKING_* environment variables, and index comes from KnowledgeBase(index=...) or app_name:

kb = KnowledgeBase(
    backend="openviking",
    index="product_docs",
)
kb.add_from_directory("./docs")

Call close() to release the OpenViking client held by the backend when the knowledge base is no longer needed:

kb.close()

Parameters

KnowledgeBase parameters

Parameter	Type	Default	Description
`backend`	`str \| BaseKnowledgebaseBackend`	`"local"`	Set to `openviking` or pass a backend instance
`backend_config`	`dict`	`{}`	Must include index when nonempty; does not merge the outer index
`index`	`str`	`""`	Index name; falls back to app_name when no configuration dictionary is supplied
`app_name`	`str`	`""`	Fallback for index; not a user authorization filter
`top_k`	`int`	`10`	Default result count; search(top_k=0) uses this value
`name`	`str`	`"user_knowledgebase"`	Knowledge-base name shown to the agent
`description`	`str`	`"This knowledgebase stores some user-related information."`	Explains the knowledge base to the agent
`enable_profile`	`bool`	`False`	Enables document profiles; generate profile files first, or leave disabled for ordinary retrieval
`query_with_user_profile`	`bool`	`False`	Uses the agent’s Viking long-term memory profile to guide queries; the knowledge backend itself need not be Viking

Backend configuration

Parameter	Type	Default	Description
`index`	`str`	None	Knowledge-base name for the default resource URI; nonempty, containing only letters, digits, periods, underscores, @, and hyphens, and not . or ..
`openviking_user_id`	`str \| None`	`DATABASE_OPENVIKING_USER_ID` or `default`	OpenViking owner/context used to build the default resource URI. Allowed characters: letters, digits, `.`, `_`, `@`, `-`; cannot be `.` or `..`.
`url`	`str \| None`	Environment	OpenViking service URL.
`api_key`	`str \| None`	Environment	OpenViking API key.
`account`	`str \| None`	Environment	OpenViking account.
`user`	`str \| None`	Environment	OpenViking user.
`actor_peer_id`	`str \| None`	Environment	Identity used for resource operations.
`target_uri`	`str \| None`	`viking://user/<openviking_user_id>/resources/<index>/`	Resource URI used for ingestion and retrieval. When set explicitly, it is used as-is.
`wait`	`bool`	`true`	Whether ingestion waits for processing to finish.
`import_timeout`	`float \| None`	`300`	Resource-ingestion timeout in seconds.
`hydrate_results`	`bool`	`true`	Whether to read full content for matched resources.
`read_limit`	`int`	`200`	Maximum amount of content read from a matched resource.
`score_threshold`	`float \| None`	`None`	Minimum relevance score for search results.
`use_context_search`	`bool`	`false`	Whether to use OpenViking context search.

When openviking_user_id is not configured, VeADK checks DATABASE_OPENVIKING_USER_ID and then OPENVIKING_USER_ID, falling back to default. user_id remains available as a compatibility alias and is equivalent to openviking_user_id.

Environment variables

The parameters map to DATABASE_OPENVIKING_URL, DATABASE_OPENVIKING_API_KEY, DATABASE_OPENVIKING_USER_ID, DATABASE_OPENVIKING_ACCOUNT, DATABASE_OPENVIKING_USER, DATABASE_OPENVIKING_ACTOR_PEER_ID, DATABASE_OPENVIKING_TARGET_URI, DATABASE_OPENVIKING_WAIT, DATABASE_OPENVIKING_IMPORT_TIMEOUT, DATABASE_OPENVIKING_HYDRATE_RESULTS, DATABASE_OPENVIKING_READ_LIMIT, DATABASE_OPENVIKING_SCORE_THRESHOLD, and DATABASE_OPENVIKING_USE_CONTEXT_SEARCH. The URL, API key, user ID, account, user, actor peer ID, and target URI also accept the corresponding OPENVIKING_* variables.

Per-operation overrides

Constructor parameters define the defaults. These keyword arguments can override them for one ingestion or search operation.

Method	Parameters	Default	Description
`add_from_directory`	`target_uri`, `wait`, `timeout`	Instance configuration	Override the destination, wait behavior, and timeout.
`add_from_directory`	`strict`, `directly_upload_media`, `preserve_structure`, `telemetry`	`false`, `true`, `true`, `false`	Control strict mode, media upload, directory preservation, and telemetry.
`add_from_directory`	`ignore_dirs`, `include`, `exclude`, `args`	`None`	Filter directories and files and pass additional ingestion arguments.
`add_from_directory`	`watch_interval`	`0`	Directory polling interval; `0` disables continuous watching.
`add_from_files`	`target_uri`, `wait`, `timeout`	Instance configuration	Override the destination, wait behavior, and timeout.
`add_from_files`	`strict`, `reason`, `instruction`, `directly_upload_media`, `telemetry`	`false`, `""`, `""`, `true`, `false`	Control single-file ingestion behavior.
`search`	`target_uri`, `score_threshold`, `use_context_search`	Instance configuration	Override the search scope, threshold, and search mode.
`search`	`filter`, `context_type`, `tags`	`None`	Pass retrieval filters to OpenViking.
`search`	`session_id`	`None`	Supply the session ID for context search.
`search`	`telemetry`	`false`	Enable OpenViking telemetry for this search.

wait=False confirms submission only, not search readiness. hydrate_results=True adds content reads for matched resources, limited by read_limit; it does not guarantee the complete document is returned. Runner.user_id does not automatically change the resource directory; configure explicit directories and service permissions for separate tenants The example search should return the annual-leave policy. For empty results, check successful ingestion, matching embedding dimensions, completed server processing, network access, and permissions. Managed ingestion may not be immediately searchable. Running the configured Agent also requires model credentials

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Dependencies

Example

Parameters

KnowledgeBase parameters

Backend configuration

Environment variables

Per-operation overrides

​Dependencies

​Example

​Parameters

​KnowledgeBase parameters

​Backend configuration

​Environment variables

​Per-operation overrides

Dependencies

Example

Parameters

KnowledgeBase parameters

Backend configuration

Environment variables

Per-operation overrides