OpenLink Personal Assistant VAD Installation, Configuration, and Usage Guide

hwilliams · October 11, 2023, 2:43pm

Overview

Package Download & Installation
Configuration
Application Usage
Personal Assistant Configuration
Sample Prompts
Additional Information

Conceptual Architecture

opal-architecture-overview-4

Package Download & Installation

Perform the following steps in order to have a working OPAL instance at a designated interaction endpoint.

Confirm that you’re running Virtuoso version 08.03.3329 or later. The latest versions are available for download here.
Download the Virtuoso Authentication Layer (VAL) VAD package.
Download the Personal Assistant VAD package.
In the [Flags] section of the virtuoso.ini configuration file, set enable_g_in_sec = 1, and restart the Virtuoso server.
In the [URIQA] section of the virtuoso.ini configuration file, set DefaultHost to the canonical host/domain name the Virtuoso server will be accessed on.

Virtuoso VAD Installation Note

It is usually best to put the VAD packages into the vad/ directory, typically found alongside the bin/ directory that holds your Virtuoso binary, replacing any older versions of these VADs that may already be there.

Once the packages have been downloaded, they can be installed via the Virtuoso iSQL command-line or Conductor interfaces. You MUST install the VAL package before installing the Personal Assistant package.

Assuming you are using the Conductor interface, drill down to the System Admin → Packages tab.

If you put the VAD packages in the vad/ directory, you should see them in the long list, where you can tick the boxes to the left of both VADs, and click the Install/Upgrade button.
If you put the VAD packages elsewhere, you’ll need to install them one-by-one. Scroll down to the Install package → Install from section, and click the Choose File button, to get a file navigator dialog within which you can navigate to your downloaded VAD packages. (Locate the VAL package, first!) Once you’ve selected one of those VAD packages, click the Proceed button:

Whether installing one-by-one or both-at-once, you’ll be presented with a confirmation pane. Review the VAD(s) listed there, and click the Proceed button to install the VAD(s):

If installing one-by-one, repeat for the other (i.e,. the Personal Assistant package).

The installation is now complete:

Additional information about the VAL package is available here. You don’t need to digest all that now. The steps in this guide will walk you through relevant aspects of VAL configuration for use with the Personal Assistant.

Configuration

Virtual Directories

The Virtuoso /chat, /chat/api, /ws/chat, /assist and /ws/assistant virtual directories must be exposed via a secure HTTPS port.

The can be done by either

Using a HTTPS reverse proxy server like nginx or other to forward HTTPS request back to the Virtuoso HTTP virtual directories. Note the proxy must forward request to the HTTP (/) and WebSocket (/ws/) endpoints.
Setting up a Virtuoso HTTPS listener and either:
2.1 create a copy the definitions for the existing /chat, /chat/api, /ws/chat, /assist and /ws/assistant virtual directories from the HTTP listener definitions, which were created during VAD package installation.
2.2 Alternatively, you can use the SQL command templates below, where the {CNAME} placeholder implies the Canonical Name of the machine hosting your Virtuoso instance, to create the required HTTPS Listener virtual directories via the iSQL command-line or Conductor interfaces:

