Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
"""Decision routing: the decision service picks who answers a message that no
rule delivered to anyone.
In a room with automatic routing on (`!auto-route on`, on a server with the
`decision_routing` feature, in a workspace with a decision backend:
`decision/settings.py`), a person's text message that names nobody and that
no follow-up or assigned agent took is marked undecided as it is written
(`MessageRouter._follow_the_conversation`). It passed the same filters as a
follow-up (`may_follow`): a person sent it, it has no `@` in it, it is not
Switch's own or another app's, it is not in a direct room, and it is not
thanks or praise (`is_small_talk`). In a workspace with no backend nothing is
marked, and rooms behave as they do without auto-route.
Marking it writes a `pending_decisions` row in the transaction that writes
the message, so a decision survives a restart. Once the message has
committed, the process that wrote it is woken to decide it, and every process
sweeps for waiting rows (`MessageRouter.decide_pending`), so a slow or failed
decision never holds up the write, and a room's messages are decided in
order:
1. The candidates are the room's agents other than the sender whose
addressing policy and budget let the sender through, as for a mention,
but without a refusal. With none, the service is not asked.
2. The service is sent the room's context (`decision_request`), read in a
session closed before the call.
3. When it names a candidate, the agent is checked once more, after the
call: still in the room, its policy and budget still letting the sender
through. Then, in one transaction, the pending row is deleted and the
person's own message is stored as the agent's own event, addressed and
marked routed (`routed_reason: "decided"`), under the message's key and
place in the room, so it is never delivered twice. It doesn't count as the
person addressing the agent, so the person's next untagged message is
decided again rather than followed up.
Nobody receives the message when the service names nobody. When the service
fails (a timeout, a connection error, an error response, a malformed one, or
one naming an agent that was not a candidate), the room is told auto-route is
unavailable (`DECISION_NOTICE`), at most once an hour, and the message goes
to the room's triage agent if it has one (`!auto-route fallback @agent`),
through the same checks, marked `routed_reason: "fallback"`; otherwise to
nobody. A message still waiting after `DECISION_PENDING_MAX_AGE_SECONDS` is
dropped and logged rather than answered late. Every decision is logged at
INFO.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Literal
from sqlalchemy import select
from switch_core.clients.admin_messages import PLATFORM_MARKER, platform_on_behalf_of
from switch_core.db.models import Client, ClientRoom, ExternalUser
from switch_core.decision.client import (
ContextMessage,
DecisionAgent,
DecisionMessage,
DecisionRequest,
DecisionRoom,
)
from switch_core.delivery.conversation import (
CHANNEL_LOOKBACK,
is_automatic,
mentioned_names,
)
if TYPE_CHECKING:
from collections.abc import Mapping
from sqlalchemy.ext.asyncio import AsyncSession
from switch_core.db.models import Message, Room
from switch_core.delivery.conversation import RoomConversation
from switch_core.delivery.recipient import AgentRecipient, RoomMember
from switch_core.transport.types import InboundMessage
# What the room is told when its decision backend fails, at most once every
# `DECISION_NOTICE_EVERY_SECONDS` (room metadata `decision_notice_at`), and
# never for a decision of nobody.
DECISION_NOTICE = "Auto-route is unavailable right now; tag an agent to reach it."
DECISION_NOTICE_EVERY_SECONDS = 3600
# The most of a thread's latest messages, and of the room's latest top-level
# messages, sent as context: enough to see who is talking to whom, and short
# enough to keep the decision quick.
THREAD_CONTEXT = 30
RECENT_CONTEXT = CHANNEL_LOOKBACK
async def decision_request(
session: AsyncSession,
*,
room: Room,
members: list[RoomMember],
roles: Mapping[str, str],
conversation: RoomConversation,
message: InboundMessage,
candidates: list[AgentRecipient],
) -> DecisionRequest:
"""What the decision service is sent about `message`.
`members` are the room's agents and `roles` the role each live-holds
here, by agent id. The thread and the recent messages are the ones the
follow-up rules read (`conversation`), as they stood when the message was
written: anything written after it is left out.
"""
names = _Names(members, roles, await _people(session, room.id))
thread = await _context(
session, conversation, names, await conversation.thread(session), message
)
recent = await _context(
session, conversation, names, await conversation.channel(session), message
)
return DecisionRequest(
room=DecisionRoom(name=room.name, instructions=room.instructions),
message=DecisionMessage(
sender=_person_name(message.content, message.sender_name, message.sender),
text=message.body,
thread_id=message.thread_root_id,
),
agents=[
DecisionAgent(
name=candidate.agent.name,
description=candidate.agent.description,
role=roles.get(candidate.agent.id),
)
for candidate in candidates
],
thread=thread[-THREAD_CONTEXT:],
recent=recent[-RECENT_CONTEXT:],
)
class _Names:
"""Who the room's messages come from and whom they address, by name."""
def __init__(
self,
members: list[RoomMember],
roles: Mapping[str, str],
people: set[str],
) -> None:
self._agents = {
member.transport_user_id: member.agent.name for member in members
}
# Every handle that reaches an agent here, lowercased, to the agent's
# name: its name, its alias and the role it holds.
self._handles: dict[str, str] = {}
for member in members:
name = member.agent.name
self._handles[name.lower()] = name
if member.alias:
self._handles[member.alias.lower()] = name
role = roles.get(member.agent.id)
if role:
self._handles[role.lower()] = name
self._people = {person.lower(): person for person in people}
def agent(self, transport_user_id: str) -> str | None:
return self._agents.get(transport_user_id)
def addressed(self, body: str) -> list[str]:
"""The room members `body` @-mentions, by name, in a stable order."""
found: set[str] = set()
for handle in mentioned_names(body):
if handle in self._handles:
found.add(self._handles[handle])
elif handle in self._people:
found.add(self._people[handle])
return sorted(found)
async def _people(session: AsyncSession, room_id: str) -> set[str]:
"""The names the room's other members go by and are tagged with: their
display names, and a platform user's username there."""
rows = (
await session.execute(
select(Client.display_name, ExternalUser.external_username)
.select_from(ClientRoom)
.join(Client, Client.id == ClientRoom.client_id)
.outerjoin(ExternalUser, ExternalUser.client_id == Client.id)
.where(ClientRoom.room_id == room_id, Client.type != "agent")
)
).all()
return {name for row in rows for name in row if name}
async def _context(
session: AsyncSession,
conversation: RoomConversation,
names: _Names,
rows: list[Message],
message: InboundMessage,
) -> list[ContextMessage]:
"""`rows` (newest first) as context for the decision, oldest first: the
messages people and agents wrote before `message`. Switch's own notices,
automatic replies and anything that is not a text message are left out."""
context: list[ContextMessage] = []
for row in rows:
if (
row.seq >= message.seq
or row.event_type != "m.room.message"
or not (row.body or "").strip()
or is_automatic(row)
):
continue
said = await _said_by(session, conversation, names, row)
if said is None:
continue
sender, kind = said
context.append(
ContextMessage(
sender=sender,
sender_kind=kind,
text=row.body or "",
addressed=names.addressed(row.body or ""),
)
)
context.reverse()
return context
async def _said_by(
session: AsyncSession,
conversation: RoomConversation,
names: _Names,
row: Message,
) -> tuple[str, Literal["person", "agent"]] | None:
"""Who wrote `row` and whether a person or an agent; None for Switch's
own messages, and for a sender that is neither."""
content = row.content or {}
if PLATFORM_MARKER in content:
# Switch's app speaking for someone, whom the marker names.
speaker = platform_on_behalf_of(content)
if speaker is None:
return None
return speaker.name, "agent" if speaker.agent_id is not None else "person"
kind = await conversation.sender_kind(session, row)
if kind == "agent":
return names.agent(row.sender_id) or row.sender_name or row.sender_id, "agent"
if kind == "user":
return _person_name(content, row.sender_name, row.sender_id), "person"
return None
def _person_name(
content: Mapping[str, object], sender_name: str | None, sender: str
) -> str:
"""The name a person goes by in the room: the person a platform message
speaks for, else the name their message carries, else their id's
localpart."""
speaker = platform_on_behalf_of(content)
if speaker is not None:
return speaker.name
named = content.get("sender_name") or sender_name
if named:
return str(named)
return sender.split(":")[0].lstrip("@")