README.md

metadata

title: AI Executive Assistant Simulator
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.13.0
python_version: '3.10'
app_file: ui/app.py
pinned: false

🤖 AI Executive Assistant Simulator

OpenEnv RL Environment — An advanced reinforcement learning environment that simulates a smart executive assistant managing scheduling, inbox communication, and task prioritization.

---

🔷 Problem

Modern professionals struggle with scheduling overload, task prioritization, and communication management. An average executive handles 50+ decisions daily — making this a rich environment for RL agents to learn optimal strategies.

🔷 Solution

An RL-powered executive assistant built on the OpenEnv framework that:

• 📅 Manages schedules with temporal reasoning and overlap detection
• ⚡ Resolves conflicts using conflict graph modeling
• 📬 Handles messages with urgency-aware prioritization
• 🧠 Learns personalized strategies through user preference modeling
• 📈 Improves via curriculum learning from easy → hard scenarios

---

🧠 Advanced Features

Feature	Description
🕐 Temporal Reasoning	Duration-aware time slots with overlap detection
🎯 Multi-Objective Rewards	5 reward components: task, schedule, message, efficiency, preferences
👤 User Preferences	Personalization memory (preferred times, focus hours, meeting limits)
👁️ Partial Observability	Hidden tasks & delayed inbox revealed progressively
🚫 Action Masking	Invalid action prevention — agents only see legal moves
🔗 Conflict Graph	Graph-based modeling of scheduling conflicts
📚 Curriculum Learning	Auto-scaling difficulty: easy → medium → hard
📊 Metrics Tracking	Completion rate, efficiency score, conflict count, response rate
📅 Gantt Timeline	Interactive Plotly visualization of the schedule

---

📁 Project Structure

ai-executive-assistant-openenv/
│
├── openenv.yaml              # OpenEnv environment manifest
├── README.md                 # This file
├── requirements.txt          # Python dependencies
│
├── env/                      # Core environment
│   ├── assistant_env.py      # Main env class (OpenEnv entry point)
│   ├── state.py              # State representation + partial observability
│   ├── actions.py            # Action definitions + action masking
│   ├── rewards.py            # Multi-objective reward engine
│   ├── scheduler.py          # Temporal reasoning + conflict resolution
│   ├── scenario_generator.py # Curriculum-aware scenario generation
│   └── utils.py              # Time utilities, conflict detection, metrics
│
├── agents/                   # Agent implementations
│   ├── random_agent.py       # Random baseline (lower bound)
│   ├── rule_based_agent.py   # Priority heuristic (strong baseline)
│   └── rl_agent.py           # Tabular Q-learning agent
│
├── training/                 # Training & evaluation
│   ├── train_rl.py           # Multi-agent training comparison
│   ├── evaluate.py           # Evaluation harness
│   └── plots.py              # Visualization utilities
│
├── ui/                       # Interactive demo
│   ├── app.py                # Gradio web interface
│   └── timeline.py           # Plotly Gantt timeline
│
└── logs/                     # Training outputs
    ├── reward_curves.png
    ├── agent_comparison.png
    └── rl_metrics.png

---

🚀 Quick Start

Installation

pip install -r requirements.txt

Run Training

python -m training.train_rl

This trains all 3 agents (Random, Rule-Based, Q-Learning) for 200 episodes and generates comparison plots in logs/.

Run Evaluation

python -m training.evaluate

Launch Interactive Demo

python -m ui.app

Then open http://localhost:7860 in your browser.

---

🎮 Environment API

from env.assistant_env import ExecutiveAssistantEnv

env = ExecutiveAssistantEnv(difficulty="medium", max_steps=50)

state = env.reset()
print(state["tasks"])      # List of task objects
print(state["inbox"])       # List of inbox messages
print(state["valid_actions"])  # Legal actions (action masking)

# Take a step
action = ("complete_task", 0)  # Complete task with ID 0
next_state, reward, done, info = env.step(action)

Action Space

Action	Description
schedule_task	Schedule a pending task into a time slot
complete_task	Mark a task as completed
defer_task	Postpone a task to a later time
send_reply	Reply to an inbox message
reject_task	Cancel a task
ask_clarification	Request more info about a task/message

Observation Space

{
  "time": "09:30",
  "tasks": [
    {"id": 0, "title": "Q4 Strategy Review", "time": "10:00",
     "duration": 60, "priority": "high", "type": "meeting", "status": "pending"}
  ],
  "inbox": [
    {"id": 0, "sender": "CEO", "content": "Need figures ASAP",
     "urgency": "high", "replied": false}
  ],
  "preferences": {"preferred_meeting_times": ["09:00", "14:00"], ...},
  "valid_actions": [("complete_task", 0), ("send_reply", 0), ...],
  "action_mask": [1, 1, 1, 1, 1, 1]
}

---

📈 Results

Agent	Avg Reward	Task Completion	Message Response	Efficiency
🎲 Random	Low	~30%	~25%	~25/100
📋 Rule-Based	Medium	~65%	~70%	~55/100
🧠 Q-Learning	High	~75%	~80%	~70/100

Results vary by difficulty and random seed.

---

🏗️ System Architecture

User / RL Agent
       │
       ▼
┌──────────────────────┐
│  ExecutiveAssistantEnv │
│  ┌─────────────────┐ │
│  │ ScenarioGenerator│ │ ← Curriculum Learning
│  └─────┬───────────┘ │
│  ┌─────▼───────────┐ │
│  │     State        │ │ ← Partial Observability
│  │ (tasks + inbox)  │ │
│  └─────┬───────────┘ │
│  ┌─────▼───────────┐ │
│  │   Scheduler      │ │ ← Temporal Reasoning
│  │ (conflict graph) │ │
│  └─────┬───────────┘ │
│  ┌─────▼───────────┐ │
│  │  RewardEngine    │ │ ← Multi-Objective Shaping
│  │ (5 components)   │ │
│  └─────────────────┘ │
│  ┌─────────────────┐ │
│  │  Action Masking  │ │ ← Invalid Action Prevention
│  └─────────────────┘ │
└──────────────────────┘
       │
       ▼
   Observation + Reward + Done

---

📜 License

MIT License

---

🙏 Acknowledgments

• Built for the OpenEnv platform
• Inspired by real-world executive assistant workflows
• Visualization powered by Plotly and Gradio