Platform Enumerations

Provides the cross-system enumerations that define the Sollertia platform vocabulary: acquisition systems, session types, external read assets, and credentials categories.

This module is a leaf: it imports nothing from the rest of the library, so every other module — shared, system-specific, or interface — can use the enumerations without creating circular imports. The dispatch registries keyed by these enumerations are all defined in the registries module.

class sollertia_shared_assets.enums.AcquisitionSystems(*values)

Bases: StrEnum

Defines the data acquisition systems supported by the Sollertia platform.

Every Sollertia acquisition system runs in Virtual Reality, presenting a Unity task in the linear infinite corridor. Each acquisition runtime package owns its own system configuration classes; this enum remains the shared vocabulary that identifies which runtime a session or dataset was acquired on.

MESOSCOPE_VR = 'mesoscope'

Uses the 2-Photon Random Access Mesoscope (2P-RAM) from Thor-Labs and a heavily modified Janelia / Allen hardware harness.

class sollertia_shared_assets.enums.CredentialsTypes(*values)

Bases: StrEnum

Defines the credentials categories supported by the Sollertia platform.

Each member’s string value is the canonical identifier for the credentials’ category. Members are durable contracts added by Sollertia platform maintainers together with a matching CREDENTIALS_FILE_REGISTRY entry; this is a platform-contract surface, not a routine extension point.

GOOGLE = 'google'

The Google service account credentials used for all interactions with the Google Sheets API (canonical filename google_credentials.json).

class sollertia_shared_assets.enums.ReadAssets(*values)

Bases: StrEnum

Defines the external data-asset formats the platform reads and caches as on-disk dataclasses.

Each member’s string value is the canonical identifier for the read-asset format. Members are durable translation contracts added by Sollertia platform maintainers together with a matching READ_ASSET_REGISTRY entry; this is a platform-contract surface, not a routine extension point.

SURGERY_DATA = 'surgery_data'

The animal’s surgical-intervention record read from the platform surgery log and stored on disk as SurgeryData (canonical filename surgery_metadata.yaml).

class sollertia_shared_assets.enums.SessionTypes(*values)

Bases: StrEnum

Defines the data acquisition session types supported by all data acquisition systems in the Sollertia platform.

LICK_TRAINING = 'lick training'

Teaches animals to use the water delivery port while being head-fixed on the Mesoscope-VR system.

MESOSCOPE_EXPERIMENT = 'mesoscope experiment'

Runs virtual reality tasks using Unity game engine and collects brain activity data using the 2-Photon Random Access Mesoscope (2P-RAM).

RUN_TRAINING = 'run training'

Teaches animals to run on the treadmill while being head-fixed on the Mesoscope-VR system.

WINDOW_CHECKING = 'window checking'

Evaluates the quality of the cranial window implantation procedure and the suitability of the animal for experiment sessions using the Mesoscope.

Configuration Assets

Provides configuration assets for data acquisition and processing runtimes in the Sollertia platform.

class sollertia_shared_assets.configuration.Cue(name, code, length_cm, texture='')

Bases: object

Defines a single visual cue used in the experiment task’s Virtual Reality (VR) environment.

Notes

Each cue has a unique name (used in trial cue sequences) and a unique uint8 code (used during MQTT communication and analysis). Cues are not loaded as individual prefabs - they are baked into segment prefabs.

code: int

The unique uint8 code (0-255) that identifies the cue during MQTT communication and data analysis.

length_cm: float

The length of the cue in centimeters.

name: str

The visual identifier for the cue (e.g., ‘A’, ‘B’, ‘Gray’). Used to reference the cue in trial cue sequences.

texture: str

The texture filename (e.g., Cue 016 - 4x1.png) located in the Unity project’s Assets/InfiniteCorridorTask/Textures/ directory. Applied 1:1 to the cue wall panels during prefab generation. Defaults to an empty string for backwards compatibility with templates that predate this field.

class sollertia_shared_assets.configuration.ExperimentState(experiment_state_code, system_state_code, state_duration_s, supports_trials=True, reinforcing_initial_guided_trials=0, reinforcing_recovery_failed_threshold=0, reinforcing_recovery_guided_trials=0, aversive_initial_guided_trials=0, aversive_recovery_failed_threshold=0, aversive_recovery_guided_trials=0)

Bases: object

Defines the structure and runtime parameters of an experiment state (phase).

aversive_initial_guided_trials: int

The number of aversive trials after the onset of the experiment state that use the guidance mode.

aversive_recovery_failed_threshold: int

The number of sequentially failed aversive trials after which to enable the recovery guidance mode.

aversive_recovery_guided_trials: int

The number of guided aversive trials to use in the recovery guidance mode.

experiment_state_code: int

The unique identifier code of the experiment state.

reinforcing_initial_guided_trials: int

The number of reinforcing trials after the onset of the experiment state that use the guidance mode.

reinforcing_recovery_failed_threshold: int

The number of sequentially failed reinforcing trials after which to enable the recovery guidance mode.

reinforcing_recovery_guided_trials: int

The number of guided reinforcing trials to use in the recovery guidance mode.

state_duration_s: float

The time, in seconds, to maintain the experiment state while executing the experiment.

supports_trials: bool

Determines whether trials are executed during this experiment state. When False, no trial-related processing occurs during this phase.

system_state_code: int

The data acquisition system’s state (configuration snapshot) code associated with the experiment state.

class sollertia_shared_assets.configuration.TaskTemplate(cues, vr_environment, trial_structures)

Bases: YamlConfig

Defines a VR task template used by Unity for prefab generation and runtime configuration.

Notes

Task templates contain only the data Unity needs for prefab generation and runtime. Experiment-specific parameters (rewards, guidance, experiment states) are not included here — those live on the matching runtime trial classes defined by each acquisition system and are joined by trial name.

This dataclass can parse any valid task configuration (template) .yaml file from the sollertia-unity-tasks project.

cues: list[Cue]

Defines the Virtual Reality environment wall cues used in the task.

trial_structures: dict[str, TrialStructure]

Defines the spatial configuration for each trial type. Keys are trial names (e.g., ‘ABC’).

vr_environment: VREnvironment

Defines the Virtual Reality corridor configuration.

class sollertia_shared_assets.configuration.TrialStructure(cue_sequence, stimulus_trigger_zone_start_cm, stimulus_trigger_zone_end_cm, stimulus_location_cm, show_stimulus_collision_boundary, trigger_type, occupancy_duration_ms=None, transitions=None)

Bases: object

Defines the spatial configuration of a trial structure for Unity prefabs.

Notes

This class contains only the spatial data needed by Unity for prefab generation and runtime zone configuration. Experiment-specific parameters (reward sizes, puff durations, etc.) live on the matching runtime trial classes defined by each acquisition system and are joined back by trial name.

The trigger_type field specifies the stimulus trigger zone behavior and determines which of the acquisition system’s runtime trial classes is created when loading this template for experiment configuration.

cue_sequence: list[str]

The ordered sequence of cue names that comprise the trial’s segment.

occupancy_duration_ms: float | None

The duration in milliseconds the animal must occupy the zone for occupancy trigger modes. Unity enforces this value and the experiment configuration mirrors it. Leave null for non-occupancy trials to inherit the experiment configuration’s generation default.

show_stimulus_collision_boundary: bool

Determines whether the stimulus collision boundary is visible to the animal during this trial type. When True, the boundary marker is displayed in the Virtual Reality environment at the stimulus location.

stimulus_location_cm: float

The location of the invisible boundary (wall) with which the animal must collide to elicit the stimulus.

stimulus_trigger_zone_end_cm: float

The position of the trial stimulus trigger zone ending boundary, in centimeters.

stimulus_trigger_zone_start_cm: float

The position of the trial stimulus trigger zone starting boundary, in centimeters.

transitions: dict[str, float] | None

Transition probabilities to other trials that make up the task’s corridor environment. Keys must reference other trial names defined on the same TaskTemplate. If provided and non-empty, values must sum to 1.0. Set to null in the YAML file if not used.

trigger_type: str | TriggerType

Specifies the stimulus trigger zone behavior. Must be one of the valid TriggerType enumeration members.

class sollertia_shared_assets.configuration.TriggerType(*values)

Bases: StrEnum

Defines the supported stimulus trigger zone activators for experiment trials.

Notes

These are the platform-wide trigger mechanisms; each acquisition system supports the subset it can resolve to its own stimuli (Mesoscope-VR supports INTERACTION and OCCUPANCY_DISARM, and leaves the rest unmapped). INTERACTION maps to the StimulusTriggerZone prefab (GuidanceZone child) and the three occupancy types to the OccupancyTriggerZone prefab (OccupancyZone + OccupancyGuidanceZone children) in Unity; COLLISION reuses the StimulusTriggerZone prefab as a bare boundary wall.

