sollertia-shared-assets 8.1.0

Provides data acquisition and processing assets shared between Sollertia platform libraries.

sollertia-shared-assets

Provides data acquisition and processing assets shared between Sollertia platform libraries.

---

Detailed Description

This library is part of the Sollertia AI-assisted scientific data acquisition and processing platform, built on the Ataraxis framework and developed in the Sun (NeuroAI) lab at Cornell University. It keeps the two main Sollertia libraries used for data acquisition (sollertia-experiment) and processing (sollertia-forgery) independent of each other by providing the shared assets both depend on.

The library stores dataclasses used to save data acquired with the Sollertia platform (sessions, subjects, hardware state) and configure data acquisition and processing runtimes. It also provides a CLI (slsa) for platform configuration and an MCP server with tools for agentic configuration management, session operations, and Unity Editor integration. A subset of the MCP tools relay commands to a running Unity Editor instance via the McpBridge plugin from sollertia-unity-tasks. This subset enables agents to generate task prefabs, manage scenes, and control Play Mode.

---

Table of Contents

• Dependencies
• Installation
• Usage
  • CLI Commands
  • MCP Server
• API Documentation
• Developers
  • Adding New Session Types
  • Adding New Acquisition Systems
• Versioning
• Authors
• License
• Acknowledgments

---

Dependencies

• Python 3.14 (the only currently supported interpreter version).
• An optional Google service account credentials JSON file, required only when downstream Sollertia libraries fetch subject metadata or water-restriction logs from Google Sheets.
• An optional running Unity Editor instance with the McpBridge plugin from sollertia-unity-tasks, required only by the MCP tools that generate task prefabs, manage scenes, and control Play Mode.

For users, all other library dependencies are installed automatically by all supported installation methods. For developers, see the Developers section for information on installing additional development dependencies.

---

Installation

Source

Note, installation from source is highly discouraged for anyone who is not an active project developer.

1. Download this repository to the local machine using the preferred method, such as git-cloning. Use one of the stable releases that include precompiled binary and source code distribution (sdist) wheels.
2. If the downloaded distribution is stored as a compressed archive, unpack it using the appropriate decompression tool.
3. cd to the root directory of the prepared project distribution.
4. Run pip install . to install the project and its dependencies.

pip

Use the following command to install the library and all of its dependencies via pip: pip install sollertia-shared-assets

---

Usage

Most library components are intended to be used via other Sollertia platform libraries. For details on using shared assets for data acquisition and preprocessing, see the sollertia-experiment library. For details on using shared assets for data processing and dataset formation, see the sollertia-forgery library.

Warning! End users should not use any component of this library directly or install this library into any Python environment. All assets from this library are intended to be used exclusively by developers working on other Sollertia platform libraries.

CLI Commands

This library provides the slsa CLI that exposes the following commands and command groups:

Command	Description
mcp	Starts the MCP server for agentic configuration management
get directory	Reports the configured local Sollertia platform working directory
get data-root	Reports the configured local Sollertia platform data root
get google	Reports the configured Google service account credentials file path
get templates	Reports the configured sollertia-unity-tasks task templates directory
get projects	Lists the projects stored under the data root
get experiments	Lists the experiment configurations available for a project
configure directory	Sets the local Sollertia platform working directory
configure data-root	Sets the local Sollertia platform data root
configure google	Sets the path to the Google service account credentials file
configure templates	Sets the path to the sollertia-unity-tasks task templates directory
configure project	Creates a project directory structure for data acquisition
configure experiment	Creates an experiment configuration from a task template

Use slsa --help, slsa get --help, slsa configure --help, or slsa COMMAND --help for detailed usage information.

MCP Server

This library provides an MCP server that exposes configuration management, session and dataset operations, and Unity Editor relay tools for AI agent integration. The server enables agents to query and configure shared Sollertia platform workflow components.

Starting the Server

Start the MCP server using the CLI:

slsa mcp

The server defaults to the stdio transport. Use the -t/--transport flag to select one of stdio, sse, or streamable-http.

Available Tools

