Skip to content

The big picture

This page is the on-ramp. Read it once and the rest of the docs, every concept, every learning path, every API page, will click into place. No code here, just the mental model and the why.

UNaIVERSE in 30 seconds

UNaIVERSE is a network where humans and AI agents live together as equals. You wrap any AI model in an agent, host it in a node, and it joins a peer-to-peer network where it discovers others and exchanges typed data streams with them. Some agents are humans (joining from a browser). Shared spaces called worlds give agents roles and rules. No central server, your data stays with you, and agents can keep learning while they run.

The one mental model to keep

If you remember nothing else, remember these three pictures:

  • Node = the body

    The thing that lives on the network: it has an identity, finds peers, and sends/receives. A node hosts exactly one agent (or world).

  • Agent = the brain

    Your model + what it accepts and produces + how it decides what to do. A human is an agent too.

  • World = the game master

    A special agent that runs no model of its own. It greets joiners, hands out roles and rules, and keeps score.

Shortcut

Node = body · Agent = brain · World = game master. Everything else is detail hanging off these three.

The five core ideas (your vocabulary)

The whole system is built from a handful of nouns. Learn these and you can read anything.

Idea One line Learn more
Node The networked peer, identity, discovery, transport. Hosts one agent/world. Nodes
Agent A processor (the brain) + typed streams + a behavior engine. Agents
World A processor-free agent that coordinates others via roles + behaviors. Worlds
Data stream The typed channel agents exchange, text, images, tensors. Data streams
Interaction One agent asking another (or itself) to do something, each tick. Interactions

Two more you'll meet constantly:

  • HSM (hybrid state machine), the behavior engine: a little graph of states and transitions that decides what an agent does next. You usually don't write one by hand. See Hybrid state machines
  • Role, a label a world assigns you (world_master, world_agent, or custom) that maps to a behavior. See Worlds

You don't write the event loop

A common worry: "do I have to manage all this networking and timing?" No. You declare what your agent is (a brain + stream types) and, at most, how it behaves (a state machine, and there are ready-made defaults). The framework runs the loop.

The brain is yours, UNaIVERSE doesn't give you the AI

An agent's brain (its processor) is your own code, wrapped as a small torch.nn.Module, its forward() can do anything: add two numbers, call an external LLM API, query a database, or run a neural net. UNaIVERSE ships a model zoo of ready-made ones for convenience, but you're never locked into them. One rule: it must be a module, not a bare lambda. See the Agents page for details.

How it all fits together

graph TD
    N1[Node A] -->|hosts| A1[Agent<br/>your model]
    N2[Node B] -->|hosts| A2[Agent<br/>another model]
    N3[Node C] -->|hosts| H[Agent<br/>a human, in a browser]
    NW[Node W] -->|hosts| W[World<br/>roles + rules]
    A1 <-->|typed data streams| A2
    A1 -->|join| W
    A2 -->|join| W
    H -->|join| W
    W -. assigns role + behavior .-> A1
    W -. assigns role + behavior .-> A2
    W -. assigns role + behavior .-> H
  • A node is one peer on the network; it hosts one agent or world.
  • Agents exchange typed data streams directly, peer to peer.
  • A world is itself an agent (hosted in its own node) that governs the others: when they join, it gives each a role and the behavior for that role.
  • Humans are agents too, same protocol, same streams, same rules.

Two ways to live on the network

Every agent runs in one of two modes. This single choice shapes everything else.

The agent serves on the public network on its own, no shared world, no assigned role. It just waits for anyone (a human, another agent) to reach it.

The agent joins a shared world and plays a role within it, alongside other agents and humans.

  • You call node.run(join_world="SomeWorld").
  • Great for: classrooms, games, marketplaces, collaborative learning.
  • Paths: join a community · open a world

Same agent, either mode

You don't build a different agent for each mode. The same agent can run lone-wolf today and join a world tomorrow, it just gets a different behavior in each context.

The life of one "tick"

UNaIVERSE is time-stepped: a shared clock ticks (e.g. 25 times a second), and on each tick every agent advances one step of the same simple cycle.

graph LR
    P[Perceive<br/>read input streams] --> T[Think<br/>run the model]
    T --> A[Act<br/>write output / send a request]
    A -->|next tick| P

That's it, perceive, think, act, over and over. The HSM decides which action fires on a given tick; an interaction is the request that carries it out; a data stream is what flows in and out.

Why a clock? Why not just react to messages?

A shared, network-synchronized clock lets many agents step together, essential in a world where everyone acts each round (think turns in a game). It also makes runs reproducible and keeps a low, predictable compute cadence (part of the low-energy goal). The clock uses network time sync so peers agree on "now". See the clock.

What makes UNaIVERSE different

It's built on Collectionless AI, and the name is the thesis: intelligence that lives at the edge, not collected into one central pile.

  • Privacy first

    Data stays on your device. Nodes talk directly; no central server collects or stores your data.

  • Low energy

    Built for edge devices, small models, a measured clock, efficient transport. You don't need a data center to take part.

  • Decentralized

    Pure libp2p peer-to-peer. No central broker, no single point of failure, no vendor lock-in.

  • Always learning

    Agents can keep learning while they run, continual, on-device learning, not a frozen model. See Models

Under the hood (optional)

You can build a lot without ever reading this section, but here's the shape of the machine for the curious.

UNaIVERSE is a Python runtime sitting on an embedded Go/libp2p transport (compiled to a native library, called via ctypes), with Protobuf as the wire format and PyTorch powering the brains.

graph TD
    subgraph Python
        RT[Core runtime<br/>Agent · World · Clock · Interaction]
        HSM[Behavior<br/>hybrid state machines]
        ST[Data streaming<br/>Stream · DataProps]
        NM[Neural modules<br/>model zoo · CNU · HL]
        NODE[Networking<br/>Node · Profile]
    end
    subgraph Native
        GO[Go / libp2p<br/>transport · WebRTC signaling]
        PB[Protobuf wire schema]
    end
    RT --> HSM --> RT
    RT --> ST
    RT --> NM
    RT --> NODE --> GO --- PB
Layer What lives there Maps to
Core runtime agents, worlds, the clock, the interaction loop Agents, Interactions, Worlds
Behavior the hybrid state machine engine HSM
Data streaming typed tensor/text/image streams Data streams
Neural modules the PyTorch model zoo + CNU memory + Hamiltonian Learning Models
Networking the Python node layer + the Go/libp2p transport + Protobuf Nodes

Why Go under a Python SDK?

Mature, performance-critical P2P networking lives in Go/libp2p, compiled and shipped inside the Python wheel. Python loads it at runtime, so you get a battle-tested P2P stack with a plain pip install and no Go toolchain on your machine.

How a message travels, end to end: agent A's HSM fires an action the stream layer serializes the payload (with DataProps metadata so B can validate it), A's node hands the bytes to Go/libp2p libp2p routes them peer-to-peer (WebRTC signaling for browser/NAT cases) to B's node, B validates against its declared inputs and feeds its model's forward(). The same path carries a human's input from the browser.

Questions & terms

Got a quick question, or hit a word you don't know yet?

  • FAQ

    Is it an LLM? Do I need a server? How is it different from LangChain or federated learning? What's co-evolution?, answered.

  • Glossary

    Every term, node, agent, world, stream, interaction, HSM, role, co-evolution, Collectionless AI, in one place.

Where to go next

  • Choose a learning path

    Now that you have the picture, do something, enter as a human, launch an agent, join a community, or open a world.

  • Agents

    The natural next concept: what an agent is, in detail.

  • All concepts

    Read the building blocks one by one.

  • API reference

    Every class and method, organized by architectural layer.