COLLISION = 'collision'

Indicates a collision-triggered trial where crossing the invisible boundary wall elicits stimulus delivery unconditionally, with no sensor or occupancy requirement.

INTERACTION = 'interaction'

Indicates an interaction-triggered trial where the animal must engage an interaction sensor (lick port, button, lever, pressure plate) inside the stimulus trigger zone to elicit stimulus delivery.

OCCUPANCY_ARM = 'occupancy_arm'

Indicates an occupancy-arm trial where occupying the zone arms the boundary; colliding with the now-armed boundary (occupancy met) elicits stimulus delivery.

OCCUPANCY_DISARM = 'occupancy_disarm'

Indicates an occupancy-disarm trial where occupying the zone disarms the boundary; colliding with the still-armed boundary (occupancy not met) elicits stimulus delivery.

OCCUPANCY_TRIGGER = 'occupancy_trigger'

Indicates an occupancy-trigger trial where occupying the zone for the required duration elicits stimulus delivery immediately, with no boundary collision.

class sollertia_shared_assets.configuration.VREnvironment(corridor_spacing_cm, segments_per_corridor, padding_prefab_name, cm_per_unity_unit, cue_offset_cm)

Bases: object

Defines the Unity Virtual Reality (VR) corridor system configuration.

Notes

This class is primarily used by Unity to configure the task environment. Python parses these values from the YAML configuration file but does not use them at runtime.

cm_per_unity_unit: float

The conversion factor from centimeters to Unity units.

corridor_spacing_cm: float

The horizontal spacing between corridor instances in centimeters.

cue_offset_cm: float

Specifies the offset of the animal’s starting position relative to the Virtual Reality (VR) environment’s cue sequence origin, in centimeters.

padding_prefab_name: str

The name of the Unity prefab used for corridor padding.

segments_per_corridor: int

The number of segments visible in each corridor instance (corridor depth).

sollertia_shared_assets.configuration.get_data_root()

Resolves and returns the path to the local machine’s Sollertia platform data root.

Return type:

Path

Returns:

The path to the local data root, the directory under which all project directories are stored.

Raises:

FileNotFoundError – If the local data root has not been configured for the host-machine, or if the currently configured directory does not exist at the expected path.

sollertia_shared_assets.configuration.get_task_templates_directory()

Resolves and returns the path to the sollertia-unity-tasks project’s Configurations (Template) directory.

Return type:

Path

Returns:

The path to the task templates directory.

Raises:

FileNotFoundError – If the task templates directory path has not been configured for the host-machine, or if the previously configured directory does not exist at the expected path.

sollertia_shared_assets.configuration.get_working_directory()

Resolves and returns the path to the local Sollertia platform working directory.

Return type:

Path

Returns:

The path to the local working directory.

Raises:

FileNotFoundError – If the local working directory has not been configured for the host-machine, or if the currently configured directory does not exist at the expected path.

sollertia_shared_assets.configuration.set_data_root(path)

Sets the specified directory as the local machine’s Sollertia platform data root.

Notes

The data root is the directory under which all project directories, and therefore all animal and session directories, are stored on this machine. Persisting it lets the discovery and inventory assets resolve the project hierarchy without the caller supplying the root each time.

This function caches the path to the data root in the user’s data directory.

If the input path does not point to an existing directory, the function creates the requested directory.

Parameters:

path (Path) – The path to the directory to set as the local Sollertia platform data root.

Return type:

None

sollertia_shared_assets.configuration.set_task_templates_directory(path)

Sets the path to the sollertia-unity-tasks project’s Configurations (Template) directory.

Persists the path under platformdirs-managed application data so it is reused by subsequent slsa mcp sessions on the same local machine (PC).

Parameters:

path (Path) – The path to the sollertia-unity-tasks project’s Configurations (Template) directory.

Raises:

• FileNotFoundError – If the specified directory does not exist at the provided path.

• ValueError – If the specified path does not point to a directory.

Return type:

None

sollertia_shared_assets.configuration.set_working_directory(path)

Sets the specified directory as the Sollertia platform working directory for the local machine (PC).

Notes

This function caches the path to the working directory in the user’s data directory.

If the input path does not point to an existing directory, the function creates the requested directory along with its configuration and credentials subdirectories.

Parameters:

path (Path) – The path to the directory to set as the local Sollertia platform working directory.

Return type:

None

Data Contract Assets

Provides contract dataclasses that translate external data records into on-disk formats for Sollertia libraries.

class sollertia_shared_assets.data_classes.DrugData(drug, drug_volume_ml, drug_code)

Bases: object

Stores information about a single medical substance (drug) administered to the subject before, during, or immediately after the surgical intervention.

Multiple DrugData instances can be used at the same time if the surgery involved administering multiple drugs.

drug: str

The descriptive name of the drug.

drug_code: str

The manufacturer code or internal reference code for the administered drug.

drug_volume_ml: float

The volume of the drug administered to the subject, in milliliters.

class sollertia_shared_assets.data_classes.ImplantData(implant, implant_target, implant_code, implant_ap_coordinate_mm, implant_ml_coordinate_mm, implant_dv_coordinate_mm)

Bases: object

Stores information about a single implantation procedure performed during the surgical intervention.

Multiple ImplantData instances can be used at the same time if the surgery involved multiple implantation procedures.

implant: str

The descriptive name of the implant.

implant_ap_coordinate_mm: float

The implant’s antero-posterior stereotactic coordinate, in millimeters, relative to bregma.

implant_code: str

The manufacturer code or internal reference code for the implant.

implant_dv_coordinate_mm: float

The implant’s dorsal-ventral stereotactic coordinate, in millimeters, relative to bregma.

implant_ml_coordinate_mm: float

The implant’s medial-lateral stereotactic coordinate, in millimeters, relative to bregma.

implant_target: str

The name of the brain region or cranium section targeted by the implant.

class sollertia_shared_assets.data_classes.InjectionData(injection, injection_target, injection_volume_nl, injection_code, injection_ap_coordinate_mm, injection_ml_coordinate_mm, injection_dv_coordinate_mm)

Bases: object

Stores information about a single injection performed during the surgical intervention.

Multiple InjectionData instances can be used at the same time if the surgery involved multiple injections.

injection: str

The descriptive name of the injection.

injection_ap_coordinate_mm: float

The injection’s antero-posterior stereotactic coordinate, in millimeters, relative to bregma.

injection_code: str

The manufacturer code or internal reference code for the injected substance.

injection_dv_coordinate_mm: float

The injection’s dorsal-ventral stereotactic coordinate, in millimeters, relative to bregma.

injection_ml_coordinate_mm: float

The injection’s medial-lateral stereotactic coordinate, in millimeters, relative to bregma.

injection_target: str

The name of the brain region targeted by the injection.

injection_volume_nl: float

The volume of substance, in nanoliters, delivered during the injection.

class sollertia_shared_assets.data_classes.ProcedureData(surgery_start_us, surgery_end_us, surgeon, protocol, surgery_notes, post_op_notes, surgery_quality=0)

Bases: object

Stores general information about the surgical intervention.

post_op_notes: str

The surgeon’s notes taken during the post-surgery recovery period.

protocol: str

The number (ID) of the experiment protocol used during the surgery.

surgeon: str

The surgeon’s name or ID. If the intervention was carried out by multiple surgeons, the data for all surgeons is stored as part of the same string.

surgery_end_us: int

The surgery’s stop date and time as microseconds elapsed since UTC epoch onset.

surgery_notes: str

The surgeon’s notes taken during the surgery.

surgery_quality: int

The quality of the surgical intervention on a scale from 0 to 3 inclusive. 0 indicates unusable (bad) result, 1 indicates usable result that does not meet the publication threshold, 2 indicates publication-grade result, 3 indicates high-tier publication grade result.

surgery_start_us: int

The surgery’s start date and time as microseconds elapsed since UTC epoch onset.

class sollertia_shared_assets.data_classes.SubjectData(id, ear_punch, sex, genotype, date_of_birth_us, weight_g, cage, location_housed, status)

Bases: object

Stores information about the subject of the surgical intervention.

cage: int

The unique identifier (number) of the cage used to house the subject after the surgery.

date_of_birth_us: int

The subject’s date of birth, stored as the number of microseconds elapsed since the UTC epoch onset.

ear_punch: str

The number and the locations of ear-tags used to distinguish the subject from its cage-mates.

genotype: str

The subject’s genotype.

id: int

The subject’s unique identifier.

location_housed: str

The location (room) used to house the subject after the surgery.

sex: str

The subject’s sex.

status: str

The current subject’s status (alive / deceased).

weight_g: float

The subject’s pre-surgery weight, in grams.

class sollertia_shared_assets.data_classes.SurgeryData(subject, procedure, drugs, implants, injections)

