Project 4: The Executive Calendar Optimizer (NLP to Action)

Project 4: The Executive Calendar Optimizer (NLP to Action)

Build an assistant that converts natural language scheduling requests into safe, auditable Google Calendar operations using function calling and guardrails.

Quick Reference

Attribute Value
Difficulty Level 3: Advanced
Time Estimate 20–30 hours
Language Python (Alternatives: TypeScript, Swift)
Prerequisites OAuth, REST APIs, JSON schema, basic concurrency, good prompt discipline
Key Topics tool/function calling, idempotency, safety confirmations, planning, constraint solving

1. Learning Objectives

By completing this project, you will:

  1. Implement function calling to bridge LLM “thinking” to API “doing”.
  2. Build safe calendar tools (list/create/update/delete) with audit logs.
  3. Design a planning loop (ReAct-style) that asks clarifying questions and confirms destructive actions.
  4. Encode scheduling constraints (working hours, travel buffers, focus blocks) and resolve conflicts.
  5. Make operations deterministic and reversible (dry-run + diff preview).

2. Theoretical Foundation

2.1 Core Concepts

  • Function calling / tools: The model selects a tool and produces structured args; your code executes the call and returns an observation.
  • Agent loop (Reason → Act → Observe): Multi-step tasks require iterative planning, not single-shot completion.
  • Safety in agents:
    • “Read-only by default”
    • “Explicit confirmation before mutation”
    • “Least privilege tools”
    • “Audit log for every action”
  • Idempotency: Calendar updates must not duplicate or repeatedly move events if a retry happens.
  • Constraint reasoning: Scheduling is a constrained optimization problem (availability, conflicts, priorities, time zones).

2.2 Why This Matters

This is the transition from “chatbot” to “assistant”. If the system can safely modify your calendar, it can safely modify many other systems (tickets, tasks, files) with the same patterns.

2.3 Common Misconceptions

  • “The model should directly call update_event.” It should plan first, and ask clarifying questions when ambiguous.
  • “If tools exist, the model will always use them correctly.” Tool schemas and guardrails determine reliability.
  • “Calendar operations are easy.” Time zones, recurring events, and partial updates create subtle bugs.

3. Project Specification

3.1 What You Will Build

A conversational interface (CLI or web) where users can say:

  • “I’m too busy on Tuesday, move all my morning meetings to the afternoon.”
  • “Find a 45-minute slot for the gym this week, but not after 6pm.”
  • “Block two hours of focus time every weekday morning.”

The assistant:

  • Fetches relevant events
  • Proposes a plan
  • Shows a before/after diff
  • Requests confirmation
  • Applies changes with tool calls

3.2 Functional Requirements

  1. Tools: list_events, create_event, update_event, delete_event, check_availability.
  2. Clarifications: ask when the request is underspecified (which Tuesday? which calendar?).
  3. Dry-run: support a mode that only proposes changes.
  4. Diff preview: show what will change (event IDs, titles, start/end).
  5. Confirmation gates: required for delete and large batch moves.
  6. Safety policies: don’t move meetings with VIP attendees unless confirmed; never delete without explicit user “yes”.

3.3 Non-Functional Requirements

  • Correctness: no accidental duplication; respect recurring event rules.
  • Security: OAuth tokens stored securely; least privileges.
  • Auditability: log each tool call + result (without sensitive tokens).
  • Latency: minimize API calls; cache list_events results during a turn.

3.4 Example Usage / Output

User: Move my 10 AM yoga to 3 PM on Thursday.

Assistant: I found “Yoga Class” on Thu 10:00–11:00. 15:00–16:00 is free.
Assistant: Proposed change:
  - Update evt_abc123: Thu 10:00–11:00 → Thu 15:00–16:00
Confirm? (yes/no)

4. Solution Architecture

4.1 High-Level Design

┌──────────────┐   user msg   ┌────────────────┐   tool call   ┌──────────────┐
│ Chat UI       │────────────▶│ Agent Orchestr. │─────────────▶│ Calendar Tools│
└──────────────┘              │ (plan+policy)   │◀─────────────│ (API wrapper) │
                              └───────┬────────┘   result      └───────┬──────┘
                                      │                                 │
                                      ▼                                 ▼
                              ┌────────────────┐                 ┌──────────────┐
                              │ Diff + Confirm │                 │ Audit Log     │
                              └────────────────┘                 └──────────────┘

4.2 Key Components

Component Responsibility Key Decisions
Calendar client Google Calendar API wrapper strict types, idempotent updates
Tool schemas JSON schemas + descriptions clarity beats cleverness
Policy engine safety constraints explicit confirmations, VIP rules
Planner interpret intent, sequence tools ReAct loop with max steps
Diff engine compute before/after make changes reviewable

4.3 Data Structures

from dataclasses import dataclass

@dataclass(frozen=True)
class CalendarEvent:
    id: str
    title: str
    start_iso: str
    end_iso: str
    attendees: list[str]
    calendar_id: str

@dataclass(frozen=True)
class ProposedChange:
    kind: str  # "update" | "create" | "delete"
    event_id: str | None
    before: CalendarEvent | None
    after: CalendarEvent | None

