machine-health 0.1.0__tar.gz

machine_health-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Virtual environments and scratch space used while building. Never committed:
+# they are large, machine-specific, and rebuilt from pyproject.toml anyway.
+_venvs/
+_proof/
+.venv*/
+
+# Build output. Wheels are built by the release workflow from this source, so a
+# wheel in git could silently differ from the code beside it.
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+
+# Python noise
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local verification state, not source
+verify_results.json
+publish-log.txt
+published.json
+
+# Credentials. None of these belong here, and this line is the backstop.
+.pypirc
+.env
+*.pem
+*.key

machine_health-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pranay Mahendrakar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

machine_health-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: machine-health
+Version: 0.1.0
+Summary: A single continuously updated 0-100 health score per machine, combining many sensors and rules
+Project-URL: Homepage, https://pypi.org/project/machine-health/
+Project-URL: Author, https://pypi.org/user/pranaymahendrakar/
+Author: Pranay Mahendrakar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anomaly-detection,condition-monitoring,iot,machine-health,pandas,predictive-maintenance,sensors,telemetry,time-series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: pyarrow>=12; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=12; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# machine-health
+
+One continuously updated 0-100 health score per machine, built from every sensor you have
+and the limits you already know, with the reasoning attached so you can act on it.
+
+## Install
+
+```
+pip install machine-health
+```
+
+## Quickstart
+
+```python
+import numpy as np, pandas as pd
+from machine_health import score
+
+rng = np.random.default_rng(0)
+temp = np.r_[rng.normal(60, 1, 800), rng.normal(63, 1.5, 200)]        # the last fifth runs hot
+vib = np.r_[rng.normal(0.2, 0.02, 800), rng.normal(0.24, 0.025, 200)]
+result = score(pd.DataFrame({"temp": temp, "vibration": vib}), rules={"temp": {"max": 70, "warn_max": 65}})
+print(result.summary())
+```
+
+```
+machine health: 78.2 / 100  (grade C, trend degrading)
+window: 800 row(s), baseline: 200 row(s)
+channels (2): temp, vibration
+components (score, weight, points lost):
+  stability      68.3  weight 0.30     -9.50
+  compliance     90.0  weight 0.30     -3.00
+  anomaly        53.8  weight 0.20     -9.25
+  availability  100.0  weight 0.20      0.00
+points lost by channel:
+  temp                  -16.19
+  vibration              -5.57
+violations (1):
+  [warning] temp above warn_max=65 on 10 of 800 rows (1.2%), worst 66.73
+```
+
+`result.value` is the number to put on a dashboard; everything else on the object says where
+it came from. The points lost are split two ways - `result.component_penalties` (stability,
+compliance, anomaly, availability) and `result.contributors` (temp, vibration) - and each
+split adds up to exactly `result.penalty`, which is `100 - result.value`. The printed figures
+above are those two splits rounded to two decimals.
+
+## What it scores
+
+Four components, each reported separately on its own 0-100 scale, each measured against a
+**baseline period** of rows you call healthy (by default the first 20% of the data):
+
+- **stability** - how far each channel has moved from the way it behaved in the baseline, in
+  either of the two ways it can move, whichever costs more. It **swings more**: a channel
+  swinging `4x` more than it used to scores 0, and varying less than baseline is never
+  penalised. Or it has **settled at another level**: a move of up to one baseline spread is
+  free, 1000 spreads scores 0, logarithmic in between. The second half matters because a
+  channel that steps to a steady wrong value swings exactly as much as it always did.
+- **compliance** - whether your own limits hold. Hard limits (`min` / `max`) are critical, soft
+  limits (`warn_min` / `warn_max`) are warnings, and a single breach always costs something,
+  so one bad reading in a million rows does not vanish into the average.
+- **anomaly** - the share of readings that are outliers against the baseline (robust z above
+  3.5, median and MAD based). A channel with 10% or more outlying readings scores 0.
+- **availability** - missing readings, plus a penalty for a channel that used to move and is
+  now flatlined, which is what a dead sensor looks like.
+
+The components are combined with weights (`stability 0.30, compliance 0.30, anomaly 0.20,
+availability 0.20` by default) into `value = 100 - sum(weight * points lost)`, so the score is
+always between 0 and 100.
+
+**Grades are fixed bands**, not a curve: `A >= 90`, `B >= 80`, `C >= 70`, `D >= 60`, `F` below 60.
+`result.ok` is `True` when the grade is C or better *and* no hard limit was broken.
+
+**A component that cannot be measured is not guessed.** With no rules there is no compliance
+score; with a one-row baseline there is no stability score. The weight of a component that
+could not be measured is shared out over the ones that could, `result.unmeasured` names it,
+`result.to_dict()["components"]` reports it as `null` rather than a free 100, and a note in
+`result.notes` says so. That is why an all-NaN table scores 0 on availability alone instead
+of inheriting three free 100s.
+
+**Without rules the score is statistical, not absolute.** It knows only how the machine
+behaves now compared with its own healthy period - nothing about what its readings *mean*.
+That is enough to catch extra noise, outliers, a level shift and dead sensors, but a channel
+whose baseline was never healthy in the first place will look fine. Pass your own limits
+(`rules={"temp": {"max": 80}}`) whenever you have them; they are the only part of the score
+that knows what the numbers are supposed to be.
+
+## API
+
+```python
+score(df, *, time=None, channels=None, rules=None, weights=None, baseline=None) -> MachineScore
+```
+
+- `df` - a DataFrame or a path to a `.csv` / `.tsv` / `.parquet` file; one row per reading,
+  one column per channel.
+- `time` - name of the timestamp column. Rows are sorted by it, violations report when they
+  first happened, and `result.when` carries the newest timestamp.
+- `channels` - which columns to score; defaults to every numeric column. A channel a rule
+  names is always included.
+- `rules` - `{"temp": {"max": 80}}`, a `Rule`, or a list of either. A rule naming a channel
+  that is not in the data raises `ValueError` listing the channels that are.
+- `weights` - `{"compliance": 0.5}`; missing names keep their default. Weights that do not sum
+  to 1 are normalized and a note is recorded.
+- `baseline` - the healthy period: a DataFrame or file path, a fraction (`0.3`), a row count
+  (`500`), or a boolean mask over the rows. Default: the first 20% of the rows.
+
+`HealthScorer(time=..., channels=..., rules=..., weights=..., baseline=...)` is the same thing
+as an object, when you want to keep the settings and call `.score(df)` repeatedly.
+
+### `MachineScore`
+
+- `.value` - 0-100; `.grade` - `"A"` to `"F"`; `.penalty` - `100 - value`
+- `.components` - `{"stability": 68.3, "compliance": 90.0, ...}`, each 0-100
+- `.weights` - the weight each component actually got; `.component_penalties` - points each cost
+- `.contributors` - `{channel: penalty points}`, summing to `.penalty`; `.top_contributors(n)`
+- `.violations` - list of `Violation(channel, limit, value, severity, count, n_rows, fraction,
+  worst, first_time)`, critical first; `.critical_violations`
+- `.trend` - `"improving"`, `"stable"` or `"degrading"`: the two halves of the window compared
+  by how far each sits from the baseline (level shift, extra spread, missing readings and
+  breached rules, in baseline spreads). It compares the halves with each other, not with the
+  score, so a half that straddles a step never outranks the steady bad level that follows it
+- `.unmeasured` - components that could not be scored at all; `.notes` - everything the scorer
+  decided for you; `.channels`, `.n_rows`, `.n_baseline_rows`, `.when`, `.ok`
+- `.summary()` - the text above; `.to_dict()` - JSON-safe, including the grade bands
+
+### `Rule`
+
+```python
+from machine_health import Rule, score
+score(df, rules=[Rule("temp", max=80, warn_max=75), Rule("vibration", max=2.5, weight=2.0)])
+```
+
+`Rule(channel, min=None, max=None, warn_min=None, warn_max=None, weight=1.0)`. `weight` sets
+how much the rule counts against the other rules inside the compliance component.
+
+### `HealthMonitor`
+
+```python
+from machine_health import HealthMonitor
+
+monitor = HealthMonitor(healthy_df, rules={"temp": {"max": 70}}, time="ts")
+for batch in incoming_batches:
+    result = monitor.update(batch)      # same baseline every time, so scores are comparable
+print(monitor.history)                  # one row per update
+print([a.summary() for a in monitor.alerts])
+```
+
+`HealthMonitor(baseline_df, rules=None, weights=None, *, time=None, channels=None)` keeps the
+baseline fixed and scores each batch exactly the way `score()` does.
+
+- `.update(batch)` - a `MachineScore`. An empty batch returns the previous score unchanged
+  with a note instead of raising. From the second update on, `.trend` compares the batch with
+  the mean of the previous three.
+- `.history` - DataFrame: `update, when, value, grade, trend, stability, compliance, anomaly,
+  availability, rows, violations`. A component that was not measured is `NaN` in its column
+  (with no rules, the whole `compliance` column is), never a free 100
+- `.alerts` - `Alert(when, severity, message)`, raised when the grade drops a level (critical
+  for two levels or a drop to F) or a rule is violated
+- `.baseline_score` - the baseline scored against itself, the starting point for comparisons
+- `.last_score`, `.summary()`, `.to_dict()`
+
+## CLI
+
+```
+machine-health telemetry.csv
+machine-health telemetry.csv --time ts --rule "temp:max=80,warn_max=75" --rule "vibration:max=2.5"
+machine-health telemetry.csv --json --output health.json
+machine-health telemetry.csv --baseline 0.3 --weight compliance=0.5 --fail-under 70
+```
+
+`--rule` is repeatable and takes `channel:key=number` pairs (`min`, `max`, `warn_min`,
+`warn_max`, `weight`); `--rules FILE` reads the same thing from JSON. `--baseline` takes a
+fraction, a row count or a path to a table of healthy rows. The exit status is 0 unless
+`--fail-under SCORE` is given and the score is below it (2 on a bad argument or unreadable
+file), so it drops straight into a shell check.
+
+## License
+
+MIT

