Python Client

A Python port of the TypeScript @vuer-ai/vuer-rtc library. Multiple clients can concurrently edit a shared scene graph and all changes converge automatically.

Install

bash

pip install vuer-rtc

Quick Start

python

from vuer_rtc import create_graph

# Create a client store
store = create_graph("client-1", on_send=lambda msg: send_to_server(msg))

# Build a scene
store.edit({
    "ot": "node.insert",
    "key": "",            # parent key ("" = root)
    "path": "children",
    "value": {"key": "scene", "tag": "Scene", "name": "My Scene"},
})
store.edit({
    "ot": "node.insert",
    "key": "scene",
    "path": "children",
    "value": {"key": "cube", "tag": "Mesh", "position": [0, 1, 0], "opacity": 1.0},
})
store.commit("create scene")

# Edit properties
store.edit({"ot": "vector3.set", "key": "cube", "path": "position", "value": [3, 2, 1]})
store.edit({"ot": "number.set",  "key": "cube", "path": "opacity",  "value": 0.5})
store.commit("move and fade cube")

# Read state
graph = store.get_state().graph
print(graph.nodes["cube"].get_property("position"))  # [3, 2, 1]

Two-Client Example

python

from vuer_rtc import create_graph

messages_a, messages_b = [], []

store_a = create_graph("alice", on_send=lambda msg: messages_a.append(msg))
store_b = create_graph("bob",   on_send=lambda msg: messages_b.append(msg))

# Alice creates a node
store_a.edit({
    "ot": "node.insert",
    "key": "",
    "path": "children",
    "value": {"key": "obj", "tag": "Mesh", "health": 100},
})
msg = store_a.commit("create obj")

# Bob receives Alice's message
store_b.receive(msg)

# Both edit concurrently
store_a.edit({"ot": "number.add", "key": "obj", "path": "health", "value": -25})
msg_a = store_a.commit("damage")

store_b.edit({"ot": "number.add", "key": "obj", "path": "health", "value": -10})
msg_b = store_b.commit("poison")

# Exchange messages
store_a.receive(msg_b)
store_b.receive(msg_a)

# Both converge: 100 + (-25) + (-10) = 65
assert store_a.get_state().graph.nodes["obj"].get_property("health") == 65
assert store_b.get_state().graph.nodes["obj"].get_property("health") == 65

Operations

Every operation is a dict with ot, key, path, and typically value. The Python client supports all the same operations as the TypeScript client.

Number

python

{"ot": "number.set",      "key": "n", "path": "score",    "value": 42}     # LWW
{"ot": "number.add",      "key": "n", "path": "counter",  "value": 1}      # additive
{"ot": "number.multiply", "key": "n", "path": "scale",    "value": 2}      # multiplicative
{"ot": "number.min",      "key": "n", "path": "cooldown", "value": 5}      # min
{"ot": "number.max",      "key": "n", "path": "health",   "value": 0}      # max

Vector3 / Quaternion / Euler

python

{"ot": "vector3.set", "key": "n", "path": "position", "value": [1, 2, 3]}
{"ot": "vector3.add", "key": "n", "path": "velocity", "value": [0, 1, 0]}

{"ot": "quaternion.set",      "key": "n", "path": "rotation", "value": [0, 0, 0, 1]}
{"ot": "quaternion.multiply", "key": "n", "path": "rotation", "value": [0, 0.707, 0, 0.707]}

{"ot": "euler.set", "key": "n", "path": "rotation", "value": [0, 1.57, 0]}
{"ot": "euler.add", "key": "n", "path": "rotation", "value": [0, 0.1, 0]}

String / Boolean / Color

python

{"ot": "string.set",   "key": "n", "path": "name",    "value": "Cube"}
{"ot": "string.concat", "key": "n", "path": "log",     "value": " line2", "separator": "\n"}

{"ot": "boolean.set", "key": "n", "path": "visible", "value": True}
{"ot": "boolean.or",  "key": "n", "path": "dirty",   "value": True}
{"ot": "boolean.and", "key": "n", "path": "locked",  "value": False}

{"ot": "color.set",   "key": "n", "path": "color", "value": "#ff0000"}
{"ot": "color.blend",  "key": "n", "path": "color", "value": "#0000ff", "alpha": 0.5}

Array / Object

python

{"ot": "array.set",    "key": "n", "path": "items", "value": [1, 2, 3]}
{"ot": "array.push",   "key": "n", "path": "items", "value": 4}
{"ot": "array.remove",  "key": "n", "path": "items", "value": 2}
{"ot": "array.union",   "key": "n", "path": "tags",  "value": ["a", "b"]}

{"ot": "object.set",   "key": "n", "path": "config", "value": {"debug": True}}
{"ot": "object.merge",  "key": "n", "path": "config", "value": {"verbose": True}}

Node (Scene Graph Structure)

python

# Insert a child node
{"ot": "node.insert", "key": "parent", "path": "children",
 "value": {"key": "child", "tag": "Mesh", "name": "Child"}}

# Remove (soft-delete / tombstone)
{"ot": "node.remove", "key": "parent", "path": "children", "value": "child"}

