Nexus AI - Personal AI Assistant 🤖

A powerful, cross-platform AI assistant with voice control, WhatsApp automation, and intelligent task execution.

Features • Quick Start • Documentation • Contributing

---

🌟 Features

• 🎤 Voice Control - Natural language commands with speech recognition
• 💬 WhatsApp Automation - Send messages via voice or text commands
• 🖥️ System Control - Open apps, control volume, manage files
• 🤖 AI-Powered - Gemini 2.0 Flash + Groq Llama 3.3 70B
• 🧠 State Machine - Disciplined execution with IDLE → THINKING → EXECUTING flow
• 💾 Short-Term Memory - Context retention for multi-step commands
• 🎨 Beautiful GUI - Modern PyQt6 interface with command history
• 🌍 Cross-Platform - Works on macOS, Windows, and Linux

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• Microphone (for voice mode)
• API Keys: Google Gemini and Groq

Installation

macOS / Linux

git clone https://github.com/pratik1258m/nexus.git
cd nexus
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.template .env
# Edit .env with your API keys

Windows

git clone https://github.com/pratik1258m/nexus.git
cd nexus
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.template .env
# Edit .env with your API keys

Configuration

Edit .env file:

GEMINI_API_KEY=your_gemini_key_here
GROQ_API_KEY=your_groq_key_here

Edit contacts.json for WhatsApp:

{
  "mom": "+1234567890",
  "dad": "+0987654321"
}

Run

Voice Mode (with GUI):

python main.py

Text Mode (terminal only):

python main.py --text

💡 Usage Examples

Voice Commands

• "Open calculator"
• "Send WhatsApp to mom saying hello"
• "What's the weather today?"
• "Take a screenshot"
• "Search Google for Python tutorials"

Text Commands

YOU: open chrome
YOU: send message to dad hello from nexus on whatsapp
YOU: set volume to 50

📁 Project Structure

nexus/
├── core/                      # Core modules
│   ├── engine.py              # AI engine with Gemini & Groq
│   ├── state_machine.py       # Strict state control
│   ├── task_memory.py         # Short-term context retention
│   ├── command_interpreter.py # Local-first command routing
│   ├── voice.py               # Voice system (TTS/STT)
│   ├── platform_utils.py      # Cross-platform utilities
│   └── logger.py              # Logging system
├── skills/                    # AI skills (modular capabilities)
│   ├── whatsapp_skill.py      # WhatsApp automation
│   ├── system_ops.py          # System control
│   ├── automation_ops.py      # Keyboard/mouse control
│   └── ...                    # 16+ more skills
├── gui/                       # GUI components
│   └── app.py                 # PyQt6 interface
├── main.py                    # Entry point
└── requirements.txt           # Dependencies

🔧 Platform Support

Platform	Voice	GUI	WhatsApp	App Control	Status
macOS	✅ Native	✅	✅	✅	Fully Tested
Windows	✅ pyttsx3	✅	✅	✅	Ready
Linux	✅ pyttsx3	✅	✅	✅	Ready

Platform-Specific Notes

Linux: Install system dependencies first

sudo apt-get install python3-pyaudio espeak portaudio19-dev

Windows: Volume control requires pycaw (included in requirements)

🎯 Skills

Nexus AI includes 18+ built-in skills:

• System - App control, volume, file operations
• WhatsApp - Automated messaging via Chrome/Safari
• Web - Search, browse, scrape
• Vision - Object detection, image analysis
• Email - Send/read emails
• Weather - Current conditions and forecasts
• Automation - Keyboard/mouse control
• Memory - Context and conversation history
• Screenshot - Capture screen
• Datetime - Time and date queries
• Notes - Create and manage notes
• Reminders - Set reminders
• Tasks - Task management
• Detection - Object detection with AI
• Camera - Camera control
• Execution - Code execution

🛠️ Development

Adding Custom Skills

Create a new file in skills/:

from core.skill import Skill

class MySkill(Skill):
    @property
    def name(self):
        return 'my_skill'
    
    def get_tools(self):
        return [...]  # Define your tools
    
    def get_functions(self):
        return {...}  # Map tool names to functions

Skills are auto-loaded on startup.

📝 Configuration

See .env.template for all available options:

• API keys (Gemini, Groq)
• Voice settings
• Logging levels
• Feature toggles
• State machine configuration

🐛 Troubleshooting

Voice not working?

• Check microphone permissions
• Verify pyttsx3 installation on Windows/Linux

WhatsApp automation fails?

• Ensure Chrome is installed
• First run requires QR code scan
• Check contacts.json format

Import errors?

• Activate virtual environment: source .venv/bin/activate
• Reinstall dependencies: pip install -r requirements.txt

📊 Architecture

Nexus uses a disciplined state machine architecture:

IDLE → THINKING → EXECUTING → COMPLETED → IDLE
           ↓
         ERROR → IDLE
           ↓
       ABORTING → IDLE

Key Features:

• ✅ Sequential execution (no concurrent tasks)
• ✅ 60-second short-term memory for context
• ✅ Local-first command routing (80-85% faster)
• ✅ Minimal responses ("Done.", "Opened.", "Sent.")
• ✅ Safe abort mechanism

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

👤 Author

Pratik Mishra (@pratik1258m)

⭐ Show Your Support

Give a ⭐️ if this project helped you!

---

Made with ❤️ using Python, Gemini AI, and Groq