Personal Assistant

Automate your morning. Optimize your day. Accelerate your growth.

Overview

Mornings set the trajectory for your entire day. But for many of us—engineers, students, and entrepreneurs—the first hour is wasted on low-value tasks. We toggle between weather apps, calendars, fitness trackers, and news sites, trying to piece together a plan. By the time we start working, we're already suffering from decision fatigue.

This Personal Assistant was built to solve that fragmentation.

It is a silent, automated system that runs while you sleep. At 7:00 AM, it delivers a single, comprehensive briefing email that answers the critical questions:

• "What do I need to achieve today?"
• "How should I train based on my recovery?"
• "When can I find time to study?"
• "What is happening in my industry?"

Stop reacting to your day. Start owning it.

The Problems We Solve

1. Information Overload

Instead of checking five different apps, get one synthesized report. The system aggregates weather, news, and schedule data so you don't have to.

2. Goal Drift

It's easy to skip a workout or study session when it's not on your calendar. This assistant proactively schedules your goals into your free time, making consistency the default option.

3. Decision Fatigue

The "Calendar Agent" analyzes your day and uses LLMs to identify your Top 3 Priorities. You wake up knowing exactly what matters, without burning mental energy on prioritization.

4. Professional Isolation

Finding relevant networking events is tedious. The "Event Scout" scrapes local meetups and ranks them based on your specific career interests (e.g., "Rust", "Startups"), ensuring you never miss an opportunity to connect.

How It Works

The system operates on a hub-and-spoke model. A central "Orchestrator" manages specialized agents, each an expert in one domain.

Core Agents

Agent	Responsibility
Orchestrator	Manages dependencies, retries failed tasks, and compiles the final report.
Calendar	Analyzes your schedule to find free blocks for deep work and spot travel conflicts.
Fitness	Connects to Strava to calculate a recovery score (1-10) and suggests workouts adapted to the local weather.
Event Scout	Scrapes local events and scores them based on relevance to your career goals.
Ghostwriter	Synthesizes your day's achievements into a professional social media draft to help build your personal brand.
Linguist	Teaches you vocabulary words that are contextually relevant to your day's specific schedule.
Weather	Provides hyper-local forecasts to inform your run, commute, or outfit choice.

Architecture

The system is designed for reliability and extensibility. It runs locally or on a server, using a modular design that allows you to easily enable or disable agents.

flowchart TB
    subgraph Trigger
        Cron[Cron / Task Scheduler] -->|7 AM| Orchestrator
    end

    subgraph Core System
        Orchestrator[Orchestrator Agent]
        DailyState[(Daily State JSON)]
        Email[HTML Email Output]
    end

    subgraph Independent Agents
        Weather[Weather Agent]
        Calendar[Calendar Agent]
        Spiritual[Spiritual Agent]
        Events[Event Scout Agent]
    end

    subgraph Dependent Agents
        Fitness[Fitness Agent]
        WGU[WGU Agent]
        Linguist[Linguist Agent]
        Ghostwriter[Ghostwriter Agent]
    end

    subgraph Services
        NewsService[News Service]
        OAuth[OAuth Manager]
    end

    %% Flow
    Orchestrator --> Weather
    Orchestrator --> Calendar
    Orchestrator --> Spiritual
    Orchestrator --> Events
    
    %% Data Dependencies
    Weather -->|Weather Data| Fitness
    Calendar -->|Free Blocks| WGU
    Calendar -->|Schedule & Context| Linguist
    Calendar -->|Priorities & Schedule| Ghostwriter
    Fitness -->|Workout Context| Linguist
    Fitness -->|Recovery & Plan| Ghostwriter
    WGU -->|Study Progress| Ghostwriter
    
    %% News Flow
    Orchestrator --> NewsService
    NewsService -->|Filter: Tech Stories| Ghostwriter
    NewsService -->|Filter: Top 3 Stories| Email

    %% Persistence
    Fitness -.->|Save Goals| DailyState
    WGU -.->|Save Goals| DailyState
    Orchestrator -.->|Load/Save| DailyState

    %% Output
    Orchestrator -->|Compiles| Email
    
    style Orchestrator fill:#ff6b6b,color:#fff
    style DailyState fill:#4ecdc4,color:#000
    style Email fill:#95e1d3,color:#000
    style OAuth fill:#f9d5e5,color:#000

Loading

Quick Start

Prerequisites

• Python 3.11+
• Git
• API Keys: OpenWeatherMap, DeepSeek (LLM), Google Calendar, Strava

Installation

1. Clone & Install

   git clone https://github.com/yourusername/personal-assistant.git
   cd personal-assistant
   pip install -e .

2. Configure Environment See docs/ENV_SETUP.md for detailed instructions on obtaining API keys.

   # Create .env file and fill in your keys
   # (Refer to docs/ENV_SETUP.md)

3. Setup OAuth (One-time)

   python scripts/setup_oauth_google.py
   python scripts/setup_oauth_strava.py

4. Run It

   python src/main.py

Configuration

You can tailor the assistant to your specific needs without modifying the code by editing data/config.json.

{
  "location": "San Francisco, CA",
  "timezone": "America/Los_Angeles",
  "event_keywords": ["AI", "Python", "Networking"],
  "agents": {
    "fitness": { "enabled": true },
    "wgu": { "enabled": false }
  }
}

Privacy & Security

We built this tool because we believe your data belongs to you.

• Local First: All processing happens on your machine.
• Encrypted Tokens: OAuth credentials are encrypted at rest.
• No Leaks: Strict git policies ensure your personal data never accidentally leaves your computer.

Development & Testing

Run the test suite using pytest:

# Run all tests
pytest

# Run only unit tests
pytest tests/unit

Contributing

We welcome contributions from anyone who wants to improve their productivity workflow. Please feel free to submit a Pull Request.

---

Built for those who value their time.