Skip to content

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

8.6 KB
Raw Blame
"""Who reads a brief, and keeping them "you" in it.

Every brief surface (the /today header, the morning brief, the end-of-day
digest) is written for one person, but its inputs name that person like
anyone else: their own chat ("Inbound google_chat from <their name>"), the
Executive's replies to their address, a chat titled with their name, the
activity log. A model handed those lines wrote about its reader in the third
person ("<their name> has been messaging you nonstop").

So the reader is fixed in code, not left to the model:

  • ``mask`` rewrites the reader's full name and email addresses in the
    rendered context to "the reader", so no input line names them;
  • ``reader_line`` heads the context with who that is;
  • ``slips`` finds the name, an address, "the reader" or "the principal" in
    what the model wrote, and ``fix_slips`` turns any left after one retry
    into "you" / "your".
"""
from __future__ import annotations

import logging
import re
from dataclasses import dataclass
from typing import Any

logger = logging.getLogger(__name__)

READER = "the reader"

# What the model must never write about its reader: the context's own label
# for them. "The principal" is never written for anyone: it is the reader on
# the owner's own brief and the owner by name on a teammate's.
_READER_LABELS = ("the reader",)
_OWNER_LABEL = "the principal"
# The Executive writes every brief, so it is "I" / "me" / "my" in it.
# Not a title ("the Executive Director") or a noun phrase ("the Executive
# team"), where "I" would not read.
_EXECUTIVE = re.compile(
    r"\b[Tt]he Executive(['’]s)?\b(?! [A-Z])(?! (?:team|teams|office|offices|committee|"
    r"board|role|roles|suite|level|summary|summaries|session|sessions|assistant|"
    r"function|branch|order|orders|member|members|leadership|staff)\b)"
)
# Words after which the Executive is the object: "emailed the Executive" → "me".
_OBJECT_BEFORE = re.compile(
    r"(?:\b(?:to|from|with|for|by|of|on|at|about|than|asked|told|emailed|"
    r"messaged|pinged|sent|gave|asking|telling|messaging|emailing|pinging))\s*$",
    re.IGNORECASE,
)


@dataclass(frozen=True)
class Reader:
    """The person a brief is written for."""

    name: str
    emails: tuple[str, ...] = ()
    # The owner's name when the reader is a teammate (None: the reader is
    # the owner), for "the principal" in a teammate's brief.
    owner: str | None = None

    def terms(self) -> list[str]:
        """The reader's full name and addresses, longest first. A bare first
        name is left out: on a team it names someone else just as often."""
        name = " ".join(self.name.split())
        found = [name] if len(name.split()) > 1 else []
        found += [e.strip().lower() for e in self.emails if e and "@" in e]
        return sorted(set(found), key=len, reverse=True)


def _from_person(person: Any) -> Reader | None:
    if person is None or not (person.full_name or "").strip():
        return None
    return Reader(
        name=person.full_name,
        emails=tuple(a for a in [person.email or "", *person.email_aliases] if a),
    )


def principal_reader() -> Reader | None:
    """The principal as a Reader, or None (also on a failed lookup)."""
    from openexecutive.people.store import find_principal_person

    try:
        return _from_person(find_principal_person())
    except Exception:
        logger.exception("reader: principal lookup failed")
        return None


def person_reader(person_id: int) -> Reader | None:
    """A teammate as a Reader, or None (also on a failed lookup)."""
    from openexecutive.people.store import get_person

    try:
        reader = _from_person(get_person(person_id))
    except Exception:
        logger.exception("reader: person lookup failed")
        return None
    owner = principal_reader()
    if reader is None or owner is None:
        return reader
    return Reader(name=reader.name, emails=reader.emails, owner=owner.name)


def _pattern(terms: list[str]) -> re.Pattern[str] | None:
    if not terms:
        return None
    alts = "|".join(re.escape(t) for t in terms)
    # Whole words only, and the possessive with it: "<name>'s" → "the reader's".
    return re.compile(rf"(?<![\w@.])(?:{alts})(?![\w@])", re.IGNORECASE)


def reader_line(reader: Reader) -> str:
    """THE READER line: who "the reader" in the context is."""
    from openexecutive.briefing.live_signals import _one_line

    also = ", ".join(e for e in reader.terms() if "@" in e)
    who = _one_line(reader.name, 80) + (f" ({_one_line(also, 160)})" if also else "")
    return (
        f"THE READER (the person this is written for; every line below that "
        f"says 'the reader' means them): {who}\n"
    )


