qriton-hopfield-anomaly 4.0.1

Production-ready Binary and Continuous (Modern) Hopfield Neural Networks for anomaly detection and cross-domain discovery

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

Class	Description
HopfieldNetwork	Binary Hopfield network with Hebbian and Storkey learning rules, asynchronous recall, and energy computation.
ContinuousHopfieldNetwork	Modern Hopfield network with continuous states, LogSumExp/quadratic energy, gradient descent dynamics, and attention weights.
AdaptiveThreshold	Auto-tuning anomaly threshold using 95th-percentile tracking (unsupervised) or labeled feedback (supervised).
HopfieldAnomalyDetector	Binary anomaly detector with threshold-based binarization, Z-score scoring, and gradient-based feature attribution.
ContinuousHopfieldAnomalyDetector	Continuous anomaly detector with feature normalization, pattern composition analysis, and gradient-based discovery.
AnomalyMonitor	High-level wrapper around HopfieldAnomalyDetector with a single process() call for streaming data.
ContinuousAnomalyMonitor	High-level wrapper around ContinuousHopfieldAnomalyDetector with cross-domain event detection.

---

Requirements

• Python >= 3.10
• No external dependencies

---

Links

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

License

MIT