machine_health-0.1.0/README.md

@@ -0,0 +1,178 @@
+# machine-health
+
+One continuously updated 0-100 health score per machine, built from every sensor you have
+and the limits you already know, with the reasoning attached so you can act on it.
+
+## Install
+
+```
+pip install machine-health
+```
+
+## Quickstart
+
+```python
+import numpy as np, pandas as pd
+from machine_health import score
+
+rng = np.random.default_rng(0)
+temp = np.r_[rng.normal(60, 1, 800), rng.normal(63, 1.5, 200)]        # the last fifth runs hot
+vib = np.r_[rng.normal(0.2, 0.02, 800), rng.normal(0.24, 0.025, 200)]
+result = score(pd.DataFrame({"temp": temp, "vibration": vib}), rules={"temp": {"max": 70, "warn_max": 65}})
+print(result.summary())
+```
+
+```
+machine health: 78.2 / 100  (grade C, trend degrading)
+window: 800 row(s), baseline: 200 row(s)
+channels (2): temp, vibration
+components (score, weight, points lost):
+  stability      68.3  weight 0.30     -9.50
+  compliance     90.0  weight 0.30     -3.00
+  anomaly        53.8  weight 0.20     -9.25
+  availability  100.0  weight 0.20      0.00
+points lost by channel:
+  temp                  -16.19
+  vibration              -5.57
+violations (1):
+  [warning] temp above warn_max=65 on 10 of 800 rows (1.2%), worst 66.73
+```
+
+`result.value` is the number to put on a dashboard; everything else on the object says where
+it came from. The points lost are split two ways - `result.component_penalties` (stability,
+compliance, anomaly, availability) and `result.contributors` (temp, vibration) - and each
+split adds up to exactly `result.penalty`, which is `100 - result.value`. The printed figures
+above are those two splits rounded to two decimals.
+
+## What it scores
+
+Four components, each reported separately on its own 0-100 scale, each measured against a
+**baseline period** of rows you call healthy (by default the first 20% of the data):
+
+- **stability** - how far each channel has moved from the way it behaved in the baseline, in
+  either of the two ways it can move, whichever costs more. It **swings more**: a channel
+  swinging `4x` more than it used to scores 0, and varying less than baseline is never
+  penalised. Or it has **settled at another level**: a move of up to one baseline spread is
+  free, 1000 spreads scores 0, logarithmic in between. The second half matters because a
+  channel that steps to a steady wrong value swings exactly as much as it always did.
+- **compliance** - whether your own limits hold. Hard limits (`min` / `max`) are critical, soft
+  limits (`warn_min` / `warn_max`) are warnings, and a single breach always costs something,
+  so one bad reading in a million rows does not vanish into the average.
+- **anomaly** - the share of readings that are outliers against the baseline (robust z above
+  3.5, median and MAD based). A channel with 10% or more outlying readings scores 0.
+- **availability** - missing readings, plus a penalty for a channel that used to move and is
+  now flatlined, which is what a dead sensor looks like.
+
+The components are combined with weights (`stability 0.30, compliance 0.30, anomaly 0.20,
+availability 0.20` by default) into `value = 100 - sum(weight * points lost)`, so the score is
+always between 0 and 100.
+
+**Grades are fixed bands**, not a curve: `A >= 90`, `B >= 80`, `C >= 70`, `D >= 60`, `F` below 60.
+`result.ok` is `True` when the grade is C or better *and* no hard limit was broken.
+
+**A component that cannot be measured is not guessed.** With no rules there is no compliance
+score; with a one-row baseline there is no stability score. The weight of a component that
+could not be measured is shared out over the ones that could, `result.unmeasured` names it,
+`result.to_dict()["components"]` reports it as `null` rather than a free 100, and a note in
+`result.notes` says so. That is why an all-NaN table scores 0 on availability alone instead
+of inheriting three free 100s.
+
+**Without rules the score is statistical, not absolute.** It knows only how the machine
+behaves now compared with its own healthy period - nothing about what its readings *mean*.
+That is enough to catch extra noise, outliers, a level shift and dead sensors, but a channel
+whose baseline was never healthy in the first place will look fine. Pass your own limits
+(`rules={"temp": {"max": 80}}`) whenever you have them; they are the only part of the score
+that knows what the numbers are supposed to be.
+
+## API
+
+```python
+score(df, *, time=None, channels=None, rules=None, weights=None, baseline=None) -> MachineScore
+```
+
+- `df` - a DataFrame or a path to a `.csv` / `.tsv` / `.parquet` file; one row per reading,
+  one column per channel.
+- `time` - name of the timestamp column. Rows are sorted by it, violations report when they
+  first happened, and `result.when` carries the newest timestamp.
+- `channels` - which columns to score; defaults to every numeric column. A channel a rule
+  names is always included.
+- `rules` - `{"temp": {"max": 80}}`, a `Rule`, or a list of either. A rule naming a channel
+  that is not in the data raises `ValueError` listing the channels that are.
+- `weights` - `{"compliance": 0.5}`; missing names keep their default. Weights that do not sum
+  to 1 are normalized and a note is recorded.
+- `baseline` - the healthy period: a DataFrame or file path, a fraction (`0.3`), a row count
+  (`500`), or a boolean mask over the rows. Default: the first 20% of the rows.
+
+`HealthScorer(time=..., channels=..., rules=..., weights=..., baseline=...)` is the same thing
+as an object, when you want to keep the settings and call `.score(df)` repeatedly.
+
+### `MachineScore`
+
+- `.value` - 0-100; `.grade` - `"A"` to `"F"`; `.penalty` - `100 - value`
+- `.components` - `{"stability": 68.3, "compliance": 90.0, ...}`, each 0-100
+- `.weights` - the weight each component actually got; `.component_penalties` - points each cost
+- `.contributors` - `{channel: penalty points}`, summing to `.penalty`; `.top_contributors(n)`
+- `.violations` - list of `Violation(channel, limit, value, severity, count, n_rows, fraction,
+  worst, first_time)`, critical first; `.critical_violations`
+- `.trend` - `"improving"`, `"stable"` or `"degrading"`: the two halves of the window compared
+  by how far each sits from the baseline (level shift, extra spread, missing readings and
+  breached rules, in baseline spreads). It compares the halves with each other, not with the
+  score, so a half that straddles a step never outranks the steady bad level that follows it
+- `.unmeasured` - components that could not be scored at all; `.notes` - everything the scorer
+  decided for you; `.channels`, `.n_rows`, `.n_baseline_rows`, `.when`, `.ok`
+- `.summary()` - the text above; `.to_dict()` - JSON-safe, including the grade bands
+
+### `Rule`
+
+```python
+from machine_health import Rule, score
+score(df, rules=[Rule("temp", max=80, warn_max=75), Rule("vibration", max=2.5, weight=2.0)])
+```
+
+`Rule(channel, min=None, max=None, warn_min=None, warn_max=None, weight=1.0)`. `weight` sets
+how much the rule counts against the other rules inside the compliance component.
+
+### `HealthMonitor`
+
+```python
+from machine_health import HealthMonitor
+
+monitor = HealthMonitor(healthy_df, rules={"temp": {"max": 70}}, time="ts")
+for batch in incoming_batches:
+    result = monitor.update(batch)      # same baseline every time, so scores are comparable
+print(monitor.history)                  # one row per update
+print([a.summary() for a in monitor.alerts])
+```
+
+`HealthMonitor(baseline_df, rules=None, weights=None, *, time=None, channels=None)` keeps the
+baseline fixed and scores each batch exactly the way `score()` does.
+
+- `.update(batch)` - a `MachineScore`. An empty batch returns the previous score unchanged
+  with a note instead of raising. From the second update on, `.trend` compares the batch with
+  the mean of the previous three.
+- `.history` - DataFrame: `update, when, value, grade, trend, stability, compliance, anomaly,
+  availability, rows, violations`. A component that was not measured is `NaN` in its column
+  (with no rules, the whole `compliance` column is), never a free 100
+- `.alerts` - `Alert(when, severity, message)`, raised when the grade drops a level (critical
+  for two levels or a drop to F) or a rule is violated
+- `.baseline_score` - the baseline scored against itself, the starting point for comparisons
+- `.last_score`, `.summary()`, `.to_dict()`
+
+## CLI
+
+```
+machine-health telemetry.csv
+machine-health telemetry.csv --time ts --rule "temp:max=80,warn_max=75" --rule "vibration:max=2.5"
+machine-health telemetry.csv --json --output health.json
+machine-health telemetry.csv --baseline 0.3 --weight compliance=0.5 --fail-under 70
+```
+
+`--rule` is repeatable and takes `channel:key=number` pairs (`min`, `max`, `warn_min`,
+`warn_max`, `weight`); `--rules FILE` reads the same thing from JSON. `--baseline` takes a
+fraction, a row count or a path to a table of healthy rows. The exit status is 0 unless
+`--fail-under SCORE` is given and the score is below it (2 on a bad argument or unreadable
+file), so it drops straight into a shell check.
+
+## License
+
+MIT

