PA - Personal Assistant

What is PA

PA is a local-first, command-driven personal assistant for daily execution. It combines chat, calendar, tasks, email intelligence, research memory, journaling, habits/goals tracking, Slack notifications, voice input, automations, and plugins in one Python CLI app.

Full feature list (all 7 phases)

Phase 1 - Core Assistant

• REPL chat with persistent conversation history in PostgreSQL
• Command system with aliases and macros
• Session export to Markdown
• Local memory/preferences support

Phase 2 - Calendar and Scheduling

• Google Calendar OAuth2 integration
• Calendar views by date and range
• Reminder scheduling with natural language time parsing
• Smart free-slot suggestions and conflict detection
• Morning brief and end-of-day summary foundation

Phase 3 - Task and Notes Workflow

• Task management with Notion backend or local fallback
• Project-based task views
• Overdue and priority views
• Meeting notes extraction into actions

Phase 4 - Email Intelligence

• Gmail OAuth2 integration
• Inbox triage and urgency scoring
• Draft reply generation
• Follow-up detection
• VIP sender management

Phase 5 - Knowledge and Research

• Local vector knowledge base
• Save/search notes and ask contextual questions
• Web research and clipping
• Knowledge stats and export

Phase 6 - Tracking and Coaching

• Daily journal entries and reflection
• Mood tracking and trends
• Habit tracking with streaks and history
• Goal tracking with milestones/progress updates
• Weekly review flow

Phase 7 - Operations Layer

• Slack integration and quick notifications
• Workflow automation engine (trigger/action)
• Voice input (local transcription)
• Plugin architecture with auto-discovery
• Scheduled automation checks and weekly reporting

Requirements

• Python 3.10+
• PostgreSQL 14+
• 8GB RAM recommended for voice models
• Google Cloud OAuth credentials (Calendar/Gmail)
• Optional: Notion API token
• Optional: Slack bot token

Installation (step by step)

1. Clone repository.
2. Create and activate virtual environment.
3. Install Python dependencies.
4. Create PostgreSQL database and user.
5. Configure pa/config.yaml.
6. Run the assistant.

cd pa
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

Create database:

CREATE DATABASE pa_assistant;
CREATE USER pa_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE pa_assistant TO pa_user;

Start app:

cd pa
python -m assistant

Configuration (every config key explained)

File: pa/config.yaml

Root keys

• groq_api_key: API key for LLM calls. Keep null and provide via env for safety.
• model: LLM model name.
• user_name: Name shown in prompt.
• user_email: Email destination for weekly report and automations.
• timezone: IANA timezone (America/New_York).

database

• host: Postgres host.
• port: Postgres port.
• name: Database name.
• user: Database user.
• password: Database password.

calendar

• working_hours.start: Start of working day.
• working_hours.end: End of working day.
• duration: Default event duration in minutes.
• buffer: Travel/context buffer in minutes.

email

• vip_check_interval: VIP scan interval in minutes.
• digest_max: Max emails in digest.
• urgency_threshold: Urgency cutoff for escalations.

notion

• api_key: Notion integration token.
• tasks_db_id: Notion tasks database ID.
• projects_db_id: Notion projects database ID.

tasks

• default_priority: Default new-task priority (high|medium|low).
• nudge_time: Daily task nudge time.
• backup_to_markdown: Mirror tasks to Markdown backup.

knowledge

• embedding_model: Sentence-transformer model for vectors.
• storage_path: Local KB path.
• threshold: Similarity threshold for retrieval.

search

• engine: Search provider (duckduckgo or custom logic).
• brave_api_key: Optional Brave Search key.
• max_results: Result cap per search.

slack

• bot_token: Slack bot OAuth token.
• default_channel: Default Slack channel.
• notification_channel: Channel for alerts/reminders.

journal

• daily_prompt: Enable daily prompt seeding.
• reflection: Enable AI reflection support.
• streak_reminder: Reminder when journaling streak breaks.

habits

• reminder_time: Daily habit reminder time.
• show_on_startup: Print habit snapshot at startup.

goals

• check_in_frequency: Goal check cadence.
• ai_planning: Enable AI-assisted planning hints.

voice

