Metadata-Version: 2.5
Name: telespec
Version: 0.1.0
Summary: Explainable spectral analysis and anomaly detection for irregular network telemetry
Project-URL: Homepage, https://github.com/akshajbachu/telespec
Project-URL: Documentation, https://akshajbachu.github.io/telespec
Project-URL: Source, https://github.com/akshajbachu/telespec
Project-URL: Issues, https://github.com/akshajbachu/telespec/issues
Project-URL: Changelog, https://github.com/akshajbachu/telespec/blob/main/CHANGELOG.md
Author: Akshaj Bachu
Maintainer: Akshaj Bachu
License-Expression: MIT
License-File: LICENSE
Keywords: anomaly-detection,lomb-scargle,networking,spectral-analysis,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26
Requires-Dist: rich>=13.7
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.12
Requires-Dist: statsmodels>=0.14
Requires-Dist: typer>=0.12
Provides-Extra: data
Requires-Dist: requests>=2.32; extra == 'data'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: python-multipart>=0.0.12; extra == 'dev'
Requires-Dist: requests>=2.32; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: ui
Requires-Dist: fastapi>=0.115; extra == 'ui'
Requires-Dist: python-multipart>=0.0.12; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'ui'
Description-Content-Type: text/markdown

# telespec

[![CI](https://github.com/akshajbachu/telespec/actions/workflows/ci.yml/badge.svg)](https://github.com/akshajbachu/telespec/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/telespec)](https://pypi.org/project/telespec/)
[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)](https://www.python.org/)
[![Docs](https://img.shields.io/badge/docs-online-blue)](https://akshajbachu.github.io/telespec/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Explainable spectral analysis and anomaly detection for irregular network telemetry.

Unlike interpolate-then-FFT pipelines, telespec applies a floating-mean generalized
Lomb-Scargle periodogram directly to observed timestamps and calibrates significant
peaks using a permutation bootstrap. It turns latency, throughput, jitter, loss, or
request-count series into plain-language, evidence-backed findings.

## Install

```bash
pip install "telespec[ui]"
```

For development:

```bash
git clone https://github.com/akshajbachu/telespec.git
cd telespec
uv sync --extra dev
```

## Try it

```bash
telespec demo -o demo.csv
telespec analyze-file demo.csv --column latency
telespec view
```

The dashboard is private and local at `http://127.0.0.1:8765`.

![telespec dashboard showing local telemetry controls](docs/assets/dashboard.png)

## Python

```python
from telespec import analyze
from telespec.io import read_csv

telemetry = read_csv("metrics.csv", timestamp="timestamp", value="latency_ms")
result = analyze(telemetry, bootstrap_iterations=200)
for finding in result.findings:
    print(finding.summary)
```

## Reproducible validation

`uv run python benchmarks/run_all.py --quick` regenerates `benchmarks/results/results.json`
and every SVG under `benchmarks/results/`. The full run evaluates frequency recovery
under missing/jittered samples, false-alarm calibration, synthetic anomaly detection,
and selected expert-labeled NAB series. Metrics are generated from code; no numbers are
handwritten.

<!-- BENCHMARK_RESULTS_START -->
Latest `full` reproducible run:

- At 60% missing observations, median frequency error was 0.57% for GLS versus 1.27% for interpolate+FFT.
- Synthetic level shift F1: 0.644 (telespec), 0.000 (3-sigma), 0.678 (EWMA).
- Synthetic variance burst F1: 0.678 (telespec), 1.000 (3-sigma), 1.000 (EWMA).
- Synthetic spikes F1: 0.678 (telespec), 0.833 (3-sigma), 0.833 (EWMA).
- Synthetic periodicity F1: 0.667 (telespec), 0.919 (3-sigma), 0.919 (EWMA).
- NAB macro F1 across 5 selected series: 0.187.
<!-- BENCHMARK_RESULTS_END -->

## Design promises

- Irregular sampling is measured and surfaced.
- Interpolation is explicit and never used for the primary periodogram.
- Every peak has a global bootstrap false-alarm probability.
- Every anomaly is an interval with evidence and a plain-English reason.
- Limitations and benchmark losses are reported alongside wins.

## Documentation

Full documentation is at
[akshajbachu.github.io/telespec](https://akshajbachu.github.io/telespec/),
including the [methodology](docs/methodology.md), [validation protocol](docs/validation.md),
and [release guide](docs/release.md).

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
development setup and checks, and the [Code of Conduct](CODE_OF_CONDUCT.md).
Report security issues privately as described in [SECURITY.md](SECURITY.md).
Release history is in [CHANGELOG.md](CHANGELOG.md).

## Citation

If you use telespec in research, please cite it. GitHub's **Cite this
repository** button (from [`CITATION.cff`](CITATION.cff)) provides APA and
BibTeX entries.

## License

telespec is released under the [MIT License](LICENSE).
