README.md

---
title: REmatch
emoji: 🏠
colorFrom: blue
colorTo: yellow
sdk: gradio
sdk_version: 5.0.0
app_file: app.py
pinned: false
---

# REmatch

REmatch is an educational real-estate investment matching prototype.

The application converts a short free-text investor description into a probability-weighted structured profile, filters ineligible properties, ranks the remaining opportunities with a trained DCN-v2 recommendation model, and generates grounded explanations for the three selected properties.

## Live Application Flow

1. The user describes their investment preferences in up to three lines.
2. MPNet converts the description into a 768-dimensional text embedding.
3. Five supervised classifiers estimate probability distributions for budget level, financing willingness, liquidity importance, risk profile, and primary goal.
4. A dollar amount is extracted from the description. If none is present, the application asks one follow-up budget question.
5. The exact amount deterministically sets the categorical budget level.
6. Strict eligibility rules are applied:
   - properties above the exact budget are excluded;
   - conservative investors do not receive high-volatility or negative-forecast properties.
7. REmatch integrates DCN-v2 scores across the complete inferred profile distribution rather than collapsing the text to one profile too early.
8. A small deterministic tie-breaker uses yield, forecast, volatility, and budget headroom.
9. Saved DCN-v2 property embeddings are used with a small similarity penalty to reduce repetitive recommendations while preserving match quality.
10. Qwen generates a grounded explanation for each selected property.
11. The application displays up to three recommendations.

If no eligible property exists within the entered budget, the application clearly labels and displays the strongest matching alternatives outside that budget. The normal budget rule is not relaxed unless the strict run returns no results.

## Recommendation Model

The production recommender is **DCN-v2**.

It uses five investor-profile features inferred from the description:

- `budget_level`
- `financing_willingness`
- `liquidity_importance`
- `risk_profile`
- `primary_goal`

and five property-group features:

- `price_band`
- `yield_band`
- `liquidity_band`
- `volatility_band`
- `forecast_band`

Three tabular recommendation models were evaluated on the same held-out data:

| Model | MAE | RMSE | NDCG@3 |
|---|---:|---:|---:|
| DCN-v2 | 0.01418 | 0.02085 | 0.99991 |
| TabTransformer | 0.01433 | 0.01916 | 0.99988 |
| DeepFM | 0.23391 | 0.29457 | 0.84306 |

DCN-v2 was selected because the application displays only three recommendations and it achieved the strongest `NDCG@3`, together with the lowest MAE.

The deployed model artifacts are loaded from:

`omershahar/REmatch-DCN-v2`

## Grounded Generative Explanations

The explanation layer uses:

`Qwen/Qwen2.5-1.5B-Instruct`

The generative model does not select, score, or rerank properties.

For each recommendation, Qwen receives only a small approved packet of structured investor and property fields. It generates one cautious alignment sentence. Python then adds the remaining explanation sections deterministically.

Every output is validated. If validation fails, the system performs one controlled retry. If generation still fails, or the GPU call raises an exception, a deterministic fallback explanation is returned.

This design reduces hallucination risk and prevents model scores from being presented as factual financial evidence.

## Investor Profile Description

After questionnaire submission, the application also displays a representative natural-language investor profile from Dataset A.

The representative profile is selected by:

1. exact agreement on the five structured investor dimensions;
2. closest `max_budget_usd`;
3. `investor_id` as the deterministic tie-breaker.

This gives the LLM-generated `investor_description` field from Part 1 a direct role in the final user experience without affecting property scoring or ranking.

## Property Return Display

Each property card displays an estimated 12-month gross return composed of:

- gross rental yield;
- 12-month value forecast.

The components are shown separately together with approximate annual rent and projected value change.

This is a gross educational estimate before expenses, taxes, financing, maintenance, vacancies, insurance, transaction costs, and due diligence. It is not a guaranteed return.

## User Interface

The interface includes:

- a branded REmatch header;
- one natural-language investor-description field;
- a conditional exact-budget follow-up;
- Quick Starter demonstration profiles;
- a representative investor-description card;
- three property recommendation cards;
- illustrative property images;
- price and estimated gross-return components;
- grounded recommendation explanations;
- a clearly labeled outside-budget fallback when needed.

The Quick Starter profiles are demonstration examples only and do not imply participation in or endorsement of the project.

## Data and Model Repositories

Dataset repository:

`https://huggingface.co/datasets/omershahar/REmatch-Investment-Matching-Dataset`

Model repository:

`https://huggingface.co/omershahar/REmatch-DCN-v2`

The Dataset repository contains the final datasets, EDA, quality-control journey, notebooks, model-comparison artifacts, and the full project documentation.

## Files Required in This Space

- `app.py`
- `generation.py`
- `requirements.txt`
- `rematch_text_profile_classifiers.joblib`
- `rematch_dataset_b_dcn_v2_embeddings.parquet`
- `assets/`

The `assets/` folder contains:

- the REmatch logo;
- illustrative property images;
- example-profile images;
- fallback images used when a specific image is unavailable.

## Runtime

- MPNet text encoding and DCN-v2 recommendation scoring run on CPU.
- DCN-v2 profile/property scores are precomputed once at startup and stored in a compact float32 matrix; each request then uses one weighted matrix operation.
- The classifier artifact and runtime are pinned to scikit-learn 1.7.2 for compatibility with the Gradio SDK's Python 3.10 image.
- Part 4 Qwen generation uses Hugging Face ZeroGPU through `@spaces.GPU(duration=60)`.
- Dataset A and Dataset B are loaded directly from the Hugging Face Dataset repository.
- The trained DCN-v2 checkpoint and preprocessing vocabulary are loaded from the Hugging Face Model repository.

## Important Limitations

- The project is an educational prototype and does not provide financial advice.
- Dataset C supervision labels are synthetic and rule-derived.
- Model results show how closely the models reproduce the designed compatibility methodology, not real-world investment performance.
- Investor descriptions are synthetic.
- The text classifiers reproduce structured labels from synthetic descriptions and may misinterpret vague or contradictory language.
- Some rental and market fields are estimates or area-level proxies.
- Property images are illustrative and are not photographs of the listed properties.
- Estimated gross return does not include expenses, taxes, financing, vacancies, maintenance, insurance, or transaction costs.
- Recommendations do not replace property due diligence or professional financial advice.