Getting Started with Interactions

Interactions performs a detailed security analysis of the input and output of LLM interactions. The detections returned depend on the rules configured for the relevant Project — for example, prompt injection, personally identifiable information (PII), code, denial of service, guardrails, model refusals, and prompt language. The rest of this page shows how to call it via the Python SDK.

The HiddenLayer SaaS endpoint lets you exercise the API and detections without needing to deploy a container or wire up a backend LLM. The same script also works against a locally-running Runtime Security container — just point base_url at your container.

This content demonstrates using the HiddenLayer SDK and Python. There are other options.

For other programming languages, like Typescript, see the HiddenLayer GitHub page.
For the HiddenLayer API, see the Developer Portal (requires a login).

Pre-Requisites

To follow this tutorial, you need:

HiddenLayer AI Runtime Security license
HiddenLayer ClientId and ClientSecret to generate an access token
Python 3.9+

SDK Python

The following script shows you how to make a simple call to the HiddenLayer endpoint for Interactions. Copy the script, save it to your working drive, and replace any necessary variables with your values.

Install the HiddenLayer SDK Python using PyPI. If you cannot use PyPI, you can download the SDK from the HiddenLayer SDK Python GitHub page.
pip install hiddenlayer-sdk

Create a Python file.

from hiddenlayer import HiddenLayer

client = HiddenLayer(
    # By default, the client connects to US Production; to use EU Production:
    # environment="prod-eu",
    # It is recommended to source the authentication credentials from the environment:
    #  - HIDDENLAYER_CLIENT_ID=<client_id>
    #  - HIDDENLAYER_CLIENT_SECRET=<client_secret>
    # They can also be specified directly via:
    # client_id="...",
    # client_secret="...",
    # Alternatively, a bearer token can be sourced from the environment:
    #  - HIDDENLAYER_TOKEN=<token>
    # Or specified here directly:
    # bearer_token="...",
    # The API URL will default appropriately based on the environment.
    # To use a locally-hosted Runtime Security, set the base URL here:
    # base_url="...",
)

response = client.interactions.analyze(
  metadata={
    "model": "gpt-5",
    "requester_id": "user-1234",
    "provider": "openai"
  },
  input={
    "messages": [
      {
        "role": "user",
        "content": "What the largest moon of jupiter?"
      }
    ]
  },
  output={
    "messages": [
      {
        "role": "assistant",
        "content": "The largest moon of Jupiter is Ganymede."
      }
    ]
  }
)
print(response)

Notes

Some notes on using this script:

Authentication and calling the endpoint are region-specific operations. Set environment="prod-eu" if you are in the EU, or leave it as the default (prod-us) if you are in the US.
If there are multiple Python versions on your system, make sure you are using the version the HiddenLayer SDK is installed to.
This script can also be run against a locally-running containerized instance of Runtime Security — set base_url to your container’s URL, e.g. http://localhost:8000.

Response

The following is an example Interactions response.

