Metadata-Version: 2.3
Name: velix-sdk
Version: 0.1.0a1
Summary: Official Python SDK for VELIX Biometrics — facial access control platform
Project-URL: Homepage, https://velixbiometrics.com
Project-URL: Repository, https://github.com/VELIX-Biometrics/sdk-velix-python
Author-email: VELIX Biometrics <sdk@velixbiometrics.com>
License: MIT
License-File: LICENSE
Keywords: access-control,biometrics,facial-recognition,velix
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.13,>=3.11
Requires-Dist: httpx==0.27.2
Provides-Extra: dev
Requires-Dist: mypy==1.11.1; extra == 'dev'
Requires-Dist: pytest-asyncio==0.23.8; extra == 'dev'
Requires-Dist: pytest==8.3.2; extra == 'dev'
Requires-Dist: respx==0.21.1; extra == 'dev'
Requires-Dist: ruff==0.5.7; extra == 'dev'
Description-Content-Type: text/markdown

# velix-sdk — Python SDK ![version](https://img.shields.io/badge/version-0.1.0a1-orange)

> ⚠️ **Alpha / pre-release.** This SDK targets the real API-key surface implemented in
> api-velix-identity-core under `/v1/api/*` (see `lib-velix-contracts/openapi/public-api.yaml`,
> task #593/#656). Only 6 endpoints exist today. Do not use in production integrations yet.

Official Python SDK for the VELIX Biometrics platform — facial access control B2B SaaS.

## Requirements

- Python 3.11 or 3.12 (3.14 is not supported — `onnxruntime` has no wheel)

## Installation

```bash
pip install velix-sdk
```

## Quick Start

```python
from velix import VelixClient
from velix.modules.checkin import CheckinModule

with VelixClient(api_url="https://api.velixbiometrics.com", api_key="vlx_...") as client:
    result = CheckinModule(client).identify(image_base64=frame_base64)
    print(result["matched"])  # True | False
```

Auth: `x-api-key: vlx_<hex>` header (alternative: `Authorization: Bearer vlx_<hex>`).
Default client timeout is 30s, overridable via `VelixClient(..., timeout=...)`.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `VELIX_API_URL` | Yes | API base URL (`https://api.velixbiometrics.com`) |
| `VELIX_API_KEY` | Yes | API key (`vlx_...`) |

```python
import os
from velix import VelixClient

client = VelixClient(
    api_url=os.environ["VELIX_API_URL"],
    api_key=os.environ["VELIX_API_KEY"],
)
```

## Modules

| Module | Methods | Endpoint |
|--------|---------|----------|
| `OnboardingModule` | `enroll()` | `POST /v1/api/onboarding` (scope `onboarding:write`) |
| `CheckinModule` | `identify()` | `POST /v1/api/checkin/identify` (scope `checkin:write`) |
| `LgpdModule` | `request_deletion()` | `POST /v1/api/deletion-request` (scope `lgpd:write`) |
| `MeModule` | `get()` | `GET /v1/api/me/{personId}` (scope `me:read`) |
| `EventsModule` | `create_guest()`, `get_guest()` | `POST/GET /v1/api/events/{id}/guests[/{guestId}]` (scopes `events:write`/`events:read`) |
| `PersonsModule` | — | **not implemented** — no such endpoint under `/v1/api/*`; raises `NotImplementedError` |
| `TenantsModule` | — | **not implemented** — no such endpoint under `/v1/api/*`; raises `NotImplementedError` |
| `TimeModule` | — | **not implemented** — identity-core has no proxy to api-velix-time yet (task #593, follow-up #616); raises `NotImplementedError` |

## Onboarding Module

```python
from velix.modules.onboarding import OnboardingModule

onboarding = OnboardingModule(client)
result = onboarding.enroll(
    name="João Silva",
    frames=[frame1_b64, frame2_b64, frame3_b64],
    email="joao@company.com",
    external_id="EMP-001",
)
# {"person_id": ..., "identity_id": ..., "enrolled": True, "frames_processed": 3, ...}
```

## Checkin Module

```python
from velix.modules.checkin import CheckinModule

checkin = CheckinModule(client)

result = checkin.identify(image_base64=frame_base64)
# {"matched": True, "person_id": "uuid", "quality_score": 0.92, "message": "..."}

# With liveness challenge (token from the public HMAC endpoint) and GPS
result = checkin.identify(
    image_base64=frame_base64,
    liveness={"token": nonce, "samples": [{"action": "center", "imageBase64": sample_b64}]},
    latitude=-23.5, longitude=-46.6, accuracy=10.0,
)
```

Liveness score is never returned by the API — only `matched`/`passed` booleans.

## LGPD Module

```python
from velix.modules.lgpd import LgpdModule

result = LgpdModule(client).request_deletion(person_id="uuid")
# {"protocol_number": "...", "message": "..."}
```

## Me Module

```python
from velix.modules.me import MeModule

me = MeModule(client).get(person_id="uuid")
# {"id": ..., "name": ..., "email": ..., "phone": ..., "photo_url": ..., "created_at": ...}
```

## Events Module

```python
from velix.modules.events import EventsModule

events = EventsModule(client)

guest = events.create_guest("event-uuid", name="Jane Doe", email="jane@company.com")
# {"id": ..., "eventId": ..., "name": ..., "email": ..., "status": ..., "categoryId": ...}

guest = events.get_guest("event-uuid", "guest-uuid")
```

## Error Handling

```python
from velix.exceptions import VelixAuthError, VelixNotFoundError, VelixRateLimitError, VelixAPIError

try:
    result = checkin.identify(image_base64=frame)
except VelixAuthError:
    print("Invalid API key")
except VelixNotFoundError as e:
    print(f"Not found: {e}")
except VelixRateLimitError as e:
    print("Rate limited")
except VelixAPIError as e:
    print(f"HTTP {e.status_code}: {e.message}")
```

## Running Tests

```bash
pip install -e ".[dev]"
pytest
pytest -v --tb=short     # verbose
pytest --cov=velix       # with coverage
```

Tests run with a mock HTTP server — no running service required.

## Local Development

```bash
git clone <repo>
pip install -e ".[dev]"
pytest
```

## Get an API Key

Access the dashboard at **velixbiometrics.com** → Settings → API Keys → New Key.
