ai-real-estate-assistant

ai-real-estate-assistant

Advanced AI Real Estate Assistant using RAG, LLMs, and Python. Features market analysis, property valuation, and intelligent search.

Stars: 108

Visit
 screenshot

AI Real Estate Assistant is a modern platform that uses AI to assist real estate agencies in helping buyers and renters find their ideal properties. It features multiple AI model providers, intelligent query processing, advanced search and retrieval capabilities, and enhanced user experience. The tool is built with a FastAPI backend and Next.js frontend, offering semantic search, hybrid agent routing, and real-time analytics.

README:

๐Ÿ  AI Real Estate Assistant

AI-powered assistant for real estate agencies that helps buyers and renters find their ideal property.

Python FastAPI Next.js CI License

AI Real Estate Assistant (Docker Run)

๐ŸŒฟ Branching & Versioning

We follow a structured branching strategy. Active development happens in dev.

Branch Status Description
dev ๐Ÿ”ฅ Active Current Development. All new features and fixes land here.
main ๐ŸŸข Stable Production-ready releases.
ver4 ๐ŸŸก Legacy Previous V4 development branch (Frozen).
ver3 โ„๏ธ Archived Legacy Streamlit version.
ver2 โ„๏ธ Archived Early prototype.

Releases are tracked with tags (SemVer), e.g. v1.0.0.

๐ŸŒŸ Overview

The AI Real Estate Assistant is a modern, conversational AI platform helping users find properties through natural language. Built with a FastAPI backend and Next.js frontend, it features semantic search, hybrid agent routing, and real-time analytics.

Docs | User Guide | Backend API | Developer Notes | Troubleshooting | Testing | Contributing


โœจ Key Features

๐Ÿค– Multiple AI Model Providers

  • OpenAI: GPT-4o, GPT-4o-mini, O1, O1-mini
  • Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus
  • Google: Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0 Flash
  • Grok (xAI): Grok 2, Grok 2 Vision
  • DeepSeek: DeepSeek Chat, DeepSeek Coder, R1
  • Ollama: Local models (Llama 3, Mistral, Qwen, Phi-3)

๐Ÿง  Intelligent Query Processing

  • Query Analyzer: Automatically classifies intent and complexity
  • Hybrid Agent: Routes queries to RAG or specialized tools
  • Smart Routing: Simple queries โ†’ RAG (fast), Complex โ†’ Agent+Tools
  • Multi-Tool Support: Mortgage calculator, property comparison, price analysis

๐Ÿ” Advanced Search & Retrieval

  • Persistent ChromaDB Vector Store: Fast, persistent semantic search
  • Hybrid Retrieval: Semantic + keyword search with MMR diversity
  • Result Reranking: 30-40% improvement in relevance
  • Filter Extraction: Automatic extraction of price, rooms, location, amenities

๐Ÿ’Ž Enhanced User Experience

  • Modern UI: Next.js App Router with Tailwind CSS
  • Real-time: Streaming responses from backend
  • Interactive: Dynamic property cards and map views

๐Ÿ—๏ธ Architecture

flowchart TB
  subgraph Session["Chat Session (V4)"]
    Client["Next.js Frontend"] --> Req["POST /api/v1/chat"]
    Req --> DB["SQLite Persistence"]
    DB --> Agent["Hybrid Agent"]
    Agent --> VS["ChromaDB Vector Store"]
    Agent --> Tools["Tools (Calculator, Search)"]
  end

๐Ÿš€ Quick Start

๐Ÿณ Docker (Fastest Way)

The easiest way to run the full stack locally.

Requires: At least one external API key (OpenAI, Anthropic, Google, etc.)

# 1. Prepare environment
Copy-Item .env.example .env
# Edit .env to add your API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)

# 2. Run with Docker Compose (external AI models)
docker compose -f deploy/compose/docker-compose.yml up --build

# 3. Access
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000/docs

Optional: Local LLM with Ollama

Note: Local LLM with Ollama requires GPU for good performance.

# Run with Ollama for local models
docker compose -f deploy/compose/docker-compose.yml --profile local-llm up --build

๐Ÿ Manual Setup

1. Backend (FastAPI)

Windows (PowerShell)

git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
cd ai-real-estate-assistant

# Install uv (fast Python package manager)
pip install uv

# Create virtual environment and install dependencies
uv venv .venv
.\.venv\Scripts\Activate.ps1
uv pip install -e .[dev]

Copy-Item .env.example .env
# Edit .env and set provider API keys and ENVIRONMENT
# Set ENVIRONMENT="local"

python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

macOS/Linux

git clone https://github.com/AleksNeStu/ai-real-estate-assistant.git
cd ai-real-estate-assistant

# Install uv (fast Python package manager)
pip install uv

# Create virtual environment and install dependencies
uv venv .venv
source .venv/bin/activate
uv pip install -e .[dev]

cp .env.example .env
# Edit .env and set provider API keys and ENVIRONMENT
# Set ENVIRONMENT="local"

python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

2. Frontend (Next.js)

cd frontend
npm install
npm run dev

Open http://localhost:3000 (frontend). The backend runs at http://localhost:8000.

๐Ÿงช Testing

We use pytest for backend testing and jest for frontend testing.

# Backend Tests
python -m pytest tests/unit          # Unit tests
python -m pytest tests/integration   # Integration tests

# Frontend Tests
cd frontend
npm test

๐Ÿš€ Deployment

Quick Start

Component Platform Status
Frontend Vercel Automated from GitHub
Backend Render, Railway, Fly.io Manual deployment

