Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

5.2 KB
Raw Blame
"""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 = ""