Integration¶
Integrate a new symbolic engine and convert a trained model to ONNX.
Integrate a new symbolic machine¶
The agent talks to a symbolic virtual machine (SVM) over a websocket protocol and exchanges JSON messages. To integrate a new engine:
Implement the server side of the websocket protocol. The agent-side reference is
AIAgent/connection/game_server_conn/(connector.pyandmessages.py); the game loop that drives the connection lives underAIAgent/ml/validation/coverage/game_managers/.Provide serialization and deserialization of the data according to that protocol (see
AIAgent/connection/game_server_conn/messages.py).Implement two execution methods on the engine side:
Symbolic execution in training mode (example:
GameServers/VSharp/VSharp.ML.GameServer.Runner/Main.fs).Execution guided by a trained model (example:
GameServers/VSharp/VSharp.Explorer/AISearcher.fs).
Integration examples live under GameServers/. Two machines are integrated:
V# is the primary game server. A typical end-to-end workflow is automated in
.github/workflows/build_and_run.yaml, whose pipeline steps live in the
shared reusable workflow .github/workflows/e2e_build_and_run.yml.
Wire protocol¶
This section is the wire contract for engine integrators: the message
types, the field lists, the encoding rules, and the versioning. The
executable schema is the message dataclasses in
AIAgent/connection/game_server_conn/messages.py (with the domain types
in AIAgent/common/game.py); the two must stay in agreement — the
wire-format pins in AIAgent/tests/unit/connection/ are the drift net.
Transport and framing¶
The agent and the game server talk over a websocket and exchange one JSON
object per text frame. Every message is an envelope with a MessageType
(string) and a MessageBody:
{"MessageType": "step", "MessageBody": "{\"StateId\": 3, \"PredictedStateUsefulness\": 1.5}"}
Protocol versions¶
v1 (legacy): the envelope has no
Versionfield. This is the format the V# and usvm servers speak today.v2: the envelope carries
"Version": 2.
The version the agent speaks is PROTOCOL_VERSION in
messages.py (currently 2). On receive, the agent:
accepts a
Versionequal toPROTOCOL_VERSION;rejects any other present
VersionwithProtocolVersionMismatchError(the game fails with that reason);accepts a missing
Versionas a legacy v1 server and logs a loud warning (once per process).
The agent does not emit Version yet: the current usvm server rejects
unknown envelope keys, so client-side emission ships together with the
server-side rollout (the V# and usvm follow-ups that add the field to
their outgoing messages). Any change to the message types, fields, or
encoding below is a new version: bump PROTOCOL_VERSION and update this
page in the same change.
Client to server¶
The client sends the MessageBody as a JSON string inside the JSON
envelope (JSON-in-JSON) — see the encoding note below.
start— body: theGameMapfields (StartMessageBodymirrorscommon.game.GameMapfield-for-field):StepsToPlay(int),StepsToStart(int),AssemblyFullName(str),NameOfObjectToCover(str),DefaultSearcher(str,"BFS"or"DFS"),MapName(str).step— body:StateId(int),PredictedStateUsefulness(float). Insvms_each_stepmode the agent sends the model’s predicted value for the chosen (argmax) state.stop— body: an empty object. The servers handle it; the client does not send it today.
Server to client¶
The server sends the MessageBody as a nested JSON object.
ReadyForNextStep— body:GameState(GraphVertices,States,PathConditionVertices,Map— seecommon.game.GameState).MoveReward— body:Reward(ForMovewithForCoverageandForVisitedInstructions(ints),MaxPossibleReward(int)).IncorrectPredictedStateId— body:StateId(int). Sent when the predicted state does not exist; the agent continues with the server’s state.GameOver— body:ActualCoverage(int or null),TestsCount(int),StepsCount(int),ErrorsCount(int).ServerError— body:ErrorMessage(str) in V#; usvm sends the keyMessageinstead. The agent does not decode this body today; the message surfaces as a decode failure.
Encoding note: the JSON-in-JSON client-body asymmetry¶
The client encodes MessageBody as a JSON string (the server
decodes the string as JSON a second time), while the server encodes it as
a nested JSON object. This asymmetry is a known wart of the current
protocol, flagged for a future protocol revision; changing it is a
breaking wire change (a future version).
Result and steps files¶
In svms_model (send-model) mode the agent launches the engine as a
subprocess (the platform’s SVMSInfo.launch_command, with {OutputDir}
substituted) and collects the outcome from two files the engine writes into
that output directory. The agent polls for the result file until it appears
or the per-map timeout elapses:
<OutputDir>/<MapName>result— four space-separated integers:actual_coverage_percent tests_count steps_count errors_count
steps_countis the total trace steps (the startup steps included); the agent subtractsStepsToStartto obtain the model-played count (see SVM validation step metric).<OutputDir>/<MapName>_steps— a JSON array with one entry per model-played step (the game state and the model output). The engine writes it only on request: after writing the result file it connects to the agent’s listening port (the{Port}substitution) and reads one byte —1= save the steps,0= skip — and writes the file only for1.
Port allocation¶
Two ports are involved in an SVM run: the broker’s own port and the per-instance game-server port.
Broker port. The websocket broker serves
/get_wsand/post_wsonBrokerConfig.port(default35000). It is a single fixed port per broker process.Game-server port. Each game server instance gets its own port from the platform’s
SVMSInforange (min_port/max_port). The shipped configs keep the ranges disjoint from the broker port: the broker occupies35000and the SVM ranges start at35100(35000–35099is reserved for broker(s)).
How the game-server port is bound differs by validation mode:
svms_each_step(broker-launched): the broker probes the range for a free port — binding the probe on the same interface the server binds (127.0.0.1for the V# runner) — and launches the server with it. The server is a separate process that binds its own socket, so the listening socket cannot be passed to it and the probe→bind window is a cross-process race. The race is accepted with a bounded retry-on-collision: if the port is open while the server process is dead (it died on the bind — a foreign process holds the port), the broker reaps the corpse and retries the next port, up toMAX_PORT_ATTEMPTSattempts. A port that never opens within the startup timeout is a startup failure, not a collision, and fails fast.svms_model(send-model): the agent binds and holds the listening socket itself and passes the port to the engine, which connects to it (see Result and steps files); there is no cross-process bind race for that socket.
In broker-launched mode the broker also leases each issued instance: the
issue is recorded with a monotonic timestamp and the lease ends when the
client returns the instance on /post_ws. A hard-killed worker never
returns its instance, so a background reaper on the broker’s event loop
scans every LEASE_REAP_INTERVAL_SEC (60 s) and reaps any issued
instance older than BrokerConfig.lease_ttl_sec (default 1 h — larger
than the per-map timeout, so a legitimate game is never reaped): the game
server is killed and a placeholder is re-queued, so the slot is
re-issuable instead of lost forever. A kill failure is logged and the slot
is still re-queued (the surviving process is cleaned up at broker
shutdown).
ONNX conversion¶
To convert a PyTorch model to ONNX, run onyx.py:
cd AIAgent
python3 onyx.py --sample-gamestate <game_state0.json> \
--pytorch-model <path_to_model>.pth \
--savepath <converted_model_save_path>.onnx \
--model-name <model_name> \
--model-kwargs <yaml_with_model_args>.yml \
[optional] --verify-on <game_state1.json> <game_state2.json> <game_state3.json> ... \
[optional] --opset-version <n>
pytorch-modelis the path to the PyTorch model weights.Examples of the
model-kwargsYAML file, verification game states, and asample-gamestate(any can be used) are underresources/onnx/.model-nameis the registry name of the model to convert (seeAIAgent/ml/models/registry.py), for exampleNorthernPenguin.--opset-versionis the ONNX opset version to export with (default: 17).
See Guide symbolic execution with a trained model for how to run execution with the converted model.