OpenViking Client Wrapper

A wrapper project around the openviking SDK that exposes operations as a standardized REST API using FastAPI.

Requirements

1. Python 3.12+
2. Conda environment managing dependencies (e.g., openvk).
3. An active OpenViking backend environment.

Setup

First, initialize your .env file at the root of the project. It maps the credentials used to initialize the openviking client.

OPENVK_BACKEND=http://localhost:8080
OPENVK_API_KEY=your-api-key-here

Ensure your dependencies are installed within your active Conda environment:

conda activate openvk
pip install -r requirements.txt
pip install fastapi uvicorn pytest pytest-mock pytest-env

Running the API Server

You can run the FastAPI application via uvicorn:

conda run -n openvk uvicorn main:app --reload

Substitute conda run -n openvk with just uvicorn main:app --reload if you have your environment activated.

The API serves interactive documentation at http://127.0.0.1:8000/docs.

Endpoints

The application exposes the mapped /resources/ and /retrieval/ scopes:

• Resources: /add, /list, /relations, /move, /delete, /link, /unlink
• Retrieval: /find, /search, /read_progressively, /read

All API paths map down directly into the configured openviking singleton client instance internally. Requests handle JSON Payloads defining configurations like src, dest, target_uri, query, returning uniformly structured payload data.

Docker

You can also run the application isolated within a Docker container.

Building the Image

docker build -t openvk-client .

Running the Container

docker run -d --name openvk-api -p 8000:8000 \
  -e OPENVK_BACKEND=http://host.docker.internal:8080 \
  -e OPENVK_API_KEY=your-api-key-here \
  openvk-client

Running Tests

Unit tests are included via pytest mimicking client responses without requiring an active remote instance:

conda run -n openvk pytest tests/test_resources.py tests/test_retrieval.py -v