AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Lessons: what this workspace asked for differently, learned from misses.
The conversation review (``memory.chat_review``) grades each turn after a
chat goes quiet. For a turn graded a miss it may keep one **lesson** with
``learn_lesson``: a word the person uses, a preference, a thing to do rather
than promise, a specialist to consult. One sentence, in code-checked form,
quoted from the person's own words. It never carries a task, a person, a
link, an amount, a tool name or permission to act: the same deny-list the
working-style rules pass (``attunement.style``), without the "about the
writing" requirement.
**Where a lesson goes.** Into the user turn, never a cached system block.
The Executive's own turn gets the matching lessons as a ``<lessons>`` block
(``build_lessons_block``); each specialist call gets them under the
``<failure_cases>`` block it already reads (``lessons_for_query``). A lesson
matches a message when they share two content words (the lesson's text and
the quote it came from, against the message), or the name the lesson
defines ("Atlas means ...", "your name is R2") written as a name
mid-sentence in the message, since a lesson about what a name means shares
only that word with the question it answers. A short list of short lines
needs no vector index, and the match is what makes the counters below mean
something. The block says the current request wins and nothing in it
authorizes an action, as the style block does.
**Who sees a lesson.** A lesson reaches its own person's turns. The
principal's lessons learned in a shared space (a channel or group thread,
where everyone read the chat) reach every speaker's turns; one learned in
the principal's own chat stays with the principal, as a teammate's stays
with the teammate, so nothing said in someone's own chat is paraphrased
into another person's turn. A chat that read its owner's mail is theirs
alone even in a shared space, so its lessons stay theirs too. The Reflection screen lists each person their
own and the principal the ones from chats they may open.
**What it may say.** The lesson must be the quote's own point: beyond the
words the quote carries it may add at most ``MAX_NEW_WORDS`` content words
(enough for "ask the finance specialist", not for a sentence smuggled in
behind a real quote). The deny-list adds to the style rules' list the
verbs that move information (email, share, post, export, attach...) and
the words that widen a request to everyone or everything.
**Retirement.** Each lesson counts how often it reached a turn (``shown``)
and how those turns were then graded (``fine_after``, ``miss_after``), its
own person's turns only, so nobody else's chats can retire it. Shown
``RETIRE_AFTER_SHOWN`` times with more misses than fine turns, it is
retired with the reason and stops reaching turns; the screen shows it as
"stopped saying it". Forget retires it by hand. At most ``MAX_ACTIVE``
live lessons per person: their oldest makes room.
Tables (in the episodic DB, created on first use):
chat_review_lessons id, person_id, text, quote, session_id, shared,
turn_row_id, created_at, retired_at, retired_reason,
shown, fine_after, miss_after
chat_review_lesson_uses lesson_id, turn_id, person_id, ts
(which turn, whose, saw which lesson)
"""
from __future__ import annotations
import logging
import re
import sqlite3
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
logger = logging.getLogger(__name__)
TABLE = "chat_review_lessons"
USES_TABLE = "chat_review_lesson_uses"
BLOCK_TAG = "lessons"
_BLOCK_CLOSE = f"</{BLOCK_TAG}>"
MIN_CHARS = 8
MAX_CHARS = 240
MAX_ACTIVE = 40
MAX_PER_TURN = 6
MAX_NEW_WORDS = 2
RETIRE_AFTER_SHOWN = 5
# Two shared content words: one common word ("report") matches too much.
# The name a lesson defines is enough (``_defined_names``).
_MATCH_WORDS = 2
# Beyond the style rules' deny-list (which has the acting verbs and the
# instruction talk): the verbs that move information somewhere, and the
# words that widen a request to everyone or everything. A lesson is a
# definition or a preference; none of these belongs in one.
_LESSON_DENY = re.compile(
r"\b(email|emails|emailed|mail|mails|mailed|share|shares|shared|post|posts|posted|"
r"publish\w*|release\w*|submit\w*|export\w*|attach\w*|upload\w*|"
r"give|gives|gave|hand|hands|handed|tell|tells|told|show|shows|showed|"
r"disclos\w*|spell out|copy|copies|paste|whoever|whomever|anyone|anybody|"
r"everyone|everybody|whole|entire|full|all of|every request|every message|"
r"treat|treats|treated|approved|external|outside|channel|channels|address|addresses)\b",
re.IGNORECASE,
)
REASON_UNHELPFUL = "unhelpful"
REASON_FORGOTTEN = "forgotten"
REASON_ROOM = "room"
# The replay (memory.replay) found it didn't flip its miss, or broke a turn
# that was fine.
REASON_REPLAY = "replay"
def _now() -> datetime:
return datetime.now(UTC)
def _connect(db_path: Path | None) -> sqlite3.Connection:
from openexecutive.memory.episodic import _resolve_db_path
conn = sqlite3.connect(str(_resolve_db_path(db_path)))
conn.row_factory = sqlite3.Row
conn.execute(
f"CREATE TABLE IF NOT EXISTS {TABLE} ("
" id INTEGER PRIMARY KEY AUTOINCREMENT,"
" person_id INTEGER NOT NULL,"
" text TEXT NOT NULL,"
" quote TEXT NOT NULL,"
" session_id TEXT NOT NULL,"
" shared INTEGER NOT NULL DEFAULT 0,"
" turn_row_id INTEGER,"
" created_at TEXT NOT NULL,"
" retired_at TEXT,"
" retired_reason TEXT,"
" shown INTEGER NOT NULL DEFAULT 0,"
" fine_after INTEGER NOT NULL DEFAULT 0,"
" miss_after INTEGER NOT NULL DEFAULT 0"
")"
)
conn.execute(
f"CREATE TABLE IF NOT EXISTS {USES_TABLE} ("
" lesson_id INTEGER NOT NULL,"
" turn_id TEXT NOT NULL,"
" person_id INTEGER,"
" ts TEXT NOT NULL,"
" PRIMARY KEY (lesson_id, turn_id)"
")"
)
conn.commit()
return conn
# --------------------------------------------------------------------------- #
# Validation
# --------------------------------------------------------------------------- #
def lesson_rejection(text: str, *, roster_names: list[str] | None = None) -> str | None:
"""Why ``text`` may not be a lesson, or None when it may. The style
rules' deny-list (no link, handle, amount, markup, identifier, action
verb, instruction talk, nudge to act unchecked, roster name), without
the requirement that it be about the writing."""
from openexecutive.attunement import style
if len(text) < MIN_CHARS:
return "too_short"
if len(text) > MAX_CHARS:
return "too_long"
if style._non_latin_letter(text):
return "non_latin_letters"
for pattern in style._DENY_PATTERNS:
if pattern.search(text):
return "denied_content"
if _LESSON_DENY.search(text):
return "denied_content"
names = roster_names if roster_names is not None else style._roster_names()
if style._names_a_person(text, names):
return "names_a_person"
return None
def lesson_overreach(text: str, quote: str) -> str | None:
"""Why ``text`` says more than ``quote`` does, or None: a lesson may add
at most ``MAX_NEW_WORDS`` content words to the quote it rests on."""
new = _content_words(text) - _content_words(quote)
if len(new) > MAX_NEW_WORDS:
return "the lesson says more than the quote does"
return None
def _normalize(text: str) -> str:
from openexecutive.attunement.style import _normalize
return _normalize(text)
def _shared_space(session_id: str, db_path: Path | None = None) -> bool:
"""Whether the chat was a channel or group thread everyone there read
(``api.routes.chat._shared_space``) and never read its owner's mail
(``session_store.mark_mail_private``: then it is theirs alone, wherever
it happened). Fails closed: not shared."""
try:
from openexecutive.api.routes.chat import _shared_space
from openexecutive.memory.episodic import _resolve_db_path
from openexecutive.memory.session_store import session_mail_private
if not _shared_space(str(session_id)):
return False
return not session_mail_private(str(session_id), db_path=_resolve_db_path(db_path))
except Exception:
return False
# --------------------------------------------------------------------------- #
# Keeping and forgetting
# --------------------------------------------------------------------------- #
def add_lesson(
person_id: int,
text: str,
*,
quote: str,
session_id: str,
turn_row_id: int | None,
db_path: Path | None = None,
private: bool = False,
) -> tuple[dict[str, Any] | None, str | None]:
"""Keep one lesson; ``(lesson, None)`` when stored, ``(None, reason)``
when not. The caller has checked ``quote`` against the person's words.
``private``: learned from a chat that read mail, so never shared.
A duplicate of a live lesson is refused; past ``MAX_ACTIVE`` live
lessons the oldest retires to make room."""
clean = _normalize(text)
rejection = lesson_rejection(clean)
if rejection:
return None, rejection
now = _now().isoformat()
shared = not private and _shared_space(session_id, db_path)
conn = _connect(db_path)
try:
# One writer at a time: two reviews landing together must not both
# pass the duplicate check or both skip making room.
conn.execute("BEGIN IMMEDIATE")
live = conn.execute(
f"SELECT id, text FROM {TABLE} WHERE retired_at IS NULL AND person_id = ? " # noqa: S608
"ORDER BY created_at, id",
(int(person_id),),
).fetchall()
if any(_same(str(row["text"]), clean) for row in live):
conn.rollback()
return None, "duplicate"
for row in live[: max(0, len(live) - MAX_ACTIVE + 1)]:
conn.execute(
f"UPDATE {TABLE} SET retired_at = ?, retired_reason = ? WHERE id = ?", # noqa: S608
(now, REASON_ROOM, int(row["id"])),
)
cur = conn.execute(
f"INSERT INTO {TABLE} (person_id, text, quote, session_id, shared, turn_row_id, created_at) " # noqa: S608
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(int(person_id), clean, _normalize(quote)[:400], str(session_id), 1 if shared else 0,
turn_row_id, now),
)
conn.commit()
row_id = int(cur.lastrowid or 0)
finally:
conn.close()
_audit(f"lesson kept for person {person_id}", {"op": "learn_lesson", "lesson_id": row_id, "person_id": person_id})
return get_lesson(row_id, db_path=db_path), None
def _same(a: str, b: str) -> bool:
return a.casefold().rstrip(".!") == b.casefold().rstrip(".!")
def get_lesson(lesson_id: int, *, db_path: Path | None = None) -> dict[str, Any] | None:
conn = _connect(db_path)
try:
row = conn.execute(f"SELECT * FROM {TABLE} WHERE id = ?", (int(lesson_id),)).fetchone() # noqa: S608
finally:
conn.close()
return _out(row) if row is not None else None
def list_lessons(
*, person_id: int | None, limit: int = 200, offset: int = 0, db_path: Path | None = None
) -> list[dict[str, Any]]:
"""Live lessons first, newest first, then the retired ones: one
person's, or everyone's when ``person_id`` is None, ``offset`` rows in
(the principal's page is read in parts, like the misses)."""
conn = _connect(db_path)
try:
where, params = "1 = 1", []
if person_id is not None:
where, params = "person_id = ?", [int(person_id)]
rows = conn.execute(
f"SELECT * FROM {TABLE} WHERE {where} " # noqa: S608
"ORDER BY (retired_at IS NOT NULL), created_at DESC, id DESC LIMIT ? OFFSET ?",
(*params, max(1, min(int(limit), 1000)), max(0, int(offset))),
).fetchall()
finally:
conn.close()
return [_out(r) for r in rows]
def forget_lesson(lesson_id: int, *, caller_person_id: int | None, db_path: Path | None = None) -> bool:
"""Retire one lesson by hand: its own person or the principal may.
False when there is no such lesson, it is already retired, or the
caller may not."""
from openexecutive.people.store import is_principal_or_self
conn = _connect(db_path)
try:
row = conn.execute(
f"SELECT person_id, retired_at FROM {TABLE} WHERE id = ?", (int(lesson_id),) # noqa: S608
).fetchone()
if row is None or row["retired_at"] is not None:
return False
if not is_principal_or_self(caller_person_id, int(row["person_id"])):
return False
conn.execute(
f"UPDATE {TABLE} SET retired_at = ?, retired_reason = ? WHERE id = ?", # noqa: S608
(_now().isoformat(), REASON_FORGOTTEN, int(lesson_id)),
)
conn.commit()
return True
finally:
conn.close()
def retire_lesson(lesson_id: int, reason: str, *, db_path: Path | None = None) -> bool:
"""Retire one live lesson for ``reason`` (the replay's gate, memory.replay).
False when there is no such live lesson. Never raises."""
try:
conn = _connect(db_path)
try:
conn.execute(
f"UPDATE {TABLE} SET retired_at = ?, retired_reason = ? " # noqa: S608
"WHERE id = ? AND retired_at IS NULL",
(_now().isoformat(), reason, int(lesson_id)),
)
changed = bool(conn.execute("SELECT changes()").fetchone()[0])
conn.commit()
finally:
conn.close()
except Exception:
logger.debug("lessons: couldn't retire %s", lesson_id, exc_info=True)
return False
if changed:
_audit(f"lesson {lesson_id} retired: {reason}",
{"op": "retire_lesson", "lesson_id": int(lesson_id), "reason": reason})
return changed
def lessons_since(since: str | None, *, db_path: Path | None = None) -> list[dict[str, Any]]:
"""The live lessons learned after ``since`` (an ISO time; None = all of
them), oldest first. Never raises."""
try:
conn = _connect(db_path)
try:
rows = conn.execute(
f"SELECT * FROM {TABLE} WHERE retired_at IS NULL AND created_at > ? " # noqa: S608
"ORDER BY created_at, id",
(since or "",),
).fetchall()
finally:
conn.close()
return [_out(r) for r in rows]
except Exception:
logger.debug("lessons: lookup failed", exc_info=True)
return []
def _out(row: sqlite3.Row) -> dict[str, Any]:
return {
"id": int(row["id"]),
"person_id": int(row["person_id"]),
"text": str(row["text"]),
"quote": str(row["quote"]),
"session_id": str(row["session_id"]),
"shared": bool(row["shared"]),
"turn_row_id": int(row["turn_row_id"]) if row["turn_row_id"] is not None else None,
"created_at": str(row["created_at"]),
"retired_at": str(row["retired_at"]) if row["retired_at"] else None,
"retired_reason": str(row["retired_reason"]) if row["retired_reason"] else None,
"shown": int(row["shown"]),
"fine_after": int(row["fine_after"]),
"miss_after": int(row["miss_after"]),
}
# --------------------------------------------------------------------------- #
# Reaching a turn
# --------------------------------------------------------------------------- #
_STOPWORDS = frozenset(
["the", "a", "an", "and", "or", "to", "of", "in", "on", "for", "my", "me", "i", "it", "is", "was",
"that", "this", "with", "from", "at", "by", "be", "please", "can", "you", "your", "we", "our",
"they", "them", "he", "she", "his", "her", "its", "are", "were", "has", "have", "had", "will",
"would", "should", "could", "just", "about", "out", "off", "up", "down", "into", "over", "when",
"what", "than", "then", "there", "here", "also", "always", "never", "rather", "instead", "want",
"wants", "wanted", "need", "needs", "thing", "things", "something", "every", "each", "some",
"more", "most", "very", "really", "like", "make", "made", "does", "did", "done", "mean", "means"]
)
def _content_words(text: str) -> set[str]:
return {w for w in re.findall(r"[a-z0-9']+", text.casefold()) if len(w) >= 4 and w not in _STOPWORDS}
_TOKEN_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9']*")
# A lesson that says what a name means: "Atlas means ...", "R2 is ...",
# "... is called Atlas", "your name is R2".
_NAME = r"([A-Z][A-Za-z0-9']*|[A-Za-z]*\d[A-Za-z0-9']*)"
_DEFINED_RES = (
re.compile(_NAME + r"\s+(?:is|means|stands for|refers to)\b"),
re.compile(r"\b(?:called|call it|named|name is|known as)\s+" + _NAME),
)
def _names(text: str, *, sentence_starts: bool = True) -> set[str]:
"""The name-like words in ``text``, casefolded: written with a capital
or a digit ("Atlas", "R2"), not a stopword or a bare number.
``sentence_starts=False`` skips a word that opens a sentence, where a
capital says nothing."""
out: set[str] = set()
for m in _TOKEN_RE.finditer(text):
word = m.group()
if not any(c.isupper() or c.isdigit() for c in word) or word.isdigit():
continue
if not sentence_starts and re.search(r"(^|[.!?:]\s+)$", text[: m.start()]):
continue
folded = word.casefold()
if len(folded) >= 2 and folded not in _STOPWORDS:
out.add(folded)
return out
def _defined_names(text: str) -> set[str]:
"""The names ``text`` says the meaning of: a lesson about what a name
means ("Atlas means the Dallas warehouse move") shares only that word
with the question it answers. A name it merely mentions ("Pipeline
reports go to Sam") is not one."""
found: set[str] = set()
for pattern in _DEFINED_RES:
for m in pattern.finditer(text):
found |= _names(m.group(1))
return found
def _matches(lesson: dict[str, Any], message: str) -> bool:
"""Whether ``lesson`` reaches a turn about ``message``: two shared
content words, or the name the lesson defines, written as a name
mid-sentence in the message."""
own = _content_words(lesson["text"]) | _content_words(lesson["quote"])
if len(own & _content_words(message)) >= _MATCH_WORDS:
return True
names = _defined_names(lesson["text"]) | _defined_names(lesson["quote"])
return bool(names & _names(message, sentence_starts=False))
def lessons_for(
person_id: int | None, message: str, *, db_path: Path | None = None
) -> list[dict[str, Any]]:
"""The live lessons that reach this speaker's turn about ``message``:
the speaker's own, and the principal's from shared spaces. Never
raises."""
if person_id is None:
return []
try:
from openexecutive.people.store import find_principal_person
if not _content_words(message) and not _names(message, sentence_starts=False):
return []
principal = find_principal_person()
principal_id = int(principal.id) if principal is not None and principal.id is not None else -1
conn = _connect(db_path)
try:
rows = conn.execute(
f"SELECT * FROM {TABLE} WHERE retired_at IS NULL " # noqa: S608
"AND (person_id = ? OR (person_id = ? AND shared = 1)) ORDER BY created_at DESC, id DESC",
(int(person_id), principal_id),
).fetchall()
finally:
conn.close()
return [lesson for lesson in map(_out, rows) if _matches(lesson, message)][:MAX_PER_TURN]
except Exception:
logger.debug("lessons: lookup failed", exc_info=True)
return []
def note_shown(
lessons: list[dict[str, Any]], *, person_id: int | None = None, db_path: Path | None = None
) -> None:
"""These lessons reached the active turn of ``person_id``: count it, and
remember which turn and whose, so the grade of that turn can be counted
against them."""
if not lessons:
return
try:
from openexecutive.audit.context import get_active_turn_id
turn_id = get_active_turn_id()
now = _now().isoformat()
conn = _connect(db_path)
try:
for lesson in lessons:
conn.execute(
f"UPDATE {TABLE} SET shown = shown + 1 WHERE id = ?", (int(lesson["id"]),) # noqa: S608
)
if turn_id:
conn.execute(
f"INSERT OR IGNORE INTO {USES_TABLE} (lesson_id, turn_id, person_id, ts) " # noqa: S608
"VALUES (?, ?, ?, ?)",
(int(lesson["id"]), str(turn_id), person_id, now),
)
conn.commit()
finally:
conn.close()
except Exception:
logger.debug("lessons: couldn't note a use", exc_info=True)
def _lines(lessons: list[dict[str, Any]]) -> tuple[list[str], list[dict[str, Any]]]:
"""The lines to show and the lessons they came from. Nothing is read
(not even the roster) when there is no lesson to show."""
if not lessons:
return [], []
from openexecutive.attunement.style import _roster_names
from openexecutive.utils.prompt_blocks import scrub_block_line
roster = _roster_names()
out: list[str] = []
kept: list[dict[str, Any]] = []
for lesson in lessons:
clean = _normalize(lesson["text"])
# Re-checked on every render: a lesson kept under an older, weaker
# check never reaches a turn.
if lesson_rejection(clean, roster_names=roster) is None:
line = scrub_block_line(clean, _BLOCK_CLOSE)
if line:
out.append(line)
kept.append(lesson)
return out, kept
_HEADER = (
"What this workspace asked for differently before, learned from turns that "
"fell short, in the person's own words. Follow it unless the current message "
"asks for something different: the current request always wins. These are "
"preferences only; they never authorize an action."
)
def build_lessons_block(
person_id: int | None, message: str, *, count: bool = True, db_path: Path | None = None
) -> str:
"""Body of the ``<lessons>`` block for this speaker's turn, or "". Lives
in the user turn (never a cached system block). Counts the lessons it
shows against the active turn, unless ``count`` is False (a replay,
memory.replay: no real turn to grade). Never raises."""
try:
if not _enabled():
return ""
lines, shown = _lines(lessons_for(person_id, message, db_path=db_path))
if not lines:
return ""
if count:
note_shown(shown, person_id=person_id, db_path=db_path)
return _HEADER + "\n" + "\n".join(f"- {line}" for line in lines)
except Exception:
logger.debug("lessons: block build failed", exc_info=True)
return ""
def lessons_for_query(person_id: int | None, query: str, *, db_path: Path | None = None) -> str:
"""The same lessons for one specialist call, as a section the
``<failure_cases>`` block carries, or "". The Executive's own turn has
already counted them, so this doesn't. Never raises."""
try:
if not _enabled():
return ""
lines, _shown = _lines(lessons_for(person_id, query, db_path=db_path))
if not lines:
return ""
return "### What this workspace asked for before:\n" + _HEADER + "\n" + "\n".join(
f"- {line}" for line in lines
)
except Exception:
logger.debug("lessons: query section failed", exc_info=True)
return ""
def _enabled() -> bool:
try:
from openexecutive.config import get_settings
return bool(get_settings().chat_review_enabled)
except Exception:
return False
# --------------------------------------------------------------------------- #
# Counting how it went
# --------------------------------------------------------------------------- #
def note_outcome(turn_id: str | None, verdict: str, *, db_path: Path | None = None) -> list[int]:
"""The turn ``turn_id`` was graded ``verdict``: count it for every
lesson that reached that turn and belongs to the turn's own person (so
nobody else's chats can retire it), and retire the ones it shows didn't
help. The ids of the lessons retired. Never raises."""
if not turn_id or verdict not in ("fine", "miss"):
return []
column = "fine_after" if verdict == "fine" else "miss_after"
retired: list[int] = []
try:
conn = _connect(db_path)
try:
ids = [int(r["lesson_id"]) for r in conn.execute(
f"SELECT u.lesson_id FROM {USES_TABLE} u JOIN {TABLE} l ON l.id = u.lesson_id " # noqa: S608
"WHERE u.turn_id = ? AND u.person_id = l.person_id",
(str(turn_id),),
).fetchall()]
for lesson_id in ids:
conn.execute(
f"UPDATE {TABLE} SET {column} = {column} + 1 WHERE id = ?", (lesson_id,) # noqa: S608
)
row = conn.execute(
f"SELECT shown, fine_after, miss_after, retired_at FROM {TABLE} WHERE id = ?", # noqa: S608
(lesson_id,),
).fetchone()
if (
row is not None and row["retired_at"] is None
and int(row["shown"]) >= RETIRE_AFTER_SHOWN
and int(row["miss_after"]) > int(row["fine_after"])
):
conn.execute(
f"UPDATE {TABLE} SET retired_at = ?, retired_reason = ? WHERE id = ?", # noqa: S608
(_now().isoformat(), REASON_UNHELPFUL, lesson_id),
)
retired.append(lesson_id)
conn.commit()
finally:
conn.close()
except Exception:
logger.debug("lessons: couldn't count an outcome", exc_info=True)
return retired
for lesson_id in retired:
_audit(f"lesson {lesson_id} retired: the turns it reached went worse, not better",
{"op": "retire_lesson", "lesson_id": lesson_id, "reason": REASON_UNHELPFUL})
return retired
def _audit(summary: str, details: dict[str, Any]) -> None:
try:
from openexecutive.audit import log_event
log_event("chat_review", summary, actor="chat_review", details=details)
except Exception:
logger.debug("lessons: audit failed", exc_info=True)