AI Employee Vault - Complete Hackathon 0 Project

Tagline: Your life and business on autopilot. Local-first, agent-driven, human-in-the-loop.

Tier Declaration: Platinum (Partial - Cloud deployment pending)
Last Updated: April 5, 2026

---

📋 Table of Contents

1. Project Overview
2. Architecture
3. Prerequisites & Setup
4. Bronze Tier - Foundation
5. Silver Tier - Functional Assistant
6. Gold Tier - Autonomous Employee
7. Platinum Tier - Always-On + AI Features
8. What's Missing
9. Project Structure
10. Troubleshooting
11. Security

---

Project Overview

A Personal AI Employee that proactively manages your personal affairs (Gmail, WhatsApp) and business (Social Media, Payments, Tasks) 24/7. Built as a "Digital FTE" (Full-Time Equivalent) that works ~9,000 hours/year vs a human's 2,000, at 85-90% cost savings.

Key Features:

• Local-first: All data stays on your machine (Obsidian Markdown vault)
• Proactive: Watchers monitor Gmail, WhatsApp, LinkedIn, Twitter, Facebook 24/7
• Human-in-the-Loop: Approval workflow prevents AI accidents
• ML-Powered: Learns from your corrections over time
• LLM-Enhanced: Generates natural language posts/emails (OpenAI/Gemini)
• Web Dashboard: Monitor, approve, and manage everything from a browser
• Voice Interface: Hands-free operation via voice commands

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    EXTERNAL SOURCES                             │
│   Gmail  │  WhatsApp  │  LinkedIn  │  Twitter  │  Facebook     │
└────┬──────────┬──────────┬───────────┬──────────┬──────────────┘
     │          │          │           │          │
     ▼          ▼          ▼           ▼          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PERCEPTION LAYER (Watchers)                  │
│  gmail_watcher │ whatsapp_watcher │ linkedin_watcher │ etc.    │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OBSIDIAN VAULT (Local)                       │
│  /Needs_Action/ → /Plans/ → /Pending_Approval/ → /Approved/    │
│  Dashboard.md │ Company_Handbook.md │ Business_Goals.md         │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    REASONING LAYER                              │
│  Claude Code + Ralph Wiggum Loop (multi-step autonomy)          │
│  ML Classifier (TF-IDF + Naive Bayes)                           │
│  LLM Generator (OpenAI/Gemini + template fallback)              │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ACTION LAYER                                 │
│  MCP Servers (Email) │ Multi-Platform Publisher │ HITL Handler  │
│  Auto-Scaler │ A/B Testing │ Predictive Analytics │ Voice       │
└─────────────────────────────────────────────────────────────────┘

---

Prerequisites & Setup

Required Software

Component	Version	Purpose
Python	3.13+	Watchers, skills, orchestration
Node.js	v24+ LTS	MCP servers
Obsidian	v1.10.6+	Knowledge base & dashboard
Claude Code	Latest	Primary reasoning engine
Git	Latest	Version control

Python Dependencies

cd AI_Employee_Vault

# Core dependencies
pip install watchdog playwright google-auth google-auth-oauthlib google-api-python-client

# ML/AI dependencies
pip install scikit-learn joblib

# Web dashboard
pip install flask

# Voice interface (optional)
pip install SpeechRecognition pyttsx3

# System monitoring (for auto-scaler)
pip install psutil

# Install Playwright browsers
playwright install

Node.js Dependencies

cd AI_Employee_Vault/mcp_servers/email-mcp
npm install

Google API Setup

1. Go to Google Cloud Console
2. Enable Gmail API
3. Create OAuth 2.0 credentials
4. Download credentials.json → place in project root
5. First run of Gmail watcher will open browser for OAuth authorization

---

Bronze Tier - Foundation

Status: ✅ COMPLETE (6/6 requirements met)

What's Included

