hcgk-kernel 1.0.5

Hardware Control Gatekeeper Kernel - Authorization system for heavy AI models

HCGK Kernel

Hardware Control Gatekeeper Kernel for AI Model Loading

HCGK Kernel is a hardware authorization system designed to prevent AI model loading failures by validating system resources before execution. It performs comprehensive hardware detection and validation to ensure your system meets the requirements for loading memory-intensive models.

---

Overview

Modern AI models require substantial computational resources. Loading a model without adequate RAM or VRAM can lead to:

• System crashes and out-of-memory errors
• Prolonged loading times and system freezes
• Data loss from forced shutdowns
• Wasted time troubleshooting preventable failures

HCGK Kernel solves this by validating your hardware before attempting to load models, providing clear feedback on what's available and what's required.

---

Features

• Comprehensive Hardware Detection: Detailed scanning of RAM, VRAM, CPU, and GPU resources
• Validated Configuration: Type-safe configuration with automatic validation
• Safety Margins: Configurable resource reservation to prevent system instability
• Retry Logic: Automatic retry on transient hardware detection failures
• Detailed Reporting: Clear, actionable feedback on authorization status
• CLI Tools: Professional command-line interface with JSON output support
• Extensive Logging: Comprehensive logs for debugging and monitoring
• Zero Side Effects: Pure functional design with no global state

---

Installation

pip install hcgk-kernel

Requirements:

• Python 3.8 or higher
• psutil 5.9.0 or higher
• torch 2.0.0 or higher

---

Quick Start

Command Line Interface

# Check hardware authorization
hcgk check

# Display system information
hcgk info

# Show system requirements
hcgk info --requirements

# Output as JSON
hcgk info --json

# Display configuration
hcgk config

Python API

from hcgk_kernel import HCGKKernel

# Initialize kernel
kernel = HCGKKernel()

# Check authorization
authorized, message = kernel.authorize()

if authorized:
    # Proceed with model loading
    model = load_your_model()
else:
    print(f"Authorization denied: {message}")

---

Hardware Requirements

HCGK Kernel validates hardware against configurable thresholds:

GPU Mode (CUDA Available)

• Minimum RAM: 8 GB (default)
• Minimum VRAM: 4 GB (default)

CPU Mode (No GPU)

• Minimum RAM: 16 GB (default)

These values can be configured via environment variables or programmatic configuration.

---

Configuration

Environment Variables

# Hardware thresholds
export HCGK_MIN_RAM_GB=8.0              # Minimum RAM for GPU mode
export HCGK_MIN_VRAM_GB=4.0             # Minimum VRAM required
export HCGK_MIN_RAM_NO_GPU_GB=16.0      # Minimum RAM for CPU mode

# Safety settings
export HCGK_RAM_SAFETY_MARGIN=0.1       # Reserve 10% RAM (0.0-1.0)
export HCGK_MAX_SCAN_RETRIES=2          # Hardware scan retry attempts
export HCGK_STRICT_MODE=true            # Enable strict validation

Programmatic Configuration

from hcgk_kernel import HCGKKernel, HCGKConfig

config = HCGKConfig(
    MIN_RAM_GB=16.0,
    MIN_VRAM_GB=8.0,
    MIN_RAM_NO_GPU_GB=32.0,
    RAM_SAFETY_MARGIN=0.15,
    MAX_SCAN_RETRIES=3,
    STRICT_MODE=True
)

kernel = HCGKKernel(config=config)

---

Usage Examples

Basic Authorization

from hcgk_kernel import HCGKKernel

kernel = HCGKKernel()
authorized, message = kernel.authorize()

if not authorized:
    raise RuntimeError(f"Hardware requirements not met: {message}")

# Safe to proceed with model loading

Retrieve System Information

kernel = HCGKKernel()
info = kernel.get_system_info()

# Access hardware details
ram_total = info['ram']['total_gb']
gpu_name = info['gpu']['name']
vram_free = info['gpu']['vram_total_gb'] - info['gpu']['vram_allocated_gb']

print(f"System: {ram_total:.2f}GB RAM, GPU: {gpu_name}")

Silent Mode for Scripts

import sys
from hcgk_kernel import HCGKKernel

