Deployment Modes

Client

The OpenViking client is the main entry point for all operations.

Deployment Modes

API Reference

OpenViking()

Create an OpenViking client instance.

Signature

def __init__(
    self,
    path: Optional[str] = None,
    vectordb_url: Optional[str] = None,
    agfs_url: Optional[str] = None,
    user: Optional[str] = None,
    config: Optional[OpenVikingConfig] = None,
    **kwargs,
)

Parameters

*Either path (embedded mode) or both vectordb_url and agfs_url (service mode) must be provided.

Example: Embedded Mode

import openviking as ov

# Create client with local storage
client = ov.OpenViking(path="./my_data")
client.initialize()

# Use client...
results = client.find("test query")
print(f"Found {results.total} results")

client.close()

Example: Service Mode

import openviking as ov

# Connect to remote services
client = ov.OpenViking(
    vectordb_url="http://vectordb.example.com:8000",
    agfs_url="http://agfs.example.com:8001",
)
client.initialize()

# Use client...
client.close()

Example: Using Config Object

import openviking as ov
from openviking.utils.config import (
    OpenVikingConfig,
    StorageConfig,
    AGFSConfig,
    VectorDBBackendConfig
)

config = OpenVikingConfig(
    storage=StorageConfig(
        agfs=AGFSConfig(
            backend="local",
            path="./custom_data",
        ),
        vectordb=VectorDBBackendConfig(
            backend="local",
            path="./custom_data",
        )
    )
)

client = ov.OpenViking(config=config)
client.initialize()

# Use client...
client.close()

initialize()

Initialize storage and indexes. Must be called before using other methods.

Signature

def initialize(self) -> None

Parameters

None.

Returns

Example

client = ov.OpenViking(path="./data")
client.initialize()  # Required before any operations

close()

Close the client and release resources.

Signature

def close(self) -> None

Parameters

None.

Returns

Example

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

# ... use client ...

client.close()  # Clean up resources

wait_processed()

Wait for all pending resource processing to complete.

Signature

def wait_processed(self, timeout: float = None) -> Dict[str, Any]

Parameters

Returns

Return Structure

{
    "queue_name": {
        "processed": 10,      # Number of processed items
        "error_count": 0,     # Number of errors
        "errors": []          # Error details
    }
}

Example

import openviking as ov

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

# Add resources
client.add_resource("./docs/")

# Wait for processing to complete
status = client.wait_processed(timeout=60)
print(f"Processed: {status}")

client.close()

reset()

Reset the singleton instance. Primarily used for testing.

Signature

@classmethod
def reset(cls) -> None

Parameters

None.

Returns

Example

# Reset singleton (for testing)
ov.OpenViking.reset()

observers

Get observer objects for monitoring.

Signature

@property
def observers(self) -> Dict[str, Any]

Returns

Return Structure

{
    "queue": QueueObserver,      # Queue processing observer
    "vikingdb": VikingDBObserver # Vector database observer
}

Singleton Behavior

In embedded mode, OpenViking uses singleton pattern:

# These return the same instance
client1 = ov.OpenViking(path="./data")
client2 = ov.OpenViking(path="./data")
assert client1 is client2  # True

In service mode, each call creates a new instance:

# These are different instances
client1 = ov.OpenViking(vectordb_url="...", agfs_url="...")
client2 = ov.OpenViking(vectordb_url="...", agfs_url="...")
assert client1 is not client2  # True

Error Handling

import openviking as ov

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

try:
    client.initialize()
except RuntimeError as e:
    print(f"Initialization failed: {e}")

try:
    content = client.read("viking://invalid/path/")
except FileNotFoundError:
    print("Resource not found")

client.close()

Related Documentation

• Resources - Resource management
• Retrieval - Search operations
• Sessions - Session management
• Configuration - Configuration options