使用说明

🤖 Personal AI Employee - Silver Tier (Vector)

Autonomous File & Email Processing with Agent Skills & MCP

Version: 2.0 (Silver Tier Complete, Platinum Ready)
Last Updated: 2026-02-21
Status: ✅ Production Ready

📖 TABLE OF CONTENTS

What Is This?
How It Works
Quick Start (5 Minutes)
Installation (Step-by-Step)
Usage Guide
Folder Movement Logic
Tech Stack
Agent Skills
Security & Privacy
Troubleshooting
FAQ

🎯 WHAT IS THIS?

Personal AI Employee is an autonomous assistant that:

✅ Watches your files 24/7 (detects new files in /Inbox)
✅ Monitors your emails (Gmail API integration)
✅ Processes items using AI (categorizes, prioritizes, suggests actions)
✅ Routes high-value items for your approval (HITL safety)
✅ Keeps you updated in real-time (Dashboard.md)
✅ Creates complete audit trails (every action logged)

100% Free Tools: Gemini API, Gmail API, Python, Obsidian

🤖 Talos: The Autonomous Workforce (Current Tier: Silver)

Architected by Ibrahim Tayyab (The IT Boy)

"Your Files. Your Rules. Zero Oversight."

Talos is not just a script; it's a living digital entity designed to evolve. Starting as a Bronze Tier guardian, it has now evolved into a Silver Tier (Vector) executor that not only watches your workflow but actively researches, drafts emails, automates LinkedIn responses, and uses MCP (Model Context Protocol) to empower Claude Code.

The Silver Tier foundation establishes the critical Perception, Reasoning, and Action (MCP) layers:

👁️ Perception: Watches your digital environment 24/7 (gmail_live_watcher.py, filesystem_watcher.py).
🧠 Reasoning: Thinks before it acts using Agent Skills (Email, Social, Planner, Research).
⚙️ Action: Features a working Python MCP Server (email_mcp.py) bridging the AI directly to your Gmail.
🛡️ Safety: Enforces strict Human-in-the-Loop (HITL) protocols for high-value decisions.

🗺️ THE TALOS EVOLUTION (ROADMAP)

Talos is designed to evolve. Each tier unlocks new capabilities, transforming from a guardian into an executive.

Tier	Code Name	Identity	Status
🥉 BRONZE	SENTRY	The Guardian. Watches files/emails. Filters noise. Demands human approval for critical actions. 100% Safe.	✅ COMPLETED
🥈 SILVER	VECTOR	The Executor. Gained the ability to act. Executes approved tasks, sends emails natively, drafts LinkedIn posts, web research, and utilizes MCP servers.	✅ ACTIVE
🥇 GOLD	NEXUS	The Brain. Deep memory & context. Remembers past interactions, preferences, and complex project histories.	🔒 Locked
💎 PLATINUM	APEX	The Executive. Full autonomy. Proactive decision making, cloud orchestration, and strategic management.	🔒 Locked

🏗️ HOW IT WORKS (ARCHITECTURE)

┌─────────────────────────────────────────────────────────┐
│                   PERCEPTION LAYER                       │
│  (24/7 Monitoring using Watchdog + Gmail API)          │
└─────────────────┬───────────────────────────────────────┘
                  │
        ┌─────────┴──────────┐
        │                    │
   File Drops           Important Emails
   (Inbox/)            (Gmail Important)
        │                    │
        └─────────┬──────────┘
                  ↓
        Metadata .md Created
        (Needs_Action/)
                  │
┌─────────────────┴───────────────────────────────────────┐
│                   REASONING LAYER                        │
│        (Agent Skills - AI Categorization)                │
│                                                          │
│  • email_processor.py - Email triage & VIP Drafts       │
│  • social_media_agent.py - LinkedIn automation          │
│  • planner.py - Multi-step execution planning           │
│  • research_agent.py - DuckDuckGo Web Research          │
│  • task_manager.py - File handling & workflow           │
└─────────────────┬───────────────────────────────────────┘
                  │
         ┌────────┴────────┐
         │                 │
   Auto-Approvable?   Needs Approval?
   (Low-value)        (High-value)
         │                 │
         ↓                 ↓
┌──────────────┐  ┌──────────────────┐
│   /Done      │  │ /Pending_Approval│
│  (Complete)  │  │  (Human Review)  │
└──────────────┘  └─────────┬────────┘
                            │
                    Human Approves
                    (Moves file to /Approved)
                            │
                            ↓
