Skip to content

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

9.1 KB
Raw Blame
"""On-disk cache for the on-page briefing narrative.

Mirrors `openexecutive.people.insights_cache`: a dedicated table in the
shared `./episodic_memory.db`, validated against an `input_hash` of the
briefing state. The narrative is one LLM call, so we never generate it on
the request hot path — `/today` serves the cached text instantly and, when
the state hash has moved, regenerates in a FastAPI background task (same
pattern as the per-person insight notes).

Keyed by a `scope` string rather than a person id: the principal's own
whole-company narrative lives under `"principal"` (the default) and may carry
what is private to them; an unrostered/unresolved viewer gets the shared
`"company"` narrative written from what everyone may see; each non-principal
teammate gets their own role-scoped narrative under `person:<id>` (see
`today._attach_narrative`).
"""
from __future__ import annotations

import hashlib
import json
import logging
import sqlite3
from collections.abc import Generator
from contextlib import contextmanager
from datetime import UTC, datetime
from pathlib import Path

from pydantic import BaseModel

from openexecutive.memory import episodic as _episodic

logger = logging.getLogger(__name__)

# Explicit override slot. Left None in production so the cache follows the
# episodic DB dynamically (see _resolve_db_path) — same rationale as
# insights_cache: capturing episodic.DB_PATH at import time would make a
# test's monkeypatch of episodic.DB_PATH silently miss this table.
DB_PATH: Path | None = None

DEFAULT_SCOPE = "principal"
# The whole-company narrative for a caller who resolved to no roster row.
COMPANY_SCOPE = "company"


def local_today(now: datetime | None = None) -> str:
    """The principal's local date (``YYYY-MM-DD``), in the workspace's zone.

    The header's daily floor and its PERIOD line: a UTC date rolled the
    narrative over mid-evening in the Americas and kept yesterday's header
    until mid-morning east of UTC. Never raises (UTC when the zone is
    unreadable).
    """
    now = now or datetime.now(UTC)
    try:
        from openexecutive.memory.workspace_settings import get_user_timezone

        return now.astimezone(get_user_timezone()).strftime("%Y-%m-%d")
    except Exception:
        return now.strftime("%Y-%m-%d")


class BriefingNarrative(BaseModel):
    """A cached briefing narrative for one scope."""

    scope: str
    input_hash: str
    narrative_text: str
    generated_at: str  # ISO-8601 UTC


def _resolve_db_path(db_path: Path | None) -> Path:
    if db_path is not None:
        return db_path
    if DB_PATH is not None:
        return DB_PATH
    return _episodic.DB_PATH


@contextmanager
def _get_conn(db_path: Path | None = None) -> Generator[sqlite3.Connection, None, None]:
    resolved = _resolve_db_path(db_path)
    conn = sqlite3.connect(str(resolved))
    conn.row_factory = sqlite3.Row
    try:
        yield conn
        conn.commit()
    finally:
        conn.close()


def initialize_db(db_path: Path | None = None) -> None:
    with _get_conn(db_path) as conn:
        conn.execute(
            """
            CREATE TABLE IF NOT EXISTS briefing_narrative (
                scope TEXT PRIMARY KEY,
                input_hash TEXT NOT NULL,
                narrative_text TEXT NOT NULL,
                generated_at TEXT NOT NULL
            )
            """
        )


# Bump this whenever the narrative PROMPTS change (BRIEFING_NARRATIVE_SYSTEM /
# _viewer_system_prompt / STANDALONE_BRIEF_SYSTEM in narrative.py). It is folded
# into the input hash so a prompt change invalidates every cached narrative on
# the next view — otherwise a wording fix wouldn't surface until the underlying
# state changed (or the daily date rollover).
NARRATIVE_PROMPT_VERSION = "11"


# Stands in for the rendered context when nothing on the viewer's board wants
# a decision. The narrative is then a fixed line and no model call happens, so
# the key must NOT depend on anything volatile: hashing the real context there
# would re-key on every activity row and re-write the identical quiet line
# forever.
QUIET_CONTEXT = "<nothing-needs-attention>"
# The same for Right now when items are open but none moved today: the
# header is the fixed "nothing new" line and Needs you below says the rest.
NOTHING_MOVED_CONTEXT = "<nothing-moved-today>"


