Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Antisource/heronaisec/llms.txt
Use this file to discover all available pages before exploring further.
This page covers everything you need to set up a working Heron AI Security environment: system requirements, virtual environment creation, dependency installation, and a verification script that confirms PyTorch can see your hardware. Following these steps in order ensures a clean, reproducible environment before you run any experiments.
System Requirements
| Requirement | Minimum | Notes |
|---|
| Python | 3.8 or higher | 3.10+ recommended |
| pip | Latest stable | Included with Python 3.8+ |
| Git | Any recent version | Required to clone the repository |
| CUDA-capable GPU | Optional | Strongly recommended; CPU-only runs are supported but slow |
Installation Steps
1. Clone the Repository
git clone https://github.com/Antisource/heronaisec.git
cd heronaisec
2. Create a Virtual Environment
Creating an isolated environment prevents dependency conflicts with other Python projects on your system.
3. Activate the Virtual Environment
source .venv/bin/activate
(.venv) when the environment is active. All subsequent pip install and python commands will operate inside this environment.
4. Install Dependencies
pip install -r requirements.txt
Dependencies
The requirements.txt file pins every dependency to a compatible version range. The table below documents each package, its pinned range, and its role in the framework.
Deep Learning
| Package | Version Range | Purpose |
|---|
torch | >=2.7,<3.0 | Core deep learning runtime; model training and inference on CPU and GPU |
Hugging Face Ecosystem
| Package | Version Range | Purpose |
|---|
transformers | >=4.56,<5.0 | Pre-trained transformer models and tokenizers (DistilBERT, BERT) |
datasets | >=3.6,<4.0 | Standardised dataset loading and preprocessing (SST-2 via GLUE) |
accelerate | >=1.8,<2.0 | Hardware-agnostic training acceleration used internally by Transformers |
evaluate | >=0.4.6,<0.5 | Metric computation utilities (accuracy, etc.) |
Scientific Computing
| Package | Version Range | Purpose |
|---|
numpy | >=2.0,<3.0 | Numerical array operations underpinning data manipulation |
pandas | >=2.2,<3.0 | Tabular storage and export of per-stage evaluation metrics |
scikit-learn | >=1.7,<2.0 | Supporting utilities for dataset splitting and evaluation helpers |
Visualization
| Package | Version Range | Purpose |
|---|
matplotlib | >=3.10,<4.0 | Publication-quality figures: persistence curves and intervention plots |
Configuration
| Package | Version Range | Purpose |
|---|
PyYAML | >=6.0,<7.0 | YAML parsing for experiment configuration files under configs/ |
Utilities
| Package | Version Range | Purpose |
|---|
tqdm | >=4.67,<5.0 | Progress bars during training and evaluation loops |
Verifying the Installation
After installation, run the included verification script to confirm that PyTorch is installed correctly and that your GPU (if present) is visible to the framework.
The script prints a four-line summary of your environment:
PyTorch version: 2.7.0
CUDA version: 12.4
CUDA available: True
GPU: NVIDIA GeForce RTX 3090
No GPU detected by PyTorch
Automatic GPU detectionHeron AI Security uses torch.cuda.is_available() to detect CUDA at runtime. The entry point main.py prints the detected device name at startup — Using GPU: <name> or Using CPU — before any experiment logic runs. You do not need to set environment variables or modify configuration files to switch between CPU and GPU; the framework handles device placement automatically.
Running on CPUAll experiments will complete without a GPU, but training DistilBERT on CPU is significantly slower than on a CUDA-capable device. A single baseline run that takes a few minutes on an RTX-class GPU may take several hours on CPU. If you are working on a CPU-only machine, consider using a smaller prototype subset (the train_dataset.select(range(5000)) call in experiments/baseline.py is already active by default) or reducing the number of training epochs in configs/baseline.yaml to keep iteration times manageable.