┌──────────────────────────┴──────────────────────────────┐
│                     ACTION LAYER                         │
│         (Final Execution - Platinum Tier)                │
│                                                          │
│  • Execute approved actions                              │
│  • Send emails, make payments, etc.               │
│  • Create completion records                             │
└──────────────────────────────────────────────────────────┘
                            │
                            ↓
                   Dashboard.md Updated

⚡ QUICK START

If you already have Python and dependencies installed:

1. Drop a Test File

# Open File Explorer
# Navigate to: e:\hackton 0\New folder\AI_Employee_Vault\Inbox
# Drop ANY file (text, image, document)

2. Start Watcher (One Command)

cd "e:\hackton 0\New folder\AI_Employee_Vault"
.\test_watcher.bat

Watch it detect the file in real-time!

3. Process Items

# Open new terminal
cd "e:\hackton 0\New folder\AI_Employee_Vault\scripts"
python process_items.py

4. Check Results

# Open in File Explorer or Obsidian:
# - Check Done/ folder for completed file
# - Open Dashboard.md for updates

Done! You've verified the complete workflow!

💻 INSTALLATION

Prerequisites

Required:

✅ Python 3.13+ (Download)
✅ Node.js v24+ (Download)
✅ Git (Download)

Optional but Recommended:

Obsidian (Download) - For viewing Dashboard.md
VS Code (Download) - For editing code

Step 1: Clone or Download

# Option A: Git Clone
git clone <your-repo-url>
cd AI_Employee_Vault

# Option B: Download ZIP
# Extract to: e:\hackton 0\New folder\AI_Employee_Vault

Step 2: Install Python Dependencies

cd "e:\hackton 0\New folder\AI_Employee_Vault\scripts"

# Install all required packages
pip install watchdog rich google-api-python-client google-auth-oauthlib google-auth-httplib2 python-dotenv

Expected Output:

Successfully installed watchdog-6.0.0 rich-13.7.0 ...

Step 3: Configure Environment

Copy .env.example to .env:

cd "e:\hackton 0\New folder\AI_Employee_Vault"
copy .env.example .env

Edit .env file and add your API keys:

notepad .env

Required Configuration:

# Get your free Gemini API key from: https://aistudio.google.com/apikey
GEMINI_API_KEY=your_actual_gemini_key_here

# Vault path (update if different)
VAULT_PATH=e:/hackton 0/New folder/AI_Employee_Vault

# Other paths (auto-configured)
INBOX_FOLDER=e:/hackton 0/New folder/AI_Employee_Vault/Inbox
NEEDS_ACTION_FOLDER=e:/hackton 0/New folder/AI_Employee_Vault/Needs_Action
DONE_FOLDER=e:/hackton 0/New folder/AI_Employee_Vault/Done

Save and close .env

Step 4: (Optional) Gmail API Setup

Only if you want email monitoring:

Go to Google Cloud Console
Create new project: "AI Employee"
Enable Gmail API
Create OAuth 2.0 credentials
Download as credentials.json
Place in: scripts/credentials.json

Update .env:

GMAIL_CREDENTIALS_PATH=e:/hackton 0/New folder/AI_Employee_Vault/scripts/credentials.json
GMAIL_TOKEN_PATH=e:/hackton 0/New folder/AI_Employee_Vault/scripts/token.json

Step 5: Verify Installation

# Run automated tests
cd "e:\hackton 0\New folder\AI_Employee_Vault"
.\test_quick.bat

Expected:

Test 1: Folder Structure               PASSED
Test 2: Essential Files                PASSED
Test 3: Watcher Scripts                PASSED
Test 4: Inbox -> Needs_Action          PASSED
Test 5: Item Processing                PASSED
Test 6: Dashboard Update               PASSED
Test 7: Security Checks                PASSED

Overall: 7/7 tests passed (100%)

✅ Installation Complete!

🎮 USAGE GUIDE

Daily Operation

1. Start Watchers (Morning)

cd "e:\hackton 0\New folder\AI_Employee_Vault"
.\start_watchers.bat

This starts 24/7 monitoring:

filesystem_watcher.py - Watches /Inbox folder
gmail_watcher.py - Watches Gmail (if configured)
orchestrator.py - Coordinates everything

Leave these running in the background!

2. Drop Files or Receive Emails

Option A: File Drop

Drag any file into /Inbox folder
Watcher detects instantly
Metadata created in /Needs_Action

Option B: Email

Mark email as "Important" in Gmail
Gmail watcher detects it
Email metadata created in /Needs_Action

3. Process Items (Manual or Scheduled)

# Manually process pending items
cd scripts
python process_items.py

OR schedule this to run every hour:

# Windows Task Scheduler
# Task: Run python process_items.py
# Trigger: Every 1 hour