def mask(text: str, reader: Reader | None) -> str:
    """``text`` with the reader's full name and addresses as "the reader"."""
    if reader is None:
        return text
    pattern = _pattern(reader.terms())
    return pattern.sub(READER, text) if pattern else text


def slips(text: str, reader: Reader | None) -> list[str]:
    """The ways ``text`` names its reader instead of saying "you", or calls
    anyone "the principal", or the Executive instead of saying "I"."""
    if reader is None:
        return []
    pattern = _pattern([*reader.terms(), *_READER_LABELS, _OWNER_LABEL])
    found = {m.group(0).lower() for m in pattern.finditer(text)} if pattern else set()
    if _EXECUTIVE.search(text):
        found.add("the executive")
    return sorted(found)


def rewrite_request(named: list[str], reader: Reader | None) -> str:
    """The note that sends a slipping draft back: each kind of slip gets its
    own replacement ("you" for the reader, the owner's name for "the
    principal" on a teammate's brief, "I" / "me" / "my" for the Executive)."""
    executive = "the executive" in named
    owner = reader.owner if reader is not None and _OWNER_LABEL in named else None
    as_you = [n for n in named if n != "the executive" and not (owner and n == _OWNER_LABEL)]
    asks: list[str] = []
    if as_you:
        asks.append(
            "write " + ", ".join(f"'{n}'" for n in as_you)
            + " as 'you' or 'your' (that is the person reading it)"
        )
    if owner:
        asks.append(f"write 'the principal' as {owner}")
    if executive:
        asks.append("write 'the Executive' as 'I', 'me' or 'my' (that is you)")
    return (
        "Rewrite that: " + "; ".join(asks)
        + ". Change nothing else, and output only the rewrite."
    )


def _cased(word: str, start: int, source: str) -> str:
    before = source[:start].rstrip("*_ -")
    return word[0].upper() + word[1:] if not before or before[-1] in ".!?:\n" else word


def _possessive(pattern: re.Pattern[str]) -> re.Pattern[str]:
    return re.compile(pattern.pattern + r"['’]s\b", re.IGNORECASE)


def fix_slips(text: str, reader: Reader | None) -> str:
    """Turn every way ``text`` names its reader into "you" / "your", "the
    principal" into the owner's name on a teammate's brief, and the Executive
    into "I" / "me" / "my"."""
    if reader is None:
        return text
    if reader.owner:
        owner = _pattern([_OWNER_LABEL])
        assert owner is not None
        text = _possessive(owner).sub(lambda m: f"{reader.owner}'s", text)
        text = owner.sub(lambda m: reader.owner or "", text)
    pattern = _pattern([*reader.terms(), *_READER_LABELS, *([] if reader.owner else [_OWNER_LABEL])])
    if pattern is not None:
        text = _possessive(pattern).sub(lambda m: _cased("your", m.start(), m.string), text)
        text = pattern.sub(lambda m: _cased("you", m.start(), m.string), text)
        # The verb after a third-person name: "you has been" → "you have been".
        text = _AGREE.sub(lambda m: m.group(1) + _AGREE_WITH[m.group(2).lower()], text)

    def _me(m: re.Match[str]) -> str:
        if m.group(1):
            return _cased("my", m.start(), m.string)
        if _OBJECT_BEFORE.search(m.string[: m.start()]):
            return "me"
        return "I"

    text = _EXECUTIVE.sub(_me, text)
    return _I_AGREE.sub(lambda m: "I " + _I_AGREE_WITH[m.group(1)], text)


_AGREE_WITH = {"has": "have", "is": "are", "was": "were", "hasn't": "haven't",
               "isn't": "aren't", "wasn't": "weren't", "doesn't": "don't", "does": "do"}
_AGREE = re.compile(r"\b([Yy]ou )(" + "|".join(re.escape(k) for k in _AGREE_WITH) + r")\b")
_I_AGREE_WITH = {"has": "have", "is": "am", "was": "was", "hasn't": "haven't",
                 "isn't": "am not", "doesn't": "don't", "does": "do"}
_I_AGREE = re.compile(r"\bI (" + "|".join(re.escape(k) for k in _I_AGREE_WITH) + r")\b")


__all__ = [
    "READER",
    "Reader",
    "fix_slips",
    "mask",
    "person_reader",
    "principal_reader",
    "reader_line",
    "rewrite_request",
    "slips",
]