AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
from __future__ import annotations
from enum import StrEnum
from pydantic import BaseModel, ConfigDict, Field
# Topic tag on an alert only the principal may see: one raised on a turn
# about mail from one of their contacts or mail they forwarded, or a meeting
# proposal with a contact. Every surface that serves anyone else — /today for
# a teammate, a teammate's chat digest, the alert review, the activity rail,
# the unattended reflection — leaves it out (see ``is_private_alert``). A
# namespaced token, so no tag the triage model invents can collide with it.
PRIVATE_ALERT_TAG = "private:principal"
def is_private_alert(alert: object) -> bool:
"""Whether ``alert`` (an Alert, ProposalItem or anything with
``topic_tags``) is private to the principal."""
tags = getattr(alert, "topic_tags", None) or []
return any(str(t).lower() == PRIVATE_ALERT_TAG for t in tags)
# Source of a document the Executive published (`draft_artifact`). Each one
# is its owner's alone (``owner_person_id``; none = the principal's): it never
# reaches a surface that serves anyone else (see ``artifact_visible_to``).
ARTIFACT_SOURCE = "artifact"
def artifact_visible_to(
owner_person_id: int | None, person_id: int | None, *, is_principal: bool
) -> bool:
"""Whether the person ``person_id`` (``is_principal`` when they are the
principal) may see a drafted artifact owned by ``owner_person_id``. Not
even the principal sees a teammate's."""
if owner_person_id is None:
return is_principal
return person_id is not None and person_id == owner_person_id
def visible_alert(alert: object, viewer: object | None) -> bool:
"""Whether ``alert`` may be shown to ``viewer`` (anything with
``person_id`` and ``is_principal``, e.g. ``artifact_records.Viewer``).
Every alert but a drafted artifact may; an artifact only to its owner,
and to no one when there is no viewer (a surface shared by everyone)."""
if getattr(alert, "source", None) != ARTIFACT_SOURCE:
return True
if viewer is None:
return False
return artifact_visible_to(
getattr(alert, "owner_person_id", None),
getattr(viewer, "person_id", None),
is_principal=bool(getattr(viewer, "is_principal", False)),
)
class AlertSeverity(StrEnum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
URGENT = "urgent"
SEVERITY_RANK: dict[str, int] = {
AlertSeverity.LOW.value: 0,
AlertSeverity.MEDIUM.value: 1,
AlertSeverity.HIGH.value: 2,
AlertSeverity.URGENT.value: 3,
}
class AlertChannel(StrEnum):
WEB = "web"
SLACK_DM = "slack_dm"
EMAIL = "email"
PERSISTED = "persisted"
# Shift 3 — broadcast channels. The triage agent picks these when the
# alert is dept-scoped (no single human owner) or company-wide. The
# dispatcher reads the accompanying TriageDecision.department_slug /
# broadcast_integration fields to know which room to post to.
DEPARTMENT_CHANNEL = "department_channel"
COMPANY_BROADCAST = "company_broadcast"
class AlertEvent(BaseModel):
"""An external event that may or may not become an alert."""
model_config = ConfigDict(extra="ignore")
source: str # "email" | "slack" | "document"
external_id: str # source-system id for idempotency
subject: str = ""
body: str = ""
from_: str | None = Field(default=None, alias="from")
channel: str | None = None
user: str | None = None
title: str | None = None # for documents
# Producer-supplied dedup key that overrides the triage model's own
# (monitoring sets ``watch:<slug>`` so one watch = one open alert).
dedup_hint: str = ""
# Person the alert should be routed to (assigned_to_person_id from the
# Executive's create_alert tool). Lands on the row so the "principal
# owns unrouted" rule stops sweeping every triage-born alert to them.
routed_to_person_id: int | None = None
# Department the alert belongs to (slug). Becomes the row's
# ``department:<slug>`` topic tag — a routing hint only, unlike
# ``channel``, which triage reads as the room a message came from and may
# answer with a team-room broadcast.
department: str = ""
# Private to the principal (see PRIVATE_ALERT_TAG): the pipeline tags it,
# routes it to the principal, keeps it out of every broadcast and live
# push, and never coalesces it into a card someone else can see.
private: bool = False
# Set only by the create_alert tool on a team member's chat turn: who
# raised it, for its "Raised by <name>" label. Such an alert keeps a
# source and id the server picked (``TEAM_RAISED_SOURCE``), whatever the
# turn asked, and never goes out as a company-wide broadcast — a person
# or department only (alerts/pipeline.py).
raised_by: str = ""
# The source of every alert a team member raises from chat (see
# ``AlertEvent.raised_by``): never "email" or a watch, so it can't pose as
# one, coalesce into one, or claim the id a real one will arrive with.
TEAM_RAISED_SOURCE = "team_member"
class TriageDecision(BaseModel):
"""Structured output of the Triage agent."""
model_config = ConfigDict(extra="ignore")
alert: bool
severity: AlertSeverity = AlertSeverity.LOW
channels: list[AlertChannel] = Field(default_factory=list)
headline: str = ""
body: str = ""
suggested_action: str = ""
topic_tags: list[str] = Field(default_factory=list)
dedup_key: str = ""
reason_if_suppressed: str = ""
# Shift 3 broadcast routing. Set when `channels` contains
# DEPARTMENT_CHANNEL or COMPANY_BROADCAST so the dispatcher knows
# WHERE to post. Empty strings when the alert is per-person or
# web-only — those channels never read these fields.
department_slug: str = ""
broadcast_integration: str = ""
class Alert(BaseModel):
"""A persisted alert row."""
model_config = ConfigDict(extra="ignore")
id: int | None = None
external_id: str = ""
source: str
severity: str
headline: str
body: str
suggested_action: str = ""
topic_tags: list[str] = Field(default_factory=list)
channels_attempted: list[str] = Field(default_factory=list)
channels_delivered: list[str] = Field(default_factory=list)
dedup_key: str = ""
# unread | read | ack | dismissed | resolved | expired. `ack` means the
# user approved (the Executive executes the suggested action);
# `resolved` means the Executive's review closed it with evidence;
# `expired` means the lifecycle sweep aged it out (alerts/lifecycle.py).
status: str = "unread"
created_at: str
# Phase 4: person the alert is routed to for approval. NULL means the
# alert is general (not routed to a specific approver).
routed_to_person_id: int | None = None
# Soft-delete for the Executive Artifacts gallery. NULL = active; an ISO
# timestamp means the artifact was archived (hidden from the default list
# but restorable). Only meaningful for source='artifact' rows.
archived_at: str | None = None
# Lifecycle (alerts/lifecycle.py + alerts/review.py). All additive with
# defaults so rows written by older builds read back unchanged.
# Coalescing: a repeat of an open alert bumps these instead of stacking.
last_seen_at: str | None = None
occurrence_count: int = 1
# Executive review verdict: '' | relevant | changed | likely_stale |
# drafted | routed | merged, plus resolved | stale on rows the review
# closed; `review_note` is the one-line "what changed since
# you last looked"; `recommended_move` the next move the card leads with;
# `why_now` a short urgency note; `due_at` an ISO deadline when one exists.
last_reviewed_at: str | None = None
review_verdict: str = ""
review_note: str = ""
recommended_move: str = ""
why_now: str = ""
due_at: str | None = None
# Set on a row folded into another (merge): the surviving alert's id.
superseded_by_alert_id: int | None = None
# Hidden from the live queue until this ISO timestamp (snooze).
snoozed_until: str | None = None
# Registry workflow the review suggested as the next step ('' = none).
suggested_workflow: str = ""
# Artifact format + link metadata (source='artifact' rows only; see
# orchestrator/artifact_formats.py). Legacy rows read back as Markdown.
artifact_format: str = "markdown"
artifact_url: str | None = None
artifact_link_label: str | None = None
# Composite id ('alert:<n>' / 'run:<hex>') of the version this revised.
supersedes_id: str | None = None
# Whose document a drafted artifact is (orchestrator/artifact_records.py);
# NULL on a draft = the principal's. Unused on every other source.
owner_person_id: int | None = None
class UserPreferences(BaseModel):
model_config = ConfigDict(extra="ignore")
severity_threshold: AlertSeverity = AlertSeverity.MEDIUM
quiet_hours_start: str = "" # "22:00"
quiet_hours_end: str = "" # "07:00"
# IANA zone the quiet hours are read in. "UTC" (the historical default,
# and the column DEFAULT) and "" both mean "the user's zone" — see
# alerts.preferences._quiet_hours_zone.
quiet_hours_tz: str = "UTC"
channels_enabled: list[AlertChannel] = Field(
default_factory=lambda: [
AlertChannel.WEB,
AlertChannel.SLACK_DM,
AlertChannel.EMAIL,
AlertChannel.PERSISTED,
]
)
class MuteTopic(BaseModel):
model_config = ConfigDict(extra="ignore")
id: int | None = None
pattern: str
created_at: str