Research and development roadmap

Purpose

RODENT is being developed as a platform in which researchers can define an arena, connect an agent or treatment model, run controlled virtual experiments, inspect what happened and export the evidence. The platform does not provide a scientifically validated rat by itself. Its current statistical agent is a demonstration component used to test the surrounding experiment infrastructure.

The roadmap therefore separates two responsibilities:

1. RODENT provides the experiment platform. This includes templates, stimuli, simulated time, model interfaces, recording, replay, project access and exports.
2. Researchers provide or select scientifically motivated models. A model determines how an agent interprets sensed conditions and chooses an action. The validity of that model must be established for its intended research question.

Status language

The documentation uses the following terms consistently:

Status	Meaning
Implemented	Working code exists in the repository.
Integrated	The feature is connected to the combined application.
Released	Researchers can access it through the hosted build.
Verified	The intended workflow has been tested and recorded as evidence.
Planned	The feature is part of a future stage and must not be presented as complete.

See Sprint 2 delivery for the current platform work and Testing and evidence for what has been checked.

Current research workflow

The current platform establishes the path around a researcher-supplied model:

Account and research project
             |
             v
Choose or build an arena template
             |
             v
Configure stimuli, treatment, seed and timing
             |
             v
Run through the visual workspace or headless API
             |
             v
Record steps, events and interventions
             |
             v
Replay or export JSON and CSV

The website supports research projects, scoped team access and experiment configuration. Godot supplies the 3D arena, fixed-step simulation host and replay view. The internal Python interface can start and control Godot without opening the renderer. Supabase supplies hosted authentication and research-project persistence, while a local Python and SQLite mode remains available for development.

Next research milestone: headless model operation

The next major milestone is a complete model adapter that works without rendering the arena. A researcher should be able to train or evaluate a model from a script with no mouse input, no visible Godot window and no dependency on display frame rate.

The intended loop is:

Load experiment and model
          |
          v
Reset with a recorded seed
          |
          v
Receive current sensations
          |
          v
Model chooses an action
          |
          v
Advance one or more fixed steps
          |
          v
Return observation, events, outcome and completion state
          |
          +---------------- repeat ----------------+

RODENT already has local reset, step, observe, act, load and close commands. The planned work is to replace the limited movement hook with a documented, versioned observation and action contract suitable for external users. The API must reject incompatible models clearly and record the adapter version, experiment version and random seed used for every episode.

Readable current sensations

An observation should describe only information that the selected model is allowed to sense. It should use stable names, units and plain JSON rather than exposing Godot nodes. A typical observation may contain:

Observation group	Research-facing information
Time	Episode ID, fixed step, simulated seconds and remaining duration.
Agent state	Position, heading, speed, contact state and current region.
Arena sensing	Distance to nearby walls, accessible doors, floor material, shelter status and objects within sensing range.
Light	Local intensity at the agent, source direction, distance, activation state and whether the source is obstructed.
Odour	Local concentration for each configured odour, concentration change and estimated gradient direction.
Sound	Local sound level, source direction, distance, activation state and attenuation.
Temperature	Local temperature and change since the previous observation.
Treatment	Condition label, administration events and model-exposed treatment state.
Previous transition	Previous action, resulting movement, collision, region change and newly triggered events.

Each field must state its unit and reference frame. Missing sensors should be omitted or explicitly marked unavailable. The platform must not secretly provide global information to a model that is meant to use local sensing only.

A simplified future response could look like this:

{
  "protocol": "rodent-model-v1",
  "episode_id": "run-1042",
  "step": 315,
  "simulated_time_s": 31.5,
  "observation": {
    "region_id": "central_circle",
    "position_cm": [82.4, 61.7],
    "heading_deg": 40.0,
    "contacts": [],
    "light": [{"source_id": "bridge_light", "local_lux": 120.0}],
    "odour": [{"source_id": "shelter_odour", "concentration": 0.34}],
    "sound": [{"source_id": "speaker_a", "local_level": 0.18}],
    "temperature_c": 22.4
  },
  "events": ["entered:central_circle"],
  "terminated": false
}

The exact schema will be frozen and versioned before researchers are asked to build against it.

Actions and interactions

The action contract should stay small and explicit. At minimum, a locomotion model needs a requested forward movement and turn. Optional actions may include waiting, approaching an object or interacting with an enabled experimental object. The platform remains responsible for applying collisions and arena constraints. A model cannot move through a wall simply because it requests a position on the other side.

Objects and regions need stable IDs and declared interaction rules. For each interaction the configuration should state:

• what the object is;
• whether it can be sensed, entered, climbed, pushed or activated;
• which actions are valid;
• which physical rule decides the outcome;
• what event is recorded; and
• what information is returned to the model.

A door, for example, may be open or closed, block movement when closed and produce a door_state_changed intervention event. A shelter may be enterable and change light exposure. A wire bridge may alter movement cost or stability only when a researcher-selected model defines that effect. These effects must not be hidden inside the renderer.

Modelling how stimuli affect an agent

RODENT must keep environmental exposure separate from behavioural interpretation.

Configured source
      |
      v
Physical or phenomenological field model
      |
      v
Exposure at the agent's location
      |
      v
Researcher-supplied response model
      |
      v
Internal state and chosen action

The platform may calculate that a local light exposure is 120 lux or that an odour concentration is 0.34 in the configured model. It must not automatically claim that the animal is anxious, attracted or impaired. That interpretation belongs to the selected response model and its scientific justification.

Planned stimulus work includes:

• light falloff, direction, obstruction and controlled on/off schedules;
• odour concentration, spread, decay and gradients over time;
• sound attenuation, direction, duration and obstruction assumptions;
• temperature zones and time-dependent changes;
• treatment administration, concentration or effect models supplied through an adapter;
• combined exposures, with their execution order declared; and
• calibration metadata and units for every stimulus model.