• enabled: Enable voice system.
• model: Whisper model (base, small, etc.).
• language: Language code.
• record_seconds: Recording duration for voice captures.

workflows

• check_interval_minutes: Workflow trigger polling interval.

Google Setup (Calendar + Gmail OAuth2)

1. Open Google Cloud Console.
2. Create/select project.
3. Enable APIs:

• Google Calendar API
• Gmail API

4. Configure OAuth consent screen.
5. Create OAuth Client ID (Desktop app).
6. Save credentials JSON to:

• pa/assistant/integrations/credentials.json

7. Run assistant and trigger:

• /calendar for Calendar auth
• /email for Gmail auth

8. OAuth tokens are stored locally and refreshed automatically.

Notion Setup

1. Create integration at Notion Developers.
2. Copy integration token to notion.api_key.
3. Create two databases: Tasks and Projects.
4. Share both databases with integration.
5. Add IDs to:

• notion.tasks_db_id
• notion.projects_db_id

Slack Setup

1. Create app in Slack API dashboard.
2. Add bot scopes:

• chat:write
• channels:read
• channels:history
• search:read

3. Install app to workspace.
4. Copy bot token into slack.bot_token.
5. Invite bot to channels:

• /invite @your-bot

Voice Setup

1. Ensure machine has enough RAM (8GB recommended).
2. Install audio dependencies from requirements.txt.
3. Enable in config:

• voice.enabled: true

4. Start assistant and run:

• /voice test

5. Toggle runtime voice mode:

• /voice

All commands (complete reference — every command with example)

Core

• /help - Show command list
  • Example: /help
• /clear - Clear history state
  • Example: /clear
• /history - Show latest conversation entries
  • Example: /history
• /memory - Show stored memory/preferences
  • Example: /memory
• /export - Export chat history to Markdown
  • Example: /export
• /alias - Create alias
  • Example: /alias /gm = /brief
• /macro - Execute named macro
  • Example: /macro morning_routine

Calendar and reminders

• /calendar - Calendar view/status
  • Example: /calendar today
• /remind - Create reminder
  • Example: /remind "Call Alex" "tomorrow 3pm"
• /reminders - List reminders
  • Example: /reminders
• /schedule - Schedule event
  • Example: /schedule "1:1 with Sam" tomorrow 2pm
• /freeslots - Suggest available slots
  • Example: /freeslots next 3
• /conflicts - Show overlaps
  • Example: /conflicts 2026-04-02
• /brief - Daily briefing
  • Example: /brief
• /eod - End-of-day summary
  • Example: /eod

Tasks and projects

• /tasks - Task list summary
  • Example: /tasks all
• /task add - Add task
  • Example: /task add "Ship report" due:tomorrow priority:high project:Ops
• /task done - Complete task
  • Example: /task done 12
• /task find - Search tasks
  • Example: /task find payroll
• /projects - Project overview
  • Example: /projects
• /overdue - Overdue tasks grouped by age
  • Example: /overdue
• /meeting - Meeting action extraction
  • Example: /meeting

Email

• /email - Inbox triage and operations
  • Example: /email unread
• /reply - Draft/send reply flow
  • Example: /reply 18c2a1f0
• /followups - Detect follow-up candidates
  • Example: /followups
• /unsubscribe - Suggest unsubscribe candidates
  • Example: /unsubscribe
• /send - Compose/send new message
  • Example: /send jane@company.com "Status Update"
• /vip - VIP sender management
  • Example: /vip add ceo@company.com "CEO"

Knowledge and research

• /save - Save note to KB
  • Example: /save "Client prefers async updates" #client #ops
• /ask - Ask with KB context
  • Example: /ask What did I decide about launch scope?
• /search - Web/local search
  • Example: /search SOC2 control mapping
• /notes - Note browsing/search
  • Example: /notes search launch
• /research - Multi-result research summary
  • Example: /research AI meeting assistants privacy model
• /clip - Clip URL into KB
  • Example: /clip https://example.com/article
• /kb - KB tools
  • Example: /kb stats

Tracking and goals

• /journal - Journal commands
  • Example: /journal today
• /habit - Habit tracking commands
  • Example: /habit done reading
