Internal API (Ahmed)

This page is about the interfaces Ahmed uses to control the simulator and save a custom arena. It is separate from Zidan's external environment API. The internal API is for the RODENT application and developers working with it; it is not an internet-facing service that researchers should call directly.

How the pieces connect

Python client or website
        |
        v
Headless adapter or web bridge
        |
        v
SimulationKernel
        |
        +-- arena, stimuli, demo agent and recorder plugins

The kernel owns simulated time, the seed and plugin order. A user interface sends a command, and the kernel returns a snapshot or emits a signal. This separation lets the same experiment run with a 3D view or without rendering. The current moving agent is a demonstration placeholder, not a validated biological rat model.

Kernel contract

The in-process Godot API is implemented in src/core/simulation_kernel.gd. The app shell registers plugins, loads a validated experiment, and routes updates back to the UI.

Call or signal	Purpose
register_plugin(plugin)	Add a module before loading an experiment. Plugins execute in priority order.
load_experiment(configuration)	Load a configuration, stop the current run and initialize plugins.
start() / stop()	Start or stop automatic fixed-step progression.
reset()	Restart the loaded experiment with its configured seed.
advance_one_step()	Run one deterministic simulation step.
snapshot()	Return step number, simulated time, current state and event count.
stepped(snapshot)	Signal that a new snapshot is available.
run_state_changed(is_running)	Signal that the run has started or stopped.

Experiment validation happens before load_experiment; callers should not send arbitrary JSON straight into the kernel. Changing 1x, 10x or 100x changes how quickly fixed steps are run, not the experiment's fixed_delta or seed.

Headless Python control

Ahmed's feature/headless-simulation-api provides python/rodent_client.py and tools/headless_simulation.gd. The Python client launches Godot with --headless, opens a connection to 127.0.0.1 on a temporary port, and exchanges newline-delimited JSON. The protocol identifier is rodent-headless-v1. It is local-only and does not require the website or a rendered arena.

From the application repository, with Godot installed and available as godot:

from python.rodent_client import RodentClient

with RodentClient("godot", ".") as sim:
    initial = sim.reset()
    after_ten_steps = sim.step(10)
    current = sim.observe()
    print(current["step"], current["time"])

Python method	What it does
reset()	Restart the current experiment.
step(count=1)	Advance between 1 and 100,000 steps in one request.
observe()	Return the current snapshot without advancing time.
act(action, advance=True)	Apply an intervention, then optionally advance one step.
load(path)	Load a validated experiment file.
close()	End the local session and stop its Godot process.

Every successful command returns a snapshot containing step, time, state and event_count. Errors return a message rather than a snapshot. The current act implementation accepts heading_delta and a two-number floor position; it bounds the requested position to the arena rectangle and records an intervention event. This is a limited control hook, not a complete observation/action/reward interface for training a model. Position bounds alone should not be treated as proof of wall-safe movement.

Custom arena save path

Ahmed's feature/arena-editor also implements a 2D arena editor. Its Create experiment action produces an experiment configuration using the application's schema. In local development, the editor uses the Python backend's project experiment-creation route. In hosted mode, it saves through Supabase. This is an application-internal save path, distinct from the headless simulation protocol. See Arena Template Builder for the researcher workflow.

The template-builder code exists on its feature branch, but its role checks and database insert policy still need an end-to-end test in the combined hosted build. Being implemented in a branch does not by itself mean the hosted portal has received it.

What to test

• Run the same experiment and seed twice and compare step-by-step snapshots.
• Confirm changing display speed does not change the trajectory at the same step.
• Send a bad experiment path or unsupported command and check that the error is understandable.
• Confirm an intervention is recorded at the expected step.
• Test custom-arena save and reopen with a project lead, scoped researcher and observer account.

AI Attribution: This page was drafted with OpenAI Codex assistance from Ahmed's headless client, Godot adapter, kernel and arena-editor branch. The team should review examples and verify the combined hosted workflow.