Skip to content

SETUP.md

Latest commit

 

History

History
599 lines (437 loc) · 11.9 KB

SETUP.md

File metadata and controls

599 lines (437 loc) · 11.9 KB

📖 Setup & Usage Guide

Complete guide to installing, configuring, and using the SmartHome Architect Agent.

📋 Table of Contents

  1. Installation
  2. Configuration
  3. Running the Agent
  4. Usage Patterns
  5. Advanced Features
  6. Troubleshooting
  7. Best Practices

🔧 Installation

Step 1: System Requirements

  • Python: 3.10 or higher
  • Operating System: Windows, macOS, or Linux
  • Memory: Minimum 4GB RAM
  • Internet: Required for API calls

Step 2: Check Python Version

python --version
# Should show: Python 3.10.x or higher

# If not installed, download from:
# https://www.python.org/downloads/

Step 3: Clone the Repository

git clone https://github.com/nobitanobi22/SmartHome-Architect-Agent.git
cd SmartHome-Architect-Agent

Step 4: Create Virtual Environment (Recommended)

# Create virtual environment
python -m venv venv

# Activate it
# On Windows:
venv\Scripts\activate

# On Mac/Linux:
source venv/bin/activate

Step 5: Install Dependencies

pip install -r requirements.txt

Requirements:

  • google-adk>=1.15.0 - Agent Development Kit
  • google-generativeai>=0.8.3 - Gemini API
  • python-dotenv>=1.0.0 - Environment management

⚙️ Configuration

Get Your API Key

  1. Go to Google AI Studio
  2. Click "Create API Key"
  3. Copy the generated key

Set Up Environment

Method 1: Environment Variable (Temporary)

# Mac/Linux
export GOOGLE_API_KEY="your_api_key_here"

# Windows Command Prompt
set GOOGLE_API_KEY=your_api_key_here

# Windows PowerShell
$env:GOOGLE_API_KEY="your_api_key_here"

Method 2: .env File (Recommended)

# Create .env file
echo 'GOOGLE_API_KEY=your_api_key_here' > .env

Or create .env manually:

GOOGLE_API_KEY=your_actual_api_key_here

Method 3: Python Script

import os
os.environ['GOOGLE_API_KEY'] = 'your_api_key_here'

Verify Installation

# test_setup.py
import google.generativeai as genai
from dotenv import load_dotenv
import os

load_dotenv()

api_key = os.getenv('GOOGLE_API_KEY')
if api_key:
    print("✅ API Key loaded successfully")
    genai.configure(api_key=api_key)
    print("✅ Gemini configured successfully")
else:
    print("❌ API Key not found")

Run it:

python test_setup.py

🚀 Running the Agent

Launch ADK Web Interface

adk web

What happens:

  1. ADK starts local web server (usually port 8000)
  2. Opens browser automatically
  3. Shows available agents

Select Agent

  1. In the browser interface, you'll see: "SmartHome Architect Agent"
  2. Click to load the agent
  3. Chat interface appears

Alternative: Command Line

# Run agent in terminal
adk run agent:root_agent

💬 Usage Patterns

Pattern 1: Current Room + Budget

Scenario: You have a room you want to renovate with a specific budget.

Step 1: Upload photo of your current room
Step 2: Type your request

Example:

User: "What can I improve in this kitchen with $20,000?"
[Upload: current_kitchen.jpg]

Agent Response:
✓ Analyzes your current space
✓ Identifies issues and opportunities
✓ Suggests budget-appropriate improvements
✓ Generates rendering showing renovation
✓ Provides budget breakdown
✓ Creates timeline and action plan

Pattern 2: Current Room + Inspiration

Scenario: You have a room and a Pinterest/magazine photo showing your desired style.

Step 1: Upload your current room photo
Step 2: Upload inspiration image
Step 3: Describe what you want

Example:

User: "Transform my bathroom to look like this modern spa style. What's the cost?"
[Upload 1: current_bathroom.jpg]
[Upload 2: inspiration_spa.jpg]

