Waveguardclient

WaveGuard Python SDK

波動物理学を活用した異常検知。機械学習ではありません。
API 呼び出しは 1 回。完全にステートレス。あらゆるデータ型に対応します。

ベンチマーク • クイックスタート • ユースケース • 例 • MCP / Claude • API リファレンス

WaveGuard とは？

WaveGuard は、汎用的な異常検知 API です。サーバーメトリクス、金融取引、ログファイル、センサーの測定値、時系列など、あらゆるデータを送信すると、異常スコア、信頼度、アラートの原因となった特徴量の説明が返されます。

トレーニングパイプラインは不要です。モデル管理も状態管理も不要です。API 呼び出しは 1 回です。

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

内部では、機械学習の代わりに GPU 加速による波動物理学を使用しています。物理学について知る必要も、気にする必要もありません。すべてサーバー側で処理されます。

Modal のダッシュボードと API エンドポイント

Modal を見ると、デプロイ済みの関数（たとえば fastapi_app、gpu_scan、gpu_fingerprint）が表示されます。 これらはコンピューティング／ランタイムの単位であり、HTTP ルートの一覧ではありません。

稼働中の API エンドポイントをすべて確認するには、次を使用してください。

• OpenAPI ドキュメント：https://gpartin--waveguard-api-fastapi-app.modal.run/docs
• OpenAPI JSON：https://gpartin--waveguard-api-fastapi-app.modal.run/openapi.json

ベンチマーク（v2.2）

実世界の 6 つのシナリオでのWaveGuard v2.2 と scikit-learn の比較（各シナリオでトレーニングサンプル 10 件、テストサンプル 10 件）。

要約：WaveGuard v2.2 は6 シナリオ中 4 シナリオで優位で、F1 の平均は 0.76 です。sklearn の手法に匹敵し、機械学習の専門知識は一切必要ありません。

F1 スコア（適合率と再現率のバランス）

v2.2 の新機能

マルチ解像度スコアリングでは、全体的なフィンガープリント距離に加えて、各特徴量の局所格子エネルギーを追跡します。これにより、v2.1 の全体平均では見逃されていた、微妙な特徴量ごとの異常（IoT センサー 10 台中 3 台のドリフトなど）を検出できます。IoT の F1 は 0.30 から 0.87 に向上しました。

sklearn ではなく WaveGuard を選ぶ場合

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

ベンチマークの拡張版：WaveGuard は、公開ベンチマークデータセット12件すべてで F1 スコア第1位です。HuggingFace で比較結果の全容をご覧ください。

実環境での検証：暗号資産の暴落検知

WaveGuard は、暗号資産リスクスキャナーの CryptoGuard を支えています。過去の暴落7件（LUNA、FTX、Celsius、3AC、UST、SOL/FTX、TITAN）を対象にバックテストを実施しました。

WaveGuard は2022年10月16日に FTT（FTX トークン）を「注意」と判定しました。これは94%の暴落の23日前です。一方、Z スコア分析では異常は見られませんでした。

再現率を維持しながら、統計的なベースラインより誤検知を5分の1に削減します。結果の全容：CryptoGuard バックテスト。

インストール

pip install WaveGuardClient

これで完了です。依存関係は requests のみです。物理演算はすべて GPU 上のサーバー側で実行されます。

RapidAPI で無料の API キーを取得 →

クイックスタート

同じ scan() 呼び出しを、あらゆる種類のデータに使用できます。以下は異なる3つの業界の例です。API は同じです。

侵害されたサーバーを検出する

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%}")

不正な取引を検知する

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
    ],
)

ログ内のセキュリティイベントを検出する

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",
)

同じクライアント。同じ scan() 呼び出し。あらゆるデータに対応します。

ユースケース

WaveGuard はあらゆる構造化データ、数値データ、テキストデータに対応します。「正常」を定義できれば、そこからの逸脱を検出できます。

API はユーザーのドメインを把握しません。「正常」の状態（トレーニングデータ）を把握し、そこから逸脱するものを検知するだけです。そのため汎用的に使えます。状況の説明はユーザーが行い、検知は API が担います。

対応データ型

データの形状からすべて自動判定されます。設定は不要です。

使用例

すべての使用例は、ライブ API にアクセスする実行可能な Python スクリプトです。

pip install WaveGuardClient
python examples/iot_predictive_maintenance.py

MCP サーバー（Claude Desktop）

MCP ツールとして利用できる、初の物理学ベースの異常検知ツールです。 ML の知識がなくても、あらゆる AI エージェントが異常を検知できるようになります。

クイックセットアップ

{
  "mcpServers": {
    "waveguard": {
      "command": "uvx",
      "args": ["--from", "WaveGuardClient", "waveguard-mcp"]
    }
  }
}

その後、Claude に 「これらのセンサー読み取り値に異常はありますか？」 と尋ねると、自動的に waveguard_scan を呼び出します。

利用可能な MCP ツール

動作する使用例については MCP エージェントのデモを、セットアップの詳細については MCP 統合ガイドをご覧ください。

Azure からの移行

Azure Anomaly Detector は 2026 年 10 月に廃止されます。 WaveGuard はそのまま置き換えて使用できます。

# 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

詳細については Azure 移行ガイドをご覧ください。

API リファレンス

wg.scan(training, test, encoder_type=None, sensitivity=None)

.results（サンプルごとの結果）と .summary（集計結果）を含む ScanResult を返します。

wg.health() / wg.tier()

ヘルスチェック（認証不要）とサブスクリプションティアの情報を取得します。

高度なインテリジェンスメソッド（v3.3.0）

• wg.counterfactual(...)
• wg.trajectory_scan(...)
• wg.instability(...)
• wg.phase_coherence(...)
• wg.interaction_matrix(...)
• wg.cascade_risk(...)
• wg.mechanism_probe(...)
• wg.action_surface(...)
• wg.multi_horizon_outlook(...)

これらは /v1/* インテリジェンスエンドポイントに直接対応し、急速に進化するサーバー側レスポンススキーマとの最大限の互換性を確保するため、生の JSON ペイロードを返します。

エラー処理

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")

API リファレンスの全容については、docs/api-reference.mdをご覧ください。

プロジェクト構成

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

開発

git clone https://github.com/gpartin/WaveGuardClient.git
cd WaveGuardClient
pip install -e ".[dev]"
pytest

リンク

• RapidAPI（API キーの取得先）：https://rapidapi.com/gpartin/api/waveguard
• ライブ API: https://gpartin--waveguard-api-fastapi-app.modal.run
• 対話型ドキュメント（Swagger）: https://gpartin--waveguard-api-fastapi-app.modal.run/docs
• PyPI: https://pypi.org/project/WaveGuardClient/
• Smithery: https://smithery.ai/servers/emergentphysicslab/waveguard
• Glama: https://glama.ai/mcp/connectors/com.emergentphysicslab/waveguard

ライセンス

MIT — LICENSEをご覧ください。