Spaces:
Build error
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
14.6 kB
| 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) | |
| ```bash | |
| # 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 | |
| ```bash | |
| # 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 & tenant | |
| - `POST /api/auth/login` - Login (JWT) | |
| - `POST /api/auth/refresh` - Refresh access token | |
| - `GET /api/auth/me` - Get current user | |
| ### Face Operations | |
| - `POST /api/face/register` - Register face from exactly 3 images & generate detailed embedding | |
| - `POST /api/face/recognize` - Recognize faces in image | |
| - `GET /api/face/embeddings` - List registered embeddings | |
| - `GET /api/face/logs` - Get recognition logs | |
| - `DELETE /api/face/embeddings/{embedding_id}` - Delete embedding | |
| ### Admin | |
| - `GET /api/admin/analytics` - Platform analytics | |
| - `GET /api/admin/users` - List all users | |
| - `DELETE /api/admin/users/{user_id}` - Delete user | |
| - `POST /api/admin/api-keys` - Create third-party API key | |
| ### Third-Party API | |
| - `POST /api/v1/faces/register` - Register face with `X-API-Key` | |
| - `POST /api/v1/faces/recognize` - Recognize faces with `X-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 tenant | |
| - `successful_recognitions` - Counted when a recognition matches a known face | |
| - `api_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: | |
| ```text | |
| 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 | |
| 1. **Register**: Create tenant & user account | |
| ```bash | |
| 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" | |
| }' | |
| ``` | |
| 2. **Login**: Get access token | |
| ```bash | |
| curl -X POST http://localhost:8000/api/auth/login \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "email": "user@company.com", | |
| "password": "SecurePassword123" | |
| }' | |
| ``` | |
| 3. **Use Token**: Access protected endpoints | |
| ```bash | |
| 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 | |
| ```bash | |
| 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 | |
| ```bash | |
| 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: | |
| ```json | |
| { | |
| "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 | |
| ```bash | |
| 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 | |
| ```bash | |
| 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. | |
| ```json | |
| { | |
| "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 | |
| ```bash | |
| 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 | |
| ```bash | |
| 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: | |
| 1. **JWT Validation**: Every request validated with tenant_id | |
| 2. **Query Filtering**: All database queries filtered by tenant_id | |
| 3. **Middleware**: Custom middleware enforces tenant context | |
| 4. **Database Level**: Foreign keys prevent cross-tenant access | |
| ```python | |
| # 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_id` for multi-tenant isolation | |
| - Appropriate indexes for performance | |
| - Timestamps for audit | |
| ## π§ Configuration | |
| Environment variables (see `.env.example`): | |
| ```bash | |
| # 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) | |
| ```bash | |
| docker-compose up -d | |
| ``` | |
| ### Docker Production | |
| ```bash | |
| 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 | |
| ```bash | |
| # Run tests | |
| pytest tests/ -v | |
| # Run with coverage | |
| pytest tests/ --cov=app | |
| ``` | |
| ## π Database Migrations | |
| ```bash | |
| # Create migration | |
| alembic revision --autogenerate -m "Add new table" | |
| # Apply migrations | |
| alembic upgrade head | |
| # Rollback | |
| alembic downgrade -1 | |
| ``` | |
| ## π€ Contributing | |
| 1. Fork repository | |
| 2. Create feature branch (`git checkout -b feature/amazing-feature`) | |
| 3. Commit changes (`git commit -m 'Add amazing feature'`) | |
| 4. Push to branch (`git push origin feature/amazing-feature`) | |
| 5. 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 | |
| 2. Upload files to the space: | |
| - `Dockerfile` | |
| - `requirements.txt` | |
| - `app.py` | |
| - `README.md` (this file) | |
| 3. 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: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| { | |
| "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) | |