EcoHome Energy Advisor

An AI-powered energy optimization agent that helps customers reduce electricity costs and environmental impact through personalized recommendations.

Project Overview

EcoHome is a smart-home energy start-up that helps customers with solar panels, electric vehicles, and smart thermostats optimize their energy usage. The Energy Advisor agent provides personalized recommendations about when to run devices to minimize costs and carbon footprint.

Key Features

• Weather Integration: Uses weather forecasts to predict solar generation
• Dynamic Pricing: Considers time-of-day electricity prices for cost optimization
• Historical Analysis: Queries past energy usage patterns for personalized advice
• RAG Pipeline: Retrieves relevant energy-saving tips and best practices
• Multi-device Optimization: Handles EVs, HVAC, appliances, and solar systems
• Cost Calculations: Provides specific savings estimates and ROI analysis

Project Structure

ecohome_solution/
├── models/
│   ├── __init__.py
│   └── energy.py              # Database models for energy data
├── data/
│   └── documents/
│       ├── tip_device_best_practices.txt
│       └── tip_energy_savings.txt
├── agent.py                   # Main Energy Advisor agent
├── tools.py                   # Agent tools (weather, pricing, database, RAG)
├── requirements.txt           # Python dependencies
├── 01_db_setup.ipynb         # Database setup and sample data
├── 02_rag_setup.ipynb        # RAG pipeline setup
├── 03_run_and_evaluate.ipynb # Agent testing and evaluation
├── requirements.txt           # Python dependencies (verified versions)
├── .env.example               # Environment variable template
└── README.md                  # This file

Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Set Environment Variables

Create a .env file with your API keys:

cp .env.example .env
# then edit .env:
VOCAREUM_API_KEY=your_vocareum_api_key_here
OPENAI_API_KEY=your_vocareum_api_key_here
OPENAI_BASE_URL=https://openai.vocareum.com/v1

3. Run the Notebooks

Execute the notebooks in order:

1. 01_db_setup.ipynb - Set up the database and populate with sample data
2. 02_rag_setup.ipynb - Configure the RAG pipeline for energy tips
3. 03_run_and_evaluate.ipynb - Run the agent, test it with 10+ scenarios, and evaluate it

Agent Capabilities

Tools Available

• Weather Forecast: Get hourly weather predictions and solar irradiance
• Electricity Pricing: Access time-of-day pricing data
• Energy Usage Query: Retrieve historical consumption data
• Solar Generation Query: Get past solar production data
• Energy Tips Search: Find relevant energy-saving recommendations
• Savings Calculator: Compute potential cost savings

Example Questions

The Energy Advisor can answer questions like:

• "When should I charge my electric car tomorrow to minimize cost and maximize solar power?"
• "What temperature should I set my thermostat on Wednesday afternoon if electricity prices spike?"
• "Suggest three ways I can reduce energy use based on my usage history."
• "How much can I save by running my dishwasher during off-peak hours?"

Database Schema

Energy Usage Table

• timestamp: When the energy was consumed
• consumption_kwh: Amount of energy used
• device_type: Type of device (EV, HVAC, appliance)
• device_name: Specific device name
• cost_usd: Cost at time of usage

Solar Generation Table

• timestamp: When the energy was generated
• generation_kwh: Amount of solar energy produced
• weather_condition: Weather during generation
• temperature_c: Temperature at time of generation
• solar_irradiance: Solar irradiance level

Learning Objectives

This project helps students learn:

1. Database Design: Creating schemas for energy management systems
2. API Integration: Working with external weather and pricing APIs
3. RAG Implementation: Building retrieval-augmented generation pipelines
4. Agent Development: Creating intelligent agents with tool usage
5. Evaluation Methods: Testing and measuring agent performance
6. Energy Optimization: Understanding smart home energy management

Key Technologies

• LangChain: Agent framework and tool integration
• LangGraph: Agent orchestration and workflow
• ChromaDB: Vector database for document retrieval
• SQLAlchemy: Database ORM and management
• OpenAI: LLM and embeddings
• SQLite: Local database storage

