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

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": "your-openviking-api-key",
        # Optional; defaults to default when omitted
        "openviking_user_id": "product_app",
    },
)
kb.add_from_directory("./docs")

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

Parameter	Type	Default	Description
`index`	`str`	None	Knowledge-base name used to build the default resource URI. It cannot be empty.
`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`, `session_id`	`None`	Supply session information for context search.
`search`	`telemetry`	`false`	Enable OpenViking telemetry for this search.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Dependencies

Example

Parameters

Environment variables

Per-operation overrides

​Dependencies

​Example

​Parameters

​Environment variables

​Per-operation overrides

Dependencies

Example

Parameters

Environment variables

Per-operation overrides