PyBehaviorLog is an ASGI-first behavioral observation platform built with Django 6.0.5. It is designed for research teams who need video-assisted coding, live observations, structured ethograms, review workflows, and exportable analytics without being locked into a desktop-only workflow.
This version extends the earlier CowLog/BORIS-inspired foundations with:
- projects, role-based memberships, videos, and observation sessions
- point and state behaviors with keyboard bindings
- modifiers, subjects, subject groups, and independent variables
- synchronized videos and live observation sessions
- annotations, review states, and audit trail entries
- JSON, CSV, TSV, XLSX, BORIS-compatible project/session exports, and reproducibility bundles
- CowLog-compatible plain-text coding result import/export
- broader BORIS project import support for list- and mapping-based payload shapes
- BORIS-inspired behavioral sequence, TextGrid, binary-table, and compatibility-report exports
- an inline event editor in the session player with timeline-linked selection and quick nudging tools
- a one-click helper to close unpaired state events during review
- project-level analytics, transition summaries, and subject-based statistics
- multilingual interface support limited to English, Arabic, Chinese, Spanish, French, and Russian
- ASGI deployment with Granian
- PostgreSQL 18 + Redis 8 container stack
- Argon2 password hashing
- database-backed sessions
- Django CSP middleware support
- unit tests, coverage gate, pre-commit, and GitHub Actions CI
- built-in BORIS/CowLog round-trip certification fixtures and comparison helpers
- BORIS-style CSV/TSV/XLSX session imports
- media diagnostics with relative media paths and lightweight waveform/spectrogram previews for compatible audio files
- HTML and SQL session exports for downstream review pipelines
- player-side review note autosave and event-editor undo/redo history
- server-side undo/redo backed by database sessions for create/update/delete event operations
- more faithful BORIS-style tabular imports with start/stop intervals, annotation rows, and broader header aliases
- deeper image-sequence diagnostics for picture-based observations and relative-path exports
- Python 3.13+
- Django 6.0.5
- Granian (ASGI server)
- PostgreSQL 18
- Redis 8
- psycopg 3 with connection pooling
- openpyxl for spreadsheet exports
- argon2-cffi for password hashing
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
granian --interface asgi --host 127.0.0.1 --port 8000 config.asgi:applicationFor ASGI-parity in local development, use Granian (instead of the Django dev server) as shown above.
cp .env.example .env
docker compose up --buildThe default Docker stack starts:
web: Django on Granian / ASGIdb: PostgreSQL 18redis: Redis 8
pip install -r requirements-dev.txt
pre-commit install
python manage.py test
coverage run manage.py test
coverage report --fail-under=80PyBehaviorLog exposes a focused LANGUAGES list in the interface selector limited to the project languages requested for deployment: English, Arabic, Chinese, Spanish, French, and Russian.
The application uses Django's i18n infrastructure (LocaleMiddleware, the set_language endpoint, locale paths, and translatable templates) so translations can continue to evolve without changing the architecture.
The repository includes:
.pre-commit-config.yaml.github/workflows/ci.yml- coverage configuration with an 80% gate on the
trackerapp - a trimmed dependency set limited to the packages actually used by the project
Additional English documentation is available in:
docs/architecture.mddocs/deployment.mddocs/compatibility.mddocs/certification.mddocs/compatibility_matrix.mddocs/dealhost.md
This repository is marked as AGPL-3.0-only.