Requirement	File	Status
Obsidian vault	.obsidian/	✅
Dashboard.md	Dashboard.md	✅
Company_Handbook.md	Company_Handbook.md	✅
One watcher	watchers/filesystem_watcher.py	✅
Folder structure	/Inbox, /Needs_Actions, /Done	✅
Agent Skills	Skills/*.md (9 skill definitions)	✅

How to Run

1. File System Watcher (monitors /Inbox for new files):

cd AI_Employee_Vault
python watchers/filesystem_watcher.py

2. Test it:

# Drop a file into Inbox
echo "Process this" > Inbox/test.txt

# Watcher copies it to Needs_Actions with metadata
ls Needs_Actions/FILE_test.txt
ls Needs_Actions/FILE_test.txt_metadata.md

How to Verify

• Dashboard.md exists and shows bank balance, pending messages, active tasks
• Company_Handbook.md contains your rules of engagement
• Dropping a file in Inbox/ creates files in Needs_Actions/
• Claude Code can read and write to the vault

---

Silver Tier - Functional Assistant

Status: ✅ COMPLETE (6/6 requirements met)

What's Included

Requirement	File	Status
2+ watchers	6 watchers total	✅
LinkedIn auto-posting	Skills/auto_linkedin_poster.py	✅
Plan.md files	Plans/ directory	✅
MCP server	mcp_servers/email-mcp/index.js	✅
HITL approval	Skills/hitl_approval_handler.py	✅
Scheduling	schedulers/ (daily + weekly)	✅

Watchers

Watcher	File	Interval	Keywords
File System	watchers/filesystem_watcher.py	Real-time	N/A
Gmail	watchers/gmail_watcher.py	120s	urgent, invoice, payment, sales
LinkedIn	watchers/linkedin_watcher.py	60s	sales, client, project
WhatsApp	watchers/whatsapp_watcher.py	30s	urgent, invoice, payment, sales
Facebook/Instagram	watchers/facebook_instagram_watcher.py	60s	sales, client, project
Twitter	watchers/twitter_watcher.py	60s	sales, client, project

How to Run

Start individual watchers:

cd AI_Employee_Vault

# Gmail Watcher (first run opens browser for OAuth)
python watchers/gmail_watcher.py

# LinkedIn Watcher (first run requires LinkedIn login)
python watchers/linkedin_watcher.py

# WhatsApp Watcher (first run requires QR code scan)
python watchers/whatsapp_watcher.py

# Auto LinkedIn Poster (creates drafts from business leads)
python Skills/auto_linkedin_poster.py

Start all watchers with PM2 (production):

npm install -g pm2

cd AI_Employee_Vault
pm2 start watchers/filesystem_watcher.py --name "fs_watcher" --interpreter python
pm2 start watchers/gmail_watcher.py --name "gmail_watcher" --interpreter python
pm2 start watchers/linkedin_watcher.py --name "linkedin_watcher" --interpreter python
pm2 start watchers/whatsapp_watcher.py --name "whatsapp_watcher" --interpreter python
pm2 start Skills/auto_linkedin_poster.py --name "linkedin_poster" --interpreter python --cron "*/5 * * * *"

pm2 save
pm2 startup

Start MCP Server:

cd AI_Employee_Vault/mcp_servers/email-mcp
node index.js

How to Test

1. Gmail Watcher: Send yourself an email with "urgent" or "invoice" in subject, mark as unread, wait 120s
2. LinkedIn Poster: Create a business lead in Needs_Actions/, run python Skills/auto_linkedin_poster.py, check Pending_Approval/
3. HITL Workflow: Check Pending_Approval/ → move file to Approved/ → HITL handler executes it
4. MCP Email: Use Claude Code to call draft_email tool, check Plans/ for draft

---

Gold Tier - Autonomous Employee

Status: ✅ COMPLETE (7/8 - Odoo accounting pending)

What's Included

Requirement	File	Status
Cross-domain integration	Skills/cross_domain_integrator.py	✅
Facebook/Instagram	watchers/facebook_instagram_watcher.py	✅
Twitter integration	watchers/twitter_watcher.py + Skills/twitter_post_generator.py	✅
Weekly audit + CEO briefing	Skills/weekly_audit_briefer.py	✅
Error recovery	utils/error_recovery.py	✅
Audit logging	utils/audit_logger.py	✅
Ralph Wiggum loop	tools/ralph_loop_runner.py	✅
Odoo accounting (MCP)	NOT IMPLEMENTED	❌

How to Run

Cross Domain Integrator (classifies personal vs business, routes appropriately):

cd AI_Employee_Vault
python Skills/cross_domain_integrator.py

Ralph Wiggum Loop (multi-step autonomous task execution):

python tools/ralph_loop_runner.py "Process all files in Needs_Actions" --max-iterations 20

Weekly Audit Briefer (generates CEO briefing):

