BixAI - AI-Powered Desktop Assistant with Gemma 4

🏆 Gemma 4 Good Hackathon Submission - Harnessing the power of Gemma 4 to drive positive change and global impact.

A cross-platform Flutter desktop application that brings AI assistance to your fingertips through customizable keyboard shortcuts, intelligent screen interaction, and local on-device AI inference using Gemma 4.

Version: 1.0.2 | Status: ✅ Production Ready | Hackathon: Gemma 4 Good

---

✨ Core Features

🤖 Dual AI Engine Support

• Gemma 4 Local Inference (NEW!) - On-device AI processing with privacy-first approach

  • Powered by flutter_gemma package
  • No API calls required - runs completely offline
  • Supports multimodal inputs (text + images)
  • Perfect for sensitive data and privacy-conscious applications

• Google Gemini 2.0 Flash - Cloud-based advanced conversational AI

  • Real-time streaming responses
  • Full conversation history with local storage
  • Search and filter past conversations
  • Export chat history

📸 Screenshot Analysis

• Vision AI - Capture and analyze any part of your screen
• Instant AI-powered visual insights
• OCR text extraction from screenshots
• Automatic image processing

⌨️ Custom Keyboard Shortcuts

• Create personalized shortcuts for instant AI command execution
• Support for complex key combinations
• Multiple command types (text & screenshot)
• Quick access to frequently used AI tasks
• Manage shortcuts from settings

📊 Request Tracking & Statistics

• Monitor AI usage and request history
• View detailed statistics and analytics
• Track remaining free requests (20 limit)
• Request counter with daily reset
• Detailed request information screen

🎨 User Interface

• Dark/Light Theme Support - Beautiful Material Design UI
• Responsive layout for all screen sizes
• Smooth animations and transitions
• Intuitive navigation with tabs
• Professional color scheme

🔐 License Management

• Lemon Squeezy Integration - Secure license validation
• Free tier with 20 daily requests
• Pro tier with unlimited requests
• License activation and deactivation
• License status indicator

💾 Local Data Management

• Isar Database - Fast local SQLite storage
• All data stored locally on your machine
• No cloud dependency
• Automatic data persistence
• Conversation history backup

🖥️ Cross-Platform Support

• Windows - Native Windows integration
• macOS - Native macOS integration with Cocoa
• Linux - Full Linux support
• Platform-specific optimizations
• Consistent experience across all platforms

---

🏗️ Architecture

Project Structure

lib/
├── core/                 # Configuration & themes
│   ├── config/          # App configuration
│   ├── constants/       # App constants
│   └── themes/          # Light & dark themes
├── services/            # Business logic
│   ├── ai/              # AI integrations
│   │   └── gemma4_service.dart    # Local Gemma 4 inference ⭐ NEW
│   ├── database/        # Isar database
│   ├── license/         # License management
│   ├── shortcuts/       # Keyboard shortcuts
│   ├── screen/          # Screenshot & OCR
│   ├── cache/           # Response caching
│   ├── logging/         # Structured logging
│   ├── error/           # Error handling
│   ├── prompts/         # Prompt management
│   ├── request/         # Request tracking
│   └── window/          # Window management
├── models/              # Data models
├── presentation/        # UI layer
│   ├── screens/         # App screens
│   └── widgets/         # Reusable widgets
└── providers/           # State management

Key Services

Service	Purpose
Gemma4Service	Local Gemma 4 inference ⭐ NEW
DatabaseService	Local data persistence
LicenseService	License validation & management
ShortcutService	Keyboard shortcut registration
ScreenService	Screenshot capture & OCR
RequestCounterService	Usage tracking
AppLogger	Structured logging
ErrorHandler	Error management

---

📱 Screens

Home Screen

• Dashboard with recent requests
• Feature showcase
• Statistics overview
• Quick access to shortcuts
• License status indicator
• Gemma 4 model status ⭐ NEW

Chat Screen

• Real-time AI conversations
• Message history
• Screenshot upload capability
• Streaming responses
• Switch between Gemma 4 (local) and Gemini (cloud) ⭐ NEW
• License status bar