Tool	Description
create_experiment_configuration_tool	Creates an experiment configuration from a task template using sensible defaults
create_task_tool	Builds a Unity task end-to-end from a template: task prefab plus matching scene in one call
delete_asset_tool	Deletes a non-scene Unity asset (cue prefabs, materials) within the InfiniteCorridorTask root
delete_task_tool	Removes a Unity task end-to-end: scene, scene companion, task prefab, and every segment prefab
describe_experiment_configuration_schema_tool	Returns the schema for the experiment configuration of a given acquisition system
describe_session_data_schema_tool	Returns the schema for the SessionData dataclass
describe_session_descriptor_schema_tool	Returns the schema for the descriptor associated with a given session type
describe_session_hardware_state_schema_tool	Returns the hardware-state schema for a given acquisition system
describe_surgery_data_schema_tool	Returns the schema for SurgeryData and its nested subclasses
describe_template_schema_tool	Returns the schema for TaskTemplate and nested Cue, TrialStructure, and VREnvironment
discover_experiments_tool	Discovers all experiment configuration YAML files under the data root
discover_templates_tool	Lists all task templates in the configured templates directory
enter_play_mode_tool	Enters Play Mode in the Unity Editor
exit_play_mode_tool	Exits Play Mode in the Unity Editor
filter_sessions_tool	Filters discovered session entries by date range and animal- or session-name criteria
get_data_root_overview_tool	Builds the project/animal/session hierarchy from SessionData and per-session lifecycle status
get_platform_environment_status_tool	Reports the status of the working directory, data root, templates directory, and Google creds
get_play_state_tool	Returns the current Unity Editor play state and active scene name
inspect_prefab_tool	Returns the full hierarchy, components, transforms, and collider details of a prefab
inspect_scene_tool	Returns the active scene's metadata, dirty flag, and recursive root GameObject hierarchy
inspect_sessions_tool	Produces a detailed health and inventory report for one or more sessions
list_assets_tool	Lists Unity assets of a given type within a search path
list_processing_trackers_tool	Enumerates the canonical ProcessingTracker filenames written by each pipeline
list_scenes_tool	Lists all Unity scene assets and identifies the currently active scene
list_supported_acquisition_systems_tool	Enumerates the acquisition systems supported by the Sollertia platform
list_supported_session_types_tool	Enumerates the session types supported by the Sollertia platform
list_supported_trial_types_tool	Enumerates the trial classes supported by experiment configurations
list_supported_trigger_types_tool	Enumerates the trigger type values supported by trial structures
open_scene_tool	Opens a Unity scene in the Editor with explicit unsaved-edits handling
read_data_root_tool	Returns the configured Sollertia platform data root path
read_experiment_configuration_tool	Loads an experiment configuration YAML (project source or per-session frozen snapshot)
read_google_credentials_tool	Returns the configured path to the Google service account credentials file
read_session_data_tool	Loads a session_data.yaml file via the SessionData schema
read_session_descriptor_tool	Loads a session descriptor YAML using the descriptor class for the given session type
read_session_hardware_state_tool	Loads a hardware-state YAML for a session using the class for the given acquisition system
read_surgery_data_tool	Loads the full SurgeryData payload from a session's raw_data/surgery_metadata.yaml snapshot
read_task_parameters_tool	Reads the Unity Editor's Task Parameters window state, options, and per-control visibility
read_task_templates_directory_tool	Returns the configured path to the task templates directory
read_template_tool	Loads a TaskTemplate YAML (live template or per-session frozen snapshot)
read_working_directory_tool	Returns the configured Sollertia platform working directory path
set_data_root_tool	Sets the local Sollertia platform data root
set_google_credentials_tool	Sets the path to the Google service account credentials file
set_task_templates_directory_tool	Sets the path to the task templates directory
set_working_directory_tool	Sets the local Sollertia platform working directory
validate_experiment_configuration_tool	Validates an experiment configuration YAML for a project
validate_template_tool	Validates a TaskTemplate (live or session snapshot) against its schema and constraints
write_experiment_configuration_tool	Creates or replaces an experiment configuration YAML for a project
write_session_data_tool	Creates or replaces a session_data.yaml file, validated against the SessionData schema
write_session_descriptor_tool	Creates or replaces a session descriptor YAML for a session
write_session_hardware_state_tool	Creates or replaces a session's hardware-state YAML using the acquisition-system dataclass
write_surgery_data_tool	Creates or replaces a session's surgery_metadata.yaml, validated against SurgeryData
write_task_parameters_tool	Writes a subset of the Unity Editor's Task Parameters fields atomically in one relay call
write_template_tool	Creates or replaces a live TaskTemplate YAML in the configured templates directory

Note, tools that interact with Unity (create_task_tool, delete_asset_tool, delete_task_tool, enter_play_mode_tool, exit_play_mode_tool, get_play_state_tool, inspect_prefab_tool, inspect_scene_tool, list_assets_tool, list_scenes_tool, open_scene_tool, read_task_parameters_tool, write_task_parameters_tool) require the Unity Editor to be running on the local machine with the McpBridge plugin from sollertia-unity-tasks active. These tools relay commands to the Editor via HTTP.

Client Registration

MCP server registration and Claude Code skill assets for this library are distributed through the sollertia marketplace as part of the assets plugin. Install the plugin from the marketplace to automatically register the MCP server with compatible clients and make all associated skills available.

---

API Documentation

See the API documentation for the detailed description of the methods and classes exposed by components of this library.