Evaluation Criteria

The agent is evaluated on:

• Accuracy: Correct information and calculations
• Relevance: Responses address the user's question
• Completeness: Comprehensive answers with actionable advice
• Tool Usage: Appropriate use of available tools
• Reasoning: Clear explanation of recommendations

Getting Started

1. Clone this repository
2. Install the required dependencies
3. Set up your environment variables
4. Run the notebooks in sequence
5. Test the agent with your own questions

Contributing

This is a learning project. Feel free to:

• Add new tools and capabilities
• Improve the evaluation metrics
• Enhance the RAG pipeline
• Add more sophisticated optimization algorithms

License

This project is for educational purposes as part of the Udacity Course 2 curriculum.

Solution Implementation Notes

Environment

• Python version: 3.12 (developed and verified on GitHub Codespaces)
• Key package versions (full pinned set in requirements.txt): langchain 0.3.x, langchain-core 0.3.x, langgraph 0.6.x, langchain-openai 0.3.x, langchain-chroma 0.2.x, chromadb >= 0.5, sqlalchemy 2.0.x
• Note: the original starter requirements listed sqlite3 (part of the Python standard library, not pip-installable) and pinned pre-release versions incompatible with the agent code; requirements.txt has been corrected to a verified, coherent dependency set.

What was implemented

1. get_weather_forecast (tools.py) - Mock weather API generating deterministic (seeded per location+date) hourly forecasts: temperature curves, weather conditions, and a solar irradiance bell curve peaking at noon (scaled by condition), plus daily summaries with best solar hours.
2. get_electricity_prices (tools.py) - Mock time-of-use pricing: off-peak overnight (~0.7x base, zero demand charge), peak 06:00-22:00 (~1.6x), and a super-peak window 17:00-20:00 (~2.5x) with demand charges, plus a summary of the cheapest/most expensive hours. Seeded per date for reproducibility.
3. search_energy_tips fix (tools.py) - The vector store bootstrap now loads all .txt files from data/documents/ (rather than a hardcoded pair) and uses Vocareum-compatible embeddings configured from the environment.
4. Knowledge base expansion (data/documents/) - Five additional articles covering HVAC optimization, smart home automation, renewable energy integration, seasonal energy management, and energy storage optimization (7 documents total).
5. ECOHOME_SYSTEM_PROMPT (notebook 03) - Comprehensive agent instructions covering the agent's role, step-by-step workflow, key capabilities/tools, recommendation guidelines (data-grounded, specific hours/setpoints/savings), and example questions.
6. 10 test cases (notebook 03) - Covering EV charging, thermostat settings, appliance scheduling, solar maximization, cost savings, usage-history analysis, pool pumps, laundry, HVAC, and battery storage.
7. Evaluation suite (notebook 03):
   • evaluate_response() - LLM-as-judge with a structured-output schema scoring ACCURACY, RELEVANCE, COMPLETENESS, and USEFULNESS (1-5) with comprehensive feedback.
   • evaluate_tool_usage() - programmatic Tool Appropriateness (precision) and Tool Completeness (recall) against expected tools, with feedback on missing/extra tools.
   • generate_evaluation_report() - aggregates overall scores, per-test results, strengths, weaknesses, and improvement recommendations; displayed via the separate display_evaluation_report() function.
8. Agent hardening (agent.py) - proper error handling in invoke() (empty-question guard, structured error returns) while preserving the required contract (instructions/model constructor, question/context invoke).

Evaluation Findings

The evaluation suite (notebook 03) scored the agent 4.62/5 on response quality (accuracy 4.5, relevance 4.7, completeness 4.5, usefulness 4.8) across 10 test scenarios. Tool-usage analysis found 65% tool completeness: the agent (gpt-4o-mini) sometimes answers from a single data source rather than consulting all expected tools, even after strengthening the system prompt with mandatory tool-usage rules between evaluation iterations. The report's recommendations capture the remaining improvement paths: stricter per-question-type tool mandates, a larger model, and broader test coverage.