Metadata-Version: 2.4
Name: qriton-hopfield-anomaly
Version: 4.0.1
Summary: Production-ready Binary and Continuous (Modern) Hopfield Neural Networks for anomaly detection and cross-domain discovery
Project-URL: Homepage, https://github.com/qriton/hopfield-anomaly
Project-URL: Repository, https://github.com/qriton/hopfield-anomaly
Project-URL: Issues, https://github.com/qriton/hopfield-anomaly/issues
Author-email: Qriton <info@qriton.com>
License-Expression: MIT
Keywords: anomaly-detection,attention,continuous-hopfield,hebbian,hopfield,iot,logsumexp,machine-learning,monitoring,neural-network,outlier-detection,pattern-recognition,real-time,sensor-data,storkey,time-series,unsupervised
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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](https://www.npmjs.com/package/@qriton/hopfield-anomaly) npm package (v4.0.1), providing adaptive thresholds, gradient-based attribution, and cross-domain pattern discovery with zero external dependencies.

---

## Installation

```bash
pip install qriton-hopfield-anomaly
```

---

## Quick Start

### Binary Hopfield (Hard Anomaly Detection)

```python
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)

```python
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)

```python
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)

```python
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](https://www.npmjs.com/package/@qriton/hopfield-anomaly)
- GitHub: [github.com/qriton/hopfield-anomaly](https://github.com/qriton/hopfield-anomaly)

## License

MIT
