# HiddenLayer's SDK documentation

The HiddenLayer platform enhances the developer experience for protecting artificial intelligence (AI) and machine learning (ML) models without needing to write complex code or manage the underlying infrastructure.

The HiddenLayer SDK uses Python to provide a simple and efficient way to interact with the HiddenLayer API. This guide will walk you through how to install and use the HiddenLayer Python SDK to retrieve AI Runtime Security and AI Supply Chain Security information.

This SDK can be used to interact with the following HiddenLayer services:

- AI Supply Chain Security (model scanning)
- AI Runtime Security — Interactions (LLM input/output analysis)
- AI Runtime Security for Predictive Models
- AI Attack Simulation (red team evaluations)


Active Development
This project is under active development. The full API surface is documented in the SDK's api.md.

## Before You Begin

The following are required for using the HiddenLayer Python SDK:

- Python 3.9+ (this should include pip)
- HiddenLayer API key and secret; see [Create API Key](/docs/products/console/apikey_aisec_platform#create-api-key)


## Install SDK

Install the `hiddenlayer-sdk` package with pip.

```
pip install hiddenlayer-sdk
```

The HiddenLayer Python SDK offers functionality to interact with other services, such as HuggingFace, AWS, etc.

- To scan models from HuggingFace, install the necessary HuggingFace dependencies via:

```
pip install hiddenlayer-sdk[hf]
```
- To scan models from AWS, install the necessary AWS dependencies via:

```
pip install hiddenlayer-sdk[aws]
```


## Usage Overview

The main client exposed by the SDK is `hiddenlayer.HiddenLayer`, which provides access to all HiddenLayer services exposed via API. An async equivalent (`AsyncHiddenLayer`) is also available with the same interface.

```python
from hiddenlayer import HiddenLayer

client = HiddenLayer(
    # Defaults to "prod-us"; use "prod-eu" for the EU region.
    # environment="prod-eu",
    # Credentials are sourced from the environment by default:
    #   HIDDENLAYER_CLIENT_ID, HIDDENLAYER_CLIENT_SECRET (OAuth2)
    #   HIDDENLAYER_TOKEN (bearer token)
)
```

API methods are grouped by resource on the client, for example:

```
client.<resource>.<method>(<parameters>)
```

For the full list of resources and methods, see the SDK's api.md and the Developer Portal.

## Authentication

To authenticate to HiddenLayer, generate a client ID and secret from the platform UI. See [Create API Key](/docs/products/console/apikey_aisec_platform#create-api-key).

The SDK supports two authentication methods:

- **OAuth2 client credentials** — set `HIDDENLAYER_CLIENT_ID` and `HIDDENLAYER_CLIENT_SECRET`, or pass `client_id` / `client_secret` directly.
- **Bearer token** — set `HIDDENLAYER_TOKEN`, or pass `bearer_token` directly.


```python
from hiddenlayer import HiddenLayer

client = HiddenLayer(
    client_id="...",      # Your HiddenLayer API Client ID
    client_secret="...",  # Your HiddenLayer API Secret Key
)
```

## Data Models

The HiddenLayer Python SDK uses Pydantic to represent data for APIs, which makes the code more readable and type-safe and easier to work with.

Specific data models are organized under `hiddenlayer.types`. Each resource exposes its own request and response types — see the SDK's api.md for the full inventory.

## Example Usage

The HiddenLayer Python SDK comes with a number of examples demonstrating how to use the library for various common use-cases.

These examples and more are located in the `examples` directory of the GitHub repository.

### Initiate Client

```python
from hiddenlayer import HiddenLayer

client = HiddenLayer(
    # environment="prod-eu",  # default is "prod-us"
    client_id="...",
    client_secret="...",
)
```

### Scanning Models

#### Scanning a model on disk

```python
scan_results = client.model_scanner.scan_file(
    model_name="sdk_example_model",
    model_path="./models/example_model.xgb",
)

print(scan_results)
```

#### Scanning a Hugging Face model

```python
from hiddenlayer.lib import CommunityScanSource

huggingface_scan_results = client.community_scanner.community_scan(
    model_name="bert-tiny-torch-vuln",
    model_path="drhyrum/bert-tiny-torch-vuln",
    model_source=CommunityScanSource.HUGGING_FACE,
)

print(huggingface_scan_results)
```

### Runtime Security

#### Analyzing LLM Interactions

Use `client.interactions.analyze` to send LLM input and output to the Interactions endpoint. For a full walkthrough and an example response, see [Getting Started with Interactions](/docs/products/runtime/interactions).

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

To target a locally-running Runtime Security container instead of the SaaS endpoint, set `base_url="http://localhost:8000"` (or your container's URL) when constructing the client.

#### Submitting vectors to Runtime Security (Predictive Models)

For Predictive Model runtime use cases, see the `examples/mldr.py` script in the SDK repository.