kernel = HCGKKernel(silent=True)
authorized, _ = kernel.authorize()

sys.exit(0 if authorized else 1)

Custom Configuration

from hcgk_kernel import HCGKKernel, HCGKConfig

# Define custom requirements
config = HCGKConfig(
    MIN_RAM_GB=32.0,
    MIN_VRAM_GB=16.0,
    RAM_SAFETY_MARGIN=0.2
)

kernel = HCGKKernel(config=config)
authorized, message = kernel.authorize()

Integration with Model Loading

from hcgk_kernel import HCGKKernel
import torch

def load_model_with_validation(model_path):
    """Load model with hardware validation."""
    kernel = HCGKKernel()
    
    # Validate hardware
    authorized, message = kernel.authorize()
    if not authorized:
        raise RuntimeError(f"Hardware validation failed: {message}")
    
    # Get system info for optimization
    info = kernel.get_system_info()
    device = "cuda" if info['gpu']['available'] else "cpu"
    
    # Load model
    model = torch.load(model_path, map_location=device)
    return model

# Usage
try:
    model = load_model_with_validation("model.pt")
except RuntimeError as e:
    print(f"Error: {e}")

---

CLI Reference

hcgk check

Check hardware authorization status.

Options:

• -s, --silent - Suppress output, return exit code only
• -V, --verbose - Show detailed validation messages

Exit Codes:

• 0 - Authorization granted
• 1 - Authorization denied or error

Example:

hcgk check --verbose

hcgk info

Display detailed system information.

Options:

• -j, --json - Output in JSON format
• -r, --requirements - Include requirements check

Example:

hcgk info --json --requirements

hcgk config

Display current configuration.

Options:

• -j, --json - Output in JSON format

Example:

hcgk config

hcgk validate

Validate configuration without running authorization.

Example:

hcgk validate

---

Architecture

HCGK Kernel is built with a modular architecture:

• HCGKKernel: Main orchestrator that coordinates scanning and validation
• SystemScanner: Performs hardware detection with retry logic
• ConstraintValidator: Validates hardware against requirements
• HCGKConfig: Type-safe configuration with validation
• HardwareInfo: Immutable data container for hardware information
• SecureLogger: Thread-safe logging with secure directory handling

---

Safety Features

RAM Safety Margin

By default, HCGK reserves 10% of available RAM to prevent the system from running out of memory during model loading. This margin is configurable via RAM_SAFETY_MARGIN.

Retry Logic

Hardware scanning includes automatic retry logic to handle transient failures. The number of retries is configurable via MAX_SCAN_RETRIES.

Validation Checks

Multiple independent validation checks are performed:

• Total RAM sufficiency
• Available RAM after safety margin
• VRAM total and free space
• System memory pressure detection

Detailed Reporting

When validation fails, HCGK provides:

• Specific reasons for each failure
• Current hardware specifications
• Actionable recommendations for resolution

---

Error Handling

HCGK Kernel provides a hierarchy of custom exceptions:

• HCGKError: Base exception for all kernel errors
• DependencyError: Missing required dependencies (psutil, torch)
• ScanError: Hardware scan failures
• ValidationError: Hardware validation failures

All exceptions include detailed error messages for debugging.

---

Performance

• Initialization: 10-20ms
• Hardware Scan: 50-100ms
• Validation: 5-10ms
• Total Authorization: 100-150ms
• Memory Overhead: 2-5MB

Performance measurements on standard development hardware.

---

Testing

HCGK Kernel includes comprehensive test coverage:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=hcgk_kernel

Test suite includes:

• Unit tests for all components
• Integration tests for complete workflows
• Configuration validation tests
• Error handling tests

---

Logging

Logs are written to ~/.alice_kernels/logs/.hcgk_au.log by default. Log entries include:

• Timestamp
• Log level
• Function name and line number
• Detailed message

Logging is thread-safe and includes fallback to current directory if home directory is not writable.

---

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Please ensure code follows the existing style and includes appropriate documentation.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Author

Matias Nisperuza

---

Support

Email: [e-mail] pyPI page:https://pypi.org/project/hcgk-kernel/

---

Acknowledgments

Built for the AI/ML community to provide reliable hardware validation for model loading operations.