Skip to content

API Reference

Session and machine control

murineshiftwork.logic.machine_config

Machine-local config at ~/.murineshiftwork/msw_machine.yaml.

Stores machine-specific settings that are independent of the shared config dir. All external service URLs and credentials use a flat <service>_api_<key> naming scheme so machine configs across rigs remain consistent.

Expected YAML structure (all keys optional): config_dir: /mnt/maindata/msw_configs data_dir: /mnt/maindata/data

# MSW LogAgent / monitor backend : the FastAPI ingest+query server;
# msw-ui Vue SPA polls this for live session data
logagent_api_url: http://monitor:8080
logagent_api_token: <bearer-token>

# MSW UI frontend: URL to open in browser (served by msw-ui nginx container)
msw_ui_url: http://monitor:3000

# Open Ephys remote control (fallback; prefer setup YAML open_ephys_url)
openephys_api_url: <oe-host-ip>

# labwatch session push: read by msw-labwatch, not by murineshiftwork core
labwatch_api_url: https://labwatch.example.com
labwatch_api_token: <token>

Priority for config_dir resolution (highest wins): 1. CLI --config-dir argument 2. MSW_CONFIG_DIR environment variable 3. ~/.murineshiftwork/msw_machine.yaml config_dir key 4. /mnt/maindata/msw_configs (historical default, if it exists)

read_log_config()

Return LogAgent config from machine config.

Reads new-style prefixed keys first, falls back to legacy names: logagent_api_url (legacy: log_url) logagent_api_token (legacy: log_bearer_token)

read_open_ephys_url()

Return the Open Ephys GUI host from machine config (legacy fallback).

Preferred location is the setup YAML open_ephys_url: field. Machine config is checked as a fallback; reads new-style key first: openephys_api_url (legacy: open_ephys_url)

read_ui_url()

Return the MSW UI frontend URL from machine config.

Reads new-style key first, falls back to legacy: msw_ui_url (legacy: ui_url)

resolve_config_dir(cli_override='')

Return the config dir to use, applying the priority chain.

Parameters:

Name Type Description Default
cli_override str

value of --config-dir from CLI (empty string = not set).

 ''

resolve_config_dir_with_source(cli_override='')

Return (config_dir, source) where source names the winning layer.

The single definition of the config-dir priority chain; resolve_config_dir and msw config show both read it so the reported source can never drift from the value actually used. source is a human-readable label; config_dir is "" if nothing is set.

resolve_data_dir(cli_override='')

Return the default data output directory, applying priority chain.

Priority (highest first): 1. --out-path CLI argument (passed as cli_override) 2. MSW_DATA_DIR environment variable 3. ~/.murineshiftwork/msw_machine.yaml data_dir key 4. /mnt/maindata/data (historical default, if it exists) 5. ~/data (fallback)

write_machine_config(config_dir, **extra_fields)

Write (or update) ~/.murineshiftwork/msw_machine.yaml.

murineshiftwork.logic.task_process

TaskProcess

Manages one session: paths, bpod connection, task thread lifecycle.

Bpod injection: pass a pre-opened RobustBpodSession via bpod= to let the caller (controller/hardware manager) own the hardware connection. When bpod is None (default), TaskProcess opens the connection itself using serial_port_bpod.

init_task()

Import specific Task and make self.task_runner Thread.

run_task()

Run the Task thread.

TaskRunner

Bases: Thread

Base class for task threads.

Subclass and override run(). Check self.continue_task in the run loop so stop() can interrupt gracefully. No Qt dependency: GUI layers can wrap this in a QThread adapter if needed.

emit_trial(trial)

Persist one scored trial through the framework's trial-data writer.

A migrated task calls this once per scored trial instead of writing the file itself: the durable write goes through the injected TrialDataWriter (input_kwargs['trial_writer']) so the framework owns the destination path and on-disk format. A task that has not migrated never calls this, and the writer stays empty.

get_path(artifact)

Return the session file path for artifact (e.g. 'df.jsonl', 'log').

prepare()

Override for setup work before the task starts (load settings, open video, etc.).

run()

Override with task loop logic.

trial_index = 0 max_trials = 1500 while self.continue_task and trial_index < max_trials: ...

update_session_yaml(session_file_path, **sections)

Add or update top-level sections in .msw.session.yaml.

Creates the file with msw_format_version: 2 if it does not exist yet. Typical callers: task_objects writing task_settings or stage after init.

Config models

murineshiftwork.logic.config.models.SetupConfig

Bases: BaseModel

Hardware configuration for a single behavioural rig.

Describes the physical devices (Bpod, PulsePal, stage, scale), camera backend, valve calibrations, and per-rig hooks for one named setup. Loaded from {config_dir}/setups/{name}.yaml by load_setup_config.

murineshiftwork.logic.config.models.SubjectConfig

Bases: BaseModel

Per-animal configuration stored as a YAML file under subjects/.

Captures identity metadata (name, project, experiment) and optional per-task parameter overrides that are merged on top of the task's default settings at session start.

murineshiftwork.logic.config.models.ExecutionConfig

Bases: BaseModel

Runtime bundle assembled at session start from setup, subject, and task.

Collects the resolved SetupConfig, SubjectConfig, and merged task settings into a single object that is passed through the session pipeline. All fields are optional so the object can be built incrementally as each config source becomes available.

Barcode helpers (re-exported from ttl-barcoder) and host-session helpers (from msw-open-ephys) are documented in those packages' own docs.