WaveGuardClient 2.0.0__py3-none-any.whl

waveguard/__init__.py

@@ -0,0 +1,53 @@
+"""
+WaveGuard — Physics-based anomaly detection SDK.
+
+Quick start::
+
+    from waveguard import WaveGuard
+
+    wg = WaveGuard(api_key="YOUR_KEY")
+    result = wg.scan(training=normal_data, test=new_data)
+
+    for r in result.results:
+        print(r.is_anomaly, r.score, r.confidence)
+"""
+
+from .client import (  # noqa: F401
+    WaveGuard,
+    ScanResult,
+    SampleResult,
+    ScanSummary,
+    FeatureInfo,
+    EngineInfo,
+    HealthStatus,
+    TierInfo,
+    __version__,
+)
+from .exceptions import (  # noqa: F401
+    WaveGuardError,
+    AuthenticationError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    # Client
+    "WaveGuard",
+    # Results
+    "ScanResult",
+    "SampleResult",
+    "ScanSummary",
+    "FeatureInfo",
+    "EngineInfo",
+    "HealthStatus",
+    "TierInfo",
+    # Exceptions
+    "WaveGuardError",
+    "AuthenticationError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    # Meta
+    "__version__",
+]

waveguard/client.py

@@ -0,0 +1,363 @@
+"""
+WaveGuard Python SDK — stateless anomaly detection via wave physics.
+
+Usage::
+
+    from waveguard import WaveGuard
+
+    wg = WaveGuard(api_key="YOUR_KEY")
+
+    result = wg.scan(
+        training=[
+            {"cpu": 45, "memory": 62, "errors": 0},
+            {"cpu": 48, "memory": 63, "errors": 0},
+            {"cpu": 42, "memory": 61, "errors": 1},
+            {"cpu": 50, "memory": 64, "errors": 0},
+        ],
+        test=[
+            {"cpu": 46, "memory": 62, "errors": 0},    # normal
+            {"cpu": 99, "memory": 95, "errors": 150},   # anomaly
+        ],
+    )
+
+    for r in result.results:
+        print(r.is_anomaly, r.score, r.confidence)
+"""
+
+from __future__ import annotations
+
+import requests
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .exceptions import (
+    WaveGuardError,
+    AuthenticationError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+)
+
+__version__ = "2.0.0"
+
+
+# ─────────────────────────────── Data Classes ─────────────────────────────
+
+
+@dataclass
+class FeatureInfo:
+    """A single top-contributing feature in anomaly scoring."""
+
+    dimension: int
+    label: str
+    z_score: float
+
+
+@dataclass
+class EngineInfo:
+    """Physics engine configuration for this scan."""
+
+    grid_size: int
+    evolution_steps: int
+    fingerprint_dims: int
+
+
+@dataclass
+class SampleResult:
+    """Result of anomaly detection on a single test sample."""
+
+    score: float
+    is_anomaly: bool
+    threshold: float
+    mahalanobis_distance: float
+    confidence: float
+    top_features: List[FeatureInfo]
+    latency_ms: float
+    engine: EngineInfo
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ScanSummary:
+    """Aggregate statistics from a scan."""
+
+    total_test_samples: int
+    total_training_samples: int
+    anomalies_found: int
+    anomaly_rate: float
+    mean_score: float
+    max_score: float
+    total_latency_ms: float
+    encoder_type: str
+
+
+@dataclass
+class ScanResult:
+    """Complete result of a ``/v1/scan`` call.
+
+    Attributes
+    ----------
+    results : list[SampleResult]
+        One entry per test sample, in order.
+    summary : ScanSummary
+        Aggregate statistics across all test samples.
+    raw : dict
+        The full JSON response from the API.
+    """
+
+    results: List[SampleResult]
+    summary: ScanSummary
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HealthStatus:
+    """API health information."""
+
+    status: str
+    version: str
+    gpu: str
+    mode: str
+    uptime_seconds: float
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TierInfo:
+    """Current subscription tier and rate limits."""
+
+    tier: str
+    limits: Dict[str, int]
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+# ─────────────────────────────── Client ───────────────────────────────────
+
+
+class WaveGuard:
+    """WaveGuard Anomaly Detection client.
+
+    Parameters
+    ----------
+    api_key : str
+        Your WaveGuard API key.
+    base_url : str, optional
+        API base URL.  Defaults to the production Modal endpoint.
+    timeout : float, optional
+        Request timeout in seconds.  Default ``120`` (generous for GPU
+        cold starts).
+
+    Examples
+    --------
+    >>> wg = WaveGuard(api_key="wg_test_key")
+    >>> result = wg.scan(
+    ...     training=[{"a": 1}, {"a": 2}, {"a": 3}],
+    ...     test=[{"a": 100}],
+    ... )
+    >>> result.results[0].is_anomaly
+    True
+    """
+
+    DEFAULT_URL = "https://gpartin--waveguard-api-fastapi-app.modal.run"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_URL,
+        timeout: float = 120.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "X-API-Key": api_key,
+                "Content-Type": "application/json",
+                "User-Agent": f"waveguard-python/{__version__}",
+            }
+        )
+
+    # ── Core API ──────────────────────────────────────────────────────
+
+    def scan(
+        self,
+        training: List[Any],
+        test: List[Any],
+        encoder_type: Optional[str] = None,
+        sensitivity: Optional[float] = None,
+    ) -> ScanResult:
+        """Scan test data for anomalies against a training baseline.
+
+        This is the only method you need.  Send training + test data in a
+        single call, get anomaly scores back, and everything is torn down.
+        Fully stateless — nothing persists between calls.
+
+        Parameters
+        ----------
+        training : list
+            2+ examples of **normal** data.  All entries must be the same
+            type and shape.
+        test : list
+            1+ samples to check for anomalies.
+        encoder_type : str, optional
+            Force a specific encoder: ``"json"``, ``"numeric"``,
+            ``"text"``, ``"timeseries"``, ``"tabular"``.
+            Leave *None* for auto-detection (recommended).
+        sensitivity : float, optional
+            Detection sensitivity in the range 0.5–3.0.
+            Lower values are more sensitive (flag more anomalies).
+
+        Returns
+        -------
+        ScanResult
+            ``.results`` has one :class:`SampleResult` per test sample.
+            ``.summary`` has aggregate stats.
+        """
+        body: Dict[str, Any] = {
+            "training": training,
+            "test": test,
+        }
+        if encoder_type is not None:
+            body["encoder_type"] = encoder_type
+        if sensitivity is not None:
+            body["sensitivity"] = sensitivity
+
+        resp = self._post("/v1/scan", body)
+        return self._parse_scan(resp, len(training), len(test))
+
+    # ── Utility ───────────────────────────────────────────────────────
+
+    def health(self) -> HealthStatus:
+        """Check API health and GPU status.  No auth required."""
+        resp = self._get("/v1/health")
+        return HealthStatus(
+            status=resp.get("status", "unknown"),
+            version=resp.get("version", ""),
+            gpu=resp.get("gpu", ""),
+            mode=resp.get("mode", ""),
+            uptime_seconds=resp.get("uptime_seconds", 0.0),
+            raw=resp,
+        )
+
+    def tier(self) -> TierInfo:
+        """Get current subscription tier and rate limits."""
+        resp = self._get("/v1/tier")
+        return TierInfo(
+            tier=resp.get("tier", ""),
+            limits=resp.get("limits", {}),
+            raw=resp,
+        )
+
+    # ── Response parsing ──────────────────────────────────────────────
+
+    def _parse_scan(
+        self, resp: dict, n_train: int, n_test: int
+    ) -> ScanResult:
+        results = []
+        for r in resp.get("results", []):
+            features = [
+                FeatureInfo(
+                    dimension=f.get("dimension", 0),
+                    label=f.get("label", ""),
+                    z_score=f.get("z_score", 0.0),
+                )
+                for f in r.get("top_features", [])
+            ]
+            eng = r.get("engine", {})
+            results.append(
+                SampleResult(
+                    score=r.get("score", 0.0),
+                    is_anomaly=r.get("is_anomaly", False),
+                    threshold=r.get("threshold", 0.0),
+                    mahalanobis_distance=r.get("mahalanobis_distance", 0.0),
+                    confidence=r.get("confidence", 0.0),
+                    top_features=features,
+                    latency_ms=r.get("latency_ms", 0.0),
+                    engine=EngineInfo(
+                        grid_size=eng.get("grid_size", 32),
+                        evolution_steps=eng.get("evolution_steps", 150),
+                        fingerprint_dims=eng.get("fingerprint_dims", 52),
+                    ),
+                    raw=r,
+                )
+            )
+
+        s = resp.get("summary", {})
+        summary = ScanSummary(
+            total_test_samples=s.get("total_test_samples", n_test),
+            total_training_samples=s.get("total_training_samples", n_train),
+            anomalies_found=s.get("anomalies_found", 0),
+            anomaly_rate=s.get("anomaly_rate", 0.0),
+            mean_score=s.get("mean_score", 0.0),
+            max_score=s.get("max_score", 0.0),
+            total_latency_ms=s.get("total_latency_ms", 0.0),
+            encoder_type=s.get("encoder_type", "auto"),
+        )
+
+        return ScanResult(results=results, summary=summary, raw=resp)
+
+    # ── Internal HTTP ─────────────────────────────────────────────────
+
+    def _post(self, path: str, body: dict) -> dict:
+        url = f"{self.base_url}{path}"
+        try:
+            r = self._session.post(url, json=body, timeout=self.timeout)
+        except requests.ConnectionError:
+            raise WaveGuardError(f"Cannot connect to {self.base_url}")
+        except requests.Timeout:
+            raise WaveGuardError(
+                f"Request timed out after {self.timeout}s"
+            )
+        return self._handle(r)
+
+    def _get(self, path: str) -> dict:
+        url = f"{self.base_url}{path}"
+        try:
+            r = self._session.get(url, timeout=self.timeout)
+        except requests.ConnectionError:
+            raise WaveGuardError(f"Cannot connect to {self.base_url}")
+        except requests.Timeout:
+            raise WaveGuardError(
+                f"Request timed out after {self.timeout}s"
+            )
+        return self._handle(r)
+
+    def _handle(self, r: requests.Response) -> dict:
+        if r.status_code == 401:
+            raise AuthenticationError(
+                "Invalid or missing API key",
+                status_code=401,
+                detail=r.text,
+            )
+        if r.status_code == 422:
+            raise ValidationError(
+                f"Validation failed: {r.text}",
+                status_code=422,
+                detail=r.text,
+            )
+        if r.status_code == 429:
+            raise RateLimitError(
+                f"Rate or tier limit exceeded: {r.text}",
+                status_code=429,
+                detail=r.text,
+            )
+        if r.status_code >= 500:
+            raise ServerError(
+                f"Server error {r.status_code}: {r.text}",
+                status_code=r.status_code,
+                detail=r.text,
+            )
+        if r.status_code >= 400:
+            raise WaveGuardError(
+                f"API error {r.status_code}: {r.text}",
+                status_code=r.status_code,
+                detail=r.text,
+            )
+        try:
+            return r.json()
+        except ValueError:
+            return {"raw": r.text}
+
+    def __repr__(self) -> str:
+        return f"WaveGuard(base_url='{self.base_url}')"

