---

The Problem

Every home has 15-30 appliances. Each comes with a manual nobody reads — until something breaks. Then you're digging through drawers, Googling error codes, and sitting on hold with customer support for 45 minutes.

HomeGuard AI fixes this.

How It Works

Upload Manual (PDF, photo, or barcode scan)
        |
        v
AI extracts & indexes everything (OCR --> Chunk --> Embed --> Store)
        |
        v
Ask anything: "Why is my washer showing error code UE?"
        |
        v
AI answers with exact page references from YOUR manual
        |
        v
Still stuck? AI calls the manufacturer FOR you (Phase 3)

Key Features

Feature	Status	Description
Smart Manual Upload	Phase 1	PDF upload, camera scan, barcode lookup
AI Q&A (RAG)	Phase 1	Ask questions, get manual-grounded answers with citations
Warranty Tracker	Phase 1	Visual timeline, expiration alerts (green/yellow/red)
Telegram Bot	Phase 1	/ask, /warranty, /products — full access via chat
WhatsApp Bot	Phase 2	Same capabilities, pending Meta business verification
Auto Customer Care Calls	Phase 3	AI voice agent calls manufacturer, navigates IVR, schedules service

Architecture

+-------------------------------------------------------------+
|                      CLIENTS                                  |
|  iOS App (Expo)  |  Telegram  |  WhatsApp                    |
+--------+---------+------+------+---------+-------------------+
         |                |                |
         v                v                v
+------------------+ +------------------+ +------------------+
|   API Service    | | Webhook Service  | |  Agent Service   |
|   (FastAPI)      | | (FastAPI)        | |  (LangGraph)     |
|   Port 8000      | | Port 8002        | |  Port 8001       |
+--------+---------+ +--------+---------+ +--------+---------+
         |                    |                     |
         v                    v                     v
+-------------------------------------------------------------+
|                    SHARED INFRASTRUCTURE                      |
| PostgreSQL 16 + pgvector  |  Redis 7  |  AWS S3              |
+-------------------------------------------------------------+
         |
         v
+------------------+
|  Worker Service  |
|  (Celery)        |
|  OCR --> Chunk   |
|  Embed --> Store |
+------------------+

AI Pipeline

OCR: Hybrid PDF Processing (English-only)

PDF Upload
    |
    +-- Has text layer? (PyMuPDF check)
    |       |
    |       +-- YES --> PyMuPDF + pdfplumber (FREE, 1000x faster, zero errors)
    |       |
    |       +-- NO  --> Mistral OCR 3 ($2/1K pages, 96.6% table accuracy)
    |       |
    |       +-- FAIL -> Docling fallback (free, self-hosted)
    |
    v
    Markdown output (RAG-ready)

RAG: State-of-the-Art Retrieval

User Query
    |
    +-- Intent Classification (GPT-5 mini)
    |
    +-- Simple Q&A / Warranty ---------> GPT-5 mini ($0.25/M tokens)
    |
    +-- Troubleshooting / Diagnosis ---> Claude Haiku 4.5 ($1.00/M tokens)
    |
    +-- RAG Pipeline:
         Query --> Multi-Query Rewriting (2-3 phrasings)
           --> Hybrid Search (pgvector dense + ParadeDB BM25)
           --> Reciprocal Rank Fusion (RRF)
           --> Cohere Rerank v3.5 (top-20 --> top-5)
           --> CRAG: Relevance gate (score >= 0.7 or refuse)
           --> LLM Generation with citations

Chunking: Structure-Aware for Product Manuals

Manual Section          Chunk Strategy
-----------------       ----------------------------------
Safety Warnings     --> Single chunk (never split)
Troubleshooting     --> Each error code + fix = ONE chunk
Installation        --> Split by numbered step, max 400 tokens
Operation           --> Split by feature/mode, max 400 tokens
Maintenance         --> Split by task, max 300 tokens
Specifications      --> Single chunk (table as Markdown)

Every chunk gets contextual headers prepended: [Brand: X | Model: Y | Section: Z | Page: N] plus an LLM-generated context blurb (Anthropic contextual retrieval) reducing retrieval failures by 49-67%.

Tech Stack

