Metadata-Version: 2.4
Name: pycontrol-core
Version: 3.0.0a13
Summary: Sans-IO host library for the pyControl behavioural-experiment framework.
Project-URL: Homepage, https://github.com/karpova-lab/pycontrol-core
Author: pyControl contributors
License: GPL-3.0-or-later
License-File: LICENSE.txt
Keywords: behaviour,micropython,neuroscience,pyboard,pycontrol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.6
Requires-Dist: pyserial>=3.5
Provides-Extra: analysis
Requires-Dist: pandas>=3.0.3; extra == 'analysis'
Provides-Extra: integrations
Requires-Dist: boto3>=1.43.22; extra == 'integrations'
Requires-Dist: notion-client>=3.1.0; extra == 'integrations'
Requires-Dist: slack-sdk<4,>=3.27; extra == 'integrations'
Provides-Extra: lint
Requires-Dist: mypy>=1.10; extra == 'lint'
Requires-Dist: ruff>=0.5; extra == 'lint'
Requires-Dist: types-pyserial>=3.5; extra == 'lint'
Provides-Extra: notion
Requires-Dist: notion-client>=3.1.0; extra == 'notion'
Provides-Extra: s3
Requires-Dist: boto3>=1.43.22; extra == 's3'
Provides-Extra: slack
Requires-Dist: slack-sdk<4,>=3.27; extra == 'slack'
Provides-Extra: test
Requires-Dist: hypothesis>=6.100; extra == 'test'
Requires-Dist: pandas>=3.0.3; extra == 'test'
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# pycontrol-core

`pycontrol-core` is the host engine for pyControl. It handles board
communication, the wire protocol, workspace configuration, data logging, task
and experiment extensions, firmware sync, and the `pycontrol` command-line
tool.

The package is designed so GUI and script frontends share the same tested core:

```text
Pyboard <-> Transport <-> protocol codec <-> BoardSession <-> event bus <-> subscribers
```

The board wire protocol remains compatible with existing pyControl tasks. The
host writes one canonical `.pycontrol.zip` run bundle per recording. The
analysis importer reads both historical TSVs and native bundles and can return
the familiar legacy dataframe columns; manual TSV/NPY export remains available
only for external tools that require loose files. See
[wire-protocol.md](docs/wire-protocol.md) and
[data-format.md](docs/data-format.md) for the frozen specs.

## Install From PyPI Alpha

For the current alpha, allow prereleases:

```bash
uv add pycontrol-core --prerelease allow
# or
pip install --pre pycontrol-core
```

For the GUI workflow, install the app once globally with
`pycontrol-manager app install`, verify it with
`pycontrol-manager app status`, then launch it with `pycontrol gui`.
See [getting-started.md](docs/getting-started.md).

## Install For Development

From this package:

```bash
pip install -e ".[test,lint]"
```

With `uv`:

```bash
uv sync --extra test --extra lint
```

Run checks:

```bash
uv run pytest
uv run ruff check src tests
uv run mypy
```

## Create A Workspace

Most lab-authored files live in a workspace, not inside this package.

```bash
pycontrol workspace init my-workspace
cd my-workspace
pycontrol setups add BoxA --port /dev/cu.usbmodemXXXX
```

The workspace contains:

| Path | Purpose |
| --- | --- |
| `tasks/` | Task files uploaded to the board. |
| `hardware_definitions/` | Rig wiring files uploaded as `hardware_definition.py`. |
| `devices/` | Workspace device classes uploaded when referenced. |
| `plugins/task_extensions/` | Host-side task automation. |
| `plugins/experiment_extensions/` | Whole-experiment automation. |
| `plugins/task_plotters/` | Optional GUI plotters. |
| `plugins/task_controls/` | Optional GUI control panels. |
| `experiments/*.json` | Multi-subject experiment definitions. |
| `settings.json` / `setups.json` | Workspace settings and setup registry. |
| `data/` | Default output folder for native `.pycontrol.zip` run bundles. |

