This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Semantic Guardrails

Using Semantic Guardrails with PPC

1: Prerequisites
2: Installing Semantic Guardrails
3: Testing the Semantic Guardrails deployment
4: Configuring Semantic Guardrails
5: Uninstalling Semantic Guardrails

Protegrity’s Semantic Guardrails solution is a security guardrail engine for AI systems. It evaluates risks in GenAI systems such as chatbots, workflows, and agents, through advanced semantic analytics and intent classification to detect potentially malicious messages. PII detection can also be leveraged for comprehensive security coverage.

For more information about Semantic Guardrails, refer to the Semantic Guardrails documentation.

1 - Prerequisites

Prerequisites to install Semantic Guardrails

Ensure that the following requirements are met before installing Semantic Guardrails with PPC.

The jumpbox is registered and prepared.
For more information about registering a jumpbox, refer to Configuring Authentication for Protegrity AI Team Edition.
PPC is installed and accessible.
For PII detection, Data Discovery service is installed.
Access to relevant images is available.

2 - Installing Semantic Guardrails

Steps to install Semantic Guardrails

This section describes the steps to install Semantic Guardrails.

1. Installing Data Discovery

For PII detection, it is recommended to install Data Discovery services before installing Semantic Guardrails.

For more information about installing Data Discovery service, refer to Installing Data Discovery.

To verify the Data Discovery service status, run the following command.

kubectl get pods -n data-discovery

2. Preparing and Installing

To install Semantic Guardrails, you must have access to the v1.1.1 helmchart.

To install the helm chart, run the following command.

helm upgrade semantic-guardrails \
oci://<container_registry_path>/semantic-guardrails/1.1/helm/semantic-guardrails \
--install --namespace pty-semantic-guardrails \
--version 1.1.1 \
--create-namespace

Note: In some deployments the above permission is managed by ProductConfiguration in the Helmchart.
If you create the user after installing SGR, you may have to redeploy the SGR helmchart afterwards.

3. Creating an SGR User

SGR users need the semantic_guardrails_user role with can_create_token permissions to access the API. For more information on assigning roles, refer to Policy Management Command Line Interface (CLI) Reference.

To create a user, run the following command.

# Auto-discover gateway host from the cluster
GW_HOST=$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')
ADMIN_USER="admin"
ADMIN_PASS="Admin123!"
 
# Obtain an admin token
TOKEN=$(curl -sk -X POST "https://${GW_HOST}/pty/v1/auth/login/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "loginname=${ADMIN_USER}&password=${ADMIN_PASS}" \
 -D - -o /dev/null | grep -i 'pty_access_jwt_token' | awk '{print $2}' | tr -d '\r\n')
echo $TOKEN
 
 
# Add `can_create_token` as a permission to the `semantic_guardrails_user` role.
# This only needs to be done **once per deployment** (not per user).
curl -sk -X PUT "https://${GW_HOST}/pty/v1/auth/roles" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
   "name": "semantic_guardrails_user",
   "permissions": ["semantic_guardrails_administrator", "can_create_token"]
    }'
 
# Create User
curl -sk -X POST "https://${GW_HOST}/pty/v1/auth/users" \
 -H "Authorization: Bearer ${TOKEN}" \
 -H "Content-Type: application/json" \
 -d '{
 "username": "semantic_guardrails_username",
 "password": "Admin123!",
 "roles": [
  "semantic_guardrails_user"
 ]
 }'

4. Verifying Deployment Status

To verify the deployment status, run the following command.

kubectl get pods -n pty-semantic-guardrails

After Semantic Guardrails feature is successfully deployed, the expected output is as follows.

NAME                                                 READY   STATUS    RESTARTS   AGE
semantic-guardrails-deployment-xxxxxxxxxx-xxxxx     1/1     Running   0          2m

5. Verifying the Service Status

To verify the service status, run the following command.

kubectl get svc -n pty-semantic-guardrails

After Semantic Guardrails feature is successfully deployed, the expected output is as follows.

NAME                              TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
semantic-guardrails-service       ClusterIP   172.20.109.155   <none>        8001/TCP   3h

3 - Testing the Semantic Guardrails deployment

Steps to test the deployment for Semantic Guardrails

Perform the following steps to test the Semantic Guardrails deployment.

1. Testing Semantic Guardrails API

To test the Semantic Guardrails API endpoint, run the following command.

Note: The endpoints require authentication. For more information on creating a user with correct permissions and getting the JWT token, refer to PPC documentation.

GATEWAY_URL=$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')
USERNAME="semantic_guardrails_user"
PASSWORD="Admin123!"
 
