Add Nix flake for declarative and reproducible installation

[basnijholt]

Summary

This PR introduces a Nix flake to provide a declarative and reproducible way to install and run agent-cli with all its dependencies and services.

Motivation

• Simplifies setup process for Nix/NixOS users
• Provides reproducible builds and environments
• Handles all service dependencies automatically
• Offers both development shells and system-wide installation options

Changes

New Files

• flake.nix - Main flake configuration with:

  • Development shell with all Python dependencies
  • NixOS module for system integration
  • Platform-aware service management script
  • Package definitions for agent-cli

• flake.lock - Lock file for reproducible builds

• docs/installation/flake.md - Comprehensive documentation for:

  • Quick start guide
  • Multiple installation methods
  • GPU acceleration setup
  • Platform-specific instructions
  • Troubleshooting guide

Features

Platform Support

• NixOS: Native systemd service integration for Ollama and Wyoming services
• macOS: Automatic fallback to Docker containers for AI services
• Linux: Support for both Docker and manual service management

Key Commands

# Enter development environment
nix develop

# Start all services
nix run .#start-services

# Or use from GitHub directly
nix run github:basnijholt/agent-cli#start-services

NixOS Module

Users can add agent-cli to their system configuration:

{
  services.agent-cli = {
    enable = true;
    enableOllama = true;
    enableWhisper = true;
    enablePiper = true;
    enableOpenWakeWord = true;
    enableServer = true;  # Optional API server
  };
}

Testing

The flake has been tested for:

• ✅ Syntax validation (nix flake check)
• ✅ Output evaluation (nix flake show)
• ✅ Package building
• ✅ Development shell creation

Notes

• Wyoming services (wyoming.faster-whisper, wyoming.piper, wyoming.openwakeword) are NixOS-specific
• macOS users need Docker Desktop installed for AI services
• The flake automatically handles Python packages not available in nixpkgs by installing them via pip

Future Improvements

• Add support for more Whisper models
• Configure GPU acceleration options
• Add Home Manager module
• Support for additional TTS voices