python Skills/weekly_audit_briefer.py
# Output: Briefings/ceo_briefing_YYYYMMDD.md

Error Recovery Tests:

python test_error_recovery.py
# Validates: bad input handling, error logging, error files, degradation plans, retry with backoff, graceful skip, audit logger

How to Test

1. Cross-Domain: Drop files in Needs_Actions/, run integrator, check Pending_Approval/ (personal) and Plans/ (business)
2. Ralph Loop: Run with test data, verify all 11 steps execute (scan → classify → route → summary → draft → approval → execute → publish → log → done)
3. Weekly Audit: Run briefer, check Briefings/ for generated CEO report with revenue, bottlenecks, suggestions
4. Error Recovery: Disconnect network, run a watcher, verify exponential backoff retry in Logs/error_*.log

---

Platinum Tier - Always-On + AI Features

Status: 🔄 PARTIALLY COMPLETE (Hackathon cloud requirements pending, AI features complete)

AI Features Included (Beyond Hackathon Spec)

Feature	File	Status
Web Dashboard	dashboard/app.py + 8 templates	✅
ML-Based Classification	utils/ml_classifier.py	✅
LLM Content Generation	utils/llm_generator.py	✅
Multi-Platform Publishing	Skills/multi_platform_publisher.py	✅
Predictive Analytics	Skills/predictive_analytics.py	✅
A/B Testing Framework	Skills/ab_testing_framework.py	✅
Auto-Scaling	Skills/auto_scaler.py	✅
Voice Interface	Skills/voice_interface.py	✅

Hackathon Platinum Requirements (Not Yet Implemented)

Requirement	Status	Notes
Cloud deployment (24/7 VM)	❌	Requires Oracle/AWS VM setup
Work-zone specialization	❌	Cloud vs local routing logic
Synced vault (Git/Syncthing)	❌	No git repo initialized
Claim-by-move rule	❌	No multi-agent ownership mechanism
Odoo on cloud VM	❌	Odoo not implemented (also Gold gap)
A2A upgrade	❌	Agent-to-Agent protocol

How to Run Platinum Features

1. Web Dashboard:

cd AI_Employee_Vault
python dashboard/app.py
# Open browser: http://localhost:5000

Dashboard pages:

• / - Main dashboard with stats, charts, quick actions
• /queue - Needs Actions queue viewer
• /approvals - Approve/reject workflow UI
• /logs - Audit log viewer with filters
• /errors - Error reports viewer
• /briefings - CEO briefings viewer
• /ml - ML Classifier management (train, view data, retrain)
• /llm - LLM content generator (LinkedIn posts, emails, tweets, WhatsApp)

2. ML Classifier (replaces keyword matching with ML):

# Train from existing data
python utils/ml_classifier.py train --dirs Needs_Actions Done

# Classify a file
python utils/ml_classifier.py classify Needs_Actions/some_file.md

# View stats
python utils/ml_classifier.py stats

# Learn from a correction
python utils/ml_classifier.py learn Needs_Actions/some_file.md --domain business --source linkedin

3. LLM Content Generator:

# Generate LinkedIn post
python utils/llm_generator.py generate linkedin --lead "Client needs website, budget $5000" --tone professional

# Generate email response
python utils/llm_generator.py generate email --original "Need a quote for..." --type sales_reply --tone friendly

# Generate tweet
python utils/llm_generator.py generate tweet --topic "New product launch" --tone excited

# Check status
python utils/llm_generator.py status

4. Multi-Platform Publisher:

# Dry run (simulate publishing)
python Skills/multi_platform_publisher.py publish --dry-run

# Publish all approved files
python Skills/multi_platform_publisher.py publish --all

# Check status
python Skills/multi_platform_publisher.py status

# Configure platforms
python Skills/multi_platform_publisher.py config --platform twitter --enable

5. Predictive Analytics:

# Full analytics report
python Skills/predictive_analytics.py report

# Revenue forecast
python Skills/predictive_analytics.py forecast

# Detect anomalies
python Skills/predictive_analytics.py anomalies

# Score a lead
python Skills/predictive_analytics.py lead-score --content "Client needs website, budget $8000, 3 weeks timeline"

# View trends
python Skills/predictive_analytics.py trends --days 7

6. A/B Testing:

# Create a test
python Skills/ab_testing_framework.py create --name "LinkedIn Post Tone" --variants professional casual formal

