OpenViking/sdk/python/README.md

openviking-sdk

Lightweight Python HTTP SDK for OpenViking.

openviking-sdk is the small package for users who only need to call an existing OpenViking server over HTTP. It avoids the heavier local-runtime, server, and CLI dependencies from the main openviking package.

Installation

pip install openviking-sdk

Requirements:

• Python 3.10+
• A reachable OpenViking HTTP server, for example http://127.0.0.1:1933

Package Name vs Import Name

• PyPI package name: openviking-sdk
• Python import name: openviking_sdk

from openviking_sdk import AsyncHTTPClient, SyncHTTPClient

Configuration Sources

You can configure the SDK in three ways, with this precedence:

1. Explicit constructor arguments
2. Environment variables such as OPENVIKING_URL, OPENVIKING_API_KEY, OPENVIKING_ACCOUNT, OPENVIKING_USER, OPENVIKING_ACTOR_PEER_ID, and OPENVIKING_TIMEOUT
3. ovcli.conf, either from OPENVIKING_CLI_CONFIG_FILE or the default path ~/.openviking/ovcli.conf

This means existing setups that relied on ovcli.conf continue to work after the SDK split.

Authentication Model

Most deployments use API key authentication.

Common client fields:

• url: OpenViking server base URL
• api_key: root key or user key
• account: optional account override, usually only needed with a root key
• user: optional user override, usually only needed with a root key
• user_id: legacy alias for user
• actor_peer_id: optional actor peer override
• agent_id: legacy alias for actor_peer_id
• event_hooks: optional httpx.AsyncClient event hooks, such as async request or response hooks

Compatibility notes:

• user_id and agent_id are still accepted for legacy callers
• actor_peer_id and agent_id cannot be passed together

Example:

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(
    url="http://127.0.0.1:1933",
    api_key="your-user-or-root-key",
)

If you are using a root key and want to act as a specific tenant user:

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(
    url="http://127.0.0.1:1933",
    api_key="your-root-key",
    account="demo-account",
    user="demo-user",
)

Quick Start: Sync Client

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(
    url="http://127.0.0.1:1933",
    api_key="your-user-key",
)
client.initialize()

healthy = client.health()
print("health:", healthy)

session = client.create_session("demo-session")
print("session:", session)

client.session("demo-session").add_message("user", "hello from sdk")
context = client.session("demo-session").get_session_context(token_budget=4096)
print("context:", context)

Quick Start: Async Client

import asyncio

from openviking_sdk import AsyncHTTPClient


async def main() -> None:
    client = AsyncHTTPClient(
        url="http://127.0.0.1:1933",
        api_key="your-user-key",
    )
    await client.initialize()

    healthy = await client.health()
    print("health:", healthy)

    session = await client.create_session("demo-session-async")
    print("session:", session)

    session_client = client.session("demo-session-async")
    await session_client.add_message("user", "hello from async sdk")
    context = await session_client.get_session_context(token_budget=4096)
    print("context:", context)

    await client.close()


asyncio.run(main())

Common Operations

Create a Session

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-user-key")
client.initialize()
result = client.create_session("demo-session")
print(result)

Add a Resource from a Local File

add_resource handles file upload for local paths automatically.

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-user-key")
client.initialize()

result = client.add_resource(
    "/path/to/notes.md",
    to="viking://resources/demo-notes",
    reason="knowledge import",
    wait=True,
)
print(result)

Filesystem Operations

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-user-key")
client.initialize()

client.mkdir("viking://resources/demo-dir")
print(client.ls("viking://resources"))
print(client.read("viking://resources/demo-dir/example.md"))

Retrieval

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-user-key")
client.initialize()

result = client.find("hello", limit=5)
print(result)

Image search uses the same methods. Pass a local path, bytes, data URI, HTTP URL, or viking:// URI with image. The server must use a multimodal embedding model.

result = client.find(image="/path/to/photo.png", limit=5)
result = client.search("similar poster", image="viking://resources/poster.png")

Admin Operations

If you connect with a root key, the SDK also exposes admin APIs such as:

• admin_create_account
• admin_register_user
• admin_list_accounts
• admin_list_users
• admin_regenerate_key
• admin_delete_account

Example:

from openviking_sdk import SyncHTTPClient

root_client = SyncHTTPClient(
    url="http://127.0.0.1:1933",
    api_key="your-root-key",
)
root_client.initialize()

result = root_client.admin_create_account(
    account_id="demo-account",
    admin_user_id="demo-admin",
    seed="demo-admin-seed",
)
print(result)

root_client.admin_register_user(
    account_id="demo-account",
    user_id="alice",
    role="user",
    seed="alice-seed",
    user_config={
        "add_targets": {
            "resource_uri": "viking://user/resources/project-a",
            "skill_uri": "viking://user/skills",
        }
    },
)

root_client.admin_regenerate_key(
    account_id="demo-account",
    user_id="alice",
    seed="alice-new-seed",
)

admin_create_account also accepts user_config with the same shape. These fields initialize server-side user config; ordinary add calls still just omit to / parent / target_uri and let the server resolve defaults. When seed is set, the returned API key is derived from sha256(user_id + "\0" + seed); omit it for random key generation.

Error Handling

The SDK maps server-side error codes to Python exceptions.

from openviking_sdk import OpenVikingError, SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-user-key")
client.initialize()

try:
    print(client.read("viking://resources/not-exists.md"))
except OpenVikingError as exc:
    print(type(exc).__name__, exc)

Relationship to openviking

Use openviking-sdk when you want:

• the HTTP client only
• the smallest dependency footprint
• a package suitable for application-side integration

Use openviking when you want:

• the full Python package
• local runtime integrations
• server entrypoints
• compatibility imports that re-export the HTTP clients

Development

Install from source:

cd sdk/python
pip install -e .

Build distributions:

cd sdk/python
python -m build

The SDK version is derived from git tags with this format:

python-sdk@0.1.3

That tag namespace is independent from the main package release tags such as:

v0.3.26

Release

The repository is configured so SDK releases can be driven by SDK-only tags.

Typical flow:

1. Merge SDK changes.
2. Create and push a tag like python-sdk@0.1.3.
3. GitHub Actions builds sdk/python.
4. GitHub Actions publishes openviking-sdk to PyPI.