-- Chat Endpoint
DB.DBA.VHOST_REMOVE (
	 lhost=>':443',
	 vhost=>'{CNAME}',
	 lpath=>'/chat'
);
DB.DBA.VHOST_DEFINE (
	 lhost=>':443',
	 vhost=>'{CNAME}',
	 lpath=>'/chat',
	 ppath=>'/DAV/VAD/personal_assistant/',
	 is_dav=>1,
	 is_brws=>0,
	 def_page=>'index.html',
	 ses_vars=>0,
	 sec=>'SSL',
	 auth_opts=>vector ('https_key', '{db-or-filesystem-hosted-tls-key}', 'https_cert', '{db-or-filesystem-hosted-tls-cert}', 'https_extra_chain_certificates', '{db-or-filesystem-hosted-tls-cert-chain.pem}', 'https_verify', '0', 'https_cv_depth', 10),
	 is_default_host=>0
);
-- Chat Websockets Endpoint
DB.DBA.VHOST_REMOVE (
	 lhost=>':443',
	  vhost=>'{CNAME}',
	 lpath=>'/ws/chat'
);
DB.DBA.VHOST_DEFINE (
	 lhost=>':443',
	  vhost=>'{CNAME}',
	 lpath=>'/ws/chat',
	 ppath=>'/SOAP/Http/websockets',
	 is_dav=>0,
	 is_brws=>0,
	 soap_user=>'chat',
	 ses_vars=>0,
	 auth_opts=>vector ('https_key', '{db-or-filesystem-hosted-tls-key}', 'https_cert', '{db-or-filesystem-hosted-tls-cert}', 'https_extra_chain_certificates', '{db-or-filesystem-hosted-tls-cert-chain.pem}', 'https_verify', '0', 'https_cv_depth', 10),
	 opts=>vector ('websocket_service_call', 'OAI.DBA.CHAT', 'websocket_service_connect', 'OAI.DBA.CHAT_WS_CONNECT', 'cors', '*', 'cors_allow_headers', '*', 'cors_restricted', 0),
	 is_default_host=>0
);
-- Chat API Endpoint 	
DB.DBA.VHOST_REMOVE (
	 lhost=>':443',
	  vhost=>'{CNAME}',
	 lpath=>'/chat/api'
);
DB.DBA.VHOST_DEFINE (
	 lhost=>':443',
	 vhost=>'{CNAME}',
	 lpath=>'/chat/api',
	 ppath=>'/SOAP/Http',
	 is_dav=>0,
	 is_brws=>0,
	 realm=>'Chat',
	 auth_fn=>'OAI.DBA.CHAT_WS_AUTH',
	 soap_user=>'chat',
	 ses_vars=>0,
auth_opts=>vector ('https_key', '{db-or-filesystem-hosted-tls-key}', 'https_cert', '{db-or-filesystem-hosted-tls-cert}', 'https_extra_chain_certificates', '{db-or-filesystem-hosted-tls-cert-chain.pem}', 'https_verify', '0', 'https_cv_depth', 10),
	 opts=>vector ('websocket_service_call', 'OAI.DBA.CHAT', 'websocket_service_connect', 'OAI.DBA.CHAT_WS_CONNECT','cors', '*', 'cors_allow_headers', '*', 'cors_restricted', 0),
	 is_default_host=>0
);

-- Assist Endpoint
DB.DBA.VHOST_REMOVE (
	 lhost=>':443',
	 vhost=>'{CNAME}',
	 lpath=>'/assist'
);
DB.DBA.VHOST_DEFINE (
	 lhost=>':443',
	 vhost=>'{CNAME}',
	 lpath=>'/assist',
	 ppath=>'/DAV/VAD/personal_assistant/',
	 is_dav=>1,
	 is_brws=>0,
	 def_page=>'assist.html',
	 sec=>'SSL',
	 ses_vars=>0,
	 auth_opts=>vector ('https_key', '{db-or-filesystem-hosted-tls-key}', 'https_cert', '{db-or-filesystem-hosted-tls-cert}', 'https_extra_chain_certificates', '{db-or-filesystem-hosted-tls-cert-chain.pem}', 'https_verify', '0', 'https_cv_depth', 10),
	 opts=>vector ('browse_sheet', ''),
	 is_default_host=>0
);

-- Assist Websockets Endpoint
DB.DBA.VHOST_REMOVE (
	 lhost=>':443',
	  vhost=>'{CNAME}',
	 lpath=>'/ws/assistant'
);
DB.DBA.VHOST_DEFINE (
	 lhost=>':443',
	  vhost=>'{CNAME}',
	 lpath=>'/ws/assistant',
	 ppath=>'/SOAP/Http/websockets',
	 is_dav=>0,
	 is_brws=>0,
	 soap_user=>'chat',
	 ses_vars=>0,
	 auth_opts=>vector ('https_key', '{db-or-filesystem-hosted-tls-key}', 'https_cert', '{db-or-filesystem-hosted-tls-cert}', 'https_extra_chain_certificates', '{db-or-filesystem-hosted-tls-cert-chain.pem}', 'https_verify', '0', 'https_cv_depth', 10),
	 opts=>vector ('websocket_service_call', 'OAI.DBA.ASSISTANT_RUN', 'websocket_service_connect', 'OAI.DBA.CHAT_WS_CONNECT', 'cors', '*', 'cors_allow_headers', '*', 'cors_restricted', 0),
	 is_default_host=>0
);

HTTP & WebSocket Endpoint Configuration

Using the Conductor’s WebDAV Explorer, locate /DAV/VAD/personal_assistant/config.js.example. Copy or rename it to config.js in the same folder (ensuring read permissions for owner, group, and other on the resulting config.js), and edit to set the relevant WebSocket (wsServer) & Base URI (httpServer) for the installation in question.

var wsServer='wss://{CNAME}:{PORT}/ws/chat';
var httpServer='https://{CNAME}:{PORT}';

Note: The client UI (a lightweight Single Page Application) can be used as a frontend to any other Personal Assistant chat backend; it is not mandatory to use the client UI on the same instance as the backend.

Instance Protection using Attribute-Based Access Controls (ABAC)

API Keys

