sl-behavior

A Python library that provides tools for processing non-visual behavior data acquired in the Sun (NeuroAI) lab.

---

Detailed Description

This library extracts and processes data from .npz log archives generated by the sl-experiment library. It saves extracted data as uncompressed .feather files that are later integrated into unified project datasets using assets from the sl-forgery library.

The library supports two primary usage modes:

• Remote processing: Called via bindings in sl-forgery and run on remote compute servers for large-scale batch processing.
• Local processing: Called via CLI or MCP server for processing individual sessions or smaller batches on local machines.

---

Table of Contents

• Dependencies
• Installation
• Usage
  • MCP Server
• API Documentation
• Developers
• Versioning
• Authors
• License
• Acknowledgments

---

Dependencies

For users, all library dependencies are installed automatically by all supported installation methods (see the Installation section).

Note! Developers should 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 python -m pip install . to install the project. Alternatively, if using a distribution with precompiled binaries, use python -m pip install WHEEL_PATH, replacing 'WHEEL_PATH' with the path to the wheel file.

pip

Use the following command to install the library using pip: pip install sl-behavior.

---

Usage

Remote Processing

The library is primarily designed for use on remote compute servers via bindings in the sl-forgery library. Due to the centralized approach to data collection and processing in the lab, all experiment and training sessions require processing with this library.

CLI Processing

The library can process sessions locally using the sl-behavior process CLI command:

sl-behavior process --session-path /path/to/session --runtime --face-camera --body-camera --actor --sensor --encoder

Use sl-behavior process --help to see all available options.

MCP Server

This library provides an MCP server that exposes behavior data processing tools for AI agent integration. The server enables agents to discover sessions, start batch processing with automatic queuing, and monitor progress.

Starting the Server

Start the MCP server using the CLI:

sl-behavior mcp

Available Tools

Tool	Description
discover_sessions_tool	Finds processable sessions under a root directory
start_processing_tool	Starts batch processing for one or more sessions with automatic queuing
get_processing_status_tool	Returns status for all sessions being managed

The discover_sessions_tool automatically filters out non-processable session types and returns only sessions that contain behavior data (lick training, run training, and mesoscope experiment sessions).

Claude Desktop Configuration

Add the following to the Claude Desktop configuration file:

{
  "mcpServers": {
    "sl-behavior": {
      "command": "sl-behavior",
      "args": ["mcp"]
    }
  }
}

---

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 important information about Command-Line Interfaces (CLIs) exposed by this library as part of installation into a Python environment.

---

Developers

This section provides installation, dependency, and build-system instructions for project developers.

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 the three latest stable versions. It is recommended to use a tool like pyenv to install and manage the required versions.

Development Automation

This project comes with a fully configured set of automation pipelines implemented using tox. Check the tox.ini file for details about the available pipelines and their implementation. Alternatively, call tox list from the root directory of the project to see the list of available tasks.

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.

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 (.tox, .ruff_cache, .mypy_cache, etc.) manually or via a CLI command typically solves 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 GPL3 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.

---