AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Live updates for a chat more than one person is in.
A chat its owner shared (``session_store.shared_with``) is read and written by
everyone in it at once. Each page that has it open holds one stream
(``GET /sessions/{id}/live``) and this module feeds those streams:
- ``turn_started``: someone sent a message; who, and what it says.
- the reply as it is written: ``chunk``, ``thinking``, ``activity``,
``action_taken``, as the sender's own stream carries them.
- ``turn_ended``: the turn is saved. Pages read the chat again, which brings
the reply's id, its sources and anything added while it worked.
- ``typing``: someone is writing a message.
- ``people``: someone was added or left. ``removed`` ends the stream of
whoever lost the chat, ``deleted`` everyone's.
- ``resync``: a page fell behind (its queue filled). Its stream ends; it
connects again and reads the chat.
Every event names the chat's running turn by ``turn_key`` (the sender's own
client turn id), so the sender's page can skip the copy of what its own
stream already showed.
It costs nothing until a turn runs: a stream waits on its queue, and a chat
nobody shares publishes nothing (the chat route only calls in for shared
ones). One process holds every chat's watchers, as it holds every live
``Session`` (``chat._sessions``). Nothing here is stored: a page that
(re)connects reads the saved chat and gets the running turn so far in
``ready`` (``snapshot``).
"""
from __future__ import annotations
import asyncio
import time
from dataclasses import dataclass, field
from typing import Any
# Events a page may be behind by before it is told to read the chat again. A
# long reply streams a few hundred chunks.
_QUEUE_MAX = 1024
# Open pages per chat and per process. Each is an idle connection, but
# without a cap one caller could open any number.
MAX_PER_CHAT = 40
MAX_PER_PERSON = 12
MAX_TOTAL = 2000
# One `typing` event per person per chat at most this often.
TYPING_EVERY_S = 2.0
_TYPING_MAX = 4096
@dataclass(eq=False)
class Watcher:
"""One open page: who it is for and the events waiting for it."""
session_id: str
person_id: int | None
queue: asyncio.Queue[dict[str, Any]] = field(
default_factory=lambda: asyncio.Queue(maxsize=_QUEUE_MAX)
)
# Set once its last event (``removed``, ``deleted``, ``resync``) is
# queued: nothing after it is sent.
ended: bool = False
_watchers: dict[str, set[Watcher]] = {}
# The running turn of each shared chat, for a page that opens mid-turn.
_turns: dict[str, dict[str, Any]] = {}
_typing_at: dict[tuple[str, int], float] = {}
def admits(session_id: str, person_id: int | None) -> bool:
"""Whether one more page may watch ``session_id``: per person first, so
one person's pages can't use up everyone's. A caller with no Person (a
single-user install) has no per-person cap."""
total = sum(len(w) for w in _watchers.values())
if total >= MAX_TOTAL or len(_watchers.get(session_id, ())) >= MAX_PER_CHAT:
return False
if person_id is None:
return True
mine = sum(1 for ws in _watchers.values() for w in ws if w.person_id == person_id)
return mine < MAX_PER_PERSON
def subscribe(session_id: str, person_id: int | None) -> Watcher | None:
"""A new page watching ``session_id``. None when the caps are reached."""
if not admits(session_id, person_id):
return None
watcher = Watcher(session_id=session_id, person_id=person_id)
_watchers.setdefault(session_id, set()).add(watcher)
return watcher
def unsubscribe(watcher: Watcher) -> None:
current = _watchers.get(watcher.session_id)
if current is None:
return
current.discard(watcher)
if not current:
_watchers.pop(watcher.session_id, None)
def watchers(session_id: str) -> int:
"""How many pages have ``session_id`` open."""
return len(_watchers.get(session_id, ()))
def _end(watcher: Watcher, event_type: str) -> None:
while not watcher.queue.empty():
watcher.queue.get_nowait()
watcher.queue.put_nowait({"type": event_type, "session_id": watcher.session_id})
watcher.ended = True
def _offer(watcher: Watcher, event: dict[str, Any]) -> None:
if watcher.ended:
return
try:
watcher.queue.put_nowait(event)
except asyncio.QueueFull:
# Too far behind to catch up event by event: drop what it missed and
# have it connect again and read the saved chat instead.
_end(watcher, "resync")
def publish(session_id: str, event: dict[str, Any]) -> None:
"""Send ``event`` to every page watching ``session_id``. Never blocks."""
for watcher in list(_watchers.get(session_id, ())):
_offer(watcher, {**event, "session_id": session_id})
def end_for(session_id: str, person_ids: set[int] | None, event_type: str) -> None:
"""End the streams of ``person_ids`` on ``session_id`` (everyone's when
None) with a last ``event_type`` event (``removed``, ``deleted``)."""
for watcher in list(_watchers.get(session_id, ())):
if (person_ids is None or watcher.person_id in person_ids) and not watcher.ended:
_end(watcher, event_type)
def turn_started(
session_id: str,
*,
turn_key: str,
sender_person_id: int | None,
sender_name: str,
content: str,
) -> None:
"""A turn began: kept for pages that open while it runs, and sent."""
turn: dict[str, Any] = {
"turn_key": turn_key,
"sender_person_id": sender_person_id,
"sender_name": sender_name,
"content": content,
"reply": "",
"actions": [],
}
_turns[session_id] = turn
publish(session_id, {"type": "turn_started", **{k: v for k, v in turn.items() if k not in ("reply", "actions")}})
def turn_event(session_id: str, turn_key: str, event: dict[str, Any]) -> None:
"""One step of the running turn's reply, as the sender's stream sent it."""
turn = _turns.get(session_id)
if turn is None or turn["turn_key"] != turn_key:
return
kind = event.get("type")
if kind == "chunk":
turn["reply"] += str(event.get("content") or "")
elif kind == "action_taken":
turn["actions"].append(event)
publish(session_id, {**event, "turn_key": turn_key})
def turn_ended(session_id: str, turn_key: str) -> None:
"""The turn is over and saved (or saved nothing): pages read the chat."""
turn = _turns.get(session_id)
if turn is not None and turn["turn_key"] == turn_key:
_turns.pop(session_id, None)
publish(session_id, {"type": "turn_ended", "turn_key": turn_key})
def snapshot(session_id: str) -> dict[str, Any] | None:
"""The running turn so far, or None."""
turn = _turns.get(session_id)
if turn is None:
return None
return {**turn, "actions": list(turn["actions"])}
def typing(session_id: str, person_id: int, name: str) -> bool:
"""Tell the chat ``person_id`` is writing. False when they just did."""
now = time.monotonic()
key = (session_id, person_id)
last = _typing_at.get(key)
if last is not None and now - last < TYPING_EVERY_S:
return False
if len(_typing_at) >= _TYPING_MAX:
_typing_at.clear()
_typing_at[key] = now
publish(session_id, {"type": "typing", "person_id": person_id, "name": name})
return True
def reset() -> None:
"""Forget every watcher and turn (tests)."""
_watchers.clear()
_turns.clear()
_typing_at.clear()