machine_health-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "machine-health"
+version = "0.1.0"
+description = "A single continuously updated 0-100 health score per machine, combining many sensors and rules"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Pranay Mahendrakar" }]
+keywords = [
+  "machine-health",
+  "condition-monitoring",
+  "predictive-maintenance",
+  "sensors",
+  "telemetry",
+  "anomaly-detection",
+  "iot",
+  "time-series",
+  "pandas",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "pandas>=1.5",
+  "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+parquet = ["pyarrow>=12"]
+dev = ["pytest>=7", "pyarrow>=12"]
+
+[project.scripts]
+machine-health = "machine_health.cli:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/machine-health/"
+Author = "https://pypi.org/user/pranaymahendrakar/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/machine_health"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

machine_health-0.1.0/src/machine_health/__init__.py

@@ -0,0 +1,34 @@
+"""machine-health: one continuously updated 0-100 health score per machine.
+
+    >>> from machine_health import score
+    >>> result = score(df, rules={"temp": {"max": 80}})
+    >>> print(result.value, result.grade)
+
+The score combines four components - stability, compliance, anomaly and
+availability - and reports each of them separately, so the number can always be
+explained: the points lost add up per component and per channel.
+"""
+
+from ._io import load_table
+from .monitor import Alert, HealthMonitor
+from .result import COMPONENTS, GRADE_BANDS, MachineScore, grade_for
+from .rules import Rule, Violation
+from .scoring import DEFAULT_WEIGHTS, HealthScorer, score
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Alert",
+    "COMPONENTS",
+    "DEFAULT_WEIGHTS",
+    "GRADE_BANDS",
+    "HealthMonitor",
+    "HealthScorer",
+    "MachineScore",
+    "Rule",
+    "Violation",
+    "__version__",
+    "grade_for",
+    "load_table",
+    "score",
+]

