> ## 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://resources/<index>/` by default. This backend is available in VeADK 1.0.3 and later.

## 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",
    },
)
kb.add_from_directory("./docs")

agent = Agent(knowledgebase=kb)
```

## Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `index` | `str` | None | Knowledge-base name used to build the default resource URI. It cannot be empty. |
| `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://resources/<index>/` | Resource URI used for ingestion and retrieval. |
| `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. |

## Environment variables

The parameters map to `DATABASE_OPENVIKING_URL`, `DATABASE_OPENVIKING_API_KEY`, `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, 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. |