push

README.md

@@ -198,43 +198,55 @@ residential-architecture-assistant/
 
 ## 🚀 **Getting Started**
 
+### **🤗 Hugging Face Spaces Deployment**
+
+This application is ready for **one-click deployment** to Hugging Face Spaces:
+
+#### **Option 1: Direct Hugging Face Spaces Deployment**
+1. **Fork/Clone** this repository to your GitHub account
+2. **Create a new Space** on [Hugging Face](https://huggingface.co/spaces)
+3. **Select Gradio** as the SDK
+4. **Connect your GitHub repository** to the Space
+5. **Deploy automatically** - Hugging Face will use `app.py` and `requirements.txt`
+
+#### **Option 2: Quick Deploy Button**
+[![Deploy to Hugging Face Spaces](https://huggingface.co/datasets/huggingface/badges/raw/main/deploy-to-spaces-md.svg)](https://huggingface.co/spaces/new?template=gradio&sdk=gradio&filename=app.py)
+
 ### **System Requirements**
 
 ```bash
-# Core Dependencies
+# Core Dependencies (All included in requirements.txt)
 Python >= 3.8
-OpenAI API Access
-LangGraph >= 0.0.40
-LangChain >= 0.1.0
+OpenAI API Access (User provides their own key)
+LangGraph >= 0.2.0
+LangChain >= 0.3.0
 Gradio >= 4.0.0
 
 # Essential Dependencies
 python-dotenv >= 1.0.0  # Environment management
 ```
 
-### **Installation & Setup**
+### **Local Installation & Setup**
 
 ```bash
 # 1. Clone the repository
 git clone https://github.com/ZeruiW/Home_Design_Agent.git
 cd Home_Design_Agent
 
-# 2. Create virtual environment or Conda (recommended)
+# 2. Create virtual environment (recommended)
 python -m venv venv
 source venv/bin/activate  # On Windows: venv\Scripts\activate
 
 # 3. Install dependencies
 pip install -r requirements.txt
 
-# 4. Configure environment
-cp .env.example .env
-# Edit .env and add: OPENAI_API_KEY=your_openai_api_key_here
+# 4. Launch for Hugging Face Spaces (main app)
+python app.py
+# → Opens http://localhost:7860
 
-# 5. Launch production interface
+# 5. Alternative: Launch full-featured local version
 python gradio_app.py
-# → Opens http://localhost:7860 or 7861 or 7862 (auto port detection) 
-
-
+# → Opens http://localhost:7862 (with user state management)
 ```
 
 ### **Alternative Launch Methods**
@@ -243,6 +255,8 @@ python gradio_app.py
 # Command Line Interface (for debugging)
 python main.py
 
+# Full multi-user interface (local development)
+python gradio_app.py
 ```
 
 ---
@@ -411,13 +425,58 @@ routing_map = {
 
 ---
 
+## 🚀 **Hugging Face Spaces Configuration**
+
+### **Deployment Files**
+
+This repository includes everything needed for Hugging Face Spaces deployment:
+
+```bash
+📁 Required Files for HF Spaces:
+├── app.py              # Main Gradio app (HF Spaces entry point)
+├── requirements.txt    # Python dependencies 
+├── README.md          # Space documentation (this file)
+└── graph.py           # Core LangGraph architecture
+└── agents.py          # Multi-agent system
+└── state.py           # State management
+└── user_state_manager.py  # User persistence
+└── detailed_budget_agent.py  # Specialized agents
+```
+
+### **Space Configuration**
+
+**Recommended Hugging Face Space Settings:**
+- **SDK**: Gradio
+- **Python Version**: 3.9+
+- **Hardware**: CPU (Basic) - sufficient for this application
+- **Visibility**: Public (users provide their own OpenAI API keys)
+- **License**: MIT
+
+### **Environment Variables (Optional)**
+
+For enhanced functionality, you can set these in your Space settings:
+
+```bash
+# Optional: Default values (users still need to provide their API key)
+OPENAI_API_KEY=""  # Users provide their own key via UI
+```
+
+### **Usage in Hugging Face Spaces**
+
+1. **Users visit your Space**
+2. **Enter their OpenAI API key** (securely handled, not stored)
+3. **Initialize the assistant** with one click
+4. **Start their architecture consultation**
+
+---
+
 ## 📊 **Production Deployment**
 
 ### **Performance Metrics**
 
 - **Response Time**: < 3 seconds for routine consultations
 - **Agent Coordination**: < 5 seconds for multi-agent workflows
-- **State Persistence**: 100% conversation continuity across sessions
+- **State Persistence**: Session-based (in HF Spaces) / Full persistence (local)
 - **Error Rate**: 0% (all NoneType issues resolved)
 - **Reliability**: 7/7 agents fully operational
 
@@ -425,7 +484,7 @@ routing_map = {
 
 - **Stateless Agents**: Support horizontal scaling
 - **JSON Storage**: Easily upgradeable to database systems
-- **Multi-User Support**: Complete data isolation between users
+- **Multi-User Support**: Session isolation in HF Spaces
 - **API-Ready**: Agents exportable as REST/GraphQL endpoints
 
 📄 **License & System Information**