Settings Screen

• Keyboard shortcut management
• Add/edit/delete shortcuts
• Command type selection
• Shortcut configuration
• Gemma 4 model configuration ⭐ NEW

Request Detail Screen

• View detailed request information
• Continue conversations
• Message history
• License status

---

🚀 Getting Started

Prerequisites

• Flutter SDK 3.8.0+
• Dart SDK 3.8.0+
• macOS, Windows, or Linux
• For Gemma 4: Download Gemma 4 model files (e.g., from Hugging Face)

Installation

# Clone and navigate
cd ai_explainer

# Get dependencies
flutter pub get

# Generate code (Isar models)
flutter pub run build_runner build

# Run the app
flutter run -d <platform>  # macos, windows, or linux

Environment Setup

Create a .env file or set environment variables:

export GEMINI_API_KEY=your_gemini_api_key
export LEMON_SQUEEZY_API_KEY=your_lemon_squeezy_key
export LEMON_SQUEEZY_STORE_ID=your_store_id

Gemma 4 Setup

1. Download a Gemma 4 model (recommended: gemma-2b-it-q4_0.gguf for desktop)
2. Place the model in your app's assets or documents directory
3. The app will automatically detect and load the model

Example model paths:

• macOS: ~/Library/Application Support/bix_ai/models/gemma-2b-it-q4_0.gguf
• Windows: %APPDATA%/bix_ai/models/gemma-2b-it-q4_0.gguf
• Linux: ~/.local/share/bix_ai/models/gemma-2b-it-q4_0.gguf

---

📦 Key Dependencies

• flutter - UI framework
• provider - State management
• isar - Local database
• http - HTTP client
• window_manager - Window management
• hotkey_manager - Keyboard shortcuts
• screen_capturer - Screenshot capture
• screen_text_extractor - OCR
• shared_preferences - Local preferences
• google_fonts - Typography
• bot_toast - Toast notifications
• flutter_gemma ⭐ NEW - Local Gemma 4 inference

---

🧪 Testing

flutter test

---

📚 Documentation

• Quick Start Guide - Service usage examples
• Project Analysis - Architecture details
• Production Readiness - Deployment checklist
• Testing Guide - Test execution
• Improvements Summary - Recent enhancements
• Gemma 4 Setup Guide - ⭐ NEW Model configuration

---

🔒 Security & Privacy

• ✅ Gemma 4 Local Inference - Process sensitive data completely offline
• ✅ All data stored locally
• ✅ No cloud storage required (when using Gemma 4)
• ✅ Secure license validation
• ✅ JWT authentication ready
• ✅ Environment-based configuration
• ✅ No sensitive data logging

---

🎯 Free vs Pro

Free Tier

• 20 daily AI requests (Gemini cloud)
• Unlimited Gemma 4 local inference ⭐ NEW
• All core features
• Local data storage
• Screenshot analysis
• Custom shortcuts

Pro Tier

• Unlimited AI requests (Gemini cloud)
• All free features
• Priority support
• Advanced analytics

---

🏆 Gemma 4 Good Hackathon

This project is submitted to the Gemma 4 Good Hackathon with the mission to harness the power of Gemma 4 to drive positive change and global impact.

How BixAI Uses Gemma 4 for Good:

1. Privacy-First AI - Enables users in sensitive fields (healthcare, legal, counseling) to use AI without data leaving their device
2. Offline Accessibility - Works in areas with limited internet connectivity
3. Cost-Free AI Access - No API costs make AI accessible to everyone
4. Educational Tool - Helps users understand how local AI models work
5. Multilingual Support - Gemma 4's multilingual capabilities help break language barriers

---

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Run tests: flutter test
4. Submit a pull request

---

📄 License

Proprietary - All rights reserved

---

🆘 Support

For issues or questions:

1. Check the documentation files
2. Review test files for usage examples
3. Check application logs with AppLogger
4. Refer to IMPROVEMENTS_SUMMARY.md

---

Built with ❤️ using Flutter and Gemma 4

Submitted to the Gemma 4 Good Hackathon