# Move a node to a new parent
{"ot": "node.move", "key": "old-parent", "path": "children",
 "value": {"nodeKey": "child", "newParent": "new-parent"}}

Text (Collaborative CRDT)

python

# Initialize a text property
{"ot": "text.init",    "key": "doc", "path": "content"}

# Insert text at a position. `value` is an [anchor, content] tuple; use None for
# the anchor on a position-based local insert (the CRDT computes it).
{"ot": "text.insert",  "key": "doc", "path": "content", "position": 0, "value": [None, "Hello"]}

# Delete a range
{"ot": "text.delete",  "key": "doc", "path": "content", "position": 0, "length": 5}

# Atomic delete + insert (for select-and-type)
{"ot": "text.replace", "key": "doc", "path": "content", "position": 0, "length": 5, "value": [None, "Hi"]}

Important: Use text.replace instead of separate text.delete + text.insert when replacing a selection. The edit buffer deduplicates by key:path, so a delete followed by an insert on the same key and path will lose the delete.

Undo / Redo

python

store.edit({"ot": "number.set", "key": "n", "path": "x", "value": 10})
store.commit("set x")

store.undo()  # x reverts to previous value
store.redo()  # x = 10 again

Undo/redo is journal-based. Each undo() marks a journal entry as deleted and replays the remaining entries. This works correctly across concurrent edits from multiple clients.

Edit Buffer

Edits are buffered until commit(). Additive operations on the same key:path are merged automatically:

python

store.edit({"ot": "vector3.add", "key": "n", "path": "pos", "value": [1, 0, 0]})
store.edit({"ot": "vector3.add", "key": "n", "path": "pos", "value": [0, 1, 0]})
store.edit({"ot": "vector3.add", "key": "n", "path": "pos", "value": [0, 0, 1]})

# Only one op in the buffer: value = [1, 1, 1]
assert len(store.get_state().edits.ops) == 1

store.commit("combined move")

Use store.cancel() to discard uncommitted edits and revert to the pre-edit graph.

Receiving Remote Messages

python

store.receive(msg)      # apply a CRDTMessage from the server
store.ack(msg_id)       # mark one of our messages as server-acknowledged

Duplicate messages are automatically ignored (idempotent).

Retry and Compaction

python

from vuer_rtc import get_unacked_messages

# Retry unacknowledged messages (e.g. after reconnect)
for msg in get_unacked_messages(store.get_state()):
    send_to_server(msg)

# Compact acknowledged journal entries into a snapshot
store.compact()

API Reference

GraphStore

Method	Description
`edit(op)`	Add operation to edit buffer (optimistic apply)
`commit(description?)`	Commit edits as a single `CRDTMessage`
`cancel()`	Discard uncommitted edits
`receive(msg)`	Process incoming remote `CRDTMessage`
`ack(msg_id)`	Mark a journal entry as server-acknowledged
`undo()`	Undo last committed message from this session
`redo()`	Redo last undone message from this session
`compact()`	Bake acknowledged entries into snapshot
`get_state()`	Return current `ClientState`

Pure Functions

For advanced use cases, the bare state-transition functions are also exported:

python

from vuer_rtc import (
    create_initial_state,
    on_edit, commit_edits, cancel_edits,
    on_server_ack, on_remote_message,
    undo, redo, compact, rebuild_graph,
)

Low-Level Operations

python

from vuer_rtc import (
    apply_operation,    # Apply a single op to a SceneGraph (mutates in place)
    apply_message,      # Apply a CRDTMessage (returns new graph)
    apply_message_mut,  # Apply a CRDTMessage (mutates in place)
    apply_messages,     # Apply multiple messages
    create_empty_graph, # Create an empty SceneGraph
)

Conflict Resolution

Merge Strategy	Operation Types
Last-Write-Wins (LWW)	`*.set` — highest Lamport timestamp wins
Additive	`number.add`, `vector3.add`, `quaternion.multiply` — values accumulate
Commutative	`boolean.or`/`boolean.and`, `number.min`/`number.max`, `array.union`
Deep merge	`object.merge` — recursive per-key merge
CRDT text	`text.insert`/`text.delete`/`text.replace` — RGA/YATA algorithm

All strategies are deterministic: given the same set of operations (in any order), every client converges to the same state.

Running Tests

bash

pip install -e ".[test]"
pytest tests/ -x -q

To skip slow benchmarks:

bash

pytest tests/ -x -q -m "not slow"

Lossless checkpoints (Python 0.0.2)

Keep the server snapshot's textRopes field when constructing Snapshot. Both createGraph(initial_snapshot=...) and GraphStore.fromServer(...) hydrate this metadata automatically; custom consumers can call hydrateTextSnapshot(snapshot). The Python graph retains its existing _textCrdt.<path> rope plus visible string representation. TypeScript camelCase rope fields and deleted anchors are supported, and fresh local inserts use the local agent ID.

The raw MessagePack codec forwards additive sync-check, sync-status, and checkpoint metadata unchanged. Python does not automatically run a checksum monitor or manage held drafts. Compare note-body hashes only at equal committed clocks with no pending edits; legacy strings cannot recover discarded character identities.