Bases: YamlConfig

Stores information about a surgical intervention performed on an animal before data acquisition session(s).

drugs: list[DrugData]

Stores information about all medical substances (drugs) administered to the subject before, during, and immediately after the surgical intervention.

implants: list[ImplantData]

Stores information about all implantation procedures performed during the surgical intervention.

injections: list[InjectionData]

Stores information about all injections (brain infusions) performed during the surgical intervention.

procedure: ProcedureData

Stores general information about the surgical intervention.

subject: SubjectData

Stores information about the subject of the surgical intervention.

Data Hierarchy Assets

Provides assets for creating, discovering, and accessing the Sollertia platform project data hierarchy across all data acquisition and processing machines.

class sollertia_shared_assets.data_hierarchy.AnimalData(root, project_name, animal_id)

Bases: object

Resolves the on-disk locations of a single animal’s assets under a given data root.

Like ProjectData, instances are path-grammar views that do not require the animal directory to exist. Rebind the animal under a different root with for_root to resolve its session paths on a remote storage root.

animal_id: str

The unique identifier of the animal, used as the animal directory name.

exists()

Determines whether the animal directory exists on disk under the project.

Return type:

bool

for_root(root)

Returns a copy of this animal anchored on a different data root.

Parameters:

root (Path) – The data root to rebind the animal under, such as a mounted remote storage root.

Return type:

AnimalData

Returns:

A new AnimalData with the same project and animal resolved under the input root.

property path: Path

Returns the absolute path to the animal directory under the project.

property persistent_data_path: Path

Returns the absolute path to the animal’s cross-session persistent data directory.

property project: ProjectData

Returns the ProjectData view for the project this animal belongs to.

project_name: str

The name of the project the animal belongs to.

root: Path

The data root under which the project hierarchy is stored.

session_path(session_name)

Returns the absolute path to the session directory for the given session name.

Parameters:

session_name (str) – The unique identifier of the session, used as the session directory name.

Return type:

Path

Returns:

The absolute path to the session directory under this animal.

class sollertia_shared_assets.data_hierarchy.Directories(*values)

Bases: StrEnum

Enumerates the canonical names of subdirectories found under a session’s raw_data or processed_data that are shared across all acquisition systems on the platform.

BEHAVIOR_DATA = 'behavior_data'

Behavior data directory. Contains raw DataLogger NPZ archives under raw_data and processed behavior feather files under processed_data.

CAMERA_DATA = 'camera_data'

Camera data directory. Stores the raw camera recordings under raw_data and the outputs of the sollertia-forgery video-processing pipeline (DeepLabCut pose estimation followed by re-packaging) under processed_data.

CAMERA_TIMESTAMPS = 'camera_timestamps'

Camera timestamps directory under processed_data. Stores the per-frame timing data extracted by the ataraxis-video-system log-processing pipeline.

CINDRA = 'cindra'

Cindra output directory under processed_data. The root of cindra’s single-recording and multi-recording outputs. Cindra is reusable by any photometry-data-generating acquisition system.

MICROCONTROLLER_DATA = 'microcontroller_data'

Microcontroller data directory under processed_data. Stores the extracted microcontroller data produced by the ataraxis-communication-interface log-processing pipeline. Microcontroller raw data is bundled into the DataLogger archives under raw_data/behavior_data rather than living in a dedicated raw-side directory.

MULTI_RECORDING = 'multi_recording'

Multi-recording subdirectory inside cindra’s output directory. Each child is a dataset-named directory holding cindra’s multi-day analysis output.

class sollertia_shared_assets.data_hierarchy.ProcessedData(behavior_data_path, behavior_tracker_path, camera_timestamps_path, camera_tracker_path, video_data_path, video_tracker_path, microcontroller_data_path, microcontroller_tracker_path, cindra_data_path, cindra_single_recording_tracker_path, cindra_multi_recording_path)

Bases: object

Stores the absolute paths to all generic processed assets of a single data acquisition session.

Notes

Cindra fields live here because cindra is reusable by any photometry-data-generating acquisition system, not Mesoscope-VR-specific. Future processing tools that apply across acquisition systems get added directly as new fields here.

behavior_data_path: Path

Holds the extracted behavior data produced by the sollertia-forgery behavior-processing pipeline.

behavior_tracker_path: Path

Tracks the outcome of behavior-data extraction performed by the sollertia-forgery behavior-processing pipeline.

classmethod build(root)

Builds a ProcessedData instance with every field resolved against the input processed data root.

Parameters:

root (Path) – The path to the session’s processed_data directory.

Return type:

ProcessedData

Returns:

A ProcessedData instance whose fields are absolute paths under the input root.

camera_timestamps_path: Path

Holds the per-frame camera timing data extracted by the ataraxis-video-system log-processing pipeline, used to align the camera recordings with the rest of the session’s data.

camera_tracker_path: Path

Tracks the outcome of camera-timestamp extraction performed by the ataraxis-video-system log-processing pipeline.

cindra_data_path: Path

Acts as the root for both single-recording and multi-recording cindra outputs. Cindra is reusable by any photometry-data-generating acquisition system on the Sollertia platform, which is why these fields live on the generic ProcessedData rather than on an acquisition-system-specific dataclass.

cindra_multi_recording_path: Path

Acts as the root for cindra’s multi-recording analysis outputs. Each child holds the multi-day analysis output produced by cindra’s multi-recording pipeline for a particular dataset that this session participates in.

cindra_single_recording_tracker_path: Path

Tracks the outcome of single-recording neural imaging analysis performed by cindra’s single-recording pipeline.

microcontroller_data_path: Path

Holds the extracted microcontroller data produced by the ataraxis-communication-interface log-processing pipeline.

microcontroller_tracker_path: Path

Tracks the outcome of microcontroller-event extraction performed by the ataraxis-communication-interface log-processing pipeline.

video_data_path: Path

Holds the DeepLabCut pose-estimation output re-packaged by the sollertia-forgery video-processing pipeline.

video_tracker_path: Path

Tracks the outcome of DeepLabCut processing and re-packaging performed by the sollertia-forgery video-processing pipeline.

class sollertia_shared_assets.data_hierarchy.ProcessingTrackers(*values)

Bases: StrEnum

Enumerates canonical ProcessingTracker filenames written by each data-integrity and processing pipeline shared across all acquisition systems on the platform.

ANALYSIS = 'analysis_tracker.yaml'

Tracker for the sollertia-forgery analysis pipeline.

BEHAVIOR = 'behavior_processing_tracker.yaml'

Tracker for the behavior processing pipeline.

CAMERA = 'camera_processing_tracker.yaml'

Tracker for the ataraxis-video-system camera timestamp processing pipeline.

CHECKSUM = 'checksum_processing_tracker.yaml'

Tracker for the checksum verification pipeline.

CINDRA_MULTI_RECORDING = 'multi_recording_tracker.yaml'

Tracker for cindra’s multi-recording pipeline.

CINDRA_SINGLE_RECORDING = 'single_recording_tracker.yaml'

Tracker for cindra’s single-recording pipeline.

FORGING = 'forging_tracker.yaml'

Tracker for the sollertia-forgery dataset-forging pipeline.

MANIFEST = 'manifest_processing_tracker.yaml'

Tracker for the project manifest generation pipeline.

MICROCONTROLLER = 'microcontroller_processing_tracker.yaml'

Tracker for the ataraxis-communication-interface microcontroller log processing pipeline.

TRANSFER = 'transfer_processing_tracker.yaml'

Tracker for batch session transfer and deletion jobs. Location is specified by the caller, since transfer jobs are not bound to a single session or dataset.

VIDEO = 'video_processing_tracker.yaml'

Tracker for the sollertia-forgery video processing pipeline (re-packaging of DeepLabCut outputs).

class sollertia_shared_assets.data_hierarchy.ProjectData(root, project_name)

Bases: object

Resolves the on-disk locations of a single project’s assets under a given data root.

Instances are lightweight path-grammar views: they construct paths from the root and project name and do not require the project directory to exist on disk. Rebind the same project under a different root with for_root to resolve its locations on a remote storage root, or materialize the project’s directory structure on the current root with create.

animal(animal_id)

Returns the AnimalData view for the given animal under this project.

Parameters:

animal_id (str) – The unique identifier of the animal, used as the animal directory name.

Return type:

AnimalData

Returns:

An AnimalData anchored on the same root and project as this instance.

property configuration_directory: Path

Returns the absolute path to the project’s experiment configuration directory.

create()

Creates the project’s directory structure under the data root.

Materializes the project’s configuration directory, which also creates the project directory itself as a parent. The operation is idempotent, so existing directories are left untouched.

Return type:

ProjectData

Returns:

This instance, to support call chaining.

exists()

Determines whether the project directory exists on disk under the data root.