Agent Response:
✓ Analyzes current bathroom layout
✓ Extracts style elements from inspiration
✓ Identifies specific changes needed
✓ Estimates costs for transformation
✓ Generates rendering matching inspiration
✓ Provides complete renovation plan

Pattern 3: Text-Only Description

Scenario: No photos, but you have a clear vision.

Provide detailed description including:
- Room type and dimensions
- Current state
- Desired style
- Budget
- Specific preferences

Example:

User: "I want to renovate my 10x12 bedroom. Currently has beige carpet,
white walls, and basic lighting. I love modern minimalist style with
gray accent wall, hardwood floors, and better lighting. Budget is $12,000.
Can you create a plan and show me what it would look like?"

Agent Response:
✓ Creates design based on description
✓ Selects appropriate materials
✓ Generates photorealistic rendering
✓ Provides budget breakdown
✓ Suggests timeline

Pattern 4: Iterative Refinement

Scenario: You have a rendering but want to make changes.

After initial rendering:
Step 1: Request specific changes
Step 2: Agent updates rendering
Step 3: Repeat until satisfied

Example:

[After initial kitchen rendering generated]

User: "Make the cabinets cream instead of white"
→ Agent generates v2 with cream cabinets

User: "Add pendant lights over the island"
→ Agent generates v3 with pendant lights

User: "Change backsplash to subway tile"
→ Agent generates v4 with subway tile

All versions saved and tracked automatically.

🎯 Advanced Features

Version Control

Every rendering is automatically versioned:

kitchen_modern_v1.png  # Original
kitchen_modern_v2.png  # First edit
kitchen_modern_v3.png  # Second edit

List all versions:

User: "Show me all versions"
Agent: Uses list_renovation_renderings tool

Reference Image Management

# Agents automatically track:
- Current room photos
- Inspiration images
- Generated renderings
- Edit history

# You can reference any by name:
User: "Use the first inspiration image"
User: "Apply style from pinterest_modern.jpg"

Budget Optimization

User: "My budget is only $15k, show me what's possible"

Agent will:
✓ Prioritize high-impact changes
✓ Suggest cost-effective materials
✓ Phase renovation if needed
✓ Show must-haves vs nice-to-haves

Multi-Room Planning

User: "I want to renovate kitchen and bathroom. Kitchen budget: $25k,
bathroom budget: $12k. Can you plan both?"

Agent will:
✓ Create separate plans for each
✓ Consider shared contractors
✓ Optimize timeline for both
✓ Generate renderings for both

🔍 Understanding Agent Responses

Visual Assessor Output

ASSESSMENT COMPLETE

Images Provided:
- Current room photo: Yes - 10x12 kitchen with oak cabinets
- Inspiration photo: Yes - Modern farmhouse style

Room Details:
- Type: Kitchen
- Current Analysis: Dated oak cabinets, laminate counters, poor lighting
- Desired Style: Modern farmhouse with white shakers
- Key Issues: Outdated finishes, insufficient lighting
- Budget Constraint: $25,000

Design Planner Output

DESIGN COMPLETE

Renovation Scope: Moderate
Design Approach: Preserve layout

Materials Summary:
- Cabinets: Shaker style white (Benjamin Moore Simply White)
- Countertops: Carrara quartz
- Flooring: Light oak LVP
- Backsplash: White subway tile
- Hardware: Brushed nickel
- Lighting: Recessed LED + pendant over island

Project Coordinator Output

## Renovation Plan

Budget Breakdown:
- Materials: $12,500
- Labor: $9,800
- Permits/fees: $1,200
- Contingency (10%): $2,350
- **Total: $25,850**

Timeline: 8-10 weeks

## 🎨 Visual Rendering
[Photorealistic image generated]

## Action Checklist
1. Get 3 contractor quotes
2. Apply for permits
3. Order materials (4-week lead time)
4. Schedule installation

🛠️ Troubleshooting

Issue: "API Key not set"

Solution:

# Check if key is loaded
echo $GOOGLE_API_KEY  # Mac/Linux
echo %GOOGLE_API_KEY%  # Windows

