Waveguardclient

<p align="center">




<a href="https://smithery.ai/servers/emergentphysicslab/waveguard"></a>
</p>

<h1 align="center">WaveGuard Python SDK</h1>

<p align="center">
<strong>Anomaly detection powered by wave physics. Not machine learning.</strong><br>
One API call. Fully stateless. Works on any data type.
</p>

<p align="center">
<a href="#benchmarks">Benchmarks</a> •
<a href="#quickstart">Quickstart</a> •
<a href="#use-cases">Use Cases</a> •
<a href="#examples">Examples</a> •
<a href="#mcp-server-claude-desktop">MCP / Claude</a> •
<a href="docs/api-reference.md">API Reference</a>
</p>

---

What is WaveGuard?

WaveGuard is a general-purpose anomaly detection API. Send it any data — server metrics, financial transactions, log files, sensor readings, time series — and get back anomaly scores, confidence levels, and explanations of which features triggered the alert.

No training pipelines. No model management. No state. One API call.

Your data  →  WaveGuard API (GPU)  →  Anomaly scores + explanations

Under the hood, it uses GPU-accelerated wave physics instead of machine learning. You don't need to know or care about the physics — it's all server-side.

Modal dashboard vs API endpoints

If you look at Modal, you will see deployed functions (for example fastapi_app, gpu_scan, gpu_fingerprint).
Those are compute/runtime units, not the HTTP route list.

To see all live API endpoints, use:
- OpenAPI docs: https://gpartin--waveguard-api-fastapi-app.modal.run/docs
- OpenAPI JSON: https://gpartin--waveguard-api-fastapi-app.modal.run/openapi.json

<details>
<summary><strong>How does it actually work?</strong></summary>

Your data is encoded onto a 64³ lattice and run through coupled wave equation simulations on GPU. Normal data produces stable wave patterns; anomalies produce divergent ones. A 52-dimensional statistical fingerprint is compared between training and test data. Everything is torn down after each call — nothing is stored.

The key advantage over ML: no training data requirements (2+ samples is enough), no model drift, no retraining, no hyperparameter tuning. Same API call works on structured data, text, numbers, and time series.

</details>

Benchmarks (v2.2)

WaveGuard v2.2 vs scikit-learn across 6 real-world scenarios (10 training + 10 test samples each).

> TL;DR: WaveGuard v2.2 wins 4 of 6 scenarios and averages 0.76 F1 — competitive with sklearn methods while requiring zero ML expertise.

F1 Score (balanced precision-recall)

| Scenario | WaveGuard | IsolationForest | LOF | OneClassSVM |
|----------|:---------:|:---------------:|:---:|:-----------:|
| Server Metrics (IT Ops) | 0.87 | 0.71 | 0.87 | 0.62 |
| Financial Fraud | 0.83 | 0.74 | 0.77 | 0.77 |
| IoT Sensors (Industrial) | 0.87 | 0.69 | 0.69 | 0.65 |
| Network Traffic (Security) | 0.82 | 0.61 | 0.77 | 0.61 |
| Time-Series (Monitoring) | 0.46 | 0.77 | 0.80 | 0.67 |
| Sparse Features (Logs) | 0.72 | 0.90 | 0.82 | 0.78 |
| Average | 0.76 | 0.74 | 0.79 | 0.68 |

What's new in v2.2

Multi-resolution scoring tracks each feature's local lattice energy in addition to global fingerprint distance. This catches subtle per-feature anomalies (like 3 of 10 IoT sensors drifting) that v2.1's global averaging missed. IoT F1 improved from 0.30 → 0.87.

When to choose WaveGuard over sklearn

| Choose WaveGuard when... | Choose sklearn when... |
|--------------------------|------------------------|
| False alarms are expensive (alert fatigue, SRE pages) | You need to catch every possible anomaly |
| You have no ML expertise on the team | You have data scientists who can tune models |
| You need a zero-config API call | You can manage model lifecycle (train/save/load) |
| Data schema changes frequently | Feature engineering is stable |
| Your AI agent needs anomaly detection (MCP) | Everything runs locally, no API calls |