Environment Variables Matrix

Environment NEXT_PUBLIC_API_URL BACKEND_API_URL
Local /api/v1 (uses Next.js proxy) http://localhost:8000/api/v1
Production /api/v1 (uses Next.js proxy) https://your-backend.com/api/v1

Key Security Design

  • API Access Key: Set in Vercel dashboard (server-side only), never exposed to browser
  • API Proxy: Frontend calls /api/v1/* which proxies to backend, injecting X-API-Key server-side
  • No Public Secrets: NEXT_PUBLIC_* variables never contain sensitive data

For complete deployment instructions, see DEPLOYMENT.md.


๐Ÿงน Maintenance

Code Quality

The project uses ruff for Python linting and formatting.

python -m ruff check .

Pre-Commit Hooks

This project includes a 3-layer pre-commit security system that runs automatically before each commit:

  1. Gitleaks - Secret scanning (API keys, passwords, tokens)
  2. Semgrep - SAST for Python security vulnerabilities (CI/CD only)
  3. Lint-staged - Frontend code quality (Prettier + ESLint)

Installation

# After cloning, install the hooks
pre-commit install

# Install required tools
scoop install gitleaks  # Windows (or use choco)
pip install semgrep     # Optional: for local SAST
npm install             # For lint-staged and prettier

Running Hooks Manually

# Test all files
pre-commit run --all-files

# Run on staged files (automatic before commit)
git commit

# Skip temporarily if needed
git commit --no-verify

Configuration Files

Local Security Scanning

For full CI/CD security parity, you can run all security checks locally:

# Run all security scans (Gitleaks, Semgrep, Bandit, pip-audit)
python security-scan.py

# Or use the direct path
python scripts/ci/security_local.py

# Run specific scan only
python security-scan.py --scan-only=secrets    # Gitleaks
python security-scan.py --scan-only=semgrep    # Semgrep SAST
python security-scan.py --scan-only=bandit     # Bandit Python security
python security-scan.py --scan-only=pip-audit  # Dependency vulnerabilities

# Quick mode (skip slower pip-audit scan)
python security-scan.py --quick

# Verbose output
python security-scan.py --verbose

Docker Fallback: On Windows, if Gitleaks or Semgrep binaries aren't installed, the script automatically uses Docker containers.

Tool Installation:

# Optional: Install tools locally for faster execution
scoop install gitleaks   # Windows (or brew install gitleaks on macOS)
pip install semgrep       # SAST scanning
pip install bandit        # Python security (already in dev dependencies)
pip install pip-audit     # Dependency auditing (already in dev dependencies)

โš™๏ธ Configuration

Core configuration is controlled via environment variables and .env:

# Required (at least one provider)
OPENAI_API_KEY="<OPENAI_API_KEY>"
ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
GOOGLE_API_KEY="<GOOGLE_API_KEY>"

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

# Optional
OLLAMA_BASE_URL="http://localhost:11434"
SMTP_USERNAME="..."
SMTP_PASSWORD="..."
SMTP_PROVIDER="sendgrid"

Frontend-specific variables (optional) go into frontend/.env.local.


๐Ÿค– Local Models (Ollama)

  1. Install Ollama: ollama.com
  2. Pull Model: ollama pull llama3.3
  3. Configure: Set OLLAMA_BASE_URL="http://localhost:11434" in .env
  4. Select: Choose "Ollama" in the frontend provider selector.

๐Ÿงช Development & Testing

  • Backend Tests: pytest
  • Frontend Tests: cd frontend; npm test
  • Linting: ruff check . (Python), npm run lint (Frontend)

See docs/testing/TESTING_GUIDE.md for details.


๐Ÿš€ One-Command Start (Docker)

# CPU
.\scripts\dev\run-docker-cpu.ps1

# GPU (if available)
.\scripts\dev\run-docker-gpu.ps1

# GPU + Internet web research (starts the `internet` compose profile)
.\scripts\dev\run-docker-gpu-internet.ps1

If you prefer a single entrypoint:

.\scripts\dev\start.ps1 --mode docker --docker-mode auto
.\scripts\dev\start.ps1 --mode docker --docker-mode gpu --internet

๐Ÿ—„๏ธ Optional Redis (MCP/Caching)

For MCP tooling or future caching/session features, a local Redis service is included in Docker Compose.

# Start only Redis
docker compose up -d redis

# Or start all services (backend, frontend, redis)
docker compose up -d --build

Configure clients via:

REDIS_URL="redis://localhost:6379"

๐Ÿค Contributing

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

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/short-description)
  3. Run checks locally
  4. Commit using the format type(scope): message [IP-XXX]
  5. Open a Pull Request against main

๐Ÿ”ง Troubleshooting

See docs/development/TROUBLESHOOTING.md for detailed help.

Common Issues

Port already in use (8000):

netstat -ano | findstr :8000
taskkill /PID <PID> /F

API Key not recognized:

  • Ensure .env file is in project root
  • Restart the application after editing .env

๐Ÿ“„ License

This project is licensed under the MIT License โ€” see the LICENSE file for details.


๐Ÿ‘ค Author

Alex Nesterovich


๐Ÿ™ Acknowledgments


๐Ÿ“ž Support

For questions or issues:


โญ Star this repo if you find it helpful!

Made with โค๏ธ using Python, FastAPI, and Next.js

Copyright ยฉ 2026 Alex Nesterovich

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for ai-real-estate-assistant

Similar Open Source Tools

For similar tasks

For similar jobs