Metadata-Version: 2.3
Name: mxbiflow
Version: 0.3.12
Summary: mxbiflow is a toolkit based on pygame and pymxbi
Author: HuYang
Author-email: HuYang <huyangcommit@gmail.com>
Requires-Dist: gpiozero>=2.0.1
Requires-Dist: inflection>=0.5.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: keyring>=25.6.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: matplotlib>=3.10.6
Requires-Dist: mss>=10.1.0
Requires-Dist: numpy>=2.3.3
Requires-Dist: pandas>=2.3.2
Requires-Dist: pillow>=11.3.0
Requires-Dist: pyaudio>=0.2.14
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pygame-ce>=2.5.6
Requires-Dist: pymotego>=0.1.3
Requires-Dist: pymxbi>=0.3.5
Requires-Dist: pyserial>=3.5
Requires-Dist: pyside6>=6.10.1
Requires-Dist: qtawesome>=1.4.1
Requires-Dist: rich>=14.1.0
Requires-Dist: typer>=0.20.0
Requires-Dist: varname>=0.15.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# mxbiflow

A framework for building multi-animal, multi-stage behavioral neuroscience experiments with touchscreen interfaces.

## Overview

mxbiflow provides the core infrastructure for cognitive and behavioral experiment scheduling. It handles the experiment lifecycle — from configuration wizards and session management to real-time scene rendering and data logging — so you can focus on designing your experiment logic.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                       mxbiflow                          │
│                                                         │
│  Wizard (PySide6)          Game Loop (pygame-ce)        │
│  ┌────────────────┐         ┌───────────────────┐       │
│  │ MXBIPanel      │         │ SceneManager      │       │
│  │ ExperimentPanel│ ──────▶ │   ├─ Scene A      │       │
│  └────────────────┘         │   ├─ Scene B      │       │
│                             │   └─ ...          │       │
│                             │                   │       │
│                             │ Scheduler         │       │
│                             │ DetectorBridge    │       │
│                             └───────────────────┘       │
│                                                         │
│  ConfigStore ◄──── JSON config files                    │
│  DataLogger  ────► session data output                  │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌───────────────────┐
│     pymxbi        │
│  RFID / Rewarder  │
│  Detector / Audio │
└───────────────────┘
```

## Usage

Implement your experiment as a set of scenes, register them, and launch:

```python
from mxbiflow import set_base_path
from mxbiflow.scene import SceneManager
from mxbiflow.wizard import config_wizard, init_gameloop

scene_manager = SceneManager()
scene_manager.register([IDLE, Detect, Discriminate])

config_wizard(scene_manager)
game = init_gameloop(scene_manager)
game.play()
```

Each scene implements `SceneProtocol`:

```python
class MyScene:
    _running: bool
    level_table: dict[str, list[int]] = {"default": [1, 2, 3]}

    def start(self) -> None: ...
    def quit(self) -> None: ...
    @property
    def running(self) -> bool: ...
    def handle_event(self, event: Event) -> None: ...
    def update(self, dt_s: float) -> None: ...
    def draw(self, screen: Surface) -> None: ...
```

## Installation

```shell
uv add mxbiflow
```

## Requirements

- Python 3.14+
- pygame-ce, PySide6, pymxbi
