Metadata-Version: 2.4
Name: subphase
Version: 0.1.0
Summary: Detect adversarial audio attacks that hijack AI voice assistants.
Author: Nour Habib
License: MIT
Project-URL: Homepage, https://subphase.ai
Keywords: audio,security,adversarial,voice,asr
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Dynamic: license-file

# Subphase

Detect adversarial audio attacks — inaudible perturbations hidden in ordinary
audio that hijack AI voice assistants.

```bash
pip install subphase
```

## Quickstart

```python
from subphase import Subphase

client = Subphase(api_key="sk_...")      # or set SUBPHASE_API_KEY
result = client.scan("voice-note.wav")
print(result["status"])                  # "clean" or "threat"
print(result["confidence"])              # 0.0 – 1.0
```

## Two detectors

Both run on Subphase's servers; this client just sends the audio. Every scan
needs an API key — the free tier key costs nothing and takes a minute to
generate.

| Model | Key | Notes |
|-------|-----|-------|
| `heuristic` (default) | free tier | free, DSP-based |
| `cnn` | Developer+ | learned ensemble, higher accuracy |

```python
# Free tier — free key:
client = Subphase(api_key="sk_...")
client.scan("audio.wav")                         # model="heuristic" (default)

# Paid — needs a Developer+ key:
client = Subphase(api_key="sk_dev_...")
client.scan("audio.wav", model="cnn")
```

## Authentication

Both detectors need an API key. Pass it directly or set an environment
variable:

```python
client = Subphase(api_key="sk_dev_...")
```
```bash
export SUBPHASE_API_KEY="sk_dev_..."
```

Get a key at <https://subphase.ai/keys>. Free-tier keys are free to generate.
Keys are shown once — store them securely.

## Input formats

`scan()` accepts a file path, raw `bytes`, or a file-like object:

```python
client.scan("audio.wav")
client.scan(open("audio.wav", "rb").read())
client.scan(open("audio.wav", "rb"))
```

## Response

```python
{
    "status": "threat",              # or "clean"
    "confidence": 0.82,              # 0.0 – 1.0
    "threat_type": "adversarial_perturbation",
    "signals": {...},                # per-signal / per-model scores
    "model": "cnn_ensemble",         # or "heuristic"
    "plan": "developer",
    "quota_remaining": 49998,        # CNN only
}
```

## Errors

```python
from subphase import (
    AuthenticationError,   # missing / invalid / revoked key
    PlanError,             # your plan doesn't include this feature
    QuotaExceededError,    # monthly scan quota used up
    SubphaseError,         # base class
)

try:
    client.scan("audio.wav", model="cnn")
except QuotaExceededError:
    ...  # upgrade or wait for the monthly reset
```

## Plans

| Plan | Price | Scans / mo | Detector |
|------|-------|-----------|----------|
| Free | $0 | unlimited | heuristic (hosted), free key required |
| Developer | $49 | 50,000 | + CNN, basic logs |
| Pro | $199 | 500,000 | + audit logs, webhooks, dashboard |
| Enterprise | custom | unlimited | + SLA, SSO, custom tuning |

## Configuration

| Argument | Env var | Default |
|----------|---------|---------|
| `api_key` | `SUBPHASE_API_KEY` | — |
| `base_url` | `SUBPHASE_BASE_URL` | hosted gateway |
| `timeout` | — | 30s |

Point `base_url` at a self-hosted gateway for on-prem deployments.
