sam4rano/Ase_agent

Àṣẹ (ah-sheh) — In Yoruba, the word spoken after a command to affirm it will be carried out. This project brings that power to your Mac: speak in Yoruba, and your computer listens. # Àṣẹ Agent — Autonomous Yorùbá Voice Assistant for macOS > **Àṣẹ** — *"So it is. Let it be done."* Àṣẹ is a highly modular, fully offline, Yorùbá-language voice assistant for macOS built on Apple Silicon. Speak in Yorùbá (or mixed Yorùbá–English) to control your Mac: open apps, browse the web, search files, type text, and more. --- ## 🚀 Quick Start ```bash # 1. Clone git clone github.com cd Ase_agent # 2. Bootstrap (installs dependencies + downloads ~1.3GB of models) bash setup.sh # 3. Grant macOS Permissions # System Settings → Privacy → Microphone → enable Terminal # System Settings → Privacy → Accessibility → add Terminal # 4. Run the Agent source venv/bin/activate python3 src/main.py # Optional Flags: # python3 src/main.py --no-vlm # Skip loading the 2B Vision model (saves ~4GB RAM) # python3 src/main.py --no-wakeword # Use push-to-talk (ENTER key) instead of background listening ``` See **instruction.md** for the deep-dive setup guide. --- ## 🧪 Testing We maintain a robust suite of unit tests for core logic (Parser, Executor, Memory). ```bash # Run all tests source venv/bin/activate pip install pytest pytest tests/ -v ``` --- ## 🧠 Architecture & Tech Stack Àṣẹ is built to run entirely locally on an M1/M2/M3 Mac, ensuring absolute privacy and low latency. ```mermaid graph TD; A[Continuous Wake Word Listening] --> B[LyngualLabs Yorùbá STT]; B --> C[Qwen2.5-1.5B LLM Parser]; C --> D[SQLite Memory Database]; D --> E[ReAct Execution Loop]; E --> F[MacExecutor / Playwright Browser]; F -->|Visual Grounding via VLM| E; E --> G[MMS-TTS Dynamic Yorùbá Response]; ``` | Component | Model / Library | |---|---| | **STT Engine** | `LyngualLabs/whisper-small-yoruba` (Fine-tuned Whisper) | | **Command Parser** | `mlx-community/Qwen2.5-1.5B-Instruct-4bit` (via MLX) | | **Wake Word Engine** | `openWakeWord` (Continuous background listening) | | **Memory & State** | Built-in `sqlite3` for rolling contextual memory | | …