README.md

---
title: ML Services
emoji: 💍
colorFrom: pink
colorTo: red
sdk: docker
pinned: false
---

# 💍 Soul Mate Matchmaking API

AI-powered partner recommendation using Supabase data and scikit-learn.

---

## 🎯 What It Does

1. Takes a **user ID (UID)** as input
2. Fetches user profile from **Supabase**
3. Compares with opposite-gender profiles using ML model
4. Returns **top compatible matches** (0-100% score)

---

## 🚀 API Endpoint

### `GET /recommend/{user_id}`

Get AI-matched partners for a user.

**Query Parameters:**
- `top_n` (optional, default=10): number of matches to return

**Response:**
```json
{
  "matches": [
    {
      "user_id": "uuid-here",
      "name": "Fatima Ali",
      "age": 26,
      "city": "Karachi",
      "compatibility_score": 87.5,
      "photo_url": "https://..."
    }
  ]
}
```

**Example:**
```bash
curl http://127.0.0.1:7860/recommend/44d81ff7-93d2-4805-a973-df9a62a99cf2?top_n=5
```

---

### `POST /feedback`

Record a like/reject action on a match.

**Body:**
```json
{
  "user_id": "user-123",
  "target_id": "user-456",
  "action": "like"
}
```
`action`: `"like"` or `"reject"`

**Response:**
```json
{ "status": "ok" }
```

---

### `GET /health`

Check if model is loaded.
```json
{ "status": "running", "model": "loaded" }
```

---

## 🔧 Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Train model on Supabase data
python train.py

# Start server
python start.py
# or
uvicorn app:app --reload --port 7860
```

**Interactive docs:** http://localhost:7860/docs

---

## 🧠 Model Features

The model encodes **10 profile attributes**:

| Category | Columns |
|----------|---------|
| Numeric (1) | `age` |
| Categorical (6) | `religion`, `marital_status`, `qualification`, `country`, `maslak`, `region_caste` |
| Text (3) | `hobbies`, `personality_traits`, `preferred_partner_criteria` |

**Technique:**
- LabelEncoder for categoricals
- TF-IDF (max_features=20) for text fields
- MinMaxScaler for age
- Cosine similarity via NearestNeighbors

**Total feature dimensions:** 1 + 6 + (20×3) = **67 features**

---

## 🚢 Deployment to HuggingFace Spaces

```bash
# 1. Train locally first
python train.py

# 2. Clone your HF space
git clone https://huggingface.co/spaces/subhan971/ML-services
cd ML-services

# 3. Copy files
xcopy /s /y "D:\soulmate\soul_mate_app_flutter_backup\recommendation_service\*" ".\"

# 4. Ensure model exists
if not exist "models\recommendation_model.pkl" (
    echo Model missing! Run train.py first.
    exit /b 1
)

# 5. Setup LFS
git lfs track "*.pkl"
git add .gitattributes

# 6. Commit & push
git add .
git commit -m "deploy: matchmaking model"
git push origin main
```

**Space URL:** https://subhan971-ml-services.hf.space

---

## ⚙️ Environment Variables

| Variable | Description |
|----------|-------------|
| `SUPABASE_URL` | Your Supabase project URL |
| `SUPABASE_SERVICE_KEY` | Service role key (for read access) |
| `PORT` | Server port (default: 7860) |

Set **before** starting the server:
```bash
export SUPABASE_URL=https://xxxx.supabase.co
export SUPABASE_SERVICE_KEY=your-service-role-key
```

---

## 📊 Training Data

Model is trained on all **active profiles** from Supabase `profiles` table.

To retrain after adding new users:
```bash
python train.py
```

The script:
1. Fetches all active profiles from Supabase
2. Preprocesses features
3. Trains NearestNeighbors model
4. Saves to `models/recommendation_model.pkl`

---

## 🔄 Flutter Integration

Flutter calls:
```dart
final response = await dio.get(
  'https://subhan971-ml-services.hf.space/recommend/$userId',
  queryParameters: {'top_n': 10}
);
```

Matches are displayed with:
- Name
- Age
- City
- Compatibility % score
- Photo

---

## 📁 Project Structure

```
recommendation_service/
├── app.py              # FastAPI server (2 endpoints)
├── train.py            # Training script (Supabase → model)
├── requirements.txt    # Dependencies
├── Dockerfile          # HF Spaces container
├── start.py            # Launch with env vars
├── models/
│   └── recommendation_model.pkl  # Trained model
├── README.md
├── .gitignore
└── .gitattributes      # LFS tracking
```

---

## ✅ Requirements Met

- ✅ Fetch user data from Supabase using UID
- ✅ Preprocess: age, religion, preferred_partner_criteria, personality_traits, hobbies, qualification, marital_status, nationality, sect, region/caste, gender
- ✅ Train ML model (TF-IDF + LabelEncoder + NearestNeighbors)
- ✅ Save as `.pkl`
- ✅ Backend API: `/recommend/{user_id}` returns ranked matches
- ✅ Flutter integration: AI Match button → API → display results
- ✅ Only opposite-gender matches
- ✅ Compatibility score 0-100%

---

**Questions?** Check `/docs` when server is running.