README.md

metadata

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:

• 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

pip install -r requirements.txt
python app.py

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