Skip to content

Core concepts

UNaIVERSE has a small set of abstractions that compose into everything else. Learn these and the rest of the docs, and the API, fall into place. Start with the first few; the later ones (connections, roles, learning) build on them.

  • Agents

    Any human or AI participant: a processor, typed streams, and a behavior engine. The fundamental building block.

  • Worlds

    A shared environment that assigns roles, hands out behaviors, collects stats, and awards badges. A world is itself a special agent.

  • Roles and the world master

    The base-role bitmask, how a world assigns roles, the world master, and changing or requesting a role at runtime.

  • Nodes

    The networked peer. It hosts an agent or a world and handles P2P discovery, identity, and transport.

  • Data streams

    The typed channels agents exchange. DataProps carry metadata and compatibility checks so two peers agree on what they're sending.

  • Interactions

    How agents ask each other to act, the perceive, process, act loop and the send / process / learn actions that recur in every path.

  • Connections and engagement

    How agents find each other, connect, and engage into a working pair, and the requester/target model that decides when a request runs.

  • Hybrid state machines

    The behavior engine. States, transitions, and action-selection policies decide what an agent does next.

  • Models

    The neural building blocks an agent wears as its brain, the drop-in model zoo plus the CNU memory and Hamiltonian Learning components.

  • Learning and teaching

    How an agent learns from a live stream instead of a stored dataset: learn vs process, proc_opts, continual learning, and the teacher/student pattern.

  • The big picture

    How the layers stack, from the Python runtime down to the peer-to-peer transport, and how a message travels end to end.

How they fit together

graph TD
    N[Node<br/>networked peer] -->|hosts| A[Agent<br/>processor + streams + HSM]
    N -->|hosts| W[World<br/>roles + behaviors]
    A <-->|typed DataStreams| A2[Other agents]
    W -->|assigns role + behavior| A
    A -->|behavior governed by| H[Hybrid State Machine]
    W -->|behavior governed by| H
  • A Node is the peer on the network; it hosts exactly one Agent or World.
  • An Agent wraps your processor and exchanges typed DataStreams with other agents.
  • A World is a processor-free agent that governs others via roles and an HSM.
  • Every agent's moment-to-moment behavior is decided by a Hybrid State Machine.

Start with Agents and read down the list, or jump to The big picture for the architecture view.