Supported Formats

Resources

Resources are external knowledge that agents can reference. This guide covers how to add, manage, and retrieve resources.

Supported Formats

Processing Pipeline

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 virtual file system
4. SemanticQueue: Generates L0/L1 asynchronously
5. Vector Index: Indexes for semantic search

API Reference

add_resource()

Add a resource to the knowledge base.

Signature

def add_resource(
    self,
    path: str,
    target: Optional[str] = None,
    reason: str = "",
    instruction: str = "",
    wait: bool = False,
    timeout: float = None,
) -> Dict[str, Any]

Parameters

Returns

Return Structure

{
    "status": "success",           # "success" or "error"
    "root_uri": "viking://resources/docs/",  # Root resource URI
    "source_path": "./docs/",      # Original source path
    "errors": [],                  # List of errors (if any)
    "queue_status": {...}          # Queue status (only when wait=True)
}

Example: Add Single File

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()
client.close()

Example: Add from URL

import openviking as ov

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

result = client.add_resource(
    "https://example.com/api-docs.md",
    target="viking://resources/external/",
    reason="External API documentation"
)

# Wait for processing
client.wait_processed()
client.close()

Example: Wait for Processing

import openviking as ov

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

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

# Option 2: Wait separately (for batch processing)
client.add_resource("./file1.md")
client.add_resource("./file2.md")
client.add_resource("./file3.md")

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

client.close()

export_ovpack()

Export a resource tree as a .ovpack file.

Signature

def export_ovpack(self, uri: str, to: str) -> str

Parameters

Returns

Example

import openviking as ov

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

# Export a project
path = client.export_ovpack(
    "viking://resources/my-project/",
    "./exports/my-project.ovpack"
)
print(f"Exported to: {path}")

client.close()

import_ovpack()

Import a .ovpack file.

Signature

def import_ovpack(
    self,
    file_path: str,
    parent: str,
    force: bool = False,
    vectorize: bool = True
) -> str

Parameters

Returns

Example

import openviking as ov

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

# Import a package
uri = client.import_ovpack(
    "./exports/my-project.ovpack",
    "viking://resources/imported/",
    force=True,
    vectorize=True
)
print(f"Imported to: {uri}")

client.wait_processed()
client.close()

Managing Resources

List Resources

# List all resources
entries = client.ls("viking://resources/")

# List with details
for entry in entries:
    type_str = "dir" if entry['isDir'] else "file"
    print(f"{entry['name']} - {type_str}")

# Simple path list
paths = client.ls("viking://resources/", simple=True)
# Returns: ["project-a/", "project-b/", "shared/"]

# Recursive listing
all_entries = client.ls("viking://resources/", recursive=True)

Read Resource Content

# L0: Abstract
abstract = client.abstract("viking://resources/docs/")

# L1: Overview
overview = client.overview("viking://resources/docs/")

# L2: Full content
content = client.read("viking://resources/docs/api.md")

Move Resources

client.mv(
    "viking://resources/old-project/",
    "viking://resources/new-project/"
)

Delete Resources

# Delete single file
client.rm("viking://resources/docs/old.md")

# Delete directory recursively
client.rm("viking://resources/old-project/", recursive=True)

Create Links

# Link related resources
client.link(
    "viking://resources/docs/auth/",
    "viking://resources/docs/security/",
    reason="Security best practices for authentication"
)

# Multiple links
client.link(
    "viking://resources/docs/api/",
    [
        "viking://resources/docs/auth/",
        "viking://resources/docs/errors/"
    ],
    reason="Related documentation"
)

Get Relations

relations = client.relations("viking://resources/docs/auth/")
for rel in relations:
    print(f"{rel['uri']}: {rel['reason']}")

Remove Links

client.unlink(
    "viking://resources/docs/auth/",
    "viking://resources/docs/security/"
)

Best Practices

Organize by Project

viking://resources/
├── project-a/
│   ├── docs/
│   ├── specs/
│   └── references/
├── project-b/
│   └── ...
└── shared/
    └── common-docs/

Related Documentation

• Retrieval - Search resources
• File System - File operations
• Context Types - Resource concept