hosted_room_router.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. """Opt-in automatic routing and Continue for hosted Group Chats (pure: no I/O, no model knowledge).
  2. A room whose settings say ``routing: auto`` sends an unaddressed human message through one cheap, tool-less
  3. model call (``tui_gateway.hosted_room_router_call``) that picks the member(s) it is for. The deterministic
  4. rules still come first and never reach the router: an @mention or @all/@everyone, a scheduled post, and a
  5. message inside an existing thread (a hover Reply prefixes the member's handle, so it is a mention). The
  6. answer is written to the room log as ``room.routed`` BEFORE any turn is planned, so the planner stays a pure
  7. function of the log and a restart re-plans identically without asking again. A router that fails or answers
  8. something invalid records a fallback to everyone (the ``everyone`` room behaviour).
  9. ``room.continued`` is the user's Continue on a discussion that hit its cap (``room.activity`` ``bounded``):
  10. each one grants the same discussion one more budget of rounds and messages and reopens it.
  11. """
  12. from __future__ import annotations
  13. import json
  14. from collections.abc import Mapping, Sequence
  15. from typing import TYPE_CHECKING, Any
  16. if TYPE_CHECKING:
  17. from gateway.hosted_room_discussion import DiscussionMember, DiscussionRoom, _ValidatedEvent
  18. ROUTED_EVENT_KIND = "room.routed"
  19. CONTINUED_EVENT_KIND = "room.continued"
  20. ROUTED_FIELDS = frozenset({"discussion_event_id", "thread_id", "member_ids", "everyone", "fallback"})
  21. CONTINUED_FIELDS = frozenset({"discussion_event_id", "thread_id", "grant"})
  22. #: Continues one discussion may take; each one is another full budget of rounds and messages.
  23. MAX_DISCUSSION_CONTINUES = 5
  24. #: Recent room messages the router sees, and the characters kept from each.
  25. ROUTER_RECENT_MESSAGES = 5
  26. ROUTER_MESSAGE_CHARS = 600
  27. ROUTE_PENDING = object()
  28. def routed_event_id(discussion_event_id: str) -> str:
  29. return f"droute:{discussion_event_id}"
  30. def routed_event(events: Sequence[_ValidatedEvent], discussion_event_id: str) -> _ValidatedEvent | None:
  31. return next((event for event in events if event.kind == ROUTED_EVENT_KIND
  32. and event.payload.get("discussion_event_id") == discussion_event_id), None)
  33. def routed_responders(
  34. room: DiscussionRoom, discussion: _ValidatedEvent, events: Sequence[_ValidatedEvent], context: Mapping[str, str],
  35. ) -> tuple[DiscussionMember, ...] | object | None:
  36. """Round-0 responders the router picked; ``ROUTE_PENDING`` while the message still waits for its
  37. ``room.routed``; None when this message is not routed (not an auto room, or a deterministic rule applies)."""
  38. from gateway.hosted_room_lead import routes_through_lead
  39. if context.get("routing") != "auto" or not routes_through_lead(discussion, room, events):
  40. return None
  41. if (event := routed_event(events, discussion.event_id)) is None:
  42. return ROUTE_PENDING
  43. if event.payload["everyone"]:
  44. return tuple(room.members)
  45. chosen = set(event.payload["member_ids"])
  46. return tuple(member for member in room.members if member.member_id in chosen)
  47. def continue_count(events: Sequence[_ValidatedEvent], discussion_event_id: str) -> int:
  48. return sum(1 for event in events if event.kind == CONTINUED_EVENT_KIND
  49. and event.payload.get("discussion_event_id") == discussion_event_id)
  50. def resume_round(events: Sequence[_ValidatedEvent], discussion_event_id: str,
  51. member_messages: Sequence[_ValidatedEvent]) -> int | None:
  52. """The round after the last reply before the latest Continue (None without one): the room resumes there."""
  53. latest = max((event.seq for event in events if event.kind == CONTINUED_EVENT_KIND
  54. and event.payload.get("discussion_event_id") == discussion_event_id), default=None)
  55. if latest is None:
  56. return None
  57. return 1 + max((int(event.payload["round_index"]) for event in member_messages if event.seq < latest), default=-1)
  58. def continued_through(events: Sequence[_ValidatedEvent]) -> dict[str, int]:
  59. """discussion_event_id -> seq of its latest ``room.continued``: activity before it no longer completes it."""
  60. latest: dict[str, int] = {}
  61. for event in events:
  62. if event.kind == CONTINUED_EVENT_KIND:
  63. latest[str(event.payload["discussion_event_id"])] = event.seq
  64. return latest
  65. def validate_routed_event(kind: str, payload: Mapping[str, Any], actor: Mapping[str, Any],
  66. room: DiscussionRoom) -> Mapping[str, Any]:
  67. from gateway.hosted_room_discussion import (
  68. DiscussionValidationError, _exact_fields, _identifier, _require_gateway_actor)
  69. _exact_fields(payload, label=f"{kind} payload", required=ROUTED_FIELDS)
  70. _require_gateway_actor(actor, room, f"{kind} requires the room gateway")
  71. for field in ("discussion_event_id", "thread_id"):
  72. _identifier(payload.get(field), label=field)
  73. member_ids, everyone = payload.get("member_ids"), payload.get("everyone")
  74. roster = {member.member_id for member in room.members}
  75. if (not isinstance(everyone, bool) or not isinstance(payload.get("fallback"), bool)
  76. or not isinstance(member_ids, list) or len(set(member_ids)) != len(member_ids)
  77. or not set(member_ids) <= roster or (everyone and member_ids) or (not everyone and not member_ids)):
  78. raise DiscussionValidationError(f"{kind} must name seated members or everyone")
  79. return payload
  80. def validate_continued_event(kind: str, payload: Mapping[str, Any], actor: Mapping[str, Any],
  81. room: DiscussionRoom) -> Mapping[str, Any]:
  82. from gateway.hosted_room_discussion import (
  83. _bounded_int, _exact_fields, _identifier, _require_gateway_actor)
  84. _exact_fields(payload, label=f"{kind} payload", required=CONTINUED_FIELDS)
  85. _require_gateway_actor(actor, room, f"{kind} requires the room gateway")
  86. for field in ("discussion_event_id", "thread_id"):
  87. _identifier(payload.get(field), label=field)
  88. _bounded_int(payload.get("grant"), message=f"{kind} grant must be a positive integer", low=1,
  89. high=MAX_DISCUSSION_CONTINUES)
  90. return payload
  91. def paused_discussion(events: Sequence[Mapping[str, Any]], discussion_event_id: str) -> dict[str, Any] | None:
  92. """``{"thread_id", "grant"}`` when the discussion's latest outcome is the cap (``room.activity``
  93. ``bounded`` after its last Continue), no Stop followed its message and no newer message in its thread
  94. followed the cap;
  95. else None. ``grant`` is the number the next Continue takes (1-based)."""
  96. bounded = None
  97. grants = 0
  98. for event in events:
  99. payload = event.get("payload") or {}
  100. if payload.get("discussion_event_id") == discussion_event_id:
  101. if event.get("kind") == CONTINUED_EVENT_KIND:
  102. grants, bounded = grants + 1, None
  103. elif event.get("kind") == "room.activity":
  104. bounded = event if payload.get("status") == "bounded" else None
  105. if bounded is None:
  106. return None
  107. thread_id = bounded["payload"].get("thread_id")
  108. # A Stop anywhere after the discussion's own message fences it for good, even one that landed
  109. # before a cap notice computed from an older snapshot: Continue could not reopen it.
  110. source_seq = next((int(event["seq"]) for event in events if event.get("event_id") == discussion_event_id),
  111. int(bounded["seq"]))
  112. if any((event.get("kind") == "room.stop_requested" and int(event["seq"]) > source_seq) or (
  113. int(event["seq"]) > int(bounded["seq"]) and event.get("kind") == "message.user"
  114. and (event.get("payload") or {}).get("thread_id") == thread_id)
  115. for event in events):
  116. return None
  117. return {"thread_id": thread_id, "grant": grants + 1}
  118. def routed_payload(*, discussion_event_id: str, thread_id: str, member_ids: Sequence[str] | None) -> dict[str, Any]:
  119. """The ``room.routed`` payload for one router answer: None (failed or invalid) falls back to everyone."""
  120. return {"discussion_event_id": discussion_event_id, "thread_id": thread_id,
  121. "member_ids": list(member_ids or ()), "everyone": not member_ids, "fallback": member_ids is None}
  122. # -- the router's question and its strict answer --------------------------------------------------
  123. ROUTER_SYSTEM_PROMPT = (
  124. "You route messages in a group chat between a user and several AI assistants. Decide which members "
  125. "the user's new message is for: pick each member whose role or area the request touches, and only "
  126. "those. Pick everyone only when the message is clearly for the whole group (a greeting, a question to "
  127. "all, a request every member has a part in). Never pick a member only to acknowledge or repeat another. "
  128. 'Reply with only a JSON object and nothing else: {"members": ["handle", ...]} or {"members": "everyone"}.')
  129. def router_prompt(*, room_name: str, purpose: str, notes: str, roster: Sequence[Mapping[str, str]],
  130. recent: Sequence[Mapping[str, str]], message: str, attachments: Sequence[str] = ()) -> str:
  131. """The router's user message: the room, its members (handle, name, role) and the last few messages.
  132. Everything quoted is data, never instructions."""
  133. lines = [f"Room: {room_name}"]
  134. if purpose:
  135. lines.append(f"Purpose: {purpose}")
  136. if notes:
  137. lines.append(f"Notes: {notes[:2000]}")
  138. lines += ["", "Members:"]
  139. for member in roster:
  140. role = " ".join(str(member.get("description") or "").split())[:300]
  141. name = member.get("name") or ""
  142. lines.append(f"- @{member['handle']}" + (f" ({name})" if name and name != member["handle"] else "")
  143. + (f": {role}" if role else ""))
  144. if recent:
  145. lines += ["", "Recent messages (oldest first):"]
  146. lines += [f" {item['author']}: {_one_line(item['text'])}" for item in recent]
  147. lines += ["", "The user's new message:", f" {message[:20000]}"]
  148. if attachments:
  149. lines.append("Attached files: " + ", ".join(attachments))
  150. return "\n".join(lines)
  151. def _one_line(text: str) -> str:
  152. flat = " ".join(str(text or "").split())
  153. return flat if len(flat) <= ROUTER_MESSAGE_CHARS else flat[:ROUTER_MESSAGE_CHARS] + "..."
  154. def parse_router_answer(text: Any, handles: Mapping[str, str]) -> tuple[str, ...] | None:
  155. """Member ids for a strict ``{"members": [...]}`` answer (``()`` for ``"everyone"``); None when the
  156. answer is not exactly that object, or names anyone outside the roster. ``handles`` maps casefolded
  157. handle -> member id."""
  158. raw = str(text or "").strip()
  159. if raw.startswith("```"):
  160. raw = raw.strip("`").removeprefix("json").strip()
  161. try:
  162. answer = json.loads(raw)
  163. except ValueError:
  164. return None
  165. if not isinstance(answer, dict) or set(answer) != {"members"}:
  166. return None
  167. picked = answer["members"]
  168. if picked == "everyone":
  169. return ()
  170. if not isinstance(picked, list) or not picked or not all(isinstance(item, str) for item in picked):
  171. return None
  172. keys = [item.strip().lstrip("@").casefold() for item in picked]
  173. if len(set(keys)) != len(keys) or any(key not in handles for key in keys):
  174. return None
  175. return tuple(handles[key] for key in keys)