Merlin - Your AI Assistant

Merlin is a powerful, multi-agent AI assistant designed to help you with various tasks on your computer. While we're starting small, our long-term vision is to become a comprehensive AI system capable of home automation and software management.

Features

• Multi-Agent Architecture: Merlin uses specialized agents for different tasks
• Weather Expert: Get detailed meteorological analysis and forecasts
• Games Expert: Roll dice, flip coins, and enjoy random fun activities
• Lighting Expert: Set up and connect to your phillips hue bridge to control your lights
• Memory Expert: Manages Merlins long term memory in a memory.yaml file, so you the user can easily see whats going on.

Current Capabilities

Weather Expert

• Provides detailed weather analysis for locations in the UK
• Shows temperature, humidity, pressure, and wind conditions
• Gives atmospheric insights and forecasts

Games Expert

• Roll dice with custom sides (default 6-sided)
• Flip coins with random outcomes
• Engaging and fun responses to gaming requests

Lighting Expert

• Sets up your phillips hue bridge
• Sync all your lights and rooms ready to command
• Control brightness and power on / of rooms and lights

Memory Expert

• Manage long term memory for Merlin
• Add / edit / remove items from a yaml file that gets loaded on start up and also on command
• can always access memory and show whats there.
• stored in memory.yaml so you the use has easy access to the long term memory

File Expert

• Find, read and save files
• User control over where the LLM can look

Future Vision

Merlin's long-term goal is to become a comprehensive AI assistant that can:

• Home Automation: Control smart home devices, manage schedules, and automate daily tasks
• Software Management: Start applications, manage music playback, and handle software operations
• General Computer Assistance: Provide help with various computer tasks and workflows

Getting Started

Quick Setup

1. Install the project in development mode:

   uv sync

2. Copy the user config template:

   cp src/config/user_config_template.py src/config/user_config.py

3. Edit your personal settings in src/config/user_config.py:

   class UserConfig:
       class Model:
           # Your personal API keys and preferences
           ORCHESTRATOR = {
               'model_name': 'gpt-4',
               'api_base': 'https://api.openai.com/v1',
               'api_key': 'your-api-key-here'
           }

4. Run the application:

   uv run merlin

Alternative: Direct Python Execution

If you prefer not to use the entry point, you can run directly:

uv run src/main.py

Development Workflow

Merlin includes automated development workflows using Just - a command runner that simplifies common tasks.

Installing Just

Option 1: Quick Install (Recommended)

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

Option 2: Package Manager

# On macOS with Homebrew
brew install just

# On Ubuntu/Debian
wget -qO - 'https://proget.makedeb.org/debian-feeds/prebuilt-mpr.pub' | gpg --dearmor | sudo tee /usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg 1> /dev/null
echo "deb [arch=all,amd64,arm64,armhf signed-by=/usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg] https://proget.makedeb.org prebuilt-mpr $(lsb_release -cs)" | sudo tee /etc/apt/sources.list.d/prebuilt-mpr.list
sudo apt update
sudo apt install just

# On Windows with Chocolatey  
choco install just

# On Windows with Scoop
scoop install just

Available Commands

Run just --list to see all available commands:

• just pr_prep_patch - Prepare PR with patch version bump (bug fixes, small changes)
• just pr_prep_minor - Prepare PR with minor version bump (new features, backward compatible)
• just pr_prep_major - Prepare PR with major version bump (breaking changes)

What Each Command Does

Each PR preparation command performs a complete automated workflow:

1. Git Sync: Fetch, checkout main, pull latest, merge to current branch
2. Code Quality: Format code with ruff format and fix issues with ruff check --fix
3. Dependencies: Update lock file with uv lock -U
4. Versioning: Bump version (patch/minor/major) and build project
5. Commit: Stage all changes and commit with automated message

Usage Examples

Terminal Usage:

# For bug fixes and documentation updates
just pr_prep_patch

# For new features that don't break existing functionality
just pr_prep_minor

# For breaking changes or major rewrites
just pr_prep_major

VS Code Integration:

The project includes VS Code tasks for easy access to Just commands:

1. Command Palette (Ctrl+Shift+P or Cmd+Shift+P):

   • Type "Tasks: Run Task"
   • Select from available tasks:
     • PR Prep: Patch (🟢 Green icon)
     • PR Prep: Minor (🔵 Blue icon)
     • PR Prep: Major (🔴 Red icon)
     • Code Quality: Format & Lint
     • Dependencies: Update Lock

2. Quick Access (Ctrl+Shift+P):

   • Type "Tasks: Run Build Task" for default formatting task

3. Terminal Menu: Go to Terminal → Run Task...

Task Features:

• 🎯 Auto-focus: Tasks automatically switch to terminal when running
• 🎨 Color-coded: Green for patch, blue for minor, red for major changes
• 📝 Descriptive: Each task shows what it does in the picker
• 🔗 Integrated: Seamless workflow between VS Code and terminal

Configuration

Merlin uses a two-tier configuration system to separate application settings from personal user settings.

Configuration Layers

Application Config (src/config/app_config.py)

• Application-level defaults
• Weather code mappings
• Agent structure definitions
• No personal API keys - safe to commit

User Config (src/config/user_config.py)

• Personal API keys
• Custom model preferences
• Personal endpoint configurations
• Never committed - stays local (gitignored)

Configuration Examples

Local Ollama Setup (Default)

# No user_config.py needed - works out of the box!

Custom Local Ollama

# src/config/user_config.py
class UserConfig:
    class Model:
        HOST_ADDRESS = '127.0.0.1'
        HOST_PORT = '11434'
        HOST_API_KEY = 'local'

Mixed Providers

# src/config/user_config.py  
class UserConfig:
    class Model:
        ORCHESTRATOR = {
            'model_name': 'gpt-4',
            'api_base': 'https://api.openai.com/v1',
            'api_key': 'your-openai-key'
        }
        EXPERTS = {
            'weather': {
                'model_name': 'claude-3-sonnet',
                'api_base': 'https://api.anthropic.com',
                'api_key': 'your-anthropic-key'
            }
        }

Configuration Hierarchy Settings are merged in this order (later overrides earlier):

1. Application defaults (app_config.py)
2. User base settings (user_config.py)
3. User agent-specific settings (user_config.py)

Commands

• Type 'history' to see conversation history
• Type 'quit', 'exit', or 'bye' to leave
• Ask about weather, games, or other supported topics

Architecture

Merlin uses DSPy an AI Framework with:

• An orchestrator (TheOracle) that routes questions to appropriate experts
• Specialized agents for specific domains (weather, games, lights & memory)
• Rich UI with rich library for beautiful terminal output