Rematch / app.py
omershahar's picture
Update app.py
4d2e86a verified
Raw History Blame Contribute Delete
53.4 kB
# ============================================================ # REMATCH - HUGGING FACE SPACE APP # Keep generation.py and the assets folder beside this file. # ============================================================ import html import json from pathlib import Path from urllib.parse import quote import gradio as gr import numpy as np import pandas as pd import torch from huggingface_hub import hf_hub_download from torch import nn from generation import generate_property_explanation # Put the generated illustrative images in an `assets` folder beside this file. # In a Hugging Face Space, upload the same folder to the repository root. ASSET_DIR = Path("assets") PROPERTY_IMAGES = { "single_family": "illustrative_single_family_home.png", "single_family_home": "illustrative_single_family_home.png", "singlefamily": "illustrative_single_family_home.png", "townhouse": "illustrative_townhouse.png", "condo": "illustrative_condo.png", "multi_family": "illustrative_multi_family.png", "multifamily": "illustrative_multi_family.png", "luxury_home": "illustrative_luxury_home.png", } DEFAULT_PROPERTY_IMAGE = "illustrative_default_property.png" REMATCH_LOGO_URL = "/gradio_api/file=" + quote( str((ASSET_DIR / "rematch_logo.png").resolve()) ) def property_image_url(property_type): """Return a Gradio-served URL for a generic illustrative property image.""" normalized_type = ( str(property_type or "") .strip() .lower() .replace(" ", "_") .replace("-", "_") ) image_name = PROPERTY_IMAGES.get(normalized_type, DEFAULT_PROPERTY_IMAGE) image_path = (ASSET_DIR / image_name).resolve() return "/gradio_api/file=" + quote(str(image_path)) # Part 3 intentionally stays CPU-only. DEVICE = torch.device("cpu") print("Runtime device:", DEVICE) # ============================================================ # LOAD APPROVED MODEL ARTIFACTS # ============================================================ MODEL_REPO_ID = "omershahar/REmatch-DCN-v2" MODEL_CONFIG_PATH = hf_hub_download( repo_id=MODEL_REPO_ID, filename="model_config.json", ) VOCABULARY_PATH = hf_hub_download( repo_id=MODEL_REPO_ID, filename="preprocessor_vocabulary.json", ) CHECKPOINT_PATH = hf_hub_download( repo_id=MODEL_REPO_ID, filename="dcn_v2_checkpoint.pt", ) with open(MODEL_CONFIG_PATH, "r", encoding="utf-8") as file: model_config = json.load(file) with open(VOCABULARY_PATH, "r", encoding="utf-8") as file: vocabulary_payload = json.load(file) I = model_config["investor_cols"] P = model_config["property_cols"] F = model_config["feature_cols"] assert F == I + P assert vocabulary_payload["feature_cols"] == F # ============================================================ # LOAD DATASET B DIRECTLY FROM HUGGING FACE DATASET REPO # ============================================================ DATASET_REPO_ID = "omershahar/REmatch-Investment-Matching-Dataset" DATASET_FILENAME = "rematch_properties.csv" DATASET_REVISION = "main" DATASET_B_PATH = hf_hub_download( repo_id=DATASET_REPO_ID, repo_type="dataset", filename=DATASET_FILENAME, revision=DATASET_REVISION, ) B = pd.read_csv(DATASET_B_PATH) required_property_columns = set( P + [ "id", "formattedAddress", "city_rentcast", "state", "propertyType", "price", "monthly_rent", "gross_rental_yield_percent", "value_forecast_12months", "price_volatility_percent", "property_description", ] ) missing_property_columns = required_property_columns - set(B.columns) assert not missing_property_columns, ( "Dataset B is missing required columns: " + str(sorted(missing_property_columns)) ) for column in P: B[column] = ( B[column] .fillna("__MISSING__") .astype(str) .str.strip() ) print("Loaded Dataset B from Hugging Face") print("Property inventory rows:", len(B)) # ============================================================ # LOAD SAVED DCN-v2 PROPERTY EMBEDDINGS FROM THE SPACE # ============================================================ EMBEDDINGS_PATH = Path( "rematch_dataset_b_dcn_v2_embeddings.parquet" ) if not EMBEDDINGS_PATH.exists(): raise FileNotFoundError( "Missing rematch_dataset_b_dcn_v2_embeddings.parquet. " "Upload it to the root of this Hugging Face Space." ) EMBEDDINGS = pd.read_parquet(EMBEDDINGS_PATH) EMBEDDING_COLS = sorted( [ column for column in EMBEDDINGS.columns if column.startswith("dcn_v2_property_embedding_") ], key=lambda column: int(column.rsplit("_", 1)[1]), ) assert len(EMBEDDING_COLS) == 60, ( f"Expected 60 DCN-v2 embedding columns, found {len(EMBEDDING_COLS)}." ) assert "id" in EMBEDDINGS.columns, ( "The embedding Parquet file must contain an id column." ) # IDs are the bridge between the vector index and Dataset B. B["id"] = B["id"].astype(str) EMBEDDINGS["id"] = EMBEDDINGS["id"].astype(str) EMBEDDINGS = EMBEDDINGS[ ["id"] + EMBEDDING_COLS ].drop_duplicates("id") missing_embedding_ids = set(B["id"]) - set(EMBEDDINGS["id"]) assert not missing_embedding_ids, ( "Some Dataset B properties have no saved embedding. " f"Missing count: {len(missing_embedding_ids)}" ) print("Loaded DCN-v2 property embedding index from Parquet") print("Embedding rows:", len(EMBEDDINGS)) print("Embedding dimensions:", len(EMBEDDING_COLS)) # ============================================================ # LOAD DATASET A FOR REPRESENTATIVE INVESTOR DESCRIPTIONS # ============================================================ DATASET_A_PATH = hf_hub_download( repo_id=DATASET_REPO_ID, repo_type="dataset", filename="rematch_investor_profiles.csv", revision=DATASET_REVISION, ) A = pd.read_csv(DATASET_A_PATH) required_investor_columns = { "investor_id", "budget_level", "max_budget_usd", "financing_willingness", "liquidity_importance", "risk_profile", "primary_goal", "investor_description", } missing_investor_columns = required_investor_columns - set(A.columns) assert not missing_investor_columns, ( "Dataset A is missing required columns: " + str(sorted(missing_investor_columns)) ) for column in [ "budget_level", "financing_willingness", "liquidity_importance", "risk_profile", "primary_goal", ]: A[column] = A[column].astype(str).str.strip() A["max_budget_usd"] = pd.to_numeric( A["max_budget_usd"], errors="coerce", ) print("Loaded Dataset A from Hugging Face") print("Investor profile rows:", len(A)) # ============================================================ # APPROVED DCN-v2 ARCHITECTURE # ============================================================ class Prep: def __init__(self, vocabularies): self.v = vocabularies def transform(self, dataframe): encoded = np.zeros( (len(dataframe), len(F)), dtype=np.int64, ) for index, column in enumerate(F): encoded[:, index] = ( dataframe[column] .astype(str) .map(self.v[column]) .fillna(0) .astype(int) ) return encoded @property def sizes(self): return [len(self.v[column]) for column in F] class Emb(nn.Module): def __init__(self, sizes, dim=12): super().__init__() self.t = nn.ModuleList( [nn.Embedding(size, dim) for size in sizes] ) def forward(self, inputs): return torch.stack( [ embedding(inputs[:, index]) for index, embedding in enumerate(self.t) ], dim=1, ) class Cross(nn.Module): def __init__(self, input_size): super().__init__() self.w = nn.Parameter(torch.randn(input_size) * 0.01) self.b = nn.Parameter(torch.zeros(input_size)) def forward(self, initial_input, current_input): return ( initial_input * (current_input * self.w).sum(1, keepdim=True) + self.b + current_input ) class DCNv2(nn.Module): def __init__(self, sizes, dim=12): super().__init__() self.e = Emb(sizes, dim) flattened_size = len(sizes) * dim self.c = nn.ModuleList( [ Cross(flattened_size), Cross(flattened_size), ] ) self.d = nn.Sequential( nn.Linear(flattened_size, 96), nn.ReLU(), nn.Dropout(0.15), nn.Linear(96, 48), nn.ReLU(), ) self.o = nn.Linear(flattened_size + 48, 1) def forward(self, inputs): initial_input = self.e(inputs).flatten(1) crossed_input = initial_input for cross_layer in self.c: crossed_input = cross_layer( initial_input, crossed_input, ) return self.o( torch.cat( [ crossed_input, self.d(initial_input), ], dim=1, ) ).squeeze(1) # ============================================================ # LOAD TRAINED MODEL # ============================================================ prep = Prep(vocabulary_payload["vocabularies"]) embedding_dimension = int(model_config["embedding_dim"]) model = DCNv2( sizes=prep.sizes, dim=embedding_dimension, ).to(DEVICE) checkpoint = torch.load( CHECKPOINT_PATH, map_location=DEVICE, ) assert checkpoint["model_name"] == "DCN-v2" assert checkpoint["feature_cols"] == F assert checkpoint["investor_cols"] == I assert checkpoint["property_cols"] == P model.load_state_dict(checkpoint["state_dict"]) model.eval() print("Loaded trained model: DCN-v2") # ============================================================ # PART 3 - RECOMMENDATION ENGINE # ============================================================ RECOMMENDATION_FIELDS = [ "id", "formattedAddress", "city_rentcast", "state", "propertyType", "price", "monthly_rent", "gross_rental_yield_percent", "value_forecast_12months", "price_volatility_percent", "property_description", ] def predict(model, encoded_features): model.eval() outputs = [] with torch.inference_mode(): for start in range(0, len(encoded_features), 1024): batch = torch.tensor( encoded_features[start:start + 1024], dtype=torch.long, device=DEVICE, ) prediction = torch.sigmoid(model(batch)) outputs.append(prediction.cpu().numpy()) return np.concatenate(outputs) def percentile_rank(series, ascending=True): ranks = ( pd.to_numeric(series, errors="coerce") .rank(pct=True) .fillna(0.5) ) return ranks if ascending else 1 - ranks def cosine_similarity(vector_a, vector_b): """Cosine similarity for two already numeric property vectors.""" denominator = np.linalg.norm(vector_a) * np.linalg.norm(vector_b) if denominator == 0: return 0.0 return float(np.dot(vector_a, vector_b) / denominator) def select_diverse_top_3(ranked_candidates, diversity_weight=0.015): """ Select three strong recommendations while using the saved DCN-v2 property embeddings to avoid returning three almost identical assets. DCN-v2 fit score remains the main ranking signal. The embedding similarity penalty is intentionally small. """ pool = ranked_candidates.head(100).copy() selected_rows = [] selected_vectors = [] for _, row in pool.iterrows(): candidate_vector = row[EMBEDDING_COLS].to_numpy( dtype=np.float32 ) if not selected_vectors: max_similarity = 0.0 else: max_similarity = max( cosine_similarity(candidate_vector, selected_vector) for selected_vector in selected_vectors ) selection_score = ( float(row["final_score"]) - diversity_weight * max_similarity ) selected_rows.append( ( selection_score, row, candidate_vector, ) ) # At each round, take the best currently available candidate. best = max( selected_rows, key=lambda item: item[0], ) # Only select when this row is the best remaining option. if best[1]["id"] == row["id"]: selected_vectors.append(candidate_vector) if len(selected_vectors) == 3: break # Keep only rows not already selected. selected_ids = { str(vector_row[1]["id"]) for vector_row in selected_rows if any( np.array_equal( vector_row[2], selected_vector, ) for selected_vector in selected_vectors ) } pool = pool[ ~pool["id"].astype(str).isin(selected_ids) ] # A clearer greedy implementation, preserving original DCN score. chosen = [] chosen_vectors = [] remaining = ranked_candidates.head(100).copy() while len(chosen) < 3 and not remaining.empty: selection_scores = [] for index, row in remaining.iterrows(): candidate_vector = row[EMBEDDING_COLS].to_numpy( dtype=np.float32 ) if chosen_vectors: max_similarity = max( cosine_similarity( candidate_vector, selected_vector, ) for selected_vector in chosen_vectors ) else: max_similarity = 0.0 selection_score = ( float(row["final_score"]) - diversity_weight * max_similarity ) selection_scores.append( (index, selection_score, max_similarity) ) best_index, best_selection_score, best_similarity = max( selection_scores, key=lambda item: item[1], ) selected_row = remaining.loc[best_index].copy() selected_row["embedding_similarity_penalty"] = best_similarity selected_row["selection_score"] = best_selection_score chosen.append(selected_row) chosen_vectors.append( selected_row[EMBEDDING_COLS].to_numpy( dtype=np.float32 ) ) remaining = remaining.drop(index=best_index) return pd.DataFrame(chosen) def recommend_top_3( budget_level, max_budget_usd, financing_willingness, liquidity_importance, risk_profile, primary_goal, enforce_budget=True, ): answers = dict( zip( I, [ budget_level, financing_willingness, liquidity_importance, risk_profile, primary_goal, ], ) ) for column, value in answers.items(): if value not in prep.v[column]: raise ValueError(f"Unsupported {column}: {value}") max_budget_usd = float(max_budget_usd) if not np.isfinite(max_budget_usd) or max_budget_usd <= 0: raise ValueError( "max_budget_usd must be greater than zero." ) # Dataset B remains the source of truth for every property. candidates = B.copy() candidates["price"] = pd.to_numeric( candidates["price"], errors="coerce", ) # Strict eligibility rules run before any recommendation scoring. candidates = candidates[ candidates["price"].notna() & (candidates["price"] > 0) ] if enforce_budget: candidates = candidates[ candidates["price"] <= max_budget_usd ] if risk_profile == "conservative": candidates = candidates[ (candidates["volatility_band"] != "high_volatility") & (candidates["forecast_band"] != "negative_forecast") ] if candidates.empty: return pd.DataFrame( columns=RECOMMENDATION_FIELDS + [ "predicted_match_fit", "final_score", "selection_score", ] ) # Join each live Dataset B property to its saved DCN-v2 embedding. # Only the embedding vectors come from the Parquet file. candidates = candidates.merge( EMBEDDINGS, on="id", how="inner", validate="one_to_one", ) if candidates.empty: raise RuntimeError( "No eligible Dataset B properties could be matched " "to the saved embedding index." ) # DCN-v2 computes personalized match quality from the five answers. model_features = candidates[P].copy() for column, value in answers.items(): model_features[column] = value candidates["predicted_match_fit"] = predict( model, prep.transform(model_features[F]), ) # Deterministic property-quality tie-breaker. tie_breaker = ( 0.35 * percentile_rank( candidates["gross_rental_yield_percent"] ) + 0.30 * percentile_rank( candidates["value_forecast_12months"] ) + 0.20 * percentile_rank( candidates["price_volatility_percent"], ascending=False, ) ) if enforce_budget: tie_breaker += ( 0.15 * ( 1 - candidates["price"] / max_budget_usd ).clip(0, 1) ) else: # No budget headroom exists in fallback mode. # Rescale the remaining 85% of the tie-breaker to 100%. tie_breaker = tie_breaker / 0.85 candidates["final_score"] = ( 0.85 * candidates["predicted_match_fit"] + 0.15 * tie_breaker ) ranked_candidates = candidates.sort_values( [ "final_score", "predicted_match_fit", "price", "id", ], ascending=[ False, False, True, True, ], kind="mergesort", ) # The saved Parquet vectors now actively influence the final three: # selected results remain high-fit, but are less repetitive. result = select_diverse_top_3(ranked_candidates) assert len(result) <= 3 if enforce_budget: assert (result["price"] <= max_budget_usd).all(), ( "Exact budget guard failed" ) if risk_profile == "conservative": assert not ( result["volatility_band"] == "high_volatility" ).any(), "Conservative volatility guard failed" assert not ( result["forecast_band"] == "negative_forecast" ).any(), "Conservative forecast guard failed" return result[ RECOMMENDATION_FIELDS + [ "predicted_match_fit", "final_score", "selection_score", ] ] # ============================================================ # PART 5A - REGRESSION TEST # ============================================================ regression_results = recommend_top_3( budget_level="medium", max_budget_usd=450000, financing_willingness="no", liquidity_importance="medium", risk_profile="conservative", primary_goal="income", ).reset_index(drop=True) expected_address_starts = [ "435 Canberra Dr", "3508 Dance Ave", "400 Dublin Dr", ] assert len(regression_results) == 3 for actual, expected in zip( regression_results["formattedAddress"].astype(str).tolist(), expected_address_starts, ): assert actual.startswith(expected), ( f"Expected {expected}, got {actual}" ) assert (regression_results["price"] <= 450000).all() regression_details = regression_results.merge( B[ [ "id", "volatility_band", "forecast_band", ] ], on="id", how="left", ) assert not ( regression_details["volatility_band"] == "high_volatility" ).any() assert not ( regression_details["forecast_band"] == "negative_forecast" ).any() print("Part 5A regression test passed.") # ============================================================ # PART 4 - GROUNDED EXPLANATIONS # ============================================================ def derive_budget_level(max_budget_usd): amount = float(max_budget_usd) if amount < 150000: return "low" if amount < 300000: return "lower_mid" if amount < 500000: return "medium" return "high" def render_representative_investor_profile( max_budget_usd, financing_willingness, liquidity_importance, risk_profile, primary_goal, ): """Return one deterministic Dataset A description matching the user.""" budget_level = derive_budget_level(max_budget_usd) budget = float(max_budget_usd) matches = A[ (A["budget_level"] == budget_level) & (A["financing_willingness"] == financing_willingness) & (A["liquidity_importance"] == liquidity_importance) & (A["risk_profile"] == risk_profile) & (A["primary_goal"] == primary_goal) & A["max_budget_usd"].notna() & A["investor_description"].notna() ].copy() if matches.empty: return "" matches["budget_distance"] = ( matches["max_budget_usd"] - budget ).abs() selected = matches.sort_values( ["budget_distance", "investor_id"], ascending=[True, True], kind="mergesort", ).iloc[0] description = html.escape( str(selected["investor_description"]).strip() ) return f""" <div class="representative-profile-card"> <div class="representative-profile-label"> YOUR INVESTOR PROFILE </div> <h2>A profile that matches your selections</h2> <p>“{description}”</p> </div> """ PART4_PROPERTY_FIELDS = [ "id", "formattedAddress", "city_rentcast", "propertyType", "yield_band", "liquidity_band", "volatility_band", "forecast_band", ] def python_value(value): if isinstance(value, np.generic): return value.item() if pd.isna(value): return None return value def property_record_for_generation(property_id): matches = B[B["id"].astype(str) == str(property_id)] if len(matches) != 1: raise ValueError( f"Expected one property for ID {property_id}; found {len(matches)}." ) row = matches.iloc[0] return { field: python_value(row[field]) for field in PART4_PROPERTY_FIELDS if field in B.columns } def generate_top_3_explanations( investor_profile, property_records, ): generation_results = [] for property_record in property_records: explanation = generate_property_explanation( investor_profile=investor_profile, property_record=property_record, ) generation_results.append(explanation) return generation_results def prepare_part_4( max_budget_usd, financing_willingness, liquidity_importance, risk_profile, primary_goal, ): budget_level = derive_budget_level(max_budget_usd) results = recommend_top_3( budget_level=budget_level, max_budget_usd=max_budget_usd, financing_willingness=financing_willingness, liquidity_importance=liquidity_importance, risk_profile=risk_profile, primary_goal=primary_goal, ).reset_index(drop=True) budget_fallback = False if results.empty: results = recommend_top_3( budget_level=budget_level, max_budget_usd=max_budget_usd, financing_willingness=financing_willingness, liquidity_importance=liquidity_importance, risk_profile=risk_profile, primary_goal=primary_goal, enforce_budget=False, ).reset_index(drop=True) budget_fallback = not results.empty if results.empty: return [], {}, [] investor_profile = { "budget_level": budget_level, "financing_willingness": financing_willingness, "liquidity_importance": liquidity_importance, "risk_profile": risk_profile, "primary_goal": primary_goal, } ranked_records = [] for record in results.to_dict(orient="records"): clean_record = { key: python_value(value) for key, value in record.items() } clean_record["budget_fallback"] = budget_fallback clean_record["requested_budget_usd"] = float(max_budget_usd) ranked_records.append(clean_record) property_records = [ property_record_for_generation(row["id"]) for row in ranked_records ] return ranked_records, investor_profile, property_records def format_explanation_html(explanation): """ Removes the duplicate opening heading and converts important explanation section titles into bold visual headings. """ text = str(explanation or "").strip() lines = text.splitlines() # Remove blank lines at the beginning. while lines and not lines[0].strip(): lines.pop(0) # Remove duplicate first line shown beneath the card heading. if lines: first_line = lines[0].strip().strip("*").lower() if first_line in { "why this property may fit:", "why this property may fit", "why this property matches you:", "why this property matches you", }: lines.pop(0) headings = { "key consideration:", "key property indicators:", "what to verify:", } formatted_lines = [] for line in lines: clean_line = line.strip() if not clean_line: formatted_lines.append("<div class='explanation-space'></div>") continue escaped_line = html.escape(clean_line) normalized_line = clean_line.strip("*").lower() if normalized_line in headings: formatted_lines.append( f"<div class='explanation-heading'>{escaped_line}</div>" ) else: formatted_lines.append( f"<div class='explanation-text'>{escaped_line}</div>" ) return "".join(formatted_lines) # ============================================================ # RESULT CARDS # ============================================================ def render_part_4_results( ranked_records, generation_results, ): if not ranked_records: return """ <div class="no-results"> <h2>No eligible properties found</h2> <p>Try adjusting the budget or investor preferences.</p> </div> """ if len(ranked_records) != len(generation_results): raise ValueError( "Recommendation and generation result counts do not match." ) cards = [] budget_fallback = bool( ranked_records[0].get("budget_fallback", False) ) fallback_message = "" if budget_fallback: requested_budget = float( ranked_records[0]["requested_budget_usd"] ) lowest_displayed_price = min( float(record["price"]) for record in ranked_records ) gap = lowest_displayed_price - requested_budget fallback_message = f""" <div class="budget-fallback"> <strong>No eligible property was found within your ${requested_budget:,.0f} budget.</strong> <span> We’re showing the strongest matching alternatives outside your current budget. The lowest-priced option shown is ${lowest_displayed_price:,.0f}, which is ${gap:,.0f} above your entered budget. </span> </div> """ for rank, (property_record, explanation) in enumerate( zip(ranked_records, generation_results), start=1, ): address = html.escape( str(property_record.get("formattedAddress", "Address unavailable")) ) property_type = html.escape( str(property_record.get("propertyType", "Property")) ) image_url = property_image_url( property_record.get("propertyType", "") ) try: price = f"${float(property_record.get('price')):,.0f}" except (TypeError, ValueError): price = "Price unavailable" try: price_value = float(property_record.get("price")) except (TypeError, ValueError): price_value = None try: monthly_rent = float( property_record.get("monthly_rent") ) except (TypeError, ValueError): monthly_rent = None try: rental_yield = float( property_record.get("gross_rental_yield_percent") ) except (TypeError, ValueError): rental_yield = None try: value_forecast = float( property_record.get("value_forecast_12months") ) except (TypeError, ValueError): value_forecast = None annual_rent = ( monthly_rent * 12 if monthly_rent is not None else None ) projected_value_change = ( price_value * value_forecast / 100 if price_value is not None and value_forecast is not None else None ) estimated_gross_return = ( rental_yield + value_forecast if rental_yield is not None and value_forecast is not None else None ) rental_yield_text = ( f"{rental_yield:.1f}%" if rental_yield is not None else "N/A" ) annual_rent_text = ( f"~${annual_rent:,.0f}/yr" if annual_rent is not None else "N/A" ) forecast_text = ( f"{value_forecast:+.1f}%" if value_forecast is not None else "N/A" ) value_change_text = ( f"~${projected_value_change:+,.0f}" if projected_value_change is not None else "N/A" ) gross_return_text = ( f"{estimated_gross_return:.1f}%" if estimated_gross_return is not None else "N/A" ) explanation_text = format_explanation_html(explanation) cards.append( f""" <div class="property-card"> <div class="property-image-wrap"> <img class="property-image" src="{image_url}" alt="Illustrative {property_type} exterior" /> <div class="property-rank">MATCH #{rank}</div> </div> <div class="property-content"> <h2 class="property-address">{address}</h2> <div class="property-details"> <div> <span class="detail-label">PROPERTY TYPE</span> <span class="detail-value">{property_type}</span> </div> <div> <span class="detail-label">PRICE</span> <span class="property-price">{price}</span> </div> </div> <div class="return-panel"> <div class="return-main"> <span class="return-label"> EST. 12-MONTH GROSS RETURN </span> <span class="return-value"> {gross_return_text} </span> </div> <div class="return-components"> <div class="return-component"> <span class="return-component-label"> RENTAL INCOME </span> <strong>{rental_yield_text}</strong> <small>{annual_rent_text}</small> </div> <div class="return-plus">+</div> <div class="return-component"> <span class="return-component-label"> VALUE FORECAST </span> <strong>{forecast_text}</strong> <small>{value_change_text}</small> </div> </div> <div class="return-note"> Gross estimate before expenses, taxes, financing and transaction costs. </div> </div> <div class="illustrative-note">Illustrative property image</div> <div class="explanation-section"> <h3>Why this property matches you</h3> <div>{explanation_text}</div> </div> </div> </div> """ ) return f""" {fallback_message} <div class="results-header"> <h1>Your top matches</h1> <p>Three properties selected for your investment profile.</p> </div> <div class="property-grid"> {''.join(cards)} </div> """ # ============================================================ # QUICK STARTER USER EXAMPLES # ============================================================ USER_EXAMPLES = { "Custom profile": None, "Eyal Ofer": { "max_budget_usd": 1_000_000, "financing_willingness": "no", "liquidity_importance": "low", "risk_profile": "aggressive", "primary_goal": "growth", }, "Gary Barnett": { "max_budget_usd": 450_000, "financing_willingness": "no", "liquidity_importance": "medium", "risk_profile": "balanced", "primary_goal": "preservation", }, "Adam Neumann": { "max_budget_usd": 125_000, "financing_willingness": "yes", "liquidity_importance": "high", "risk_profile": "conservative", "primary_goal": "income", }, } # Upload these three authorised image files to the assets folder. The app uses # an initials-based placeholder until the corresponding image has been added. EXAMPLE_DETAILS = { "Eyal Ofer": { "photo": "eyal_ofer.jpg", "initials": "EO", "bio": ( "Eyal Ofer founded Ofer Global, a private portfolio of international businesses. " "Its areas of activity include maritime shipping, real estate and hotels, technology, banking and energy. " "This example profile represents a high-budget, growth-oriented investment approach." ), }, "Gary Barnett": { "photo": "gary_barnett.jpg", "initials": "GB", "bio": ( "Gary Barnett is the founder and chairman of Extell Development. " "Extell develops luxury residential, commercial and hospitality properties in New York City and beyond. " "This example profile represents a balanced, preservation-oriented investment approach." ), }, "Adam Neumann": { "photo": "adam_neumann.jpg", "initials": "AN", "bio": ( "Adam Neumann co-founded WeWork and later founded Flow, a residential real-estate company. " "Flow focuses on a technology-enabled residential experience for owners, operators and residents. " "This example profile represents a lower-budget, income-oriented investment approach." ), }, } def example_image_url(example): """Use an authorised local image when present, otherwise show initials.""" photo_path = ASSET_DIR / EXAMPLE_DETAILS[example]["photo"] if photo_path.exists(): return "/gradio_api/file=" + quote(str(photo_path.resolve())) initials = EXAMPLE_DETAILS[example]["initials"] return ( "data:image/svg+xml;utf8," + quote( f"<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'>" f"<rect width='100%' height='100%' fill='%23003b95'/>" f"<text x='50%' y='55%' text-anchor='middle' fill='white' " f"font-family='Arial' font-size='52' font-weight='700'>{initials}</text>" f"</svg>" ) ) def render_example_profiles(): cards = [] for name, details in EXAMPLE_DETAILS.items(): cards.append( f""" <div class="example-profile-card"> <img class="example-photo" src="{example_image_url(name)}" alt="{html.escape(name)}" /> <div class="example-profile-copy"> <h3>{html.escape(name)}</h3> <p>{html.escape(details['bio'])}</p> </div> </div> """ ) return f"<div class='example-profile-grid'>{''.join(cards)}</div>" def render_selected_example(example_name): """Show an investor bio only when the visitor selects an example.""" if example_name == "Custom profile": return "" details = EXAMPLE_DETAILS[example_name] return f""" <div class="selected-example-card"> <img class="selected-example-photo" src="{example_image_url(example_name)}" alt="{html.escape(example_name)}" /> <div class="selected-example-copy"> <div class="selected-example-label">INVESTOR EXAMPLE</div> <h2>{html.escape(example_name)}</h2> <p>{html.escape(details['bio'])}</p> </div> </div> """ def apply_user_example(example_name): profile = USER_EXAMPLES[example_name] if profile is None: return ( gr.update(), gr.update(), gr.update(), gr.update(), gr.update(), [], {}, [], ) ranked_records, investor_profile, property_records = prepare_part_4( max_budget_usd=profile["max_budget_usd"], financing_willingness=profile["financing_willingness"], liquidity_importance=profile["liquidity_importance"], risk_profile=profile["risk_profile"], primary_goal=profile["primary_goal"], ) return ( profile["max_budget_usd"], profile["financing_willingness"], profile["liquidity_importance"], profile["risk_profile"], profile["primary_goal"], ranked_records, investor_profile, property_records, ) # ============================================================ # GRADIO UI # ============================================================ with gr.Blocks( title="rematch | Property matching", css=""" :root { --blue:#003b95; --blue-dark:#002b6d; --yellow:#febb02; --ink:#1a1a1a; --muted:#6b6b6b; } .gradio-container { background:#f5f5f5 !important; font-family:Arial,Helvetica,sans-serif !important; } .hero { background:linear-gradient(112deg,var(--blue-dark),var(--blue)); border-radius:0 0 20px 20px; color:white; margin:-8px -8px 0; padding:42px max(24px,calc((100vw - 1120px)/2)) 72px; } .brand-row { align-items:center; display:flex; gap:14px; margin:0 0 14px; } .brand-logo { height:92px; object-fit:contain; width:92px; } .brand { color:#ffffff !important; font-size:56px; font-weight:800; letter-spacing:-2px; line-height:1; margin:0; } .hero-subtitle { color:#ffffff !important; font-size:19px; line-height:1.4; margin:0; opacity:.96; } .search-shell { max-width:1120px; margin:36px auto 0; position:relative; z-index:2; background:var(--yellow); border-radius:12px; padding:5px; box-shadow:0 6px 22px rgba(0,0,0,.18); } .search-card { background:white; border-radius:8px; padding:18px; } .search-title { color:var(--ink); font-size:21px; font-weight:700; margin:0 0 4px; } .search-subtitle { color:var(--muted); margin:0 0 18px; } .input-row { align-items:flex-end; gap:10px !important; } .field-question { align-items:flex-start; color:#262626; display:flex; font-size:14px; font-weight:700; gap:6px; line-height:1.25; margin:0 0 3px; min-height:28px; } .help-icon { align-items:center; align-self:center; background:#003b95; border-radius:50%; color:white; cursor:help; display:inline-flex; flex:0 0 18px; font-size:12px; font-weight:800; height:18px; justify-content:center; width:18px; } .search-field { min-width:0 !important; } .match-button { margin-top:44px !important; } .quick-starter { background:#eef5ff; border:1px solid #c8ddff; border-radius:8px; margin:24px auto 0; max-width:1120px; padding:8px 16px; } .selected-example { max-width:1120px; margin:16px auto 0; } .selected-example-card { align-items:center; background:white; border:1px solid #c8ddff; border-radius:10px; display:flex; gap:18px; padding:18px; } .selected-example-photo { border-radius:50%; flex:0 0 110px; height:110px; object-fit:cover; width:110px; } .selected-example-copy h2 { color:#262626; font-size:22px; margin:3px 0 8px; } .selected-example-copy p { color:#555; line-height:1.55; margin:0; } .selected-example-label { color:#003b95; font-size:11px; font-weight:800; letter-spacing:.1em; } .representative-profile { max-width:1120px; margin:18px auto 0; } .representative-profile-card { background:white; border-left:5px solid var(--blue); border-radius:8px; box-shadow:0 2px 8px rgba(0,0,0,.08); padding:20px 22px; } .representative-profile-label { color:var(--blue); font-size:11px; font-weight:800; letter-spacing:.1em; } .representative-profile-card h2 { color:#262626; font-size:21px; margin:5px 0 10px; } .representative-profile-card p { color:#404040; font-size:16px; font-style:italic; line-height:1.6; margin:0; } .match-button { background:#0071c2 !important; border:1px solid #0071c2 !important; border-radius:6px !important; color:white !important; font-size:17px !important; font-weight:700 !important; min-height:50px !important; } .match-button:hover { background:#005fa3 !important; } .page-content { max-width:1120px; margin:22px auto 44px; } .results-header { margin:28px 0 16px; text-align:left; } .results-header h1 { color:var(--ink); font-size:27px; margin-bottom:6px; } .results-header p { color:var(--muted); } .property-grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:16px; align-items:stretch; margin-top:20px; } .property-card { background:white; border:1px solid #d0d0d0; border-radius:8px; box-shadow:0 2px 8px rgba(0,0,0,.09); overflow:hidden; } .property-image-wrap { height:190px; position:relative; overflow:hidden; background:#e8eef5; } .property-image { width:100%; height:100%; display:block; object-fit:cover; } .property-content { display:flex; flex-direction:column; padding:18px; min-height:390px; } .property-rank { background:var(--blue); border-radius:4px; color:white; font-size:11px; font-weight:800; letter-spacing:.1em; padding:6px 8px; position:absolute; top:12px; left:12px; } .property-address { color:#262626; font-size:20px; line-height:1.25; margin:0 0 18px; } .property-details { display:grid; grid-template-columns:1fr 1fr; gap:12px; background:#f5f5f5; border-radius:6px; padding:12px; margin-bottom:8px; } .detail-label { display:block; color:var(--muted); font-size:10px; font-weight:800; letter-spacing:.08em; margin-bottom:4px; } .detail-value { color:#262626; font-weight:700; } .property-price { color:#008009; font-size:19px; font-weight:800; } .illustrative-note { color:#777; font-size:11px; margin:2px 0 14px; } .return-panel { background:#f7fbff; border:1px solid #d7e7f7; border-radius:8px; margin:8px 0 12px; padding:14px; } .return-main { text-align:center; margin-bottom:12px; } .return-label { color:#6b6b6b; display:block; font-size:10px; font-weight:800; letter-spacing:.08em; } .return-value { color:#008009; display:block; font-size:27px; font-weight:800; margin-top:3px; } .return-components { align-items:center; display:grid; grid-template-columns:1fr auto 1fr; gap:8px; text-align:center; } .return-component-label { color:#6b6b6b; display:block; font-size:9px; font-weight:800; letter-spacing:.07em; } .return-component strong { color:#262626; display:block; font-size:16px; margin-top:3px; } .return-component small { color:#777; display:block; font-size:11px; margin-top:2px; } .return-plus { color:#003b95; font-size:20px; font-weight:800; } .return-note { border-top:1px solid #e1eaf3; color:#777; font-size:9px; margin-top:10px; padding-top:8px; text-align:center; } .budget-fallback { background:#fff7ed; border:1px solid #f5c38b; border-left:5px solid #f59e0b; border-radius:8px; color:#704214; margin:24px 0 8px; padding:16px 18px; } .budget-fallback strong { display:block; font-size:16px; margin-bottom:5px; } .budget-fallback span { display:block; font-size:14px; line-height:1.5; } .explanation-section { border-top:1px solid #e2e2e2; padding-top:16px; margin-top:auto; } .explanation-section h3 { color:#262626; font-size:15px; margin:0 0 8px; } .no-results { background:#fff7ed; border:1px solid #fed7aa; border-radius:8px; color:#854d0e; padding:24px; text-align:center; } .explanation-heading { color:#262626; font-size:14px; font-weight:800; margin-top:14px; margin-bottom:5px; } .explanation-text { color:#454545; font-size:14px; line-height:1.65; margin-bottom:4px; } .explanation-space { height:8px; } @media (max-width:900px) { .property-grid { grid-template-columns:1fr; } .hero { padding:32px 22px 48px; } .brand-logo { height:70px; width:70px; } .brand { font-size:42px; } .selected-example-card { align-items:flex-start; flex-direction:column; } } """, ) as demo: gr.HTML(f""" <div class="hero"> <div class="brand-row"> <img class="brand-logo" src="{REMATCH_LOGO_URL}" alt="REmatch logo" /> <h1 class="brand">Rematch</h1> </div> <p class="hero-subtitle">Find investment properties that fit the way you invest.</p> </div> """) with gr.Group(elem_classes="search-shell"): with gr.Column(elem_classes="search-card"): gr.HTML(""" <h2 class="search-title">Tell us how you want to invest</h2> <p class="search-subtitle">Choose your preferences and we’ll find three eligible property matches.</p> """) with gr.Row(elem_classes="input-row"): with gr.Column(scale=2, min_width=180, elem_classes="search-field"): gr.HTML(""" <div class="field-question">Maximum property price (USD) <span class="help-icon" title="Enter the highest total property price you are willing to consider, including any financing. Properties above this amount will never be recommended.">?</span> </div> """) max_budget = gr.Number(label="", value=350000, minimum=1, precision=0) with gr.Column(scale=1, min_width=150, elem_classes="search-field"): gr.HTML(""" <div class="field-question">Use financing? <span class="help-icon" title="Yes means you are open to financing part of the purchase. No means you prefer to purchase without financing.">?</span> </div> """) financing = gr.Dropdown(choices=[("Yes", "yes"), ("No", "no")], value="no", label="") with gr.Column(scale=1, min_width=150, elem_classes="search-field"): gr.HTML(""" <div class="field-question">Liquidity importance <span class="help-icon" title="High: you may need to exit quickly. Medium: liquidity matters. Balanced: a moderate exit timeline is acceptable. Low: you can hold longer before selling.">?</span> </div> """) liquidity = gr.Dropdown(choices=[("High", "high"), ("Medium", "medium"), ("Balanced", "balanced"), ("Low", "low")], value="medium", label="") with gr.Column(scale=1, min_width=150, elem_classes="search-field"): gr.HTML(""" <div class="field-question">Risk profile <span class="help-icon" title="Conservative: prioritize stability; high-volatility and negative-forecast properties are excluded. Balanced: accept moderate uncertainty. Aggressive: accept greater uncertainty for growth potential.">?</span> </div> """) risk = gr.Dropdown(choices=[("Conservative", "conservative"), ("Balanced", "balanced"), ("Aggressive", "aggressive")], value="balanced", label="") with gr.Column(scale=1, min_width=150, elem_classes="search-field"): gr.HTML(""" <div class="field-question">Investment goal <span class="help-icon" title="Income: prioritize rental-income signals. Growth: prioritize value-growth signals. Preservation: prioritize capital stability. Total return: balance income and growth signals.">?</span> </div> """) goal = gr.Dropdown(choices=[("Income", "income"), ("Growth", "growth"), ("Preservation", "preservation"), ("Total return", "total_return")], value="total_return", label="") with gr.Column(scale=1, min_width=175): full_pipeline_button = gr.Button("Match Me Up!", variant="primary", elem_classes="match-button") with gr.Group(elem_classes="quick-starter"): quick_starter = gr.Dropdown( choices=list(USER_EXAMPLES.keys()), value="Custom profile", label="Try an investor example", info="Choosing a named example fills its profile and immediately loads recommendations.", ) with gr.Column(elem_classes="selected-example"): selected_example_output = gr.HTML(value="") with gr.Column(elem_classes="representative-profile"): representative_profile_output = gr.HTML(value="") with gr.Column(elem_classes="page-content"): full_output = gr.HTML(value=""" <div class="no-results"><h2>Ready when you are</h2><p>Enter your investment preferences above, then select <strong>Match Me Up!</strong></p></div> """) ranked_state = gr.State([]) investor_state = gr.State({}) property_state = gr.State([]) generation_state = gr.State([]) match_event = full_pipeline_button.click( fn=prepare_part_4, inputs=[max_budget, financing, liquidity, risk, goal], outputs=[ranked_state, investor_state, property_state], ) match_event = match_event.then( fn=render_representative_investor_profile, inputs=[max_budget, financing, liquidity, risk, goal], outputs=representative_profile_output, ) match_event = match_event.then( fn=generate_top_3_explanations, inputs=[investor_state, property_state], outputs=generation_state, ) match_event.then( fn=render_part_4_results, inputs=[ranked_state, generation_state], outputs=full_output, ) quick_event = quick_starter.change( fn=apply_user_example, inputs=quick_starter, outputs=[max_budget, financing, liquidity, risk, goal, ranked_state, investor_state, property_state], ) quick_event = quick_event.then( fn=render_representative_investor_profile, inputs=[max_budget, financing, liquidity, risk, goal], outputs=representative_profile_output, ) quick_event = quick_event.then( fn=generate_top_3_explanations, inputs=[investor_state, property_state], outputs=generation_state, ) quick_event.then( fn=render_part_4_results, inputs=[ranked_state, generation_state], outputs=full_output, ) quick_starter.change( fn=render_selected_example, inputs=quick_starter, outputs=selected_example_output, ) demo.queue().launch( share=False, debug=False, show_error=True, allowed_paths=[str(ASSET_DIR.resolve())], )
# ============================================================
# REMATCH - HUGGING FACE SPACE APP
# Keep generation.py and the assets folder beside this file.
# ============================================================
import html
import json
from pathlib import Path
from urllib.parse import quote
import gradio as gr
import numpy as np
import pandas as pd
import torch
from huggingface_hub import hf_hub_download
from torch import nn
from generation import generate_property_explanation
# Put the generated illustrative images in an `assets` folder beside this file.
# In a Hugging Face Space, upload the same folder to the repository root.
ASSET_DIR = Path("assets")
PROPERTY_IMAGES = {
"single_family": "illustrative_single_family_home.png",
"single_family_home": "illustrative_single_family_home.png",
"singlefamily": "illustrative_single_family_home.png",
"townhouse": "illustrative_townhouse.png",
"condo": "illustrative_condo.png",
"multi_family": "illustrative_multi_family.png",
"multifamily": "illustrative_multi_family.png",
"luxury_home": "illustrative_luxury_home.png",
}
DEFAULT_PROPERTY_IMAGE = "illustrative_default_property.png"
REMATCH_LOGO_URL = "/gradio_api/file=" + quote(
str((ASSET_DIR / "rematch_logo.png").resolve())
)
def property_image_url(property_type):
"""Return a Gradio-served URL for a generic illustrative property image."""
normalized_type = (
str(property_type or "")
.strip()
.lower()
.replace(" ", "_")
.replace("-", "_")
)
image_name = PROPERTY_IMAGES.get(normalized_type, DEFAULT_PROPERTY_IMAGE)
image_path = (ASSET_DIR / image_name).resolve()
return "/gradio_api/file=" + quote(str(image_path))
# Part 3 intentionally stays CPU-only.
DEVICE = torch.device("cpu")
print("Runtime device:", DEVICE)
# ============================================================
# LOAD APPROVED MODEL ARTIFACTS
# ============================================================
MODEL_REPO_ID = "omershahar/REmatch-DCN-v2"
MODEL_CONFIG_PATH = hf_hub_download(
repo_id=MODEL_REPO_ID,
filename="model_config.json",
)
VOCABULARY_PATH = hf_hub_download(
repo_id=MODEL_REPO_ID,
filename="preprocessor_vocabulary.json",
)
CHECKPOINT_PATH = hf_hub_download(
repo_id=MODEL_REPO_ID,
filename="dcn_v2_checkpoint.pt",
)
with open(MODEL_CONFIG_PATH, "r", encoding="utf-8") as file:
model_config = json.load(file)
with open(VOCABULARY_PATH, "r", encoding="utf-8") as file:
vocabulary_payload = json.load(file)
I = model_config["investor_cols"]
P = model_config["property_cols"]
F = model_config["feature_cols"]
assert F == I + P
assert vocabulary_payload["feature_cols"] == F
# ============================================================
# LOAD DATASET B DIRECTLY FROM HUGGING FACE DATASET REPO
# ============================================================
DATASET_REPO_ID = "omershahar/REmatch-Investment-Matching-Dataset"
DATASET_FILENAME = "rematch_properties.csv"