# Record results
python Skills/ab_testing_framework.py record --test <test_id> --variant professional --score 85

# View all tests
python Skills/ab_testing_framework.py list

# Get winner
python Skills/ab_testing_framework.py winner --test <test_id>

# Get recommendations
python Skills/ab_testing_framework.py recommendations

7. Auto-Scaler:

# Check status
python Skills/auto_scaler.py status

# Evaluate and apply scaling
python Skills/auto_scaler.py evaluate

# Reset to defaults
python Skills/auto_scaler.py reset

8. Voice Interface:

# Interactive mode (text-based for testing)
python Skills/voice_interface.py cmd "status"
python Skills/voice_interface.py cmd "queue"
python Skills/voice_interface.py cmd "approve 1"
python Skills/voice_interface.py cmd "help"

# Full voice mode (requires microphone + SpeechRecognition package)
python Skills/voice_interface.py listen

Available voice commands: approve [number], reject [number], status, queue, how many pending, list approvals, help, exit

---

What's Missing

Critical Gaps

Gap	Tier	Priority	Effort
Odoo Accounting via MCP	Gold	HIGH	20-30 hours
Cloud Deployment	Platinum	MEDIUM	10-15 hours
Synced Vault (Git)	Platinum	MEDIUM	2-4 hours
Work-Zone Specialization	Platinum	LOW	8-12 hours
Claim-by-Move Rule	Platinum	LOW	4-6 hours
A2A Protocol	Platinum	LOW	10-15 hours

Odoo Accounting (Highest Priority Missing Feature)

To implement:

1. Install Odoo Community Edition (self-hosted, local or cloud)
2. Create MCP server using Odoo's JSON-RPC APIs
3. Implement: invoice creation, payment drafting, transaction logging
4. Integrate with HITL approval workflow

Reference: https://www.odoo.com/documentation/19.0/developer/reference/external_api.html

---

Project Structure

Hackathona 0/
├── credentials.json                          # Google OAuth credentials
├── package.json                              # Node.js dependencies
├── README.md                                 # This file
│
└── AI_Employee_Vault/                        # Main vault
    ├── Dashboard.md                          # Real-time summary
    ├── Company_Handbook.md                   # Rules of engagement
    ├── Business_Goals.md                     # Q1/Annual goals tracking
    ├── mcp.json                              # MCP server configuration
    ├── SETUP_GUIDE.md                        # Detailed setup guide
    ├── ERROR_RECOVERY_TEST_GUIDE.md          # Error recovery testing guide
    │
    ├── watchers/                             # Perception layer
    │   ├── filesystem_watcher.py             # Bronze: File monitoring
    │   ├── gmail_watcher.py                  # Silver: Gmail monitoring
    │   ├── linkedin_watcher.py               # Silver: LinkedIn monitoring
    │   ├── whatsapp_watcher.py               # Silver: WhatsApp monitoring
    │   ├── facebook_instagram_watcher.py     # Gold: Facebook/Instagram
    │   └── twitter_watcher.py                # Gold: Twitter monitoring
    │
    ├── Skills/                               # Processing & action skills
    │   ├── cross_domain_integrator.py        # Gold: Personal vs business routing
    │   ├── auto_linkedin_poster.py           # Silver: LinkedIn post drafts
    │   ├── hitl_approval_handler.py          # Silver: HITL workflow
    │   ├── social_summary_generator.py       # Gold: Social message summaries
    │   ├── twitter_post_generator.py         # Gold: Twitter post generation
    │   ├── weekly_audit_briefer.py           # Gold: CEO briefing generation
    │   ├── multi_platform_publisher.py       # Platinum: Multi-platform publishing
    │   ├── predictive_analytics.py           # Platinum: Lead scoring, forecasting
    │   ├── ab_testing_framework.py           # Platinum: A/B content testing
    │   ├── auto_scaler.py                    # Platinum: Dynamic load scaling
    │   └── voice_interface.py                # Platinum: Voice commands
    │
    ├── utils/                                # Shared utilities
    │   ├── audit_logger.py                   # Gold: Centralized audit logging
    │   ├── error_recovery.py                 # Gold: Exponential backoff retry
    │   ├── ml_classifier.py                  # Platinum: ML-based classification
    │   └── llm_generator.py                  # Platinum: LLM content generation
    │
    ├── dashboard/                            # Platinum: Web dashboard
    │   ├── app.py                            # Flask server
    │   ├── requirements.txt                  # Flask dependencies
    │   └── templates/                        # HTML templates (8 files)
    │
    ├── mcp_servers/email-mcp/                # Silver: Email MCP server
    │   ├── index.js
    │   └── package.json
    │
    ├── tools/                                # Orchestration
    │   ├── ralph_loop_runner.py              # Gold: Multi-step task execution
    │   └── RALPH_LOOP_GUIDE.md
    │
    ├── schedulers/                           # Scheduling scripts
    │   ├── daily_scheduler.ps1/.sh
    │   └── weekly_audit_briefer.ps1/.sh
    │
    ├── ml_model/                             # ML classifier data
    │   ├── classifier_model.pkl
    │   ├── training_data.json
    │   └── metadata.json
    │
    ├── Inbox/                                # Drop files here for processing
    ├── Needs_Actions/                        # Auto-processed items
    ├── Plans/                                # Draft content
    ├── Pending_Approval/                     # HITL queue
    ├── Approved/                             # Approved content
    ├── Rejected/                             # Rejected content
    ├── Done/                                 # Completed tasks
    ├── Logs/                                 # Audit & error logs
    ├── Errors/                               # Detailed error reports
    ├── Briefings/                            # CEO weekly briefings
    └── session/                              # Browser sessions (LinkedIn, WhatsApp, etc.)

