> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiddenlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HiddenLayer Python SDK

> Use the official HiddenLayer Python SDK to scan models, analyze LLM interactions, and run AI Attack Simulation from Python code.

The HiddenLayer Python SDK is the official Python library for the HiddenLayer REST API. It lets you call HiddenLayer services from scripts, CI/CD pipelines, and applications without writing raw HTTP requests or handling authentication tokens yourself.

* If you are familiar with SDKs and want to get started right away, see the [Quickstart Guide](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/quickstart.md).
* For a more thorough walk-through (including Installation and Common Workflows), read the rest of this Overview page, then continue with the [Prerequisities](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/prerequisites.md) and read the rest of the Python SDK guide. You can skip the Quickstart section.

The SDK provides:

* **A synchronous client and an asynchronous client.** Use `HiddenLayer` in regular Python code. Use `AsyncHiddenLayer` with `asyncio`. Both clients accept the same configuration options and expose the same methods.
* **Typed requests and responses.** Request parameters are defined as `TypedDict` types (typed Python dictionaries), so editors can autocomplete and check them. Responses are Pydantic models (Python objects with validated, typed fields), so you access results as attributes such as `response.evaluation.action`.
* **Built-in authentication, retries, and timeouts.** The client exchanges your client ID and client secret for an access token, refreshes it when it expires, and retries failed requests that are safe to retry.
* **Helpers for common workflows.** Higher-level helpers handle multi-step tasks, such as uploading and scanning a model folder or driving a red team session.

| Package | Value |
| - | - |
| PyPI package name | `hiddenlayer-sdk` |
| Import name | `hiddenlayer` |
| Minimum Python version | 3.9 (3.11 or later recommended) |
| License | Apache-2.0 |

## Services covered

You can use the SDK with the following HiddenLayer services:

| Service | What you can do | SDK entry points |
| - | - | - |
| [AI Supply Chain Security](https://docs.hiddenlayer.ai/docs/products/supply-chain/overview.md) | Scan model files and folders, including models stored in Hugging Face, AWS S3, or Azure Blob Storage, and retrieve scan results. | `client.model_scanner`, `client.community_scanner`, `client.scans`, `client.models` |
| [AI Runtime Security: Interactions](https://docs.hiddenlayer.ai/docs/products/runtime/interactions.md) | Analyze LLM prompts and responses for threats such as prompt injection or data leakage. | `client.interactions.analyze` |
| [AI Runtime Security: Agentic Evaluation Endpoints](https://docs.hiddenlayer.ai/docs/products/runtime/agentic/evaluation_endpoints.md) | Evaluate requests, responses, and full agent interactions, including tool calls. | `client.runtime` |
| [AI Attack Simulation](https://docs.hiddenlayer.ai/docs/products/ai-attack-simulation/overview.md) | Run automated red teaming (simulated attacks against your AI application) and retrieve the results. | `client.evaluation_sessions.red_team`, `client.evaluations.red_team` |

> [!NOTE]
>
> **Active development**
>
> This project is under active development. Some endpoints are marked **Beta**. Beta APIs have no compatibility guarantees and may change at any time, and they are not considered when the SDK determines its semantic version. When you call a beta endpoint, the SDK emits a `hiddenlayer.BetaWarning`. For details, see the [Beta API FAQ](https://dev.hiddenlayer.ai/docs/beta-api-faq) on the Developer Portal.

## A first look

Every API call follows the same pattern: create a client, then call a method on a resource attribute.

```python theme={null}
from hiddenlayer import HiddenLayer

# Reads HIDDENLAYER_CLIENT_ID and HIDDENLAYER_CLIENT_SECRET from the environment.
client = HiddenLayer()

response = client.interactions.analyze(
    metadata={"model": "gpt-4o", "requester_id": "user-1234"},
    input={"messages": [{"role": "user", "content": "What is the largest moon of Jupiter?"}]},
)

for analysis in response.analysis:
    print(analysis.name, analysis.detected)
```

To run this code, follow the [Quickstart](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/quickstart.md). It walks you through installation, credentials, and error handling.

## How this guide is organized

### Get started

> [card] [Quickstart](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/quickstart.md)
>
> Make your first API call in a few minutes.

> [card] [Prerequisites](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/prerequisites.md)
>
> What you need before you install the SDK.

> [card] [Installation](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/installation.md)
>
> Create a virtual environment and install the package.

> [card] [Authentication and configuration](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/authentication.md)
>
> Provide credentials, choose a region, and configure the client.

> [card] [Core concepts](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/core_concepts.md)
>
> Clients, resources, request types, and response models.

### Workflows

> [card] [Scan models](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/model_scanning.md)
>
> Scan local, Hugging Face, S3, and Azure models with AI Supply Chain Security.

> [card] [Runtime security](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/runtime_security.md)
>
> Analyze LLM interactions and use the agentic evaluation endpoints.

> [card] [Attack simulation](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/attack_simulation.md)
>
> Run red team sessions against your AI application.

> [card] [API usage examples](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/api_examples.md)
>
> Low-level resources, pagination, raw responses, and more.

### Reference

> [card] [Error handling](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/error_handling.md)
>
> Exception types, retries, and timeouts.

> [card] [Troubleshooting](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/troubleshooting.md)
>
> Fixes for common problems.

> [card] [Security and production guidance](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/security.md)
>
> Handle credentials and data safely in production.

> [card] [Version compatibility and upgrades](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/versioning.md)
>
> Versioning policy, pinning, and upgrading.

> [card] [Python API reference](https://docs.hiddenlayer.ai/docs/integrations/sdk_python/api_reference.md)
>
> Clients, resources, methods, and types.

## Additional resources

* [`hiddenlayer-sdk` on PyPI](https://pypi.org/project/hiddenlayer-sdk/): release history and package metadata.
* [GitHub repository](https://github.com/hiddenlayerai/hiddenlayer-sdk-python): source code, README, changelog, and the `examples` directory (including `demo.py` for model scanning and `red_team/` notebooks for AI Attack Simulation).
* [api.md](https://github.com/hiddenlayerai/hiddenlayer-sdk-python/blob/main/api.md): the generated list of every resource, method, and type in the SDK.
* [HiddenLayer Developer Portal](https://dev.hiddenlayer.ai/): REST API reference for the endpoints the SDK calls.
