🏠 AI Real Estate Assistant

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

If you find my tools helpful and want to support the development of practical, open-source AI systems, you can contribute here:

5-Minute Quickstart → — Clone, configure, Docker up. Running in 5 minutes.

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

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

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

• 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)

• 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

• 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

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

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

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:3082
# Backend API: http://localhost:8082/docs

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

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

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

cd apps/web
npm install
npm run dev

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

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

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

• 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.

The project uses ruff for Python linting and formatting.

python -m ruff check .

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)

# 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

# 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

• .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

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-    # Gitleaks
python scripts/security/local_scan.py --scan-    # Semgrep SAST
python scripts/security/local_scan.py --scan-     # Bandit Python security
python scripts/security/local_scan.py --scan-  # 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)

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.

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.

• 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.

# 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

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"

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

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

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

This project is licensed under the MIT License — see the LICENSE file for details.

Alex Nesterovich

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

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

If you find this project useful, you can support its development:

• GitHub Sponsors — best for long-term support and roadmap work
• Ko-fi — best for a one-time “thank you”
• Buy Me a Coffee — one-time support for API/compute costs

Suggested donation message: “Support new market-analysis prompts and property evaluation workflows.”

Need help with installation, deployment, customization for your agency, or CRM integration (Bitrix24, amoCRM, custom pipelines)?

• Start a Discussion with the prefix: [Commercial]
• Contact the author via the links on the GitHub profile

For questions or issues (community support):

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