<details>
<summary><strong>Reproduce these benchmarks</strong></summary>

pip install WaveGuardClient scikit-learn
python benchmarks/benchmark_vs_sklearn.py

Results saved to benchmarks/benchmark_results.json. Benchmarks use deterministic random seeds for reproducibility.

</details>

Real-World Validation: Crypto Crash Detection

WaveGuard powers CryptoGuard, a crypto risk scanner. Backtested against 7 historical crashes (LUNA, FTX, Celsius, 3AC, UST, SOL/FTX, TITAN):

| Method | Recall | Avg Lead Time | False Positive Rate |
|--------|--------|---------------|---------------------|
| WaveGuard | 100% (7/7) | 27.4 days | 6.1% |
| Z-score baseline | 100% (7/7) | 28.4 days | 29.9% |
| Rolling volatility | 86% (6/7) | 15.5 days | 4.0% |

WaveGuard flagged FTT (FTX token) at CAUTION on October 16, 2022 — 23 days before the 94% crash — while z-score analysis showed nothing unusual.

5× fewer false alarms than statistical baselines with the same recall. Full results: CryptoGuard backtest.

Install

pip install WaveGuardClient

That's it. The only dependency is requests. All physics runs server-side on GPU.

Quickstart

The same scan() call works on any data type. Here are three different industries — same API:

Detect a compromised server

from waveguard import WaveGuard
wg = WaveGuard(api_key="YOUR_KEY")
result = wg.scan(

    training=[

        {"cpu": 45, "memory": 62, "disk_io": 120, "errors": 0},

        {"cpu": 48, "memory": 63, "disk_io": 115, "errors": 0},

        {"cpu": 42, "memory": 61, "disk_io": 125, "errors": 1},

    ],

    test=[

        {"cpu": 46, "memory": 62, "disk_io": 119, "errors": 0},    # ✅ normal

        {"cpu": 99, "memory": 95, "disk_io": 800, "errors": 150},   # 🚨 anomaly

    ],

)
for r in result.results:

    print(f"{'🚨' if r.is_anomaly else '✅'}  score={r.score:.1f}  confidence={r.confidence:.0%}")

Flag a fraudulent transaction

result = wg.scan(
    training=[
        {"amount": 74.50, "items": 3, "session_sec": 340, "returning": 1},
        {"amount": 52.00, "items": 2, "session_sec": 280, "returning": 1},
        {"amount": 89.99, "items": 4, "session_sec": 410, "returning": 0},
    ],
    test=[
        {"amount": 68.00, "items": 2, "session_sec": 300, "returning": 1},     # ✅ normal
        {"amount": 4200.00, "items": 25, "session_sec": 8, "returning": 0},     # 🚨 fraud
    ],
)

Catch a security event in logs

result = wg.scan(
    training=[
        "2026-02-24 10:15:03 INFO  Request processed in 45ms [200 OK]",
        "2026-02-24 10:15:04 INFO  Request processed in 52ms [200 OK]",
        "2026-02-24 10:15:05 INFO  Cache hit ratio=0.94 ttl=300s",
    ],
    test=[
        "2026-02-24 10:20:03 INFO  Request processed in 48ms [200 OK]",                  # ✅ normal
        "2026-02-24 10:20:04 CRIT  xmrig consuming 98% CPU, port 45678 open",             # 🚨 crypto miner
        "2026-02-24 10:20:05 WARN  GET /api/users?id=1;DROP TABLE users-- from 185.x.x",  # 🚨 SQL injection
    ],
    encoder_type="text",
)

Same client. Same scan() call. Any data.

Use Cases

WaveGuard works on any structured, numeric, or text data. If you can describe "normal," it can detect deviations.

…