4.4 Algorithm Overview

Key Algorithm: safe scheduling

  1. Parse intent and extract constraints (date range, time window, duration).
  2. Retrieve candidate events and availability.
  3. Propose a plan and compute diffs.
  4. Ask for confirmation if needed.
  5. Apply changes with idempotent tool calls; record audit log.

Complexity Analysis:

  • Time: O(number_of_API_calls) (dominant)
  • Space: O(number_of_events_in_scope)

5. Implementation Guide

5.1 Development Environment Setup

python -m venv .venv
source .venv/bin/activate
pip install pydantic python-dotenv rich

5.2 Project Structure

calendar-optimizer/
├── src/
│   ├── cli.py
│   ├── agent.py
│   ├── policy.py
│   ├── diff.py
│   ├── tools/
│   │   └── calendar_tools.py
│   └── storage/
│       └── audit_log.sqlite
└── README.md

5.3 Implementation Phases

Phase 1: Read-only assistant (5–7h)

Goals:

  • Authenticate and list events.

Tasks:

  1. Implement list_events and check_availability.
  2. Build a CLI that can answer “What’s on my calendar tomorrow?”

Checkpoint: Read-only queries work reliably with correct time zones.

Phase 2: Write operations + confirmation gates (7–10h)

Goals:

  • Create/update/delete safely.

Tasks:

  1. Implement create_event/update_event/delete_event.
  2. Add diff preview and explicit confirmation.
  3. Add audit logging and idempotency keys for retries.

Checkpoint: You can move a single event with a clear diff and safe confirmation.

Phase 3: Planning + constraints (8–13h)

Goals:

  • Handle multi-step requests and conflicts.

Tasks:

  1. Implement a bounded agent loop (max steps, stop conditions).
  2. Encode user constraints (working hours, buffers, do-not-move tags).
  3. Add clarifying questions for ambiguity.

Checkpoint: Multi-event transformations (e.g., “move morning meetings”) behave predictably.

5.4 Key Implementation Decisions

Decision Options Recommendation Rationale
Confirmation per-event vs batch batch + per-event override safe but not annoying
Recurring events expand instances vs series edits start with instances reduces accidental mass edits
Planner single-shot vs loop bounded loop handles ambiguity and failures

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Unit policy/diff VIP rules, diff formatting, time parsing
Integration calendar tools mock API responses, idempotency retries
Scenario end-to-end “move meeting”, “block focus”, “resolve conflict”

6.2 Critical Test Cases

  1. Time zone correctness: 10am local stays 10am local after update.
  2. Retry safety: repeating an update doesn’t create duplicates.
  3. Confirmation required: delete never happens without explicit “yes”.

7. Common Pitfalls & Debugging

Pitfall Symptom Solution
Time zone drift events shift by hours store time zone explicitly; test in multiple zones
Over-broad scope assistant edits wrong day always confirm date range; show scope summary
Recurrence surprises series changes unexpectedly avoid series edits initially; require confirmation
Tool misuse model calls delete unnecessarily tighten tool descriptions + policy blocks

Debugging strategies:

  • Log the agent plan, tool calls, and final diff.
  • Implement a dry-run mode and use it by default while iterating.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add “busy summary” and weekly heatmap output.
  • Add tagging rules (don’t move “medical”, “1:1” by default).

8.2 Intermediate Extensions

  • Add a simple optimizer (maximize contiguous focus blocks).
  • Add “travel time buffers” between locations.

8.3 Advanced Extensions

  • Integrate tasks (create TODOs for meetings).
  • Add natural language recurring rules (“every other Friday”).

9. Real-World Connections

9.1 Industry Applications

  • Scheduling assistants and meeting coordinators.
  • Operations automation (safe tool use patterns).
  • Calendar analytics for productivity tooling.

9.3 Interview Relevance

  • Function calling patterns, tool schemas, and safety guardrails.
  • Idempotency and audit logs in automation systems.

10. Resources

10.1 Essential Reading

  • Generative AI with LangChain (Ben Auffarth) — tool use patterns (Ch. 4)
  • AI Engineering (Chip Huyen) — agentic workflows and safety (Ch. 6)

10.3 Tools & Documentation

  • Google Calendar API docs (events.list, events.patch)
  • OAuth best practices (token storage, scopes)
  • Previous: Project 3 (email triage) — structured outputs and policy
  • Next: Project 6 (tool routing) — generalized multi-tool assistants

11. Self-Assessment Checklist

  • I can explain function calling and why schemas matter.
  • I can prove an operation is safe (dry-run + diff + confirm).
  • I can explain my idempotency strategy for retries.
  • I can debug a misbehaving agent using tool-call logs.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Read-only chat that can list events and check availability
  • Move a single event safely with confirmation and diff

Full Completion:

  • Multi-step planning with clarifying questions
  • Batch edits with safety policies and audit logs

Excellence (Going Above & Beyond):

  • Constraint-aware optimization (focus time, buffers) with measurable improvements

This guide was generated from project_based_ideas/AI_PERSONAL_ASSISTANTS_MASTERY.md. For the complete sprint overview, see project_based_ideas/AI_PERSONAL_ASSISTANTS_MASTERY/README.md.