Return type:

bool

experiment_configs()

Returns the sorted experiment configuration YAML paths under the project’s configuration directory.

Return type:

tuple[Path, ...]

Returns:

A tuple of the .yaml file paths directly under the configuration directory, empty when the directory does not exist.

for_root(root)

Returns a copy of this project anchored on a different data root.

Parameters:

root (Path) – The data root to rebind the project under, such as a mounted remote storage root.

Return type:

ProjectData

Returns:

A new ProjectData with the same project name resolved under the input root.

property path: Path

Returns the absolute path to the project directory under the data root.

project_name: str

The name of the project, used as the project directory name directly under the root.

root: Path

The data root under which the project hierarchy is stored.

class sollertia_shared_assets.data_hierarchy.RawData(session_data_path, session_descriptor_path, surgery_metadata_path, hardware_state_path, system_configuration_path, experiment_configuration_path, vr_configuration_path, checksum_path, checksum_tracker_path, nk_path, behavior_data_path, camera_data_path)

Bases: object

Stores the absolute paths to all generic raw assets of a single data acquisition session.

Notes

Instances are constructed by SessionData._build_sub_dataclasses after the session’s raw data root has been finalized. The build classmethod is the single source of truth for the enum-to-field mapping.

behavior_data_path: Path

Holds the raw behavior data captured during acquisition, including the raw messages emitted by every microcontroller managed by ataraxis-communication-interface.

classmethod build(root)

Builds a RawData instance with every field resolved against the input raw data root.

Parameters:

root (Path) – The path to the session’s raw_data directory.

Return type:

RawData

Returns:

A RawData instance whose fields are absolute paths under the input root.

camera_data_path: Path

Holds the raw camera recordings captured during acquisition.

checksum_path: Path

Stores the ataraxis data-integrity checksum used by the checksum verification pipeline to detect corruption or accidental modification of raw assets after acquisition.

checksum_tracker_path: Path

Tracks the outcome of integrity checks performed by the checksum verification pipeline.

experiment_configuration_path: Path

Stores the experiment configuration in effect when the session was acquired. Only populated for experiment sessions; callers should check .exists() before reading. The concrete parsing class is determined by the session’s acquisition_system and is dispatched via EXPERIMENT_CONFIGURATION_REGISTRY.

hardware_state_path: Path

Records the configuration of every active hardware module on the acquisition system, used to interpret the raw data during downstream processing. The concrete parsing class is determined by the session’s acquisition_system and is dispatched via HARDWARE_STATE_REGISTRY.

nk_path: Path

Marks the session as uninitialized while the acquisition runtime is still creating snapshots and initializing instruments. Removed by mark_runtime_initialized() once the session is ready to begin acquisition.

session_data_path: Path

Stores the metadata that identifies the session and resolves the on-disk locations of all of its assets.

session_descriptor_path: Path

Stores the task parameters and outcome metadata captured during acquisition. The concrete descriptor class is determined by the session’s session_type and is dispatched via DESCRIPTOR_REGISTRY.

surgery_metadata_path: Path

Stores a frozen snapshot of the animal’s surgical history (subject, procedure, drugs, implants, injections) as it stood at the moment the session was acquired.

system_configuration_path: Path

Preserves the acquisition-system-level configuration in effect when the session was acquired. The concrete parsing class is determined by the session’s acquisition_system and is owned by sollertia-experiment.

vr_configuration_path: Path

Stores the linear infinite corridor task template (cues, VR environment, trial structures) active when the session was acquired. Written only for sessions that run the corridor task, so callers should check .exists() before reading. Parsed via TaskTemplate.

class sollertia_shared_assets.data_hierarchy.RawDataFiles(*values)

Bases: StrEnum

Enumerates the canonical filenames at the root of a session’s raw_data directory that are written by every acquisition system on the platform.

CHECKSUM = 'ax_checksum.txt'

The ataraxis data integrity checksum for the session’s raw_data directory.

EXPERIMENT_CONFIGURATION = 'experiment_configuration.yaml'

The experiment configuration YAML copied into the session for experiment sessions only.

HARDWARE_STATE = 'hardware_state.yaml'

The hardware state snapshot YAML written at the start of acquisition.

NK_MARKER = 'nk.bin'

The ‘uninitialized session’ marker present in raw_data while the acquisition runtime has not yet finished creating snapshots and initializing instruments. Removed by mark_runtime_initialized() once initialization completes.

SESSION_DATA = 'session_data.yaml'

The session marker YAML serialized from SessionData itself.

SESSION_DESCRIPTOR = 'session_descriptor.yaml'

The session-embedded descriptor YAML written by the acquisition runtime. The concrete descriptor class is determined by the session’s session_type, but the filename is flat across all session types.

SURGERY_METADATA = 'surgery_metadata.yaml'

The per-animal surgery metadata YAML cached into the session’s raw_data at acquisition time.

SYSTEM_CONFIGURATION = 'system_configuration.yaml'

The system configuration YAML copied into the session by the acquisition runtime.

VR_CONFIGURATION = 'vr_configuration.yaml'

The linear infinite corridor task template YAML (cues, VR environment, trial structures) cached into the session at acquisition time. Written only for sessions that run the corridor task.

class sollertia_shared_assets.data_hierarchy.SessionData(project_name, animal_id, session_name, session_type, acquisition_system, experiment_name=None, python_version='3.14.6', sollertia_experiment_version='5.0.0', raw_data_path=PosixPath('.'), processed_data_path=PosixPath('.'))

Bases: YamlConfig

Defines the structure and the metadata of a data acquisition session.

This class encapsulates the information necessary to access the session’s data stored on disk and functions as the entry point for all interactions with the session’s data.

Notes

Do not initialize this class directly. Instead, use the create() method when starting new data acquisition sessions or the load() method when accessing data for an existing session. Both methods build the runtime-only raw_data, processed_data, and system_raw_data sub-dataclass attributes from the currently configured root paths. create() finalizes only raw_data_path; the processed_data root is resolved later, on the processing host, by load(), which finalizes both. Instances constructed via from_yaml directly (without going through load()) do not have these attributes populated; access raises AttributeError.

When this class is used to create a new session, it generates the new session’s name using the current UTC timestamp, accurate to microseconds. This ensures that each session ‘name’ is unique and preserves the overall session order.

raw_data

The runtime-only sub-dataclass exposing the session’s raw-data asset paths, populated by create() and load().

processed_data

The runtime-only sub-dataclass exposing the session’s processed-data asset paths, populated by load().

system_raw_data

The runtime-only sub-dataclass exposing the acquisition-system-specific raw-data asset paths, populated by create() and load().

acquisition_system: str | AcquisitionSystems

The name of the data acquisition system used to acquire the session’s data.

animal_id: str

The unique identifier of the animal that participates in the session.

classmethod create(animal, session_type, python_version, sollertia_experiment_version, acquisition_system, experiment_name=None)

Initializes a new data acquisition session and creates its data structure on the host-machine’s filesystem.

Notes

To access the data of an already existing session, use the load() method.

Parameters:

• animal (AnimalData) – The AnimalData view identifying the data root, project, and animal under which the session is created. The session is created under animal.session_path(<session_name>).

• session_type (str | SessionTypes) – The type of the session.

• python_version (str) – The Python version used to acquire the session’s data.

• sollertia_experiment_version (str) – The sollertia-experiment library version used to acquire the session’s data.

• acquisition_system (str | AcquisitionSystems) – The acquisition system that will run the session. Accepts an AcquisitionSystems enumeration member or its string value.

• experiment_name (str | None, default: None) – The name of the experiment performed during the session or None, if the session is not an experiment session.

Return type:

SessionData

Returns:

An initialized SessionData instance that stores the structure and the metadata of the created session.

Raises:

• ValueError – If the specified session_type or acquisition_system is not a valid enumeration member.

• FileNotFoundError – If the project does not exist on the local machine (PC).

experiment_name: str | None = None

The name of the experiment performed during the session or Null (None), if the session is not an experiment session.

classmethod load(session_path)

Loads the target session’s data from the specified session_data.yaml file.

Notes

To create a new session, use the create() method.

Parameters:

session_path (Path) – The path to the directory where to search for the session_data.yaml file. Typically, this is the path to the root session’s directory, e.g.: root/project/animal/session.

Return type:

SessionData

Returns:

An initialized SessionData instance that stores the loaded session’s data.

Raises:

FileNotFoundError – If multiple or no ‘session_data.yaml’ file instances are found under the input directory.

mark_runtime_initialized()

Removes the ‘nk.bin’ uninitialized-session marker after acquisition-runtime initialization completes.

Return type:

None

Notes

This service method is used by the sollertia-experiment library when it acquires a session’s data. Do not call it manually. Removal of the marker only changes the uninitialized signal; the separate descriptor incomplete field is updated independently by the runtime at session end to report whether acquisition completed without issues.

