Metadata-Version: 2.4
Name: sollertia-shared-assets
Version: 8.0.0
Summary: Provides data acquisition and processing assets shared between Sollertia platform libraries.
Project-URL: Homepage, https://github.com/Sun-Lab-NBB/sollertia-shared-assets
Project-URL: Documentation, https://sollertia-shared-assets-api-docs.netlify.app/
Author: Ivan Kondratyev, Kushaan Gupta, Natalie Yeung
Maintainer-email: Ivan Kondratyev <ik278@cornell.edu>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ataraxis,configuration,dataclasses,sollertia
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.14
Requires-Dist: ataraxis-base-utilities<7,>=6
Requires-Dist: ataraxis-data-structures<7,>=6
Requires-Dist: ataraxis-time<7,>=6
Requires-Dist: click<9,>=8
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<2,>=1
Requires-Dist: platformdirs<5,>=4
Requires-Dist: polars<2,>=1
Requires-Dist: python-dateutil<3,>=2
Requires-Dist: pyyaml<7,>=6
Requires-Dist: tzdata<2027,>=2024; sys_platform == 'win32'
Description-Content-Type: text/markdown

# sollertia-shared-assets

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

![PyPI - Version](https://img.shields.io/pypi/v/sollertia-shared-assets)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sollertia-shared-assets)
[![uv](https://tinyurl.com/uvbadge)](https://github.com/astral-sh/uv)
[![Ruff](https://tinyurl.com/ruffbadge)](https://github.com/astral-sh/ruff)
![type-checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square&logo=python)
![PyPI - License](https://img.shields.io/pypi/l/sollertia-shared-assets)
![PyPI - Status](https://img.shields.io/pypi/status/sollertia-shared-assets)
![PyPI - Wheel](https://img.shields.io/pypi/wheel/sollertia-shared-assets)

___

## Detailed Description

This library is part of the [Sollertia](https://github.com/Sun-Lab-NBB/sollertia) AI-assisted scientific data
acquisition and processing platform, built on the [Ataraxis](https://github.com/Sun-Lab-NBB/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](https://github.com/Sun-Lab-NBB/sollertia-experiment)) and processing
([sollertia-forgery](https://github.com/Sun-Lab-NBB/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](https://github.com/Sun-Lab-NBB/sollertia-unity-tasks). This subset enables agents to generate
task prefabs, manage scenes, and control Play Mode.

___

## Table of Contents

- [Dependencies](#dependencies)
- [Installation](#installation)
- [Usage](#usage)
  - [CLI Commands](#cli-commands)
  - [MCP Server](#mcp-server)
- [API Documentation](#api-documentation)
- [Developers](#developers)
  - [Adding New Session Types](#adding-new-session-types)
  - [Adding New Acquisition Systems](#adding-new-acquisition-systems)
- [Versioning](#versioning)
- [Authors](#authors)
- [License](#license)
- [Acknowledgments](#acknowledgments)

___

## Dependencies

- [Python](https://www.python.org/downloads/) **3.14** (the only currently supported interpreter version).
- An optional
  [Google service account credentials JSON file](https://cloud.google.com/iam/docs/service-account-overview),
  required only when downstream Sollertia libraries fetch subject metadata or water-restriction logs from Google Sheets.
- An optional running [Unity Editor](https://unity.com/download) instance with the McpBridge plugin from
  [sollertia-unity-tasks](https://github.com/Sun-Lab-NBB/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](#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](https://github.com/Sun-Lab-NBB/sollertia-shared-assets/tags)
   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](https://pip.pypa.io/en/stable/): `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](https://github.com/Sun-Lab-NBB/sollertia-experiment) library. For details on using shared assets
for data processing and dataset formation, see the
[sollertia-forgery](https://github.com/Sun-Lab-NBB/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           |
| `configure directory`   | Sets the local Sollertia platform working directory                  |
| `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 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:

```bash
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, templates directory, and Google credentials        |
| `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_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_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](https://github.com/Sun-Lab-NBB/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](https://github.com/Sun-Lab-NBB/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](https://sollertia-shared-assets-api-docs.netlify.app/) 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](#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](https://github.com/conda-forge/miniforge) 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](https://www.python.org/downloads/) 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](https://github.com/pyenv/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`:

```python
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`:

```python
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](https://github.com/Sun-Lab-NBB/sollertia) marketplace: Provides MCP server registration,
  configuration-specific skills for working directory management, system and experiment configuration, session data,
  subject metadata, dataset management, task templates, and MCP environment setup via the **assets** plugin.
  Install this plugin to register the `slsa mcp` server with compatible MCP clients and make all configuration
  workflow skills available.
- [ataraxis](https://github.com/Sun-Lab-NBB/ataraxis) marketplace: Provides 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 via the **automation** plugin.

Install both marketplace plugins to make all associated skills and development tools available to compatible AI coding
agents.

### 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](https://semver.org/). See the
[tags on this repository](https://github.com/Sun-Lab-NBB/sollertia-shared-assets/tags) for the available project
releases.

___

## Authors

- Ivan Kondratyev ([Inkaros](https://github.com/Inkaros))
- Kushaan Gupta ([kushaangupta](https://github.com/kushaangupta))
- Natalie Yeung

___

## License

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

___

## Acknowledgments

- All Sun lab [members](https://neuroai.github.io/sunlab/people) 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](pyproject.toml) file.