APIs and data
RODENT has several boundaries that are easy to confuse. The website is not the simulator, and the file drop zones in the checked integration build are not themselves a model API. Team API work may exist in separate working copies or branches; the table below describes the code inspected for this page. See Zidan's External API Integration and Ahmed's Internal API for the separate detailed pages.
| Boundary | Available now | Limits |
|---|---|---|
| Browser ↔ Godot | Same-origin postMessage commands for setup, run, camera, doors, results and replay. | The embedded Godot export renders and executes; browser controls own the visible workflow. This is not a public network API. |
| Python ↔ headless Godot | python/rodent_client.py launches Godot without rendering and exposes reset, step, observe, act, load and close over localhost TCP. | Local-only protocol rodent-headless-v1. Current actions can change heading or set a bounded position; they are not a complete trainable agent contract. |
| Browser ↔ local Python server | JSON routes for config, validated templates, experiments, membership, replays and a weather preview. | Account and project routes use SQLite only in local mode. The server disables those routes when Supabase mode is configured. |
| Browser ↔ Supabase | Hosted sign-in, project data and role RPCs using a publishable key. | Needs the live schema, RLS policies and RPC migrations to match the client. Never use a service-role key in browser code. |
| Weather service ↔ Open-Meteo | Location and date/time lookup used to suggest ambient light and sound settings. | A suggestion is not a measured exposure model; no temperature physics is implemented. |
Headless interface
For developers, the Python client is the simplest existing external integration point. The script in tools/headless_simulation.gd runs the kernel and its arena, stimulus, demonstration-agent and recorder plugins without opening the 3D scene. Requests and responses are newline-delimited JSON on 127.0.0.1. Each successful response includes a snapshot with step, simulated time, state and event_count.
from python.rodent_client import RodentClient
with RodentClient("godot", ".") as sim:
first = sim.reset()
next_step = sim.step()
current = sim.observe()
This is useful for automated checks and future model training without rendering. It does not yet return a reward or episode-complete flag, replace the statistical agent with a learned policy, or prove a biological model is valid. A future model adapter needs declared input/output fields, units, version, validation, permitted actions and a way to replay the exact model version.
Local website API
The Python server exposes GET /api/config, GET /api/templates, GET /api/templates/{id} and GET /api/default-experiment as setup endpoints. In local SQLite mode, authenticated routes manage /api/paradigms, project members, experiments and replays. Writes require an authenticated session and CSRF token. GET /api/environment/preset is restricted to a local preview, while the authenticated POST route is used by the website. These are application routes, not a promised stable public API. In Supabase mode, login and project writes go to Supabase rather than these local routes.
Ahmed implemented a local POST /api/paradigms/{id}/experiments path for a new custom arena and a hosted Supabase save path on feature/arena-editor. The code exists in that branch; it has not yet been verified end to end in the checked integration build. Its permissions and database insert policy need role-based testing before calling it generally available.
Hosted database
The database represents projects and experiments rather than a single global instructor workspace. The table names in the application are:
| Table | Purpose |
|---|---|
profiles | Research account profile linked to Supabase Auth. |
paradigms | Project name, lead, enabled customization modules and archive state. |
paradigm_memberships | Account-to-project membership, editor/viewer access and assigned edit scopes. |
experiments | Versioned configuration JSON, project relationship, status and revision. |
replays | Saved run data linked to an experiment and creator. |
audit_log | Changes to important project entities. |
One project has many memberships and experiments; one experiment can have many replays. An active account may create a project and starts as its lead. The lead can assign researcher modules within the project's enabled modules. The hosted assign_paradigm_role RPC and the configuration_allowed rule are intended to enforce that scope on writes. Read-only observers must not gain write access merely by calling the API directly.
Supabase schema changes are in the application repo's supabase/migrations/ directory. Apply and verify them in filename order against the intended Supabase project; creating a SQL file in Git does not apply it to the live database. The team's original SQL work should be attributed to its actual author. The later 202609120001_research_projects.sql migration adds per-member scopes and the four-argument role RPC. If the app says a function is missing, inspect the live schema and migration history rather than creating duplicate accounts or broadly disabling RLS.
For a deployment record, capture the applied migration filenames, the actual table columns and types, enabled RLS policies and the RPC signatures. The available schema screenshot is not enough to certify the current production schema. This read-only SQL gives a column inventory to attach to the private deployment log:
select table_name, column_name, data_type, is_nullable
from information_schema.columns
where table_schema = 'public'
and table_name in (
'profiles', 'paradigms', 'paradigm_memberships',
'experiments', 'replays', 'audit_log'
)
order by table_name, ordinal_position;
Use the Supabase policy view and test accounts to verify what each role may read and write. Do not treat a successful SQL migration or a UI badge as sufficient permission evidence.
Deployment configuration
The application server reads SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY from backend/.env in local development or from hosting environment settings. The browser receives only those public values. Keep .env out of Git. Do not copy account passwords, service-role keys, real participant details or private replay data into documentation or issue screenshots. Record database project ID, migration versions and deploy date in the team's private deployment log before claiming a hosted feature is working.
AI Attribution: This page was drafted with OpenAI Codex assistance from the application code and migration files. Live database behaviour must be verified by the team.