Məskən — harada yaşamalı, rəqəmlərlə

Məskən helps a home buyer in Azerbaijan pick an area, not just a flat. You write one sentence ("Nərimanovda metroya yaxın ev lazımdır"). An AI decision engine turns it into constraints. Deterministic code then ranks 87 regions, 3,700 micro-areas (an H3 honeycomb cut to each district's shape) and 1,284 villages against them, and AI explains each recommendation with real numbers. A confidence score, computed by code rather than the model, says how much to trust the answer.

Live demo: https://meskan-seven.vercel.app (app: /xerite, tests: /keyfiyyet) · UI language: Azerbaijani · AI: Google Gemini (flash models, free tier) · Tests: /keyfiyyet

Landing: one sentence in	Decision engine: 5 micro-areas, confidence, map pins	Quality tests on /keyfiyyet

---

1. Value for the user

Who: a first-time buyer family in Baku (two adults and a child, budget ~150–200k ₼, one parent commuting). Outcome: a shortlist of 5 concrete micro-areas in about 2 minutes, each with metro walking distance, the nearest school and kindergarten, a price and its source, plus a legal-risk check of the listing they are about to call.

Why this is needed (sourced):

Figure	Source
New-build prices +12.4% y/y (Q2 2026); all housing +8.6%	Central Bank review via JAM News, 31.08.2026
Wages +7%, so prices outpace income	same
2.8× price gap between Baku districts (Səbail 4,132 ₼/m², Pirallahı 1,452 ₼/m²)	Caliber.az, 30.09.2026
21% of 100,436 Baku listings state "Çıxarış: yoxdur" (no property deed)	bina.az listings dataset, Oct–Nov 2024 (aggregated by us, see §4)

The three questions a buyer can't answer today: Which area suits me? What is the real price? Is there a legal risk? Listing sites show flats, maps show places, and nobody joins them up for a decision.

User interviews / timing test: <!-- TODO: 3 participants, manual bina.az + Google Maps vs Məskən, minutes + quotes (template on /keyfiyyet) -->

2. Prototype & AI

Core scenario: "Nərimanovda metroya yaxın ev lazımdır" → 5 micro-areas around Nəriman Nərimanov, Gənclik, Bakmil and other stations. Each shows walking distance to the metro (e.g. 540 m), school distance, the count of groceries and pharmacies, the price per m² with its badge, a trade-off, and "bina.az / tap.az" search links. Confidence is 60/100 ("orta"), with a breakdown. The answer ends with one clarifying question: "Büdcən nə qədərdir?" The map flies to the 5 numbered, pulsing pins.

Decision-engine pipeline (/api/decide)

flowchart LR
  Q[User sentence] --> I["1 INTENT (Gemini, JSON schema)<br/>goal · type · budget · locations from a 248-item catalog<br/>hard constraints · soft weights · missing fields"]
  I -->|AI unavailable| K[keyword-rule fallback]
  I --> R["3 RETRIEVE (code)<br/>filter 3,700 hex pieces / 1,284 villages / 87 regions by hard constraints<br/>relax if empty · score by weights · diversity"]
  K --> R
  R --> E["4 EXPLAIN (Gemini, grounded)<br/>only the candidates' JSON · why + trade-off per area"]
  R --> C["5 CONFIDENCE (code, never AI)<br/>coverage 40 · intent completeness 25<br/>#1–#2 margin 20 · constraints met 15"]
  E --> U[Answer + map pins + clarifying question]
  C --> U

What the AI adds over a rule baseline (measured, see §3): it resolves place names with typos and slang ("nerimanovda kiraye") and catches implicit legal risk ("sənədlər sonra düzələcək"): 100% recall vs 58% for keyword rules. The LLM never ranks and never computes the confidence score. Ranking is reproducible code, which keeps the AI honest.

Other AI features: precomputed area profiles for 87 regions (quality-gated, regenerated automatically when the data changes), a legal check of pasted listings, 2–3-area comparison, and "Sənin üçün" fit explanations.

Data features: a choropleth map at two levels (8 metrics), H3 micro-area layer, region panel with 6 chart tabs (prices, services per 10k vs median, transport, road surface, nature and climate, a 7-index radar plus "similar but cheaper"), 10-year true-cost calculator (price + commute money and time), and a business-gap finder.

3. Quality testing

All tests live in /evals, write public/data/evals.json, and are shown on /keyfiyyet. Gemini runs on the free tier, sequentially, and cached cases are never re-run.

Eval	What	Result
Intent (20 Azerbaijani queries, incl. 3 vague and 2 slang/typo)	per-field accuracy, AI pipeline vs keyword rules	location 95% vs 80%, budget 100% vs 90%, goal 100 vs 95, constraints 100 vs 100, property type 95 vs 100
Legal check (18 listings: 6 clean, 12 risky incl. implicit)	precision / recall	AI P 86% / R 100% · rules P 100% / R 58%
Grounding (29 AI area profiles, 639 numbers)	every number must exist (±1%) in the input JSON	99.8% grounded (was 93.8% before the stale-profile fix below)
Retrieval (10 queries with hard constraints)	100% of returned areas satisfy them	10/10
Data sanity (16 checks)	completeness, NaN, plausibility, metro vs official list, outliers, honeycomb pieces inside districts and area sums	16/16

The AI pipeline adds a deterministic step that normalises location ids: it drops unknown ids, maps az-X to bk-X, and drops az-baki when a district is named. Without it, location accuracy was 75% (failure #6).

Failure analysis (6 real bugs, input → wrong output → cause → fix):

1. Xankəndi topped every ranking. The 409 OSM POIs are mapped for the pre-2023 city (~55k residents), but DSK 2026 counts 4,400. That gives 47.7× the median per capita, so every index hit 99. Fix: a generic rule (>10× median ⇒ per-capita values become null, with a warning) and a data-sanity guard.
2. A non-existent metro station was recommended ("20 Sentyabr"). OSM tags depots, exits and planned stations as station=subway (33 vs 27 real). Fix: validate against the 27-station list.
3. Stale AI numbers (6.2% ungrounded). Profiles were written before fix #1 changed the percentiles. Fix: an input hash per profile, so changed data triggers regeneration. Grounding went from 93.8% to 99.8%.
4. NaN confidence. Operator precedence (s + x ?? 0). Fixed.
5. Fallback model dropped Azerbaijani letters. Fix: a profile quality gate (length, ≥6 numbers, forbidden generic phrases, ə/ğ/ı/ş present).
6. The model invented location ids (az-nerimanov), or added az-baki, which widened the search to the whole city. Fix: deterministic normalisation. Location accuracy went from 75% to 95%.

4. Feasibility

Data	Status	Source	Needed for production
Boundaries, POIs, metro, stops, routes, roads, land cover	real	OpenStreetMap (Geofabrik, osmium)	monthly refresh job
Population 01.01.2026	official	DSK table 1.15	yearly
Elevation, climate 2025, PM2.5 (model)	real / model	Open-Meteo (Copernicus DEM, ERA5, CAMS)	none
Prices	61 real (54 sample medians from 95,632 listings + 7 published figures) · 40 demo	bina.az listings dataset (Oct–Nov 2024; supplied by the user, collected by a third party; we don't scrape, only aggregates are stored) + press	price-data partnership (portal API, banks, Chamber of Appraisers)
Metro validation	real	27 operating stations (Wikipedia list; metro.gov.az unreachable)	official GTFS
Legal texts	not yet	e-qanun.az	lawyer-reviewed corpus

Running cost (measured): on average 2,027 input + 386 output tokens per AI call (37 calls measured). A session of ~4 calls (decide = intent + explain, a follow-up, a legal check) costs $0.006 at gemini-3.7-flash list prices (third-party tracker; $0.375 / $1.88 per 1M) to $0.026 at the conservative 3.5-flash price ($1.50 / $9). That is $6–26 per 1,000 users. The free Gemini tier covers the demo, and the sha256 cache makes repeated questions free. Hosting is free (Vercel; data is static, ~1.6 MB).

Limitations: most rayons have no price; OSM is thin outside cities (16 of 87 areas have low coverage, shown in the UI); hex prices come from 2024 listings (+8–12%/yr since); commute times are straight-line × 1.4 with no traffic; PM2.5 is a model value.

Next step: a 4-week pilot with one Baku realtor (lead form + area report), a listing-data partnership to replace demo prices, and a monthly OSM refresh with the sanity evals as a gate.

Business model: free for buyers; B2B area reports and qualified leads for realtors and developers; mortgage-by-area analytics for banks; a premium legal check with partner notaries; service-gap reports for municipalities.

5. Originality

• Decision engine, not a chatbot. AI parses intent and explains, code ranks, and code computes confidence with a visible breakdown. No other tool here joins neighbourhood-level metrics to a buyer's sentence.
• Micro-areas. 3,700 H3 res-8 pieces in Baku, Sumqayıt and Gəncə — a honeycomb clipped to each district polygon (border cells split per district, slivers merged, verified: every piece inside its district, areas sum to ±1.6%), labelled with human names ("Nərimanov · Gənclik m. ətrafı"), with walking distance to a validated metro station and hex-level price medians where at least 5 listings exist. Outside these cities, 1,284 OSM towns and villages carry stats within 1.5 km ("Bakıdan kənarda dağ havası" returns "Şəki · Kiş", "Quba · Bəhrəli").
• Legal check of listing language, AI plus a deterministic detector, so known risk phrases are never missed.
• True cost over 10 years: a cheap flat far from work can cost more.
• Data honesty as a feature: every number has a badge (Canlı OSM, Rəsmi DSK, Nümunə, Mətbuat, Demo, Model), and we publish our own failures.

Architecture & run locally

flowchart LR
  A[Geofabrik PBF] -->|osmium| B[process-osm · build-hexes]
  C[DSK xls] --> D[fetch-dsk]
  E[Open-Meteo] --> F[fetch-meteo]
  L[listings CSV] --> M[import-listings: aggregates only]
  B & D & F & M --> H[build-data + score.ts]
  H --> P[ai-profiles · Gemini, hash-checked]
  P --> H
  H --> J[(public/data ≈1.6 MB)]
  J --> N[Next.js 16 · MapLibre · Recharts]
  N --> X[/api/decide · persona · ask · compare · legal-check/]
  X --> G[src/lib/ai.ts generateJSON → Gemini, cache]
  J --> T[evals/* → /keyfiyyet]

npm install
cp .env.example .env.local   # GEMINI_API_KEY
npm run dev                  # http://localhost:3000  (app: /xerite)
npm run check                # data-sanity + zod + next build
node --dns-result-order=ipv4first evals/run-evals.mjs all && node evals/build.mjs

Team: <names, roles> · Hackathon, October 2026.