Metadata-Version: 2.4
Name: csiphon
Version: 0.1.0
Summary: An online-first, schema-validated CSI preprocessing pipeline library.
Author: Fabian Portner
License-Expression: MIT
Project-URL: Homepage, https://github.com/nzqo/csiphon
Project-URL: Repository, https://github.com/nzqo/csiphon
Project-URL: Issues, https://github.com/nzqo/csiphon/issues
Keywords: csi,wifi,channel-state-information,dsp,signal-processing,doppler,streaming
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1
Provides-Extra: sst
Requires-Dist: ssqueezepy>=0.6; extra == "sst"
Provides-Extra: filters
Requires-Dist: scipy>=1.11; extra == "filters"
Provides-Extra: all
Requires-Dist: csiphon[filters,sst]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: polars; extra == "dev"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: twine; extra == "release"
Dynamic: license-file

<p align="center">
  <img
    src="https://raw.githubusercontent.com/nzqo/csiphon/main/assets/ai_slop_mascot.png"
    alt="slop Kanna doing Wi-Fi plumbing"
    width="300"
  >
</p>

# csiphon

`csiphon` is an online-first processing library for WiFi Channel State
Information. Compose reusable DSP steps, compile them against your capture
setup, then pour a complete recording or stream live chunks through the same
validated pipeline.

```python
from csiphon import AcquisitionProfile, Pipeline
from csiphon.steps import GainNormalize, Magnitude, WindowedVariance

profile = AcquisitionProfile(
    n_rx_antennas=3,
    subcarrier_indices=tuple(range(52)),
    sampling_rate_hz=1000.0,
)

siphon = (
    Pipeline()
    .then(Magnitude())
    .then(GainNormalize())
    .then(WindowedVariance(win_size_s=0.1))
    .compile(profile)
)

features = siphon.pour(profile.raw_signal(csi, timestamps)).single()
```

## What it does

- **Catches structural mistakes before execution.** Compilation checks axes,
  shapes, value semantics, and physical representations before data starts
  flowing.
- **Runs the same recipe in batch or live.** Every step states whether its
  streaming computation matches batch, differs intentionally, or requires the
  complete recording.
- **Supports branching pipelines.** Split into parallel feature paths, merge
  them again, and expose named intermediate outlets.
- **Keeps real timestamps.** Non-uniform CSI sampling is expected; resampling is
  explicit rather than silently assumed.
- **Describes itself.** Steps and compiled siphons expose their contracts,
  layouts, parameters, and streaming behavior, and can save that information
  alongside results for reproducibility.

The built-in steps cover calibration, cleaning, filtering, delay and
time-frequency transforms, temporal features, pooling, statistics, reduction,
and restructuring. Custom steps use the same contracts and inspection tools.

## Install

```bash
pip install -e .
```

The core only depends on NumPy. Install every optional transform with:

```bash
pip install -e ".[all]"
```

Runnable recipes live in [`examples/`](examples/).
