README.md

---
title: FaceMatch Azure Dev
emoji: 🐨
colorFrom: red
colorTo: green
sdk: docker
pinned: false
---

# FaceMatch FastAPI

A face matching and recommendation system built with FastAPI, InsightFace, and Azure Blob Storage. This application provides personalized face recommendations based on user preferences and similarity matching.

## Features

- **Face Detection & Embedding**: Uses InsightFace for robust face detection and embedding extraction
- **Similarity Matching**: Finds similar faces using cosine similarity on face embeddings
- **Personalized Recommendations**: Learns from user likes/dislikes to provide personalized matches
- **Gender Filtering**: Filter recommendations by gender (male, female, or all)
- **Azure Integration**: Stores images and embeddings in Azure Blob Storage
- **FastAPI**: Modern, fast web framework with automatic API documentation

## API Endpoints

### Core Endpoints

- `GET /` - Health check and welcome message
- `POST /api/init_user` - Initialize a new user session
- `GET /api/get_training_images` - Get training images for user preference learning
- `POST /api/record_preference` - Record user like/dislike preferences
- `POST /api/get_matches` - Get personalized matches based on user preferences
- `POST /api/get_recommendations` - Get recommendations based on query images
- `POST /api/extract_embeddings` - Extract embeddings from all images (admin)

### API Documentation

Visit `/docs` for interactive Swagger UI documentation when running locally.

## Local Setup

### Prerequisites

- Python 3.8+
- Azure Blob Storage account
- Azure credentials

### Installation

1. **Clone the repository**
   ```bash
   git clone <your-repo-url>
   cd Facematch_Dev
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure Azure credentials**
   
   Set your Azure credentials as environment variables:
   ```bash
   export AZURE_STORAGE_CONNECTION_STRING="your_connection_string"
   export AZURE_CONTAINER_NAME="your_container_name"
   ```
   
   Or create a `config.py` file with your credentials.

4. **Run the application**
   ```bash
   python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
   ```

5. **Access the API**
   - API: http://localhost:8000
   - Documentation: http://localhost:8000/docs

## Usage Examples

### Get Recommendations

**Direct Format:**
```bash
curl -X POST "http://localhost:8000/api/get_recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "query_images": [
      "https://your-azure-url/image1.jpg",
      "https://your-azure-url/image2.jpg"
    ],
    "gender": "female",
    "top_n": 5
  }'
```

**Hugging Face Format:**
```bash
curl -X POST "http://localhost:8000/api/get_recommendations" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "query_images": [
        "https://your-azure-url/image1.jpg",
        "https://your-azure-url/image2.jpg"
      ],
      "gender": "female",
      "top_n": 5
    }
  }'
```

### Initialize User Session
```bash
curl -X POST "http://localhost:8000/api/init_user"
```

### Record Preferences
```bash
curl -X POST "http://localhost:8000/api/record_preference" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "your_user_id",
    "image_url": "https://your-azure-url/image.jpg",
    "preference": "like"
  }'
```

## Hugging Face Spaces Deployment

### 1. Create a Hugging Face Space

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Choose "FastAPI" as the SDK
4. Set visibility (public or private)
5. Create the space

### 2. Configure Secrets

In your Hugging Face Space settings, add these secrets:

- `AZURE_STORAGE_CONNECTION_STRING`: Your Azure connection string
- `AZURE_CONTAINER_NAME`: Your Azure container name

### 3. Upload Files

Upload these files to your Hugging Face Space:

- `main.py` - FastAPI application
- `handler.py` - Face matching logic
- `requirements.txt` - Dependencies
- `config.py` - Configuration (if using file-based config)

### 4. Deploy

The space will automatically build and deploy your FastAPI application.

### 5. Access Your API

Your API will be available at:
```
https://your-username-your-space-name.hf.space
```

## Azure Setup

### Required Azure Resources

1. **Storage Account**: For storing images and embeddings
2. **Blob Container**: Organized with folders:
   - `ai-images/men/` - Training images for men
   - `ai-images/women/` - Training images for women
   - `profile-media/` - Images to search for matches

### Configuration

The application expects these Azure settings:

```python
# In config.py or environment variables
AZURE_STORAGE_CONNECTION_STRING = "your_connection_string"
AZURE_CONTAINER_NAME = "your_container_name"
```

## File Structure

```
Facematch_Dev/
├── main.py                 # FastAPI application
├── handler.py              # Face matching logic
├── config.py               # Configuration
├── requirements.txt        # Dependencies
├── README.md              # This file
├── templates/             # HTML templates (if needed)
└── user_preferences.json  # User preferences storage
```

## Performance Notes

- **Local Development**: Runs on CPU, suitable for testing
- **Hugging Face Spaces**: Runs on GPU, much faster for production
- **Embedding Extraction**: Run `/api/extract_embeddings` after uploading new images
- **Caching**: Embeddings are cached in Azure for faster subsequent queries

## Troubleshooting

### Common Issues

1. **Face Detection Fails**: Some images may not contain detectable faces
2. **Azure Connection**: Ensure credentials are correctly set
3. **Memory Issues**: Large image collections may require more memory on Hugging Face

### Debug Mode

Enable debug logging by setting environment variable:
```bash
export DEBUG=1
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

[Add your license information here]

## Support

For issues and questions:
- Create an issue on GitHub
- Check the API documentation at `/docs`
- Review the debug logs for detailed error information