🎙️ Pixie - AI Voice Assistant

A sophisticated voice-enabled AI assistant powered by Google's Gemini 2.0 Flash model, enabling natural conversational interactions with advanced language understanding.

📋 Table of Contents

Features
Prerequisites
Installation
Configuration
Usage
Commands
Security
Architecture
Troubleshooting
Contributing
License

✨ Features

🎤 Voice Recognition - Real-time speech-to-text using Google Speech Recognition
🤖 AI-Powered Responses - Advanced language model (Gemini 2.0 Flash) for intelligent answers
🔊 Text-to-Speech - Natural-sounding audio output with pyttsx3
💬 Conversation Memory - Maintains conversation history for contextual awareness
🌐 Local Task Integration - Quick access to web browsers, time, and system operations
🔒 Enterprise-Grade Security - Secure API key management and input validation
⚡ Low Latency - Optimized for quick response times with token-limited outputs

📦 Prerequisites

Before you begin, ensure you have the following installed:

Python 3.7 or higher
pip (Python package manager)
Microphone connected to your system
Google Gemini API Key (free tier available)

System Requirements

Component	Requirement
OS	Windows, macOS, Linux
RAM	4GB minimum (8GB recommended)
Storage	~200MB for dependencies
Internet	Required for API calls

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/yourusername/Pixie.git
cd Pixie

Step 2: Create a Virtual Environment (Recommended)

# On Windows
python -m venv venv
venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Obtain Your API Key

Visit Google AI Studio
Click "Create API Key"
Copy your API key

Step 5: Configure Environment Variables

# Create .env file from template
cp .env.example .env

# Edit .env and add your API key
# On Windows: notepad .env
# On macOS/Linux: nano .env

Add your API key to the .env file:

GEMINI_API_KEY=your_api_key_here

⚙️ Configuration

Environment Variables

The application uses a .env file for configuration:

# Required
GEMINI_API_KEY=your_google_gemini_api_key

# Optional (can be added for future enhancements)
# VOICE_SPEED=1.5
# RESPONSE_LENGTH=70

Application Settings

Modify these constants in Pixie.py to customize behavior:

# Model Configuration
model = genai.GenerativeModel('gemini-2.0-flash')  # Change model if needed

# Response Configuration
max_output_tokens=70  # Adjust response length

🎯 Usage

Starting the Assistant

python Pixie.py

Once started, the assistant will:

Greet you with "Hi there."
Listen for voice commands continuously
Process and respond to your queries
Maintain conversation context across interactions

Example Interaction

Assistant: Hi there.
[Listening...]
You: What time is it?
Assistant: 3:45 PM
[Listening...]
You: Open YouTube
Assistant: YouTube.
[Opens YouTube in your browser]

🎤 Commands

System Commands

Command	Action
"open youtube"	Opens YouTube in default browser
"open google"	Opens Google in default browser
"what time"	Announces current time
"what day"	Announces current date
"stop"	Gracefully stops the assistant (with confirmation)
"exit"	Closes the application (with confirmation)
"interrupt"	Interrupts current task
"hello" or "start"	Resumes assistant

AI Queries

Any other voice input will be processed by the Gemini AI and generate contextual responses based on conversation history.

🔒 Security

This project implements industry best practices for security:

✅ Implemented Security Measures

Measure	Description
Environment Variables	API keys loaded from `.env`, never hardcoded
Input Validation	Voice inputs sanitized and length-limited (500 chars max)
`.gitignore`	Prevents accidental commits of sensitive files
Error Handling	Graceful exception handling without exposing sensitive data
Dependency Management	All packages specified in `requirements.txt` with versions

🚨 Important Security Guidelines

⚠️ NEVER share your API key publicly
⚠️ NEVER commit .env file to version control
⚠️ ALWAYS use .env.example as a template
⚠️ Regenerate API key if it's accidentally exposed
⚠️ Use .gitignore to exclude sensitive files

🏗️ Architecture

Component Overview

┌─────────────────────────────────────┐
│     Voice Input (Microphone)        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   Speech Recognition (Google STT)   │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   Local Task Processor              │
│   (Web, Time, Control)              │
└──────────────┬──────────────────────┘
               │
        ┌──────┴──────┐
        │             │
       Yes           No
        │             │
        ▼             ▼
   Execute        AI Response
    Local      (Gemini Model)
    Task            │
        │           ▼
        └──────┬────┘
               │
               ▼
┌─────────────────────────────────────┐
│     Text-to-Speech Output           │
└─────────────────────────────────────┘

Key Modules

genai - Google Generative AI API client
speech_recognition - Voice input processing
pyttsx3 - Text-to-speech engine
webbrowser - Browser automation for web tasks
dotenv - Environment variable management

🐛 Troubleshooting

Common Issues and Solutions

Issue: "GEMINI_API_KEY environment variable is not set"

Solution:

# Ensure .env file exists in project root
cp .env.example .env
# Add your API key to .env

Issue: Microphone not detected

Solution:

# Check microphone access/permissions
# On Windows: Check Sound Settings
# On macOS: Settings > Security & Privacy > Microphone
# On Linux: Check PulseAudio/ALSA configuration

Issue: "Huh?" response (voice not recognized)

Speak clearly and closer to microphone
Reduce background noise
Check microphone levels in system settings

Issue: API errors (quota exceeded)

Check your API quota at Google AI Studio
Review billing settings for your Google account
Consider implementing request throttling

Debug Mode

Enable verbose logging by modifying the script:

# Add at the top of main_loop()
print(f"DEBUG: Recognized command: {command}")
print(f"DEBUG: Is local task: {perform_local_task(command)}")

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

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

📞 Support

For issues, questions, or suggestions:

Check existing GitHub Issues
Search troubleshooting section above
Open a new issue with detailed information

📚 Additional Resources

🙋 FAQ

Q: Does this work offline?
A: No, it requires internet for API calls. Local TTS works offline.

Q: Is my conversation data stored?
A: Only locally in conversation_history during session. Not persisted by default.

Q: Can I customize the voice?
A: Yes, modify pyttsx3 settings for rate, voice, and volume.

Made by Arijit

Name		Name	Last commit message	Last commit date
.env.example		.env.example
.gitignore		.gitignore
Pixie.py		Pixie.py
README.md		README.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation