A voice-controlled AI assistant inspired by Neptr from Adventure Time, designed to run on Raspberry Pi 4. NEPTR (Not Evil Pie-Throwing Robot) is your friendly robot companion that responds to voice commands with personality and enthusiasm!

• Voice Wake Word Detection: Say "Hello Neptr" to activate
• Speech Recognition: Converts your voice to text using Vosk
• Text-to-Speech: Responds with a robotic voice using espeak-ng
• Neptr Personality: Friendly, enthusiastic responses in character
• Multiple Commands: Time, date, jokes, math, weather, and more
• OpenAI Integration: Optional cloud brain for advanced conversations
• Raspberry Pi Optimized: Designed specifically for Pi 4 performance

• Time: "What time is it?"
• Date: "What's the date today?"
• Name: "What's your name?"
• Jokes: "Tell me a joke"
• Status: "How are you feeling?"
• Math: "Calculate 15 plus 27"
• Pi: "Tell me about pi"

• OpenAI Integration: Ask complex questions (requires API key)
• Weather: Get weather information (requires API setup)
• Conversation: Chat naturally with Neptr's personality

• Raspberry Pi 4 (2GB RAM minimum, 4GB recommended)
• Microphone and speakers/headphones
• Internet connection for initial setup
• OpenAI API key (for advanced features)

For Raspberry Pi (Recommended):

curl -sSL https://raw.githubusercontent.com/johhncastro/neptr/main/install_neptr.sh | bash

This single command will:

• ✅ Download the complete NEPTR repository
• ✅ Install all system dependencies
• ✅ Set up Python virtual environment
• ✅ Download speech recognition model
• ✅ Configure audio permissions
• ✅ Create helper scripts and desktop shortcut
• ✅ Optimize for Bookworm Lite OS

1. Navigate to the installation directory

   cd ~/neptr

2. Test your setup

   ./test_neptr.sh

3. Set up your API key (optional)

   # Copy the template
   cp run_neptr_template.sh run_neptr.sh
   
   # Edit the file and add your OpenAI API key
   nano run_neptr.sh

   Replace your-openai-api-key-here with your actual OpenAI API key:

   export OPENAI_API_KEY="sk-your-actual-api-key-here"

4. Make the script executable

   chmod +x run_neptr.sh

5. Start NEPTR

   ./start_neptr.sh

If you prefer to install manually or are not using a Raspberry Pi:

1. Clone the repository

   git clone https://github.com/johhncastro/neptr.git
   cd neptr

2. Install system dependencies

   sudo apt update
   sudo apt install python3-pip python3-venv espeak-ng portaudio19-dev python3-pyaudio python3-dev build-essential

3. Create virtual environment

   python3 -m venv neptr_env
   source neptr_env/bin/activate

4. Install Python packages

   pip install -r requirements.txt

5. Download speech model

   mkdir -p ~/models
   cd ~/models
   wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
   unzip vosk-model-small-en-us-0.15.zip
   rm vosk-model-small-en-us-0.15.zip
   cd ~/neptr

6. Set up API key

   cp run_neptr_template.sh run_neptr.sh
   nano run_neptr.sh  # Add your OpenAI API key
   chmod +x run_neptr.sh

Note: The one-command installer is recommended as it handles all dependencies and optimizations automatically.

1. Go to OpenAI Platform
2. Sign up or log in
3. Navigate to "API Keys" section
4. Create a new API key
5. Copy the key (starts with sk-)

The project includes a template file to safely store your API key:

# Copy the template
cp run_neptr_template.sh run_neptr.sh

# Edit with your API key
nano run_neptr.sh

Important Security Notes:

• The run_neptr.sh file is in .gitignore to prevent accidentally committing your API key
• Never share your API key publicly
• The template file (run_neptr_template.sh) is safe to commit as it contains no real keys

You can also set these in your shell or add to ~/.bashrc:

# For OpenAI integration (optional)
export OPENAI_API_KEY="your-openai-api-key-here"

