Metadata-Version: 2.4
Name: nff-normalized-factor-flow
Version: 0.1.0
Summary: Python package scaffold for Normalized Factor Flow (NFF).
Author: Elxrth
Project-URL: Homepage, https://github.com/Elxrth/NFF-normalized-factor-flow
Project-URL: Repository, https://github.com/Elxrth/NFF-normalized-factor-flow
Project-URL: Issues, https://github.com/Elxrth/NFF-normalized-factor-flow/issues
Keywords: data-streams,signal-analysis,time-series,normalized-factor-flow
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: engine
Requires-Dist: torch>=2.0; extra == "engine"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: serial
Requires-Dist: pyserial>=3.5; extra == "serial"
Provides-Extra: all
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: matplotlib>=3.7; extra == "all"
Requires-Dist: pyserial>=3.5; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# NFF — Normalized Factor Flow

Python package migration scaffold for [Elxrth/NFF-normalized-factor-flow](https://github.com/Elxrth/NFF-normalized-factor-flow).

> **Important status:** this archive provides the packaging layout, installation metadata,
> tests, command-line entry point, and reusable data utilities. It does **not** contain the
> original `main.py` analysis implementation. The source file could not be retrieved while
> preparing this ZIP, so no NUA, normalization, signature, or ORDER formula has been recreated
> or guessed. Follow [`INTEGRATION.md`](INTEGRATION.md) to integrate the actual engine before
> publishing a functional NFF release to PyPI.

## Requirements

- Python 3.10 or newer
- NumPy 1.24 or newer
- PyTorch is an optional extra in this scaffold; install it when integrating/running the
  original PyTorch engine.

## Install for development

```bash
git clone https://github.com/Elxrth/NFF-normalized-factor-flow.git
cd NFF-normalized-factor-flow
python -m venv .venv
```

Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev,engine]"
```

Linux / macOS:

```bash
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev,engine]'
```

For a CUDA-enabled PyTorch build, install the build matching your CUDA/runtime from the
[official PyTorch install selector](https://pytorch.org/get-started/locally/) before installing
this project with `--no-deps`, or adjust the project extras to your supported CUDA index.

## Current utility API

```python
import nff
import numpy as np

flow = nff.Flow(np.sin(np.linspace(0, 10, 2_000)), name="sensor", sampling_rate=100)
containers = nff.create_containers(flow.data, size=256, stride=128)
normalized = nff.normalize(containers[0], method="zscore")

print(len(flow))
print(normalized[:5])
```

Available utilities:

| API | Purpose |
| --- | --- |
| `nff.Flow(data)` | Validated one-dimensional numeric flow |
| `nff.create_containers(data, size, stride=...)` | Split a stream into temporal windows |
| `nff.normalize(data, method=...)` | Generic z-score, min-max, or robust scaling |
| `nff.compare_signatures(a, b, metric=...)` | Generic cosine / Euclidean / Manhattan comparison |
| `nff.load_csv(path, column=0)` | Load a numeric CSV column |
| `nff.load_numpy(path)` | Load a `.npy` array |
| `nff.export_json(data, path)` | Export structured data to JSON |
| `nff.export_csv(data, path)` | Export a numeric vector to CSV |
| `nff.NFFEngine(...).analyze(flow)` | Reserved for the original NFF engine; pending integration |

The generic normalization and comparison helpers are convenience utilities. They are not claims
about the project's canonical NFF normalization or signature-comparison definitions.

## CLI

```bash
nff --version
nff info
nff doctor
```

## Tests

```bash
python -m pytest
```

## Build distributions

```bash
python -m pip install --upgrade build twine
python -m build
twine check dist/*
```

Do not upload this scaffold to PyPI as a finished NFF release until the original algorithm is
integrated, tests cover its documented outputs, and the license metadata has been verified.

## PyPI publication

1. Confirm that the distribution name `nff-normalized-factor-flow` is available on PyPI.
2. Integrate the original engine and complete the tests (see `INTEGRATION.md`).
3. Verify the real license and author metadata.
4. Build and validate the distributions with the commands above.
5. Test on TestPyPI, then publish with `twine upload dist/*` or configure PyPI Trusted Publishing.

Project source and theory: <https://github.com/Elxrth/NFF-normalized-factor-flow>
