README.md

---
title: HomeMatch AI
emoji: 🏠
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 4.44.0
python_version: "3.10"
app_file: app.py
pinned: false
---

# HomeMatch AI

**AI-powered property recommendations with embeddings and grounded generation.**

A buyer describes what they want in free text; HomeMatch AI retrieves the most relevant
listings using sentence embeddings, explains *why* they fit with a grounded text-to-text
model, and drafts a direct buyer-to-owner inquiry message — shown in a polished
real-estate-style interface with property cards. **HomeMatch is a direct owner-to-buyer
platform**: no brokers, agents, agencies, or realtors.

## How it works

1. **Recommendation** — the query is embedded with the model named in
   `homematch_embedding_model_info.json` (`sentence-transformers/multi-qa-MiniLM-L6-cos-v1`).
   Structured filters (city, property type, max price, min rooms) are applied **before**
   ranking; the rest are ranked by cosine similarity (dot product on normalized vectors).
2. **Generation** — `google/flan-t5-base` (fallback `google/flan-t5-small`) produces a
   concise buyer summary and an owner-inquiry message, deterministically
   (`do_sample=False`), grounded **only** in the selected listings' structured facts.
3. **Safety** — outputs are checked and cleaned for banned broker/agent/agency/realtor
   wording and passed through quality checks (non-empty, length, grounding by
   city / neighborhood / property type).

## Property images

Property photos are stored locally in `assets/` and are assigned **by property type**
(`apartment`, `studio`, `private_house`, `penthouse`, `duplex`, `garden_apartment`),
with one of four image sets chosen deterministically from each listing's `listing_id`
(so a listing keeps the same images across refreshes). **Images are illustrative only and
do not depict the actual property.** Missing image folders/files fall back gracefully to a
styled placeholder.

## Data

All recommendation artifacts are read at runtime from the Hugging Face Dataset repo
[`BarWachsman7/HomeMatch-AI-Dataset`](https://huggingface.co/datasets/BarWachsman7/HomeMatch-AI-Dataset):

- `homematch_embedding_metadata.csv`
- `homematch_embeddings.npy`
- `homematch_embedding_model_info.json`
- `homematch_generation_model_info.json` *(optional)*
- `homematch_generation_examples.csv` *(optional)*

If `homematch_embeddings.npy` is uploaded directly into the Space, it is used as a local
fallback. Files and models are cached so they load once, not per request.

## Files to upload to the Space

```
app.py
requirements.txt
README.md
assets/            # hero image + property images by type
  hero/hero_home.jpg
  apartment/set_1..4/{1,2,3}.jpg
  studio/ ...  duplex/ ...  penthouse/ ...  private_house/ ...  garden_apartment/ ...
```

## Run locally

```bash
pip install -r requirements.txt
python app.py
```

No API keys or secrets are required. Hugging Face models only — no OpenAI, no paid APIs.