README.md

---
title: InstaAutoApp TeamDataMavericks
emoji: 🚗
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: "4.44.1"
python_version: "3.11"
app_file: app.py
pinned: false
license: mit
short_description: AI-Powered Symptom Triage for 2023 Ford Bronco
---

# 🚗 Insta-AutoApp

**AI-Powered Symptom Triage for 2023 Ford Bronco**

Insta-AutoApp is a RAG-based (Retrieval-Augmented Generation) application that helps 2023 Ford Bronco owners understand warning lights and vehicle symptoms. Describe your issue in plain English and receive structured, OEM-grounded triage guidance in under 60 seconds.

---

## 🌟 Features

- **OEM-Grounded Responses**: All answers are based on the official 2023 Ford Bronco Owner's Manual
- **Structured Triage Output**: Every response includes Urgency Level, Likely Meaning, Next Step, and OEM Citation
- **Vehicle-Specific Follow-ups**: AI asks Bronco-specific clarifying questions (GOAT modes, Sasquatch package, etc.)
- **Safety-First Design**: Conservative defaults for brake, steering, and drivetrain issues
- **No Fabrication**: If the manual doesn't cover it, the app says so

---

## 🚀 Quick Start

### Prerequisites

- Python 3.10+
- HuggingFace API token ([get one here](https://huggingface.co/settings/tokens))
- 2023 Ford Bronco Owner's Manual PDF

### Installation

1. **Clone or download this repository**

```bash
git clone https://github.com/your-repo/insta-autoapp.git
cd insta-autoapp
```

2. **Create a virtual environment (recommended)**

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. **Install dependencies**

```bash
pip install -r requirements.txt
```

4. **Configure environment**

```bash
cp .env.example .env
# Edit .env and add your HuggingFace API token
```

5. **Ingest the OEM Manual** (one-time setup)

```bash
# Place your Bronco manual PDF in a convenient location
python ingest.py path/to/bronco_2023_manual.pdf
```

6. **Launch the app**

```bash
python app.py
```

7. **Open in browser**: http://localhost:7860

---

## 📁 Project Structure

```
insta-autoapp/
├── app.py              # Main Gradio application
├── config.py           # Configuration constants
├── prompts.py          # LLM system prompts
├── llm_client.py       # HuggingFace Inference API client
├── rag_pipeline.py     # FAISS retrieval logic
├── ingest.py           # PDF preprocessing script
├── requirements.txt    # Python dependencies
├── .env.example        # Environment template
├── README.md           # This file
└── data/               # FAISS index (created by ingest.py)
    ├── index.faiss
    └── index.pkl
```

---

## 🔧 Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `HF_API_TOKEN` | Yes | - | HuggingFace API token for LLM inference |
| `HF_MODEL_ID` | No | `Qwen/Qwen2.5-72B-Instruct` | Model ID for inference |
| `TOP_K` | No | `5` | Number of chunks to retrieve |

### Vehicle Profile Options

The app only accepts valid 2023 Ford Bronco configurations:

- **Trim**: Base, Big Bend, Black Diamond, Badlands, Outer Banks, Wildtrak, Raptor
- **Engine**: 2.3L EcoBoost, 2.7L EcoBoost
- **Package**: None, Sasquatch, Lux, Sasquatch + Lux
- **Top Type**: Soft Top, Hard Top, Modular Top
- **Mileage**: 0 - 300,000

---

## 🤖 How It Works

### Architecture

```
User Input (Symptom)
       │
       ▼
┌──────────────────┐
│ Follow-up Gen    │ ◄── LLM (Qwen2.5-72B)
│ (1-2 questions)  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Combined Query   │ = Symptom + Vehicle Profile + Follow-up Answers
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ FAISS Retrieval  │ ◄── Top-5 OEM manual chunks
│ (all-MiniLM-L6)  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Triage Gen       │ ◄── LLM with retrieved context
│ (4-field output) │
└────────┬─────────┘
         │
         ▼
   Structured Response
   + Disclaimer
```

### Urgency Levels

| Level | Meaning | Action |
|-------|---------|--------|
| **Safe** | Cosmetic or informational | No action required |
| **Monitor** | Non-critical issue | Check within 7 days if persists |
| **Urgent** | Needs attention | Schedule service, limit driving |
| **Do Not Drive** | Safety-critical | Stop immediately, seek assistance |

---

## 🚀 Deployment to HuggingFace Spaces

1. **Create a new Space** at https://huggingface.co/new-space
   - Select "Gradio" as the SDK
   - Choose a name (e.g., `insta-autoapp`)

2. **Clone the Space repository**

```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/insta-autoapp
cd insta-autoapp
```

3. **Copy all files** from this project into the Space folder

4. **Add your FAISS index** (from running `ingest.py` locally)
   - Copy `data/index.faiss` and `data/index.pkl` to the Space

5. **Set Space Secrets**
   - Go to Settings → Variables and secrets
   - Add `HF_API_TOKEN` as a secret

6. **Push to deploy**

```bash
git add .
git commit -m "Initial deployment"
git push
```

---

## ⚠️ Limitations

- **Single Vehicle**: V1 supports only 2023 Ford Bronco. Multi-vehicle support planned for V2.
- **Text Only**: No image/photo upload. No voice input.
- **Ephemeral Sessions**: Vehicle profile and history are not saved across sessions.
- **Table Extraction**: Table-heavy manual sections (fluid specs, fuse layouts) may have degraded extraction quality.
- **Not a Diagnosis**: This is triage guidance, not professional mechanical advice.

---

## 🔒 Privacy

- **No PII Collected**: No names, emails, or personal data stored
- **Ephemeral Sessions**: All session data is lost when browser closes
- **Local Data**: FAISS index stored locally, not transmitted
- **API Calls**: Only symptom text is sent to HuggingFace API for inference

---

## 📝 License

MIT License - See LICENSE file for details.

---

## 👥 Team

**Data Mavericks** - ANLY 601 Advanced Coding for Business  
Texas A&M University, Mays Business School

- Nasser Chaudhry
- Miriam Camacho
- Neil Driscoll

---

## 🙏 Acknowledgments

- OEM Manual Source: [CarManualsOnline.info](https://carmanualsonline.info)
- Embedding Model: [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
- LLM: [Qwen/Qwen2.5-72B-Instruct](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct)