AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""The solo morning brief's "Top three today", and a slot for each.
Three things to focus on today, picked in code (not by the model) so the pick
is stable and testable, from what the principal owns:
1. their commitments that are overdue, then due today,
2. goals that are off track, then at risk,
3. commitments due later this week,
4. active projects (initiatives), the longest-untouched first.
When the Executive can read a calendar (the MCP gateway is up and the Google
Workspace server is one it runs), one ``get_events`` call lists today's events
on the principal's calendar — their address as the calendar id, read with the
Executive's account, so it works when the principal shared their calendar with
it or signed the Executive in as themselves. When the principal has Act as
me and Read my calendar on, their own calendar is read too, through their own
sign-in (``delegation.calendar``, Gmail or Outlook), and the two are merged
with a meeting on both listed once. On a business day (Monday to
Friday, ``calendar_tools.is_business_day``) each item then gets a free block
inside working hours (``CALENDAR_BUSINESS_HOURS_START`` / ``_END``). Without a
calendar, or at the weekend, there are no slot suggestions (a weekend still
lists the day's events). The read has a short timeout, and any failure (no
gateway, no principal address, an error, a timeout, a reply it cannot read)
reads as "no calendar": the brief never fails because of it. The log carries
only a reply's length or an error's type, never calendar text.
The brief's fingerprint carries the items' keys and only a coarse hash of the
day's calendar (``calendar_hash``: busy blocks rounded to 15 minutes, no
titles, no dates), so an unchanged day still suppresses.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import re
from dataclasses import dataclass
from datetime import UTC, date, datetime, time, timedelta, tzinfo
from typing import Any
logger = logging.getLogger(__name__)
TOP_THREE_MAX = 3
CALENDAR_TOOL = "google_workspace__get_events"
CALENDAR_TIMEOUT_SECONDS = 4.0
# Most events listed in the brief's calendar block (and read from the tool).
_MAX_EVENTS = 12
_TITLE_MAX = 80
# A suggested block: an hour when the gap allows, never under half an hour.
_BLOCK = timedelta(minutes=60)
_MIN_BLOCK = timedelta(minutes=30)
_DEFAULT_WORK_START = time(9, 0)
_DEFAULT_WORK_END = time(18, 0)
# Ranking tiers (lower first).
_TIER_OVERDUE = 0
_TIER_DUE_TODAY = 1
_TIER_OFF_TRACK = 2
_TIER_AT_RISK = 3
_TIER_DUE_SOON = 4
_TIER_PROJECT = 5
@dataclass(frozen=True)
class CalendarEvent:
title: str
# Aware datetimes for a timed event (equal for a zero-length one); None
# for an all-day event.
start: datetime | None
end: datetime | None
# Only an event given as a date (no time) is all day.
all_day: bool = False
# --------------------------------------------------------------------------- #
# Picking the three
# --------------------------------------------------------------------------- #
def _clean(text: object, limit: int = 160) -> str:
return " ".join(str(text or "").split())[:limit]
def focus_candidates(
*,
due_soon: list[dict[str, Any]],
goals: list[dict[str, Any]],
projects: list[dict[str, Any]],
now: datetime,
) -> list[dict[str, Any]]:
"""Every candidate, ranked. Each is ``{key, kind, text, why, tier}``.
``due_soon``: ``open_loops.principal_due_soon`` rows. ``goals``: dicts with
``id``, ``area``, ``key_result``, ``target``, ``current``, ``status``.
``projects``: dicts with ``id``, ``title``, ``updated_at``. ``key`` holds
no date, so it can go into a fingerprint.
"""
out: list[dict[str, Any]] = []
for d in due_soon:
state = str(d.get("state", ""))
raw = str(d.get("due_date", ""))[:10]
if state == "overdue":
tier, why = _TIER_OVERDUE, f"overdue (was due {raw})"
elif state == "today":
tier, why = _TIER_DUE_TODAY, "due today"
else:
tier, why = _TIER_DUE_SOON, f"due {raw}"
out.append({
"key": f"loop:{int(d.get('loop_id') or 0)}:{state}",
"kind": "commitment",
"text": _clean(d.get("description")),
"why": why,
"tier": tier,
"order": str(d.get("due_at") or raw),
})
for g in goals:
status = str(g.get("status", ""))
if status not in ("off_track", "at_risk"):
continue
current = _clean(g.get("current"), 80)
why = f"{status.replace('_', ' ')}; target {_clean(g.get('target'), 80)}"
if current:
why += f", now {current}"
out.append({
"key": f"goal:{int(g.get('id') or 0)}:{status}",
"kind": "goal",
"text": f"{_clean(g.get('area'), 60)}: {_clean(g.get('key_result'))}",
"why": why,
"tier": _TIER_OFF_TRACK if status == "off_track" else _TIER_AT_RISK,
"order": "",
})
for p in projects:
updated = _parse(p.get("updated_at"))
days = max(0, (now - updated).days) if updated is not None else None
why = "active project" if days is None else f"active project, last updated {days}d ago"
out.append({
"key": f"project:{int(p.get('id') or 0)}",
"kind": "project",
"text": _clean(p.get("title")),
"why": why,
"tier": _TIER_PROJECT,
# Longest-untouched first; unknown last.
"order": updated.isoformat() if updated is not None else "~",
})
out.sort(key=lambda c: (c["tier"], c["order"]))
return out
def pick_top_three(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""The first three distinct candidates, without the ranking fields."""
picked: list[dict[str, Any]] = []
seen: set[str] = set()
for c in candidates:
if c["key"] in seen or not c["text"]:
continue
seen.add(c["key"])
picked.append({k: c[k] for k in ("key", "kind", "text", "why")})
if len(picked) >= TOP_THREE_MAX:
break
return picked
def gather_goals_and_projects() -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
"""Goals at risk (by area) and active projects from the stores. A read
failure is logged and reads as empty."""
goals: list[dict[str, Any]] = []
projects: list[dict[str, Any]] = []
try:
from openexecutive.departments import registry as dept_registry
for state in dept_registry.list_states():
for g in state.goals:
if g.status in ("off_track", "at_risk"):
goals.append({
"id": g.id, "area": state.config.title, "key_result": g.key_result,
"target": g.target, "current": g.current, "status": g.status,
})
except Exception:
logger.warning("top_three: goals unreadable", exc_info=True)
try:
from openexecutive.memory.episodic import _resolve_db_path, get_active_initiatives
for i in get_active_initiatives(db_path=_resolve_db_path(None)):
if i.status == "active":
projects.append({"id": i.id, "title": i.title, "updated_at": i.updated_at})
except Exception:
logger.warning("top_three: projects unreadable", exc_info=True)
return goals, projects
# --------------------------------------------------------------------------- #
# Reading today's calendar (one call, short timeout, never raises)
# --------------------------------------------------------------------------- #
def _parse(raw: object) -> datetime | None:
if not raw:
return None
try:
dt = datetime.fromisoformat(str(raw))
except ValueError:
return None
return dt if dt.tzinfo else dt.replace(tzinfo=UTC)
def _as_date(raw: object) -> tuple[str, datetime | None]:
try:
date.fromisoformat(str(raw).strip())
except ValueError:
return "bad", None
return "date", None
def _as_datetime(raw: object, tz: tzinfo) -> tuple[str, datetime | None]:
try:
dt = datetime.fromisoformat(str(raw).strip())
except ValueError:
return "bad", None
return "datetime", dt if dt.tzinfo else dt.replace(tzinfo=tz)
def _event_time(raw: object, tz: tzinfo) -> tuple[str, datetime | None]:
"""How an event's start or end is given: ``("date", None)`` for a date
with no time (Google's all-day form), ``("datetime", aware)`` for a time,
``("missing", None)`` when absent, ``("bad", None)`` when unreadable."""
if isinstance(raw, dict):
# The API's form: ``dateTime`` for a timed event, ``date`` alone for
# an all-day one.
timed = raw.get("dateTime") or raw.get("date_time")
if timed:
return _as_datetime(timed, tz)
day = raw.get("date")
return _as_date(day) if day else ("missing", None)
text = str(raw or "").strip()
if not text:
return "missing", None
if len(text) == 10: # the text listing prints an all-day event's date alone
return _as_date(text)
return _as_datetime(text, tz)
def _event(title: object, start: object, end: object, tz: tzinfo) -> CalendarEvent | None:
"""One event, or None when its times cannot be read (it is then left out
of the listing, the busy time and the all-day count). Only a date-only
start makes it all day; a zero-length timed event is timed and blocks
nothing."""
name = _clean(title, _TITLE_MAX) or "(untitled)"
s_kind, s = _event_time(start, tz)
e_kind, e = _event_time(end, tz)
if s_kind == "date" and e_kind in ("date", "missing"):
return CalendarEvent(title=name, start=None, end=None, all_day=True)
if s is not None and e is not None and e >= s:
return CalendarEvent(title=name, start=s, end=e)
return None
# workspace-mcp's text listing: `- "Title" (Starts: <iso>, Ends: <iso>) ID: …`
_LINE_RE = re.compile(r'^\s*-\s*"(?P<title>.*)"\s*\(Starts:\s*(?P<start>[^,]+),\s*Ends:\s*(?P<end>[^)]+)\)')
_EMPTY_RE = re.compile(r"^\s*No events found", re.IGNORECASE | re.MULTILINE)
_LISTED_RE = re.compile(r"^\s*Successfully retrieved \d+ events?", re.IGNORECASE | re.MULTILINE)
def parse_events(text: str, tz: tzinfo) -> list[CalendarEvent] | None:
"""Events from a ``get_events`` reply, [] for an empty day, or None when
the reply is an error or a shape this does not know — read as "no
calendar", never as a free day. An event whose times cannot be read is
left out; a reply that lists events but none readable is None too."""
from openexecutive.workflows.action_step import looks_like_error
if not isinstance(text, str) or not text.strip() or looks_like_error(text):
return None
try:
parsed: Any = json.loads(text)
except ValueError:
parsed = None
if parsed is not None:
items = parsed.get("events", parsed.get("items")) if isinstance(parsed, dict) else parsed
if not isinstance(items, list):
return None
listed = [
_event(i.get("summary") or i.get("title"), i.get("start"), i.get("end"), tz)
for i in items[:_MAX_EVENTS]
if isinstance(i, dict)
]
else:
if _EMPTY_RE.search(text):
return []
matches = [
m for m in (_LINE_RE.match(line) for line in text.splitlines()) if m is not None
]
if not matches and not _LISTED_RE.search(text):
return None
listed = [
_event(m["title"], m["start"].strip(), m["end"].strip(), tz)
for m in matches[:_MAX_EVENTS]
]
events = [ev for ev in listed if ev is not None]
return None if listed and not events else events
def _calendar_id(principal_email: str) -> str:
"""The principal's calendar: "primary" when the Executive is signed in as
the principal, else their address (a calendar they shared with it)."""
try:
from openexecutive.config import get_settings
own = (get_settings().exec_email_address or "").strip().lower()
except Exception:
own = ""
return "primary" if own and own == principal_email.strip().lower() else principal_email
async def read_todays_calendar(
now: datetime, tz: tzinfo, *, include_own: bool = True
) -> list[CalendarEvent] | None:
"""Today's events on the principal's calendars, or None when there is no
calendar to read: the one the Executive reads with its own account
(:func:`_read_executive_calendar`) and, with ``include_own``, the
principal's own calendar under Read my calendar
(:func:`_read_own_calendar`). The two are read at once, each with a short
timeout, and merged: an event on both (a calendar shared with the
Executive is the same calendar) is listed once. None only when neither
could be read. Never raises."""
reads = [_read_executive_calendar(now, tz)]
if include_own:
reads.append(_read_own_calendar(now, tz))
found = await asyncio.gather(*reads)
if all(events is None for events in found):
return None
return merge_events(*(events or [] for events in found))
def merge_events(*sources: list[CalendarEvent]) -> list[CalendarEvent]:
"""The events of every source in order, each listed once: the same title
at the same times on two calendars is one meeting."""
seen: set[tuple[str, datetime | None, datetime | None, bool]] = set()
merged: list[CalendarEvent] = []
for events in sources:
for event in events:
key = (event.title.strip().casefold(), event.start, event.end, event.all_day)
if key in seen:
continue
seen.add(key)
merged.append(event)
return merged
async def _read_own_calendar(now: datetime, tz: tzinfo) -> list[CalendarEvent] | None:
"""Today's events on the principal's own calendar, read through their
own sign-in (``delegation.calendar``, Gmail or Outlook), or None unless
they have Act as me and Read my calendar on and their mailbox opens as
theirs. Events they declined are left out. Never raises."""
try:
from openexecutive.delegation import calendar
from openexecutive.delegation import settings as delegation_settings
from openexecutive.delegation.gmail import gmail_for, gmail_status
from openexecutive.people.store import find_principal_person
principal = await asyncio.to_thread(find_principal_person)
if principal is None or principal.id is None or not principal.email:
return None
if not (delegation_settings.can_delegate(principal) and delegation_settings.is_enabled(principal.id)):
return None
if not await asyncio.to_thread(calendar.enabled, principal.id):
return None
mailbox = gmail_for(principal.email)
if await gmail_status(principal.email, gmail=mailbox) != "connected":
return None
local_day = now.astimezone(tz).date()
start = datetime(local_day.year, local_day.month, local_day.day, tzinfo=tz)
raw = await asyncio.wait_for(
calendar.events_for(mailbox, start, start + timedelta(days=1), max_results=_MAX_EVENTS * 2),
timeout=CALENDAR_TIMEOUT_SECONDS,
)
except Exception as exc:
# The type only, as for the Executive's read.
logger.info("top_three: own calendar unavailable for the brief (%s)", type(exc).__name__)
return None
events: list[CalendarEvent] = []
for item in raw:
if getattr(item, "response", "") == "declined":
continue
if getattr(item, "all_day", False):
title = _clean(getattr(item, "title", ""), _TITLE_MAX) or "(untitled)"
events.append(CalendarEvent(title=title, start=None, end=None, all_day=True))
continue
event = _event(getattr(item, "title", ""), getattr(item, "start", ""), getattr(item, "end", ""), tz)
if event is not None:
events.append(event)
return events[:_MAX_EVENTS]
async def _read_executive_calendar(now: datetime, tz: tzinfo) -> list[CalendarEvent] | None:
"""Today's events on the principal's calendar as the Executive's own
account reads it, or None when there is none to read. One tool call
with a short timeout; never raises."""
try:
from openexecutive.config import get_settings
from openexecutive.integrations.workspace.registry import get_calendar_provider
from openexecutive.orchestrator.mcp_gateway import get_active_gateway
from openexecutive.people.store import find_principal_person
from openexecutive.scheduler.runner import google_workspace_ready
# The listing below is Google Calendar's; on Outlook the brief goes
# without a calendar block, as when no calendar is connected.
if get_calendar_provider().name != "google" or not google_workspace_ready():
return None
gateway = get_active_gateway()
principal = find_principal_person()
email = (principal.email or "").strip() if principal is not None else ""
if gateway is None or not email:
return None
local_day = now.astimezone(tz).date()
start = datetime(local_day.year, local_day.month, local_day.day, tzinfo=tz)
end = start + timedelta(days=1)
raw = await asyncio.wait_for(
gateway.call_tool({
"name": CALENDAR_TOOL,
"arguments": {
"user_google_email": get_settings().exec_email_address,
"calendar_id": _calendar_id(email),
"time_min": start.astimezone(UTC).isoformat(),
"time_max": end.astimezone(UTC).isoformat(),
"max_results": _MAX_EVENTS,
},
}),
timeout=CALENDAR_TIMEOUT_SECONDS,
)
except Exception as exc:
# TimeoutError included: a slow calendar never holds the brief up.
# The type only — a calendar error can carry event text or addresses.
logger.info("top_three: calendar unavailable for the brief (%s)", type(exc).__name__)
return None
events = parse_events(raw, tz)
if events is None:
# Never the reply itself: it holds the principal's event titles.
logger.info("top_three: calendar reply not readable (%d chars)", len(str(raw)))
return events
# --------------------------------------------------------------------------- #
# Free slots
# --------------------------------------------------------------------------- #
def _hhmm(raw: str, default: time) -> time:
try:
hh, mm = str(raw).strip().split(":", 1)
return time(int(hh), int(mm))
except (ValueError, TypeError):
return default
def working_hours() -> tuple[time, time]:
"""The calendar business hours setting, 09:00–18:00 when unreadable."""
try:
from openexecutive.config import get_settings
s = get_settings()
start = _hhmm(s.calendar_business_hours_start, _DEFAULT_WORK_START)
end = _hhmm(s.calendar_business_hours_end, _DEFAULT_WORK_END)
except Exception:
return _DEFAULT_WORK_START, _DEFAULT_WORK_END
return (start, end) if start < end else (_DEFAULT_WORK_START, _DEFAULT_WORK_END)
def free_gaps(
events: list[CalendarEvent],
*,
now: datetime,
tz: tzinfo,
work: tuple[time, time],
) -> list[tuple[datetime, datetime]]:
"""Free stretches of at least half an hour left today inside working
hours, in order. None on a weekend — the calendar tools' business-day
rule (``calendar_tools.is_business_day``), which also refuses to book
then. All-day and zero-length events do not block time."""
from openexecutive.orchestrator.calendar_tools import is_business_day
day = now.astimezone(tz).date()
if not is_business_day(day):
return []
window_start = datetime.combine(day, work[0], tzinfo=tz)
window_end = datetime.combine(day, work[1], tzinfo=tz)
# Not before now, rounded up to the next quarter hour.
local_now = now.astimezone(tz)
rounded = local_now.replace(second=0, microsecond=0)
rounded += timedelta(minutes=(-rounded.minute) % 15)
if rounded < local_now:
rounded += timedelta(minutes=15)
cursor = max(window_start, rounded)
busy = sorted(
(e.start, e.end) for e in events
if e.start is not None and e.end is not None and e.end > e.start
)
gaps: list[tuple[datetime, datetime]] = []
for b_start, b_end in busy:
if b_end <= cursor:
continue
if b_start >= window_end:
break
if b_start - cursor >= _MIN_BLOCK:
gaps.append((cursor, b_start))
cursor = max(cursor, b_end)
if window_end - cursor >= _MIN_BLOCK:
gaps.append((cursor, window_end))
return gaps
def assign_slots(
items: list[dict[str, Any]], gaps: list[tuple[datetime, datetime]], tz: tzinfo
) -> list[dict[str, Any]]:
"""Copies of ``items``, each with ``slot`` — "10:30–11:30" (local), or ""
when no free block is left for it."""
out: list[dict[str, Any]] = []
queue = list(gaps)
for item in items:
slot = ""
while queue:
g_start, g_end = queue[0]
end = min(g_start + _BLOCK, g_end)
if end - g_start < _MIN_BLOCK:
queue.pop(0)
continue
slot = f"{g_start.astimezone(tz):%H:%M}–{end.astimezone(tz):%H:%M}"
queue[0] = (end, g_end)
break
out.append({**item, "slot": slot})
return out
def calendar_hash(events: list[CalendarEvent], tz: tzinfo) -> str:
"""A coarse hash of the day: busy blocks rounded down to 15 minutes, and
how many all-day events. No titles and no dates, so the same shape of day
hashes the same and an unchanged day still suppresses the brief."""
def _q(dt: datetime) -> str:
local = dt.astimezone(tz)
return f"{local.hour:02d}:{local.minute // 15 * 15:02d}"
blocks = sorted(
f"{_q(e.start)}-{_q(e.end)}" for e in events
if e.start is not None and e.end is not None and e.end > e.start
)
all_day = sum(1 for e in events if e.all_day)
blob = json.dumps({"blocks": blocks, "all_day": all_day}, sort_keys=True)
return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
def render_events(events: list[CalendarEvent], tz: tzinfo) -> list[dict[str, str]]:
"""``[{time, title}]`` for the brief: all-day first, then by start."""
rows = [{"time": "all day", "title": e.title} for e in events if e.all_day]
timed = sorted(
(e.start, e.end, e.title) for e in events if e.start is not None and e.end is not None
)
for start, end, title in timed:
when = f"{start.astimezone(tz):%H:%M}"
if end > start:
when += f"–{end.astimezone(tz):%H:%M}"
rows.append({"time": when, "title": title})
return rows
# --------------------------------------------------------------------------- #
# Entry point for the morning brief
# --------------------------------------------------------------------------- #
async def build_top_three(
due_soon: list[dict[str, Any]], *, now: datetime | None = None, include_own: bool = True
) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
"""``(items, calendar)`` for the solo morning brief. Never raises.
``items``: up to three ``{key, kind, text, why, slot}`` — ``slot`` is set
only when a calendar was read on a business day. ``calendar``:
``{"events": [...], "hash": str}`` when one was read (at the weekend
too), else None. The calendar is read only when there is something to
place. ``include_own`` adds the principal's own calendar (Read my
calendar) to the read: only on a delivery to them alone.
"""
try:
from openexecutive.memory.workspace_settings import get_user_timezone
now = now or datetime.now(UTC)
tz = get_user_timezone()
goals, projects = gather_goals_and_projects()
items = pick_top_three(
focus_candidates(due_soon=due_soon, goals=goals, projects=projects, now=now)
)
except Exception:
logger.exception("top_three: picking failed — the brief goes without it")
return [], None
if not items:
return [], None
events = await read_todays_calendar(now, tz, include_own=include_own)
if events is None:
return items, None
try:
from openexecutive.orchestrator.calendar_tools import is_business_day
# No slot suggestions on a weekend (the calendar tools will not book
# one then either); the day's events are still listed.
if is_business_day(now.astimezone(tz).date()):
items = assign_slots(
items, free_gaps(events, now=now, tz=tz, work=working_hours()), tz
)
calendar = {"events": render_events(events, tz), "hash": calendar_hash(events, tz)}
except Exception:
logger.exception("top_three: slot planning failed — no slots in this brief")
return items, None
return items, calendar
__all__ = [
"merge_events",
"CALENDAR_TIMEOUT_SECONDS",
"CALENDAR_TOOL",
"TOP_THREE_MAX",
"CalendarEvent",
"assign_slots",
"build_top_three",
"calendar_hash",
"focus_candidates",
"free_gaps",
"gather_goals_and_projects",
"parse_events",
"pick_top_three",
"read_todays_calendar",
"render_events",
"working_hours",
]