Spaces:
Build error
Download README.md from jinksQspider/fmproService: direct link, hf CLI and curl.
- Browser
- Download file 14.6 kB
-
https://huggingface.co/spaces/jinksQspider/fmproService/resolve/main/README.md
- Command line
-
hf download hf://spaces/jinksQspider/fmproService/README.md
-
curl -L -o README.md https://huggingface.co/spaces/jinksQspider/fmproService/resolve/main/README.md
title: FMPro Service
emoji: π€
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
Face Inference SaaS Platform
A production-grade multi-tenant face recognition API platform built with FastAPI, InsightFace, and MySQL.
UI Preview
The current frontend runs at http://localhost:3000.
Screens
- Dashboard:
http://localhost:3000/dashboard - Billing and payment settings:
http://localhost:3000/billing - Product docs:
http://localhost:3000/docs
Notes
- The dashboard uses a compact profile menu for docs, billing, API keys, admin access, and logout.
- Billing is usage-based today: API calls and successful recognitions are metered per tenant and user.
- The billing page stores payment preferences locally for now and is ready to be connected to a real payment provider later.
π― Features
Core Capabilities
- Multi-tenant Architecture: Complete data isolation between customers
- Face Registration: Register faces from exactly 3 single-person, different-angle images
- Face Recognition: Real-time face recognition from single frames or video streams
- Secure APIs: JWT authentication with role-based access control
- Scalable: Designed for horizontal scaling with Docker & Kubernetes
Security
- Multi-tenant data isolation at database level
- JWT access & refresh tokens
- Role-based access control (ADMIN/USER)
- Encrypted embeddings
- Rate limiting & request validation
- CORS protection
Advanced Features
- Face quality validation
- Duplicate face detection
- Recognition confidence scores
- Bounding box detection
- Analytics & monitoring
- Admin dashboard capabilities
ποΈ Architecture
βββ app/
β βββ main.py # FastAPI application entry
β βββ core/ # Core configuration & security
β β βββ config.py # Settings & environment
β β βββ database.py # SQLAlchemy & session management
β β βββ security.py # JWT & authentication utilities
β β βββ middleware.py # Multi-tenant middleware
β βββ models/ # SQLAlchemy ORM models
β β βββ __init__.py # Tenant, User, FaceEmbedding, etc.
β βββ schemas/ # Pydantic request/response schemas
β βββ services/ # Business logic
β β βββ auth_service.py
β β βββ recognition_service.py
β βββ api/ # API routes
β β βββ auth_routes.py
β β βββ face_routes.py
β β βββ admin_routes.py
β βββ utils/ # Utilities
β βββ common.py # Image processing, face detection
βββ docker-compose.yml # Local development stack
βββ Dockerfile # Multi-stage production build
βββ requirements.txt # Python dependencies
βββ .env.example # Environment template
π Quick Start
Prerequisites
- Docker & Docker Compose (recommended)
- Python 3.11+ (for local development)
- MySQL 8+
- Redis 7+
Option 1: Docker Compose (Recommended)
# Clone the repository
git clone <repository-url>
cd fmproService
# Copy environment template
cp .env.example .env
# Start all services
docker-compose up -d
# Check service health
curl http://localhost/health
# View API docs
open http://localhost/docs
This starts:
- MySQL database
- Redis cache
- MinIO S3 storage
- FastAPI backend
- Nginx reverse proxy
Option 2: Local Development
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env with your local database URL
# Run migrations
alembic upgrade head
# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# API docs available at: http://localhost:8000/docs
π‘ API Endpoints
Authentication
POST /api/auth/register- Register new user & tenantPOST /api/auth/login- Login (JWT)POST /api/auth/refresh- Refresh access tokenGET /api/auth/me- Get current user
Face Operations
POST /api/face/register- Register face from exactly 3 images & generate detailed embeddingPOST /api/face/recognize- Recognize faces in imageGET /api/face/embeddings- List registered embeddingsGET /api/face/logs- Get recognition logsDELETE /api/face/embeddings/{embedding_id}- Delete embedding
Admin
GET /api/admin/analytics- Platform analyticsGET /api/admin/users- List all usersDELETE /api/admin/users/{user_id}- Delete userPOST /api/admin/api-keys- Create third-party API key
Third-Party API
POST /api/v1/faces/register- Register face withX-API-KeyPOST /api/v1/faces/recognize- Recognize faces withX-API-Key
Billing and Payments
Billing is currently usage-metered and exposed in the admin APIs and the frontend billing page.
GET /api/admin/usage?period=YYYY-MM- Get monthly usage for the tenantsuccessful_recognitions- Counted when a recognition matches a known faceapi_calls- Counted on each face register and recognize request
The frontend billing page is available at:
http://localhost:3000/billing
It includes:
- billing profile fields
- payment method label
- invoice address
- auto-renew toggle
- monthly usage summary for admins
UI Screenshots
Use these live routes as the source of the current screenshots when capturing the UI for documentation:
http://localhost:3000/dashboard
http://localhost:3000/billing
http://localhost:3000/docs
Recommended capture list:
- Dashboard header and profile menu
- Billing settings page
- Docs page billing section
π Authentication Flow
Register: Create tenant & user account
curl -X POST http://localhost:8000/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "user@company.com", "password": "SecurePassword123", "full_name": "John Doe" }'Login: Get access token
curl -X POST http://localhost:8000/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "user@company.com", "password": "SecurePassword123" }'Use Token: Access protected endpoints
curl -X GET http://localhost:8000/api/auth/me \ -H "Authorization: Bearer {access_token}"
π€ Face Registration Example
Strict rules:
- exactly 3 images
- one person per frame
- no duplicate images
- 3 different detected face angles
- one detailed normalized embedding stored
curl -X POST http://localhost:8000/api/face/register \
-H "Authorization: Bearer {access_token}" \
-F "person_id=EMP001" \
-F "name=John Doe" \
-F "images=@/path/to/front.jpg" \
-F "images=@/path/to/left.jpg" \
-F "images=@/path/to/right.jpg" \
-F "metadata={\"department\": \"Engineering\"}"
π― Face Recognition Example
curl -X POST http://localhost:8000/api/face/recognize \
-H "Authorization: Bearer {access_token}" \
-F "image=@/path/to/test_frame.jpg" \
-F "threshold=0.5" \
-F "return_bboxes=true"
Response:
{
"faces_detected": 2,
"recognized": [
{
"person_id": "EMP001",
"name": "John Doe",
"confidence": 0.96,
"bbox": [100, 200, 300, 400],
"embedding_id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"unrecognized_count": 1,
"processing_time_ms": 145.23
}
Third-Party API Integration
Third-party clients use X-API-Key, not JWT. Create key from admin account first.
1. Login As Admin
curl -X POST http://localhost:8000/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@fmproject.dev",
"password": "Admin@123456"
}'
Copy access_token.
2. Create API Key
curl -X POST http://localhost:8000/api/admin/api-keys \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"key_name": "partner-app"
}'
Response includes api_key. Save it now. It is returned once.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"key_name": "partner-app",
"is_active": true,
"created_at": "2026-05-07T10:00:00",
"last_used_at": null,
"api_key": "fmp_generated_secret_key"
}
3. Register Face From Third-Party App
curl -X POST http://localhost:8000/api/v1/faces/register \
-H "X-API-Key: {api_key}" \
-F "person_id=EMP001" \
-F "name=John Doe" \
-F "images=@/path/to/front.jpg" \
-F "images=@/path/to/left.jpg" \
-F "images=@/path/to/right.jpg" \
-F "metadata={\"source\":\"partner-app\"}"
4. Recognize Face From Third-Party App
curl -X POST http://localhost:8000/api/v1/faces/recognize \
-H "X-API-Key: {api_key}" \
-F "image=@/path/to/test_frame.jpg" \
-F "threshold=0.5" \
-F "return_bboxes=true"
Third-party API uses tenant attached to API key. Recognition logs use source third_party_api.
π‘οΈ Multi-Tenant Isolation
The system ensures strict data isolation:
- JWT Validation: Every request validated with tenant_id
- Query Filtering: All database queries filtered by tenant_id
- Middleware: Custom middleware enforces tenant context
- Database Level: Foreign keys prevent cross-tenant access
# Example: Only tenant's embeddings are loaded
embeddings = db.query(FaceEmbedding).filter(
FaceEmbedding.tenant_id == current_tenant_id
).all()
π Database Schema
Tables
- tenants: Customer organizations
- users: Tenant members (admin, user roles)
- face_embeddings: Stored face vectors & metadata
- recognition_logs: Audit trail of recognitions
- api_keys: For programmatic access
All tables include:
tenant_idfor multi-tenant isolation- Appropriate indexes for performance
- Timestamps for audit
π§ Configuration
Environment variables (see .env.example):
# Database
DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/fmproject_db
# JWT
SECRET_KEY=your-secret-key-min-32-chars
ACCESS_TOKEN_EXPIRE_MINUTES=30
# Face Recognition
INSIGHTFACE_MODEL=buffalo_l # buffalo_l, buffalo_s, etc.
INSIGHTFACE_GPU=False
FACE_RECOGNITION_THRESHOLD=0.5
# S3 Storage
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=face-embeddings
# Security
CORS_ORIGINS=["http://localhost:3000"]
RATE_LIMIT_PER_MINUTE=100
π¦ Deployment
Docker Compose (Development)
docker-compose up -d
Docker Production
docker build -t fmproject-backend:latest .
docker run -d \
-e DATABASE_URL=mysql+pymysql://... \
-e SECRET_KEY=your-key \
-p 8000:8000 \
fmproject-backend:latest
Kubernetes
See k8s/ directory for Kubernetes manifests (helm charts, deployments, services).
π Performance
- Recognition Latency: < 500ms per frame
- Throughput: 100+ concurrent users
- Embedding Storage: Optimized with binary format
- Caching: Redis for frequently accessed embeddings
π§ͺ Testing
# Run tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=app
π Database Migrations
# Create migration
alembic revision --autogenerate -m "Add new table"
# Apply migrations
alembic upgrade head
# Rollback
alembic downgrade -1
π€ Contributing
- Fork repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
π License
MIT License - see LICENSE file for details
π Support
- Documentation:
/docs(interactive API docs) - Issues: GitHub Issues
- Email: support@fmproject.com
πΊοΈ Roadmap
- WebSocket support for real-time recognition
- Face clustering & grouping
- Liveness detection
- Webhooks for events
- Advanced analytics dashboard
- Face search API
- Batch processing
- GPU acceleration
- Multi-modal search
Built with β€οΈ using FastAPI, InsightFace, and MySQL
- Name:
face-inference-service - Space SDK: Docker
- License: MIT
Upload files to the space:
Dockerfilerequirements.txtapp.pyREADME.md(this file)
Wait for auto-build (2-5 minutes). Space URL will be something like:
https://your-username-face-inference-service.hf.space
Option 2: Direct Python (if you prefer)
Create a app.py with the FastAPI code and add to a Python space type.
API Endpoints
Health Check
GET /health
Response:
{
"status": "healthy",
"service": "face-inference"
}
Recognize Faces in Frame
POST /recognize
Content-Type: application/x-www-form-urlencoded
Parameters:
- frame_data: Base64-encoded JPEG image
- known_encodings: JSON string with {"encodings": [...], "metadata": [...]}
- tolerance: float (default 0.85)
Response:
{
"success": true,
"recognized": [
{
"roll_no": "CS001",
"name": "John Doe",
"distance": 0.73
}
],
"count": 1,
"faces_detected": 1
}
Get Embedding from Image
POST /get_embedding
Content-Type: application/x-www-form-urlencoded
Parameters:
- image_data: Base64-encoded JPEG image
Response:
{
"success": true,
"embedding": [0.1, 0.2, ...],
"faces_detected": 1
}
Usage in Main App
See ../app/utils/inference_client.py for integration example.
Performance Notes
- First request will be slow (~30-60s) if Space was idle.
- Paid HF Spaces tier keeps service always-on.
- Free tier may spin down after inactivity.
Environment Variables
FACE_RECOGNITION_MODEL: Model name (default: "buffalo_l")PORT: Service port (default: 7860)