🏠 AI Real Estate Assistant

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

🌿 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

Loading

---

🚀 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 apps/web
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
cd apps/api
python -m pytest tests/unit          # Unit tests
python -m pytest tests/integration   # Integration tests

# Frontend Tests
cd apps/web
npm test

Using Makefile

For quick commands, use the Makefile:

make help        # Show all available commands
make test        # Run all tests
make lint        # Run linting
make security    # Run security scans
make dev         # Start development servers
make docker-up   # Start Docker containers
make ci          # Run full CI locally

---

🚀 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

• .gitleaks.toml - Secret detection rules
• semgrep.yml - Security scanning rules
• .pre-commit-config.yaml - Hook configuration
• .prettierrc - Code formatting config
• package.json - lint-staged configuration

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 scripts/security/local_scan.py

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

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

# Verbose output
python scripts/security/local_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: cd apps/api && pytest
• Frontend Tests: cd apps/web && npm test
• Linting: cd apps/api && ruff check . (Python), cd apps/web && npm run lint (Frontend)
• Security: python scripts/security/local_scan.py

See docs/testing/TESTING_GUIDE.md for details.

---

🚀 One-Command Start (Docker)

# CPU
.\scripts\docker\cpu.ps1

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

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

If you prefer a single entrypoint:

python scripts/start.py --mode docker --docker-mode auto
python scripts/start.py --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

• GitHub: @AleksNeStu
• Repository: ai-real-estate-assistant

---

🙏 Acknowledgments

• LangChain for the AI framework
• FastAPI for the backend
• Next.js for the frontend
• OpenAI, Anthropic, Google for AI models
• ChromaDB for vector storage

---

📞 Support

For questions or issues:

• Create an Issue
• Check existing Discussions
• Review the PRD for detailed specifications

---

⭐ Star this repo if you find it helpful!

Made with ❤️ using Python, FastAPI, and Next.js

Copyright © 2026 Alex Nesterovich