Metadata-Version: 2.4
Name: voiceidvault
Version: 1.1.0
Summary: VoiceIDVault Python SDK — voice biometric authentication
Home-page: https://voiceidvault.com
License: MIT
Project-URL: Homepage, https://voiceidvault.com
Project-URL: Repository, https://github.com/voiceidvault/voiceidvault
Keywords: voice-authentication,biometrics,voice-id,passwordless
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Dynamic: home-page
Dynamic: requires-python

# voiceidvault

VoiceIDVault Python SDK — voice biometric authentication.

## Installation

```bash
pip install voiceidvault
```

## Quick start

```python
from voiceidvault import VoiceIDVaultClient

client = VoiceIDVaultClient(api_key="your-api-key")

# ── 1. Enroll a new user ──────────────────────────────────────────────────────
session = client.init_enrollment("user-123", "+12125551234")

# User receives an SMS — collect the code and verify
sms_result = client.verify_sms_otp(session.session_id, "user-123", "654321")
print("SMS verified:", sms_result.verified, "next step:", sms_result.next_step)

# Enroll face
with open("face.jpg", "rb") as f:
    face_result = client.enroll_face(session.session_id, "user-123", f.read())
print("Face enrolled, liveness score:", face_result.liveness_score)

# Enroll voice
with open("voice.wav", "rb") as f:
    voice_result = client.enroll_voice(
        session.session_id, "user-123", f.read(),
        phrase="my voice is my password",
        duration=5,
    )
print("Voice quality score:", voice_result.quality_score)

# Complete enrollment
result = client.complete_enrollment(session.session_id, "user-123")
print("Vault ID:", result.vault_id)
print("Trust score:", result.trust_score)

# ── 2. Authenticate ───────────────────────────────────────────────────────────
with open("voice.wav", "rb") as f:
    auth = client.authenticate_voice(
        f.read(),
        user_id="user-123",        # optional — omit for open-set search
        confidence_threshold=0.85,
    )

if auth.verified:
    print("Authenticated! Confidence:", auth.confidence)
    print("Identity:", auth.identity.user_id if auth.identity else "unknown")
else:
    analysis = auth.deepfake_analysis
    if analysis and not analysis.passed:
        print("Deepfake detected, confidence:", analysis.confidence)

# ── 3. GDPR right-to-erasure ──────────────────────────────────────────────────
deletion = client.request_deletion("erasure", reason="Account closure")
print("Deletion deadline:", deletion.request.response_deadline)
print("Next steps:", deletion.next_steps)
```

## Context manager

```python
with VoiceIDVaultClient(api_key="your-api-key") as client:
    auth = client.authenticate_voice(audio_bytes)
    print(auth.verified)
```

## Error handling

```python
from voiceidvault import (
    VoiceIDVaultClient,
    AuthenticationError,
    EnrollmentError,
    RateLimitError,
    NetworkError,
)

try:
    result = client.enroll_voice(session_id, user_id, audio_bytes)
except AuthenticationError as e:
    print("Invalid API key:", e)
except EnrollmentError as e:
    print(f"Enrollment failed [{e.code}]:", e)
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except NetworkError as e:
    print("Network failure:", e)
```

## Configuration

| Parameter  | Default                    | Description                           |
|------------|----------------------------|---------------------------------------|
| `api_key`  | **required**               | Your VoiceIDVault API key             |
| `base_url` | `https://voiceidvault.com` | Override the API base URL             |
| `timeout`  | `30`                       | Request timeout in seconds            |
| `retries`  | `3`                        | Retry attempts for 5xx / timeouts     |

## License

MIT