# For weather API (optional)
export WEATHER_API_KEY="your-weather-api-key-here"

Edit neptr.py to customize:

• Wake phrases: Modify the TRIGGERS list
• Voice settings: Adjust voice_speed and voice_pitch in the tts() function
• Personality: Add more responses to the various response lists
• Commands: Add new intent patterns and handlers

Neptr supports multiple TTS engines for different voice qualities:

• Included with your OpenAI API key
• Voices: alloy (deep/robotic), echo, fable, onyx, nova, shimmer
• Configure: Edit config.py to change OPENAI_TTS_VOICE

• Runs locally without internet
• Multiple voice models available
• Configure: Set TTS_ENGINE = "piper" in config.py

• Always works, basic quality
• Configurable speed and pitch
• Configure: Set TTS_ENGINE = "espeak" in config.py

# Test current voice
python3 tests/test_openai_tts.py

# Test all voice options
python3 tests/test_voice.py

1. Navigate to NEPTR directory:

   cd ~/neptr

2. Set up your API key (if not done already):

   cp run_neptr_template.sh run_neptr.sh
   nano run_neptr.sh  # Add your OpenAI API key
   chmod +x run_neptr.sh

3. Run the assistant: ./start_neptr.sh

4. Say "Hello Neptr" to wake it up

5. Speak your command clearly

6. Listen to Neptr's response

You: "Hello Neptr"
Neptr: "Hello! I am N.E.P.T.R., your friendly pie-throwing robot!"

You: "What time is it?"
Neptr: "The current time is 2:30 PM. My internal clock is very precise!"

You: "Tell me a joke"
Neptr: "Why did the robot cross the road? Because it was programmed by a chicken!"

You: "Calculate 15 plus 27"
Neptr: "The answer is 42. My calculations are always precise!"

"Vosk model not found"

• Run the installer again: curl -sSL https://raw.githubusercontent.com/johhncastro/neptr/main/install_neptr.sh | bash
• Or manually download the model from https://alphacephei.com/vosk/models

"No module named 'sounddevice'"

• Navigate to NEPTR directory: cd ~/neptr
• Activate the virtual environment: source neptr_env/bin/activate
• Reinstall dependencies: pip install -r requirements.txt

Audio not working

• Check status: cd ~/neptr && ./neptr_status.sh
• Reboot to activate permissions: sudo reboot
• Test audio: arecord -d 5 test.wav && aplay test.wav

Wake word not detected

• Speak clearly and at normal volume
• Try different wake phrases: "Hey Neptr", "Hi Neptr", "Neptr"
• Check microphone levels in system settings

OpenAI API not working

• Navigate to NEPTR directory: cd ~/neptr
• Verify your API key is set in run_neptr.sh
• Check that you have sufficient API credits
• Ensure internet connection is working
• Test with: ./test_neptr.sh

• Reduce CPU usage: Lower SAMPLE_RATE to 8000 (less accurate but faster)
• Faster responses: Use a smaller Vosk model
• Better accuracy: Use a larger Vosk model (more CPU intensive)

• LED indicators: Add status LEDs for wake word detection
• Physical button: Add a push button for manual activation
• Display: Add a small LCD screen for visual feedback
• Servo motors: Add moving parts for more robot-like behavior

• Music player: Add Spotify/MP3 playback capabilities
• Home automation: Integrate with smart home devices
• Reminders: Add calendar and reminder functionality
• Voice training: Improve wake word detection with custom training

This project is open source. Feel free to modify and distribute!

Contributions are welcome! Some ideas:

• Add new commands and capabilities
• Improve speech recognition accuracy
• Add more personality responses
• Create hardware integration guides
• Optimize for different Raspberry Pi models

• Vosk: Speech recognition engine
• espeak-ng: Text-to-speech synthesis
• Adventure Time: Inspiration for Neptr's character
• Raspberry Pi Foundation: For making this possible

Remember: NEPTR is Not Evil Pie-Throwing Robot - friendly, helpful, and always ready to assist! 🤖🥧