Resolves the marker path directly from raw_data_path so the method works on instances that have not yet been routed through _build_sub_dataclasses.

processed_data_path: Path = PosixPath('.')

The path to the root directory that stores the session’s processed data.

project_name: str

The name of the project for which the session was acquired.

python_version: str = '3.14.6'

The Python version used to acquire session’s data.

raw_data_path: Path = PosixPath('.')

The path to the root directory that stores the session’s raw data.

required_raw_assets()

Returns the canonical filename and absolute path of every raw asset this session is required to contain.

Every session requires the session descriptor and the system configuration snapshot. Experiment sessions (those with an experiment_name) additionally require the experiment configuration snapshot, and sessions whose type runs the corridor task (those in SESSION_TYPES_USING_VR_TASK) additionally require the VR configuration snapshot. The session-inspection tooling pairs each returned path with its on-disk presence to report missing required assets, so this method is the single source of truth for the required-asset policy.

Return type:

list[tuple[str, Path]]

Returns:

A list of (canonical_filename, absolute_path) tuples, one per raw asset the session must contain.

save()

Caches the instance’s data to the session’s ‘raw_data’ directory as a ‘session_data.yaml’ file.

Return type:

None

Notes

Resolves the destination path directly from raw_data_path so the method works on instances that have not yet been routed through _build_sub_dataclasses.

session_name: str

The unique identifier (name) of the session.

session_type: str | SessionTypes

The type of the session.

sollertia_experiment_version: str = '5.0.0'

The sollertia-experiment library version used to acquire the session’s data.

sollertia_shared_assets.data_hierarchy.discover_projects(root_path, strategy='markers')

Discovers the projects under a data root and returns them as ProjectData views.

The markers strategy is authoritative: it loads every session marker and buckets projects by their SessionData identity, so only projects that hold at least one session surface and stray directories cannot appear as phantom projects. The directories strategy lists the project directories directly, which also surfaces projects that hold no sessions yet, at the cost of trusting the directory layout.

Parameters:

• root_path (Path) – The absolute path to the data root to scan.

• strategy (Literal['markers', 'directories'], default: 'markers') – Whether to derive projects from session markers (markers) or from the directory layout (directories).

Return type:

list[ProjectData]

Returns:

A list of ProjectData views anchored on the data root, sorted by project name.

sollertia_shared_assets.data_hierarchy.discover_sessions(root_path)

Discovers session root directories under a root path by locating session_data.yaml markers.

Recursively searches for RawDataFiles.SESSION_DATA markers and derives each session’s root directory from the marker location. Returns only the resolved paths without loading or validating session data, making this function suitable as a lightweight discovery primitive for both MCP tools and internal pipeline code.

Parameters:

root_path (Path) – The absolute path to the directory to search recursively.

Return type:

list[Path]

Returns:

A sorted list of absolute paths to session root directories found under root_path.

Raises:

PermissionError – If the search encounters a directory it cannot read.

sollertia_shared_assets.data_hierarchy.filter_sessions(sessions, *, start_date=None, end_date=None, include_sessions=None, exclude_sessions=None, include_animals=None, exclude_animals=None, utc_timezone=True)

Filters (session_name, animal) pairs by date range and inclusion-exclusion criteria.

Provides a general-purpose filtering mechanism for selecting a subset of sessions. Animal filtering is applied before session filtering. Exclusion filtering takes precedence over inclusion filtering.

Notes

The input is intentionally a plain iterable of (session_name, animal) tuples rather than a richer type. Callers with domain-specific session types (e.g. forgery’s DatasetSession) map their sets to tuples on the way in and rehydrate on the way out with a one-line comprehension.

Parameters:

• sessions (Iterable[tuple[str, str]]) – An iterable of (session_name, animal) string tuples. The first element is the canonical session name (YYYY-MM-DD-HH-MM-SS-microseconds); the second is the animal identifier.

• start_date (str | None, default: None) – The start date for the date range filter. Sessions recorded on or after this date are included. Accepts formats like YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. When None, no start bound is applied.

• end_date (str | None, default: None) – The end date for the date range filter. Sessions recorded on or before this date are included. Date-only values include the entire day. When None, no end bound is applied.

• include_sessions (set[str] | None, default: None) – Session names to include regardless of the date range. Sessions in this set are added even when they fall outside the start_date / end_date range, unless they are also in exclude_sessions.

• exclude_sessions (set[str] | None, default: None) – Session names to exclude from the results. Takes precedence over every other inclusion criterion.

• include_animals (set[str] | None, default: None) – Animal identifiers to include. When provided, only sessions from these animals are considered. When None, sessions from all animals are considered.

• exclude_animals (set[str] | None, default: None) – Animal identifiers to exclude. Takes precedence over include_animals.

• utc_timezone (bool, default: True) – Determines whether to interpret date boundaries and session timestamps in UTC (True) or the host machine’s local time (False). Session names reflect UTC timestamps; when this flag is False, timestamps are converted to local time before comparison.

Return type:

set[tuple[str, str]]

Returns:

A set of (session_name, animal) tuples matching every filter.

sollertia_shared_assets.data_hierarchy.get_projects_for_animal(root_path, animal_id)

Returns the names of all projects under the data root that include the given animal.

Project membership is derived from session markers, so a project is reported only when it holds at least one session for the animal.

Parameters:

• root_path (Path) – The absolute path to the data root to scan.

• animal_id (str) – The unique identifier of the animal whose projects are discovered.

Return type:

tuple[str, ...]

Returns:

A sorted tuple of project names that include the animal.

sollertia_shared_assets.data_hierarchy.get_session_root_from_marker(marker)

Returns the session root directory from a session_data.yaml marker path.

The marker lives at {session_root}/raw_data/session_data.yaml, so the session root is two directory levels above the marker file.

Parameters:

marker (Path) – The absolute path to a session_data.yaml file.

Return type:

Path

Returns:

The path to the session root directory (the grandparent of the marker).

sollertia_shared_assets.data_hierarchy.iter_animal_sessions(animal)

Discovers the session directories under an animal and yields their root paths.

Enumeration is directory-based: child directories whose names parse as session timestamps are yielded as session roots, so sessions are surfaced without reading any markers. This complements the marker-based discover_sessions for callers that already know the animal hierarchy and want to avoid a recursive scan. Non-session children, such as the persistent-data directory and hidden directories, do not parse as session names and are therefore skipped.

Parameters:

animal (AnimalData) – The AnimalData view whose session directories are discovered.

Yields:

Each session root path under the animal, in sorted order.

sollertia_shared_assets.data_hierarchy.iter_project_animals(project)

Discovers the animal directories under a project and yields them as AnimalData views.

Enumeration is directory-based, so animals that hold no sessions yet are included. The project’s configuration directory, dataset directories, and hidden directories are skipped because they are not animals.

Parameters:

project (ProjectData) – The ProjectData view whose animal directories are discovered.

Yields:

Each AnimalData view for an animal directory under the project, in sorted order.

sollertia_shared_assets.data_hierarchy.iterate_sessions(root_path)

Discovers and lazily loads every SessionData instance under the target root directory.

Composes discover_sessions with SessionData.load so that callers can switch from project-wide rglob scans to typed iteration in a single call. The returned iterator yields sessions in the same sorted order as discover_sessions.

Parameters:

root_path (Path) – The absolute path to the directory to search recursively for session markers.

Yields:

Each SessionData instance loaded from a session marker found under root_path.

sollertia_shared_assets.data_hierarchy.parse_session_timestamp(session_name, *, utc_timezone=True)

Parses a Sollertia session name and returns its acquisition datetime.

Session names follow the format YYYY-MM-DD-HH-MM-SS-microseconds and encode the acquisition timestamp in UTC. Returns None rather than raising when the name does not follow this format, so callers can skip non-conforming directory names during discovery walks.

Parameters:

• session_name (str) – The unique identifier of the session.

• utc_timezone (bool, default: True) – Determines whether to return the datetime in UTC. When False, converts to the host machine’s local time.

Return type:

datetime | None

Returns:

A timezone-aware datetime representing when the session was acquired, or None when the session name does not follow the expected format.

sollertia_shared_assets.data_hierarchy.validate_directory(directory)

Checks that the given path string refers to an existing directory.

Provides a lightweight existence check for MCP tool and pipeline call sites that already have a caller-supplied path and only need a boolean-shaped verdict. Returns None when the path is a valid directory, or a human-readable error string suitable for inclusion in an MCP tool response.

Parameters:

directory (str) – The absolute path string to validate as an existing directory.

Return type:

str | None

Returns:

None when the path points to an existing directory, otherwise a human-readable error message.

Mesoscope-VR Assets

