Metadata-Version: 2.4
Name: pycontrol-core
Version: 3.0.0a1
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
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: 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: 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 on-disk data format and board wire protocol are kept compatible with
existing pyControl sessions. 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 `3.0.0a1` alpha, pin the prerelease:

```bash
uv add "pycontrol-core==3.0.0a1"
# or
pip install --pre "pycontrol-core==3.0.0a1"
```

To install the GUI workflow, add `pycontrol-gui` instead; it depends on
`pycontrol-core`. 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 TSV and analog `.npy` files. |

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

## Run A Task

```bash
pycontrol run --setup BoxA --task blinker --hwdef example \
  --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 `--hwdef`.

The run command connects to the board, checks firmware status, uploads the
hardware definition and task, starts the framework, and writes data 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 TsvLogger
from pycontrol.extension import TaskExtension
from pycontrol.workspace import Workspace
```

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/md-viewer.html?doc=ARCHITECTURE-TOUR.md) - learn the system end to end.
- [Why the rewrite](../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md) - what changed versus pyControl v2 and why.

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)
- [Deleted surface](DELETED.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)
- [Experiment extensions](docs/experiment-extensions.md)
- [Extension settings](docs/extension-settings.md)
- [Integrations](docs/integrations.md)
- [Task sharing archives](docs/sharing.md)

Project process:

- [Testing guide](docs/testing.md)
- [Changelog](docs/changelog.md)
- [Current code review backlog](docs/code-review.md)

## Contributing

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