# If empty, set it:
export GOOGLE_API_KEY="your_key"  # Mac/Linux
set GOOGLE_API_KEY=your_key       # Windows

Issue: "Import error: google.adk not found"

Solution:

# Ensure virtual environment is activated
# Then reinstall:
pip install --upgrade google-adk

Issue: "Image generation failed"

Possible causes:

  1. Prompt not detailed enough
  2. API quota exceeded
  3. Network issues

Solution:

# Check API key permissions at:
# https://makersuite.google.com/app/apikey

# Ensure prompt includes:
# - Room type
# - Style
# - Colors
# - Materials
# - Dimensions

Issue: "Rendering edit doesn't apply changes"

Solution:

  1. Ensure a rendering was generated first
  2. Be specific in edit requests
  3. Check version history
User: "Show me all renderings"
# Agent lists all versions

User: "Edit version 2: make cabinets darker cream (Benjamin Moore Muslin OC-12)"
# Be very specific about what to change

Issue: "Agent doesn't see my uploaded image"

Current Limitation: ADK Web has some limitations with image uploads. The agent can analyze images in the conversation but direct editing has constraints.

Workaround: Provide detailed descriptions alongside images:

User: [Upload kitchen photo]
"This is my 12x15 kitchen. Oak cabinets, white appliances, laminate counters.
There's a window over the sink and island in the center."

💡 Best Practices

1. Provide Detailed Descriptions

Bad:

User: "Renovate my kitchen"

Good:

User: "Renovate my 10x14 kitchen. Currently has oak cabinets, white
appliances, laminate counters, linoleum flooring. I want modern
farmhouse style with white shaker cabinets, quartz counters,
stainless appliances. Budget: $28,000"

2. Upload High-Quality Photos

  • ✅ Good lighting
  • ✅ Multiple angles
  • ✅ Show entire room
  • ✅ Clear, in-focus
  • ❌ Avoid dark, blurry, or partial views

3. Be Specific About Style

Bad:

User: "Make it look nice"

Good:

User: "Modern farmhouse style: white shaker cabinets, natural wood
accents, marble-look quartz, matte black hardware, rustic lighting"

4. Set Realistic Budgets

Use these guidelines:

  • Cosmetic refresh: $50-100/sq ft
  • Moderate renovation: $150-250/sq ft
  • Full renovation: $300-500/sq ft
  • Luxury transformation: $600-1200/sq ft

5. Iterate Thoughtfully

Make one change at a time:

User: "Change cabinets to cream"
[Wait for v2]

User: "Now add pendant lights"
[Wait for v3]

User: "Lighten the floor color"
[Get v4]

6. Save Your Favorites

Renderings are saved automatically, but you can:

User: "I love version 3, can you save that as my final design?"
Agent: Confirms and can regenerate if needed

🎓 Tips for Best Results

Getting Accurate Cost Estimates

  1. Provide room dimensions
  2. Specify quality level (budget/mid-range/luxury)
  3. Mention existing conditions
  4. Include location if possible (costs vary by region)

Generating Better Renderings

  1. Use specific color names with codes

    • ✅ "Benjamin Moore Simply White OC-117"
    • ❌ "white color"

  2. Mention exact materials

    • ✅ "Carrara marble-look quartz countertops"
    • ❌ "nice countertops"

  3. Describe lighting specifically

    • ✅ "3 recessed LED lights, 2 pendant lights over island"
    • ❌ "better lighting"

Getting Realistic Timelines

Mention:

  • Your availability
  • Any deadlines
  • Seasonal considerations
  • Contractor availability in your area

📞 Getting Help

In-App Help

User: "What can you help me with?"
Agent: Provides system capabilities overview

User: "Show me an example"
Agent: Gives sample prompts

Community Support

  • GitHub Issues: Report bugs or request features
  • Discussions: Ask questions, share results
  • Examples: See what others have created

Ready to transform your space? Start chatting with the agent! 🏠✨

← Back to README