Kei Typing Assistant

An AI-powered desktop typing assistant that provides real-time text completions as ghost text via a floating overlay window, accessible from any application. Learns your writing style over time for increasingly personalized suggestions.

Features

• Global hotkey opens a compact overlay window from any app; press it again to copy and close
• Streaming AI suggestions appear as faint ghost text while you type
• Accept a suggestion with Tab, dismiss with Esc
• Three AI providers: local LLM (llama.cpp, runs fully offline), MiniMax, and OpenRouter
• Hybrid mode: races the local model against a cloud provider and upgrades to the cloud result if it arrives first, within a configurable time window
• Model warm-up loads the local model in the background at startup so the first suggestion isn't slowed by a cold start
• Accepted suggestions are stored with semantic embeddings and retrieved as personalized few-shot context, with per-example search/shown counts tracked over time
• Manage stored examples (view, search, add, delete) from a dedicated GUI window
• Reusable, ordered context fragments — curated notes you can prepend to the AI system prompt — managed from their own GUI window
• Mid-word suppression skips AI requests while the cursor sits inside a word
• API keys stored securely in the system keychain
• SQLite storage with Alembic-managed schema migrations

Requirements

• Python 3.12+
• macOS 12+ (primary), Windows 10/11, Linux supported
• API key for MiniMax or OpenRouter (not required for the default local LLM provider)
• macOS: Accessibility permission required for global hotkey

Quick Start

1. Install

git clone https://github.com/l0kifs/kei-typing-assistant.git
cd kei-typing-assistant
uv sync

2. Configure (optional)

Create a .env file in the project root to override defaults:

KEI__AI_PROVIDER=local_llm      # local_llm | minimax | openrouter
KEI__HOTKEY=ctrl+alt+space      # global hotkey
KEI__FLAVOUR="Concise, formal"  # personalization hint for AI

All settings with defaults are documented in src/kei_typing_assistant/config/settings.py.

3. Add your API key (cloud providers only)

If using MiniMax or OpenRouter, open Settings from the tray icon and enter your API key. Keys are stored in the system keychain — never in plaintext. The default local LLM provider needs no API key; the model is downloaded from Hugging Face on first run.

4. Grant Accessibility permission (macOS)

System Settings → Privacy & Security → Accessibility — add the app or your terminal to allow global hotkey capture.

5. Run

uv run kei

The app runs in the system tray. Press the hotkey (Ctrl+Alt+Space by default) to open the overlay.

Usage

AI Providers

Settings Window

Two standalone windows, opened from the tray/settings menu, manage personalization data directly:

• Context Fragments — add, edit, reorder, search, and delete reusable prompt snippets prepended to the AI system prompt when enabled
• Suggestion Examples — browse, search, add, and delete the accepted (input → suggestion) pairs used for semantic few-shot retrieval, including how often each has been searched/shown

Configuration Reference

Full list of settings, defaults, and validation ranges: src/kei_typing_assistant/config/settings.py.

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/kei_typing_assistant

# Lint & format
ruff check .
ruff format .

CLI Reference

kei-cli provides a command-line interface for testing suggestions, managing the semantic example store, local models, database migrations, and configuration.

uv run kei-cli [--verbose] COMMAND [ARGS]

Suggestion commands

Typical workflow:

# 1. Get a suggestion
uv run kei-cli suggest "The weather today is"
#   → warm and sunny with clear skies

# 2. Accept it — embeds and saves for future retrieval
uv run kei-cli accept "The weather today is" "warm and sunny with clear skies"
#   ✓ Saved: 'The weather today is' → 'warm and sunny with clear skies'

# 3. Next suggest call retrieves similar stored examples as context
uv run kei-cli suggest "The weather this morning is"

suggest options: --flavour TEXT, --max-tokens INT test options: --text TEXT, --flavour TEXT, --max-tokens INT

Local model

uv run kei-cli model list             # List downloaded models
uv run kei-cli model status MODEL_ID  # Check if a model is downloaded
uv run kei-cli model delete MODEL_ID  # Delete a downloaded model from disk

Database

uv run kei-cli db upgrade   # Migrate the database to the latest schema revision
uv run kei-cli db current   # Show the currently applied schema revision

Configuration

uv run kei-cli config show      # Show current configuration

Architecture

The project follows Domain-Driven Design. See docs/ddd-architecture-rules.md for conventions and docs/BRD.md for the business requirements behind it.

src/kei_typing_assistant/
├── main.py          # Composition root: wiring, bootstrap, launch
├── config/          # Settings & logging
├── domains/         # Pure business logic (suggestion, context_fragments, local_model)
├── infrastructure/  # AI provider clients, SQLite database + Alembic migrations, keychain
└── entry_points/    # Qt GUI, hotkey listener, tray, CLI, background workers

Database schema changes are managed with Alembic; migrations run automatically at startup (kei-cli db upgrade for manual control).

Publishing

See docs/PUBLISHING.md. Releases are published to PyPI automatically via GitHub Actions on tag push. See CHANGELOG.md for release history.