> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  `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.
</Note>

## Dependencies

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

```bash lines theme={null}
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:

```bash lines theme={null}
export DATABASE_OPENVIKING_URL="https://openviking.example.com"
export DATABASE_OPENVIKING_API_KEY="your-openviking-api-key"
```

<Warning>
  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.
</Warning>

## Example

```python lines theme={null}
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`:

```python lines theme={null}
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:

```python lines theme={null}
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