EN PT DE

Projekt

MyAssistant

Open-Source KI-Sprachassistent (Desktop).

Projekt-README

MyAssistant

Voice assistant with a desktop UI (PyQt5) that:

  • captures speech from the microphone;
  • sends text to an LLM agent (LlamaIndex + Groq/Ollama);
  • runs tools such as text-to-speech, notes, email, Spotify, date/time, and crypto quotes.

Features

  • Desktop UI with a button to start voice recognition;
  • real-time audio visualizer;
  • agent with tools for lightweight automation;
  • environment variables via .env and an in-app Configurations tab (API keys + language).

Project layout

  • main/: app entry point and config;
  • ui/: main window and visual components;
  • recognition_of_speech/: speech recognition;
  • agents/: LLM agents and tools;
  • features/: integrations and feature logic;
  • speak/: text-to-speech.

Requirements

  • Python 3.10+ (3.11 recommended)
  • pip
  • Internet access for external services (Groq, ElevenLabs, Spotify, CoinMarketCap)

Environment variables

  1. Copy the example file:
cp .env.example .env
  1. Fill in .env:
APP_LANGUAGE=en_US
ELEVENLABS_API_KEY=
GROQ_API_KEY=
COINMARKETCAP_API=
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=

APP_LANGUAGE controls the UI, embedded terminal messages, and Google speech language: pt_BR, en_US, de_DE, or es_ES. You can also change it under Configurations in the app.

Local data

The project expects a data/notes/ folder.

  • Example email list: data/notes/e-mails.example.txt
  • Create the real file:
cp data/notes/e-mails.example.txt data/notes/e-mails.txt

Run locally

Ubuntu / Zorin / Debian-based distros

  1. Install system packages:
sudo apt update
sudo apt install -y python3-venv python3-dev portaudio19-dev
  1. Create and activate a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
  1. Install Python dependencies:
python -m pip install --upgrade pip
pip install -r requirements.txt
  1. Run:
python -m main.app

Windows (PowerShell)

  1. Create a virtual environment:
py -m venv .venv
  1. Activate it:
.venv\Scripts\Activate.ps1
  1. Install dependencies:
python -m pip install --upgrade pip
pip install -r requirements.txt
  1. Run:
python -m main.app

If PyAudio fails to install, install Visual Studio Build Tools (C++ workload) and try again.

macOS

  1. Install Python 3 and PortAudio if needed:
brew install python portaudio
  1. Create and activate a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
  1. Install dependencies:
python -m pip install --upgrade pip
pip install -r requirements.txt
  1. Run:
python -m main.app

Troubleshooting

  • Microphone / no speech detected
  • Check OS microphone permission and default input device.

  • On Linux, use system settings or pavucontrol to pick the correct input.

  • PyAudio issues

  • Linux: ensure portaudio19-dev is installed.
  • macOS: ensure portaudio is installed (Homebrew).

  • Windows: may require Visual C++ Build Tools.

  • External API failures

  • Verify keys in .env or save them in Configurations.
  • Check network connectivity.

MVP checklist (keep it small)

  • [ ] .env with at least GROQ_API_KEY (and any other keys you actually use).
  • [ ] data/notes/e-mails.txt if you test email-related features.
  • [ ] Smoke test: open app → voice button → one agent command.
  • [ ] Tell users: keys belong in .env; never commit .env to git.
  • [ ] Optional: disable or skip heavy tools you won’t demo (smaller/fewer failure modes).

Windows executable (PyInstaller)

Build on a Windows machine (same Python version you use to develop).

  1. Create a venv and install deps (see Windows (PowerShell)).
  2. Install PyInstaller: pip install pyinstaller
  3. From the repo root, run:
scripts\build_windows.bat

Output: dist\MyAssistant\MyAssistant.exe

Distribute the entire dist\MyAssistant\ folder (not only the .exe). Place next to MyAssistant.exe:

  • Your .env (or configure keys in the app once on that PC).
  • data\notes\ if you use notes or the email list file.

Debug build (show console errors): edit scripts\build_windows.bat and replace --windowed with --console.

Notes

  • The first build might need extra --hidden-import=... if PyInstaller misses a lazy-imported module (the error usually names it).
  • Antivirus may briefly flag a new .exe (false positive); code signing is a later step.
  • The bundle can be large (ML + UI). --onedir is the default and is usually more reliable than --onefile for Qt.

Notes

  • This project is an early prototype.
  • Do not commit your .env file to the repository.
Source code