A previous release had provenance metadata, but this release does not. View details.
WaveGuard Python SDK
Anomaly detection powered by wave physics. Not machine learning.
One API call. Fully stateless. Works on any data type.
Benchmarks • Quickstart • Use Cases • Examples • MCP / Claude • API Reference
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.
How does it actually work?
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.
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 |
Reproduce these benchmarks
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.
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.
| Industry | What You Scan | What It Catches |
|---|---|---|
| DevOps | Server metrics (CPU, memory, latency) | Memory leaks, DDoS attacks, runaway processes |
| Fintech | Transactions (amount, velocity, location) | Fraud, money laundering, account takeover |
| Security | Log files, access events | SQL injection, crypto miners, privilege escalation |
| IoT / Manufacturing | Sensor readings (temp, pressure, vibration) | Equipment failure, calibration drift |
| E-commerce | User behavior (session time, cart, clicks) | Bot traffic, bulk purchase fraud, scraping |
| Healthcare | Lab results, vitals, biomarkers | Abnormal readings, data entry errors |
| Time Series | Metric windows (latency, throughput) | Spikes, flatlines, seasonal breaks |
The API doesn't know your domain. It just knows what "normal" looks like (your training data) and flags anything that deviates. This makes it general — you bring the context, it brings the detection.
Supported Data Types
All auto-detected from data shape. No configuration needed:
| Type | Example | Use When |
|---|---|---|
| JSON objects | {"cpu": 45, "memory": 62} |
Structured records with named fields |
| Numeric arrays | [1.0, 1.2, 5.8, 1.1] |
Feature vectors, embeddings |
| Text strings | "ERROR segfault at 0x0" |
Logs, messages, free text |
| Time series | [100, 102, 98, 105, 99] |
Metric windows, sequential readings |
Examples
Every example is a runnable Python script that hits the live API:
| # | Example | Industry | What It Shows |
|---|---|---|---|
| 🏭 | IoT Predictive Maintenance | Manufacturing | Detect bearing failure, leaks, overloads from sensor data |
| 🔒 | Network Intrusion Detection | Cybersecurity | Catch port scans, C2 beacons, DDoS, data exfiltration |
| 🤖 | MCP Agent Demo | AI/Agents | Claude calls WaveGuard via MCP — zero ML knowledge |
| 01 | Quickstart | General | Minimal scan in 10 lines |
| 02 | Server Monitoring | DevOps | Memory leak + DDoS detection |
| 03 | Log Analysis | Security | SQL injection, crypto miner detection |
| 04 | Time Series | Monitoring | Latency spikes, flatline detection |
| 06 | Batch Scanning | E-commerce | 20 transactions, fraud flagging |
| 07 | Error Handling | Production | Retry logic, exponential backoff |
pip install WaveGuardClient
python examples/iot_predictive_maintenance.py
MCP Server (Claude Desktop)
The first physics-based anomaly detector available as an MCP tool. Give any AI agent the ability to detect anomalies — zero ML knowledge required.
Quick setup
{
"mcpServers": {
"waveguard": {
"command": "uvx",
"args": ["--from", "WaveGuardClient", "waveguard-mcp"]
}
}
}
Then ask Claude: "Are any of these sensor readings anomalous?" — it calls waveguard_scan automatically.
Available MCP tools
| Tool | Description |
|---|---|
waveguard_scan |
Detect anomalies in any structured data |
waveguard_scan_timeseries |
Auto-window time-series and detect anomalous segments |
waveguard_health |
Check API status and GPU availability |
See the MCP Agent Demo for a working example, or the MCP Integration Guide for full setup.
Azure Migration
Azure Anomaly Detector retires October 2026. WaveGuard is a drop-in replacement:
# Before (Azure) — 3+ API calls, stateful, time-series only
client = AnomalyDetectorClient(endpoint, credential)
model = client.train_multivariate_model(request) # minutes
result = client.detect_multivariate_batch_anomaly(model_id, data)
client.delete_multivariate_model(model_id)
# After (WaveGuard) — 1 API call, stateless, any data type
wg = WaveGuard(api_key="YOUR_KEY")
result = wg.scan(training=normal_data, test=new_data) # seconds
See Azure Migration Guide for details.
API Reference
wg.scan(training, test, encoder_type=None, sensitivity=None)
| Parameter | Type | Description |
|---|---|---|
training |
list |
2+ examples of normal data |
test |
list |
1+ samples to check |
encoder_type |
str |
Force: "json", "numeric", "text", "timeseries" (default: auto) |
sensitivity |
float |
0.5–3.0, lower = more sensitive (default: 1.0) |
Returns ScanResult with .results (per-sample) and .summary (aggregate).
wg.health() / wg.tier()
Health check (no auth) and subscription tier info.
Error Handling
from waveguard import WaveGuard, AuthenticationError, RateLimitError
try:
result = wg.scan(training=data, test=new_data)
except AuthenticationError:
print("Bad API key")
except RateLimitError:
print("Too many requests — back off and retry")
Full API reference: docs/api-reference.md
Project Structure
WaveGuardClient/
├── waveguard/ # Python SDK package
│ ├── __init__.py # Public API exports
│ ├── client.py # WaveGuard client class
│ └── exceptions.py # Exception hierarchy
├── mcp_server/ # MCP server for Claude Desktop
│ └── server.py # stdio + HTTP transport
├── benchmarks/ # Reproducible benchmarks vs sklearn
│ ├── benchmark_vs_sklearn.py
│ └── benchmark_results.json
├── examples/ # 9 runnable examples
├── docs/ # Documentation
│ ├── getting-started.md
│ ├── api-reference.md
│ ├── mcp-integration.md
│ └── azure-migration.md
├── tests/ # Test suite
├── pyproject.toml # Package config (pip install -e .)
└── CHANGELOG.md
Development
git clone https://github.com/gpartin/WaveGuardClient.git
cd WaveGuardClient
pip install -e ".[dev]"
pytest
Links
- Live API: https://gpartin--waveguard-api-fastapi-app.modal.run
- Interactive Docs (Swagger): https://gpartin--waveguard-api-fastapi-app.modal.run/docs
- PyPI: https://pypi.org/project/WaveGuardClient/
- Smithery: https://smithery.ai/servers/emergentphysicslab/waveguard
License
MIT — see LICENSE.
Metadata
Release files for WaveGuardClient 3.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| waveguardclient-3.3.0.tar.gz | 22.4 kB | Without provenance | Details for waveguardclient-3.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| waveguardclient-3.3.0-py3-none-any.whl | Python 3 | none | any | Details for waveguardclient-3.3.0-py3-none-any.whl |
Total release size: 43.0 kB
Release files / waveguardclient-3.3.0.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | waveguardclient-3.3.0.tar.gz |
|---|---|
| Size | 22.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
028b14548e956795dcb85d8279190529726b1d34986a47306064ae2627a86e4b
|
|
BLAKE2b-256 checksum How to use checksums |
b8269b1c1d90528bea2dfcdfded5bde04a97c5928ebb481cec6d3d14b6da39f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Release files / waveguardclient-3.3.0-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | waveguardclient-3.3.0-py3-none-any.whl |
|---|---|
| Size | 20.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ccb7bfe54ad5c023732efb76ffdf6ccf6079228b73b76be5ba9b60245cc32778
|
|
BLAKE2b-256 checksum How to use checksums |
a31a385a3dcd78a3f6fc914f8f841d1874f8c4ef8bd9b7ffaa7c670bb9ffdc55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Security for WaveGuardClient 3.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 2.1.0 2 files With provenance
- Added 3.3.0 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.