AI Employee System - Silver Tier

An AI-powered business assistant with human-in-the-loop approval workflow, email integration, and automated social media posting.

Features

Silver Tier Capabilities

✅ Human-in-the-Loop Approval Workflow (User Story 1)

• Review and approve sensitive actions before execution
• Real-time dashboard with WebSocket updates
• 24-hour approval timeout with auto-reject
• REST API for programmatic approval management

✅ Email Integration via MCP Server (User Story 2)

• Send emails via Google Workspace MCP server
• Rate limiting (10 emails/hour)
• Ralph Wiggum Loop retry logic (5 attempts)
• Delivery confirmation logging

✅ Scheduled Task Automation (User Story 6)

• APScheduler integration (interval, cron, date triggers)
• Hour-level scheduling precision
• Gmail polling every 2 minutes
• LinkedIn posting 4 times per week

✅ Gmail Monitoring (User Story 4)

• Automatic email detection
• Task creation from new emails
• Deduplication tracking
• 2-minute polling interval

✅ LinkedIn Integration (User Story 3)

• Posting: Content generation from task history via REST API
• Scraping: Profile/company/job data via MCP server
• Duplicate detection (70% similarity)
• Approval workflow integration
• Rate limiting (4 posts/week, 30 scrapes/hour)

✅ AI Reasoning Loop (User Story 5)

• Plan.md generation for complex tasks
• Problem analysis and approach options
• Progress tracking
• Execution validation

Bronze Tier Capabilities (Maintained)

• Watchdog filesystem monitoring
• Ralph Wiggum Loop (5 retries with exponential backoff)
• Dashboard updates
• Task file processing
• Vault folder management

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+ (for Google Workspace MCP server)
• uv package manager
• Google Cloud Console project with OAuth 2.0 credentials
• LinkedIn Developer App (for posting)
• Chromium browser (for LinkedIn scraping)

Installation

# Install Python dependencies
uv pip install fastapi[all]==0.115.0 uvicorn watchdog apscheduler python-dotenv pyyaml

# Install MCP servers
# 1. Google Workspace MCP (Python-based)
uvx install workspace-mcp

# 2. LinkedIn MCP Scraper (Python-based)
uvx patchright install chromium  # Install browser first
uvx linkedin-scraper-mcp --login  # Create LinkedIn session

# Configure OAuth credentials
cp .env.example .env
# Edit .env with your credentials:
#   - Google OAuth (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)
#   - LinkedIn API (LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET)

# Authorize LinkedIn REST API (for posting)
./authorize_linkedin.sh

# Create vault credentials directory
mkdir -p /home/habib/vault/.credentials
chmod 700 /home/habib/vault/.credentials

Start the System

Option 1: Full System (Orchestrator + Dashboard + Scheduler)

# Start the orchestrator (includes scheduler and all services)
python run_orchestrator.py

This starts:

