🎙️ Hey Bolo — AI Voice Assistant

Phase 1 MVP · Flutter · Gemini AI · Supabase · Android

A personal AI voice assistant for Android that understands natural language commands and controls your smartphone.

---

📱 Features

Feature	Status
Voice input (STT)	✅
Text-to-speech responses	✅
Open installed apps	✅
Make phone calls	✅
Send WhatsApp messages	✅
Play music (Spotify / YouTube Music)	✅
Set alarms	✅
Web search	✅
Open device settings	✅
AI command understanding (Gemini)	✅
Chat-style conversation history	✅
Dark modern UI	✅
Quick action chips	✅
Voice visualizer animation	✅
Accessibility Service stub (Phase 2)	🔜

---

🚀 Quick Start

Prerequisites

• Flutter 3.22+ (flutter --version)
• Android device or emulator (API 21+)
• Gemini API key (free at aistudio.google.com)
• Supabase project (free at supabase.com)

---

Step 1 — Clone & Install

git clone <your-repo-url>
cd hey_bolo
flutter pub get

---

Step 2 — Configure API Keys

Edit .env in the project root:

GEMINI_API_KEY=your_gemini_api_key_here
SUPABASE_URL=https://xxxxxxxxxxxx.supabase.co
SUPABASE_ANON_KEY=your_supabase_anon_key_here

Get Gemini API key:
Go to https://aistudio.google.com/app/apikey → Create API key (free)

---

Step 3 — Set Up Supabase

1. Create a project at supabase.com
2. Go to SQL Editor → paste the contents of supabase/schema.sql → Run
3. Copy your Project URL and anon public key into .env

---

Step 4 — Run on Android Device

# Connect Android device (enable USB debugging)
flutter devices              # verify device is listed
flutter run                  # run in debug mode

For release build:

flutter build apk --release

---

🗣️ Example Voice Commands

Command	Action
"Open WhatsApp"	Opens WhatsApp app
"Call Mom"	Dials Mom from contacts
"Send good morning to Rahul on WhatsApp"	Opens WhatsApp chat with message
"Play Arijit Singh songs"	Opens Spotify with search
"Play Kesariya on YouTube Music"	Opens YouTube Music
"Set alarm at 7 AM"	Opens alarm dialog
"Search weather today"	Opens Google search
"Open WiFi settings"	Opens Wi-Fi settings
"What is the capital of France?"	AI general Q&A

---

🏗️ Architecture

lib/
├── core/
│   ├── constants/      # App strings & config
│   ├── router/         # GoRouter navigation
│   └── theme/          # Dark theme tokens
│
├── features/
│   ├── assistant/
│   │   ├── domain/
│   │   │   └── entities/          # AssistantCommand
│   │   └── presentation/
│   │       ├── providers/         # Riverpod state (AssistantNotifier)
│   │       ├── screens/           # Home, Splash, Settings
│   │       └── widgets/           # MicButton, ChatBubble, Visualizer
│   │
│   └── history/
│       ├── data/models/           # Hive ConversationModel
│       └── presentation/screens/  # HistoryScreen
│
└── services/
    ├── ai/             # Gemini AI service
    ├── voice/          # STT + TTS (VoiceService)
    ├── device/         # App launch, calls, WhatsApp, music
    └── accessibility/  # Phase 2 stub

Voice Flow

User speaks
    ↓
speech_to_text (STT)
    ↓
AiService (Gemini 1.5 Flash) → JSON { action, params, response }
    ↓
AssistantNotifier.executeCommand()
    ↓ (depending on action)
DeviceActionService → Android Intent / URL Launcher
    ↓
VoiceService.speak(response)  → flutter_tts (TTS)

---

🔑 Required Android Permissions

Permission	Purpose
RECORD_AUDIO	Voice input
CALL_PHONE	Make phone calls
READ_CONTACTS	Look up contact by name
INTERNET	Gemini API, Supabase
SEND_SMS	SMS (future)
QUERY_ALL_PACKAGES	List installed apps

---

📦 Key Dependencies

Package	Purpose
speech_to_text	Voice → Text
flutter_tts	Text → Voice
google_generative_ai	Gemini AI
supabase_flutter	Backend
flutter_riverpod	State management
go_router	Navigation
android_intent_plus	Android app/alarm intents
url_launcher	WhatsApp, Spotify, web
contacts_service	Contact lookup
hive_flutter	Local conversation storage
flutter_animate	Smooth animations

---

🔮 Phase 2 Roadmap

• Android Accessibility Service for UI automation
• WhatsApp message auto-send (without opening app)
• Wake word detection ("Hey Bolo")
• Multi-language support (Hindi, Tamil, etc.)
• Smart home controls
• User authentication (Supabase auth)
• Cloud sync of conversation history
• Custom contact nicknames ("Call Dad" → maps to contact)
• Conversation context across sessions

---

🛠️ Troubleshooting

Mic not working?
→ Settings screen → tap Grant for Microphone permission

App not opening?
→ Only apps installed on device will open. The package name mapping is in DeviceActionService._resolvePackageName()

Gemini not responding?
→ Check your GEMINI_API_KEY in .env — make sure it's valid and not expired

Build fails on minSdk?
→ android/app/build.gradle.kts has minSdk = 21 — requires Android 5.0+

---

📄 License

MIT — build something great!