NeuroPose (rewrite)

Ground-up rewrite of the prior NeuroPose internal prototype.

Target layout

neuropose/
├── .github/workflows/           # CI on the GitHub mirror (ruff + pyright + pytest)
├── src/neuropose/
│   ├── __init__.py              # version only
│   ├── config.py                # pydantic-settings Settings class
│   ├── io.py                    # prediction schema, load/save helpers
│   ├── estimator.py             # per-video MeTRAbs worker (ported, cleaned)
│   ├── interfacer.py            # filesystem-polling daemon (ported, cleaned)
│   ├── cli.py                   # typer app (`neuropose run|watch|analyze`)
│   ├── _model.py                # MeTRAbs model load + local cache
│   └── analyzer/                # rewrite of the prior analyzer.py
│       ├── dtw.py               # FastDTW helpers
│       ├── features.py          # normalization, padding, joint angles
│       └── classification.py    # sktime classifier wrappers
├── tests/
│   ├── unit/                    # fast, no model download
│   ├── integration/             # marked @slow, downloads the model
│   └── fixtures/                # synthetic video + reference predictions
├── docs/                        # mkdocs-material site
├── notebooks/                   # getting_started.ipynb, tested in CI via nbval
├── config/default.yaml          # example runtime config
├── scripts/download_model.py
├── pyproject.toml               # hatchling build, typer + pydantic + TF stack
├── Dockerfile                   # CPU, pinned deps
├── AUTHORS.md
├── CITATION.cff
└── LICENSE                      # MIT

Architecture

Three stages, one module each:

• estimator — per-video worker. Extracts frames from an input video, runs MeTRAbs on each frame, and writes per-frame predictions (boxes, poses3d, poses2d) to JSON. No daemon logic; usable directly from Python.
• interfacer — filesystem-polling daemon. Watches the configured input directory for new job subdirectories, dispatches each to an Estimator, and persists job state (status.json) across crashes and restarts. Owns the input → output → failed directory lifecycle.
• analyzer — post-processing subpackage. FastDTW-based motion comparison, joint-angle feature extraction, and sktime classifier wrappers. Operates on the JSON output of the estimator.

Configuration is centralized in src/neuropose/config.py (a pydantic-settings Settings class). The runtime data directory defaults to $XDG_DATA_HOME/neuropose/jobs/ and never lives inside the repository.

Commit plan

#	Scope	State
1	Scaffolding: package layout, MIT license, authors, citation, policy-aware .gitignore	in review
2	Dev tooling: pre-commit, ruff, pyright, gitleaks	planned
3	CI workflow on the GitHub mirror	planned
4	config.py, io.py, unit tests	planned
5	Port estimator.py with typing and audit §6 fixes	planned
6	Port interfacer.py with audit §7 fixes	planned
7	Typer CLI (`neuropose run	watch
8	mkdocs-material docs site	planned
9	Data-handling policy (gates going public)	blocked on IRB prose
10	analyzer/ subpackage rewrite	planned
11	MeTRAbs model loader + integration smoke test	blocked on upstream URL + TF pin
12	Dockerfile	blocked on 11
13	Comprehensive CHANGELOG.md retroactive entry	blocked on 12