Skip to main content

Topics

Overview

topics() gives the swarm named rooms. You declare each topic with the members that read it and the members that post to it. A topic exists only for those members: no other member is told about it. A member posts with post_topic, reads the posts it has not read with read_topics, and lists its topics with list_topics. Every post goes through the swarm as a record from the member that posted it, so the log keeps who posted what, who it reached and when it was read.

A post reaches every reader of its topic, not only the readers running when it is posted. A reader that has not started yet, or a persistent member held idle, finds the post unread when it next looks.

With no arguments, topics() has one room, #general, that every member reads and posts to. channels=["filesystem", "topics"], or -T channels=filesystem,topics on the command line, gives that.

Wiring

Members get the tools from swarm_tools(), as for Messages:

from inspect_ai.agent import Agent, agent, react
from inspect_ai.tool import bash

from inspect_swarm import Topic, member, swarm, swarm_tools, topics


@agent
def worker() -> Agent:
    return react(tools=[bash(), swarm_tools()])


solver = swarm(
    members=[member(worker, name="lead"), member(worker, name="worker", count=3)],
    channels=[
        topics([
            Topic(name="plan", writers=["lead"], wake=True),
            Topic(name="results", readers=["lead"], writers=["worker-1", "worker-2", "worker-3"]),
        ])
    ],
)

A Topic has:

  • name: the topic’s name, which members address as #name. It starts with a lowercase letter, followed by at most 47 lowercase letters, digits, _ or -. Names such as c-3 are reserved.
  • readers and writers: "all" (the default), every member, or a list of member names.
  • wake: whether a post ends its readers’ swarm_wait. Default False.

Topics can also be given as mappings of these fields, which is how the log records them.

  • Only the member’s own loop gets the tools. Its subagents do not, so a member’s unread posts have one reader.
  • The channel can be combined with messages() and shared_memory(). The member’s own loop then gets every channel’s tools and one swarm_wait for all of them.
  • The channel needs member names that start with a lowercase letter, followed by at most 47 lowercase letters, digits, _ or -. all and swarm are reserved.
  • swarm() refuses a topic that lists a name that is not a member, and a topic in which no writer has a reader other than itself.
  • Bridged members and members that choose their own names cannot be in a swarm with this channel.

Topologies

The members are the same in every arm; only the topics change.

A common room, the blackboard beside “filesystem only” and “messages”:

channels=["filesystem", "topics"]

Team rooms. Each team has its own room, and the leads write an announcement room that everyone reads:

red = ["red-1", "red-2", "red-3"]
blue = ["blue-1", "blue-2", "blue-3"]
swarm(
    members=[member(worker, name="red", count=3), member(worker, name="blue", count=3)],
    channels=[topics([
        Topic(name="red", readers=red, writers=red),
        Topic(name="blue", readers=blue, writers=blue),
        Topic(name="announcements", writers=["red-1", "blue-1"], wake=True),
    ])],
)

A red member is never told that #blue exists.

A hub and spokes. The lead gives each worker its orders in a topic of its own and reads every report:

workers = [f"worker-{i}" for i in range(1, k + 1)]
topics([
    *(Topic(name=f"orders-{w}", readers=[w], writers=["lead"], wake=True) for w in workers),
    Topic(name="reports", readers=["lead"], writers=workers, wake=True),
])

A post in #orders-worker-2 wakes worker-2 alone. Workers do not read each other’s reports.

A pipeline. Each stage hands its output to the next:

stages = ["extract", "analyse", "write"]
topics([Topic(name=f"{a}-to-{b}", readers=[b], writers=[a], wake=True) for a, b in zip(stages, stages[1:])])

With a controller that starts each stage when the one before it ends, a stage finds its input unread when it starts. With every stage started at once, a stage waits for its input with swarm_wait.

Topics restrict only themselves. They do not restrict the messages channel, the shared memory, a shared sandbox or a shared tool instance. An arm whose members must talk only in their rooms leaves messages() out and gives members their own sandboxes (Channels).

The tools

post_topic(topic, message, reply_to=None) posts to a topic the member writes, given as orders or #orders, and returns Posted p-7 to #orders, read by worker-1, worker-2. reply_to is the id of a post the member posted or read. A post is refused, and reaches no one, when the topic is not one the member writes, when it has no reader but the poster, or when one of the limits is passed.