4. Review Approvals (If Any)

Check /Pending_Approval folder:

Open file, read AI's analysis
Decide: Approve or Reject

If Approved:

Move file from /Pending_Approval to /Approved

If Rejected:

Delete file (or move to /Done with note)

5. Execute Approved Actions (Platinum Tier)

# Run approval executor
cd scripts
python approval_executor.py  # (TO BE CREATED IN PLATINUM)

This executes final Actions:

Send emails
Make payments
Update systems

6. Check Dashboard (Anytime)

# Open in Obsidian or text editor
notepad Dashboard.md

You'll see:

System status (Active/Paused)
Pending items count
Recent activity log
Error notifications (if any)

📁 FOLDER MOVEMENT LOGIC (The Workflow)

File Lifecycle

1. /Inbox
   ↓ (File watcher detects new file)
   
2. /Needs_Action
   ├─ Contains: Metadata .md file with YAML frontmatter
   ├─ Status: Waiting for AI processing
   ↓ (process_items.py runs)
   
3a. /Done (Auto-Approvable)
    ├─ Low-value items
    ├─ General emails
    └─ Simple file cataloging
    
3b. /Pending_Approval (Needs Human Review)
    ├─ Financial >$100
    ├─ High priority items
    ├─ First-time contacts
    └─ Commitments/deadlines
    ↓ (Human reviews and decides)
    
4. /Approved (Human Moved)
   ├─ Status: Ready for final execution
   ↓ (approval_executor.py runs - Platinum Tier)
   
5. /Done (Final State)
   ├─ Completion record created
   ├─ Audit trail complete
   └─ Dashboard updated

What Determines the Path?

Agent Skills decide based on:

Email Processor Skill:

# Categorization
if any(word in email for word in ['invoice', 'payment', 'bill']):
    category = 'Financial'
elif any(word in email for word in ['meeting', 'call', 'schedule']):
    category = 'Calendar'
    
# Prioritization
if any(word in email for word in ['urgent', 'asap', 'critical']):
    priority = 'High'
    
# Approval Check
if category == 'Financial' and priority == 'High':
    needs_approval = True  # → Pending_Approval
else:
    needs_approval = False  # → Done

Task Manager Skill:

# File categorization
if file_type in ['pdf', 'doc', 'docx']:
    category = 'Document'
    
if any(word in filename for word in ['invoice', 'receipt']):
    needs_special_handling = True  # → Pending_Approval

🛠️ TECH STACK

Component	Technology	Version	Purpose
Language	Python	3.13.5	Core logic
Runtime	Node.js	v24.11.1	Future MCP integration
AI Engine	Google Gemini	Free Tier	Reasoning (future)
File Monitoring	Watchdog	6.0.0	Real-time detection
Terminal UI	Rich	13.7.0	Beautiful output
Email API	Gmail API	Free	Email monitoring
Auth	OAuth2	google-auth	Gmail authentication
Vault	Obsidian	Free	Knowledge base
VCS	Git	Latest	Version control

🧠 AGENT SKILLS

What Are Agent Skills?

Agent Skills are executable Python modules that contain the AI reasoning logic.

NOT just documentation - they are real code that runs!

Implemented Skills

1. Email Processor Skill

File: .claude/skills/email_processor/email_processor.py

Capabilities:

✅ Cat

egorizes emails (Financial, Calendar, Support, General)

✅ Assigns priority (High, Medium, Low)
✅ Suggests actions based on category
✅ Detects if approval required
✅ Analyzes dollar amounts ($75,000 triggers high priority)
✅ Keyword detection ("urgent", "asap", "critical")

Example:

from email_processor.email_processor import EmailProcessor

processor = EmailProcessor(vault_path)
result = processor.process(email_content, metadata)

# Returns:
{
    'category': 'Financial',
    'priority': 'High',
    'needs_approval': True,
    'suggested_actions': ['Review invoice', 'Verify amount', ...]
}

2. Task Manager Skill

File: .claude/skills/task_manager/task_manager.py

Capabilities:

✅ Categorizes files (Document, Image, Data, Code)
✅ Detects special handling requirements
✅ Orchestrates workflow state transitions
✅ Moves files between folders
✅ Enforces Company_Handbook rules

Example:

from task_manager.task_manager import TaskManager

manager = TaskManager(vault_path)
result = manager.process(file_content, metadata)

# Returns:
{
    'category': 'Document',
    'needs_special_handling': False,
    'action': 'File catalogued and organized'
}

How process_items.py Uses Skills

Orchestrator Pattern (NO hardcoded AI logic):

# Import skills
from email_processor.email_processor import EmailProcessor
from task_manager.task_manager import TaskManager

