oee 0.1.0__py3-none-any.whl

oee/__init__.py

@@ -0,0 +1,32 @@
+"""oee - Overall Equipment Effectiveness for Python.
+
+Compute OEE (Availability x Performance x Quality) from machine times and piece
+counts, get the full time waterfall and the three loss categories, TEEP and
+utilization, and roll figures up correctly across machines and shifts. Every
+result carries provenance and a JSON-safe payload.
+
+    import oee
+
+    r = oee.oee(
+        planned_production_time=420,   # minutes
+        downtime=47,
+        ideal_cycle_time=1 / 60,       # minutes per piece
+        total_count=19271,
+        reject_count=423,
+    )
+    r.oee            # 0.7479
+    r.summary()      # the factor and loss breakdown
+
+Computed from the standard definitions and validated against published worked
+examples.
+"""
+
+from ._result import Alert, OEEResult
+from ._version import __version__
+from .aggregate import aggregate
+from .core import oee, oee_from_factors
+
+__all__ = [
+    "oee", "oee_from_factors", "aggregate",
+    "OEEResult", "Alert", "__version__",
+]

oee/_result.py

@@ -0,0 +1,146 @@
+"""The result contract: one ``OEEResult`` per computation, carrying the three
+factors, the time waterfall, the loss categories, provenance and a JSON-safe
+payload, so a calculation can be reproduced and audited later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+SCHEMA = 1
+WORLD_CLASS_OEE = 0.85
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def data_hash(obj: object) -> str:
+    payload = json.dumps(obj, sort_keys=True, default=str).encode("utf-8")
+    return "sha256:" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Alert:
+    """A data-quality or benchmark note attached to a result."""
+
+    indicator: str
+    message: str
+    severity: str = "warning"  # info | warning | error
+
+    def __str__(self) -> str:
+        return f"[{self.severity.upper()}] {self.indicator}: {self.message}"
+
+
+def _pct(value: float | None) -> float | None:
+    return None if value is None else round(100.0 * value, 1)
+
+
+@dataclass(frozen=True)
+class OEEResult:
+    """Overall Equipment Effectiveness and the time/loss breakdown behind it."""
+
+    name: str | None
+    availability: float
+    performance: float
+    quality: float
+    oee: float
+    performance_raw: float
+    utilization: float | None
+    teep: float | None
+    planned_production_time: float | None
+    run_time: float | None
+    net_run_time: float | None
+    fully_productive_time: float | None
+    all_time: float | None
+    schedule_loss: float | None
+    availability_loss: float | None
+    performance_loss: float | None
+    quality_loss: float | None
+    total_count: float | None
+    good_count: float | None
+    reject_count: float | None
+    target_oee: float
+    alerts: tuple[Alert, ...]
+    meta: dict
+
+    @property
+    def world_class(self) -> bool:
+        """True when OEE meets the widely cited world-class level of 85%."""
+        return self.oee >= WORLD_CLASS_OEE
+
+    @property
+    def meets_target(self) -> bool:
+        return self.oee >= self.target_oee
+
+    @property
+    def ok(self) -> bool:
+        """True when no error-severity (data-quality) alert was raised."""
+        return not any(a.severity == "error" for a in self.alerts)
+
+    def _verdict(self) -> str:
+        if self.world_class:
+            return "world-class"
+        if self.meets_target:
+            return "meets target"
+        return "below target"
+
+    def summary(self) -> str:
+        head = "oee" + (f" {self.name}" if self.name else "")
+        lines = [
+            f"{head} - {self.meta.get('computed_at', '')}",
+            f"  Availability   {_pct(self.availability):>5}%",
+            f"  Performance    {_pct(self.performance):>5}%",
+            f"  Quality        {_pct(self.quality):>5}%",
+            f"  OEE            {_pct(self.oee):>5}%",
+        ]
+        if self.teep is not None:
+            lines.append(f"  TEEP           {_pct(self.teep):>5}%")
+        for alert in self.alerts:
+            lines.append("  " + str(alert))
+        lines.append(f"Verdict: OEE {_pct(self.oee)}% - {self._verdict()}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "schema": SCHEMA,
+            "name": self.name,
+            "factors": {
+                "availability": self.availability,
+                "performance": self.performance,
+                "quality": self.quality,
+                "oee": self.oee,
+                "performance_raw": self.performance_raw,
+                "utilization": self.utilization,
+                "teep": self.teep,
+            },
+            "times": {
+                "all_time": self.all_time,
+                "planned_production_time": self.planned_production_time,
+                "run_time": self.run_time,
+                "net_run_time": self.net_run_time,
+                "fully_productive_time": self.fully_productive_time,
+            },
+            "losses": {
+                "schedule_loss": self.schedule_loss,
+                "availability_loss": self.availability_loss,
+                "performance_loss": self.performance_loss,
+                "quality_loss": self.quality_loss,
+            },
+            "counts": {
+                "total_count": self.total_count,
+                "good_count": self.good_count,
+                "reject_count": self.reject_count,
+            },
+            "world_class": self.world_class,
+            "meets_target": self.meets_target,
+            "target_oee": self.target_oee,
+            "alerts": [
+                {"indicator": a.indicator, "message": a.message, "severity": a.severity}
+                for a in self.alerts
+            ],
+            "meta": self.meta,
+        }

oee/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

oee/aggregate.py

@@ -0,0 +1,75 @@
+"""Roll OEE up across machines, lines, shifts or periods.
+
+OEE figures must not be averaged: a fast machine and a slow one do not combine
+to the mean of their OEEs. The correct roll-up sums the underlying time and
+count buckets and recomputes the factors from the totals, which this does.
+"""
+
+from __future__ import annotations
+
+from ._result import Alert, OEEResult, data_hash, utcnow
+from ._version import __version__
+
+_REQUIRED = ("planned_production_time", "run_time", "net_run_time",
+             "fully_productive_time", "total_count", "good_count")
+
+
+def aggregate(parts, *, target_oee: float = 0.85,
+              name: str | None = None) -> OEEResult:
+    """Combine several OEEResults into one by summing their time/count buckets."""
+    parts = list(parts)
+    if not parts:
+        raise ValueError("aggregate needs at least one result")
+    for i, part in enumerate(parts):
+        if not isinstance(part, OEEResult):
+            raise TypeError("aggregate expects OEEResult instances")
+        for field in _REQUIRED:
+            if getattr(part, field) is None:
+                raise ValueError(
+                    f"part {i} has no {field}; aggregate needs results created "
+                    "from times and counts (oee(), not oee_from_factors())")
+
+    s_planned = sum(p.planned_production_time for p in parts)
+    s_run = sum(p.run_time for p in parts)
+    s_net = sum(p.net_run_time for p in parts)
+    s_fp = sum(p.fully_productive_time for p in parts)
+    s_total = sum(p.total_count for p in parts)
+    s_good = sum(p.good_count for p in parts)
+
+    availability = s_run / s_planned if s_planned else 0.0
+    performance = s_net / s_run if s_run else 0.0
+    quality = s_fp / s_net if s_net else 0.0
+    oee_value = s_fp / s_planned if s_planned else 0.0
+
+    if all(p.all_time is not None for p in parts):
+        s_all = sum(p.all_time for p in parts)
+        utilization = s_planned / s_all if s_all else 0.0
+        teep = s_fp / s_all if s_all else 0.0
+        schedule_loss = s_all - s_planned
+    else:
+        s_all = utilization = teep = schedule_loss = None
+
+    alerts: list[Alert] = []
+    if oee_value < target_oee:
+        alerts.append(Alert(
+            "oee", f"OEE {oee_value * 100:.1f}% is below the target "
+            f"{target_oee * 100:.0f}%", "info"))
+
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "method": "aggregate",
+        "parts": len(parts),
+        "input_hash": data_hash([p.meta.get("input_hash") for p in parts]),
+    }
+    return OEEResult(
+        name=name, availability=availability, performance=performance,
+        quality=quality, oee=oee_value, performance_raw=performance,
+        utilization=utilization, teep=teep,
+        planned_production_time=s_planned, run_time=s_run, net_run_time=s_net,
+        fully_productive_time=s_fp, all_time=s_all, schedule_loss=schedule_loss,
+        availability_loss=s_planned - s_run, performance_loss=s_run - s_net,
+        quality_loss=s_net - s_fp, total_count=s_total, good_count=s_good,
+        reject_count=s_total - s_good, target_oee=target_oee,
+        alerts=tuple(alerts), meta=meta,
+    )

oee/core.py

@@ -0,0 +1,165 @@
+"""Overall Equipment Effectiveness from the standard definitions.
+
+OEE = Availability x Performance x Quality, with
+
+    Availability = run time / planned production time
+    Performance  = (ideal cycle time x total count) / run time
+    Quality      = good count / total count
+
+All times must be in the same unit, and ``ideal_cycle_time`` in that unit per
+piece (or pass ``ideal_rate`` in pieces per that unit). The full time waterfall
+(planned -> run -> net run -> fully productive) and each loss are returned, plus
+TEEP and utilization when ``all_time`` is given.
+"""
+
+from __future__ import annotations
+
+import math
+
+from ._result import Alert, OEEResult, data_hash, utcnow
+from ._version import __version__
+
+
+def _finite(value: float, label: str) -> float:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise TypeError(f"{label} must be a number")
+    value = float(value)
+    if not math.isfinite(value):
+        raise ValueError(f"{label} must be finite")
+    return value
+
+
+def _exactly_one(a, b, name_a: str, name_b: str):
+    if (a is None) == (b is None):
+        raise ValueError(f"provide exactly one of {name_a} or {name_b}")
+    return a, b
+
+
+def oee(planned_production_time, *, run_time=None, downtime=None,
+        ideal_cycle_time=None, ideal_rate=None, total_count,
+        good_count=None, reject_count=None, all_time=None,
+        target_oee: float = 0.85, name: str | None = None) -> OEEResult:
+    """Compute OEE and the time/loss waterfall from times and piece counts."""
+    planned = _finite(planned_production_time, "planned_production_time")
+    if planned <= 0:
+        raise ValueError("planned_production_time must be positive")
+
+    _exactly_one(run_time, downtime, "run_time", "downtime")
+    run = _finite(run_time, "run_time") if run_time is not None \
+        else planned - _finite(downtime, "downtime")
+    if not 0 <= run <= planned:
+        raise ValueError("run_time must be between 0 and planned_production_time")
+
+    _exactly_one(ideal_cycle_time, ideal_rate, "ideal_cycle_time", "ideal_rate")
+    if ideal_cycle_time is not None:
+        cycle = _finite(ideal_cycle_time, "ideal_cycle_time")
+    else:
+        rate = _finite(ideal_rate, "ideal_rate")
+        if rate <= 0:
+            raise ValueError("ideal_rate must be positive")
+        cycle = 1.0 / rate
+    if cycle <= 0:
+        raise ValueError("ideal_cycle_time must be positive")
+
+    total = _finite(total_count, "total_count")
+    if total <= 0:
+        raise ValueError("total_count must be positive")
+    _exactly_one(good_count, reject_count, "good_count", "reject_count")
+    good = _finite(good_count, "good_count") if good_count is not None \
+        else total - _finite(reject_count, "reject_count")
+    if not 0 <= good <= total:
+        raise ValueError("good_count must be between 0 and total_count")
+    reject = total - good
+
+    alerts: list[Alert] = []
+
+    availability = run / planned if planned else 0.0
+
+    ideal_time_total = cycle * total
+    performance_raw = ideal_time_total / run if run > 0 else 0.0
+    if performance_raw > 1.0 + 1e-9:
+        performance = 1.0
+        net_run = run
+        alerts.append(Alert(
+            "performance", "performance exceeds 100%; capped at 100% (check "
+            "ideal_cycle_time / ideal_rate and counts)", "warning"))
+    else:
+        performance = performance_raw
+        net_run = ideal_time_total
+
+    quality = good / total
+    fully_productive = quality * net_run
+    oee_value = availability * performance * quality
+
+    schedule_loss = None
+    utilization = None
+    teep = None
+    if all_time is not None:
+        at = _finite(all_time, "all_time")
+        if at < planned:
+            raise ValueError("all_time must be at least planned_production_time")
+        schedule_loss = at - planned
+        utilization = planned / at if at > 0 else 0.0
+        teep = fully_productive / at if at > 0 else 0.0
+
+    if not 0 < target_oee <= 1:
+        raise ValueError("target_oee must be in (0, 1]")
+    if oee_value < target_oee:
+        alerts.append(Alert(
+            "oee", f"OEE {oee_value * 100:.1f}% is below the target "
+            f"{target_oee * 100:.0f}%", "info"))
+
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "method": "time_and_counts",
+        "input_hash": data_hash({
+            "planned": planned, "run": run, "cycle": cycle,
+            "total": total, "good": good, "all_time": all_time,
+        }),
+    }
+    return OEEResult(
+        name=name, availability=availability, performance=performance,
+        quality=quality, oee=oee_value, performance_raw=performance_raw,
+        utilization=utilization, teep=teep,
+        planned_production_time=planned, run_time=run, net_run_time=net_run,
+        fully_productive_time=fully_productive, all_time=all_time,
+        schedule_loss=schedule_loss, availability_loss=planned - run,
+        performance_loss=run - net_run, quality_loss=net_run - fully_productive,
+        total_count=total, good_count=good, reject_count=reject,
+        target_oee=target_oee, alerts=tuple(alerts), meta=meta,
+    )
+
+
+def oee_from_factors(availability, performance, quality, *,
+                     target_oee: float = 0.85, name: str | None = None) -> OEEResult:
+    """Compute OEE from the three factors directly (no times or counts)."""
+    a = _finite(availability, "availability")
+    p = _finite(performance, "performance")
+    q = _finite(quality, "quality")
+    alerts: list[Alert] = []
+    for label, value in (("availability", a), ("performance", p), ("quality", q)):
+        if not 0 <= value <= 1.0 + 1e-9:
+            raise ValueError(f"{label} must be between 0 and 1")
+    if not 0 < target_oee <= 1:
+        raise ValueError("target_oee must be in (0, 1]")
+    oee_value = a * p * q
+    if oee_value < target_oee:
+        alerts.append(Alert(
+            "oee", f"OEE {oee_value * 100:.1f}% is below the target "
+            f"{target_oee * 100:.0f}%", "info"))
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "method": "factors",
+        "input_hash": data_hash({"a": a, "p": p, "q": q}),
+    }
+    return OEEResult(
+        name=name, availability=a, performance=p, quality=q, oee=oee_value,
+        performance_raw=p, utilization=None, teep=None,
+        planned_production_time=None, run_time=None, net_run_time=None,
+        fully_productive_time=None, all_time=None, schedule_loss=None,
+        availability_loss=None, performance_loss=None, quality_loss=None,
+        total_count=None, good_count=None, reject_count=None,
+        target_oee=target_oee, alerts=tuple(alerts), meta=meta,
+    )

oee-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: oee
+Version: 0.1.0
+Summary: Overall Equipment Effectiveness for Python: availability, performance and quality with the full time waterfall, TEEP, and correct multi-machine roll-up. Computed from the standard definitions and validated against published examples.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/oee
+Project-URL: Repository, https://github.com/arikanatakan/oee
+Project-URL: Issues, https://github.com/arikanatakan/oee/issues
+Keywords: oee,overall-equipment-effectiveness,manufacturing,tpm,teep,availability,performance,quality,six-big-losses,production,lean
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# oee
+
+[![CI](https://github.com/arikanatakan/oee/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/oee/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oee)](https://pypi.org/project/oee/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Overall Equipment Effectiveness for Python.
+
+Compute OEE (Availability x Performance x Quality) from machine times and piece
+counts, get the full time waterfall and the three loss categories, TEEP and
+utilization, and roll figures up correctly across machines and shifts. Computed
+from the standard definitions and validated against published worked examples.
+
+## Motivation
+
+OEE is the standard manufacturing efficiency metric, but Python has no library
+for it: what exists is monitoring *applications* (Flask/Django dashboards) or
+one-off tutorial scripts. The arithmetic looks trivial (three numbers
+multiplied) and that is exactly why it is usually done wrong:
+
+* the time waterfall (planned -> run -> net run -> fully productive) and where
+  each loss sits is skipped;
+* TEEP and utilization (which capture schedule loss) are left out;
+* and figures are *averaged* across machines, which is incorrect: a fast machine
+  and a slow one do not combine to the mean of their OEEs.
+
+`oee` does these properly, from the standard definitions, and returns one result
+with the factors, the waterfall, every loss, and provenance.
+
+```
+pip install oee
+```
+
+No runtime dependencies.
+
+## Usage
+
+The canonical worked example (Vorne's *Fast Guide to OEE*):
+
+```python
+import oee
+
+r = oee.oee(
+    planned_production_time=420,   # minutes (480 shift - 60 of breaks)
+    downtime=47,
+    ideal_rate=60,                 # pieces per minute
+    total_count=19271,
+    reject_count=423,
+    all_time=480,                  # optional, for TEEP and utilization
+)
+r.availability   # 0.888
+r.performance    # 0.861
+r.quality        # 0.978
+r.oee            # 0.748
+r.teep           # 0.654
+print(r.summary())
+```
+
+Roll up across machines (correctly, not by averaging):
+
+```python
+m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+             total_count=80, good_count=80)     # OEE 0.80
+m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+             total_count=150, good_count=135)   # OEE 0.45
+
+line = oee.aggregate([m1, m2])
+line.oee         # 0.5375, not the 0.625 average of the two
+```
+
+When you already have the three factors:
+
+```python
+oee.oee_from_factors(0.90, 0.95, 0.999).world_class   # True (OEE >= 85%)
+```
+
+Every result carries the factors, the time waterfall, the losses, `world_class`
+and `meets_target` flags, `summary()`, and a JSON-safe `to_dict()` with
+provenance (version, input hash, timestamp).
+
+## What it computes
+
+| Group | Output |
+|-------|--------|
+| Factors | availability, performance, quality, OEE |
+| Extended | TEEP, utilization (when total calendar time is given) |
+| Waterfall | planned -> run -> net run -> fully productive time, with schedule, availability, performance and quality losses |
+| Roll-up | correct aggregation across machines, lines and shifts |
+
+All times must be in the same unit; `ideal_cycle_time` is that unit per piece
+(or pass `ideal_rate` in pieces per that unit). Performance above 100% is capped
+and flagged, since it means the ideal rate or counts are off.
+
+## Status
+
+Version 0.1.0. Single-machine OEE, the time waterfall, TEEP/utilization, and
+correct roll-up. The `OEEResult` contract is append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | the six big losses (breakdown/setup, minor stops/speed, defects/startup) and a downtime-reason Pareto; computing OEE from an event log |
+| 0.3 | plotting (the OEE waterfall, six-big-losses and trend charts) as an optional extra |
+| 0.4 | an MCP server so an agent can compute and explain OEE |
+
+Out of scope: data collection / machine connectivity (that is the job of an
+MES or an IoT dashboard); `oee` is the calculation layer they can build on.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

oee-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+oee/__init__.py,sha256=wlKJcqRJR3eGdrWj5f3noaymay5QG6UoAsiRJlPyjaQ,982
+oee/_result.py,sha256=qkfsayUZsTHYPeFLmV0vWC-g1QS9YBffnv2fEbgzm1I,4756
+oee/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+oee/aggregate.py,sha256=k0pJvuDV0LDTBccyOfXaEqEUFu63ZhdudidQfJj-QzM,3152
+oee/core.py,sha256=kmcNmIK6XfOXPNkaDXZ_eURid1z4WOn-gHG8iFmONdw,6661
+oee/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oee-0.1.0.dist-info/licenses/LICENSE,sha256=a3yEF0vGHVodoVsu7IKY7Otc_8-fuwfYXMMm9h3VoJg,1070
+oee-0.1.0.dist-info/METADATA,sha256=wyBC1QENjIX-jCpj6EpNNHV-puBiIDD5FfnKtCbg6Lk,5503
+oee-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+oee-0.1.0.dist-info/top_level.txt,sha256=_pkBHsyLovAxUFoUICE8FzpdhvXv9bSNTtBBgaCPj1g,4
+oee-0.1.0.dist-info/RECORD,,

oee-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oee-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Arikan
+
+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.

oee-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+oee