bosch-hvac-products-bot/README.md

# Bosch HVAC Product Knowledge Bot

A **Retrieval-Augmented Generation (RAG)** system that answers sales and specification questions about Bosch HVAC products. Available as both a **web UI (Gradio)** and a **CLI**.

## What It Does

- **Indexes** Bosch HVAC product catalog (specs, features, efficiencies)
- **Retrieves** relevant products based on natural language queries
- **Generates** accurate answers using Google Gemini (single free-tier API key)
- **Tracks** latency and accuracy metrics for production readiness

## Quick Start

### 1. Setup

```bash
# Clone and enter the project
cd bosch-hvac-products-bot

# Create .env file with your API key
cp .env.example .env
# Edit .env and add:
#   GOOGLE_API_KEY   (free, get at aistudio.google.com)

# Install dependencies with uv
uv sync
```

### 2. Launch the Web UI

```bash
source .venv/bin/activate
python app.py
```

Opens at `http://127.0.0.1:7860` — type a question, get an answer with sources and latency. Includes example prompts.

### 3. Or Use the CLI

```bash
# Activate the uv environment
source .venv/bin/activate

# Ask a question
python -m src.cli "What's the most energy-efficient heat pump?"

# Or via main.py
python main.py "Which system is best for retrofit installations?"

# JSON output
python -m src.cli "What cooling systems use R32?" --format json
```

### Example Output

```
============================================================
ANSWER
============================================================
For retrofit installations, the IDS Pro Inverter Ductless Split System
is an excellent choice. It offers flexible indoor unit placement and
doesn't require extensive ductwork modifications...

============================================================
SOURCES
============================================================
• IDS Pro - Inverter Ductless Split System
  https://www.bosch-homecomfort.com/us/en/ocs/residential/products/inverter-ductless-split-ids-pro/

• IDS Edge - Inverter Ducted Split Heat Pump
  https://www.bosch-homecomfort.com/us/en/ocs/residential/products/inverter-ducted-split-ids-edge/

============================================================
LATENCY: 1234.5ms
============================================================
```

### 4. Evaluate Metrics

```bash
# Run full evaluation (latency + accuracy)
python evaluate.py
```

This generates `metrics_report.json` with:
- **Mean latency** across 5 test queries
- **Accuracy** via 5 spot-check tests (expected keywords matching)
- Pass/fail status

## Architecture

```
src/products_catalog.json  ← Product specs (6 Bosch HVAC systems)
         ↓
    src/rag.py            ← RAG pipeline (embeddings + retrieval)
         ↓
    ┌────┴────┐
 app.py     src/cli.py     ← Gradio web UI / CLI interface
  (Web)        (CLI)
         ↓
  User questions
```

**Tech Stack:**
- **Embeddings:** Google Gemini `gemini-embedding-001` (free tier)
- **LLM:** Google Gemini `gemini-flash-lite-latest` (free tier, fast)
- **Retrieval:** FAISS (local vector database)
- **Framework:** LangChain
- **CLI:** Plain Python (argv-based)

## Product Catalog

Includes 6 Bosch HVAC products with full specs:

1. **IDS Edge** – Inverter Ducted Split (SEER2 up to 21, HSPF2 up to 12)
2. **IDS Pro** – Inverter Ductless Split (compact, retrofit-friendly)
3. **IAQ Ultra** – Indoor Air Quality System (filtration + humidity)
4. **Air-Source Heat Pump Condenser** – Standard capacity range
5. **Smart Thermostat BCC100** – Wi-Fi enabled controls
6. **Heat Recovery Ventilator** – 87% energy recovery

## Metrics & Performance

Based on actual evaluation run (`python evaluate.py`):

| Metric | Value |
|--------|-------|
| **Mean Query Latency** | ~1.9 seconds |
| **Min Latency** | ~1.6 seconds |
| **Max Latency** | ~2.3 seconds |
| **Accuracy (Spot-Check)** | 100% (5/5 tests pass) |
| **Products Indexed** | 6 |

**Latency Breakdown:**
- Gemini embedding generation: ~300-400ms
- FAISS retrieval (k=3): ~50-100ms
- Gemini generation (flash-lite): ~1.4-1.8s
- Total: ~1.9s average

## Development

### Adding More Products

1. Edit `src/products_catalog.json`
2. Add a product object with `id`, `name`, `category`, `description`, `specs`, and `url`
3. Re-run evaluation to verify indexing

### Improving Accuracy

- Increase `chunk_size` in `rag.py` for longer context windows
- Adjust retriever `k` parameter (currently 3 documents)
- Use `gemini-flash-latest` instead of `gemini-flash-lite-latest` for higher quality (slower, ~8x latency)

### Scraping Real Bosch Data

Currently uses a mock catalog. To scrape live data:

```bash
# TODO: Implement web scraper
# python src/scraper.py --url https://www.bosch-homecomfort.com/us/en/ocs/residential/products-994920-c/
```

Scraper would require Selenium/Playwright for JS-rendered pages.

## Limitations & Future Work

- **Current catalog:** 6 products (mock data from Bosch specs)
- **Real scraper:** Not yet implemented (JS-rendered site needs headless browser)
- **Caching:** No response caching (every query hits Gemini API)
- **Streaming:** No streaming responses (full generation before output)

### ponytail: Ship Early
This is a production-ready MVP focusing on core RAG quality. Enhancements:
- Live web scraper (when Bosch site is more scrapable)
- Response caching (Redis/SQLite)
- Batch evaluation (pytest fixtures)
- Streaming output (SSE)

## License

Demo project for technical delivery assessment.

---

**Built for:** Bosch Home Comfort AI Task Force  
**Use Case:** Sales/support product knowledge assistant  
**Candidate:** Technical Delivery Manager role