🤖 Personal Minions

Your personal AI automation army for managing daily tasks, calendar, email, and more!

Build your own digital assistant army that works for you, not against you.

🌟 Vision & Motivation

The Problem We're Solving

In an age where every app wants your data, every service requires cloud connectivity, and every automation tool comes with privacy trade-offs, Personal Minions offers a different path: local-first personal automation that respects your privacy.

Our Vision

Create a world where everyone can have their own personal AI assistants without:

❌ Sending personal data to cloud services
❌ Paying monthly subscription fees
❌ Being locked into proprietary ecosystems
❌ Compromising on privacy or security

Why This Matters

Privacy First: Your data stays on your machine, encrypted and secure
No Vendor Lock-in: Open source means you control your automation forever
Cost Effective: Pay only for the APIs you choose to use
Infinitely Extensible: Build exactly the automation you need
Community Driven: Share minions, learn from others, improve together

🎯 What Makes Personal Minions Different

Traditional Automation	Personal Minions
Cloud-dependent	Local-first
Subscription fees	Free & open source
Limited customization	Infinitely extensible
Data mining	Privacy by design
Vendor lock-in	You own your automation
Manual execution	Intelligent scheduling

🚀 Quick Start

1. Setup

# Clone the repository
git clone https://github.com/yourusername/personal-minions.git
cd personal-minions

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Setup credentials (optional - will use mock data without API keys)
python main.py setup

2. Run Your First Minion

# Run weather minion once
python main.py run --agent weather

# Start the scheduler to run agents automatically
python main.py start

3. Check Status

# List available minions
python main.py list

# Check minion status
python main.py status

🤖 Available Minions

Weather Minion

Purpose: Weather monitoring and forecasting
Features: Current conditions, forecasts, weather alerts
API: OpenWeatherMap (free tier available)
Schedule: Every 30 minutes
Status: Fully implemented and tested

Coming Soon

Calendar Minion: Google Calendar integration, meeting prep, scheduling
Email Minion: Gmail processing, smart filtering, auto-responses
Todo Minion: Task management, deadline tracking, prioritization
Finance Minion: Expense tracking, budget alerts, investment monitoring
News Minion: Personalized news aggregation and summarization
Health Minion: Fitness tracking, medication reminders, health insights

🏗️ Architecture & Design Decisions

Core Principles

Local-First: Everything runs on your machine
Privacy by Design: No data leaves your control
Modular Architecture: Each minion is independent
Secure by Default: Encrypted storage, safe credential management
Easy to Extend: Simple patterns for adding new capabilities

Technical Architecture

minions/
├── core/                    # 🏗️ Shared framework
│   ├── agent.py            # Base agent class with common functionality
│   ├── scheduler.py        # APScheduler-based task scheduling
│   ├── config.py           # JSON-based configuration management
│   ├── auth.py             # Fernet-encrypted credential storage
│   └── utils.py            # Common utilities and helpers
├── agents/                 # 🤖 Individual minions
│   └── weather_minion.py   # Weather agent implementation
├── config/                 # ⚙️ Configuration files (auto-created)
├── data/                   # 💾 Local data storage (auto-created)
├── main.py                 # 🚪 Main CLI entry point
└── WHAT_WE_BUILT.md        # 📖 Simple explanation of the framework

Key Design Decisions

Why Python?

Excellent AI/ML ecosystem
Rich API integration libraries
Easy to read and contribute to
Cross-platform compatibility

Why Local Storage?

Complete privacy control
No internet dependency for core functions
Fast access to your data
No cloud storage costs

Why Modular Design?

Easy to add new minions
Isolated failure domains
Community can contribute specific agents
Users can enable only what they need

Why Encrypted Credentials?

Security without complexity
Safe to store API keys locally
Portable across machines
Industry-standard encryption (Fernet)

🔐 Security & Privacy

Security Features

Encrypted Storage: API keys encrypted using Fernet symmetric encryption
Local First: All data stored locally on your machine
Secure Permissions: Credential files have restricted access (600)
No Network by Default: Works offline, connects only when needed
Environment Variable Support: Multiple ways to provide credentials safely

Privacy Guarantees

No Telemetry: We don't track usage or collect analytics
No Cloud Dependencies: Core functionality works completely offline
Your Data, Your Control: Everything stays on your machine
Open Source: You can audit every line of code

⚙️ Configuration

Agent Configuration

Each agent can be configured through the config/minions.json file:

{
  "agents": {
    "weather_minion": {
      "enabled": true,
      "location": "San Francisco,CA",
      "units": "metric",
      "schedule": "every 30 minutes"
    }
  }
}

Environment Variables

Set API keys via environment variables:

export OPENWEATHER_API_KEY="your_api_key_here"

