-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME
More file actions
306 lines (232 loc) Β· 8.96 KB
/
README
File metadata and controls
306 lines (232 loc) Β· 8.96 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
# π Mechanic Bot - WhatsApp Car Parts Finder
A WhatsApp chatbot that helps users identify and find car parts using AI vision recognition and intelligent search. Users can send photos of car parts or text queries, and the bot will identify the part, search your inventory, and provide pricing and availability information.
---
## β¨ Features
- **Image Recognition**: Send a photo of a car part β Bot identifies it using Google Gemini AI
- **Text Search**: Describe a car part in text β Bot extracts key details and searches inventory
- **Inventory Management**: Search through a JSON-based inventory database
- **WhatsApp Integration**: Seamless WhatsApp Cloud API integration for messaging
- **Fast & Free LLM**: Uses Groq's Llama 3.1 for intelligent part extraction
- **Real-time Responses**: Instant part identification and availability checks
- **PartFindr Backend Mode**: Uses the monorepo backend bot endpoints for live marketplace search and analytics logging
---
## π οΈ Tech Stack
- **Framework**: FastAPI (Python web framework)
- **Vision AI**: Google Gemini 2.5 Flash-Lite (image analysis)
- **Language Model**: Groq Llama 3.1-8b-instant (part extraction & NLP)
- **WhatsApp API**: Meta's WhatsApp Cloud API v19.0
- **Messaging**: Real-time WhatsApp message delivery
---
## π Prerequisites
Before running this project, ensure you have:
1. **Python 3.8+** installed
2. **API Keys** (sign up for free):
- [Groq API Key](https://console.groq.com) - Free Llama 3 access
- [Google Gemini API Key](https://aistudio.google.com/app/apikeys) - Free vision AI
- [Meta WhatsApp Business Account](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) - WhatsApp Cloud API credentials
3. **WhatsApp Setup**:
- Business phone number registered with Meta
- Webhook URL (for receiving messages)
---
## π Installation & Setup
### 1. Clone or Download the Project
```bash
cd c:\Users\hp\Desktop\mechanic-bot
```
### 2. Install Dependencies
```bash
pip install fastapi uvicorn python-dotenv groq google-genai requests
```
### 3. Create `.env` File
Create a file named `.env` in the project root and add your credentials:
```
GROQ_API_KEY=your_groq_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
WHATSAPP_TOKEN=your_whatsapp_access_token
WHATSAPP_PHONE_ID=your_phone_number_id
VERIFY_TOKEN=your_custom_verification_token
```
### 4. Create `inventory.json`
Create an `inventory.json` file with your car parts inventory:
```json
[
{
"part_name": "Alternator",
"car_model": "Honda Accord",
"year": 2006,
"price_NGN": 15000,
"stock_qty": 5,
"location": "Lagos Warehouse"
},
{
"part_name": "Starter Motor",
"car_model": "Toyota Camry",
"year": 2010,
"price_NGN": 8500,
"stock_qty": 3,
"location": "Abuja Store"
}
]
```
### 5. Run the Server
```bash
python main.py
```
The bot will start on `http://0.0.0.0:8000`
---
## π‘ How It Works
### Image Processing Flow
1. User sends a **photo** of a car part via WhatsApp
2. Bot fetches the image from Meta's servers (authenticated)
3. **Gemini Vision AI** analyzes the image and describes the part
4. **Llama 3 (Groq)** extracts the exact part name and car model
5. Bot searches the `inventory.json` for a match
6. Bot sends back pricing, stock availability, and location
### Text Processing Flow
1. User sends a **text message** describing the part (e.g., "Honda Accord alternator")
2. **Llama 3 (Groq)** parses the text and extracts part name + model
3. Bot searches inventory using fuzzy matching
4. Bot responds with matching parts or suggests sending a photo
---
## π Environment Variables Explained
| Variable | Description | Example |
|----------|-------------|---------|
| `GROQ_API_KEY` | Your Groq API key (free at console.groq.com) | `gsk_xxxx...` |
| `GEMINI_API_KEY` | Your Google Gemini API key (free at aistudio.google.com) | `AIzaSy...` |
| `WHATSAPP_TOKEN` | Meta WhatsApp access token (from Meta Dashboard) | `EAAxxxxx...` |
| `WHATSAPP_PHONE_ID` | Your WhatsApp Business phone number ID | `123456789` |
| `VERIFY_TOKEN` | Custom token for webhook verification (you create this) | `my_secure_token` |
| `PARTFINDR_API_URL` | PartFindr backend API base URL | `http://localhost:5000/api/v1` |
| `PARTFINDR_BOT_SECRET` | Bot secret header value (`X-Bot-Secret`) | `replace_me` |
---
## π PartFindr Integration
This bot now fits into the PartFindr monorepo as a WhatsApp channel adapter:
1. Keep Python `mechanic-bot` for WhatsApp webhook handling and media retrieval.
2. Send extracted part queries to `POST /api/v1/bot/search` in PartFindr backend.
3. Log each conversation to `POST /api/v1/bot/sessions` for analytics.
4. If backend is unavailable, fallback to local `inventory.json` search automatically.
Set these environment variables in `mechanic-bot/.env` to enable integration:
```
PARTFINDR_API_URL=http://localhost:5000/api/v1
PARTFINDR_BOT_SECRET=replace_me
```
---
## π Project Structure
```
mechanic-bot/
βββ main.py # Main FastAPI application
βββ inventory.json # Car parts inventory database
βββ .env # Environment variables (create this)
βββ README # This file
```
---
## π Webhook Setup (WhatsApp Integration)
1. **Expose Your Local Server** (use ngrok for testing):
```bash
ngrok http 8000
```
Copy the public URL (e.g., `https://abc123.ngrok.io`)
2. **Configure in Meta Dashboard**:
- Go to [Meta for Developers](https://developers.facebook.com)
- Select your WhatsApp Business App
- Navigate to **Configuration** β **Webhooks**
- Set Webhook URL: `https://your-url.ngrok.io/webhook`
- Set Verify Token: (same as `VERIFY_TOKEN` in `.env`)
3. **Subscribe to Messages**:
- In the webhook settings, subscribe to the `messages` and `message_status` events
---
## π¬ Usage Examples
### Example 1: User Sends a Photo
**User**: *Sends photo of an alternator*
**Bot**:
```
β
IDENTIFIED: Alternator (2006).
Price: N15,000.
Stock: 5 available. Located at Lagos Warehouse.
Do you want me to reserve this for you?
```
### Example 2: User Sends Text
**User**: "I need a starter motor for my 2010 Toyota Camry"
**Bot**:
```
β
TEXT SEARCH: Starter Motor (2010) found.
Price: N8,500.
Stock: 3 available.
```
### Example 3: Part Not Found
**User**: *Sends photo of rare part*
**Bot**:
```
π Identified: Transmission Control Module. I can't find an exact match in our inventory right now.
Please try another angle or text the part number for a manual search.
```
---
## π Troubleshooting
| Issue | Solution |
|-------|----------|
| "Gemini Client not initialized" | Check your `GEMINI_API_KEY` in `.env` |
| WhatsApp messages not received | Verify `WHATSAPP_TOKEN` and `WHATSAPP_PHONE_ID` |
| Webhook verification fails | Ensure `VERIFY_TOKEN` matches in Meta Dashboard |
| Inventory not loading | Check `inventory.json` is valid JSON and in the root directory |
| "Critical Processing Error" | Ensure image URL is accessible; check your WhatsApp token expiration |
---
## π API Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/` | GET | Health check |
| `/webhook` | GET | WhatsApp webhook verification |
| `/webhook` | POST | Receive incoming WhatsApp messages |
---
## π Security Best Practices
1. **Never commit `.env` file** to version control
2. **Rotate API keys regularly** from your respective dashboards
3. **Use HTTPS** for production webhooks
4. **Validate all incoming requests** from WhatsApp
5. **Monitor API usage** to detect unusual activity
---
## π Customization
### Adding More Inventory Fields
Edit `inventory.json` to include additional fields:
```json
{
"part_name": "...",
"car_model": "...",
"year": 2020,
"price_NGN": 25000,
"stock_qty": 10,
"location": "...",
"supplier": "XYZ Parts Co.",
"warranty_months": 12
}
```
### Changing Search Logic
Modify the search algorithm in `main.py` around line 180-185 to match part names differently (e.g., fuzzy matching with `difflib`).
### Custom Prompts
Edit `VISION_PROMPT` and `LLAMA_PROMPT` strings to change how the bot analyzes images and text.
---
## π’ Deployment
For production, deploy on platforms like:
- **Render** (free tier available)
- **Heroku** (paid)
- **Railway** (simple deployment)
- **AWS EC2** (scalable)
Replace `localhost` with your production domain in WhatsApp webhook settings.
---
## π Support & Contributions
- **Issues?** Check the Troubleshooting section above
- **Feature requests?** Modify the code to suit your needs
- **API Limits?** Groq and Gemini free tiers have usage limits; upgrade if needed
---
## π License
This project is open-source. Feel free to use and modify it for your business needs.
---
## π― Future Enhancements
- [ ] Database integration (PostgreSQL) instead of JSON
- [ ] Multi-language support
- [ ] Reservation/booking system
- [ ] Payment integration
- [ ] Admin dashboard for inventory management
- [ ] Image similarity matching for better part identification
- [ ] Customer history tracking
---
**Happy part hunting! π§**