Zeke – Your Personal AI‑powered Desktop Companion 🚀

---

Table of Contents

• Overview
• Key Features
• Installation
• Quick‑Start Commands
• Configuration
• Using the Floating Widgets
  • AI Assistant Pill – zeke widget
  • Dictation Pill – zeke widgetflo
• Advanced Usage
• Development & Contributing
• License

---

Overview

Zeke is a sleek, Python‑based desktop companion that brings natural‑language AI, voice control, and system‑wide dictation to any Windows machine. It lives in the background, stays out of your way, and surfaces when you need it – all with a premium, dark‑theme UI that feels right at home on modern Windows desktops.

“Zeke, open my inbox.” → Zeke listens, interprets, and executes – instantly.

The newest addition, widgetflo, is a lightweight, always‑on‑top dictation pill that transforms spoken words into typed text anywhere you place the cursor, without ever stealing focus.

---

Key Features

Feature	Description
Voice Commands	Speak natural language to launch apps, send messages, control windows, etc.
AI Assistant Pill (zeke widget)	Small floating pill that activates Zeke’s LLM‑driven capabilities.
Dictation Pill (zeke widgetflo)	System‑wide voice‑to‑text widget – click → speak → text appears at cursor instantly.
Background Scheduler (zeke watch)	Runs health checks, activity logs, and scheduled routines 24/7.
Modular CLI	All functionality reachable via a tidy zeke command set.
Premium UI	Dark black background, light‑purple accents, smooth micro‑animations, no hover borders.
Fast & Accurate STT	Low‑latency transcription using Whisper‑fast with VAD filtering.
Config‑driven	All behaviour (max recording time, silence threshold, theme colors) is tweakable in zeke.json.

---

Installation

1. Prerequisites

   • Windows 10/11 (64‑bit)
   • Python 3.12 (recommended – the bundled venv venv312 is pre‑configured)
   • A working microphone and speaker.

2. Clone the repository

   git clone https://github.com/your‑org/zeke.git
   cd zeke

3. Create and activate the virtual environment

   python -m venv venv312
   .\venv312\Scripts\activate

4. Install dependencies

   pip install -r requirements.txt
   # optional: GPU‑accelerated Whisper models
   pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu121

5. Run the diagnostic command to ensure everything is ready:

   zeke doctor

   It will verify Python version, microphone access, and required packages.

---

Quick‑Start Commands

# General workflow
zeke doctor          # Verify your environment
zeke add ./my-project # Register a project (optional)
zeke run my-project   # Run analysis / AI on a project

# Voice‑centric commands
zeke listen          # Activate voice mode (say "Hey Zeke")
zeke widget          # Launch the AI assistant pill
zeke widgetflo       # Launch the dictation pill (system‑wide voice‑to‑text)

# Automation & monitoring
zeke watch           # Start background health & activity monitoring

Inline help

Run zeke --help or zeke <command> --help for detailed flag information.

---

Configuration

All settings live in zeke.json at the repository root. Example excerpt:

{
  "voice": {
    "stt_model": "small",               // Whisper model size
    "dictation_max_seconds": 30,          // Max recording length
    "dictation_silence_ms": 2500,         // Silence timeout before auto‑stop
    "stt_language": "en"                // Language code for Whisper
  },
  "ui": {
    "theme": {
      "background": "#000000",
      "accent": "#A78BFA",
      "text": "#FFFFFF"
    }
  }
}

Edit these values to customise recording limits, colors, or the Whisper model you prefer.

---

Using the Floating Widgets

AI Assistant Pill – zeke widget

• Appearance: 40 × 40 px rounded capsule, pure black with a subtle light‑purple outline.
• Interaction:
  1. Click → mic activates (purple glow) and you can speak a command.
  2. Zeke processes the request via its LLM and performs the action.
  3. Click again to cancel or when idle.
• Focus handling: The pill never takes keyboard focus, so your current window remains active.

Dictation Pill – zeke widgetflo

• Purpose: System-wide voice-to-text; ideal for dictating emails, notes, or code without touching the keyboard.
• Design:
  • Compact taskbar-sized 180 × 36 px pill with a flat dark-black background (#0a0a0f) and light-purple outline (#A78BFA).
  • Monospace typography (Geist Mono / SF Mono / JetBrains Mono) matching the Vercel/Linear style, rendered at 11px for all states.
  • Slight 6px border radius, creating a visual appearance matching native Windows taskbar search inputs.
  • IDLE State: Horizontally centered group consisting of a scaled 12px microphone icon, a vertical divider, and "Start Recording" text in light purple (#A78BFA). Hovering smoothly fades the text to white (#FFFFFF) and morphs the mic to a richer deep purple.
  • RECORDING State: Compact, left-aligned layout featuring ■ Stop on the left, a vertical divider, the elapsed timer in the center, another vertical divider, and a compact 5-bar dynamic waveform on the right.
  • TRANSCRIBING State: Horizontally centered group containing a rotating purple arc spinner (24px diameter) orbiting concentrically around a centered microphone icon with a clean 6px spacing gap, a vertical divider, and "Transcribing..." text in light purple (#A78BFA).
  • Success State: Horizontally centered group featuring a green check-mark icon inside a green circle, a vertical divider, and "Pasted!" text in success green (#22C55E).
  • Error State: Styled consistently with the light-purple design system — contains a centered warning triangle, a vertical divider, and the error message in light purple (#A78BFA) over the dark-black background.
• Workflow:
  1. Place the cursor exactly where you want the text to go.
  2. Click the pill → starts recording immediately.
  3. Speak naturally for as long as you need — automatic silence detection is disabled so it never starts transcribing/pasting while you are thinking or paused.
  4. Click the pill again to stop recording → transcription finishes in-memory using fast, low-latency STT.
  5. The transcribed text is pasted instantly at the cursor position (keyboard focus is never stolen from the active window, and the cursor stays in place).
• Customization: Colors and configurations are tweakable via zeke.json.

---

Advanced Usage

• Testing UI states: zeke widgetflo --test-states cycles through all visual states (IDLE → RECORDING → TRANSCRIBING → DONE → ERROR) for rapid UI verification.
• Programmatic control: Import FloatingDictationPill and DictationController from zeke.widget to embed the widget into your own PyQt applications.
• Extending STT: The STT class now offers ._transcribe_fast() for low‑latency dictation. You can call it directly if you need custom handling.

---

Development & Contributing

1. Fork the repo and create a feature branch.
2. Run tests (if any) with pytest:

   pytest -q

3. Lint using ruff to keep the codebase clean:

   ruff check .

4. Submit a Pull Request – describe the change, include screenshots or GIFs of UI updates, and ensure all CI checks pass.

All contributions follow the same premium UI guidelines (dark theme, light‑purple accents, micro‑animations). Feel free to suggest new widget ideas!

---

License

Distributed under the MIT License. See LICENSE for full text.

---

Enjoy a smoother, voice‑first workflow with Zeke – the AI companion that never gets in your way.