🏠 AI Real Estate Assistant

AI-powered conversational platform for property search, analytics, and market insights.

📑 Table of Contents

• Live Demo
• Features
• Project Growth
• Architecture
• Quick Start
• Testing
• Documentation
• Roadmap
• Branches
• Deployment
• Configuration
• Contributing
• License

🌐 Live Demo

Experience the full power of AI-driven real estate search without any setup:

• 🔍 Natural Language Property Search — ask questions like "2-bedroom apartment in Kraków under 500k" and get matched listings
• 🤖 AI-Powered Chat — conversational interface for finding your perfect property
• 📊 Financial Tools — mortgage calculator, rent-vs-buy comparison, ROI analysis, and TCO calculator
• 🗺️ Interactive Maps — clustered property markers with area analytics
• 🌍 9 Languages — English, Polish, Russian, German, Spanish, Italian, Portuguese, Turkish, and Ukrainian

Note: The demo uses simulated AI responses for instant exploration. Production deployment requires API keys.

💻 Local Demo Setup

Run the full demo locally with comprehensive mock data in minutes:

# Step 1: Launch Docker containers (5-8 min)
.\scripts\demo\01-launch-docker.ps1

# Step 2: Generate comprehensive demo data (2-3 min)
.\scripts\demo\02-generate-data.ps1

# Access the demo
# Frontend: http://localhost:3082
# Backend:  http://localhost:8082
# API Docs: http://localhost:8082/docs

Demo Data Includes:

• 🏠 250+ properties across 5 Polish cities (Kraków, Warsaw, Gdańsk, Wrocław, Poznań)
• 👥 50 users with different roles
• 🔍 100 saved searches with diverse filters
• ⭐ 200 favorites across users
• 🏢 15 real estate agent profiles
• 📊 150 leads/inquiries
• 📈 300 activity events
• ⚙️ 40 preference profiles
• 📋 20 CMA reports

Stop the demo:

.\scripts\demo\03-stop-docker.ps1

→ Demo Setup Documentation — Complete guide with troubleshooting.

📸 Screenshots

Homepage · Search · Chat · Agents · Analytics

✨ Features

🤖 Multi-Provider AI

6+ LLM providers with intelligent routing — OpenAI, Anthropic, Google, Grok, DeepSeek, and local Ollama. Automatic fallback chain ensures reliability.

🔍 Smart Property Search

Natural language queries with automatic filter extraction. Hybrid semantic + keyword search powered by ChromaDB with MMR reranking for 30-40% better relevance.

📊 Analytics & Financial Tools

Mortgage calculator, rent-vs-buy comparison, investment ROI analysis, TCO calculator, and Comparative Market Analysis (CMA) reports.

🗺️ Interactive Maps

Mapbox/Leaflet maps with property clustering, area comparisons, and city-overview analytics.

🌍 9 Languages

English, Polish, Russian, German, Spanish, Italian, Portuguese, Turkish, and Ukrainian — with EU AI Act compliance labels.

🔒 Enterprise Security

OWASP-hardened with rate limiting, audit logging, SSRF protection, and dual-mode auth (API Key + JWT). Progressive 5-stage security pipeline with full scanning on all branches.

📈 Project Growth

GitHub Stats

Star Growth

Key Metrics

🏗️ Architecture

graph LR
    UI["Next.js Frontend"] --> Proxy["API Proxy"]
    Proxy --> API["FastAPI Backend"]
    API --> QA["Query Analyzer"]
    QA -->|Simple| RAG["RAG Engine"]
    QA -->|Complex| Agent["Hybrid Agent"]
    Agent --> Tools["Tools"]
    RAG --> VDB[("ChromaDB")]
    Tools --> LLM["AI Providers"]
    API --> DB[("PostgreSQL / SQLite")]

See docs/ARCHITECTURE.md for the full system design.

🚀 Quick Start

PowerShell Scripts (recommended for Windows)

# Clone and start demo mode (no API keys required)
git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
cd ai-real-estate-assistant
.\start-docker.ps1

# Stop: .\stop-docker.ps1
# Logs: .\logs-docker.ps1

Docker (manual)

git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
cd ai-real-estate-assistant
cp deploy/compose/.env.example deploy/compose/.env
# Edit deploy/compose/.env — demo mode enabled by default
docker compose -f deploy/compose/docker-compose.yml up --build
# Frontend: http://localhost:3082 · API: http://localhost:8082/docs

Manual

# Backend
cd apps/api && uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]" && python -m uvicorn api.main:app --reload --port 8000

# Frontend
cd apps/web && npm install && npm run dev
# Frontend: http://localhost:3000 · API: http://localhost:8000

5-Minute Quickstart → — Full setup with verification scripts.

🧪 Testing

Quick Commands

Windows:

.\scripts\testing\test-fast.ps1       # ⚡ Quick test (3-5 min) - during development
.\scripts\testing\test-ci.ps1         # 🔍 Full CI (8-12 min) - before commit
.\scripts\testing\test-all.ps1        # 🐛 See all failures - fixing multiple issues
.\scripts\testing\test-coverage.ps1   # 📊 Coverage report - before PR

Linux/macOS:

./scripts/testing/test-fast.sh        # ⚡ Quick test (3-5 min)
./scripts/testing/test-ci.sh          # 🔍 Full CI (8-12 min)
./scripts/testing/test-all.sh         # 🐛 See all failures
./scripts/testing/test-coverage.sh    # 📊 Coverage report

See Testing Guide for detailed usage.

Test Coverage

Performance: Tests run in parallel using pytest-xdist (local) and GitHub Actions matrix (CI).

📖 Documentation

🗺️ Roadmap

Upcoming Features

• Multi-Tenant Architecture — Complete data isolation with tenant-aware models and repositories
• Billing API — Stripe integration for subscription management and usage-based pricing
• Market Analytics Dashboard — Advanced charts and trends for real estate markets
• Mobile App — React Native application for iOS and Android
• Property Comparison Tool — Side-by-side property analysis
• Email Notifications — Alerts for price drops, new listings, and market updates
• API Rate Limiting — Per-user quotas and usage analytics

See GitHub Issues for planned features and discussions.

🌿 Branches

🚢 Deployment

• Staging: realestate-web-dz1y.onrender.com — auto-deploys from dev branch
• Production: deploys from main via deploy.yml workflow

Note: Render free tier services spin down after inactivity. First visit may take ~30-60s to cold start.

See Deployment Guide for Docker, Render, and Kubernetes setup.

⚙️ Configuration

# Required — at least one LLM provider
OPENAI_API_KEY="sk-..."
ANTHROPIC_API_KEY="sk-ant-..."
GOOGLE_API_KEY="AI..."

# Backend
ENVIRONMENT="local"
CORS_ALLOW_ORIGINS="http://localhost:3000"

# Optional
OLLAMA_BASE_URL="http://localhost:11434"    # Local models
ENABLE_JWT_AUTH="true"                      # User auth
REDIS_URL="redis://localhost:6379"          # Caching

See .env.example for the full list.

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for the workflow.

1. Fork → git checkout -b feature/short-description
2. Run checks locally (make ci)
3. Commit: type(scope): message
4. Open a PR against dev

📄 License

MIT License — see LICENSE.

💖 Support

If you find this project helpful:

🏠 Commercial Support

Need deployment help, customization, or CRM integration? Start a Discussion with [Commercial] prefix.