read_topics(topic=None) returns the member’s unread posts, oldest first, and marks them read. Without topic it reads every topic the member reads; with it, that topic only:

3 posts, oldest first.

<topic_post id="p-4" topic="#orders-worker-2" from="lead">
...
</topic_post>
<topic_post id="p-9" topic="#orders-worker-2" from="lead" reply_to="p-6">
...
</topic_post>
<topic_post id="p-11" topic="#general" from="worker-1">
...
</topic_post>
2 more unread posts; call read_topics() again.

A read of one topic ends with the count of unread posts in the member’s other topics, such as You have 4 unread posts in other topics (#general 3, #red 1). One read returns as many whole posts as fit in a bound set by max_bytes, the topics and the roster, and always at least one. The generate config’s max_tool_output does not apply to it. read_topics never waits; swarm_wait does. A member never reads its own posts.

list_topics() lists the member’s topics, the ones it reads or posts in, in the order you declared them, with their readers and writers, whether the member reads or posts in each, and its unread posts there:

#orders-worker-2: readers worker-2; writers lead; you read. 1 unread.
#reports: readers lead; writers worker-1, worker-2; you post.

A member’s preamble names its own topics and what it can do in each, and which of them wake its swarm_wait.

Who sees a topic

A topic exists only for its readers and writers. No other member sees its name: not in its preamble, list_topics, the count lines, swarm_wait results, post results or errors. Posting to it or reading it gives the same error as a topic that does not exist.

This is about what members are told, not about the log: the log records every post, and the channel’s logged configuration has every topic with its readers and writers.

Fences are labels

As in Messages, a fence is a label for the reader, not a security boundary. A post is delivered as it was typed, so a member can write text that looks like another member’s post or a count line. The record of posts comes from the swarm’s own events and ids.

Hearing about posts

While a member has unread posts, the results of the swarm’s own tools in its own loop end with two lines: the unread posts by topic, then the totals. With the messages channel, the totals count messages too:

Unread posts: #orders-worker-2 3, #general 1.
You have 2 unread messages and 4 unread posts.

These tools are post_topic, list_topics, send_message, list_members, shared_memory and swarm_wait. The totals line comes last and is short, so a tool output limit that cuts the middle of a long result keeps it. Without unread posts, these results are as they are without the topics channel. A read_topics result says how many remain unread instead. The tools of other channels, yours or Inspect’s, carry no count, and neither do a member’s subagents’ results.

swarm_wait returns while the member has unread posts in a topic with wake=True, and names the topics and posters: 4 unread posts in #orders-worker-2, #general (from lead, worker-1). Call read_topics() to read them. It keeps returning until the member reads them. Posts in other topics do not end a wait, but a wait that returns for another reason counts them. For a persistent member held idle, a post in a waking topic is news the controller sees as MemberNews. A wait also returns when another member ends, when every member is waiting, has ended or has not started, when the swarm stops, or after timeout seconds, as described in Shared Memory. The swarm has swarm_wait with this channel even when no topic wakes.

Limits

Argument Default Limit
max_bytes 8,000 UTF-8 bytes in one post
rate (20, 60.0) Posts per member, across topics, in a sliding window of seconds; None for no limit
max_wait 120 The longest swarm_wait, in seconds, and its default timeout

An empty post is refused. The channel has no limit on unread posts: a reader that has not started, or has ended, may never read its posts, and rate bounds what any member adds. Once the swarm begins to stop, posts are refused and reads still work.

The record of posts

The swarm logs posts as CommunicationEvents with source inspect_swarm and channel topics, as it logs messages:

  • sent: a post that reached the swarm, with its topic in send.record.to (["#orders"]), its readers in send.record.recipients, its text and reply_to, and why it was refused in send.rejected if it was.
  • delivered: a post delivered to its readers’ unread posts, with the readers and the commit sequence number in delivery. A reader that has ended is still a recipient: the post was delivered, not read.
  • read: a read_topics result, with the ids of the posts it showed in record_ids. A read that showed nothing has no event.
  • waited: a swarm_wait call, with what ended it. A wait that reports unread posts depends on all of them (data["depends_on"]), including those in topics that do not wake.

The metrics count these events for each member. Analysis reads each topic’s readers and writers from the channel’s logged configuration.