fmproService / README.md
Hkoradiya123
chore: Update README metadata section with project details
4dba71d
|
Raw History Blame Contribute Delete
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)