内容摘录
🏠 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
---
🚀 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.)
Optional: Local LLM with Ollama
**Note:** Local LLM with Ollama requires GPU for good performance.
🐍 Manual Setup
Backend (FastAPI)
Windows (PowerShell)
macOS/Linux
Frontend (Next.js)
Open http://localhost:3000 (frontend). The backend runs at http://localhost:8000.
🧪 Testing
We use pytest for backend testing and jest for frontend testing.
Using Makefile
For quick commands, use the Makefile:
---
🚀 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.
Pre-Commit Hooks
This project includes a 3-layer pre-commit security system that runs automatically before each commit:
**Gitleaks** - Secret scanning (API keys, passwords, tokens)
**Semgrep** - SAST for Python security vulnerabilities (CI/CD only)
**Lint-staged** - Frontend code quality (Prettier + ESLint)
Installation
Running Hooks Manually
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:
**Docker Fallback:** On Windows, if Gitleaks or Semgrep binaries aren't installed, the script automatically uses Docker containers.
**Tool Installation:**
---
⚙️ Configuration
Core configuration is controlled via environment variables and .env:
Frontend-specific variables (optional) go into frontend/.env.local.
---
🤖 Local Models (Ollama)
**Install Ollama**: ollama.com
**Pull Model**: ollama pull llama3.3
**Configure**: Set OLLAMA_BASE_URL="http://localhost:11434" in .env
**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)
If you prefer a single entrypoint:
---
🗄️ Optional Redis (MCP/Caching)
For MCP tooling or future caching/session features, a local Redis service is included in Docker Compose.
Configure clients via:
---
🤝 Contributing
Contributions are welcome. See CONTRIBUTING.md for the full workflow.
Fork the repository
Create a feature branch (git checkout -b feature/short-description)
Run checks locally
Commit using the format type(scope): message [IP-XXX]
Open a Pull Request against main
---
🔧 Troubleshooting
See docs/development/TROUBLESHOOTING.md for detailed help.
Common Issues
**Port already in use (800…