Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""The Dodaios Verse level system's rulebook: pure tables, no I/O.
The Verse is the interior of a fleet capital ship. Three kinds of subject
serve aboard and level up:
* ``person`` — the commanding officer, the person at the keyboard (one
subject, id ``person``);
* ``agent`` — every agent on the society roster, an officer of the crew
(``agent:<agent_id>``);
* ``pet`` — the person's pet from My Pets, the commander's companion drone
(``pet:<pet_id>``; each pet keeps its own level, the active one earns). The
lead agent is drawn as the companion, so the lead's work pays the pet.
XP only ever comes from a rule in :data:`RULES`. A rule names its source, the
subject kind it pays, a fixed amount, an optional cooldown and an optional
daily cap. Server rules are read off real bus events (a finished turn, a
finished task); world rules are small actions aboard the ship that the client
reports and the server still meters. Nothing here calls a model, so the
system works with any single key and costs no tokens.
The level curve is front-loaded the way long-running progression usually is:
level 2 arrives within the first few actions, level 10 after about a week of
ordinary use, level 50 after several months. Levels climb the fleet's rank
ladder (:data:`RANKS`) in four tiers, from recruit to fleet admiral, and open
the commander's uniforms and the ribbons of the service record
(:data:`REWARDS`). ``docs/agent-society/level-system.md`` is the readable
version of this file; parity tests pin the frontend's copies of the ids.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Final, Literal
SubjectKind = Literal["person", "agent", "pet"]
SUBJECT_KINDS: Final[tuple[SubjectKind, ...]] = ("person", "agent", "pet")
#: The id of the one person subject.
PERSON_ID: Final[str] = "person"
MAX_LEVEL: Final[int] = 50
#: Society roster id of the lead. The lead is drawn as the person's pet, so its
#: work pays the pet, never an ``agent:jarvis`` subject.
LEAD_AGENT_ID: Final[str] = "jarvis"
#: The ship's decks, top to bottom: the refs a ``deck_discovered`` or an
#: ``inspection`` report may name. The frontend's copy is
#: ``components/society/verse/decks.ts`` (``DECK_IDS``); a parity test holds
#: them together.
VERSE_DECKS: Final[tuple[str, ...]] = ("bridge", "ops", "engineering", "hangar")
def xp_to_next(level: int) -> int:
"""XP needed to climb from ``level`` to ``level + 1`` (0 at the cap).
40 XP for the first step, then a gently super-linear rise, rounded to 5
so the numbers read cleanly in the HUD.
"""
if level >= MAX_LEVEL:
return 0
if level < 1:
level = 1
raw = 40 + 25 * (level - 1) ** 1.1
return int(round(raw / 5.0) * 5)
def total_xp_for_level(level: int) -> int:
"""Total XP at which ``level`` is reached (level 1 = 0 XP)."""
level = max(1, min(MAX_LEVEL, level))
return sum(xp_to_next(step) for step in range(1, level))
def level_for_xp(total_xp: int) -> int:
level = 1
remaining = max(0, int(total_xp))
while level < MAX_LEVEL:
need = xp_to_next(level)
if remaining < need:
break
remaining -= need
level += 1
return level
@dataclass(frozen=True, slots=True)
class LevelProgress:
level: int
xp: int
#: XP gathered since the current level started.
into_level: int
#: XP the current level needs in total (0 at the cap).
for_next: int
def progress_for_xp(total_xp: int) -> LevelProgress:
total = max(0, int(total_xp))
level = level_for_xp(total)
into = total - total_xp_for_level(level)
return LevelProgress(level=level, xp=total, into_level=into, for_next=xp_to_next(level))
# ------------------------------------------------------------------ XP rules
Trigger = Literal["server", "world"]
@dataclass(frozen=True, slots=True)
class XpRule:
source: str
kind: SubjectKind
xp: int
trigger: Trigger
#: Minimum seconds between two awards of this rule to one subject.
cooldown_s: int = 0
#: Most XP one subject can earn from this rule per local day (0 = no cap).
daily_cap: int = 0
#: True: at most one award per ``ref`` ever (a deck is discovered once).
once_per_ref: bool = False
RULES: Final[tuple[XpRule, ...]] = (
# The commander: talking to the assistant, giving the crew work, growing the crew.
XpRule("chat_turn", "person", 5, "server", daily_cap=100),
XpRule("voice_turn", "person", 5, "server", daily_cap=100),
XpRule("quest_posted", "person", 15, "server", daily_cap=75),
XpRule("quest_completed", "person", 20, "server"),
XpRule("agent_hired", "person", 50, "server"),
XpRule("mission_completed", "person", 30, "server", daily_cap=150),
# The commander, aboard the ship.
XpRule("daily_visit", "person", 25, "world", once_per_ref=True),
XpRule("deck_discovered", "person", 20, "world", once_per_ref=True),
XpRule("simulator_round", "person", 8, "world", cooldown_s=45, daily_cap=80),
XpRule("simulator_record", "person", 15, "world", cooldown_s=45, daily_cap=60),
XpRule("team_briefing", "person", 10, "world", cooldown_s=600, daily_cap=40),
XpRule("inspection", "person", 15, "world", once_per_ref=True, daily_cap=30),
# The commander, in the hangar duel. Server rules: only a ``duel.result``
# reaches them (``record_duel``), never ``POST /actions``.
XpRule("duel_won", "person", 40, "server", daily_cap=200),
XpRule("duel_lost", "person", 10, "server", daily_cap=50),
XpRule("duel_finisher", "person", 5, "server", daily_cap=25),
# The crew: finished work is what counts.
XpRule("task_done", "agent", 40, "server"),
XpRule("task_blocked", "agent", 8, "server", daily_cap=40),
XpRule("quest_done", "agent", 60, "server"),
XpRule("answered_teammate", "agent", 5, "server", daily_cap=50),
# The companion drone carries the lead's work: every answer and every
# hand-off it makes, and the walks it takes at the commander's heel.
XpRule("jarvis_answered", "pet", 4, "server", daily_cap=120),
XpRule("delegated", "pet", 10, "server", daily_cap=100),
XpRule("walk_together", "pet", 3, "world", cooldown_s=20, daily_cap=60),
)
RULES_BY_SOURCE: Final[dict[str, XpRule]] = {rule.source: rule for rule in RULES}
#: Sources the client may report through ``POST /api/progression/actions``.
WORLD_ACTIONS: Final[frozenset[str]] = frozenset(r.source for r in RULES if r.trigger == "world")
#: Sources earlier builds paid that no rule pays any more. Ledger rows that
#: carry them still read and still count; they are only never paid again.
RETIRED_SOURCES: Final[frozenset[str]] = frozenset(
{
# The starship (2026-10): the holodeck became the simulator room, the
# helm and its destinations are gone.
"holodeck_round",
"holodeck_record",
"warp_jump",
# The office tower.
"floor_discovered",
"dog_petted",
"dog_treat",
"arcade_round",
"arcade_record",
"team_meeting",
}
)
# ------------------------------------------------------------------ duel rules
#: The duel sources, in rulebook order (``docs/verse/unreal/contracts/bridge-protocol.md`` 10).
DUEL_SOURCES: Final[tuple[str, ...]] = ("duel_won", "duel_lost", "duel_finisher")
#: ``duel.result`` outcomes, from the person's side: a finished set is won or
#: lost; a set left mid-way (or cut short by Verse quitting) is unfinished.
DUEL_OUTCOMES: Final[tuple[str, ...]] = ("won", "lost", "unfinished")
#: Why a set ended. ``crash_recovered`` is a pending result the next launch sent.
DUEL_END_REASONS: Final[tuple[str, ...]] = (
"set_complete",
"player_left",
"verse_quit",
"crash_recovered",
"app_quit",
)
#: Game modes whose sets pay XP in ``verse.bridge/1``. Every mode counts in the statistics.
DUEL_PAYING_MODES: Final[frozenset[str]] = frozenset({"deathmatch_1v1"})
#: A finished set shorter than this (match time, pauses excluded) pays nothing.
DUEL_MIN_PAYING_TIME_S: Final[float] = 60.0
#: More kills than one per this many seconds of match time is implausible; the
#: server clamps the numbers to this rate and logs it.
DUEL_SECONDS_PER_KILL: Final[float] = 2.0
#: Multiplier on ``duel_won`` by the opponent's tier; an adaptive bot pays as
#: ``adaptive`` whatever tier it started on. Unknown tiers pay 1.0.
DUEL_TIER_MULTIPLIERS: Final[dict[str, float]] = {
"normal": 1.0,
"hard": 1.5,
"elite": 2.0,
"adaptive": 1.5,
}
def duel_tier_key(opponent_kind: str, tier: str, adaptive: bool) -> str:
"""The key a set is filed and paid under: ``adaptive``, a bot tier, or ``player``.
``opponent.kind`` is ``bot`` or ``player`` (another person, later).
"""
if opponent_kind == "bot":
if adaptive:
return "adaptive"
return tier if tier in DUEL_TIER_MULTIPLIERS else "unknown"
return opponent_kind or "unknown"
def duel_awards(
*, mode: str, outcome: str, match_time_s: float, tier_key: str, finishers: int
) -> list[tuple[str, int]]:
"""The ``(source, xp)`` pairs one set pays before the daily caps.
Only a finished set (``won`` or ``lost``) of a paying mode that lasted at
least :data:`DUEL_MIN_PAYING_TIME_S` pays; ``unfinished`` never does. A won
set pays ``duel_won`` times the tier multiplier, a lost one ``duel_lost``;
either pays ``duel_finisher`` once per finisher.
"""
if mode not in DUEL_PAYING_MODES or outcome not in ("won", "lost"):
return []
if match_time_s < DUEL_MIN_PAYING_TIME_S:
return []
awards: list[tuple[str, int]] = []
if outcome == "won":
base = RULES_BY_SOURCE["duel_won"].xp
awards.append(("duel_won", int(round(base * DUEL_TIER_MULTIPLIERS.get(tier_key, 1.0)))))
else:
awards.append(("duel_lost", RULES_BY_SOURCE["duel_lost"].xp))
if finishers > 0:
awards.append(("duel_finisher", RULES_BY_SOURCE["duel_finisher"].xp * int(finishers)))
return awards
# ------------------------------------------------------------------ ranks
RankTier = Literal["deck", "line", "command", "flag"]
#: Lowest first: enlisted deck ratings, line officers, command, flag officers.
RANK_TIERS: Final[tuple[RankTier, ...]] = ("deck", "line", "command", "flag")
#: The rank ladder everyone aboard climbs, lowest first: (first level, rank
#: id, tier). The commander, every officer and the companion drone share it,
#: so a rank means the same thing on every name plate. The frontend's copy is
#: ``components/society/verse/ranks/ranks.ts`` (with the rank plate's tile
#: pattern); its words are ``verse.ranks.rank.<id>``.
RANKS: Final[tuple[tuple[int, str, RankTier], ...]] = (
(1, "recruit", "deck"),
(3, "deckhand", "deck"),
(5, "technician", "deck"),
(8, "senior_technician", "deck"),
(11, "ensign", "line"),
(14, "lieutenant", "line"),
(17, "senior_lieutenant", "line"),
(21, "commander", "line"),
(25, "captain", "line"),
(29, "line_captain", "command"),
(33, "commodore", "command"),
(37, "rear_admiral", "flag"),
(41, "vice_admiral", "flag"),
(45, "admiral", "flag"),
(50, "fleet_admiral", "flag"),
)
RANK_IDS: Final[tuple[str, ...]] = tuple(rank for _, rank, _ in RANKS)
def rank_for(level: int) -> tuple[int, str, RankTier]:
"""The rank a subject at ``level`` holds."""
held = RANKS[0]
for entry in RANKS:
if level >= entry[0]:
held = entry
return held
def tier_start(tier: RankTier) -> int:
"""The first level of ``tier`` (the level its lowest rank opens at)."""
return min(level for level, _, t in RANKS if t == tier)
# ------------------------------------------------------------------ rewards
Slot = Literal["uniform", "ribbon"]
SLOTS: Final[tuple[Slot, ...]] = ("uniform", "ribbon")
@dataclass(frozen=True, slots=True)
class Reward:
#: ``<slot>_<name>``; a uniform's name is the rank tier it belongs to.
reward_id: str
slot: Slot
#: The level each subject kind unlocks it at; ``None`` = not for that kind.
person: int | None
agent: int | None
pet: int | None
def level_for(self, kind: SubjectKind) -> int | None:
return {"person": self.person, "agent": self.agent, "pet": self.pet}[kind]
#: What a level opens.
#:
#: Uniforms are the commander's: the quartermaster issues the work uniform on
#: day one and each higher tier's dress the day its first rank is reached; the
#: commander may wear any issued one. Officers wear their own tier's uniform
#: automatically, so they earn none. Ribbons are commendations for long,
#: steady service, worn on the service record by the commander and the crew.
#: The companion drone wears its rank only.
REWARDS: Final[tuple[Reward, ...]] = (
Reward("uniform_deck", "uniform", person=1, agent=None, pet=None),
Reward("uniform_line", "uniform", person=tier_start("line"), agent=None, pet=None),
Reward("uniform_command", "uniform", person=tier_start("command"), agent=None, pet=None),
Reward("uniform_flag", "uniform", person=tier_start("flag"), agent=None, pet=None),
Reward("ribbon_good_conduct", "ribbon", person=6, agent=4, pet=None),
Reward("ribbon_meritorious", "ribbon", person=19, agent=16, pet=None),
Reward("ribbon_distinguished", "ribbon", person=31, agent=27, pet=None),
Reward("ribbon_fleet_cross", "ribbon", person=47, agent=43, pet=None),
)
def unlocked_rewards(kind: SubjectKind, level: int) -> list[Reward]:
return [r for r in REWARDS if (at := r.level_for(kind)) is not None and level >= at]
def rewards_between(kind: SubjectKind, before: int, after: int) -> list[Reward]:
"""Rewards newly unlocked when a subject climbs from ``before`` to ``after``."""
return [
r for r in REWARDS
if (at := r.level_for(kind)) is not None and before < at <= after
]
# ------------------------------------------------------------------ agent looks
#: The agent level at which each wearable look unlocks
#: (``companion/accessories.json`` ids, the agent card's looks). The
#: maintainer opened every look from the start (2026-10-05); raise a value to
#: turn a look back into a level-up reward. A look an agent already wears is
#: never taken away.
LOOK_UNLOCKS: Final[dict[str, int]] = {
"sunglasses": 1,
"cap": 1,
"headphones": 1,
"hoodie": 1,
"lab_coat": 1,
"cigar": 1,
"suit": 1,
"top_hat": 1,
"tuxedo": 1,
"crown": 1,
}
def looks_between(before: int, after: int) -> list[str]:
"""Agent looks newly unlocked when an agent climbs from ``before`` to ``after``."""
return [look for look, at in LOOK_UNLOCKS.items() if before < at <= after]
# ------------------------------------------------------------------ titles
_RANK_BANDS: Final[tuple[tuple[int, str], ...]] = tuple((level, rank) for level, rank, _ in RANKS)
#: Title bands per kind: (first level of the band, title id). Every kind wears
#: the rank ladder, so the bands are the same; the per-kind shape stays so the
#: API can give a kind its own ladder later without a contract change.
TITLES: Final[dict[SubjectKind, tuple[tuple[int, str], ...]]] = {
"person": _RANK_BANDS,
"agent": _RANK_BANDS,
"pet": _RANK_BANDS,
}
def title_for(kind: SubjectKind, level: int) -> str:
title = TITLES[kind][0][1]
for start, name in TITLES[kind]:
if level >= start:
title = name
return title
def subject_kind(subject_id: str) -> SubjectKind | None:
if subject_id == PERSON_ID:
return "person"
prefix, sep, rest = subject_id.partition(":")
if not sep or not rest:
return None
if prefix == "agent":
return "agent"
if prefix == "pet":
return "pet"
return None
def agent_subject(agent_id: str) -> str:
return f"agent:{agent_id}"
def pet_subject(pet_id: str) -> str:
return f"pet:{pet_id}"