For a full walkthrough, use [getting-started.md](docs/getting-started.md).

## Run A Task

```bash
pycontrol run --setup BoxA --task examples/blinker \
  --subject mouse42 --duration 10
```

`--setup` looks up the serial port and setup variables from `setups.json`.
`--task` and `--hwdef` are resolved against the workspace by stem or by path.
Tasks that import `hardware_definition` need an explicit `--hwdef` or a setup
default hardware definition.

The run command connects to the board, checks firmware status, uploads the
hardware definition when the task needs one, uploads the task, starts the
framework, and writes a `.pycontrol.zip` run bundle under the workspace data
directory.

## Run An Experiment

```bash
pycontrol experiment blink_demo --duration 10
```

Experiment identity comes from the JSON file path under `experiments/`. For
example, `experiments/training/day1.json` is experiment `training/day1`.

Experiment JSON supports a first-class optional `hardware_definition` field.
When present, it overrides each setup's default hardware definition for that
experiment; when omitted, the setup default is used.

## Firmware And Board Checks

`BoardSession.connect()` performs a read-only firmware status check. It never
syncs files automatically.

```bash
pycontrol firmware status --setup BoxA
pycontrol firmware sync --setup BoxA
pycontrol board info --setup BoxA --json
```

Setups can pin an expected MCU so the host refuses the wrong board:

```bash
pycontrol setups add BoxH7 --port /dev/cu.usbmodemYYYY --mcu stm32h743
pycontrol setups detect BoxH7
```

See [troubleshooting.md](docs/troubleshooting.md) for operator triage.

## Public Imports

`pycontrol.__init__` exports only `__version__`. Import from explicit modules:

```python
from pycontrol.session import BoardSession
from pycontrol.recording import NativeEventLogger
from pycontrol.extension import TaskExtension
from pycontrol.workspace import Workspace
from pycontrol.analysis.data_import import session_dataframe
```

Install pandas dataframe helpers into the global app with
`pycontrol-manager app extras add analysis`, or install
`pycontrol-core[analysis]` in a pip-managed environment. Rig-control,
recording, bundles, and the CLI do not require pandas.

See [public-api.md](docs/public-api.md) for the supported import surface.

## Documentation

New to the project? Start with the repo-level guides:

- [Documentation index](../rewrite-docs/README.md) - map of everything, with a reading order.
- [Architecture tour](../rewrite-docs/ARCHITECTURE-TOUR.md) - learn the system end to end.
- [Data-flow walkthrough](../rewrite-docs/OVERVIEW.html#data-flow) - one packet's journey through the pipeline.

Orientation and operation:

- [Getting started](docs/getting-started.md)
- [Writing tasks](docs/writing-tasks.md)
- [Hardware definitions](docs/hardware-definitions.md)
- [Architecture](docs/architecture.md)
- [CLI reference](docs/cli-reference.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Migration from pyControl v2](docs/migration-from-official.md)

Contracts and internals:

- [Public API](docs/public-api.md)
- [Contracts](docs/contracts.md)
- [Wire protocol](docs/wire-protocol.md)
- [Data format](docs/data-format.md)
- [Threading and state](docs/threading-and-state.md)
- [Subscriber API](docs/subscriber-api.md)

Extending pyControl:

- [Task extensions](docs/task-extensions.md) - includes integrations and optional extras.
- [Experiment extensions](docs/experiment-extensions.md)
- [Extension settings](docs/extension-settings.md)
- [Task sharing archives](docs/sharing.md)

Project process:

- [Testing guide](docs/testing.md)
- [Maintainability metrics](docs/maintainability.md)
- [Changelog](docs/changelog.md)

## Contributing

See the repository-level [CONTRIBUTING.md](../pycontrol-archive/CONTRIBUTING.md)
for editable installs, tests, contracts, firmware notes, and trusted plugin
guidance.