Note, the API documentation includes additional details about the slsa CLI commands and their parameters beyond what is covered in the CLI Commands section above.

---

Developers

This section provides installation, dependency, and build-system instructions for the developers that want to modify the source code of this library.

Installing the Project

Note, this installation method requires mamba version 2.3.2 or above. Currently, all Sun lab automation pipelines require that mamba is installed through the miniforge3 installer.

1. Download this repository to the local machine using the preferred method, such as git-cloning.
2. If the downloaded distribution is stored as a compressed archive, unpack it using the appropriate decompression tool.
3. cd to the root directory of the prepared project distribution.
4. Install the core Sun lab development dependencies into the base mamba environment via the mamba install tox uv tox-uv command.
5. Use the tox -e create command to create the project-specific development environment followed by tox -e install command to install the project into that environment as a library.

Additional Dependencies

In addition to installing the project and all user dependencies, install the following dependencies:

1. Python distributions, one for each version supported by the developed project. Currently, this library supports Python 3.14 only. It is recommended to use a tool like pyenv to install and manage the required versions.

Development Automation

This project uses tox for development automation. The following tox environments are available:

Environment	Description
lint	Runs ruff formatting, ruff linting, and mypy type checking
stubs	Generates py.typed marker and .pyi stub files
py314-test	Runs the test suite via pytest for Python 3.14
coverage	Aggregates test coverage into an HTML report
docs	Builds the API documentation via Sphinx
build	Builds sdist and wheel distributions
upload	Uploads distributions to PyPI via twine
install	Builds and installs the project into its mamba environment
uninstall	Uninstalls the project from its mamba environment
create	Creates the project's mamba development environment
remove	Removes the project's mamba development environment
provision	Recreates the mamba environment from scratch
export	Exports the mamba environment as .yml and spec.txt files
import	Creates or updates the mamba environment from a .yml file

Run any environment using tox -e ENVIRONMENT. For example, tox -e lint.

Note, all pull requests for this project have to successfully complete the tox task before being merged. To expedite the task's runtime, use the tox --parallel command to run some tasks in parallel.

Adding New Session Types

A session type identifies the high-level activity performed during acquisition (e.g., training, experiment, window-checking). Each type has its own descriptor dataclass that captures the type-specific task parameters and outcome metadata, persisted as session_descriptor.yaml inside the session's raw_data directory. The descriptor filename is flat across all types — only the parsing class varies, and is dispatched via DESCRIPTOR_REGISTRY.

Step 1: Extend the SessionTypes enum

In data_classes/session_data.py, add a new member to SessionTypes:

class SessionTypes(StrEnum):
    LICK_TRAINING = "lick training"
    RUN_TRAINING = "run training"
    MESOSCOPE_EXPERIMENT = "mesoscope experiment"
    WINDOW_CHECKING = "window checking"
    NEW_TYPE = "new type"  # Add new session type here

Step 2: Add the descriptor dataclass

In data_classes/runtime_data.py, add a <Type>Descriptor dataclass inheriting from YamlConfig that captures the task parameters and outcome metadata for the new session type. Use LickTrainingDescriptor or RunTrainingDescriptor as reference. Export the new class from data_classes/__init__.py.

Step 3: Register the descriptor

In interfaces/mcp_instance.py:

1. Import the new descriptor class.
2. Register it in DESCRIPTOR_REGISTRY under the new SessionTypes key.

Step 4: Update required-asset checks (if applicable)

If the new session type requires assets beyond the universal session_descriptor.yaml and system_configuration.yaml (for example, an experiment configuration), extend _required_asset_inventory in interfaces/data_tools.py to add the relevant if session_type == SessionTypes.NEW_TYPE branch.

Step 5: Update downstream libraries

Coordinate with sollertia-experiment, which is the package that actually creates sessions of the new type during acquisition.

Adding New Acquisition Systems

An acquisition system identifies a hardware platform that can produce a session (e.g., the Mesoscope-VR system). Each system contributes its own hardware-state snapshot, experiment-configuration schema, and a system-specific raw data dataclass that resolves the system's unique on-disk assets. Three registries dispatch parsing and builder classes by AcquisitionSystems value: HARDWARE_STATE_REGISTRY, EXPERIMENT_CONFIGURATION_REGISTRY, and SYSTEM_RAW_DATA_REGISTRY. A fourth registry, _experiment_config_factory_registry, dispatches TaskTemplate-to- configuration factories. System-level hardware and software configuration classes live in the acquisition runtime package (sollertia-experiment), not in this library.

Step 1: Extend the AcquisitionSystems enum

In configuration/configuration_utilities.py, add a new member to AcquisitionSystems:

class AcquisitionSystems(StrEnum):
    MESOSCOPE_VR = "mesoscope"
    NEW_SYSTEM = "new_system"  # Add new system here