def build_narrative_input_hash(
    rendered_context: str, scope: str = DEFAULT_SCOPE, mode: str = "team"
) -> str:
    """Hash of the EXACT user-turn context the model will be given.

    The one invariant that keeps this cache honest: **the key is a function of
    the model's input.** Anything the prompt renders is covered; anything it
    does not render cannot trigger a regeneration. Both properties are free,
    and they survive future edits to `render_briefing_context` without anyone
    remembering to update a field list here.

    Two earlier designs each broke one half of that, in opposite directions:

    * Keying on proposal headlines alone left the rendered activity block
      uncovered, so the header could describe a rail that had moved on.
    * Keying on the proposals' review fields (`review_verdict`, `review_note`,
      `why_now`, `recommended_move`, `due_at`) covered data the /today header
      never renders at all — it prints `headline[:160]` and nothing else — while
      `alerts.review` rewrites those fields with fresh LLM prose on EVERY pass,
      including its "still relevant, nothing changed" path. That regenerated
      every viewer's narrative several times a day to re-synthesize byte-
      identical input.

    ``scope`` keeps two viewers whose contexts coincide under distinct keys,
    ``NARRATIVE_PROMPT_VERSION`` invalidates every entry when a prompt is
    reworded, and the principal's local date (:func:`local_today`) gives a
    daily floor (it is also inside the rendered context's PERIOD line, but
    the quiet sentinel has no such line).

    ``mode`` is the workspace mode. Solo and team use different system
    prompts over what can be the very same context, so a solo key carries the
    mode and never matches a team one. Team keys leave it out, so they are
    unchanged from before solo mode existed and no team cache is invalidated.

    The brief model (:func:`narrative.brief_model`) is folded in for every
    context the model writes, so switching the Executive's model rewrites the
    header on the next view instead of serving the old model's text.
    """
    if not isinstance(rendered_context, str):
        # This used to take the `today_data` dict. A dict is JSON-serialisable,
        # so a stale caller would hash silently and key the entry on something
        # the model never saw — a wrong cache that looks like a working one.
        raise TypeError(
            "build_narrative_input_hash takes the RENDERED context string "
            f"(see today._narrative_context), not {type(rendered_context).__name__}"
        )
    payload = {
        "scope": scope,
        "prompt_version": NARRATIVE_PROMPT_VERSION,
        "date": local_today(),
        "context": rendered_context,
    }
    if mode != "team":
        payload["mode"] = mode
    if rendered_context not in (QUIET_CONTEXT, NOTHING_MOVED_CONTEXT):
        # The model writes the text, so a new Executive model in the Council
        # re-keys every written header. The fixed lines involve no model.
        from openexecutive.briefing.narrative import brief_model

        payload["model"] = brief_model()
    blob = json.dumps(payload, sort_keys=True, default=str)
    return hashlib.sha256(blob.encode("utf-8")).hexdigest()


def get(scope: str = DEFAULT_SCOPE, db_path: Path | None = None) -> BriefingNarrative | None:
    initialize_db(db_path)
    with _get_conn(db_path) as conn:
        row = conn.execute(
            "SELECT scope, input_hash, narrative_text, generated_at "
            "FROM briefing_narrative WHERE scope = ?",
            (scope,),
        ).fetchone()
    if row is None:
        return None
    return BriefingNarrative(
        scope=row["scope"],
        input_hash=row["input_hash"],
        narrative_text=row["narrative_text"],
        generated_at=row["generated_at"],
    )


def put(narrative: BriefingNarrative, db_path: Path | None = None) -> None:
    initialize_db(db_path)
    with _get_conn(db_path) as conn:
        conn.execute(
            """
            INSERT INTO briefing_narrative
              (scope, input_hash, narrative_text, generated_at)
            VALUES (?, ?, ?, ?)
            ON CONFLICT(scope) DO UPDATE SET
              input_hash = excluded.input_hash,
              narrative_text = excluded.narrative_text,
              generated_at = excluded.generated_at
            """,
            (
                narrative.scope,
                narrative.input_hash,
                narrative.narrative_text,
                narrative.generated_at,
            ),
        )


def utc_now_iso() -> str:
    return datetime.now(UTC).isoformat()


__all__ = [
    "COMPANY_SCOPE",
    "DEFAULT_SCOPE",
    "NOTHING_MOVED_CONTEXT",
    "QUIET_CONTEXT",
    "BriefingNarrative",
    "build_narrative_input_hash",
    "get",
    "initialize_db",
    "local_today",
    "put",
    "utc_now_iso",
]