Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,55 @@
+---
+license: mit
+language: en
+library_name: scikit-learn
+tags:
+- anomaly-detection
+- isolation-forest
+- time-series
+- system-monitoring
+- tabular
+datasets:
+- harpertoken/stat
+metrics:
+- precision
+- recall
+---
+
+# mark
+
+An IsolationForest anomaly detector over the [`stat`](https://huggingface.co/datasets/harpertoken/stat) macOS system-telemetry dataset. It learns what normal machine behaviour looks like from per-second CPU, memory, disk and network counters, and flags samples that do not fit. CPU only, scikit-learn only, no PyTorch and no transformer anywhere in the path. The saved bundle is a StandardScaler plus a 200-tree forest, eight features, a few hundred kilobytes.
+
+Training used the first 80 percent of the session in time order (4,951 rows) and held out the last 20 percent (1,238 rows). The disk and network columns in `stat` are since-boot counters, so they enter as per-interval differences, exactly as that card recommends. `cpu_temp` is null throughout and is dropped; per-core `cpu_usage` enters as its mean and max.
+
+## Usage
+
+```python
+import numpy as np
+from huggingface_hub import hf_hub_download
+import joblib
+
+bundle = joblib.load(hf_hub_download("harpertoken/mark", "model.joblib"))
+X = np.array([[46.8, 96.0, 3410.2, 33.0, 6.1, 5.8, 0.4, 0.3]])
+print(bundle["model"].predict(bundle["scaler"].transform(X)))
+```
+
+The eight columns, in order, are `cpu_mean`, `cpu_max`, `memory_used_mb`, `battery_status`, `disk_read_delta`, `disk_write_delta`, `net_sent_delta` and `net_recv_delta`. Output is 1 for normal, -1 for flagged. The bundle is saved with joblib, which uses pickle internally; load it only from this repository.
+
+## Evaluation
+
+Measured on the temporal holdout and on synthetic incidents built from holdout rows:
+
+| Case | Flagged |
+|---|---|
+| Clean holdout (false alarms) | 0.027 |
+| Stressed machine, CPU, memory and disk spiking together | 0.917 |
+| Idle crash, CPU and memory dropping together | 0.372 |
+| Network storm, sent and received spiking together | 0.245 |
+
+The contamination parameter is 0.01, so about one percent of training rows score as anomalous by construction; the holdout false-alarm rate of 0.027 reflects the battery recharge region the holdout covers, which the training window never saw.
+
+Single-feature extremes score poorly, and that is a property of the algorithm rather than a bug in this fit. IsolationForest separates points by random splits, and a point that is extreme in one of eight dimensions waits several splits for that dimension to be picked, which is the same depth normal points reach. Standardizing the features changes nothing for the same reason: the splits are uniform in range, and rescaling only reparametrizes the draw. Incidents that move several counters at once, the way a real stressed machine does, are the ones it catches.
+
+## Limitations
+
+This models one machine over one 1-hour-44-minute session. It has not seen another host, another workload, or a longer timescale, and there is no reason to expect it to transfer. The synthetic incidents are illustrative, not a benchmark. The `stat` card's unit caveat applies here too: the disk and network deltas are raw counter advances whose physical unit was never confirmed, so thresholds learned on them are in those raw units.