{"id":28858092,"url":"https://github.com/gorgogerbis/k2so-personal-assistant","last_synced_at":"2026-04-19T07:32:31.035Z","repository":{"id":297873576,"uuid":"986646437","full_name":"GorgoGerbis/k2so-personal-assistant","owner":"GorgoGerbis","description":"K-2SO Personal Droid is an open-source, modular voice assistant platform inspired by the droid K-2SO from Star Wars: Rogue One. It’s designed to run fully offline or connect to remote models, giving you complete control over your AI assistant’s privacy, features, and capabilities.","archived":false,"fork":false,"pushed_at":"2025-06-08T05:09:48.000Z","size":7558,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-20T02:04:48.317Z","etag":null,"topics":["local-llm","raspberry-pi","voice-assistant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GorgoGerbis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-19T23:32:12.000Z","updated_at":"2025-06-08T02:21:01.000Z","dependencies_parsed_at":"2025-06-08T03:52:29.177Z","dependency_job_id":null,"html_url":"https://github.com/GorgoGerbis/k2so-personal-assistant","commit_stats":null,"previous_names":["gorgogerbis/k2so-personal-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GorgoGerbis/k2so-personal-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GorgoGerbis%2Fk2so-personal-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GorgoGerbis%2Fk2so-personal-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GorgoGerbis%2Fk2so-personal-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GorgoGerbis%2Fk2so-personal-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GorgoGerbis","download_url":"https://codeload.github.com/GorgoGerbis/k2so-personal-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GorgoGerbis%2Fk2so-personal-assistant/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260862914,"owners_count":23074182,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["local-llm","raspberry-pi","voice-assistant"],"created_at":"2025-06-20T02:04:48.815Z","updated_at":"2025-10-06T10:35:45.472Z","avatar_url":"https://github.com/GorgoGerbis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# K-2SO Personal (Droid) Assistant\nA fully offline, modular voice assistant designed for the Raspberry Pi and desktop. Inspired by K-2SO from Star Wars: Rogue One.\n\nK-2SO Personal (Droid) Assistant runs quantized Llama models locally, routes commands, and speaks—all without sending your data to the cloud. The architecture is modular: swap in new language models, add custom commands, or plug in your favorite TTS/STT engine. A planned animated face GUI and persistent chat log make it more than just a CLI tool.\n\n![K-2SO Prototype Front View](assets/k2so_prototype1_front.png)\n*Prototype 1: Front view of the K-2SO assistant interface*\n\n![K-2SO System Diagram](assets/k2so_prototype1_backside_diagram.png)\n*System architecture diagram for PROTOTYPE K-2SO interface*\n\n![K-2SO Animation Demo](assets/k2so_speaking_animation_prototype_waves_freqBars.gif)\n*Visual AI indicator with dual animation modes - ripples and frequency bars*\n\n\u003e \"I'm with you. The captain said I had to.\" — K-2SO\n\n### Model Flexibility\nK-2SO Personal Droid is designed for maximum flexibility in how you run language models:\n- **Run Any Quantized Model Locally:**  \n  Use efficient GGUF models (like Llama, TinyLlama, Phi-2, etc.) on your own hardware for full privacy and offline operation.\n- **Connect to Any API Model Remotely:**  \n  Seamlessly route requests to a remote server, LAN PC, or cloud API—use larger or proprietary models when you need more power.\n- **Swap Backends On the Fly:**  \n  The assistant's modular architecture lets you switch between local and remote models at runtime, or even route specific commands to different backends.\n\n**Purpose:**  \nThis project is a robust skeleton for building your own AI assistant—customize the models, commands, and features to fit your workflow. Whether you want a fully offline experience, cloud-powered intelligence, or a hybrid of both, K-2SO makes it easy to experiment and extend.\n\n\n## Table of Contents\n\n- [Features](#features)\n- [Directory Structure](#directory-structure)\n- [How It Works](#how-it-works)\n- [Setup](#setup)\n- [Running the Project](#running-the-project)\n- [Pi Setup](#pi-setup)\n- [Development Roadmap](#development-roadmap)\n\n\n## Features\n\n- [x] Local LLM inference (Llama, GGUF)\n- [x] Modular command routing\n- [ ] Wake-and-listen loop\n- [ ] Offline speech-to-text\n- [ ] Local text-to-speech\n- [ ] Animated GUI (planned)\n\n## Directory Structure\n\nHere's a quick look at how this project is organized:\n\n```plaintext\nk2so-personal-assistant/\n├── .gitignore                # Standard git ignore rules\n├── assets/                   # Images, GIFs, and media for README/docs\n├── README.md                 # Project overview and instructions\n├── requirements.txt          # Python dependencies (may be empty if using pip install directly)\n├── user_config.json          # User-specific config (not required for all setups)\n├── src/                      # All main source code lives here\n│   ├── main.py               # Entry point for the assistant\n│   ├── config.py             # Runtime settings and config logic\n│   ├── router.py             # Chooses between local or remote model backends\n│   ├── components/           # Core assistant modules\n│   │   ├── __init__.py       # Marks components as a package\n│   │   ├── local_model.py    # Handles local LLM via llama-cpp-python\n│   │   ├── remote_model.py   # Handles remote/LAN/cloud model requests\n│   │   ├── chat_session.py   # Manages chat loop and prompt formatting\n│   │   └── text_to_speech.py # Text-to-speech logic (pluggable for different TTS engines)\n│   └── __init__.py           # Marks src as a package\n├── models/                   # Place downloaded GGUF model files here (not tracked by git)\n├── .venv-k2so/               # Python virtual environment (not tracked by git)\n├── .vscode/                  # VSCode settings (optional, for editor config)\n│   └── settings.json         # Editor-specific settings\n└── .git/                     # Git version control (auto-managed)\n```\n\n## How It Works\n\n- **Startup:**  The assistant launches from `src/main.py`, loading configuration and selecting either a local or remote language model.\n\n- **Core Modules:**\n  - `local_model.py`: Runs a quantized Llama model locally using `llama-cpp-python`.\n  - `remote_model.py`: Connects to a remote/LAN server for model inference.\n  - `chat_session.py`: Manages the conversation loop and context.\n  - `text_to_speech.py`: Handles text-to-speech output.\n\n- **Workflow:**\n  1. Waits for a trigger (key press, timer, or hotword).\n  2. (Planned) Converts speech to text.\n  3. Routes input to the appropriate model.\n  4. Generates a response.\n  5. Speaks the response aloud.\n  6. Logs interactions for debugging.\n\n- **Extensibility:**  The modular design makes it easy to add new commands, swap models, or upgrade TTS/STT features.\n\n## Setup\n\n1. Create virtual environment:\n```bash\npython -m venv .venv-k2so\n```\n\n2. Activate the environment (see above for your shell)\n\n3. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n## Running the Project\nThe project uses a virtual environment named `.venv-k2so`. After setup, you can activate and run the project:\n\n```powershell\n# Windows PowerShell\n.\\.venv-k2so\\Scripts\\Activate.ps1\n\n# Windows Command Prompt\n.\\.venv-k2so\\Scripts\\activate.bat\n\n# Linux/Mac\nsource .venv-k2so/bin/activate\n```\n\nOnce activated, run the project from the root directory:\n```bash\npython src/main.py\n```\n\n## Raspberry-Pi Setup\n1. Update Raspberry Pi:\n```bash\nsudo apt update \u0026\u0026 sudo apt upgrade -y\n```\n2. Install Python 3 and build tools:\n```bash\nsudo apt install -y python3 python3-pip python3-venv build-essential\n```\n\n3. Create a virtual environment:\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n4. Install Python Packages: WIP\n```bash\npip install llama-cpp-python\n```\n\n5. Download a Small Quantized Model: WIP\n    - Option A: With Hugging Face CLI\n    - Option B: Direct Download\n\n\n## Development Roadmap\n\n### **MVP Features**:\n- [ ] basic wake-and-listen loop (triggered by key press, timer, or hotword)\n- [ ] offline speech-to-text using microphone input\n- [ ] local text-to-speech output\n- [ ] simple command routing with keyword-based logic (e.g., time, date, shutdown)\n- [ ] response behavior defined in a local module\n- [ ] fully offline operation with no cloud services or network dependency\n- [ ] console logging of input and output for debugging\n\n### **Planned Features**:\n- **Face GUI**: animated AI face with expressions that react to conversation and speech\n  * The face should visually indicate when the AI is listening, thinking, or speaking (e.g., mouth movement, eye color changes).\n  * Use a simple animated face or waveform circle as a starting point, with potential for more expressive features later.\n- **Chat Log**: persistent chat history for each session\n  * Store all user and assistant messages locally for each session.\n  * Support reviewing or exporting past conversations for context or debugging.\n- **Easy Setup Interface**: GUI or executable for first-time setup (API keys, model selection, etc.)\n  * Provide a user-friendly interface for configuring model paths, preferences, and hotword settings.\n  * Save user preferences in a config directory for easy reloading and updates.\n- **Voice Toggle**: flags to enable/disable text-to-speech and speech-to-text\n  * Allow users to switch between voice and text modes on the fly.\n  * Include adjustable speaking rate and voice settings for TTS, plus an optional hotword detection toggle.\n- **Conversational Memory**: maintain context for back-and-forth, multi-turn conversations\n  * Implement a message handler pattern for extensible command-response workflows.\n  * Use local intent parsing to match natural language input and support contextual follow-ups.\n- **Resource/Cost Tracking**: track resource usage (RAM, CPU, model size) and, for remote models, estimate API cost per prompt\n  * Display or log resource usage statistics for transparency and optimization.\n  * Provide warnings or suggestions if resource usage is high or if a remote model may incur costs.\n- **Modular Command Handling**: extend system functions (e.g., weather, file access)\n  * Design a plugin-like system for adding new commands or skills easily.\n  * Ensure robust error handling and fallback behavior for unsupported or failed commands.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgorgogerbis%2Fk2so-personal-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgorgogerbis%2Fk2so-personal-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgorgogerbis%2Fk2so-personal-assistant/lists"}