Personal AI Agent

A highly extensible, plugin-based personal AI assistant that runs on your local machine. Built with Python, CustomTkinter, and LiteLLM.

---

Features

• Plugin-Based Architecture: Dynamically load features from the /plugins folder.
• Multi-Model Support: Seamlessly switch between any LLM provider (Gemini, Ollama, OpenRouter, etc.) thanks to LiteLLM.
• Context-Aware: Remembers your conversation and selects the best "role" (e.g., Coding Assistant) for your query.
• Interactive UI:
  • Modern UI built with CustomTkinter.
  • Runs in your system tray.
  • Global hotkeys (Ctrl+Shift+Space) to open the chat window.
  • Dark / Light / System theme support.
  • Remembers window position and size.
• Extensible Tools:
  • Screen Capture: Press Ctrl+Shift+X to attach a screenshot to your message.
  • MCP Integration: (Model Context Protocol) A framework for adding custom tools (e.g., file system access, web search).

---

Project Structure

personal-ai-agent/
├── core/     # Core services (DI, events, agent, api)
├── plugins/  # All plugins (screen_capture, mcp, etc.)
├── config/   # All user-facing JSON configs
│   └── prompts/ # System prompts for agent roles
├── ui/       # CustomTkinter windows and widgets
├── input/    # Global hotkey manager
├── utils/    # Helpers (logger, config loader)
└── main.py   # Main application entry point

---

Setup & Installation

1. Prerequisites

• Python 3.10+
• An API key for at least one LLM provider (e.g., Google Gemini).

2. Clone the Repository

git clone https://github.com/your-username/personal-ai-agent.git
cd personal-ai-agent

3. Install Dependencies

It's highly recommended to use a virtual environment.

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install the required packages.

Recommended (using requirements.txt):

pip install -r requirements.txt

Manual Installation (if requirements.txt is missing):

pip install customtkinter pystray pynput tkhtmlview pillow litellm mss markdown tenacity

4. Configure API Keys

The application uses environment variables for API keys. This is the most secure method.

On macOS/Linux:

export GEMINI_API_KEY="your_google_ai_studio_key"
export OPENROUTER_API_KEY="your_openrouter_key"

On Windows (Command Prompt):

set GEMINI_API_KEY="your_google_ai_studio_key"

5. Run the Application

python main.py

The app will start and show an icon in your system tray. All configurations (like models and hotkeys) will be in the config/ folder.

---

How to Use

• Open Chat: Press Ctrl+Shift+Space or click the tray icon.
• Open Settings: Right-click the tray icon and select "Settings".
• Take Screenshot: Press Ctrl+Shift+X. The chat window will open with a "Screenshot Attached" notice.
• Send Message: Type your message and press Ctrl+Enter.
• Add Newline: Press Shift+Enter to add a new line in the chat box.

---

How to Develop a New Plugin

1. Create a new file in plugins/, e.g., my_plugin.py.
2. Import the base class: from plugins import PluginBase.
3. Create your class: class MyAwesomePlugin(PluginBase):
4. Implement the required methods: __init__, Youtube, and initialize.

Example: plugins/hello_plugin.py

import logging
from plugins import PluginBase
from core.service_locator import ServiceLocator
from core.event_dispatcher import EventDispatcher

class HelloPlugin(PluginBase):
    
    def __init__(self, service_locator: ServiceLocator):
        super().__init__(service_locator)
        # Get core services
        self.events: EventDispatcher = self.locator.resolve("event_dispatcher")
        self.logger = logging.getLogger(self.__class__.__name__)

    def get_metadata(self):
        return {
            "name": "HelloPlugin",
            "version": "1.0.0",
            "description": "A simple plugin that says hello."
        }

    def initialize(self):
        # Subscribe to an event
        self.events.subscribe("APP_START", self.say_hello)
        self.logger.info("HelloPlugin initialized.")
        
    async def say_hello(self):
        self.logger.info("Hello from the HelloPlugin!")
        await self.events.publish(
            "NOTIFICATION_EVENT.INFO",
            title="Hello Plugin",
            message="Hello, world! The app has started."
        )