| --- |
| 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) |
|
|