YOUR_JWT_TOKEN=$(curl -sk -X POST "${GATEWAY_URL}/api/v1/auth/login/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=${USERNAME}&password=${PASSWORD}" \
  -D - -o /dev/null | grep -i 'pty_access_jwt_token' | awk '{print $2}' | tr -d '\r\n')

The sample response appears as follows.


{
  "from": "user",
  "to": "ai",
  "content": "This is a test message for semantic analysis",
  "outcome": "approved",
  "score": 0.2,
  "explanation": "in-domain"
}

2. Testing Data Discovery Integration

If Data Discovery is installed, then to test the Data Discovery integration, run the following command.

curl -sk -X POST "${GATEWAY_URL}/pty/semantic-guardrails/v1.1/conversations/messages/scan"   -H 'Content-Type: application/json'   -H "Authorization: Bearer $YOUR_JWT_TOKEN"   --data '{
    "messages": [
      {
        "from": "ai",
        "to": "user",
        "content": "My name is John Smith, my credit card number is 4868 7191 9682 9038",
        "processors": ["pii"] 
              }      
    ]
  }'

The sample response appears as follows.

{
  "messages": [
    {
      "id": "1",
      "outcome": "rejected",
      "score": 0.8774,
      "processors": [
        {
          "name": "data-discovery",
          "score": 0.8773500025272369,
          "explanation": "['PERSON : [16, 21]', 'CREDIT_CARD : [48, 67]']"
        }
      ]
    }
  ],
  "batch": {
    "outcome": "rejected",
    "score": 0.8774,
    "rejected_messages": [
      "1"
    ]
  }
}

4 - Configuring Semantic Guardrails

Steps to configure Semantic Guardrails

This service provides AI conversation scanning and semantic analysis capabilities for Semantic Guardrails.

API Endpoints

This section provides an overview of the primary endpoints.

Name	Endpoint
Main API	`/pty/semantic-guardrail/v1.1/conversations/messages/`
Models API	`/pty/semantic-guardrail/v1.1/domain-models/`

Configuration Variables

The semantic-guardrail service can be configured by setting variables in the helm chart values.yaml, or overriding them with -f my.values.yaml.

Service variables

Key	Sub-Key	Description
`semanticGuardrailsAppConfig`	`environment.LOG_LEVEL`	Sets the application log level, default is `INFO`

Other variables

Semantic Guardrails Service Configuration

These Service variables are available to help diagnose and fix any resource allocation problems. It is not recommended to change them.

Key	Sub-Key
`semanticGuardrailsService`	`port`
`semanticGuardrailsService`	`containerName`
`semanticGuardrailsService`	`resources.Required.memory`
`semanticGuardrailsService`	`resources.Required.cpu`
`semanticGuardrailsService`	`resources.Limits.memory`
`semanticGuardrailsService`	`resources.Limits.cpu`
`semanticGuardrailsService`	`replicas`

Application Runtime Configuration

These Data Discovery related variables are available to help diagnose and fix any connection problems. It is not recommended to change them.

Key	Sub-Key
`semanticGuardrailsAppConfig`	`environment.LOG_LEVEL`
`semanticGuardrailsAppConfig`	`environment.DATA_DISCOVERY_SEARCH`
`semanticGuardrailsAppConfig`	`environment.DATA_DISCOVERY_URL`
`semanticGuardrailsAppConfig`	`environment.DATA_DISCOVERY_VERSION`
`semanticGuardrailsAppConfig`	`environment.DATA_DISCOVERY_PORT`

Updating cluster

To update the deployed cluster, run the following command.

helm template semantic-guardrails charts/semantic-guardrails > semantic_guardrails.yaml 2>&1
kubectl delete -f semantic_guardrails.yaml
kubectl apply -f semantic_guardrails.yaml

Update settings

To update the deployed cluster, run the following command.

helm template semantic-guardrails charts/semantic-guardrails > semantic_guardrails.yaml 2>&1
kubectl delete -f semantic_guardrails.yaml
kubectl apply -f semantic_guardrails.yaml

5 - Uninstalling Semantic Guardrails

Steps to uninstall Semantic Guardrails

Perform the following steps to uninstall Semantic Guardrails.

Uninstalling Semantic-Guardrails

To uninstall semantic-guardrails, run the following command.

helm uninstall semantic-guardrails -n pty-semantic-guardrails

Uninstalling Data Discovery

If Data Discovery is not needed, then uninstall the Data Discovery service.

To uninstall data discovery, run the following command.

helm uninstall data-discovery -n data-discovery