Layer	Technology	Why
Mobile	React Native + Expo 52 (iOS)	Cross-platform ready, fast iteration
Backend	FastAPI + SQLModel + PostgreSQL 16	Async, type-safe, batteries included
AI Agent	LangGraph + LlamaIndex	Stateful multi-step reasoning with tool use
LLM (fast)	GPT-5 mini	Cheap, fast for simple lookups
LLM (smart)	Claude Haiku 4.5	Strong reasoning for diagnostics
OCR (digital PDFs)	PyMuPDF + pdfplumber	Free, 1000x faster than OCR, zero errors
OCR (scanned PDFs)	Mistral OCR 3	96.6% table accuracy, Markdown output, $2/1K pages
OCR (fallback)	Docling (OSS)	Free, self-hosted, for local dev or API failures
Embeddings	Voyage AI voyage-3.5 (1024-dim)	Better retrieval than OpenAI, half the price, 200M free tokens
Reranking	Cohere Rerank v3.5	10-25% precision boost on retrieval
Hybrid Search	pgvector (dense) + ParadeDB pg_search (BM25)	All in PostgreSQL, no extra infra
Vector DB	pgvector via Supabase	Already using Supabase for auth, zero new infra
Voice AI	Retell AI + Twilio SIP	Automated customer care calls (Phase 3)
Messaging	Telegram Bot API + Meta Cloud API	Multi-channel reach

Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.12+
• Node.js 18+ & npm
• Expo CLI (npm install -g expo-cli)

1. Clone & Configure

git clone https://github.com/shubh-trips/HomeGuardAI.git
cd HomeGuardAI
cp .env.example .env
# Fill in your API keys in .env

2. Start Infrastructure

docker compose -f infra/docker-compose.yml up -d postgres redis

3. Run Backend

cd services/api
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

4. Run Worker

cd services/worker
celery -A app.main worker --loglevel=info

5. Run Agent

cd services/agent
uvicorn app.main:app --reload --port 8001

6. Run Mobile App

cd apps/mobile
npm install
npx expo start --ios

API Keys Required

Phase 1 (MVP)

Key	Service	Cost
SUPABASE_URL / ANON_KEY / SERVICE_KEY	Auth + managed pgvector	$25/mo (Pro)
AWS_S3_BUCKET / ACCESS_KEY_ID / SECRET_ACCESS_KEY	File storage	Pay-per-use
OPENAI_API_KEY	GPT-5 mini (LLM only)	~$10-20/mo
ANTHROPIC_API_KEY	Claude Haiku 4.5	~$5-10/mo
MISTRAL_API_KEY	OCR 3 (scanned PDFs only)	~$1-5/mo
VOYAGE_API_KEY	Embeddings (voyage-3.5)	$0 (200M free tokens)
COHERE_API_KEY	Rerank v3.5	$0 (1000 free/mo)
TELEGRAM_BOT_TOKEN	Telegram Bot	Free

Estimated Phase 1 cost: ~$35-50/mo

Phase 2+ (Later)

Key	Service	When
WHATSAPP_* (3 keys)	Meta Cloud API	Phase 2
RETELL_API_KEY	Retell AI (voice calls)	Phase 3
TWILIO_* (2 keys)	Twilio SIP	Phase 3

Project Structure

HomeGuardAI/
├── apps/mobile/            # React Native (Expo) — iOS app
├── services/
|   ├── api/                # FastAPI — CRUD, uploads, auth
|   ├── agent/              # LangGraph — RAG + AI reasoning
|   ├── webhook/            # WhatsApp + Telegram handlers
|   └── worker/             # Celery — OCR, chunking, embedding
├── shared/db/              # SQLModel ORM models
├── infra/                  # Docker Compose, nginx, Terraform
├── scripts/                # Seeding, evaluation, test generation
├── tests/                  # Unit, integration, e2e
├── assets/                 # Banner SVG, static assets
├── CLAUDE.md               # Full architecture reference
├── BUSINESS.md             # Business model & market analysis
└── MEMORY.md               # Project memory index

Roadmap

Phase	Timeline	Focus
Phase 1	Weeks 1-6	Core platform: upload, RAG Q&A, warranty tracking, Telegram bot
Phase 2	Weeks 7-10	WhatsApp integration, enhanced UI, analytics
Phase 3	Weeks 11-14	Voice AI (Retell) — automated customer care calls
Phase 4	Weeks 15+	Android, web dashboard, multi-language UI, family sharing

Contributing

See CLAUDE.md for coding standards, git conventions, and architecture decisions.

License

Private — All rights reserved.

---

Built with FastAPI + LangGraph + Voyage AI + pgvector + React Native
_{Making home appliance ownership less painful, one manual at a time.}