Step 2: Add the hardware-state dataclass

In data_classes/runtime_data.py, add a <System>HardwareState dataclass inheriting from YamlConfig that records the configuration of every active hardware module on the new system. Use MesoscopeHardwareState as reference. Export the new class from data_classes/__init__.py.

Step 3: Add the experiment-configuration module

Create a new file (e.g., new_system_configuration.py) in configuration/ containing a <System>ExperimentConfiguration dataclass inheriting from YamlConfig that captures the runtime experiment parameters for the new system. Use MesoscopeExperimentConfiguration in mesoscope_configuration.py as reference. Export the new class from configuration/__init__.py.

Step 4: Add the system-specific raw-data dataclass

In data_classes/session_data.py:

1. (Optional) Add <System>RawDataFiles and/or <System>Directories StrEnum classes that enumerate any canonical filenames or subdirectories unique to the new system's raw_data. Use MesoscopeRawDataFiles / MesoscopeDirectories as reference.
2. Add a <System>RawData @dataclass(slots=True) that holds the absolute paths to all system-specific raw assets and exposes a build(cls, root: Path) -> <System>RawData classmethod that resolves every field against the session's raw_data directory. Use MesoscopeRawData as reference.
3. Export the new class(es) from data_classes/__init__.py.

Step 5: Register the dispatch classes

Three registries need entries for the new system:

1. In interfaces/mcp_instance.py, import <System>HardwareState and add it to HARDWARE_STATE_REGISTRY.
2. In configuration/configuration_utilities.py, import <System>ExperimentConfiguration and add it to EXPERIMENT_CONFIGURATION_REGISTRY. SessionData.create() consults this registry to load the per-session experiment configuration snapshot and (if the configuration declares a unity_scene_name) cache the matching VR task template. Acquisition systems that do not use Unity-based VR omit unity_scene_name from their schema, and the VR template export is skipped automatically.
3. In data_classes/session_data.py, add <System>RawData to SYSTEM_RAW_DATA_REGISTRY. SessionData consults this registry to build the runtime-only system_raw_data sub-dataclass attribute, so this step is what wires the new system into session loading.

Step 6: Add the TaskTemplate-to-configuration factory

In configuration/configuration_utilities.py:

1. Widen the ExperimentConfigFactory type alias's return type into a union that includes the new experiment configuration class (e.g., MesoscopeExperimentConfiguration | NewSystemExperimentConfiguration).
2. Implement a private factory function (e.g., _create_new_system_experiment_config) with the signature (unity_scene_name: str, trial_structures: dict[str, WaterRewardTrial | GasPuffTrial]) that returns the new experiment configuration dataclass. Use _create_mesoscope_experiment_config as reference.
3. Register the factory in _experiment_config_factory_registry under the new AcquisitionSystems key.

Step 7: Update downstream libraries

Coordinate with sollertia-experiment (which owns the system-level hardware/software configuration classes and the acquisition runtime) and sollertia-forgery (data processing) as needed.

AI-Assisted Development

Claude Code skills and AI development assets for this project are distributed through two marketplaces:

• sollertia marketplace:
  • assets plugin — registers the slsa mcp server with compatible MCP clients and provides configuration and data skills for working directory setup, session discovery, session data, descriptors, hardware state, subject metadata, task templates, experiment configuration, library extension, and MCP environment setup. The server also fronts the Unity Editor relay that the unity plugin's skills drive.
  • unity plugin — Unity Editor skills that drive the McpBridge relay tools served by the slsa mcp server, document the MQTT contract and CreateTask pipeline, and guide manufacturing of new trigger zone prefabs.
• ataraxis marketplace:
  • automation plugin — shared development skills that enforce Sun Lab coding conventions (Python style, README style, commit messages, pyproject.toml, tox configuration) and general-purpose codebase exploration tools.

Install all three plugins to make the full skill set available to compatible AI coding agents. The unity plugin depends on the assets plugin for the backing slsa mcp server that drives the Unity Editor relay.

Automation Troubleshooting

Many packages used in tox automation pipelines (uv, mypy, ruff) and tox itself may experience runtime failures. In most cases, this is related to their caching behavior. If an unintelligible error is encountered with any of the automation components, deleting the corresponding cache directories (.tox, .ruff_cache, .mypy_cache, etc.) manually or via a CLI command typically resolves the issue.

---

Versioning

This project uses semantic versioning. See the tags on this repository for the available project releases.

---

Authors

• Ivan Kondratyev (Inkaros)
• Kushaan Gupta (kushaangupta)
• Natalie Yeung

---

License

This project is licensed under the Apache 2.0 License: see the LICENSE file for details.

---

Acknowledgments

• All Sun lab members for providing the inspiration and comments during the development of this library.
• The creators of all other dependencies and projects listed in the pyproject.toml file.