Every step record should preserve the source settings, calculated local exposure, relevant internal state reported by the model and resulting action. This enables a researcher to distinguish what the platform applied from how the model responded.

Batch experiments without rendering

Researchers should be able to run large batches before choosing anything to visualise. A batch specification should include the experiment version, model version, seeds, number of episodes, maximum steps, parameter combinations and requested outputs.

For a batch of 1,000 runs, the workflow should be:

1. Validate the experiment and model contract once.
2. Create a run manifest containing all 1,000 episode IDs and seeds.
3. Execute fixed-step episodes without loading cameras, meshes or animation.
4. Save raw transitions and events for each episode.
5. Calculate declared summaries such as region dwell time, distance travelled, entries, latencies, exposure totals and interaction counts.
6. Report failures separately rather than silently removing them.
7. Compare groups only using researcher-selected analysis methods.
8. Select representative, unusual or failed episodes for later rendering.

The result package should include:

• the exact experiment configuration;
• model and adapter identifiers;
• software and schema versions;
• random seeds;
• episode status and termination reason;
• raw or sampled trajectories;
• stimulus exposures and interventions;
• treatment events;
• per-episode metrics;
• aggregate summaries; and
• validation warnings and execution errors.

Headless execution must be benchmarked in steps per second and episodes per hour. Parallel execution can be added after it is proven that worker count and execution order do not change the result for a given seed.

Rendering completed runs

Rendering should be a view of recorded data, not a requirement for generating it. After a headless batch, a researcher should be able to choose an episode and replay its recorded states in the same arena template.

The replay renderer should support:

• play, pause, step, seek and speed controls;
• top-down, orbit, first-person and follow-agent cameras;
• an obvious Replay marker so recorded data cannot be mistaken for a live run;
• the current step, simulated time, seed, model and experiment version;
• trails, region transitions and stimulus activation markers;
• overlays for local light, odour, sound and temperature values;
• treatment and researcher-intervention markers on a timeline; and
• export of a selected replay view or screenshot without changing the data.

Animations should be derived from recorded movement and interaction state. Locomotion speed can control walk or run cycles, while collision, rearing, grooming or object-interaction animations should only appear if the model or event stream explicitly reports that state. Animation must never create an event that was absent from the recorded run.

Visual markers for internal state

Researchers may want visible markers for model outputs such as risk score, arousal, attraction, avoidance or confidence. These can be useful overlays, but they must be presented as model-reported internal variables, not observed emotions.

The planned display includes:

• a configurable colour ring or icon above the agent;
• a labelled value and scale, such as avoidance score: 0.72;
• a timeline graph linked to the replay step;
• a legend naming the model variable and unit;
• a switch to hide all interpretive overlays; and
• a warning when the active model does not supply the requested variable.

Researchers should be able to define thresholds and colours for their own variables. The default documentation should use neutral terms such as low, medium and high rather than assigning human emotions. Any claim that a marker represents fear, anxiety or another biological state requires an externally validated model and an explanation in the experiment metadata.

Researcher-facing analysis

The results view should answer four questions:

1. What was configured? Arena, stimuli, treatment, model, seed and protocol.
2. What did the agent sense? Local exposure and accessible environment at each sampled step.
3. What did the model do? Actions, internal variables and interactions.
4. What happened over the episode or batch? Trajectory, events, termination and declared metrics.

Raw results must remain available in a machine-readable form. Human-readable tables and charts should be generated from those records and should name the calculation used. Planned summaries include zone dwell time, first-entry latency, visit counts, distance, speed, immobility, stimulus exposure, treatment timing and interaction frequency. Group comparisons should show episode count, exclusions and uncertainty rather than only a single average.

Delivery stages

Stage 1: platform foundation

Completed work includes the project workspace, partial microkernel, fixed-step execution, six templates, editable experiment configuration, 3D arena, stimuli and treatment configuration, barriers, recording, replay, exports and automated checks.

Stage 2: researcher platform integration

Sprint 2 connected the web workspace, Supabase-backed accounts and projects, scoped membership, template selection and editing, internal headless control, external environment import, improved UI, hosted deployment and expanded UI and API tests. See Sprint 2 delivery.

Stage 3: stable model adapter

Define and implement rodent-model-v1, including validated observations, actions, termination, model metadata, file handling, resource limits and clear compatibility errors. Supply an example adapter that is explicitly labelled as a demonstration.

Stage 4: headless batch runner

Add manifests, checkpoints, resumable batches, parallel-worker determinism tests, progress reporting and research-ready result packages. Demonstrate at least 1,000 non-rendered episodes and retain the seeds required to reproduce selected runs.

Stage 5: scientific replay and analysis

Render chosen completed runs, add animation and exposure overlays, show model-reported internal variables responsibly, and provide transparent per-episode and aggregate analysis.

Stage 6: validation and extension

Allow new arena, stimulus, treatment and agent adapters through documented interfaces. Add validation studies, provenance records, access review, performance evidence and user testing with researchers before claiming suitability for a particular scientific use.

Scientific and ethical boundary

RODENT can make computational experiments configurable, repeatable and inspectable. It cannot make a behavioural or treatment model scientifically valid simply by running it many times. One thousand reproducible simulations are one thousand samples from the selected software model, not evidence that a real animal would behave the same way.

Every published result should identify the model source, assumptions, calibration data, validation status and limitations. Illustrative weather mappings, placeholder movement and model-reported internal states must remain clearly labelled.

---

AI Attribution: This document was drafted and edited with AI assistance, including OpenAI Codex. The team remains responsible for reviewing the roadmap and validating all scientific claims.