By default, users will be prompted upon connection to enter their own OpenAI API key to use the client UI. However, if required or preferred, one can register an OpenAI API key for system-wide access, using the command registry_set ('openai-chat-app-key', '[API KEY]') via the iSQL command-line or Conductor interfaces. Note: all usage will then be billed to that OpenAI API key account. You can disable this modality at any time by executing the command registry_remove ('openai-chat-app-key') via the iSQL command-line or Conductor interfaces.

Virtuoso Authentication Layer (VAL) Configuration

ABAC ACLs and Graph Caching

Use of this application requires the Virtuoso Multi-Protocol Authentication Layer (VAL) Graph Caching Mode be enabled, which ensures highly scalable fine-grained attributed-based access control processing.

The Graph Caching Mode can be enabled by via the Conductor UI or via the iSQL command-line.

Conductor UI

From the Conductor System Admin - Packages tab, select the VAL vad package configure link to right which loads the VAL configuration dialog and check the Cache Named Graph ACLs option:

Command Line

By simply executing the following command using the Virtuoso isql command line tool:

__dbf_set('enable_g_in_sec',1)

Virtuoso Configuration File

Edit the Virtuoso configuration file virtuoso.ini adding the enable_g_in_sec = 1 parameter to the [Flags] section ie

[Flags]
enable_g_in_sec = 1
...

Access Controls

In addition to OpenAI API Keys, it is important to protect the Personal Assistant using attribute-based access control lists (ABACLs). This is achieved by creating a generic ACL that requires users to authenticate (using a variety of authentication protocols) prior to application use.

This can be done using either of these two methods:

Using the iSQL command-line tool only (where the macro substitution commands used are supported), run the following script situated in {your-instance-cname/DAV/VAD/personal_assistant/sql/chat_acl_rules.sql} :

SELECT VAL.DBA.val_acl_rule_graph(VAL.DBA.get_default_realm ());
SET U{RULES} $LAST[1];

SPARQL
PREFIX    acl: <http://www.w3.org/ns/auth/acl#>
PREFIX   foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>