machine_health-0.1.0/src/machine_health/_io.py

@@ -0,0 +1,84 @@
+"""Input loading: a pandas DataFrame, a Series, or a path to a .csv / .tsv / .parquet file."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List, Union
+
+import pandas as pd
+
+TableLike = Union[pd.DataFrame, pd.Series, str, "os.PathLike[str]"]
+
+
+def load_table(source: TableLike, label: str = "df") -> pd.DataFrame:
+    """Return ``source`` as a DataFrame, reading .csv/.tsv/.parquet files from disk.
+
+    DataFrames are returned as-is (never copied or mutated); a Series becomes a
+    one-column frame. ``label`` names the argument in error messages.
+    """
+    if isinstance(source, pd.DataFrame):
+        return source
+    if isinstance(source, pd.Series):
+        return source.to_frame()
+    if isinstance(source, (str, os.PathLike)):
+        path = Path(source)
+        if not path.is_file():
+            raise FileNotFoundError(f"{label}: no such file: {path}")
+        suffixes = [s.lower() for s in path.suffixes]
+        if ".parquet" in suffixes or ".pq" in suffixes:
+            try:
+                return pd.read_parquet(path)
+            except ImportError as exc:
+                raise ImportError(
+                    "reading .parquet files needs pyarrow: "
+                    'pip install "machine-health[parquet]"'
+                ) from exc
+        if ".csv" in suffixes:
+            return _read_separated(path, label, ",", "CSV")
+        if ".tsv" in suffixes:
+            return _read_separated(path, label, "\t", "TSV")
+        raise ValueError(
+            f"{label}: unsupported file type {path.suffix!r}; expected .csv, .tsv or .parquet"
+        )
+    raise TypeError(
+        f"{label} must be a pandas DataFrame, a Series, or a path to a .csv/.parquet file, "
+        f"not {type(source).__name__}"
+    )
+
+
+def _read_separated(path: Path, label: str, sep: str, kind: str) -> pd.DataFrame:
+    """Read a delimited text file, turning pandas' own wording into a message that
+    names the argument and the file, the way every other error here does."""
+    try:
+        return pd.read_csv(path, sep=sep)
+    except pd.errors.EmptyDataError:
+        raise ValueError(
+            f"{label}: {path.name} has no columns to read; the file is empty"
+        ) from None
+    except pd.errors.ParserError as exc:
+        raise ValueError(f"{label}: {path.name} is not readable as {kind}: {exc}") from None
+    except UnicodeDecodeError:
+        raise ValueError(
+            f"{label}: {path.name} is not UTF-8 text; save it as UTF-8 or pass a DataFrame"
+        ) from None
+
+
+def check_columns(df: pd.DataFrame, label: str = "df") -> List[str]:
+    """Reject duplicate column names up front and return the names as text.
+
+    Without this a duplicated name makes ``df[name]`` return a DataFrame and the
+    failure surfaces much later as an AttributeError from inside pandas.
+    """
+    names = [str(c) for c in df.columns]
+    seen, dupes = set(), []
+    for name in names:
+        if name in seen and name not in dupes:
+            dupes.append(name)
+        seen.add(name)
+    if dupes:
+        raise ValueError(
+            f"{label} has duplicate column names: {', '.join(repr(d) for d in dupes)}; "
+            "rename them so each channel is addressable"
+        )
+    return names