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).
To follow this tutorial, you need:
- HiddenLayer AI Runtime Security license
- HiddenLayer ClientId and ClientSecret to generate an access token
- Python 3.9+
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-sdkCreate 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)
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_urlto your container's URL, e.g.http://localhost:8000.
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."
}
]
}
}
}