---

Troubleshooting

Common Issues

Issue	Solution
Gmail "credentials.json not found"	Copy client secret to project root as credentials.json
Playwright "Browser not found"	Run playwright install
Watcher stops overnight	Use PM2: pm2 start watcher.py --interpreter python
Token expired (Gmail)	Delete watchers/token.json, re-run Gmail watcher
CSS selectors not working	Update selectors in watcher scripts (platforms change)
Permission denied	Run terminal as Administrator
Flask dashboard won't start	pip install flask
ML classifier not available	pip install scikit-learn joblib
Voice interface not working	pip install SpeechRecognition pyttsx3

Error Recovery

All watchers and skills include error recovery:

• Exponential backoff retry (1s → 2s → 4s, max 60s)
• Error logging to /Logs/error_[component]_[date].log
• Graceful degradation (skip bad input, continue processing)
• Manual action plans created after 10+ consecutive errors

Run tests: python test_error_recovery.py

---

Security

Credential Management

• NEVER commit credentials.json, .env, or session files
• Use environment variables for API keys
• Rotate credentials monthly
• Add .gitignore immediately if initializing git repo

Human-in-the-Loop Rules

Action	Auto-Approve Threshold	Always Requires Approval
Email replies	Known contacts	New contacts, bulk sends
Payments	< $50 recurring	All new payees, > $100
Social media	Scheduled posts	Replies, DMs
File operations	Create, read	Delete, move outside vault

Audit Trail

Every action is logged to /Logs/audit_YYYYMMDD.json with:

• Timestamp, actor, action type, target, parameters, result
• 90-day retention with auto-cleanup

---

Quick Reference

Start Everything (Development)

# Terminal 1: File System Watcher
python watchers/filesystem_watcher.py

# Terminal 2: Gmail Watcher
python watchers/gmail_watcher.py

# Terminal 3: LinkedIn Watcher
python watchers/linkedin_watcher.py

# Terminal 4: WhatsApp Watcher
python watchers/whatsapp_watcher.py

# Terminal 5: Web Dashboard
python dashboard/app.py

Start Everything (Production with PM2)

cd AI_Employee_Vault
pm2 start watchers/filesystem_watcher.py --name "fs_watcher" --interpreter python
pm2 start watchers/gmail_watcher.py --name "gmail_watcher" --interpreter python
pm2 start watchers/linkedin_watcher.py --name "linkedin_watcher" --interpreter python
pm2 start watchers/whatsapp_watcher.py --name "whatsapp_watcher" --interpreter python
pm2 start Skills/auto_linkedin_poster.py --name "linkedin_poster" --interpreter python --cron "*/5 * * * *"
pm2 start dashboard/app.py --name "dashboard" --interpreter python
pm2 save
pm2 startup

Check Status

pm2 status
pm2 logs

---

Version: 1.0
Tiers Complete: Bronze ✅ | Silver ✅ | Gold ✅ (7/8) | Platinum 🔄 (AI features complete, cloud deployment pending)
License: Internal Use Only