# Initialize
email_processor = EmailProcessor(vault_path)
task_manager = TaskManager(vault_path)

# Delegate based on type
if item_type == 'email':
    logger.info('Delegating to Email Processor Skill')
    result = email_processor.process(content, metadata)
else:
    logger.info('Delegating to Task Manager Skill')
    result = task_manager.process(content, metadata)

# Check approval
if result.get('needs_approval', False):
    move_to(item, '/Pending_Approval')
else:
    move_to(item, '/Done')

Silver Tier: Advanced Agent Skills

3. Research Agent Skill

Uses duckduckgo-search to query real-time web data.
Generates markdown reports stored directly in /Research.

4. Social Media Agent Skill

Drafts LinkedIn posts based on prompts.
Opens the LinkedIn share page in your browser with the draft text, awaiting your ultimate "Post" click.

5. Planner Skill

Breaks down complex requirements into sequenced checkboxes.
Saves multi-step project overviews into /Plans.

🔌 MCP SERVERS (SILVER TIER)

To meet the hackathon requirements for standard Claude Code extensions, Talos features custom Model Context Protocol (MCP) servers.

1. Email MCP Server (scripts/email_mcp.py)

Allows Claude Code to directly trigger Gmail API Drafts.
Operates via Standard IO JSON-RPC bridging flawlessly into the AI tool ecosystem.
Configure using the provided mcp.json.

🔒 SECURITY & PRIVACY

What's Protected

✅ API Keys (.env file):

GEMINI_API_KEY=AIza...  (NEVER in code)

✅ OAuth Tokens:

credentials.json  (Google OAuth)
token.json        (Access token)

✅ Personal Data:

