Metadata-Version: 2.4
Name: faceapi-client
Version: 1.0.0
Summary: Official Python SDK for the FaceAPI — privacy-first face recognition
Author-email: zeinvob <minhajuli958@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://face-recognition-api-om7k.onrender.com/portal/
Project-URL: Documentation, https://face-recognition-api-om7k.onrender.com/docs/
Project-URL: Repository, https://github.com/zeinvob/face-recognition-api
Keywords: face-recognition,biometrics,api,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# FaceAPI Python SDK

Official Python client for the [FaceAPI](https://face-recognition-api-om7k.onrender.com/portal/) — privacy-first face recognition.

## Install

```bash
pip install faceapi-client
```

Or directly from GitHub:
```bash
pip install git+https://github.com/zeinvob/face-recognition-api.git#subdirectory=sdk
```

## Quick Start

```python
from faceapi import FaceAPIClient

client = FaceAPIClient(api_key="fk_live_your_key_here")
```

Get your free API key at: https://face-recognition-api-om7k.onrender.com/portal/

---

## Enroll a Face

```python
import face_recognition

# Extract descriptor from an image (client-side — no photo sent to API)
image      = face_recognition.load_image_file("photo.jpg")
descriptor = face_recognition.face_encodings(image)[0].tolist()

result = client.enroll(
    descriptor=descriptor,
    label="john_doe",           # optional
    collection_id="my_app",     # optional namespace
)

print(result.face_id)    # store this in your database
print(result.enrolled)   # True = new, False = updated existing
```

---

## Verify a Face (1:1)

```python
result = client.verify(
    descriptor=descriptor,   # freshly captured
    face_id="<stored_face_id>",
)

if result.verified:
    print(f"Identity confirmed! Confidence: {result.confidence:.0%}")
else:
    print("Face does not match")
```

---

## Identify a Face (1:N — Who Is This?)

```python
result = client.identify(
    descriptor=descriptor,
    collection_id="my_app",   # search only this namespace
)

if result.identified:
    print(f"Hello, {result.label}! Confidence: {result.confidence:.0%}")
else:
    print("Unknown person")
```

---

## List Enrolled Faces

```python
faces = client.list_faces(collection_id="my_app")
print(f"Total enrolled: {faces.count}")
for face in faces.faces:
    print(face.face_id, face.label, face.enrolled_at)
```

---

## Delete a Face

```python
client.delete_face(face_id="<face_id>")
```

---

## GDPR Purge

```python
# Delete all faces for one user (collection)
result = client.purge(collection_id="user_123")
print(f"Deleted {result.deleted_count} faces")

# Delete everything for your API key
result = client.purge()
```

---

## Check Usage

```python
stats = client.usage()
print(f"Tier: {stats.tier}")
print(f"Used today: {stats.used_today} / {stats.daily_limit or 'unlimited'}")
print(f"Total requests: {stats.total_requests}")
```

---

## Error Handling

```python
from faceapi import (
    FaceAPIClient,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

try:
    result = client.verify(descriptor=descriptor, face_id=face_id)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited: {e}")
except NotFoundError:
    print("face_id not found")
```

---

## Full Attendance System Example

```python
import face_recognition
from faceapi import FaceAPIClient

client = FaceAPIClient(api_key="fk_live_your_key_here")

def enroll_employee(photo_path: str, employee_id: str) -> str:
    image      = face_recognition.load_image_file(photo_path)
    descriptor = face_recognition.face_encodings(image)[0].tolist()
    result     = client.enroll(descriptor=descriptor, label=employee_id, collection_id="employees")
    return result.face_id

def clock_in(photo_path: str):
    image      = face_recognition.load_image_file(photo_path)
    descriptor = face_recognition.face_encodings(image)[0].tolist()
    result     = client.identify(descriptor=descriptor, collection_id="employees")

    if result.identified:
        print(f"Welcome, {result.label}! Clocked in. (confidence: {result.confidence:.0%})")
    else:
        print("Face not recognized. Access denied.")

# Enroll once
enroll_employee("john.jpg", "EMP001")

# Identify on every clock-in
clock_in("camera_frame.jpg")
```
