How aleksnestu/ai-real-estate-assistant works
Project Type & Purpose
• This is a full-stack, conversational AI web application (“AI Real Estate Assistant”) built in Python.
• Purpose: Leverage Retrieval-Augmented Generation (RAG) with LLMs and structured CSV real-estate data to answer user questions and recommend properties via a Streamlit UI.
File Structure Analysis
• Top-level apps:
• app.py (V1: pandas DataFrame agent)
• app_v2.py (V2: RAG with ConversationalRetrievalChain)
• streaming.py (streaming utilities for UI responses)
• Modules:
• ai/agent.py: core agent abstraction and LLM orchestration
• data/csv_loader.py: CSV loading & normalization
• common/cfg.py: configuration management (API keys, env variables)
• dataset/pl/*.csv: sample property datasets
• utils.py & utils/*.sh: helper scripts, Docker/dev-container setup
• Config & deployment:
• .devcontainer/ & utils/run_* scripts for containerized dev
• Docker scripts under utils/
• CI configuration under .github/
Key Architecture from README
• Retrieval-Augmented Generation (RAG) pattern combining:
– Vector embeddings (FastEmbed)
– In-memory vector store (DocArrayInMemorySearch / ChromaDB)
– LangChain’s ConversationalRetrievalChain for multi-turn dialog
• Data pipeline: load CSV → normalize (Pandas) → embed → index → similarity search → LLM integration
• UI: Streamlit for rapid interactive web interface
Main Components
1. User & Streamlit UI Layer
– Browser → Streamlit app (app.py/app_v2.py)
2. Application Logic
– Conversational controller (streaming.py / langchain chains)
– Agent module (ai/agent.py)
3. Data Processing
– CSV Loader (data/csv_loader.py)
– Pandas normalization
4. Embedding Engine
– FastEmbed (in-process library)
5. Vector Store
– DocArrayInMemorySearch or ChromaDB (in-memory vector DB)
6. LLM Providers
– External: OpenAI GPT API (cloud)
– Local: Llama models (optional)
7. Configuration & Utilities
– common/cfg.py (env variables, API keys)
– utils scripts & dev-container for deployment
Relationships & Data Flow
• User submits query → Streamlit UI → Agent
• Agent calls LLM (OpenAI/Llama) for intent extraction → returns structured preferences
• Agent loads/ensures data is indexed:
– CSV Loader → Pandas DF → embeddings via FastEmbed → stored in vector store
• Agent queries vector store for similarity search → retrieves top-k property records
• Agent invokes LLM again (RAG) to generate conversational response with retrieved data
• Response returned to Streamlit UI → displayed to user
Architectural Patterns & Principles
• Modular Monolith: clear separation across modules (UI, AI, Data, Config)
• RAG Pattern: retrieval (vector DB) + generation (LLM)
• SRP & Open/Closed: data loader, agent, and config follow single-responsibility and are extensible
• DevOps: containerized dev (.devcontainer), Docker deployment, CI via GitHub