Update README.md

README.md

@@ -1,229 +1,238 @@
-# 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`
+---
+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