AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Pydantic models for the People feature.
A `Person` is a real human (fractional executive, ops manager, bookkeeper,
board chair, or the founding principal) that the Executive can address,
assign work to, wait on, and resume from in Phase 6.
Phase 3 establishes the model, store, registry, and channel helper.
The WaitForHuman workflow primitive and inbound resolver land in Phase 6.
"""
from __future__ import annotations
from datetime import date
from enum import StrEnum
from typing import Literal
from pydantic import BaseModel, Field
class AuthorityScope(StrEnum):
"""Tokens describing what decisions a Person is authorised to approve.
Checked by the authority gate (Phase 4) when a department proposes an
action. A Person with WILDCARD approves anything — typically the principal.
"""
SPEND_LT_2K = "spend_lt_2k"
SPEND_LT_10K = "spend_lt_10k"
SPEND_GT_10K = "spend_gt_10k"
HIRING_SIGNOFF = "hiring_signoff"
VENDOR_ONBOARDING = "vendor_onboarding"
CUSTOMER_CREDIT = "customer_credit"
LEGAL_SIGN = "legal_sign"
BOARD_COMMS = "board_comms"
MEETING_SCHEDULING = "meeting_scheduling"
WILDCARD = "wildcard"
class AvailabilityWindow(BaseModel):
"""A recurring weekly window when a Person can be reached.
Multiple windows can be configured (e.g. "Tue 9-1 PT" + "Thu 2-4 PT").
The channel helper uses these to gate outbound delivery: a message to
a fractional CFO is queued until the next window rather than interrupting.
"""
weekdays: list[int] = Field(
default_factory=list,
description="ISO weekday numbers: 0=Mon … 6=Sun",
)
start_local: str = Field(
description="Window start in local time, HH:MM (24h)",
pattern=r"^\d{2}:\d{2}$",
)
end_local: str = Field(
description="Window end in local time, HH:MM (24h)",
pattern=r"^\d{2}:\d{2}$",
)
timezone: str = Field(
default="UTC",
description="IANA timezone name, e.g. 'America/Los_Angeles'",
)
PreferredChannel = Literal["email", "slack", "telegram", "discord", "any"]
# "team": someone the Executive works with — they can sign in to the web app,
# talk to the bot on Slack / Telegram / Discord, approve things and be chased.
# "contact": someone outside the team (a client, a contractor, an advisor) the
# Executive may email or invite only when the principal asks it to directly.
# Every roster read is team-only unless it opts in (see ``people.store``).
PersonKind = Literal["team", "contact"]
PERSON_KINDS: tuple[str, ...] = ("team", "contact")
# Contact details besides email and the chat apps (``people.contact_info``).
DetailKind = Literal["phone", "mobile", "website", "linkedin", "social", "address"]
DETAIL_KINDS: tuple[str, ...] = ("phone", "mobile", "website", "linkedin", "social", "address")
class ContactDetail(BaseModel):
kind: DetailKind
value: str
class Person(BaseModel):
"""A real human who can receive work, approve actions, and respond.
`is_principal=True` marks the founding user — the fallback approver for
any action when no delegated Person is matched. Exactly one Person should
have `is_principal=True`. The API requires a valid `BACKEND_SHARED_SECRET`
header for all mutations (see api/main.py), so `is_principal` can only be
set by authenticated callers.
`department_slugs` is advisory — it tells the Executive which department
contexts this person participates in. FK enforcement deferred to Phase 4.
`kind` separates the team from contacts (see ``PersonKind``). The
principal is always ``"team"``: the store refuses to write a principal
contact.
"""
id: int | None = None
full_name: str
role: str = ""
is_principal: bool = False
kind: PersonKind = "team"
department_slugs: list[str] = Field(default_factory=list)
email: str | None = None
# Other addresses the same person writes from (``person_emails``). They
# match inbound mail and may be emailed like ``email``, but never sign
# in: web sign-in and caller resolution read ``email`` only.
email_aliases: list[str] = Field(default_factory=list)
slack_user_id: str | None = None
telegram_chat_id: str | None = None
discord_user_id: str | None = None
# How else to reach them (``person_details``), for the reader: never a
# channel the Executive sends on. May be filled in from their own email
# signature (``people.contact_keeper``).
details: list[ContactDetail] = Field(default_factory=list)
preferred_channel: PreferredChannel = "any"
# The chat app they last talked to the Executive in, from their own
# account (``people.reach.note_talked``), and when (ISO, UTC). With
# ``preferred_channel`` "any", messages go there first.
last_channel: str | None = None
# Not serialised: when someone last talked is nobody else's business.
last_channel_at: str | None = Field(default=None, exclude=True)
availability: list[AvailabilityWindow] = Field(default_factory=list)
authority_scope: list[AuthorityScope] = Field(default_factory=list)
response_sla_hours: int = 24
on_leave_until: date | None = None
reports_to_person_id: int | None = None
archived: bool = False
created_at: str = ""
updated_at: str = ""