• Filesystem watcher (monitors /home/habib/vault/Inbox)
• Scheduler (Gmail polling, LinkedIn posting, approval timeouts)
• Dashboard API (http://localhost:8000)
• All Silver Tier services

Option 2: Dashboard Only (for testing)

# Start just the dashboard API
python src/api/main.py

Open http://localhost:8000 in your browser.

Validate Installation

./scripts/validate_silver_tier.sh

Architecture

Core Components

• Approval Handler - HITL approval workflow with timeout handling
• MCP Executor - JSON-RPC subprocess invocation with retry logic
• Skill Manager - Agent Skills auto-discovery and loading
• Fixed Scheduler - APScheduler integration for time-based tasks
• Gmail Watcher - Email monitoring with deduplication
• Task Processor - Task processing with approval integration

Agent Skills

• email-management.SKILL.md - Email sending via Google Workspace MCP
• social-posting.SKILL.md - LinkedIn content generation
• task-planning.SKILL.md - Plan.md generation for complex tasks

Configuration

All behavior is controlled via config/system.yaml:

• MCP server configuration
• Watcher settings (Gmail, LinkedIn)
• Scheduling (interval, cron, date)
• Approval workflow (timeout, default action)
• Rate limits (Gmail, LinkedIn)

Usage

Approval Workflow

1. Create a task file in /home/habib/vault/Needs_Action/
2. System detects task and checks if approval required
3. If approval needed, task moves to /home/habib/vault/Pending_Approval/
4. Review in dashboard at http://localhost:8000
5. Approve or reject the action
6. System executes approved actions

Email Sending

Create an email task:

---
id: EMAIL_001
type: email
created: 2026-02-15T12:00:00Z
status: pending
priority: medium
title: Send follow-up email
requires_approval: true
---

# Send follow-up email

**Recipient**: client@example.com
**Subject**: Follow-up on proposal
**Body**: Hi, just following up on our proposal. Let me know if you have questions.

LinkedIn Integration

Two separate integrations for different purposes:

1. LinkedIn Posting (REST API - Write Access)

LinkedIn posts are generated automatically 4 times per week (9am, 12pm, 3pm, 6pm on weekdays). Content is generated from completed tasks in the last 7 days.

Posts require approval before publishing. After approval, the system posts directly to LinkedIn via the REST API.

Setup: See LinkedIn Integration Guide

2. LinkedIn Scraping (MCP Server - Read Access)

Read profiles, companies, and job postings via the LinkedIn MCP server.

Available tools:

• get_person_profile - Get profile data (experience, education, skills)
• get_company_profile - Get company info (about, posts, jobs)
• search_jobs - Search job listings with filters
• get_job_details - Get detailed job information

Setup: See LinkedIn Integration Guide

Complex Task Planning

For complex tasks, add requires_planning: true or complexity: high to the task frontmatter. The system will generate a Plan.md file with:

• Problem analysis
• Approach options
• Selected approach with rationale
• Execution steps
• Progress tracking

Known Issues

✅ Google Workspace MCP Server - RESOLVED

Previous Issue: The MCP server was incorrectly assumed to be an npm package.

Resolution: The Google Workspace MCP server is Python-based and accessible via uvx. All email and Gmail features are now ready for testing.

Status: T002 complete - 99% implementation (77/78 tasks)

See MCP_BLOCKER_RESOLVED.md for details.

Integration Tasks

✅ Completed

• Scheduler integration with orchestrator main.py (T045)
• Gmail watcher scheduling (T051)
• Async/await support for orchestrator
• Startup script creation

⏸️ Optional/Future

• Supervisord process management configuration (T052)
• Hot-reload configuration support (T074)

Implementation Status

Total Tasks: 78 Completed: 77 tasks (99%) ✅ Deferred: 1 task (T052 - Supervisord optional)

Phase Completion

• ✅ Phase 1 (Setup): 5/5 (100%) - MCP blocker resolved
• ✅ Phase 2 (Foundational): 10/10 (100%)
• ✅ Phase 3 (US1 - Approval): 15/15 (100%) 🎯 MVP
• ✅ Phase 4 (US2 - Email): 7/7 (100%)
• ✅ Phase 5 (US6 - Scheduling): 9/9 (100%)
• ✅ Phase 6 (US4 - Gmail): 7/7 (100%)
• ✅ Phase 7 (US3 - LinkedIn): 9/9 (100%)
• ✅ Phase 8 (US5 - AI Reasoning): 6/6 (100%)
• ✅ Phase 9 (Polish): 10/10 (100%)

Integration Status

✅ Scheduler Integration Complete

• Scheduler fully integrated with orchestrator
• Gmail polling scheduled (every 2 minutes)
• LinkedIn posting scheduled (4x/week)
• Approval timeout checking scheduled (every 5 minutes)
• Async/await support added to orchestrator
• Startup script created (run_orchestrator.py)

Documentation

• Specification - Feature requirements
• Implementation Plan - Architecture and design
• Tasks - Task breakdown
• Quickstart Guide - 5-minute setup
• Data Model - Entity definitions
• API Contracts - API specifications

Deployment

Azure Deployment (Recommended)

Deploy to Azure Container Apps with persistent storage and secrets management:

# Quick deploy to Azure
cd deploy
./azure-deploy.sh

# Check deployment status
./azure-status.sh

# View logs
./azure-logs.sh

See Azure Deployment Guide for complete instructions.

Local Development

# Option 1: Docker Compose
docker-compose up

# Option 2: Direct Python
python run_orchestrator.py

Next Steps

1. Deploy to Azure - Run ./deploy/azure-deploy.sh for production deployment
2. Test the System - Start orchestrator and validate all services
3. Test Approval Workflow - Create test tasks and validate end-to-end
4. Configure Monitoring - Run ./deploy/azure-monitoring.sh for alerts

Support

• Logs: /home/habib/hackathon0-improved/logs/
• Configuration: config/system.yaml
• Validation: ./scripts/validate_silver_tier.sh

License

See LICENSE file for details.