Worlds¶

A World is a shared UNaIVERSE environment that assigns roles, loads behaviors, collects stats, and coordinates multiple agents toward a common task.

A World is a specialized UNaIVERSE node that has no AI processor of its own. Its job is pure orchestration: when other Agents connect, the World greets them, assigns them a role, hands each role a behavior configuration, collects statistics as the session runs, and awards badges when Agents complete tasks. Think of a World as the game master at a table, it defines the rules and keeps score, but the players do all the actual work.

What a World Does¶

Role Assignment

Every Agent that joins is immediately assigned a role. The first connector becomes the world_master; everyone else becomes a world_agent. You can override assign_role() to implement custom role logic.
Behavior Configuration

Each role maps to a JSON state machine file stored in the world_folder directory. The World loads the correct file and hands it to the joining Agent so the Agent knows exactly what to do.
Statistics Collection

Agents periodically push stats (connected peers, current state, action history) back to the World. The World aggregates these into a time-series store for monitoring and replay.
Badge System

Worlds can award badges to Agents based on performance. Agents can also suggest badges to the World via suggest_badges_to_world(), and the World validates and records them.

Creating a World¶

In practice you subclass World and point it at a world folder, the directory that holds your role agent classes and the generated per-role behavior files. The base constructor takes the folder as its only required argument:

import os
from unaiverse.world import World


class MyWorld(World):
    def __init__(self, **kwargs):
        world_folder = os.path.dirname(os.path.abspath(__file__))
        super().__init__(world_folder=world_folder, **kwargs)

world_folder str · required: Path to the directory that contains the per-role agent classes and the generated behavior JSON files. This is the only required argument.

A typical world_folder (modelled on the chat example) looks like this:

my_world/
├── world.py            # the World subclass (assign_role + create_behav_files)
├── user.py             # the "user" role's Agent subclass + its @action methods
├── broadcaster.py      # the "broadcaster" role's Agent subclass
├── stats.py            # optional: custom stats for this world
├── user.json           # GENERATED behavior for the "user" role
├── broadcaster.json    # GENERATED behavior for the "broadcaster" role
└── stats/              # auto-created for stats storage

The behavior file names match the role names your assign_role() returns. Each JSON file is a serialized HybridStateMachine that UNaIVERSE loads automatically when an Agent with the matching role connects. See State Machine for the JSON format.

Defining behaviors: `create_behav_files()`¶

You don't hand-write the behavior JSON. You override create_behav_files(), build each role's HSM in code, and save() it into the world folder. Crucially, each behavior is built against the agent class that will play that role, so the HSM can validate the custom actions it references.

def create_behav_files(self):
    from .user import WAgent as UserAgent
    behav = HybridStateMachine(UserAgent(proc=None))   # validate against the user class
    behav.set_role("user")
    behav.add_state("ready", action="check_messages", args={"max_silence_seconds": 25.0})
    # ... states & transitions ...
    behav.save(os.path.join(self.world_folder, "user.json"))

Each role's custom actions (check_messages, broadcast_message, …) are plain methods on that Agent subclass, decorated with @action. Built-in actions (connected, process, send, nop, …) are available to every role for free. See the world-builder path for a complete, runnable example.

Role Assignment¶

When an Agent connects to a World, the World calls assign_role() to determine what role that Agent will play. The default logic is straightforward:

The first Agent to connect with a world_master claim becomes the world_master (role bits 3).
All subsequent Agents, regardless of what they claim, become world_agent (role bits 1).

You can subclass World and override assign_role() to implement any logic you need: round-robin, capability-based, credential-based, or anything else.

class MyWorld(World):
    def assign_role(self, profile, is_world_master):
        # Example: assign role based on a profile field
        if profile.get_static_profile().get("specialty") == "teacher":
            return "world_master"
        return "world_agent"

Badge System¶

Worlds track Agent performance through a lightweight badge system. Badges have a type and an optional score, making it easy to build leaderboards or certification workflows.

# Award a badge to a specific agent
world.add_badge(
    peer_id="<agent_peer_id>",
    score=0.97,
    badge_type="completed",        # one of: completed, attended, intermediate, pro
    agent_token="<token>",
    badge_description="Passed the image classification challenge"
)

# Retrieve all badges recorded so far
all_badges = world.get_all_badges()  # dict: peer_id -> list[dict]

# Reset the badge store
world.clear_badges()

Badge types built into UNaIVERSE:

Badge type	Typical meaning
`completed`	Agent finished the task
`attended`	Agent was present for the session
`intermediate`	Agent reached an intermediate milestone
`pro`	Agent demonstrated professional-level performance

Built-in Example Worlds¶

UNaIVERSE ships with a collection of ready-to-run example Worlds that cover a wide range of multi-agent scenarios:

💬 Chat

LLM-based broadcast chat. Human and AI agents exchange messages in real time, with a broadcaster role routing every message to everyone.
🐾 Animal School

Continual learning from live image streams. Teaching agents stream labeled animal images; student agents learn on the fly.
📚 Cat Library

Poem memorization using state-space models. Agents reproduce sequences of tokens from a growing library.
🔢 Class-Incremental Learning

Teacher agents present new classes over time; student agents learn them incrementally without forgetting.
🌐 Info Extraction

Extractor agents cooperate to pull structured information from a shared image feed.
📡 Signal School

Signal reproduction with forward learning. Agents learn to reproduce waveform streams sent by teacher agents.

Run a whole world on one machine

Every example World in the UNaIVERSE examples repository can be run locally with NodeSynchronizer, which simulates the full P2P environment on a single machine without needing network access. Each example ships a run_synch.py that stitches the world runner and all the agent runners into one synchronized process:

python worlds/run_synch.py chat

This makes it easy to prototype, debug, and iterate on new World designs before deploying them online.