add_resource

Add resources to the OpenViking knowledge base

Overview

Add files, directories, URLs, or GitHub repositories to OpenViking’s knowledge base. Resources are parsed, indexed, and made available for semantic search.

Supported Resource Types

Files

Local files: PDF, Markdown, HTML, code, images, videos, audio

Directories

Recursively process entire directory trees

URLs

Fetch and process content from web URLs

Method Signature

Python SDK

client.add_resource(
    path: str,
    target: Optional[str] = None,
    reason: str = "",
    instruction: str = "",
    wait: bool = False,
    timeout: Optional[float] = None,
    build_index: bool = True,
    summarize: bool = False,
    **kwargs
) -> Dict[str, Any]

Parameters

path · string · required

Local file path, directory path, or URL to add

target · string

Target Viking URI (must be in viking://resources/ scope). If not provided, automatically determined from path.

reason · string · default: ""

Why this resource is being added. Improves search relevance and retrieval quality.

instruction · string · default: ""

Special processing instructions for the parser

wait · boolean · default: "false"

Wait for semantic processing (L0/L1 generation) and vectorization to complete before returning

timeout · float

Timeout in seconds when wait=True

build_index · boolean · default: "true"

Whether to build vector index immediately

summarize · boolean · default: "false"

Whether to generate L0/L1 summaries

strict · boolean · default: "true"

Strict parsing mode (fail on errors vs. continue with warnings)

ignore_dirs · string

Comma-separated list of directory names to ignore (e.g., “node_modules,.git”)

include · string

Glob pattern for files to include (e.g., “.md,.txt”)

exclude · string

Glob pattern for files to exclude (e.g., “.log,.tmp”)

Response

status · string · required

Either “success” or “error”

root_uri · string · required

Viking URI where the resource was added (e.g., viking://resources/docs/guide.md)

source_path · string · required

Original source path provided

errors · array

List of errors encountered during processing (if any)

queue_status · object

Queue processing status (only present when wait=True)

Show queue_status properties

processed · integer

Number of items processed

error_count · integer

Number of errors encountered

errors · array

List of error messages

Examples

Add Local File

Python SDK

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

result = client.add_resource(
    "./documents/guide.md",
    reason="User guide documentation"
)
print(f"Added: {result['root_uri']}")

client.wait_processed()

Response

{
  "status": "ok",
  "result": {
    "status": "success",
    "root_uri": "viking://resources/documents/guide.md",
    "source_path": "./documents/guide.md",
    "errors": []
  },
  "time": 0.1
}

Add from URL

Python SDK

result = client.add_resource(
    "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
    target="viking://resources/external/",
    reason="External API documentation"
)
client.wait_processed()

Add Directory with Filters

Python SDK

result = client.add_resource(
    "./my-project",
    reason="Project source code",
    ignore_dirs="node_modules,.git,dist",
    include="*.py,*.md,*.json",
    exclude="*.pyc,*.log"
)

Wait for Processing

Python SDK

# Option 1: Wait inline
result = client.add_resource(
    "./documents/guide.md",
    wait=True,
    timeout=60.0
)
print(f"Queue status: {result['queue_status']}")

# Option 2: Add multiple resources, then wait
client.add_resource("./file1.md")
client.add_resource("./file2.md")
client.add_resource("./file3.md")

status = client.wait_processed()
print(f"All processed: {status}")

Processing Pipeline

When you add a resource, OpenViking processes it through multiple stages:

Input -> Parser -> TreeBuilder -> AGFS -> SemanticQueue -> Vector Index

1. Parser: Extracts content based on file type
2. TreeBuilder: Creates directory structure
3. AGFS: Stores files in the Agentic File System
4. SemanticQueue: Generates L0 (abstract) and L1 (overview) asynchronously
5. Vector Index: Indexes content for semantic search

Use wait=True or call wait_processed() to ensure semantic processing completes before querying.

Supported File Formats

Format	Extensions	Processing
PDF	.pdf	Text and image extraction
Markdown	.md	Native support
HTML	.html, .htm	Cleaned text extraction
Plain Text	.txt	Direct import
JSON/YAML	.json, .yaml, .yml	Structured parsing
Code	.py, .js, .ts, .go, .java, etc.	Syntax-aware parsing
Images	.png, .jpg, .jpeg, .gif, .webp	VLM description
Video	.mp4, .mov, .avi	Frame extraction + VLM
Audio	.mp3, .wav, .m4a	Transcription
Documents	.docx	Text extraction

Related Methods

• wait_processed - Wait for async processing to complete
• add_skill - Add skills instead of resources
• ls - List added resources
• find - Search resources