Provides the data acquisition and processing assets specific to the Mesoscope-VR acquisition system.

class sollertia_shared_assets.mesoscope_vr.LickTrainingDescriptor(experimenter, animal_weight_g, minimum_reward_delay_s=6, maximum_reward_delay_s=18, maximum_water_volume_ml=1.0, maximum_training_time_min=20, maximum_unconsumed_rewards=1, water_reward_size_ul=5.0, reward_tone_duration_ms=300, dispensed_water_volume_ml=0.0, pause_dispensed_water_volume_ml=0.0, experimenter_given_water_volume_ml=0.0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the task and outcome information specific to lick training sessions that use the Mesoscope-VR system.

animal_weight_g: float

The weight of the animal, in grams, at the beginning of the session.

dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during runtime. This excludes the water volume dispensed during the paused (idle) state.

experimenter: str

The ID of the experimenter running the session.

experimenter_given_water_volume_ml: float = 0.0

The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.

experimenter_notes: str = 'Replace this with your notes.'

Stores the experimenter’s notes made during runtime.

incomplete: bool = True

Tracks whether the session’s data is complete and eligible for unsupervised data processing.

maximum_reward_delay_s: int = 18

The maximum delay, in seconds, that can separate the delivery of two consecutive water rewards.

maximum_training_time_min: int = 20

The maximum time, in minutes, the system is allowed to run the training.

maximum_unconsumed_rewards: int = 1

The maximum number of consecutive rewards that can be delivered without the animal consuming them. If the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal consumes the delivered rewards.

maximum_water_volume_ml: float = 1.0

The maximum volume of water the system is allowed to dispense during training.

minimum_reward_delay_s: int = 6

The minimum delay, in seconds, that can separate the delivery of two consecutive water rewards.

pause_dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during the paused (idle) state.

reward_tone_duration_ms: int = 300

The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards.

water_reward_size_ul: float = 5.0

The volume of water, in microliters, dispensed to the animal when it achieves the required running speed and duration thresholds.

class sollertia_shared_assets.mesoscope_vr.MesoscopeDirectories(*values)

Bases: StrEnum

Enumerates the canonical names of subdirectories under a session’s raw_data directory that are written exclusively by the Mesoscope-VR acquisition system.

MESOSCOPE_DATA = 'mesoscope_data'

Persistent mesoscope data directory under raw_data. Stores LERC-compressed TIFF stacks and acquisition metadata written by sollertia-experiment’s preprocessing.

class sollertia_shared_assets.mesoscope_vr.MesoscopeExperimentConfiguration(trial_structures, experiment_states, unity_scene_name)

Bases: YamlConfig

Defines an experiment session that uses the Mesoscope-VR data acquisition system.

Implements the full experiment-configuration contract shared by every Sollertia acquisition system: the experiment_states state machine, the trial_structures table, the unity_scene_name of the linear infinite corridor task the experiment runs, and the from_task_template builder. The configuration is consumed by the acquisition runtime (sollertia-experiment) and the analysis pipeline (sollertia-forgery).

experiment_states: dict[str, ExperimentState]

The experiment state machine, keyed by state name. This contract field is required by every experiment configuration.

classmethod from_task_template(template, unity_scene_name, state_count=1, default_reward_size_ul=5.0, default_reward_tone_duration_ms=300, default_puff_duration_ms=100)

Builds a Mesoscope-VR experiment configuration from a Unity VR task template.

Maps each of the template’s trial structures to a runtime trial class by its trigger type, pairing TriggerType.INTERACTION with a MesoscopeWaterRewardTrial and TriggerType.OCCUPANCY_DISARM with a MesoscopeGasPuffTrial. Then seeds state_count sequentially numbered runtime states (‘state_1’, ‘state_2’, and so on) whose reinforcing or aversive guidance defaults follow the trial types present in the template.

Parameters:

• template (TaskTemplate) – The task template whose VR trial structures (cues, trial zones) seed the configuration.

• unity_scene_name (str) – The Unity scene name for the experiment. This should match the template YAML file name so SessionData.create() can locate the corresponding VR template during snapshot export. Matching is the caller’s responsibility and is not validated here.

• state_count (int, default: 1) – The number of default-valued runtime states to generate.

• default_reward_size_ul (float, default: 5.0) – Water reward volume in microliters for interaction-type trials.

• default_reward_tone_duration_ms (int, default: 300) – Reward tone duration in milliseconds for interaction-type trials.

• default_puff_duration_ms (int, default: 100) – Gas puff duration in milliseconds for occupancy-disarm trials.

Return type:

MesoscopeExperimentConfiguration

Returns:

The experiment configuration populated with the template’s trial structures and the requested number of default-valued runtime states.

Raises:

ValueError – If any of the template’s trial structures uses a TriggerType that is not mapped to a Mesoscope-VR runtime trial class. Only TriggerType.INTERACTION and TriggerType.OCCUPANCY_DISARM are mapped to runtime trial classes.

trial_structures: dict[str, MesoscopeWaterRewardTrial | MesoscopeGasPuffTrial]

The trials the experiment runs, keyed by trial name. This contract field is required by every experiment configuration; MesoscopeWaterRewardTrial and MesoscopeGasPuffTrial are Mesoscope-VR’s trial classes.

unity_scene_name: str

The Unity scene (VR task) the experiment runs in the linear infinite corridor, identifying the paired task template by filename stem. This contract field is required by every experiment configuration.

class sollertia_shared_assets.mesoscope_vr.MesoscopeExperimentDescriptor(experimenter, animal_weight_g, maximum_unconsumed_rewards=1, dispensed_water_volume_ml=0.0, pause_dispensed_water_volume_ml=0.0, experimenter_given_water_volume_ml=0.0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the task and outcome information specific to experiment sessions that use the Mesoscope-VR system.

animal_weight_g: float

The weight of the animal, in grams, at the beginning of the session.

dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during runtime. This excludes the water volume dispensed during the paused (idle) state.

experimenter: str

The ID of the experimenter running the session.

experimenter_given_water_volume_ml: float = 0.0

The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.

experimenter_notes: str = 'Replace this with your notes.'

Stores the experimenter’s notes made during runtime.

incomplete: bool = True

Tracks whether the session’s data is complete and eligible for unsupervised data processing.

maximum_unconsumed_rewards: int = 1

The maximum number of consecutive rewards that can be delivered without the animal consuming them. If the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal consumes the delivered rewards.

pause_dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during the paused (idle) state.

class sollertia_shared_assets.mesoscope_vr.MesoscopeGasPuffTrial(puff_duration_ms=100)

Bases: object

Defines a Mesoscope-VR trial that delivers a gas puff (an aversive stimulus) when the animal fails the trial’s avoidance condition.

The animal avoids the puff by satisfying the task’s occupancy condition; failing to do so delivers a puff of the configured duration. The behavioral condition is defined by the task, not by this class.

puff_duration_ms: int

The duration, in milliseconds, for which to deliver the gas puff when the animal fails the trial.

class sollertia_shared_assets.mesoscope_vr.MesoscopeHardwareState(cm_per_pulse=None, maximum_brake_strength=None, minimum_brake_strength=None, lick_threshold=None, valve_scale_coefficient=None, valve_nonlinearity_exponent=None, torque_per_adc_unit=None, screens_initially_on=None, recorded_mesoscope_ttl=None, delivered_gas_puffs=None, system_state_codes=None)

Bases: YamlConfig

Stores configuration parameters (states) of the Mesoscope-VR system hardware modules used during training or experiment runtimes.

Notes

All hardware parameters are stored using the appropriate datatypes and rounding methods that ensure their complete equivalence to the values used by the data acquisition system during runtime.

Any field set to None indicates that the corresponding hardware module was not used by the executed data acquisition runtime.

cm_per_pulse: float | None = None

The conversion factor used to translate encoder pulses into centimeters.

delivered_gas_puffs: bool | None = None

Tracks whether the session delivered any gas puffs to the animal.

lick_threshold: int | None = None

Determines the threshold, in 12-bit Analog to Digital Converter (ADC) units reported by the lick sensor, for considering the reported signal a lick.

maximum_brake_strength: float | None = None

The braking torque, in Newton centimeters, applied by the brake to the edge of the running wheel when it is maximally engaged.

minimum_brake_strength: float | None = None

The braking torque, in Newton centimeters, applied by the brake to the edge of the running wheel when it is completely disengaged.

recorded_mesoscope_ttl: bool | None = None

Tracks whether the session recorded brain activity data with the mesoscope.

screens_initially_on: bool | None = None

Stores the initial state of the Virtual Reality screens at the beginning of the session’s runtime.

system_state_codes: dict[str, int] | None = None

Maps integer state-codes used by the Mesoscope-VR system to communicate its states (system states) to human-readable state names.

torque_per_adc_unit: float | None = None

The conversion factor used to translate torque values reported by the sensor as 12-bit Analog to Digital Converter (ADC) units into Newton centimeters (N·cm).

valve_nonlinearity_exponent: float | None = None

The nonlinearity exponent of the power law equation that describes the relationship between the time the valve is kept open and the dispensed water volume.

valve_scale_coefficient: float | None = None

The scale coefficient of the power law equation that describes the relationship between the time the valve is kept open and the dispensed water volume.

class sollertia_shared_assets.mesoscope_vr.MesoscopeRawData(zaber_positions_path, mesoscope_positions_path, window_screenshot_path, mesoscope_data_path)

Bases: object

Stores the absolute paths to the Mesoscope-VR-specific raw assets of a single data acquisition session.

Notes

Instances are constructed by SessionData._build_sub_dataclasses when the session’s acquisition_system is AcquisitionSystems.MESOSCOPE_VR. The build classmethod is the single source of truth for the enum-to-field mapping.

classmethod build(root)

Builds a MesoscopeRawData instance with every field resolved against the input raw data root.

Parameters:

root (Path) – The path to the session’s raw_data directory.

Return type:

MesoscopeRawData

Returns:

A MesoscopeRawData instance whose fields are absolute paths under the input root.

mesoscope_data_path: Path

Holds the compressed 2-Photon Random Access Mesoscope (2P-RAM) acquisition output and accompanying metadata produced by sollertia-experiment’s preprocessing, which serves as the input to cindra’s neural imaging analysis pipelines.

mesoscope_positions_path: Path

Records the 2-Photon Random Access Mesoscope (2P-RAM) objective position used to image the cranial window during the session, allowing the same imaging field of view to be recovered in follow-up sessions.

window_screenshot_path: Path

Provides a visual reference of the cranial imaging window taken at the start of the session, used for downstream registration and quality assessment.

zaber_positions_path: Path

Captures the states of the Zaber motorized stages used by the Mesoscope-VR system at the start of the session.

class sollertia_shared_assets.mesoscope_vr.MesoscopeRawDataFiles(*values)

Bases: StrEnum

Enumerates the canonical filenames at the root of a session’s raw_data directory that are written exclusively by the Mesoscope-VR acquisition system.

MESOSCOPE_POSITIONS = 'mesoscope_positions.yaml'

The Mesoscope objective position snapshot written at session start by the Mesoscope-VR acquisition runtime.

WINDOW_SCREENSHOT = 'window_screenshot.png'

The cranial imaging window screenshot captured at session start by the Mesoscope-VR acquisition runtime.

ZABER_POSITIONS = 'zaber_positions.yaml'

The Zaber motor position snapshot written at session start by the Mesoscope-VR acquisition runtime.

class sollertia_shared_assets.mesoscope_vr.MesoscopeWaterRewardTrial(reward_size_ul=5.0, reward_tone_duration_ms=300)

Bases: object

Defines a Mesoscope-VR trial that delivers a water reward (a reinforcing stimulus) when the animal meets the trial’s success condition.

The reward is a configured volume of water accompanied by an auditory tone. The behavioral condition that earns the reward is defined by the task, not by this class.

reward_size_ul: float

The volume of water, in microliters, to deliver when the animal successfully completes the trial.

reward_tone_duration_ms: int

The duration, in milliseconds, to sound the auditory tone when delivering the water reward.

class sollertia_shared_assets.mesoscope_vr.RunTrainingDescriptor(experimenter, animal_weight_g, final_run_speed_threshold_cm_s=1.5, final_run_duration_threshold_s=1.5, initial_run_speed_threshold_cm_s=0.8, initial_run_duration_threshold_s=1.5, increase_threshold_ml=0.1, run_speed_increase_step_cm_s=0.05, run_duration_increase_step_s=0.1, maximum_water_volume_ml=1.0, maximum_training_time_min=40, maximum_unconsumed_rewards=1, maximum_idle_time_s=0.3, water_reward_size_ul=5.0, reward_tone_duration_ms=300, dispensed_water_volume_ml=0.0, pause_dispensed_water_volume_ml=0.0, experimenter_given_water_volume_ml=0.0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the task and outcome information specific to run training sessions that use the Mesoscope-VR system.

animal_weight_g: float

The weight of the animal, in grams, at the beginning of the session.

dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during runtime. This excludes the water volume dispensed during the paused (idle) state.

experimenter: str

The ID of the experimenter running the session.

experimenter_given_water_volume_ml: float = 0.0

The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.

experimenter_notes: str = 'Replace this with your notes.'

Stores the experimenter’s notes made during runtime.

final_run_duration_threshold_s: float = 1.5

The running duration threshold, in seconds, at the end of training.

final_run_speed_threshold_cm_s: float = 1.5

The running speed threshold, in centimeters per second, at the end of training.

incomplete: bool = True

Tracks whether the session’s data is complete and eligible for unsupervised data processing.

increase_threshold_ml: float = 0.1

The threshold volume of water delivered to the animal, in milliliters, that triggers the increase in the running speed and duration thresholds.

initial_run_duration_threshold_s: float = 1.5

The initial running duration threshold, in seconds.

initial_run_speed_threshold_cm_s: float = 0.8

The initial running speed threshold, in centimeters per second.

maximum_idle_time_s: float = 0.3

The maximum time, in seconds, the animal can dip below the running speed threshold to still receive the reward. This allows animals that ‘run’ by taking a series of large steps, briefly dipping below speed threshold at the end of each step, to still get water rewards.

maximum_training_time_min: int = 40

The maximum time, in minutes, the system is allowed to run the training.

maximum_unconsumed_rewards: int = 1

The maximum number of consecutive rewards that can be delivered without the animal consuming them. If the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal consumes the delivered rewards.

maximum_water_volume_ml: float = 1.0

The maximum volume of water the system is allowed to dispense during training.

pause_dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during the paused (idle) state.

reward_tone_duration_ms: int = 300

The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards.

run_duration_increase_step_s: float = 0.1

The value, in seconds, used by the system to increment the duration threshold each time the animal receives ‘increase_threshold_ml’ volume of water.

run_speed_increase_step_cm_s: float = 0.05

The value, in centimeters per second, used by the system to increment the running speed threshold each time the animal receives ‘increase_threshold_ml’ volume of water.

water_reward_size_ul: float = 5.0

The volume of water, in microliters, dispensed to the animal when it achieves the required running speed and duration thresholds.

class sollertia_shared_assets.mesoscope_vr.WindowCheckingDescriptor(experimenter, surgery_quality=0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the outcome information specific to window checking sessions that use the Mesoscope-VR system.

experimenter: str

The ID of the experimenter running the session.

experimenter_notes: str = 'Replace this with your notes.'

Stores the experimenter’s notes made during runtime.

incomplete: bool = True

Tracks whether the session’s data is complete and eligible for unsupervised data processing.

surgery_quality: int = 0

The quality of the cranial window and surgical intervention on a scale from 0 (non-usable) to 3 (high-tier publication grade) inclusive.

Dispatch Registries

Collects every sollertia-shared-assets dispatch registry in one place and runs the import-time checks that guard them.

This module is the single canonical surface for wiring new capabilities into the library, and it holds two governance tiers. The system registries — descriptor, hardware state, experiment configuration, system raw data, the system/session-type association, and the corridor-task gate — form the designed extension point. They grow whenever a new acquisition system or session type is added, following the recipe owned by the /library-extension skill. The contract registries — read assets and credentials — are durable translation contracts curated by Sollertia platform maintainers; adding an entry there is a platform-contract decision, not a routine extension.

The module imports each acquisition system’s subpackage (mesoscope_vr and its future siblings) and wires the system’s classes into the registries, so the shared configuration and data modules never import from a system subpackage. The keying enumerations live in the leaf enums module, which keeps this module importable by every registry consumer without circular imports.

sollertia_shared_assets.registries.CREDENTIALS_FILE_REGISTRY: dict[CredentialsTypes, str] = {CredentialsTypes.GOOGLE: 'google_credentials.json'}

Maps each credentials category to the canonical filename under which its credentials file is stored inside the working directory’s credentials subdirectory. This contract registry is curated by Sollertia platform maintainers; the credentials toolset that consumes it lives in the top-level credentials module.

sollertia_shared_assets.registries.DESCRIPTOR_REGISTRY: dict[SessionTypes, type[YamlConfig]] = {SessionTypes.LICK_TRAINING: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.LickTrainingDescriptor'>, SessionTypes.MESOSCOPE_EXPERIMENT: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.MesoscopeExperimentDescriptor'>, SessionTypes.RUN_TRAINING: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.RunTrainingDescriptor'>, SessionTypes.WINDOW_CHECKING: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.WindowCheckingDescriptor'>}

Maps each session type to its descriptor dataclass. The canonical on-disk filename is always the flat session_descriptor.yaml (RawDataFiles.SESSION_DESCRIPTOR) regardless of session type — the only thing that varies per type is the parsing class. The registry is deliberately flat: a session type maps to exactly one descriptor platform-wide, so an acquisition system that needs a different descriptor must mint a new SessionTypes member.

sollertia_shared_assets.registries.EXPERIMENT_CONFIGURATION_REGISTRY: dict[AcquisitionSystems, type[YamlConfig]] = {AcquisitionSystems.MESOSCOPE_VR: <class 'sollertia_shared_assets.mesoscope_vr.experiment_configuration.MesoscopeExperimentConfiguration'>}

Maps each acquisition system to its experiment configuration dataclass. Every registered class satisfies the experiment-configuration contract; the configuration and template-creation tools dispatch through this registry.

sollertia_shared_assets.registries.HARDWARE_STATE_REGISTRY: dict[AcquisitionSystems, type[YamlConfig]] = {AcquisitionSystems.MESOSCOPE_VR: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.MesoscopeHardwareState'>}

Maps each acquisition system to its hardware-state dataclass. The canonical on-disk filename is always hardware_state.yaml (RawDataFiles.HARDWARE_STATE) regardless of system — only the parsing class varies.

sollertia_shared_assets.registries.READ_ASSET_REGISTRY: dict[ReadAssets, type[YamlConfig]] = {ReadAssets.SURGERY_DATA: <class 'sollertia_shared_assets.data_classes.surgery_data.SurgeryData'>}

Maps each read-asset format to the dataclass that represents it on disk. This contract registry is curated by Sollertia platform maintainers; each entry is a durable contract for translating an external data shape into the uniform on-disk format the downstream Sollertia libraries consume.

sollertia_shared_assets.registries.SESSION_TYPES_USING_VR_TASK: frozenset[SessionTypes] = frozenset({SessionTypes.MESOSCOPE_EXPERIMENT})

The session types that run the linear infinite corridor task and therefore write a vr_configuration.yaml task-template snapshot. SessionData.required_raw_assets consults this set to decide whether a session of a given type requires the snapshot. Training and window-checking sessions run no task and are absent here.

sollertia_shared_assets.registries.SYSTEM_RAW_DATA_REGISTRY: dict[AcquisitionSystems, type[_SystemRawDataBuilder]] = {AcquisitionSystems.MESOSCOPE_VR: <class 'sollertia_shared_assets.mesoscope_vr.raw_data.MesoscopeRawData'>}

Maps each acquisition system to the dataclass that captures its system-specific raw assets. The registered class exposes a build(root: Path) -> Self classmethod that resolves all system-specific paths under the session’s raw_data directory.

sollertia_shared_assets.registries.SYSTEM_SESSION_TYPES: dict[AcquisitionSystems, frozenset[SessionTypes]] = {AcquisitionSystems.MESOSCOPE_VR: frozenset({SessionTypes.LICK_TRAINING, SessionTypes.MESOSCOPE_EXPERIMENT, SessionTypes.RUN_TRAINING, SessionTypes.WINDOW_CHECKING})}

Maps each acquisition system to the set of session types it can run. SessionData.create() rejects a session type that is not paired with the session’s acquisition system.

sollertia_shared_assets.registries.resolve_read_asset(read_asset)

Resolves a read-asset format identifier to the dataclass that represents it on disk.

Parameters:

read_asset (str | ReadAssets) – A ReadAssets member or its string value (e.g., "surgery_data").

Return type:

type[YamlConfig]

Returns:

The dataclass registered for the format in READ_ASSET_REGISTRY.

Raises:

ValueError – If the identifier is not a valid ReadAssets member.

Credentials Toolset

Provides the credentials toolset that copies per-category credentials files into the working directory’s credentials subdirectory and resolves them back for downstream consumers.

This toolset lives in its own top-level module, rather than next to the other persistent host settings in configuration/configuration_utilities.py, because its functions are the runtime consumers of CREDENTIALS_FILE_REGISTRY. Keeping the consumers downstream of the registries module preserves the library-wide rule that every dispatch registry is defined in registries while keeping the import graph acyclic: this module imports the registry, and the registry module never imports this one. The CREDENTIALS_DIRECTORY constant remains part of the working-directory layout owned by the configuration package (set_working_directory pre-creates the subdirectory) and is imported from there.

sollertia_shared_assets.credentials.get_credentials(credentials)

Resolves and returns the path to the requested credentials file stored in the working directory’s credentials subdirectory.

Parameters:

credentials (str | CredentialsTypes) – The CredentialsTypes member or its string value identifying the credentials category to resolve.

Return type:

Path

Returns:

The path to the requested credentials file.

Raises:

• ValueError – If the credentials category is not a valid CredentialsTypes member.

• FileNotFoundError – If the local working directory has not been configured for the host-machine, or if the credentials file for the requested category has not been set.

sollertia_shared_assets.credentials.resolve_credentials_file(credentials)

Resolves a credentials category identifier to the canonical filename of its credentials file.

Parameters:

credentials (str | CredentialsTypes) – A CredentialsTypes member or its string value (e.g., "google").

Return type:

str

Returns:

The canonical filename registered for the category in CREDENTIALS_FILE_REGISTRY.

Raises:

ValueError – If the identifier is not a valid CredentialsTypes member.

sollertia_shared_assets.credentials.set_credentials(credentials, path)

Copies the specified credentials file into the working directory’s credentials subdirectory.

The copy is stored under the canonical filename registered for the credentials category, replacing any previously configured credentials file for that category.

Notes

The configured credentials file is used for all future interactions with the corresponding external service carried out from this machine.

Parameters:

• credentials (str | CredentialsTypes) – The CredentialsTypes member or its string value identifying the credentials category to configure.

• path (Path) – The path to the credentials file to copy into the credentials’ subdirectory.

Raises:

• ValueError – If the credentials category is not a valid CredentialsTypes member, or if the specified file’s extension does not match the canonical credentials filename’s extension.

• FileNotFoundError – If the specified credentials file does not exist at the provided path, or if the local working directory has not been configured for the host-machine.

Return type:

None

Command Line Interfaces

slsa

Provides the entry point for all interactive sollertia-shared-assets library components.

Usage

slsa [OPTIONS] COMMAND [ARGS]...

configure

Configures major components of the Sollertia platform data workflow.

Usage

slsa configure [OPTIONS] COMMAND [ARGS]...

credentials

Copies the input credentials file into the platform credentials directory under its canonical name.

Usage

slsa configure credentials [OPTIONS]

Options

-c, --category <category>

Required The category of the credentials file to configure.

Options:

google

-f, --file <file>

Required The absolute path to the credentials file to copy into the platform credentials directory.

data-root

Sets the input directory as the local Sollertia platform data root.

Usage

slsa configure data-root [OPTIONS]

Options

-d, --directory <directory>

Required The absolute path to the directory under which all project directories are stored on this machine.

directory

Sets the input directory as the local Sollertia platform working directory.

Usage

slsa configure directory [OPTIONS]

Options

-d, --directory <directory>

Required The absolute path to the directory where to cache Sollertia platform configuration and local runtime data.

project

Creates the data structure for a new project under the configured Sollertia platform data root.

Usage

slsa configure project [OPTIONS]

Options

-p, --project <project>

Required The name of the project to be created.

templates

Sets the path to the sollertia-unity-tasks task templates directory.

Usage

slsa configure templates [OPTIONS]

Options

-d, --directory <directory>

Required The absolute path to the sollertia-unity-tasks project’s Configurations (Template) directory.

get

Reports the configured paths and the composition of the local Sollertia platform data hierarchy.

Usage

slsa get [OPTIONS] COMMAND [ARGS]...

credentials

Reports the path to the requested credentials file stored in the platform credentials directory.

Usage

slsa get credentials [OPTIONS]

Options

-c, --category <category>

Required The category of the credentials file to report.

Options:

google

data-root

Reports the configured local Sollertia platform data root.

Usage

slsa get data-root [OPTIONS]

directory

Reports the configured local Sollertia platform working directory.

Usage

slsa get directory [OPTIONS]

experiments

Lists the experiment configurations available for the target project.

Usage

slsa get experiments [OPTIONS]

Options

-p, --project <project>

Required The name of the project for which to list the available experiment configurations.

projects

Lists the projects stored under the local Sollertia platform data root.

Usage

slsa get projects [OPTIONS]

templates

Reports the configured sollertia-unity-tasks task templates directory.

Usage

slsa get templates [OPTIONS]

mcp

Starts the MCP server for agentic configuration management.

Usage

slsa mcp [OPTIONS]

Options

-t, --transport <transport>

The MCP transport type to use.

Default:

'stdio'

Options:

stdio | sse | streamable-http