🔧 Creating Custom Minions

Simple Example

from core.agent import BaseAgent, AgentConfig
from typing import Dict, Any

class MyMinion(BaseAgent):
    """A simple example minion that demonstrates the framework."""
    
    async def execute(self) -> Dict[str, Any]:
        """Main execution logic for your minion."""
        # Your automation logic here
        result = await self.do_something_useful()
        
        return {
            "status": "completed",
            "data": result,
            "timestamp": self.get_timestamp()
        }
    
    def get_description(self) -> str:
        """Human-readable description of what this minion does."""
        return "Automates something useful for you"
    
    async def do_something_useful(self):
        """Your custom logic goes here."""
        return {"message": "Hello from my minion!"}

Registration

# In main.py or your custom runner
from core.scheduler import scheduler

my_minion = MyMinion(config)
scheduler.register_agent(my_minion)
scheduler.schedule_agent("my_minion", "every hour")

📋 Commands

# Setup and configuration
python main.py setup          # Interactive credential setup
python main.py list           # List available agents

# Running agents
python main.py run --agent weather    # Run specific agent once
python main.py start          # Start scheduler for automatic runs

# Monitoring
python main.py status         # Show agent status and statistics

🛠️ Development

Adding New Minions

Create Agent File: Add new file in agents/ directory
Inherit from BaseAgent: Use the provided base class
Implement Required Methods: execute() and get_description()
Add Credentials: Register any API keys with the auth system
Register Agent: Add to the main scheduler
Test: Run your agent with python main.py run --agent your_agent

Testing

# Run a specific agent for testing
python main.py run --agent your_agent

# Check logs in the console output
# All execution details are logged for debugging

Contributing Guidelines

See CONTRIBUTING.md for detailed guidelines on:

Code style and standards
How to submit pull requests
Community guidelines
Development setup

📊 Features

⏰ Intelligent Scheduling: Advanced APScheduler-based automation that runs your minions exactly when needed
💾 Smart Caching: Avoid unnecessary API calls with intelligent caching
🔐 Secure Credentials: Fernet-encrypted storage of API keys and sensitive data
📈 Status Monitoring: Track agent performance and execution history
🛡️ Error Handling: Robust error handling with retries and fallbacks
🔧 Extensible: Easy-to-follow patterns for adding new capabilities
🌐 Cross-Platform: Works on Windows, macOS, and Linux
📱 CLI Interface: Simple command-line interface for all operations
🖥️ Web Dashboard: Modern web interface for managing minions and schedules (coming soon)

🤝 Contributing

We believe personal automation should be accessible to everyone. Whether you're a seasoned developer or just getting started, there are many ways to contribute:

Ways to Help

🐛 Report Bugs: Found something broken? Let us know!
💡 Suggest Features: Have an idea for a new minion? Share it!
📝 Improve Documentation: Help make the project more accessible
🤖 Create Minions: Build and share new automation agents
🔧 Core Improvements: Enhance the framework itself
🎨 UI/UX: Help improve the user experience

Getting Started

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

See our Code of Conduct for community guidelines.

🌟 Community & Support

Philosophy

Personal Minions is built on the belief that:

Technology should serve you, not the other way around
Privacy is a fundamental right, not a premium feature
Open source creates better, more trustworthy software
Community collaboration leads to innovation

Join the Community

💬 Discussions: Share ideas and get help
🐛 Issues: Report bugs and request features
📚 Wiki: Community-maintained documentation
🎯 Projects: Contribute to planned features

📄 License

MIT License - Feel free to use, modify, and distribute for any purpose, including commercial use.

This license ensures that Personal Minions will always remain free and open source, while allowing maximum flexibility for users and contributors.

🙏 Acknowledgments

Personal Minions stands on the shoulders of giants:

APScheduler: For reliable task scheduling
Cryptography: For secure credential storage
Requests: For simple HTTP API integration
Python Community: For creating an amazing ecosystem

🚀 What's Next?

Immediate Roadmap

📧 Email Minion (Gmail integration)
📅 Calendar Minion (Google Calendar)
✅ Todo Minion (task management)
💰 Finance Minion (expense tracking)

Long-term Vision

🧠 AI-powered minion coordination
📱 Mobile companion app
🔌 Plugin marketplace
🤝 Minion collaboration protocols

Built with ❤️ for personal productivity, privacy, and automation freedom.

Ready to build your digital assistant army? Let's get started! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
agents		agents
core		core
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
WHAT_WE_BUILT.md		WHAT_WE_BUILT.md
forge.yaml		forge.yaml
main.py		main.py
requirements.txt		requirements.txt
test_weather.py		test_weather.py

nishantmodak/personal-minions

Folders and files

Latest commit

History

Repository files navigation