voculinux/AGENTS.md

AGENTS.md - Vocalinux

Guidelines for AI agents working on this codebase.

Project Overview

Vocalinux is a voice dictation system for Linux. It uses:

• Python 3.8+ for the main application
• GTK 3 (via PyGObject) for the desktop UI and system tray
• whisper.cpp (default), OpenAI Whisper, and Vosk for speech recognition
• Next.js/TypeScript for the website (in web/)

Key Dependencies

• pywhispercpp - Python bindings for whisper.cpp (default engine)
• vosk - Lightweight speech recognition
• pyaudio - Audio capture
• PyGObject - GTK integration
• psutil - Process utilities (required by pywhispercpp)

Build & Test Commands

Python

# Install in development mode
./install.sh --dev
# Or manually:
pip install -e ".[dev]"

# Run all tests
pytest

# Run a single test file
pytest tests/test_command_processor.py

# Run a single test function
pytest tests/test_command_processor.py::TestCommandProcessor::test_initialization

# Run tests with verbose output
pytest -v

# Run tests with coverage
pytest --cov=src --cov-report=html

# Run tests excluding slow/integration tests
pytest -m "not slow"
pytest -m "not integration"

# Lint (check only)
make lint
# Or manually:
flake8 src/ tests/ --select=E9,F63,F7,F82
black --check --diff src/ tests/
isort --check-only --diff --profile black src/ tests/

# Auto-format code
make format
# Or manually:
black src/ tests/
isort --profile black src/ tests/

# Type checking
make typecheck
# Or: mypy src/

# Run the application
vocalinux --debug
# Or from source: python -m vocalinux.main --debug

Website (Next.js)

cd web
npm install
npm run dev      # Development server
npm run build    # Production build
npm run lint     # ESLint
npm run test     # Jest tests

Code Style Guidelines

Formatting

• Line length: 100 characters
• Formatter: Black
• Import sorter: isort (black-compatible profile)
• Linter: flake8

Import Order

Use isort with black profile. Imports should be grouped:

1. Standard library (import os, from typing import ...)
2. Third-party packages (import gi, from vosk import Model)
3. Local imports (from vocalinux.common_types import ...)

Type Hints

Use type hints for all function signatures. Use Protocol for interfaces (see common_types.py).

Naming Conventions

• Classes: PascalCase (e.g., CommandProcessor, ConfigManager)
• Functions/methods: snake_case (e.g., process_text, load_config)
• Constants: UPPER_SNAKE_CASE (e.g., CONFIG_DIR, DEFAULT_CONFIG)
• Private methods: _leading_underscore (e.g., _compile_patterns)
• Module-level logger: logger = logging.getLogger(__name__)

Docstrings

Use triple-quoted docstrings for modules, classes, and public functions:

"""Configuration manager for Vocalinux."""

class ConfigManager:
    """Manager for user configuration settings."""

    def load_config(self):
        """Load configuration from the config file."""

Error Handling

Use specific exception types, log errors with context:

try:
    with open(CONFIG_FILE, "r") as f:
        user_config = json.load(f)
except json.JSONDecodeError as e:
    logger.error(f"Invalid JSON in config file: {e}")

Logging

Each module should have its own logger:

import logging
logger = logging.getLogger(__name__)

Testing Guidelines

• Place tests in tests/ directory
• Name test files as test_*.py, functions as test_*
• Use unittest.TestCase or plain pytest functions
• Use pytest-mock for mocking (via mocker fixture)

Test Markers

@pytest.mark.slow          # Long-running tests
@pytest.mark.integration   # Integration tests
@pytest.mark.audio         # Requires audio hardware

Project Structure

src/vocalinux/
├── main.py                    # Application entry point
├── version.py                 # Version info
├── common_types.py            # Shared types/enums/protocols
├── speech_recognition/
│   ├── recognition_manager.py # VOSK/Whisper/whisper.cpp management
│   └── command_processor.py   # Voice command processing
├── text_injection/
│   └── text_injector.py       # X11/Wayland text injection
├── ui/
│   ├── tray_indicator.py      # System tray icon
│   ├── settings_dialog.py     # Settings GUI
│   ├── config_manager.py      # Configuration handling
│   └── keyboard_backends/     # Keyboard input handling
└── utils/
    ├── resource_manager.py    # Resource utilities
    ├── whispercpp_model_info.py   # whisper.cpp model metadata & hardware detection
    └── vosk_model_info.py         # VOSK model metadata

Release Process

See docs/RELEASE_PROCESS.md for detailed release instructions.

Quick summary:

1. Update version in src/vocalinux/version.py
2. Update version references in README.md, docs/INSTALL.md, docs/UPDATE.md
3. Update web/src/app/page.tsx and web/package.json
4. Run make lint to verify code quality
5. Create branch release/vX.Y.Z-PHASE
6. Commit with chore(release): prepare vX.Y.Z-PHASE
7. Push and create PR
8. After merge, create and push tag: git tag -a vX.Y.Z-PHASE -m "Release X.Y.Z-PHASE"
9. GitHub Actions will build and publish automatically

Commit Message Format

Follow Conventional Commits:

type(scope): short description

Longer description if needed.

Fixes #123

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat(commands): add "select all" voice command
fix(tray): resolve icon not updating on Wayland
docs(readme): update installation instructions

Branch Naming

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test additions/updates
• release/ - Release preparation (e.g., release/v0.7.0-beta)

Important Rules

• Never push directly to main - Always create a branch and PR
• All changes require a PR - Even small fixes and documentation updates
• Wait for CI to pass before merging PRs
• Squash merge PRs to keep history clean