Requirements And Records

These models are the shared data shapes used by extraction, matching, and API responses. They intentionally keep raw owner, tenant, and token data out of the matching layer.

class app.alba_core.models.RentalRequirements(city: str | None = None, suburb_preferences: list[str] = <factory>, budget_max: float | None = None, budget_min: float | None = None, bedrooms_min: int | None = None, bathrooms_min: int | None = None, parking_min: int | None = None, property_type: str | None = None, move_in_timing: str | None = None, priority: str | None = None, pets_required: bool | None = None, furnished_required: bool | None = None, features: list[str] = <factory>, no_preference: list[str] = <factory>)

Structured version of a renter’s request.

The extractor fills this from plain English. Fields ending in _min or _max become hard matching rules when present. features and priority are softer ranking hints.

property is_search_ready: bool

True when the minimum useful matching inputs are known.

merge(patch: RentalRequirements) → RentalRequirements

Merge newly extracted values over an existing conversation state.

property missing_required_fields: list[str]

Fields needed before Alba Core can call the search complete.

to_dict() → dict[str, Any]

Return a JSON-friendly representation for API responses.

Example: merge conversation turns

from app.alba_core.models import RentalRequirements

first_turn = RentalRequirements(city="Auckland", budget_max=5000)
second_turn = RentalRequirements(bedrooms_min=4, property_type="house")

requirements = first_turn.merge(second_turn)

print(requirements.is_search_ready)
print(requirements.to_dict())

class app.alba_core.models.PropertyRecord(property_id: str, address: str, suburb: str | None, city: str | None, region: str | None, postcode: str | None, property_type: str | None, rent_pw: float | None, bedrooms: int | None, bathrooms: int | None, parking_spaces: int | None, availability: str | None, available_from: date | None, furnishing: str | None, pets: str | None, smoker: str | None, pool: str | None, spa: str | None, view_type: str | None, description: str | None, listing_url: str | None = None)

Privacy-shaped property record used by the matcher.

This model contains only fields Alba Core needs. Raw owner, tenant, and token details should never be mapped into this object.

to_public_dict() → dict[str, Any]

Serialize for API output, converting date objects to ISO strings.

Example: public API output

from app.propertyme.cache import load_property_cache

properties = load_property_cache("data/propertyme_property_seed_latest.json")
public_property = properties[0].to_public_dict()

print(public_property["address"])
print(public_property["rent_pw"])

class app.alba_core.models.MatchResult(property: PropertyRecord, score: float, hard_filter_reasons: list[str] = <factory>, match_notes: list[str] = <factory>, score_breakdown: dict[str, float]=<factory>)

A matched property plus score and explanation notes.

to_dict() → dict[str, Any]

Return the public response shape used by API and smoke tests.

Example: serialise a match result

from app.alba_core.matching import PropertyMatcher
from app.alba_core.models import RentalRequirements
from app.propertyme.cache import load_property_cache

properties = load_property_cache("data/propertyme_property_seed_latest.json")
requirements = RentalRequirements(city="Auckland", budget_max=5000, bedrooms_min=4)

match = PropertyMatcher().match(requirements, properties).matches[0]
print(match.to_dict())

app.alba_core.models.clean_text(value: Any) → str | None

Return compact display text or None.

Empty strings create subtle bugs in matching, so Alba Core normalises them to None as early as possible.