Metadata-Version: 2.5
Name: pista-core
Version: 0.0.0
Summary: PISTA Core — cycling telemetry analysis engine: FIT ingestion, metrics, alignment.
Author-email: Alberto Scomparin <alberto.scomparin@live.com>
License: UNLICENSED
Keywords: analysis,cycling,fit,power,telemetry
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.0
Requires-Dist: fitdecode>=0.10
Requires-Dist: numpy>=2.0
Requires-Dist: polars>=1.0
Requires-Dist: pyarrow>=17.0
Requires-Dist: pydantic>=2.0
Requires-Dist: scipy>=1.14
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pyright>=1.1.380; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# PISTA Core

**P**erformance **I**nspection, **S**ignal & **T**elemetry **A**nalysis — the analysis engine.

PISTA Core is the engine behind **PISTA Studio**, a desktop telemetry analysis application for
cycling built on the motorsport analysis paradigm (WinTAX, Pi Toolbox, ATLAS) rather than the
sports-science paradigm of existing cycling tools.

Core is usable on its own: it ingests FIT files, computes a channel library, and aligns multiple
riders onto a common distance axis.

## Status

Pre-release. Phase 0 of the roadmap — no public API yet.

## What it does

| Module | Responsibility |
|---|---|
| `pista.ingest` | FIT parsing across head-unit vendors, normalization, Parquet writing |
| `pista.schema` | The canonical time-series schema and library manifest |
| `pista.metrics` | Channel library, power-duration curve, CP/W′, durability, decoupling |
| `pista.align` | Rider-to-rider alignment by road position rather than clock |
| `pista.synthetic` | Synthetic ride generator — the only data used in tests and examples |

## Design commitments

- **Immutable, append-only Parquet.** One file per activity, never modified after writing. A
  library is a folder, so write contention cannot occur and it works over any sync service.
- **No Qt dependency, ever.** Core is a library; the application lives in PISTA Studio.
- **Vectorized or SQL.** Python orchestrates and never iterates over samples.
- **Nulls are not zeros.** A sensor dropout is a different fact from a genuine zero.

## Development

Requires [uv](https://docs.astral.sh/uv/) and Python 3.12+.

```bash
uv sync --extra dev        # create the environment
uv run pytest              # tests
uv run ruff check .        # lint
uv run ruff format .       # format
uv run pyright             # type check
uv run pre-commit install  # install the gitleaks + lint hooks (once)
```

## Data

**No rider data lives in this repository**, not even anonymised. All tests and examples use the
synthetic generator. A local FIT corpus belongs outside the repository.

## Licence

Not yet licensed. PISTA Core will be published under an open licence (Apache-2.0 or AGPL-3.0)
before the repository is made public.

© Alberto Scomparin