waveguard/exceptions.py

@@ -0,0 +1,63 @@
+"""
+WaveGuard exception hierarchy.
+
+All exceptions inherit from WaveGuardError so you can catch them with a
+single ``except WaveGuardError`` block, or handle specific cases granularly.
+"""
+
+__all__ = [
+    "WaveGuardError",
+    "AuthenticationError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+]
+
+
+class WaveGuardError(Exception):
+    """Base exception for all WaveGuard SDK errors.
+
+    Attributes
+    ----------
+    message : str
+        Human-readable error description.
+    status_code : int
+        HTTP status code (0 if not from an HTTP response).
+    detail : str
+        Raw error body from the API, if available.
+    """
+
+    def __init__(self, message: str, status_code: int = 0, detail: str = ""):
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(message)
+
+
+class AuthenticationError(WaveGuardError):
+    """API key is invalid, expired, or missing (HTTP 401)."""
+    pass
+
+
+class ValidationError(WaveGuardError):
+    """Request data failed server-side validation (HTTP 422).
+
+    Check ``detail`` for specifics (e.g. empty training array, type mismatch).
+    """
+    pass
+
+
+class RateLimitError(WaveGuardError):
+    """Rate limit or subscription tier limit exceeded (HTTP 429).
+
+    Back off and retry, or upgrade your tier.
+    """
+    pass
+
+
+class ServerError(WaveGuardError):
+    """Internal server error (HTTP 5xx).
+
+    Usually transient — retry after a short delay.
+    """
+    pass

waveguardclient-2.0.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: WaveGuardClient
+Version: 2.0.0
+Summary: Python SDK for WaveGuard — physics-based anomaly detection API
+Author: Greg Partin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gpartin/WaveGuardClient
+Project-URL: Documentation, https://github.com/gpartin/WaveGuardClient/tree/main/docs
+Project-URL: Repository, https://github.com/gpartin/WaveGuardClient
+Project-URL: Issues, https://github.com/gpartin/WaveGuardClient/issues
+Project-URL: API, https://gpartin--waveguard-api-fastapi-app.modal.run/docs
+Keywords: anomaly-detection,api-client,sdk,waveguard,physics-based,mcp,model-context-protocol,azure-migration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: mcp
+Requires-Dist: requests>=2.28; extra == "mcp"
+Requires-Dist: fastapi>=0.100; extra == "mcp"
+Requires-Dist: uvicorn>=0.20; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/pypi/v/WaveGuardClient?style=for-the-badge&color=blueviolet" alt="PyPI">
+  <img src="https://img.shields.io/badge/API-v2.0.0_stateless-brightgreen?style=for-the-badge" alt="v2.0.0">
+  <img src="https://img.shields.io/badge/GPU-CUDA_accelerated-76B900?style=for-the-badge&logo=nvidia" alt="CUDA">
+  <img src="https://img.shields.io/badge/MCP-Claude_Desktop-orange?style=for-the-badge" alt="MCP">
+</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="#quickstart">Quickstart</a> •
+  <a href="#use-cases">Use Cases</a> •
+  <a href="#examples">Examples</a> •
+  <a href="docs/api-reference.md">API Reference</a> •
+  <a href="docs/mcp-integration.md">MCP / Claude</a> •
+  <a href="docs/azure-migration.md">Azure Migration</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.
+
+<details>
+<summary><strong>How does it actually work?</strong></summary>
+
+Your data is encoded onto a 32³ 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>
+
+## Install
+
+```bash
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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. They span **6 industries and 4 data types** to show WaveGuard isn't tied to one domain:
+
+| # | Example | Industry | Data Type | What It Shows |
+|---|---------|----------|-----------|---------------|
+| 01 | [Quickstart](examples/01_quickstart.py) | General | JSON | Minimal scan in 10 lines |
+| 02 | [Server Monitoring](examples/02_server_monitoring.py) | DevOps | JSON | Memory leak + DDoS detection |
+| 03 | [Log Analysis](examples/03_log_analysis.py) | Security | Text | SQL injection, crypto miner, stack traces |
+| 04 | [Time Series](examples/04_time_series.py) | Monitoring | Numeric | Latency spikes, flatline detection |
+| 05 | [Azure Migration](examples/05_azure_migration.py) | Enterprise | JSON | Side-by-side Azure replacement |
+| 06 | [Batch Scanning](examples/06_batch_scanning.py) | E-commerce | JSON | 20 transactions, fraud flagging |
+| 07 | [Error Handling](examples/07_error_handling.py) | Production | — | Retry logic, exponential backoff |
+
+## MCP Server (Claude Desktop)
+
+Give Claude the ability to detect anomalies. Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "waveguard": {
+      "command": "python",
+      "args": ["/path/to/WaveGuardClient/mcp_server/server.py"],
+      "env": {
+        "WAVEGUARD_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+Then ask Claude: *"Check if these server metrics are anomalous..."*
+
+See [MCP Integration Guide](docs/mcp-integration.md) for full setup.
+
+## Azure Migration
+
+**Azure Anomaly Detector retires October 2026.** WaveGuard is a drop-in replacement:
+
+```python
+# 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](docs/azure-migration.md) 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
+
+```python
+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](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
+│   └── README.md           # MCP setup guide
+├── examples/               # 7 runnable examples
+├── docs/                   # Documentation
+│   ├── getting-started.md
+│   ├── api-reference.md
+│   ├── mcp-integration.md
+│   └── azure-migration.md
+├── tests/                  # Test suite (runs offline)
+├── pyproject.toml          # Package config (pip install -e .)
+└── CHANGELOG.md
+```
+
+## Development
+
+```bash
+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/
+
+## License
+
+MIT — see [LICENSE](LICENSE).

waveguardclient-2.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+waveguard/__init__.py,sha256=FONe580D6xKXbfreD9l6tRvIgU2LGucadVsIlowZv_k,971
+waveguard/client.py,sha256=OCuUwec3Z0HGat2PYob7OEGz4Vc--GqdJNmaFOF1QQU,11440
+waveguard/exceptions.py,sha256=WX9vtgk_YptWU0d_JHGofsixL_UEBLDAasdS5YNeQic,1499
+waveguardclient-2.0.0.dist-info/licenses/LICENSE,sha256=yV4vV4gmeJzzKCuJZPkv6esNWoR78ZIUHBIyq5vrSHA,1073
+waveguardclient-2.0.0.dist-info/METADATA,sha256=zie4uYNXKAgdQFhAOFqAKBO-xvwNjpwe3xo3-zUf4dc,11943
+waveguardclient-2.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+waveguardclient-2.0.0.dist-info/top_level.txt,sha256=JxjhFv0TRFvmE4KlZrJMq9F65YkIx9TodmCSOO5Mzvo,10
+waveguardclient-2.0.0.dist-info/RECORD,,

waveguardclient-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

waveguardclient-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Greg Partin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

waveguardclient-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+waveguard