WITH <$U{RULES}>
DELETE { <#rulePublicChat> ?p ?o . }
WHERE { <#rulePublicChat> a acl:Authorization ; ?p ?o .  }
INSERT
{
  <#rulePublicChat>
    a                    acl:Authorization ;
    foaf:maker           <#dba> ;
    oplacl:hasAccessMode oplacl:Read , 
                         oplacl:Write ;
    acl:accessTo         <urn:oai:chat> ;
    acl:agent            <#groupBasicNetID> ;
    oplacl:hasRealm      oplacl:DefaultRealm ;
    oplacl:hasScope      oplacl:Query .
}
;

Using the Conductor Interactive SQL interface:

Run the following query to determine the ACL rules graph name ({acl-rules-graph-name}) being used by the Virtuoso instance:
```
SELECT VAL.DBA.val_acl_rule_graph(VAL.DBA.get_default_realm ());
```

Then, in the following ACL rule, replace {acl-rules-graph-name} with the value returned by the previous step, and run the queries below to generate the required ACL rule:

SPARQL
PREFIX    acl: <http://www.w3.org/ns/auth/acl#>
PREFIX   foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>

WITH <{acl-rules-graph-name}>
DELETE
{
  <#rulePublicChat>
    a                    acl:Authorization ;
    foaf:maker           <#dba> ;
    oplacl:hasAccessMode oplacl:Read , 
                         oplacl:Sponge , 
                         oplacl:Write ;
    acl:accessTo         <urn:oai:chat> ;
    acl:agent            <#groupBasicNetID> ;
    oplacl:hasRealm      oplacl:DefaultRealm ;
    oplacl:hasScope      oplacl:Query .
}

INSERT
{
  <#rulePublicChat>
    a                     acl:Authorization ;
    foaf:maker            <#dba> ;
    oplacl:hasAccessMode oplacl:Read , 
                         oplacl:Sponge , 
                         oplacl:Write ;
    acl:accessTo         <urn:oai:chat> ;
    acl:agent            <#groupBasicNetID> ;
    oplacl:hasRealm      oplacl:DefaultRealm ;
    oplacl:hasScope      oplacl:Query .
};

VAL Scopes Configuration

In the Conductor’s VAL configure page:
1.1 Enable the VAL default ACL scopes and save then click on the Setup button of the ACL Configurator to create default ACL rules:

Screenshot 2024-12-03 at 20.31.502060×1054 297 KB

1.2 Enable Solid Client Authentication Library compatibility mode:

Screenshot 2024-06-21 at 16.02.432012×166 15.1 KB
If the HTTPS Listener is setup in Virtuoso Configure the Virtuoso Authentication Layer (VAL) Secure Endpoint to enable Callback URL from HTTPS.

Web Crawler (“Sponger”) Usage Privileges

Incorporating web crawls into query solution production pipelines requires the following steps:

Grant SPARQL_SPONGE privileges to the SQL account (“demo” by default) associated with the Demo.demo.execute_sql_query stored procedure that handles SPASQL (SPARQL inside SQL) functionality. This is achieved by executing the command GRANT SPARQL_SPONGE TO demo.
Run the attached script through the iSQL command-line interface.
assistant_sponging_patch.sql.zip (1.1 KB)

Having successfully performed the steps above, you will be able to execute SPASQL queries such as:

SELECT X.sample, X.entityTypeID, X.sampleCount
FROM
(
  SPARQL
  DEFINE get:soft "soft"
  SELECT (SAMPLE(?entity) AS ?sample) 
         (COUNT(*) AS ?sampleCount) 
         (?entityType As ?entityTypeID) 
    FROM <https://www.apple.com/shop/buy-ipad/ipad-pro>
    WHERE {?entity a ?entityType . FILTER (CONTAINS(STR(?entityType),"schema"))}
    GROUP BY ?entityType
    ORDER BY DESC (?sampleCount)
) AS X

Note: Demo.demo.execute_sql_query is the default stored procedure for handling SQL and SPARQL query processing. As part of its default settings, it runs under the identity user “demo” which can be changed to a different user account if you so desire. It is also important to note that sponging is a sandboxed read-write operation scoped to named graphs denoted by the URL of a sponged document i.e., it doesn’t have system-wide graph access.

Application Usage

The OpenLink Personal Assistant is only accessible on the secure HTTPS port of the hostname https://{CNAME}:{PORT}/chat:

Click on the Login button to log in and access the personal assistant:

Authenticate by choosing one of the authentication service options presented by Virtuoso’s multi-protocol authentication interface:

Click on the Authorize button to authorize the login request:

Enter a valid OpenAI API Key in the designated field, to enable communication with the OpenAI API:

Questions can now be posted in the prompt windows for responses by the Assistant!

Personal Assistant Configuration

An instance may or may not operate under the guidance of a Session Configuration, which is a set of parameters that dictate the behavior of the assistant during a session.

Personal Assistant Mode — No Configuration Selected

In this mode, the Assistant operates as an alternative OpenAI model sandbox, with the added ability to execute SQL, SPARQL, and SPASQL queries. This functionality is enabled through the invocation of Virtuoso Stored Procedures published for the Assistant’s use, using a callback system.

Personal Assistant Mode — Virtuoso or UDA (Universal Data Access, ODBC or JDBC Driver) Support

In this mode, the Assistant is equipped with behavior tuning information derived from a JSON-based configuration file, guiding its incorporation of relevant product knowledge graphs when responding to prompts. This process of loosely-coupling a Large Language Model (LLM)-based Assistant and a Knowledge Graph is generally known as Retrieval Augmented Generation (RAG).

Here are examples of the aforementioned JSON-based configuration files that offer powerful templates for configuring the behavior of the Assistant:

Sample Prompts

Here’s a collection of prompts that can be used to sanity check the state of the Assistant. To use these prompts, enter them in the Assistant’s input field, and verify that the responses match the expected outcomes.

System Check

What's your external function call list?
Show me your external function call list without arguments, and for each, show its expected result output format.
What is the expected results format for execute_sql_query?
Test execute_sql_query.

Basic SPARQL Tests (New Chat Session and SPARQL & SQL Processor Functions Enabled)

Write and execute a sample SPARQL query.
Write and execute a sample SPARQL query related to movies by Spike Lee using the DBpedia SPARQL endpoint.
Write and execute a sample SPARQL query related to music by Bob Marley using the DBpedia SPARQL endpoint.
Write and execute a sample SPARQL query using the DBpedia SPARQL endpoint with Paris as the focus.
Write and execute a sample SPARQL query using the DBpedia SPARQL endpoint with Paris and London as the focus.

General SPARQL/SPASQL

Write and execute a sample SPARQL query.
Write and execute a sample SPARQL query related to movies by Spike Lee using the DBpedia SPARQL endpoint.
Redo, but for music by Bob Marley using the DBpedia SPARQL endpoint.
Write and execute a sample SPARQL query using the DBpedia SPARQL endpoint with Paris as the focus.
Write and execute a sample SPARQL query using the DBpedia SPARQL endpoint with Paris and London as the focus.

Virtuoso Support Agent Session Prompts

FAQs

How does OpenLink Virtuoso support data security?
How does OpenLink Virtuoso handle data integration?
What are the key features of OpenLink Virtuoso?
Where do I place my Virtuoso license file?

HowTos

How Do I Install Virtuoso on macOS?
How Do I Install Virtuoso on Windows?
How Do I Install the Virtuoso Docker Container Image?

ODBC and JDBC Driver Support Agent Session Prompts