{
  "metadata": {
    "event_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "analyzed_at": "2023-10-10T14:48:00.000Z",
    "provider": "openai",
    "model": "gpt-5",
    "requester_id": "user-1234",
    "project": {
      "project_id": "ca87b009-90bd-4724-91c2-f23326acd51a",
      "project_alias": "enterprise-search",
      "ruleset_id": "b5d7d261-b7be-451a-b943-0d408ab88aab"
    },
    "processing_time_ms": 15.34
  },
  "analysis": [
    {
      "name": "block_list",
      "phase": "input",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true
      },
      "findings": {
        "frameworks": {},
        "matches": []
      },
      "processing_time_ms": 0.005,
      "id": "block_list.1.input"
    },
    {
      "name": "prompt_injection",
      "phase": "input",
      "version": "5",
      "detected": false,
      "configuration": {
        "enabled": true,
        "scan_type": "full",
        "allow_overrides": {},
        "block_overrides": {}
      },
      "findings": {
        "frameworks": {},
        "probabilities": [
          0.0
        ]
      },
      "processing_time_ms": 53.529,
      "id": "prompt_injection.5.input"
    },
    {
      "name": "personally_identifiable_information",
      "phase": "input",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true,
        "entities": [
          "ORGANIZATION",
          "CREDIT_CARD",
          "PHONE_NUMBER",
          "IP_ADDRESS",
          "NATIONAL_ID",
          "IBAN_CODE",
          "US_BANK_NUMBER",
          "UK_NATIONAL_INSURANCE_NUMBER",
          "UK_PASSPORT",
          "DOMAIN_NAME",
          "US_PASSPORT",
          "US_SSN",
          "US_ITIN",
          "US_ABA_ROUTING_TRANSIT_NUMBER",
          "US_HEALTHCARE_NPI"
        ],
        "redact": false,
        "redact_type": "entity",
        "custom_recognizers": {},
        "allow_list": {}
      },
      "findings": {
        "frameworks": {},
        "entities": [],
        "locations": {}
      },
      "processing_time_ms": 6.279,
      "id": "personally_identifiable_information.1.input"
    },
    {
      "name": "code",
      "phase": "input",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true
      },
      "findings": {
        "frameworks": {}
      },
      "processing_time_ms": 0.243,
      "id": "code.1.input"
    },
    {
      "name": "url",
      "phase": "input",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true
      },
      "findings": {
        "frameworks": {},
        "urls": []
      },
      "processing_time_ms": 0.004,
      "id": "url.1.input"
    },
    {
      "name": "denial_of_service",
      "phase": "input",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true,
        "token_threshold": 4096
      },
      "findings": {
        "frameworks": {},
        "embeddings_length": 4
      },
      "processing_time_ms": 0.109,
      "id": "denial_of_service.1.input"
    },
    {
      "name": "language",
      "phase": "input",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": false,
        "allowed_languages": [
          "EN",
          "FR",
          "ES",
          "IT",
          "DE",
          "JA",
          "KO"
        ]
      },
      "findings": {
        "frameworks": {}
      },
      "processing_time_ms": 0.001,
      "id": "language.1.input"
    },
    {
      "name": "personally_identifiable_information",
      "phase": "output",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true,
        "entities": [
          "ORGANIZATION",
          "CREDIT_CARD",
          "PHONE_NUMBER",
          "IP_ADDRESS",
          "NATIONAL_ID",
          "IBAN_CODE",
          "US_BANK_NUMBER",
          "UK_NATIONAL_INSURANCE_NUMBER",
          "UK_PASSPORT",
          "DOMAIN_NAME",
          "US_PASSPORT",
          "US_SSN",
          "US_ITIN",
          "US_ABA_ROUTING_TRANSIT_NUMBER",
          "US_HEALTHCARE_NPI"
        ],
        "redact": false,
        "redact_type": "entity",
        "custom_recognizers": {},
        "allow_list": {}
      },
      "findings": {
        "frameworks": {},
        "entities": [],
        "locations": {}
      },
      "processing_time_ms": 0.399,
      "id": "personally_identifiable_information.1.output"
    },
    {
      "name": "guardrails",
      "phase": "output",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true
      },
      "findings": {
        "frameworks": {},
        "probabilities": []
      },
      "processing_time_ms": 0.001,
      "id": "guardrails.1.output"
    },
    {
      "name": "code",
      "phase": "output",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true
      },
      "findings": {
        "frameworks": {}
      },
      "processing_time_ms": 0.016,
      "id": "code.1.output"
    },
    {
      "name": "url",
      "phase": "output",
      "version": "1",
      "detected": false,
      "configuration": {
        "enabled": true
      },
      "findings": {
        "frameworks": {},
        "urls": []
      },
      "processing_time_ms": 0.002,
      "id": "url.1.output"
    }
  ],
  "evaluation": {
    "action": "Allow",
    "has_detections": false,
    "threat_level": "None"
  },
  "analyzed_data": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What the largest moon of jupiter?"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "The largest moon of Jupiter is Ganymede."
        }
      ]
    }
  },
  "modified_data": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "What the largest moon of jupiter?"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "The largest moon of Jupiter is Ganymede."
        }
      ]
    }
  }
}

​Pre-Requisites

​SDK Python

​Notes

​Response

Pre-Requisites

SDK Python

Notes

Response