• /mood - Mood logging/trends
  • Example: /mood good energy:high note:focused
• /goal - Goal/milestone management
  • Example: /goal add "Publish v1" by:2026-05-15 category:product
• /weekly - Weekly review
  • Example: /weekly

Slack and workflows

• /slack - Slack integrations (send/read/channels/mentions/search)
  • Example: /slack channels
• /notify - Quick Slack notification
  • Example: /notify Team sync moved to 4 PM
• /workflow - Automation workflows
  • Example: /workflow add

Voice

• /voice - Toggle voice input
  • Example: /voice
• /voice test - Record and transcribe test clip
  • Example: /voice test

Plugin commands

• Plugin commands are auto-discovered from assistant/plugins/*.py.
• Example default plugin command:
  • /github prs
  • /github issues
  • /github repos

Plugin development guide

Plugins live in pa/assistant/plugins/.

Required plugin structure

PLUGIN_NAME = "example"
PLUGIN_VERSION = "1.0"
PLUGIN_DESCRIPTION = "Example plugin"
PLUGIN_COMMANDS = {
    "/example": "Does something useful"
}

def setup(config: dict) -> bool:
    return True

def handle_command(command: str, args: list) -> None:
    pass

def on_message(message: str) -> None:
    # Optional hook
    pass

Loader behavior

• Auto-discovers .py files in plugins directory
• Skips __init__.py and files starting with _
• Calls setup(config) if present
• Skips plugin if setup returns False
• Registers plugin commands into /help
• Dispatches unknown command routing to plugin owner
• Broadcasts every non-command message to plugin hooks

Troubleshooting (common errors per integration)

PostgreSQL

• Error: database connection failed
  • Verify database.* keys in config
  • Confirm user/password and DB exists
  • Confirm PostgreSQL service is running

Groq

• Error: missing API key
  • Set groq_api_key in config or environment
  • Validate model name in model

Google Calendar/Gmail

• Error: OAuth flow not starting
  • Ensure credentials JSON path is correct
  • Check APIs are enabled in Google Cloud
  • Delete stale token files and re-auth

Notion

• Error: no tasks returned
  • Ensure integration has access to both databases
  • Verify database IDs in config

Slack

• Error: Slack not connected
  • Verify bot token starts with xoxb-
  • Ensure scopes are granted and app is installed
  • Invite bot to target channels

Knowledge base

• Error: model load failure
  • Install sentence-transformers
  • Ensure write access to knowledge.storage_path

Voice

• Error: transcription unavailable
  • Install voice deps from requirements.txt
  • Check microphone permissions/device availability
  • Use lighter model if memory is constrained

Plugins

• Error: plugin not loaded
  • Confirm required PLUGIN_NAME and handle_command
  • Check plugin import errors in startup logs
  • Ensure setup(config) returns True

Architecture overview (module map in plain text)

pa/
  assistant/
    __main__.py
    core/
      main.py                # startup sequence + REPL + command routing
      commands.py            # parse, aliases/macros, built-in command catalog
      orchestrator.py        # LLM conversation orchestration
      memory.py              # PostgreSQL schema and persistence
      plugin_system.py       # plugin discovery/loading/dispatch/broadcast
      handlers/
        calendar.py          # calendar command handlers
        tasks.py             # task command handlers
        email.py             # email command handlers
        knowledge.py         # knowledge command handlers
        tracking.py          # journal/habit/mood/goal handlers
        slack.py             # slack/notify handlers + notifier helpers
        workflows.py         # workflow command handlers
    features/
      briefing.py            # daily/weekly brief logic
      scheduler.py           # background jobs and automation schedules
      task_manager.py        # task backend router
      journal.py             # journal + mood features
      habits.py              # habits and streaks
      goals.py               # goal tracking
      workflows.py           # trigger/action automation engine
      knowledge.py           # vector KB + research
    integrations/
      calendar.py            # Google Calendar API
      email.py               # Gmail API
      notion.py              # Notion API
      slack.py               # Slack API
    utils/
      display.py             # config loading + rich output helpers
      timeparser.py          # natural language date/time parsing
      voice.py               # whisper audio capture/transcription
    plugins/
      github_plugin.py       # example plugin