/Inbox/*          (Your files)
/Done/*           (Audit logs)
/Pending_Approval/* (High-value items)

How It's Protected

1. .gitignore:

# Prevents accidental commits
.env
*.env
credentials.json
token.json
Inbox/*
Done/*
Pending_Approval/*

2. Environment Variables:

# Code reads from .env, not hardcoded
load_dotenv()
api_key = os.getenv('GEMINI_API_KEY')

3. Local Storage Only:

All data stays on your PC
No cloud sync by default
You control what syncs (Obsidian settings)

Best Practices

❗ Never commit .env file

# Always in .gitignore
git status  # Should NOT show .env

❗ Rotate API keys if exposed

# If you accidentally commit .env:
1. Immediately revoke key in Google Cloud Console
2. Generate new key
3. Update .env
4. git filter-branch to remove from history

❗ Backup locally, not cloud

# Use local backup, not Dropbox/Google Drive
robocopy AI_Employee_Vault D:\Backups\AI_Employee /MIR

🐛 TROUBLESHOOTING

Issue 1: "ModuleNotFoundError: No module named 'watchdog'"

Solution:

pip install watchdog rich google-api-python-client google-auth-oauthlib python-dotenv

Issue 2: "UnicodeEncodeError" in terminal

Cause: Windows console can't display emojis

Solution: Already fixed in all scripts (emojis removed)

If you see it: Update scripts from latest version

Issue 3: File watcher not detecting drops

Check:

# 1. Is watcher running?
tasklist | findstr python

# 2. Correct folder being watched?
# Open filesystem_watcher.py, check inbox_path

# 3. Restart watcher
# Ctrl+C to stop
python filesystem_watcher.py

Issue 4: Gmail API not working

Check:

# 1. credentials.json exists?
dir scripts\credentials.json

# 2. First run? Need to authenticate
# Browser will open, grant permissions

# 3. token.json created?
dir scripts\token.json

# 4. API enabled in Google Cloud Console?
# Visit: https://console.cloud.google.com/
# APIs & Services > Enable Gmail API

Issue 5: Items not processing

Debug:

# 1. Check logs
notepad Logs\processor.log

# 2. Manually run processor
cd scripts
python process_items.py

# 3. Check for errors
# Look for ERROR lines in output

# 4. Verify .env configuration
notepad .env
# Check VAULT_PATH is correct

❓ FREQUENTLY ASKED QUESTIONS

Q: How does the system detect my approval?

A: Currently (Bronze Tier), you manually move files:

Step-by-step:

AI processes item → Routes to /Pending_Approval
You open /Pending_Approval folder
Review the item (read .md file)
Decision:
- Approve: Drag file to /Approved folder
- Reject: Delete file or move to /Done with rejection note

Platinum Tier (Future):

approval_watcher.py will monitor folder changes
Automatically detect file moved to /Approved
Trigger approval_executor.py for final action

Q: What command triggers final action after approval?

A: Bronze Tier: Manual execution

# After moving file to /Approved:
cd scripts
python approval_executor.py  # (To be created in Platinum Tier)

This script will:

Scan /Approved folder
For each item:
- Execute the approved action (send email, make payment, etc.)
- Create completion record in /Done
- Update Dashboard

Current Status: Not yet implemented (Platinum Tier feature)

Q: Can I use this without Gmail?

A: Yes! File monitoring works standalone.

Disable Gmail:

# Don't run gmail_watcher.py
# Only run:
python filesystem_watcher.py
python orchestrator.py

Q: How do I stop the watchers?

# In each watcher terminal:
Ctrl+C

# OR kill all Python processes:
taskkill /F /IM python.exe  # (WARNING: Kills ALL Python)

# Better: Track PIDs
# Terminal 1: python filesystem_watcher.py → Note PID
# Terminal 2: python gmail_watcher.py → Note PID
# Kill specific: taskkill /PID <pid>

Q: Where are the logs?

/Logs/processor.log      - All processing actions
/Logs/watcher.log        - File detection (if enabled)
/Logs/errors.log         - Failures (if any)
/Logs/DEVELOPMENT_HISTORY.md - Conversation log

Q: Can I customize the AI logic?

A: Yes! Edit the Agent Skills:

Email categorization:

# Edit: .claude/skills/email_processor/email_processor.py

# Add new category
if any(word in content for word in ['webinar', 'training']):
    category = 'Education'

Approval thresholds:

# Edit: .claude/skills/email_processor/email_processor.py

# Change financial threshold
if max_amount > 1000:  # Was 500
    return 'High'

Q: How do I schedule automatic processing?

A: Use Windows Task Scheduler:

Create Task:

Open Task Scheduler
Create Basic Task
Name: "AI Employee Processor"
Trigger: Daily, repeat every 1 hour
Action: Start a program
- Program: python
- Arguments: process_items.py
- Start in: e:\hackton 0\New folder\AI_Employee_Vault\scripts

Q: Is my data uploaded to the cloud?

A: No (by default).

Local only:

All processing happens on your PC
Gemini API: Only sends item metadata for categorization (if implemented)
Gmail API: OAuth tokens stored locally

Obsidian sync (optional):

You choose what to sync
Exclude /Inbox, /Done, /Pending_Approval in Obsidian settings

Q: What are the .md files in Needs_Action?

A: Metadata files created by watchers:

Structure:

---
type: file_drop
original_name: invoice.pdf
file_type: PDF
size_bytes: 125000
detected: 2026-02-17T10:30:00
---

# File Information

**Filename:** invoice.pdf
**Type:** PDF
**Size:** 122.1 KB

## Suggested Actions
- [ ] Extract text for analysis
- [ ] Check for action items

Purpose:

Standardized format for AI processing
Contains metadata for categorization
Tracks original file location
Suggests initial actions

📚 ADDITIONAL RESOURCES

Documentation:

BRONZE_COMPLIANCE_REPORT.md - Full audit report
Company_Handbook.md - Rules and governance
DEVELOPMENT_HISTORY.md - Implementation log
MANUAL_TEST_GUIDE_HINDI.md - Hindi testing guide

Quick References:

FINAL_CHECKLIST.md - Submission checklist
QUICK_START_DEMO.md - Video demo script
PROJECT_SUMMARY.md - Architecture overview

Interactive:

system_walkthrough.py - Guided terminal walkthrough (run this!)

🎯 NEXT STEPS

To Continue Learning:

✅ Run python scripts/system_walkthrough.py - Interactive tutorial
✅ Read Company_Handbook.md - Understand the rules
✅ Experiment with file drops - See it in action
✅ Customize Agent Skills - Make it yours

To Deploy to Production:

✅ Schedule process_items.py (Task Scheduler)
✅ Set up Gmail API (email monitoring)
✅ Configure Obsidian sync (optional)
✅ Monitor Dashboard.md daily

To Upgrade to Platinum Tier:

✅ Implement approval_executor.py
✅ Add MCP integrations (Stripe, WhatsApp, etc.)
✅ Implement Ralph Wiggum loop
✅ Add cloud agent orchestration

🏆 CREDITS & LICENSE

Built for: Personal AI Employee Hackathon
Tier: Bronze (Complete), Platinum (Prepared)
License: MIT
Author: [Your Name]
Date: 2026-02-17

Powered by:

Google Gemini (AI)
Watchdog (Monitoring)
Gmail API (Emails)
Obsidian (Knowledge Base)

Ready to automate your life? Drop a file in /Inbox and watch the magic happen! 🚀