AI Real Estate Assistant – Overview

What it is – An open‑source, AI‑powered web app that lets users search for homes, chat with a virtual assistant, and run financial‑analysis tools – all by typing natural‑language queries like “2‑bedroom apartment in Kraków under 500 k”. The core product is a FastAPI backend (Python 3.12+) that talks to up to 16 LLM providers, a ChromaDB vector store for semantic search, and a PostgreSQL/SQLite database for the property catalogue. A Next.js 16 + React 19 frontend provides the UI, maps, and analytics dashboards.

---

📦 Core Features (as described in the README)

Feature	What you get	How it works (high‑level)
Natural‑language property search	Type a sentence and receive a list of matching listings.	The request is parsed by a Query Analyzer which decides whether a simple vector‑search (ChromaDB) or a more complex RAG/agent flow is needed.
AI‑driven chat assistant	Conversational UI for asking follow‑up questions about listings, neighborhoods, etc.	The backend routes the conversation to the selected LLM provider; fallback chaining guarantees a response even if one provider is down.
Valuation & price‑forecast (v5.1)	Enter a property ID (or manual features) → current value + 1‑, 3‑, 5‑, 10‑year forecast with confidence band.	A specialised LLM prompt feeds property attributes into a valuation model; the result is returned as a JSON payload for the UI.
Neighborhood one‑liner (v5.1)	2‑3 sentence AI summary of the area’s character, lifestyle and transport links.	Same LLM routing, but with a concise prompt that pulls from the vector store’s neighbourhood documents.
Financial calculators	Mortgage, rent‑vs‑buy, ROI, total‑cost‑of‑ownership, CMA reports.	Pure Python calculations; UI displays results alongside listings.
Interactive maps	Clustered property markers, area analytics, city‑overview maps.	Front‑end uses Mapbox/Leaflet; backend supplies GeoJSON from the DB.
Multi‑provider LLM routing	16 providers (OpenAI, Anthropic, Google, Grok, DeepSeek, OpenRouter, Together AI, Fireworks AI, HuggingFace, Groq, Mistral, Qwen, ZAI, Moonshot, OpenCode, local Ollama).	apps/api/models/provider_factory.py builds a fallback chain; per‑request provider can be forced via header/parameter.
9‑language localisation	UI and AI outputs in English, Polish, Russian, German, Spanish, Italian, Portuguese, Turkish, Ukrainian.	Locale files are shipped with the Next.js app; AI prompts include language tags for compliance with the EU AI Act.
Enterprise‑grade security	Rate‑limiting, audit logs, SSRF protection, API‑Key + JWT auth, CI security scans.	Implemented in FastAPI middleware and GitHub‑Actions hardening steps.
Demo‑mode	Live demo (render.com) works without any API keys – AI responses are simulated for instant exploration.	A flag in the config switches the provider factory to a mock provider that returns canned answers.

---

🏗️ Architecture Snapshot

Next.js Frontend  <--->  API Proxy  <--->  FastAPI Backend
                                   │
                                   ├─ Query Analyzer → RAG Engine (ChromaDB) or Hybrid Agent
                                   ├─ Tools (LangChain wrappers)
                                   └─ LLM Providers (16 options)

Database: PostgreSQL/SQLite for relational data
Vector Store: ChromaDB for semantic embeddings + MMR reranking

The diagram in the README (Mermaid) shows the same flow, with the UI calling an API proxy that forwards to FastAPI, which then decides whether to use a simple RAG pipeline or a more complex agent‑tool chain.

---

🚀 Getting Started (quick‑start)

1. Clone & start Docker (Windows PowerShell recommended)

   git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
   cd ai-real-estate-assistant
   .\start-docker.ps1   # launches DB, vector store, API & web containers
   

   Frontend: http://localhost:3082 Backend: http://localhost:8082/docs

2. Or run manually Backend – create a virtual‑env, uv pip install -e "[dev]", then uvicorn api.main:app --reload. Frontend – npm install && npm run dev inside apps/web.

3. Demo mode – No LLM API keys are required; the app uses a mock provider that returns pre‑generated answers. For production, set your provider keys in the .env file (see deploy/compose/.env.example).

---

📚 Documentation & Resources

Area	Where to look
Architecture details	docs/architecture/large-saas-overview.md
Local demo setup	scripts/demo/README.md (PowerShell scripts for Docker launch, data generation, shutdown)
API reference	Swagger UI at http://localhost:8082/docs (FastAPI auto‑docs)
Frontend components	apps/web/src/components/ – e.g., onboarding tour, search bar, map widgets
Release notes	CHANGELOG.md – latest v5.1 adds valuation, inline payments, neighbourhood one‑liner
Roadmap	docs/roadmap.md (future features such as live MLS feeds, AI‑CRM, multi‑agent OS)

---

🛠️ Tech Stack (as listed)

• Backend – FastAPI (Python 3.12+), Pydantic, SQLAlchemy, uvicorn
• Frontend – Next.js 16, React 19, TypeScript 5.x, Tailwind (implied by UI)
• Vector DB – ChromaDB (semantic search + Max‑Marginal‑Relevance reranking)
• Relational DB – PostgreSQL (default) with SQLite fallback for quick demos
• LLM Providers – 16 major commercial APIs + local Ollama; routing handled by a custom factory
• Containerisation – Docker & Docker‑Compose; Render free‑tier used for the public demo
• CI/CD – GitHub Actions (unit tests, security scans, Docker image build, Render deploy)
• Monitoring – Uptime Kuma + structured logs

---

📈 Project Health

• Stars / forks – visible on the GitHub badge; the repo has a modest but active community (7 contributors, >1 k commits).
• Testing – >7 000 tests (backend + frontend) run in CI; the README mentions a full test suite.
• Release cadence – Frequent patch releases (e.g., Sep 2026 CVE fixes) and feature releases (v5.1).
• Memory optimisation – Lazy provider loading when deployed on Render’s 512 MiB free tier; otherwise eager loading on VPS/Docker.

---

🎯 Who Might Use This?

• Developers who want a starter SaaS‑style AI‑augmented real‑estate platform they can self‑host or extend.
• Product teams looking for a reference implementation of multi‑provider LLM routing, hybrid RAG/agent pipelines, and multilingual AI output.
• Researchers interested in evaluating LLM‑driven valuation or neighbourhood‑description prompts on a realistic property dataset.

---

📌 Bottom Line

ai-real-estate-assistant is a genuine, full‑stack AI application that combines natural‑language search, conversational assistants, and financial analytics for real‑estate listings. Its architecture, multi‑provider routing, and demo‑ready deployment make it a solid example of modern LLM‑augmented SaaS, and the repository provides everything needed to run it locally or spin up a production‑grade instance.