Qriton Hopfield Anomaly Detection

Production-ready Binary and Continuous (Modern) Hopfield Neural Networks for real-time anomaly detection in Python. A pure-Python port of the @qriton/hopfield-anomaly npm package (v4.0.1), providing adaptive thresholds, gradient-based attribution, and cross-domain pattern discovery with zero external dependencies.

Installation

pip install qriton-hopfield-anomaly

Quick Start

Binary Hopfield (Hard Anomaly Detection)

from hopfield_anomaly import HopfieldAnomalyDetector

detector = HopfieldAnomalyDetector(
    feature_count=3,
    snapshot_length=5,
    anomaly_threshold=0.3,
    learning_rule="storkey",
)

detector.set_thresholds({
    "temperature": {"mode": "range", "min": 60, "max": 80},
    "pressure": {"mode": "range", "min": 95, "max": 105},
    "vibration": {"mode": "below", "value": 50},
})

detector.train_with_defaults()

for _ in range(5):
    detector.add_data_point({"temperature": 70, "pressure": 100, "vibration": 20})

result = detector.detect()
print(result.is_anomaly)        # False
print(result.anomaly_score)     # 0.245
print(result.feature_impact[0]) # {"name": "temperature", "energy_delta": -0.123}

Continuous Hopfield (Soft Anomaly Detection)

from hopfield_anomaly import ContinuousHopfieldAnomalyDetector

detector = ContinuousHopfieldAnomalyDetector(
    feature_count=3,
    snapshot_length=5,
    energy_type="logsumexp",
    beta=1.0,
)

detector.set_features(
    ["temperature", "pressure", "vibration"],
    {
        "temperature": {"min": 0, "max": 100},
        "pressure": {"min": 0, "max": 200},
        "vibration": {"min": 0, "max": 50},
    },
)

detector.train_with_defaults()

for _ in range(5):
    detector.add_data_point({"temperature": 70.5, "pressure": 105.2, "vibration": 12.3})

result = detector.detect()
print(result.is_anomaly)         # False
print(result.anomaly_score)      # 0.182
print(result.composition[0])     # {"pattern_index": 0, "similarity": 0.95, "percentage": 72}
print(result.feature_gradients[0])  # {"name": "pressure", "gradient_norm": 0.234}

High-Level Monitor APIs

AnomalyMonitor (Binary)

from hopfield_anomaly import AnomalyMonitor

monitor = AnomalyMonitor(feature_count=3)
monitor.set_thresholds({
    "temp": {"mode": "range", "min": 60, "max": 80},
    "pressure": {"mode": "range", "min": 95, "max": 105},
    "vibration": {"mode": "below", "value": 50},
})
monitor.train_with_defaults()

result = monitor.process({"temp": 70, "pressure": 100, "vibration": 20})
if result and result.is_anomaly:
    print(f"Anomaly detected: {result.anomaly_score}")

ContinuousAnomalyMonitor (Cross-Domain Discovery)

from hopfield_anomaly import ContinuousAnomalyMonitor

monitor = ContinuousAnomalyMonitor(feature_count=3)
monitor.set_features(
    ["temp", "pressure", "vibration"],
    {
        "temp": {"min": 0, "max": 100},
        "pressure": {"min": 0, "max": 200},
        "vibration": {"min": 0, "max": 50},
    },
)
monitor.train_with_defaults()

result = monitor.process({"temp": 70.5, "pressure": 105.2, "vibration": 12.3})
if result and result.is_anomaly:
    print(f"Anomaly score: {result.anomaly_score}")
    for comp in result.composition:
        print(f"  Pattern {comp['pattern_index']}: {comp['percentage']}% match")

API Reference

Requirements

• Python >= 3.10
• No external dependencies

Links

• npm package: @qriton/hopfield-anomaly
• GitHub: github.com/qriton/hopfield-anomaly

License

MIT