> ## 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}
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`:

```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

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